stitchkit 0.103.13 → 0.104.0

package/llms/cli.txt

@@ -6,7 +6,7 @@
 
 Parts of this slice:
 - `llms/cli.txt`: Guide: CLI  (docs/guide/cli.md)
-- `llms/cli.2.txt`: API reference: `stitchkit/cli`  (docs/api/reference.md)
+- `llms/cli.2.txt`: Guide: CLI  (docs/guide/cli.md) · API reference: `stitchkit/cli`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: CLI  (docs/guide/cli.md)
@@ -26,6 +26,46 @@ It exists for what the other three surfaces cannot do: a generation kicked off
 with `Bash(run_in_background)` that notifies on exit, a `SKILL.md` that shells
 out in one line, a pipeable terminal command.
 
+## Installation and types
+
+Install `stitchkit` and `zod` for a CLI. The public `stitchkit/cli` runtime and
+declarations do not require `ai`, the MCP SDK or Bun globals. Node consumers can
+use strict `NodeNext` resolution with `skipLibCheck: false` and ordinary Node
+types; the package keeps its required dependencies separate from optional SDKs.
+
+CLI runtime tools use the shared executable contract: identity, input and output
+schemas, handler, and explicit CLI exposure. SDK presenters belong to the MCP/AI
+definitions in `stitchkit/tools`, which require the corresponding peers. A typed
+definition returned by `defineRuntimeTool` or `createRuntimeToolFactory` can be
+passed directly to both CLI and SDK mounts.
+
+Keep transport-specific `present` on that typed SDK definition, rather than on
+an inline object in `CliConfig.runtimeTools`. CLI never executes those presenters;
+its neutral configuration does not validate SDK presentation. Native CLI command
+presentation remains on `defineCliCommand({ present })` and retains its inferred
+output type.
+
+For a CLI-only managed tool, use the neutral generic construction contract to
+infer the handler from its schemas:
+
+```ts
+import type { RuntimeToolExecutionWithOutput } from 'stitchkit/cli'
+import { z } from 'zod'
+
+const input = z.object({ text: z.string() })
+const output = z.object({ size: z.number() })
+const measure = {
+  name: 'measure', description: 'Measure text',
+  identity: { serviceName: 'text', action: 'measure', method: 'POST' },
+  transports: ['CLI'], input, output,
+  handler: ({ input }) => ({ size: input.text.length }),
+} satisfies RuntimeToolExecutionWithOutput<typeof input, typeof output>
+```
+
+Pass `measure` to `runtimeTools`. The heterogeneous registration type preserves
+the definition without inventing a common handler input; execute it through
+`createCli` or `createCliInvoker` so validation remains on the canonical path.
+
 ## Exposure is opt-in
 
 Unlike MCP and agent — where an endpoint with no `expose` is a tool by default —
@@ -666,6 +706,88 @@ manifest URL is configuration you wrote, while an asset URL arrives inside a
 document the endpoint served, and a document is exactly what an SSRF boundary
 exists to distrust.
 
+### Publishing a complete version
+
+`publishCli` is an opt-in publisher for a local application-owned distribution
+directory. It commits every target and its version manifest before atomically
+replacing the public `manifest.json`. Your application selects the CLI source
+identity and admits that snapshot at each phase:
+
+```ts
+import { publishCli } from 'stitchkit/cli'
+
+const result = await publishCli({
+  storageRoot: '/srv/myapp/cli',
+  name: 'myapp', version: cliVersion, commit: selectedCliCommit,
+  baseUrl: 'https://downloads.example.com/cli/',
+  targets: [{ platform: 'linux', arch: 'x64' }],
+  signal,
+  admit: ({ phase, identity, signal }) => assertSelectedSource({ phase, identity, signal }),
+  build: ({ target, stamp, signal }) => compileSelectedSource({ target, stamp, signal }),
+})
+// result.outcome: 'published' | 'existing'; result.manifest is ready to serve.
+```
+
+The builder returns `Uint8Array` or `ReadableStream<Uint8Array>` containing the
+executable. Every target receives the same immutable `{ version, commit,
+builtAt }` stamp; carry it inside the binary. The publisher owns staging,
+gzip assets, paths and manifests. Callbacks receive the cancellation signal and
+run under the publication lock. Admission phases are `prepare`, each target's
+`build`, `commit`, and `promote`; validate the selected source through commit
+and promotion. A backend release can explicitly select an unchanged older CLI
+identity. The helper never substitutes a different commit or rebuilds an
+existing version under a new identity.
+
+Assets live at `<version>/<name>-<platform>-<arch>.gz`, with an immutable
+`<version>/manifest.json` and a public `manifest.json`. A verified repeat keeps
+the exact bytes and `builtAt`, requires the same target set and base URL, and
+returns `existing` without invoking the builder. A version committed before a
+failed promotion is recovered and promoted without rebuilding. Conflicting
+same-version commits, downgrades, unsafe components, corrupt manifests and
+assets are refused. Version/name/target components are validated before any
+build; `storageRoot` is absolute and its existing parent must be trusted.
+
+All limits are finite positive safe integers; `limits` overrides these defaults:
+
+| Field | Default | Enforced boundary |
+| --- | --- | --- |
+| `maxTargets` | 16 | Requested and verified target count |
+| `maxManifestBytes` | 256 KiB | Read and written manifest bytes |
+| `maxAssetBytes` | 256 MiB | Builder and decompressed executable bytes |
+| `maxCompressedBytes` | 256 MiB | Archived asset bytes |
+| `maxDirectoryEntries` | 128 | Version layout, root scan and commit space |
+| `maxStoredVersions` | 16 | Verified publisher-owned history |
+| `lockTimeoutMs` | 10,000 | Wait to acquire the lock |
+| `timeoutMs` | 600,000 | Whole publication deadline |
+
+`retention` defaults to 2 and keeps the current and previous published versions.
+It must be at least 2 and less than `maxStoredVersions` (at least 3), leaving a
+recovery slot. Older versions are pruned only after their own identity, exact
+layout, raw size and digest are verified. Runtime folders and foreign semver
+directories remain untouched. A full or unverifiable store refuses further
+publication; repeated completed candidates stay inside the owned history cap.
+Cancelled or failed incomplete staging is removed only while its root and
+directory generations still match. The shared asynchronous gzip decoder also
+bounds updater expansion by the declared raw size and configured byte cap.
+
+The publisher rejects symlink roots/versions/assets, non-regular files and
+multiply linked files, and checks held-lock, root and prior-pointer generations
+before commit and promotion. This is cooperative publication under a trusted
+parent directory. Portable path checks do not provide an atomic comparison with
+a hostile process replacing ancestors between syscalls. Durability uses file
+and directory sync on POSIX; Windows publication is refused. A deadline stops
+callback/stream waits and blocks late promotion; trusted callbacks remain
+responsible for cancelling their own subprocesses and external effects.
+
+A failure after an immutable commit reports that the publication outcome must
+be checked. A failure after public-pointer rename may already have published;
+`AtomicFilePublicationError.published` remains available when the atomic writer
+reports that boundary. Read the durable manifest and retry the admitted same
+identity to recover; an error does not promise rollback. Optional `signing` and
+`trust` reuse the Ed25519 contract below. The generated shell installer checks
+raw digest and size; the updater checks manifest authorship when given a trust
+root.
+
 ### Proving who built it — signing the manifest
 
 The asset digest proves the bytes that arrived are the bytes the manifest named.
@@ -889,106 +1011,3 @@ asked.
 What stays yours: what makes a repeat safe (an idempotency key derived from the
 line id), which operations a batch may contain, and how much of it runs at once.
 That is product knowledge, and the framework has no business guessing it.
-
-## Commands discovered from a running server
-
-A CLI compiled from contracts carries the surface of the build it was compiled
-from. One built from discovery carries the surface the server has *right now* —
-which matters, because a long-lived MCP client freezes schemas at connect time
-and then refuses the server's own newer fields:
-
-```ts
-const discovered = await mountConnections([
-  defineMcpClientConnection({
-    name: 'api',
-    transport: { url },
-    token: () => key,
-    transports: ['CLI'],   // the opt-in: this server's tools are commands
-  }),
-])
-await createCli({ name: 'myapp', version, runtimeTools: discovered, commands: [...] })
-```
-
-`transports` is where the opt-in belongs: a whole server becomes a set of
-commands, and a connection without it still contributes nothing to the CLI —
-exposure stays explicit, as it is everywhere else in the framework.
-
-One unconvertible schema no longer takes the connection down with it. The tool
-is skipped and **named** (`onSkippedTool`, or a stderr line by default), so a
-surface of two hundred tools is not lost to one.
-
-**A remote refusal keeps its code.** A failed `tools/call` used to become a
-one-sentence `Error` with the result discarded, which cost three things at once:
-the code (so `exitCodes` had nothing to map and every remote failure exited `1`),
-the message the operator needed, and the error's own class — a plain `Error` is
-an *unexpected* error to the runner, so it printed a code frame of the framework
-bundle before the JSON failure and was then scrubbed to `INTERNAL_SERVER_ERROR`.
-A structured `{ error, details }` body is now relayed as the contract error it
-is, on every transport; anything else fails as `UPSTREAM_TOOL_ERROR` carrying
-what the server did send. Not `INTERNAL_SERVER_ERROR`, because nothing of ours
-broke.
-
-**On the CLI a discovered command prints the answer, not the envelope.**
-`tools/call` returns `{ content: [...], structuredContent? }`, and an agent mount
-needs exactly that — the parts are what a model is shown. The CLI is different in
-kind, because the handler's value is what gets printed, piped and aggregated:
-handed the envelope, `--count-by status` groups the *content parts* and answers
-`no record carries the field "status" — available: text, type`. So the CLI
-transport unwraps, and only it: `structuredContent` when the server sent one, a
-lone text part when it parses as JSON, its text when it does not, and `null` when
-there are no parts at all — a tool without an output contract answers that way,
-and the `_meta` beside an empty `content` is protocol metadata, never the answer.
-Several parts, an image or audio pass through whole — picking one of many would
-be inventing an answer.
-
-
-## Auth parity
-
-A scoped command is guarded by the same `createAuthHook` your HTTP server uses —
-pass it as `lifecycle`, and inject the identity through `context` so
-`resolveFromContext` can read it:
-
-```ts
-const authHook = createAuthHook({ /* resolve, resolveFromContext, rules */ })
-
-await createCli({
-  name: 'myapp',
-  version: '1.0.0',
-  resolveAuth: () => resolveIdentityFromToken(process.env.MYAPP_TOKEN),
-  context: (identity) => ({ user: identity }),   // resolveFromContext reads this
-  lifecycle: { beforeHandle: authHook },          // same policy; HTTP wires it as authorize
-  services,
-})
-```
-
-Without `lifecycle`, a scoped command runs **unguarded** — the scope check lives
-entirely inside the `createAuthHook` result, so with no hook wired in there is
-nothing to enforce a method's `scope`. This matches the MCP / agent surfaces
-exactly ([ADR 0014](../decisions/0014-tool-http-parity.md)): on every tool
-transport the auth gate is opt-in, so a contract with scoped methods **must** be
-given a `lifecycle` (and `context` identity) to be protected. The gate only
-*fails closed* once the hook **is** present but `resolveFromContext` is missing —
-then a scoped call has no identity and is rejected.
-
-## Typed context
-
-Use `createToolkit<AppContext>()` to type the injected `context` against your
-app's context shape — the tool-side mirror of `createImplement`
-([ADR 0017](../decisions/0017-typed-tool-context.md)):
-
-```ts
-const tools = createToolkit<{ user: User }>()
-await tools.createCli({
-  name: 'myapp',
-  version: '1.0.0',
-  services,
-  context: (identity) => ({ user: identity }),   // checked against { user: User }
-})
-```
-
-## Remaining boundary
-
-File-upload (`multipart`) contract endpoints remain CLI-invisible, the same as
-on MCP/Agent: their wire body is not a JSON tool form. Model file-oriented
-application behavior as a managed pathless command, or binary-only behavior as
-a native command. Streaming (SSE) output is not yet piped to stdout.

package/llms/contract.txt

@@ -570,7 +570,7 @@ from the root `stitchkit`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `AppError` | class | the framework error — `code` / `status` / `details` / `hint` |
-| `ErrorEnvelope` | _type_ | the JSON shape of an error response |
+| `ErrorEnvelope` | _type_ | the JSON shape of an error response, preserving optional declared boolean `error.retryable` without changing HTTP retry policy |
 | `notFound` | function | throw `404 NOT_FOUND` — [guide](../guide/auth-and-errors.md#throwing-errors) |
 | `badRequest` | function | throw `400 BAD_REQUEST` |
 | `unauthorized` | function | throw `401 UNAUTHORIZED` |

package/llms/server.4.txt

@@ -547,12 +547,15 @@ error round-trips without adding correlation data to the response body.
 A `code` is a free string — your app codes (`BOT_NOT_FOUND`, …) are yours and the
 core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`,
-`CONFLICT`, `RATE_LIMITED`, `VALIDATION_ERROR`, `FILE_INVALID_PATH`,
+`CONFLICT`, `RATE_LIMITED`, `REQUEST_ABORTED`, `REQUEST_TIMEOUT`,
+`VALIDATION_ERROR`, `FILE_INVALID_PATH`,
 `FILE_OUTSIDE_ROOT`, `FILE_NOT_FOUND`, `FILE_NOT_REGULAR`,
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
 `WAIT_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
+`CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
 `STREAM_TERMINAL_MISSING`, `STREAM_LIFETIME_EXCEEDED`,
 `GRAMMY_WEBHOOK_NOT_ACCEPTING`, `SANDBOX_UNAVAILABLE`, `SANDBOX_INSUFFICIENT`,

package/llms/server.5.txt

@@ -57,6 +57,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `respondJson` | function | a raw route's JSON response (`204` for null/undefined) |
 | `errorResponse` | function | any thrown value → the framework error envelope + `x-request-id` |
 | `normalizeError` | function | any thrown value → an `AppError` (`ZodError` → `VALIDATION_ERROR` 400 with structured `details.issues`, else generic 500) — the framework's canonical classification, for a bespoke `onError` |
+| `NormalizeErrorOptions` | _type_ | `logUnexpected` defaults to logging the raw server-side cause; tool adapters disable process dumps while their existing observers retain that cause |
 | `errorCode` | function | the stable error code for a thrown value (side-effect-free — for log attribution) |
 | `formatZodError` | function | a `ZodError` → a readable, field-summarised string |
 | `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the machine-readable sibling of `formatZodError` |

package/llms/stitchkit.2.txt

@@ -710,6 +710,13 @@ URLs.
 
 ## `ApiError`
 
+On native Bun, both client paths disable Bun's separate socket idle timer while preserving
+the framework deadline and caller signal. A long declared deadline therefore remains the
+request policy. Explicit or patched fetch implementations, including Next, keep their own
+transport behavior; Node and browsers receive no Bun-specific fetch options. Raw responses
+and contract streams retain their existing header timeout and caller-owned body lifetime.
+See [Bun's idle timeout contract](https://bun.sh/reference/globals/BunFetchRequestInit/timeout).
+
 A non-2xx response is thrown as an `ApiError`:
 
 ```ts
@@ -724,6 +731,7 @@ try {
     err.message  // 'Note not found'
     err.details  // structured details, if any
     err.hint     // optional hint
+    err.retryable // optional explicit recommendation, true or false
     err.traceId  // x-request-id — correlate this failure with backend logs
     err.cause    // concrete injected transport failure, when delivery failed
   }
@@ -737,6 +745,12 @@ browser code can read it through Stitchkit's default CORS expose list; a custom
 
 The error model is shared with the server — see [Auth & errors](./auth-and-errors.md).
 
+`retryable` preserves an explicit boolean in the server error envelope; an absent declaration
+remains absent. This metadata does not change the HTTP transport retry policy. The existing
+seventh constructor argument remains `ErrorOptions`, including `cause`; the optional
+retryability argument is eighth. Closed error/frame schemas must accept the new optional
+field before their producer declares it.
+
 ## Auth events
 
 The HTTP client emits events your app can react to globally:

package/llms/stitchkit.txt

@@ -63,10 +63,11 @@ own, recorded as an ADR.
 | `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
 | `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
 | `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
+| `stitchkit/tools/mcp` | server (Bun or Node) | evolving | the canonical MCP HTTP/stdio server, schemas and typed MCP presenters; only Zod and the MCP server SDK peers |
 | `stitchkit/tools/contract` | browser + server | evolving | the shapes a tool surface speaks — async-operation contract, snapshot and cancel schemas, view-file input/output — without the runtime that serves them |
 | `stitchkit/tools/invoker` | server | stable | peer-free `createToolInvoker` over the canonical contract tool runner |
 | `stitchkit/tools/connections` | server (Bun or Node) | evolving | consume external MCP servers and a bounded OpenAPI subset — typed reauthorization, a per-request host fence and per-call credentials |
-| `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
+| `stitchkit/cli` | server | stable | `createCli` / `createCliInvoker` — runtime and strict NodeNext declarations without MCP SDK / `ai` |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture and process-group cancellation |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
@@ -80,12 +81,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 48 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 49 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 48 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 49 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -98,7 +99,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 11 of the 48 minors since 0.56.2, most recently 0.103.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 12 of the 49 minors since 0.56.2, most recently 0.104.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |

package/llms/telegram.txt

@@ -184,7 +184,8 @@ const report = await runTelegramBroadcast({
   `retry_after` and sends the same recipient again; a server error is retried
   with backoff up to `maxAttempts`, then `failed`. A message Telegram cannot
   parse is not the recipient's fault: the run **halts** with them still pending,
-  so the run after the fix reaches them. So does Telegram being unreachable.
+  so the run after the fix reaches them. An unknown transport outcome becomes
+  `uncertain` immediately and halts the run; resume never sends to that recipient again.
 - **Pacing** is `ratePerSecond`, 25 by default. `dryRun` counts and writes
   nothing. One runner per name: a second concurrent run is refused.
 
@@ -193,6 +194,66 @@ application (the application's signal, with admission held by the caller).
 The recipient state contains Telegram ids: keep it in the state directory, out
 of git.
 
+### Injecting another transport's failure policy
+
+`classify(error)` returns the public `TelegramBroadcastFailure` union. It lets
+an application use its own client without adding that SDK to Stitchkit:
+
+```ts
+const report = await runTelegramBroadcast({
+  name: 'announcement',
+  directory: env.STATE_DIRECTORY,
+  recipients: () => audience.activeSubscribers(),
+  send: ({ recipient }) => client.sendMessage(recipient, message),
+  classify(error) {
+    if (isFloodWait(error))
+      return { kind: 'retry-after', retryAfterMs: error.seconds * 1000,
+        reason: 'provider-rate-limit' }
+    if (isRecipientGone(error))
+      return { kind: 'permanent', recipientUnreachable: true,
+        reason: 'recipient-gone' }
+    return { kind: 'ambiguous', reason: 'unknown-provider-outcome' }
+  },
+  maxRetryDelayMs: 60_000,
+  signal: stop.signal,
+})
+```
+
+The four variants are `retry-after` (exact `retryAfterMs`), `transient` (bounded
+backoff), `permanent` (optionally `recipientUnreachable` or `stopBroadcast`), and
+`ambiguous`. Retry variants certify that the failed attempt had no external
+effect. Lack of an HTTP status does not establish that fact: a server may have
+accepted the message before the connection failed. `ambiguous` durably records
+`uncertain`, then halts; resuming the name skips that recipient.
+
+`maxRetryDelayMs` defaults to 60 seconds. A provider wait above it halts with the
+recipient pending; it is never shortened to send early. `maxAttempts` is an
+integer from 1 to 100, `maxRetryDelayMs` is an integer from 0 to 2,147,483,647,
+and pacing/progress intervals must fit native timers. The optional
+`sleep(milliseconds, signal)` receives cancellation; the runner also stops waiting
+when the signal aborts if a custom sleeper ignores it. A send already in flight
+finishes and is recorded before stopping.
+
+Without `classify`, known Bot API 429, unreachable-recipient, malformed-message
+and server-error behavior remains. Unknown/no-status failures now halt as
+uncertain, rather than being automatically retried. Existing custom `send`
+implementations that relied on those retries must supply an explicit classifier
+for proven pre-effect failures. `report.halt` now carries
+`TelegramBroadcastFailure`; inspect `halt.kind` instead of the old send-failure
+`scope`/`retryable` fields.
+
+The runner uses the shared process-instance lock and checks its generation before
+sends and journal writes. The audience and initial journal directory entry are
+synced before sending. Lost ownership cannot write a stale delivered receipt or
+start another send; the persisted intent becomes uncertain on recovery. Old
+pid-only broadcast locks have unknown ownership and require recovery after their
+writers are verified stopped, rather than automatic age-based deletion.
+
+The installed
+[`telegram-broadcast-classifier.mjs`](../../packages/core/scripts/consumer-lane/fixtures/minimal/src/telegram-broadcast-classifier.mjs)
+fixture checks injected rate limits, ambiguity/no resend, wait budgets and abort
+on Bun and Node without a client SDK.
+
 ## Message markup
 
 `stitchkit/telegram/html` is Telegram's HTML parse mode as a tree, with no peer
@@ -393,8 +454,9 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `classifyTelegramSendFailure` | function | name a refused Bot API send and separate "retry this send" from "stop addressing this recipient" |
 | `TelegramSendFailure` | _type_ | reason, `status`, Telegram-stated `retryAfterSeconds`, `retryable`, `recipientUnreachable` and which evidence produced the answer |
 | `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
-| `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience written once, an append-only journal, pacing at `ratePerSecond` (25), 429 waits `retry_after`, unreachable recipients never addressed again, a `message-invalid` or unreachable Telegram halts without charging the recipient, a send in flight at a crash is `uncertain` and not repeated, `dryRun`, one runner per name |
+| `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience and journal durably recorded, pacing at `ratePerSecond` (25), exact retry delays within the finite declared budget, injected classifier, uncertain send outcomes never replayed, `dryRun`, one fenced runner per name |
 | `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
+| `TelegramBroadcastFailureSchema` / `TelegramBroadcastFailure` | schema / _type_ | injected `classify` answers retry-after/transient/permanent/ambiguous; exact provider delay is bounded by `maxRetryDelayMs` without shortening, unknown outcome remains uncertain and is never replayed |
 | `telegramBroadcastSender` / `TelegramBroadcastSenderConfig` / `TelegramBroadcastMessage` | function / _type_ | the standard `send`: `sendMessage` with a text or `copyMessage` of a prepared message, through the Bot API |
 | `createTelegramOperatorChannel` | function | the operator chat, apart from the journal: `post(text, topic?)` returns at once and never throws; paced sends into forum topics, 429 honoured, oldest dropped on overflow, `drain(signal)` and `close()` for the way down |
 | `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`, `sensitivePatterns` and `sensitiveValues` (a bot token is always masked), `dedupe`; a drop is `overflow` / `refused` / `attempts` / `closed` / `repeated` / `over-budget` with its classification |

package/llms/tools-connections.txt

@@ -23,6 +23,9 @@ and approval path.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `defineMcpClientConnection` | function | declare one external MCP server connection over Streamable HTTP with an optional SSE fallback |
+| `ConnectionOperationLimits` / `McpConnectionLimits` | _type_ | positive finite deadline/raw byte ceilings with independent discovery/call overrides; omitted fields inherit the shared bounds |
+| `ConnectionPhase` / `ConnectionOperation` / `ConnectionFailureContext` | _type_ | closed operation/phase vocabulary and measured read context for existing typed connection errors |
+| `ConnectionTimeoutError` / `ConnectionResponseTooLargeError` | class | bounded operation refusal, with phase, operation and finite observed bytes; safe tool projection retains the raw cause locally |
 | `defineOpenApiConnection` | function | declare one OpenAPI document (object, JSON text or JSON URL) as a tool surface |
 | `mountConnections` | function | discover every connection and return readonly `RuntimeToolDefinition`s for `mountAgent` |
 | `ConnectionAuthorizationRequiredError` | class | typed reauthorization signal raised on `401` with credentials resolved again on the next call |

package/llms/tools-mcp.txt

@@ -0,0 +1,29 @@
+# stitchkit/tools/mcp — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/tools/mcp`  (docs/api/reference.md)
+
+Also read:
+- see `llms/tools.txt` for the MCP & agents guide
+
+==============================================================================
+# API reference: `stitchkit/tools/mcp`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/tools/mcp`
+
+A server-only leaf over the same MCP owner as `stitchkit/tools`. Its runtime and strict
+NodeNext declarations require Zod and `@modelcontextprotocol/server`, with no AI SDK peer.
+HTTP/stdio factories, mounts, schema policy, catalog and resource helpers keep their canonical
+behavior and names. See [MCP guide](../guide/mcp-and-agents.md#mcp--createmcphandler).
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `createMcpHandler` / `createMcpHttpRoute` / `buildMcpServer` / `mountMcp` | function | the shared authenticated HTTP handler, raw-route adapter, SDK server and contract mount |
+| `createStdioMcpServer` / `bindStdioProcessSignals` | function | the shared stdio server and bounded process cleanup |
+| `RuntimeMcpToolDefinitionWithOutput` | _type_ | schema-aware MCP-only construction with concrete handler output and presenter input |
+| `RuntimeMcpToolDefinition` | _type_ | heterogeneous MCP registration; the canonical runner validates input/output before invocation |
+| `RuntimeMcpToolPresenters` / `RuntimeMcpPresentation` | _type_ | official SDK content without framework-owned `structuredContent` or `isError`; one presenter owner shared with the full SDK surface |
+| `RuntimeToolDefinitionWithoutOutput` | _type_ | the shared neutral void definition |

package/llms/tools.2.txt

@@ -13,6 +13,65 @@ Parts of this slice:
 # Guide: MCP & agents  (docs/guide/mcp-and-agents.md)  (continued)
 ==============================================================================
 
+## Proxying a remote API — `implementRemote`
+
+`implement` binds a contract to local handlers. `implementRemote` binds it to a
+remote HTTP API instead — every handler forwards the call to a deployed server
+through the contract's typed client:
+
+```ts
+import { createHttpClient } from 'stitchkit'
+import { implementRemote } from 'stitchkit/remote'
+import { createStdioMcpServer } from 'stitchkit/tools/mcp'
+
+const http = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  headers: () => ({ Authorization: `Bearer ${apiKey}` }),
+})
+
+const stdio = await createStdioMcpServer({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth: null,
+  services: contracts.map((c) => implementRemote(c, http)),
+})
+
+// During graceful shutdown:
+await stdio.close()
+```
+
+This is how you ship a thin **local** MCP server for an API that already runs in
+the cloud: the local process owns only the transport and any filesystem-facing
+native tools, while every contract tool proxies to the remote API. One contract,
+no duplicated business logic.
+
+`implementRemote(contract, http, { transformArgs })` takes an optional
+`transformArgs` hook that rewrites a call's arguments before they are forwarded
+— e.g. to upload a local file referenced in the args and swap in its URL.
+
+The call's signal reaches the existing typed HTTP client's request options, for endpoints
+with or without arguments. An already cancelled call, including cancellation while an async
+argument transform runs, dispatches no request. Bind your process signal to `createCli` or
+`createCliInvoker`; `REQUEST_ABORTED` is a safe nonretryable failure with CLI exit130.
+Cooperative origins observe `ctx.signal` and release resources when their work ends. An
+origin or provider ignoring cancellation may continue after the local wait stops.
+
+An explicit `AppError.retryable` boolean also survives this remote hop. `false` on502 and
+`true` on409 remain the application's recommendation through HTTP, CLI, MCP and AI tools.
+Absent metadata keeps the previous defaults and does not alter HTTP transport retries.
+
+## Structured output
+
+When a contract endpoint or runtime tool declares `output`, its MCP tool
+registers that exact schema as `outputSchema` and returns the validated value as
+`structuredContent` alongside a JSON text block. Every JSON root type is kept
+unchanged: object, array, string, number, boolean and `null`. Stitchkit does not
+wrap non-object values in `{ result }`; protocol-era adaptation belongs to the
+official SDK.
+
+A tool without an output contract advertises no `outputSchema` and returns no
+invented structured value. Its successful MCP result has an empty `content`
+list.
+
 ## A different answer for tools — `withToolView`
 
 An admin page wants the full record; a model wants a card. Every byte of a

package/llms/tools.3.txt

@@ -278,6 +278,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `TransportSummary` | _type_ | `{ contractServices, runtimeTools, totals, sources }` from `summarizeTransports` |
 | `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
 | `ToolSurfaceDefinition` | _type_ | shared object-shaped `{ services?, runtimeTools? }` introspection surface |
+| `ToolSurfaceProjection` | _type_ | one readonly services/runtime container shared by full and MCP-only surfaces; executable mounts specialize the runtime definition without pulling in another adapter's peers |
 | `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
 | `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; the projection never executes validation |