cloudflare-dsh

Explain like I'm 5

Imagine you have a very capable assistant who can write and run code for you.
That assistant is DeepSeek Harness (DSH).

Now imagine you also rent a huge amount of internet plumbing from Cloudflare:
somewhere to keep files, somewhere to keep a database, a robot that can open web
pages for you, and a bank of GPUs that can run AI models.

Your assistant cannot touch any of that on its own. It does not know your
account exists.

This project is the set of hands. Install it, and three things happen:

1. The assistant gets tools. It can now say "put this in the database",
   "read that web page", "run this AI model" — 36 specific, typed actions
   instead of a vague "call an API somewhere".
2. The assistant can think using Cloudflare's own AI. Not just call
   Cloudflare models as a tool — actually be powered by them, routed through
   your AI Gateway.
3. You get the receipts. Every one of those thinking-requests is stamped
   with which conversation it came from. So when you ask "what did that
   conversation cost me?", there is a real answer from Cloudflare's billing
   data, not an estimate.

That third one is the interesting part, and it is the reason this project
exists rather than just being a list of API wrappers.

Contents

• What you get
• Install
• Architecture
• How a tool call flows
• How a model call flows
• Per-session cost attribution
• Tool catalogue
• The model provider
• Configuration
• Web Client surfaces
• Accessibility
• MCP passthrough
• Security model
• Quality
• Development
• Project status
• License

What you get

Packages

The three packages exist because they have genuinely different consumers.
Another bundle may want ctx.cloudflare without any of these tools; the client
package has its own build requirements (React, a client tsconfig, dsh.client)
that the headless packages must not inherit.

Install

dsh plugin --profile <name> add cloudflare-dsh @d4551/dsh-cloudflare-core

Then supply the API token through the environment. The configuration names the
variable; it never holds the value:

export CLOUDFLARE_API_TOKEN=...

For the Web Client surfaces, also install the client package into the profile:

dsh plugin --profile <name> add @d4551/dsh-cloudflare-client

API token scopes

Minimum permission groups for the shipped tools:

Workers AI Read/Write · AI Gateway Read/Write · Vectorize Write ·
Workers KV Storage Write · D1 Write · Workers R2 Storage Write ·
Queues Write · Account Settings Read

[!NOTE]
The Cloudflare dashboard labels these groups Edit where the API calls them
Write. Use Write when minting a token through the API.

The account id is optional when the token can reach exactly one account: it is
discovered once and reused. A token that can reach several makes discovery
ambiguous, so the plugin refuses to guess and asks for accountId, naming the
accounts it saw.

Architecture

The bundle is organised around a single capability seam. Everything that talks
to Cloudflare goes through ctx.cloudflare; everything else is a consumer of
it. That is what keeps credentials in one place, error handling in one place,
and the tool modules free of transport concerns.

graph TD
    subgraph harness["DeepSeek Harness"]
        agent["Agent loop"]
        tools["ctx.tools"]
        llm["ctx.llm"]
        slots["ctx.slots"]
        creds["ctx.credentials"]
    end

    subgraph seam["@d4551/dsh-cloudflare-core"]
        service["CloudflareService<br/>(ctx.cloudflare)"]
        client["HTTP client<br/>request · retry · paginate · errors"]
        service --> client
    end

    subgraph bundle["cloudflare-dsh"]
        tai["tools/ai — 18 tools"]
        tdata["tools/data — 13 tools"]
        tweb["tools/web — 3 tools"]
        tmeta["tools/meta — 2 tools"]
        adapter["ai — CloudflareAiAdapter"]
    end

    subgraph clientpkg["@d4551/dsh-cloudflare-client"]
        ui["SettingsCard · SessionCostChip · 3 tool views"]
    end

    cf["Cloudflare REST API<br/>api.cloudflare.com/client/v4"]
    gw["AI Gateway<br/>OpenAI-compatible endpoint"]

    creds -.->|"resolve per operation"| service
    tai & tdata & tweb & tmeta -->|"inject: cloudflare"| service
    tai & tdata & tweb & tmeta -->|register| tools
    adapter -->|"inject: cloudflare"| service
    adapter -->|registerAdapter| llm
    ui -->|register| slots
    agent --> tools
    agent --> llm
    client --> cf
    adapter --> gw

The capability seam

DSH's own convention is that a capability is complete only when all three roles
exist: a service definition, a provider, and a consumer. Here:

Why the pure/impure split

In packages/core, exactly one module dispatches a request: client.ts. The
service supplies the default fetch and nothing else there touches the network.
Everything else — path building, scope resolution, query serialization, error
mapping, pagination stepping, retry policy — is a pure function. The same is
true of the adapter: transducer.ts holds the entire streaming contract as a
state machine with no clock, no network and no randomness, and adapter.ts is
a thin shell around it.

This is not stylistic. It is what makes a 100% mutation score reachable
honestly: every branch that matters can be driven from a literal array of
fixture inputs, so a surviving mutant means a real gap rather than an
untestable seam.

What one request can carry

Cloudflare's REST surface is not uniformly JSON, so a RequestSpec says how it
is read and how it is written, and the client does exactly that.

accept names what the caller can read, so an endpoint that answers with an
image is asked for an image. Every one of these paths goes through the same
retry policy and the same failure classification: an error body is read as an
envelope when the endpoint sends one, whatever the successful shape would be.

How a tool call flows

sequenceDiagram
    participant A as Agent loop
    participant R as ctx.tools registry
    participant T as Tool (e.g. cloudflare_d1_query)
    participant S as ctx.cloudflare
    participant C as HTTP client
    participant CF as Cloudflare REST

    A->>R: call cloudflare_d1_query({...})
    R->>R: validate args against ParameterSchemaSpec
    R->>T: execute(args)
    T->>S: accountRequest(spec)
    S->>S: resolve account id — discovery, cached, not a credential
    S->>C: request(spec)
    C->>C: resolve API token from ctx.credentials
    Note over C: Re-resolved every request.<br/>Never cached, so rotation<br/>needs no restart.
    C->>CF: HTTPS with Bearer token
    CF-->>C: Cloudflare envelope
    C->>C: retry on 429/5xx and transport failures, capped backoff + jitter
    C->>C: normalize envelope to typed error or result
    C-->>T: result
    T-->>R: one canonical JSON value
    R->>R: snapshot, validate against output.schema, freeze
    R-->>A: frozen value
    R->>R: output.render(args, value) for the transcript

Two properties are worth calling out.

The canonical value is a programmatic API. DSH runs tools in PTC mode,
meaning generated code can call await tools.cloudflare_kv_list_keys({...}) and
receive the value directly. So results carry ids and cursors that feed the next
call rather than prose a model has to parse. cloudflare_kv_list_keys returns
{ keys, cursor, complete } precisely so a generated loop can page, and every
list tool pages the way its endpoint does: page-numbered endpoints take page
and perPage and return page, perPage, total (when Cloudflare reports
one, else null) and complete; cursor endpoints (cloudflare_kv_list_keys,
cloudflare_r2_bucket_list) return cursor and complete; and
cloudflare_queue_list, whose endpoint takes no paging parameters, returns the
whole listing and says if the API reported more than it returned. Every tool
declares a closed output object with each field described and required; the
registry validates a value against it before the model or generated code sees
it, and a presenter reads typed fields rather than casting.

Presenters are pure. output.render runs during session-log replay, so it
performs no I/O, reads no clock and uses no randomness.

Cancellation reaches Cloudflare. timeoutMs on a tool is declarative — the
registry does not interrupt a body — so every tool forwards exec.signal into
its request, and a tool with a budget of its own (inferenceTimeoutMs,
renderTimeoutMs) makes that budget the request deadline as well, so a 120 s
inference is not cut off by the 30 s client default.

How a model call flows

The adapter's job is to turn one HTTP response into the harness's StreamChunk
sequence, honouring the ordering guarantees the harness depends on.

sequenceDiagram
    participant L as ctx.llm
    participant AD as CloudflareAiAdapter
    participant EP as Endpoint resolver
    participant GW as AI Gateway / Workers AI
    participant TR as StreamTransducer

    L->>AD: prepareCall(provider, model)
    AD->>EP: resolveEndpoint + resolveModel, once per generation
    EP->>GW: GET ai-gateway gateways URL endpoint (first call only)
    Note over EP: Base URL comes from the API and is remembered<br/>per plugin instance. The token never is.
    EP-->>AD: { url, token } + model facts (context window, modalities)
    L->>AD: prepared.stream(GenerateOptions)
    AD->>AD: buildWireRequest — images projected to text, reasoning left out, unsupported options rejected
    AD->>AD: attributionHeaders() first, then buildGatewayHeaders — cf-aig-metadata carries sessionId + purpose
    AD->>GW: POST chat/completions (stream, caller AbortSignal forwarded)
    loop while the stream is alive
        GW-->>AD: SSE frames
        AD->>TR: push(parsed frame)
        TR-->>AD: StreamChunk[]
        AD-->>L: yield chunks
    end
    GW-->>AD: data: [DONE]
    AD->>AD: no content block opened? → EMPTY_RESPONSE
    AD->>TR: end()
    TR-->>AD: block-end… usage… finish
    AD-->>L: final chunks
    Note over AD: Reader is cancelled in `finally`,<br/>so an abandoned turn frees the connection.

Streaming contract

The transducer is where the contract lives, and it is enforced by construction
rather than convention:

stateDiagram-v2
    [*] --> Open
    Open --> Open: text-delta / reasoning-delta / tool-call-delta
    Open --> Open: usage
    Open --> Closing: finish_reason seen
    Open --> Closing: transport ended, end called
    Closing --> Finished: block-end for every open block, in index order
    Finished --> [*]: finish
    Finished --> Finished: later input ignored

Per-session cost attribution

This is the feature the architecture is shaped around.

graph LR
    A["Agent turn<br/>sessionId: abc123"] --> B["stream(GenerateOptions)"]
    B --> C["cf-aig-metadata:<br/>{sessionId, purpose}"]
    C --> D["AI Gateway"]
    D --> E["Gateway logs<br/>tagged with metadata"]
    D --> F["Billing:<br/>usage · cost"]
    E --> G["cloudflare_aigateway_session_cost"]
    F --> G
    G --> H["SessionCostChip<br/>in the session header"]

GenerateOptions.purpose is the bonus: DSH marks auxiliary calls as
compaction or session-title, so housekeeping is attributable separately from
real agent turns.

[!IMPORTANT]
The declarative path (presets/pi-ai.yaml, using the llm-pi-ai adapter DSH
already ships) works on day one and costs nothing to adopt — but it cannot set
cf-aig-* headers, so it gets no session correlation. That is the concrete
reason this bundle ships a real adapter rather than only a preset.

Tool catalogue

Tools are grouped into four modules, mounted as separate patch rows, so a
profile takes only the groups it wants.

AI — cloudflare-dsh/tools/ai (18)

Data — cloudflare-dsh/tools/data (13)

Web — cloudflare-dsh/tools/web (3)

cloudflare_browser_accessibility_tree is the standout: it hands an agent the
same tree an assistive technology would consume, which is exactly what a WCAG
review needs and what a screenshot cannot provide.

cloudflare_browser_screenshot needs an attachment store in the composition
(@deepseek-ai/dsh-attachment-local in the shipped dsh), because that store
is the harness's one durable home for image bytes. A model that accepts images
sees the page, the client shows it, and a text-only model is told the image was
omitted. PDF capture is not offered: a PDF is not a raster image, so the store
cannot hold it, and a base64 PDF in the session log would be a blob nothing
can consume.

Meta — cloudflare-dsh/tools/meta (2)

The model provider

Mounted as the cloudflare-llm row (cloudflare-dsh/ai), registering two
routes:

Registration is inert until a session selects one of the routes, so mounting the
row costs nothing.

Error mapping

Provider failures are mapped onto the harness's canonical vocabulary rather than
surfaced raw:

Two adapter hooks keep the harness defaults, deliberately: providerRetryPolicy,
because Cloudflare publishes no route-owned retry policy beyond the
retry-after a rate-limit failure already carries, and imageRequestPricing,
because Cloudflare prices vision input per token, not per image.

Configuration

Every deployment-varying value is a validated Schemastery field, changeable from
cordis.yml without a code edit. There are no tunables hidden as constants.

[!WARNING]
A patch layer replaces a row's entire config value rather than merging
into it. That is why each row's configuration is small and local: overriding
one key never forces you to restate the rest.

cloudflare — the seam (@d4551/dsh-cloudflare-core)

cloudflare-llm — the model provider (cloudflare-dsh/ai)

cloudflare-tools-ai (cloudflare-dsh/tools/ai)

cloudflare-tools-data (cloudflare-dsh/tools/data)

cloudflare-tools-web (cloudflare-dsh/tools/web)

cloudflare-tools-meta — the escape hatch (cloudflare-dsh/tools/meta)

The shipped patch layer

- insert:
    - id: cloudflare
      name: '@d4551/dsh-cloudflare-core'
      config:
        apiTokenRef: CLOUDFLARE_API_TOKEN
    - id: cloudflare-tools-ai
      name: 'cloudflare-dsh/tools/ai'
    - id: cloudflare-tools-data
      name: 'cloudflare-dsh/tools/data'
    - id: cloudflare-tools-web
      name: 'cloudflare-dsh/tools/web'
    - id: cloudflare-llm
      name: 'cloudflare-dsh/ai'
    - id: cloudflare-tools-meta
      name: 'cloudflare-dsh/tools/meta'
      config:
        allowMutations: false
        denyPathPrefixes: []

Web Client surfaces

@d4551/dsh-cloudflare-client contributes to three slots, each after the slot
is declared. Components never receive ctx; they take props. A list slot places
its entry by id; the keyed tool-view slot dispatches on the wire tool name.

Each tool view is a figure, named from the caption already on screen, and
deliberately not a landmark: a tool view is rendered once per tool call, so a
conversation that runs one query twice would otherwise put two identically
named landmarks on the page.

A tool view is registered as an adapter, not as the component itself. The
slot hands over the call's owner currency — callId, toolName, and the
running-or-settled block — not the tool's result, so a component whose props are
a query and its rows receives none of what it declares. The structured value
reaches the client through output.presentationMeta: each tool projects the
fields its view needs, the harness persists that projection with the session
log, and it arrives as the settled block's meta on live and replay paths
alike. The adapter validates that projection and renders the component, or falls
back to the result text when a replayed log carries a shape it does not
recognise — as a captioned card that scrolls its own overflow and is reachable
by keyboard, since that fallback is a tool view like any other.

The chip appears twice on purpose. SessionUsage is documented as the shape
cloudflare_aigateway_session_cost returns, so the component that renders the
session header renders that tool's result too — and its loading and failed
states are a running call and a failed one.

The package ships cloudflare.css. Colours are CSS custom properties, so a
host's theme wins wherever it defines them, and the stylesheet declares no
color-scheme of its own — light-dark() reads the scheme it inherits, so
these fragments take whichever one the page is already in. They did declare
one, which made them answer the operating system while the page answered
itself: a dark card on a white document, in a host that had done nothing
unusual. The browser lane now resolves the colour in all six combinations of
what a host declares and what a system prefers, and an invariant holds the
declaration out.

All user-facing copy routes through a typed dictionary in locales/en.ts,
including accessible names — those are part of the interface, not decoration.
That is a gate, not a habit: the invariants lane reads each component's syntax
tree and fails on any literal a user would read. It had to be, because a
toggle's entire accessible name was a literal in the component while the
sentence above sat here unchecked.

Accessibility

Upstream DSH ships no accessibility guidance for plugin authors. This project
sets its own bar: WCAG 2.2 AA, zero axe violations, enforced in CI.

Accessibility runs in five lanes, because no one of them reaches every
criterion:

graph LR
    subgraph jsdom["Lane 1 — jsdom, per component"]
        A["Roles, names, structure"]
        B["Keyboard reachability"]
        C["ARIA wiring: describedby, invalid, live regions"]
    end
    subgraph chromium["Lane 2 — real Chromium via Playwright"]
        D["Text contrast, light and dark"]
        E["Focus ring, walked by keyboard"]
        F["Every state, and the client assembled"]
    end
    subgraph computed["Lane 3 — computed from the stylesheet"]
        H["Non-text contrast: borders, focus rings"]
    end
    subgraph viewport["Lane 4 — laid out, 320px to 1920px"]
        I["Reflow, target size, text spacing"]
        J["hidden, forced colours, whose scheme wins, the engine floor"]
    end
    subgraph e2e["Lane 5 — mounted and operated"]
        K["Keyboard and pointer, form and live regions"]
    end
    jsdom --> G["0 violations, 0 left for review"]
    chromium --> G
    computed --> G
    viewport --> G
    e2e --> G

Each split exists for a measured reason.

axe-core's colour-contrast rule runs under jsdom and cannot decide there: it
comes back incomplete on every component this package renders, measured
rather than taken from an issue tracker. So text contrast is checked in a real
browser, where the rule reaches a verdict, in both
colour schemes, across every state a surface can be rendered into from its
props — an empty chip, a failed one, an empty result set each render copy no
other state does.

Components that pass alone can conflict once composed, so the client is also
scanned as a host assembles it: the session chip and the settings card once
each, and every tool view twice, because a tool view is rendered once per tool
call. That scan earns its place — the first time it ran it found the tool views
registering as region landmarks, so a conversation running the same query
twice shipped two identically named landmarks. They are figures now.

axe has no rule at all for non-text contrast (SC 1.4.11) and none for focus
appearance, so neither is assumed. The invariants lane reads the shipped
stylesheet, resolves every --cf-* token in both schemes, and fails on any
colour beneath the ratio its use requires — 4.5:1 for text, 3:1 for a border or
a focus ring. The browser lane walks the assembled page by keyboard and pins the
focus ring the stylesheet declares, because Chromium draws a ring of its own
when a page supplies none, and a test that only asks whether something is
drawn passes with the focus block deleted.

Three more criteria are only observable once the page has a width, and axe has
a rule for none of them. The assembled client is laid out at 320, 390, 430,
768, 1024, 1280 and 1920 CSS pixels and checked at every one of them for
reflow (SC 1.4.10 — at 320, which is a 1280px window at 400% zoom, nothing
may scroll in two directions at once), target size (SC 2.5.8 — measured on
the rendered box, not read off the declaration, and 44px rather than 24
wherever the pointer is coarse) and text spacing (SC 1.4.12 — line height
1.5, letter spacing 0.12em, word spacing 0.16em, paragraph spacing 2em, with
nothing clipped).

The coarse pointer is emulated, not inferred from a narrow viewport. hasTouch
is the only context option that makes (pointer: coarse) match, each run
asserts the feature actually flipped, and until it did the stylesheet's whole
finger-sized-target block could have been deleted with every gate green — under
this page saying it was measured.

That lane found a box-model bug on its first run: with no box-sizing, a field
at inline-size: 100% added its padding and border on top of the width it was
given, and the page scrolled sideways at every width including 1920. The same
lane asks what hidden computes to, because jsdom applies no CSS — a class
setting display: grid outranks the user agent's [hidden] { display: none },
and the chip's collapsed detail was on screen with a passing test asserting the
attribute was set.

The same lane asks whose colour scheme these fragments follow, in all six
combinations of what a page declares and what a reader's system prefers. That
is a contrast question (SC 1.4.3) rather than a styling one: while the
stylesheet declared a color-scheme of its own, a page that had chosen light
under a dark system got dark fragments, and one that had chosen dark under a
light system got light ones — text on its own background, and not correctable
by the host. Every fixture agreed with the system, so no lane disagreed with
it, and the screenshots showed it before any assertion did.

Every one of those lanes renders these components to static markup, which
has no React attached: a toggle that never toggles, a form that never submits
and a live region that never updates all produce markup identical to ones that
work. The fifth lane bundles the real components with the real React, mounts
them, and operates them — activating the toggle with Enter and with Space,
because a real button answers both and a div with a click handler answers
neither; typing an invalid reference and reading what the assertive region
says; saving and watching the secret field clear; and submitting with Enter
from a field. The bundle is built during the run rather than committed, so the
lane cannot drift from the source it claims to exercise.

Two more things only a browser can answer. In forced-colours mode — Windows
high contrast — nothing may opt out of the system palette, and a field and a
table cell must still be bounded by a border the mode can repaint, because a
background alone disappears there. And these surfaces animate nothing: no
transition, no animation, no keyframes, enforced by the invariants lane. There
was a prefers-reduced-motion block here, and it set transition: none on
elements the stylesheet never gave a transition — neither property being
inherited, so a host could not have given them one either. It guarded nothing.
Introducing motion now fails a gate, which is the point at which a
reduced-motion story has to be written rather than assumed.

The bar is evaluated against the engines this stylesheet is written for —
Chrome and Edge 123, Firefox 120, Safari 17.5 and later, the floor
light-dark() sets. What happens below it is measured rather than described:
the lane renames the function, which rewrites the stylesheet's own feature
query along with its tokens, and asserts what an older engine would render —
text inheriting the host's colour, backgrounds falling away, and the accent
buttons still filled, because a token is the one thing a fallback cannot use
and the feature query hands them literals.

No lane filters axe. No tag scope, no disabled rules, no excluded
selectors — and the run is read for what it left for a human to review as well
as for what it failed, since incomplete is where a prohibited aria-label sat
while the gate read violations alone. The Chromium fixture supplies the
landmarks, page heading and chrome colours a host would provide, so page-scoped
rules fail on a real defect rather than on an unrealistic harness.

Specific commitments, each named with the test that holds it. "Covered by
tests" is worth nothing unless the test exists and runs, so readme.test.ts
collects both lanes and fails when a name below is not among them:

Screenshots are not in that list: cloudflare_browser_screenshot returns the
image as a harness attachment block, which the host renders, so this package has
no screenshot surface to give alternative text to. It once did, and the
commitment outlived the code by two restarts.

MCP passthrough

cloudflare-dsh/mcp exports patch rows for 17 hosted MCP servers — every
one Cloudflare publishes — each carrying a one-line summary so a profile can
choose without leaving the file. They range from the Code Mode server, which
reaches the whole Cloudflare API through code execution, to the per-product
servers for docs, bindings, builds, observability, containers, browser
rendering, Logpush, AI Gateway, AutoRAG, audit logs, DNS analytics, Digital
Experience Monitoring, CASB, Radar, the blog, and a published demo.

cloudflare-autorag keeps that name deliberately: the REST product was renamed
AI Search, which is why the tools address /ai-search, but the hosted MCP
server is still published as AutoRAG at the AutoRAG host. This list names
servers as Cloudflare publishes them.

Nothing ships enabled. Each server is a remote endpoint reached outside the
agent sandbox, so turning one on is a deliberate act by whoever owns the
profile. Authentication is browser OAuth, which makes these useful in an
interactive profile and unsuitable for headless runs.

A profile opts in by adding the rows it wants to its own patch layer. The
module builds them, so a server name is validated against the MCP client's
constraint before anything is mounted:

import { mcpPatchRows } from 'cloudflare-dsh/mcp'

// One row per server, each mounting '@deepseek-ai/dsh-mcp-client' over
// streamable HTTP. Paste into the profile's patch layer.
const rows = mcpPatchRows(['cloudflare-docs', 'cloudflare-browser'])

Security model

Credentials

graph LR
    A["cordis.yml<br/>apiTokenRef: CLOUDFLARE_API_TOKEN"] -->|"a name, never a value"| B["ctx.credentials"]
    B -->|"resolve() per request"| C["HTTP client"]
    C -->|"Authorization: Bearer"| D["Cloudflare"]
    E["SettingsCard"] -->|"write-only"| B
    B -.->|"redacted descriptor only"| E

• The token is re-resolved on every request and never cached, so rotation
  takes effect without a restart.
• Configuration and patch YAML hold the reference name, never the secret.
• Error messages name the reference, never the value.
• The settings UI is write-only: it can set a credential and learn whether one
  is stored, never read it back.

The escape hatch is bounded

cloudflare_api exists so the ~70 Cloudflare resources this bundle does not
wrap stay reachable. It is a bounded capability, not a bypass:

1. Read-only by default. allowMutations is false, and anything but
   GET/HEAD is rejected at the schema level.
2. Path denylist. denyPathPrefixes refuses matching paths outright.
3. Validated, not concatenated. No .., no absolute URLs, no host
   override — it cannot leave the REST root or reach another host.

Quality

Every gate below fails the build. The typecheck, lint, format, invariant and
coverage lanes run on Node 22 and 24, and so does packaging, which loads the
built artifacts the way a consumer on either would. The accessibility and
mutation lanes run on Node 22 alone — a Chromium scan and a mutation run do not
change with the Node major, and doubling either buys a longer wait rather than
a stronger signal. test:invariants asserts that split, so the sentence and
the workflow cannot drift apart.

Three toolchain notes for contributors, each a pin with a reason rather than a
version left behind:

• Tests run on Vitest under Node rather than bun test, because Stryker has no
  official Bun runner and DSH executes plugins on Node. Bun is the package
  manager and script runner.
• Vitest is pinned to 4.x. On Vitest 5 the Stryker vitest runner's per-test
  filter matches nothing and every covered mutant reports as surviving
  (stryker-js#6210),
  which would leave the mutation gate green and meaningless. The pin is
  asserted, so a caret cannot appear without a gate going red. Unpin once that
  is fixed.
• TypeScript is on 6.x, not 7. TypeScript 7 is the native compiler and ships no
  programmatic API — its lib/ holds tsc.js and nothing else — and every
  gate on this page that reads a syntax tree is built on that API: the escape-
  hatch scan, the superseded-doc scan, the inline-copy scan, and the README's
  tool, field and slot discovery. A stable API is expected in 7.1. The tree is
  ready for it otherwise: baseUrl is gone, since it stops functioning in 7,
  and ignoreDeprecations is banned — silencing a deprecation is a suppression
  comment in configuration form.

Development

bun install

Development history is in QUALITY-LOOP.md.

Repository layout

packages/
  core/     @d4551/dsh-cloudflare-core   — the ctx.cloudflare seam
    src/    client.ts is the only module that performs I/O;
            config, credentials, errors, paginate, request, retry, scope are pure
  bundle/   cloudflare-dsh               — the bundle
    src/seam.ts reaching ctx.cloudflare, in one place rather than five
    src/ai/     adapter, transducer, sse, headers, request, errors
    src/tools/  ai, data, web, meta
    src/tools/_shared/  json, render, paging, batch — what every tool group shares
    src/specs/  request specifications, separated from tool wiring
    src/mcp/    hosted MCP server rows
    presets/    pi-ai.yaml — the zero-code declarative path
    cordis.patch.yml
  client/   @d4551/dsh-cloudflare-client — Web Client surfaces
scripts/    mutation-guard.ts        — the escape guard's checks, as pure functions
            verify-mutation-files.ts — applies them to the tree after a mutation run
tests/      dist.test.ts           — the built-output suite
            invariants.test.ts     — the quality rules, as assertions
            mutation-guard.test.ts — each guard check, shown to fail
            readme.test.ts         — this page's counts, names, commitments, diagrams

test:dist deliberately has no source aliases. The unit and accessibility
suites reach src through a path alias; this one resolves the packages the way
a consumer would, and rejects a workspace: range surviving into a published
manifest.

Project status

Pre-1.0, tracking a pre-stable harness. DSH is a developer preview whose own
documentation warns of compatibility-breaking changes, so DSH dependencies are
pinned to exact versions.

Not yet done, and worth knowing before you depend on this:

• Nothing enforces a green run at the merge button. The gates fail the
  build, but main carries no branch protection, so a red or unfinished run
  does not block a merge. The commit that carried this bundle onto main is the
  proof: its run was cancelled by the push that followed and never finished, so
  no gate ever reported on it. Turning protection on is a repository setting, not
  something this tree can assert.
• The packages are not published to npm. Build and pack work; publishing is
  a deliberate step that has not been taken, so the dsh plugin add command
  above will not resolve them yet.
• R2 object access and D1 database creation are missing. Buckets can be
  listed and created, and Vectorize indexes read and written; R2 object-level
  work needs the S3 API and is not wrapped yet.
• The Web Client's host contract is modelled, not compiled. The tool views
  now take the owner props a host supplies and read each tool's
  output.presentationMeta projection to get the value they render, so they
  render the tool's result rather than nothing. What remains unverified by a
  compiler is the shape of that contract: ToolCallViewProps is not exported
  from @deepseek-ai/dsh-client-ui-tool's package root, and these packages'
  declarations do not typecheck with skipLibCheck off, so the owner props and
  the settled block are modelled from the published declarations and pinned by
  the contract suite instead. A field renamed upstream is a test to fix, not a
  compiler error.
• presentCall and presentResult are not declared. The provider-neutral
  render intents would give the pending and completed cards a title and a
  category; the tools rely on the harness's generic card today. The tool views
  do not depend on them.

License

MIT — see LICENSE.