stitchkit 0.92.0 → 0.94.0

package/llms-full.txt

@@ -1,7 +1,8 @@
 # stitchkit — full documentation
 
-> The complete guide + API reference, inlined for offline agent use. Generated
-> from the `docs/` tree (the source of truth) by `bun run gen:llms`.
+> The complete guide + API reference, inlined for tools that index one file. Far
+> larger than an agent context — an agent loads the slices listed in `llms.txt`.
+> Generated from the `docs/` tree (the source of truth) by `bun run gen:llms`.
 
 
 ==============================================================================
@@ -66,13 +67,13 @@ 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 37 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 store and managed-resource conformance kits |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 39 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/agent-runtime` | server | evolving<br>_redefined in 20 of the 37 minors since 0.56.2, most recently 0.89.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 21 of the 39 minors since 0.56.2, most recently 0.94.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 and deterministic race controls |
+| `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 |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -80,7 +81,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 7 of the 37 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 39 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `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 |
@@ -639,7 +640,7 @@ const contract = defineContract(meta, endpoints)
   client method name and the handler name.
 
 `defineContract` throws at definition time if two endpoints declare the same
-`toolName` on the same transport — a tool-name clash is a bug, caught early.
+`tool.name` on the same transport — a tool-name clash is a bug, caught early.
 
 ## An endpoint
 
@@ -680,7 +681,7 @@ export const users = defineContract({ prefix: 'users' }, {
 | `output` | no | Zod schema for the **response body**; its presence declares a JSON result (`null` is data, `undefined` is not) |
 | `scope` | no | access scope for this endpoint — see [Auth & errors](./auth-and-errors.md) |
 | `expose` | no | which transports carry this endpoint — see [below](#transports) |
-| `toolName` | no | explicit MCP / agent tool name (default: a verb-aware derivation, see below — not a literal `prefix_key`) |
+| `tool` | no | what the tool surfaces (MCP / agent / CLI) read that HTTP does not — see [below](#tool-options-tool) |
 | `multipart` | no | typed file fields, cardinality, delivery and upload policy — see [below](#file-uploads) |
 | `maxJsonBodyBytes` | no | per-route JSON body ceiling; overrides the server default |
 | `timeout` | no | per-endpoint client timeout in ms, for slow endpoints |
@@ -810,14 +811,34 @@ a tool result cannot carry — it would serialize to `{}`),
 headers have no meaning on a tool call) and `rawBody` (HTTP-only by
 construction).
 
-## `toolName`
+## Tool options (`tool`)
+
+Everything a tool surface reads that HTTP does not lives in one group, so an
+endpoint that can never be a tool (a raw response, a stream, `responseMeta`,
+`rawBody`, `HEAD`) refuses all of it with one key:
+
+| `tool.` | Purpose |
+|---------|---------|
+| `name` | explicit tool name (default: a verb-aware derivation, below) |
+| `view` | a different answer on MCP / agent / CLI — input defaults and a projected, separately validated output; declared only with `withToolView` — see [MCP & agents](./mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
+| `ui` | MCP Apps widget for the tool's results — see [MCP & agents](./mcp-and-agents.md) |
+| `annotations` | MCP behavioural hints (`readOnlyHint`, `destructiveHint`, `title`, …) |
+| `mcp` | elicitation rounds asked before the handler runs (`inputRequired`) |
+
+`expose` stays outside the group: it chooses transports, HTTP included.
+Setting `tool` on an endpoint with no tool transport — `expose: ['HTTP']`, or an
+omitted `expose` under a factory with `toolExposure: 'explicit'` — throws at
+definition time. The pre-0.94 top-level keys (`toolName`, `toolView`, `ui`,
+`annotations`, `mcp`) are refused by name, with where each one went.
+
+### `tool.name`
 
 When an endpoint is exposed as a tool, its name defaults to a verb-aware
 derivation from the method key + prefix (`users` + `create` ⇒ `create_user`,
-`users` + `list` ⇒ `list_users`). Set `toolName` for an explicit, stable name:
+`users` + `list` ⇒ `list_users`). Set `tool.name` for an explicit, stable name:
 
 ```ts
-{ method: 'POST', path: '/', desc: 'Create a user', toolName: 'create_user', /* … */ }
+{ method: 'POST', path: '/', desc: 'Create a user', tool: { name: 'create_user' }, /* … */ }
 ```
 
 **Every tool name — derived or explicit — must match `[a-zA-Z0-9_-]` and be at
@@ -829,13 +850,13 @@ included: `bot-status` + `get` ⇒ `get_bot_status`, `admin/analytics` + `get`
 `get_admin_analytics`. The *method* half keeps its hyphen and normalises only
 what no provider accepts (`[^a-zA-Z0-9_-]`), because a hyphenated method key has
 always shipped a legal name that a client config may already pin: `notes` +
-`get-user` ⇒ `get-user_notes`. An explicit `toolName` is taken verbatim.
+`get-user` ⇒ `get-user_notes`. An explicit `tool.name` is taken verbatim.
 
 A prefix with *no* usable character at all (`'///'`, `'_'`, a fully non-ASCII
-prefix) and any explicit `toolName` outside the accepted class **throw at
-mount**. An unusable prefix is rescued by setting an explicit `toolName` — the
+prefix) and any explicit `tool.name` outside the accepted class **throw at
+mount**. An unusable prefix is rescued by setting an explicit `tool.name` — the
 prefix then never enters the name. An over-long name is fixed by a shorter
-explicit `toolName` (or a shorter prefix / method key). Nothing downstream checks this: the provider rejects the whole
+explicit `tool.name` (or a shorter prefix / method key). Nothing downstream checks this: the provider rejects the whole
 request, so one bad name takes every tool of that mount down with it.
 → [ADR 0035](../decisions/0035-tool-name-derivation-and-validation.md).
 
@@ -1864,8 +1885,8 @@ validate exactly as elsewhere, and the endpoint goes through `beforeHandle` —
 the **auth gate applies without a guard in the handler**. Only the response is
 handed over, so there is no `output` schema, `afterHandle` is skipped (it
 transforms data; there is none) and the endpoint is HTTP-only: never an MCP
-tool, an agent tool or a CLI command. Declaring `output`, `toolName`, `ui`,
-`annotations` or a non-HTTP `expose` alongside `rawResponse` is a type error, and throws
+tool, an agent tool or a CLI command. Declaring `output`, `tool` or a non-HTTP
+`expose` alongside `rawResponse` is a type error, and throws
 at definition time for a contract assembled at runtime.
 
 On the typed client the method resolves to the untouched `Response` — the
@@ -3262,13 +3283,13 @@ Pin the full list with `listToolNames` in a snapshot test.
 `desc` is the tool description the model reads — write it for the model, not
 just for a human. The tool name defaults
 to a verb-aware name from the method + prefix (`list` → `list_widgets`, `get` →
-`get_widget`); set `toolName` for an explicit one. Derivation normalises **per half**
+`get_widget`); set `tool.name` for an explicit one. Derivation normalises **per half**
 (→ ADR 0035): the service half turns everything outside `[a-zA-Z0-9_]` into `_`,
 hyphen included (`bot-status` ⇒ `get_bot_status`), while the method half keeps
 its hyphen (`get-user` ⇒ `get-user_notes`) because such a name has always been
 legal and may already be pinned in a client config. A name is *accepted* if it
 matches `[a-zA-Z0-9_-]`. A name that
-still cannot be delivered (illegal explicit `toolName`, over 64 characters, or a
+still cannot be delivered (illegal explicit `tool.name`, over 64 characters, or a
 prefix with no usable character) throws at mount rather than at the first model
 call —
 → [ADR 0035](../decisions/0035-tool-name-derivation-and-validation.md). See
@@ -3353,6 +3374,12 @@ model-safe envelope. Unexpected throws remain scrubbed. An unknown name throws
 against which hooks could run. Duplicate and provider-invalid names fail when
 the invoker is created.
 
+The invoker's caller is code, so it gets an endpoint's full answer even where a
+[tool view](#a-different-answer-for-tools--withtoolview) is declared. When the
+invoker backs a transport a model reads, pass `toolSurface: true`: calls then
+get the view's defaults and projected answer, which is what `collectTools` and
+`buildToolManifest` advertise.
+
 ## MCP — `createMcpHandler`
 
 `createMcpHandler` builds a complete stateless Streamable-HTTP MCP endpoint on
@@ -3694,19 +3721,21 @@ deleteProject: {
   expose: ['MCP'],
   input: DeleteProjectSchema,
   output: DeleteProjectResultSchema,
-  mcp: {
-    inputRequired: [
-      {
-        key: 'confirmation',
-        schema: DeleteConfirmationSchema,
-        message: 'Confirm permanent deletion',
-      },
-      {
-        key: 'reason',
-        schema: z.object({ value: z.string().min(3) }),
-        message: 'Record the reason',
-      },
-    ],
+  tool: {
+    mcp: {
+      inputRequired: [
+        {
+          key: 'confirmation',
+          schema: DeleteConfirmationSchema,
+          message: 'Confirm permanent deletion',
+        },
+        {
+          key: 'reason',
+          schema: z.object({ value: z.string().min(3) }),
+          message: 'Record the reason',
+        },
+      ],
+    },
   },
 }
 ```
@@ -3741,12 +3770,14 @@ input image — and there a declared list can only be empty. `inputRequired` als
 accepts a function of the parsed call:
 
 ```ts
-mcp: {
-  inputRequired: async ({ input }) => {
-    const model = await catalog.get(input.model)
-    return model.needsRatio
-      ? [{ key: 'ratio', schema: RatioSchema, message: 'Which aspect ratio?' }]
-      : []
+tool: {
+  mcp: {
+    inputRequired: async ({ input }) => {
+      const model = await catalog.get(input.model)
+      return model.needsRatio
+        ? [{ key: 'ratio', schema: RatioSchema, message: 'Which aspect ratio?' }]
+        : []
+    },
   },
 }
 ```
@@ -4145,6 +4176,69 @@ 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
+tool result enters the model's context and stays in its history, and personal
+fields a task does not need are better never shown to it. Two endpoints on one
+path (one `expose: ['HTTP']`, one for the tools) duplicate the description, the
+schemas and the handler; branching on `ctx.source` teaches every handler about
+transports and still advertises the full output schema.
+
+A **tool view** declares the difference on the endpoint instead:
+
+```ts
+import { defineContract, withToolView } from 'stitchkit';
+
+export const users = defineContract({ prefix: 'users' }, {
+  list: withToolView(
+    {
+      method: 'GET', path: '/', desc: 'List users', tool: { name: 'user_list' },
+      input: UserListQuery,        // include: z.array(...).default(['profile', 'stats'])
+      output: UserListResponse,    // HTTP, OpenAPI and the typed client — unchanged
+    },
+    {
+      defaults: { include: [] },                          // what a tool call gets when it passes nothing
+      output: UserCardList,                               // the tool answer and its schema
+      project: (full, { input }) => ({ items: full.items.map(toCard) }),  // optional: without it, `output` slices
+    },
+  ),
+});
+```
+
+- **One handler, one parser.** `defaults` joins the tool call's arguments
+  *before* the endpoint's own `input` parses them, so the handler receives an
+  ordinary `input` — `include: []` from a tool, the HTTP default from HTTP — and
+  loads only what was asked for. An explicit argument wins over the default.
+- **The answer is derived, then checked.** The handler's result is validated
+  against the full `output` first, as always; then `project` (a pure,
+  synchronous function of the full result and the parsed input) or a slice by
+  the view's `output`, then validation against the view's schema. A projection
+  that throws, returns a Promise or breaks its schema is `INTERNAL_SERVER_ERROR`
+  — a server fault, like any output mismatch.
+- **Where it applies.** The MCP, agent and CLI mounts answer with the view;
+  `outputSchema`, `structuredContent`, the advertised input `default`, the
+  catalog stamp and the surface snapshot follow it. HTTP, OpenAPI, the typed
+  client and the in-process [`createToolInvoker`](#in-process-calls--createtoolinvoker)
+  keep the full answer — code, not a model, is calling there.
+- **Three forms, one helper.** With `output` and `project` the answer has its
+  own schema. With `project` alone it reshapes values inside the full schema.
+  With `output` alone it is a slice, and the full result must fit that schema —
+  `withToolView` refuses the endpoint at compile time when it does not.
+- **Exposure.** A view needs a tool transport. With `createContractFactory({
+  toolExposure: 'explicit' })` an endpoint without `expose` is HTTP-only, so an
+  endpoint with a view names its tool transports in `expose`.
+- **What it refuses.** `defineContract` rejects a view on an endpoint with no
+  tool transport or no full `output`, on a raw, `rawBody`, multipart,
+  `responseMeta` or streaming endpoint, a view that declares neither `output`
+  nor `project`, and a default for a key the input does not have, for a path
+  param, or with a value the input would reject.
+
+A projection adds nothing the full result does not carry: a field the tool
+answer needs belongs in the full answer, loaded by the handler. Keys a
+projection returns beyond its schema are reported by `onOutputStrip`; a slice
+removes keys on purpose and is not reported. → [ADR 0196](../decisions/0196-a-tool-answer-is-a-declared-view.md)
+
 ## AI agents — `mountAgent`
 
 `mountAgent` remains the low-level path when the application owns its own model
@@ -4468,7 +4562,7 @@ const runtimeTools = exportOperation.runtimeTools
 #### Durable application-owned execution
 
 The executable reference
-[`durable-async-operation-harness.ts`](../../packages/core/examples/durable-async-operation-harness.ts)
+[`durable-async-operation-harness.ts`](../../packages/core/examples/tools/durable-async-operation-harness.ts)
 shows the complete boundary behind that surface. It composes
 `defineAsyncOperationContract`, `defineAsyncOperation`, `createApplication`,
 `createBoundedAdmission`, managed shutdown and `createAgentToolFenceLifecycle`
@@ -4943,7 +5037,7 @@ Each run may resolve a different provider adapter without changing the harness.
 provenance and sorted direct tool names; it intentionally contains no resource text, prompts,
 arguments or credentials. Observer failure never changes the canonical run outcome.
 
-[`packages/core/examples/headless-agent-runner.ts`](../../packages/core/examples/headless-agent-runner.ts)
+[`packages/core/examples/agent-runtime/headless-agent-runner.ts`](../../packages/core/examples/agent-runtime/headless-agent-runner.ts)
 is a reference structured control loop for `submit`, `interrupt`, `snapshot` and bounded `close`.
 It starts no process and chooses no framing, authentication or transport. Importing either example
 has no side effect; an external supervisor owns process placement and restart.
@@ -5765,11 +5859,11 @@ state. Exactly-once external delivery remains an application-owned outbox.
 ### External channel ingress and delivery
 
 The executable
-[`external-channel-harness.ts`](../../packages/core/examples/external-channel-harness.ts)
+[`external-channel-harness.ts`](../../packages/core/examples/agent-runtime/external-channel-harness.ts)
 is the reference composition for webhooks, polling transports and local-device
 adapters. Its generic boundary injects a runtime, durable store and delivery
 adapter; the optional
-[`external-channel-grammy.ts`](../../packages/core/examples/external-channel-grammy.ts)
+[`external-channel-grammy.ts`](../../packages/core/examples/agent-runtime/external-channel-grammy.ts)
 attaches the same ingress function to grammY polling or webhook lifecycle
 without putting provider types in the agent runtime.
 
@@ -6100,8 +6194,9 @@ outbox.
 
 ## Deterministic race and adapter proof
 
-`stitchkit/testing` exports `createAgentRaceBarrier`, `createAgentRaceDriver` and
-`createAgentRaceTrace`. Barriers have bounded teardown, traces assert exact partial order, and the
+`stitchkit/agent-runtime/testing` exports `createAgentRaceBarrier`, `createAgentRaceDriver`,
+`createAgentRaceTrace` and `runAgentStoreConformance` — agent testing tools live beside the agent
+runtime, and `stitchkit/testing` imports none of it. Barriers have bounded teardown, traces assert exact partial order, and the
 helpers are exercised from packed Bun and Node consumers. `runAgentStoreConformance` runs duplicate,
 coalescing, collision, stale checkpoint, replay safety, terminal race, absorption, bounded reads,
 causal queued-history order, durable interrupt priority, compaction and recovery invariants against
@@ -7514,9 +7609,9 @@ Unlike MCP and agent — where an endpoint with no `expose` is a tool by default
 the CLI never silently turns your existing API tools into shell commands.
 
 ```ts
-{ method: 'POST', path: '/', desc: 'Generate media', toolName: 'generate',
+{ method: 'POST', path: '/', desc: 'Generate media', tool: { name: 'generate' },
   expose: ['CLI', 'MCP', 'AGENT'], input: GenerateInput, output: Generation }   // CLI + MCP + agent
-{ method: 'GET', path: '/models', desc: 'List models', toolName: 'list_models',
+{ method: 'GET', path: '/models', desc: 'List models', tool: { name: 'list_models' },
   expose: ['CLI'] }                                                             // CLI only
 { method: 'GET', path: '/search', desc: 'Search' }                              // HTTP + MCP + AGENT — NOT CLI
 ```
@@ -7524,7 +7619,7 @@ the CLI never silently turns your existing API tools into shell commands.
 A fresh contract shows **zero** CLI commands until methods opt in — that is the
 design, not a bug. A pathless runtime definition follows the same rule: it must
 explicitly include `'CLI'` in `transports`; the undefined default remains
-`['MCP', 'AGENT']`. The command name is the tool name — `toolName` if set, else
+`['MCP', 'AGENT']`. The command name is the tool name — `tool.name` if set, else
 a verb-aware name from the method + prefix (`list` → `list_widgets`, `get` →
 `get_widget`), not a literal `prefix_key`.
 
@@ -8070,6 +8165,30 @@ Carry the build stamp inside the binary (`CliBuildStampSchema`,
 `formatCliBuildStamp`) so the tool can say what it is rather than leaving the
 reader to infer it from behaviour.
 
+#### A manifest inside your own network
+
+The check goes through the same SSRF boundary every outbound fetch does, so a
+manifest served from `10.x`, `localhost` or a `.internal` name is refused and
+the answer is `unknown`. For a self-hosted deployment that is a wrong answer
+dressed as a careful one, and the refusal says so — it names the field that
+lifts it rather than reading like a timeout:
+
+```text
+refusing to fetch an internal host — the manifest endpoint is not public.
+Set `allowPrivateHosts` if it is your own deployment; the download keeps its
+own setting, because an asset URL comes from the document.
+```
+
+```ts
+const check = await checkCliUpdate({ manifestUrl, currentVersion, allowPrivateHosts: true })
+```
+
+Set it from whether **your** endpoint is private, not as a blanket switch, and
+leave `applyCliUpdate` at its default. The two are not the same decision: the
+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.
+
 ### Proving who built it — signing the manifest
 
 The asset digest proves the bytes that arrived are the bytes the manifest named.
@@ -8190,6 +8309,39 @@ already holding, plus a process start measured at 0.15 s — thirty seconds for
 two-hundred-line manifest before any work begins. The ban on nesting one stream
 inside another was a consequence of that child process, not a rule anyone wanted.
 
+### Native commands in the stream
+
+A native command is in the invoker's surface when — and only when — it declares
+`output`:
+
+```ts
+const describe = defineCliCommand({
+  name: 'describe', description: 'Describe the catalogue',
+  input: z.object({ model: z.string() }),
+  output: z.object({ model: z.string(), ratios: z.array(z.string()) }),
+  handler: ({ input }) => ({ model: input.model, ratios: ['1:1', '16:9'] }),
+})
+
+await createCliInvoker({ name: 'myapp', services, commands: [describe] })
+// invoke('describe', { model: 'flux' }) → { ok: true, exitCode: 0, data: { … } }
+```
+
+A command that declares `output?: never` prints itself and returns nothing, so
+there is no result to hand back; it answers `NOT_FOUND` and stays on the command
+line, where stdout exists. Your stream command is one of these, which is why a
+stream still cannot invoke itself.
+
+On this path `present` is not called — it is stdout formatting, and there is no
+stdout — while `exitCode` is applied through the same function the command line
+uses, so a script branching on the code sees one answer from both. Anything the
+handler writes comes back as `written` rather than interleaving with your own
+output:
+
+```ts
+const outcome = await invoker.invoke('describe', { model: 'flux' })
+outcome.written // { stderr: 'warming the cache\n' } — absent when nothing was written
+```
+
 ### Mounting the loop
 
 ```ts
@@ -8502,7 +8654,7 @@ the framework how to load them so your bundler can put them inside — see
 [shipping one self-contained artifact](./testing-and-deployment.md#shipping-one-self-contained-artifact).
 
 The canonical room-broadcast example below is executed by the test suite. Its
-body is kept byte-identical to `packages/core/examples/realtime-room.ts`.
+body is kept byte-identical to `packages/core/examples/realtime/realtime-room.ts`.
 
 ```ts canonical-realtime-room
 export function publishExampleNote(realtime: ExampleRealtimePublisher): void {
@@ -12421,6 +12573,92 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.94.0
+
+One breaking minor that consolidates: tool options move into one group, and
+names that were exported from two entrypoints keep only their owner. Every step
+is an edit a type checker or `defineContract` points at; the few behaviour
+changes that need no edit are under Changed and Fixed in the changelog.
+
+1. **Move endpoint tool options into `tool`.** **Who must act:** every project
+   with an endpoint that sets `toolName`, `ui`, `annotations` or `mcp`. Run the
+   codemod from a checkout of this repository, then typecheck:
+
+   ```bash
+   bun packages/core/scripts/codemod-tool-group.ts --check path/to/your/src   # list
+   bun packages/core/scripts/codemod-tool-group.ts path/to/your/src           # rewrite
+   ```
+
+   ```ts
+   // before
+   { method: 'GET', path: '/', desc: 'List', toolName: 'user_list', mcp: { inputRequired } }
+   // after
+   { method: 'GET', path: '/', desc: 'List', tool: { name: 'user_list', mcp: { inputRequired } } }
+   ```
+
+   The codemod leaves two kinds of endpoint for a person and prints where: one
+   built with a spread (`{ ...base, toolName }`), and one exposed on HTTP only,
+   whose tool options never reached a tool — delete them there. Anything left
+   over fails at startup, by name — a key moved into the group under its old
+   name (`tool: { toolName }`) included:
+
+   ```text
+   Contract "users": endpoint "list" sets `toolName` — tool options live in `tool` since 0.94.0: use tool.name
+   ```
+
+   `expose` does not move. `MethodDef` — what hooks and runtime tools see — keeps
+   `toolName`, `ui`, `annotations` and `mcp` at the top level, so hook code does
+   not change. A tool view is declared only with `withToolView`, which now puts
+   it in `tool.view`.
+
+2. **Change imports of moved names.** **Who must act:** projects importing any
+   of these; the compiler lists every site.
+
+   | Name | From | To |
+   |---|---|---|
+   | `RuntimeToolTransport`, `ToolSurfaceTransport`, `ToolInvokerTransport` | `stitchkit/tools`, `stitchkit/tools/invoker`, `stitchkit/tools/connections` | `ToolTransport` from `stitchkit/contract` |
+   | `createCli`, `defineCliCommand`, `CliConfig`, `CliSurfaceSource`, `CliPresentationPolicyConfig`, `CliWaitConfig`, `ExitCodeMap`, `CliCommand*` | `stitchkit/tools` | `stitchkit/cli` |
+   | `parseSSE`, `ParseSSEOptions` | `stitchkit/server` | `stitchkit` |
+   | `runAgentStoreConformance`, `AgentStoreConformance*`, `createAgentRace*`, `AgentRace*` | `stitchkit/testing` | `stitchkit/agent-runtime/testing` |
+   | `createLocalStepDurability`, `LocalStepDurability`, `LocalStepDurabilityOptions`, `StepDurabilityLedger` | `stitchkit/agent-runtime` | `stitchkit/tools` |
+
+3. **Regenerate a surface snapshot only if it reports drift.** **Who must act:**
+   a project whose committed snapshot has an object with integer-like keys
+   (`"9"`, `"10"`) — they are now sorted like every other key. Every other
+   snapshot, CLI manifest signature and agent-store archive is byte-identical.
+
+## Released migration: 0.93.0
+
+1. **Regenerate every committed surface snapshot, once.** `manifestVersion` is
+   `3` and each operation row gained `mcp` — the rounds it declares before it
+   runs. Most rows get `null`, so the first diff is large and mechanical.
+   **Who must act:** anyone with a committed snapshot. A snapshot on the older
+   version is refused by name rather than failing a schema literal:
+
+   ```text
+   Surface snapshot is manifestVersion 2; this build writes 3. Regenerate it
+   and review the diff — the format changed, so the first regeneration is
+   expected to be large.
+   ```
+
+   ```ts
+   // before — a declared round left no trace, so declaring or removing one
+   // passed review invisibly
+   manifest.operations[0]
+   // after
+   manifest.operations[0].mcp
+   // null | { inputRequired: [{ key, message, schema }] }
+   //      | { inputRequired: 'resolved-per-call' }
+   ```
+
+   A project that kept its own test for "declared `inputRequired` implies a
+   configured state key" can drop it: the snapshot holds that link now.
+
+2. **Nothing else to do.** Native commands that declare `output` became
+   invokable in process; a name that answered `NOT_FOUND` from
+   `createCliInvoker` in 0.92.0 may now resolve. If an application relied on
+   native commands being unreachable there, stop passing them to the invoker.
+
 ## Released migration: 0.92.0
 
 1. **`RequestEvent.method`, `path` and `statusCode` are optional.** Work that did
@@ -16150,10 +16388,20 @@ from the root `stitchkit`.
 | `ScopedContractDef` | _type_ | a factory-defined contract whose `meta.scope` is the required concrete literal |
 | `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns — endpoint `scope` overrides join the union |
 | `ALL_TRANSPORTS` | constant | `['HTTP', 'MCP', 'AGENT', 'CLI']` |
+| `TOOL_TRANSPORTS` / `ToolTransport` | constant / _type_ | `['MCP', 'AGENT', 'CLI']` — the transports a model or tool client reads; the one name for a tool surface everywhere (runtime-tool `transports`, invoker, collector, connections) |
 | `ContractDef` | _type_ | a defined contract |
 | `PathParams` | _type_ | infer named `:segments` and a terminal `*wildcard` from a path literal as string params |
 | `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
 | `EndpointDef` | _type_ | a single endpoint definition; `output` declares JSON response presence (`null` is data, `undefined` is invalid); `safelistedBody: true` admits the JSON body as `text/plain` from an allow-listed `Origin` — [guide](../guide/server.md#safelisted-request-bodies-beacons) |
+| `withToolView` | function | declare an endpoint's answer on the tool surface (MCP, AGENT, CLI): input `defaults`, a view `output` and an optional `project`, typed against the endpoint's own schemas; HTTP keeps the full answer — [guide](../guide/mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
+| `EndpointToolOptions` | _type_ | an endpoint's `tool` group — `name`, `view`, `ui`, `annotations`, `mcp`: what the tool surfaces read that HTTP does not |
+| `EndpointToolView` | _type_ | the stored shape of a tool view (`MethodDef.toolView`) |
+| `DeclaredToolView` | _type_ | a tool view as `withToolView` produces it — the only form `tool.view` accepts |
+| `WithToolView` | _type_ | the endpoint `withToolView` returns: its own tool options plus the declared view in `tool.view` — name it when a helper returns such an endpoint |
+| `ProjectedToolView` / `ReshapedToolView` / `SlicedToolView` | _type_ | the three forms `withToolView` accepts: own schema + `project`, `project` inside the full schema, a slice by `output` |
+| `ToolViewCall` | _type_ | what `project` is told besides the full result: the parsed `input` and the `source` |
+| `ToolViewSliceMismatch` | _type_ | the compile-time refusal of a slice whose schema does not accept the full output |
+| `ToolViewNeedsToolTransport` | _type_ | the compile-time refusal of a view on an `expose: ['HTTP']` endpoint |
 | `EndpointStreamDescriptor` | _type_ | HTTP-only schema-derived stream declaration: item schema, envelope/item framing, stream-end/terminal completion, NDJSON/SSE encoding and frame/lifetime/heartbeat/idle bounds — [guide](../guide/server.md#contract-first-streams) |
 | `HeadEndpointDef` | _type_ | explicit HTTP-only, bodyless `HEAD` endpoint definition |
 | `EndpointResponseMeta` | _type_ | static success metadata declared by an HTTP-only typed-data endpoint |
@@ -16464,7 +16712,6 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `ndjsonRoute` | function | `streamingRoute` framed as NDJSON |
 | `sseRoute` | function | `streamingRoute` framed as SSE |
 | `DEFAULT_STREAM_HEARTBEAT_MS` | const | 5000 — deliberately well under Bun's ten-second idle threshold |
-| `parseSSE` | function | parse an SSE `Response` (also on the root entrypoint) |
 | `MultipartLifecycle` | _type_ | request-scoped rollback ownership for accepted streamed handles |
 | `MultipartResult` | _type_ | what `parseMultipart` returns |
 | `parseMultipart` | function | parse a typed buffered/streaming multipart descriptor — [guide](../guide/server.md#multipart) |
@@ -16500,7 +16747,6 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `EventBus` | _type_ | the `createEventBus` handle |
 | `RateLimitConfig` | _type_ | config for `createRateLimiter` |
 | `ClientIpOptions` | _type_ | trusted-proxy config for `extractIp` / `resolveSocketIp` |
-| `ParseSSEOptions` | _type_ | options for `parseSSE` |
 | `StreamingRouteOptions` | _type_ | options for `streamingRoute` / `ndjsonRoute` / `sseRoute` |
 | `StreamingSourceContext` | _type_ | what a streaming source is given, including the cancellation `signal` |
 | `StreamingFormat` | _type_ | `'ndjson' \| 'sse'` |
@@ -16878,8 +17124,7 @@ Server-only optional application runtime. See the
 | `composeAgentPrompt` | function | ordered prompt contributions and provenance-aware signed context budget; irreducible reservation deficits are `oversized`, not compactable history |
 | `SeedConversationInputSchema` / `SeedConversationInput` | schema / _type_ | atomic once-seeding input; partial imported identity sets are refused |
 | `AgentSeedReceiptSchema` / `AgentSeedReceipt` | schema / _type_ | durable seed receipt retained beyond compaction and implemented by custom store drivers |
-| `createLocalStepDurability` | function | record JSON step results and park on time/events; a replay returns recorded results, while unrecorded effects require host idempotency |
-| `StepDurabilityLedger` / `LocalStepDurability` / `LocalStepDurabilityOptions` / `StepRunOptions` | _type_ | the narrow ledger the port needs, the step/read surface, and its construction and per-step options |
+| `StepRunOptions` | _type_ | per-step options of the durability engine (`stitchkit/tools`) as the runtime drives it |
 | `DURABILITY_STEP_EVENT_KIND` | const | the ledger event kind a recorded step is written under |
 | `StepResultDecodeError` / `StepResultNotSerializableError` / `StepAbortedError` / `ParkRecordDecodeError` / `ParkAbortedError` | class | fail-closed decode of a recorded step or park, a body whose result cannot be serialized, an aborted step, and a park collapsed around an aborted waiter |
 | `structuredCompaction` | function | summarize a provider-valid snapshot range and replace it through CAS |
@@ -16928,7 +17173,7 @@ Server-only optional application runtime. See the
 | `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `createAgentScheduleService` / `createAgentScheduleTools` | schema / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, stable dispatch identity and Agent tools |
 | `AgentChildBudgetSchema` / `AgentChildBudget` / `AgentChildStateSchema` / `AgentChildState` / `AgentChildRecordSchema` / `AgentChildRecord` | schema / _type_ | durable child graph, bounded seed and measured budget state |
 | `AgentChildBlockingKindSchema` / `AgentChildBlockingKind` / `AgentChildBlockingSourceSchema` / `AgentChildBlockingSource` / `AgentChildBlockingEventSchema` / `AgentChildBlockingEvent` / `AgentChildBlockingDecision` | schemas / _types_ | parent-owned request identities; responses discriminate approval decisions from JSON input values |
-| `AgentChildHandle` / `AgentChildManager` / `createSqliteAgentChildManager` / `createAgentChildTools` / `agentChildBudgetStopPolicy` | _type_ / functions | host execution port, child lifecycle, cascade (given to `createAgentRuntime` as `children`), messaging, Agent tools, and the child runtime's own budget stop policy — `recordStepUsage` at every step boundary, `policy_stop` as `child-budget` when spent |
+| `AgentChildHandle` / `AgentChildManager` / `SqliteAgentChildManagerConfig` / `createSqliteAgentChildManager` / `createAgentChildTools` / `agentChildBudgetStopPolicy` | _type_ / functions | host execution port, child lifecycle, cascade (given to `createAgentRuntime` as `children`), messaging, Agent tools, and the child runtime's own budget stop policy — `recordStepUsage` at every step boundary, `policy_stop` as `child-budget` when spent |
 | `AgentToolDefinition` | _type_ | peer-neutral shape returned by the bound agent-only state, search, schedule and child tool factories |
 | `AgentProviderStreamCutError` | class | explicit retryable provider stream truncation evidence |
 
@@ -17093,6 +17338,9 @@ Credential-free provider and concurrency fixtures for Bun and Node tests.
 | `createAgentRaceBarrier` / `AgentRaceBarrier` | function / _type_ | named bounded deterministic concurrency barrier |
 | `createAgentRaceTrace` / `AgentRaceTrace` / `AgentRaceTraceEntry` | function / _type_ | record and assert exact event order without wall-clock guesses |
 | `createAgentRaceDriver` / `AgentRaceDriver` | function / _type_ | collect named barriers and release their teardown together |
+| `runAgentStoreConformance` | function | reusable black-box duplicate/coalescing/stale/recovery contract for durable agent-store adapters |
+| `AgentStoreConformanceConfig` | _type_ | `{ createStore(context), cleanup?(context) }` — the factory the contract runs against, plus a teardown that runs once whether the scenario passed or failed |
+| `AgentStoreConformanceContext` | _type_ | `{ conversationIds }` — every conversation the scenario will mutate, handed over **before** the first mutation so an adapter can provision application-owned parent rows; a zero-argument factory stays valid |
 
 ## `stitchkit/agent-runtime/harness`
 
@@ -17382,8 +17630,6 @@ payload.
 | `defineRuntimeTool` | function | define one validated pathless operation for explicit MCP, Agent and/or CLI surfaces — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner; use peer-free `stitchkit/tools/invoker`, or the full `stitchkit/tools` adapter barrel — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
-| `createCli` | function | a command-line program from contracts — [guide](../guide/cli.md) (also on `stitchkit/cli`) |
-| `defineCliCommand` | function | define one typed CLI-only command with optional post-validation `present` and successful `exitCode` policy — [guide](../guide/cli.md#native-binary-commands) (also on `stitchkit/cli`) |
 | `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
 | `mountViewFile` | function | a native multimodal "view file" MCP tool |
 | `resolveMedia` | function | resolve a media reference for a tool result |
@@ -17439,21 +17685,10 @@ payload.
 | `CimdCacheEvent` | _type_ | observable CIMD cache hit, miss, revalidation and eviction event |
 | `createSecureClientMetadataFetcher` | function | production HTTPS, DNS/IP-pinned CIMD fetcher |
 | `RuntimeAgentModelOutput` | _type_ | AI SDK model-facing text/JSON/content output returned by `present.agent` |
-| `RuntimeToolTransport` | _type_ | runtime exposure: `'MCP' \| 'AGENT' \| 'CLI'`; omission still means MCP+Agent only |
 | `AgentMountConfig` | _type_ | config for `mountAgent` |
 | `AgentToolRegistry` / `AgentToolRegistryBuilder` / `AgentToolRegistryInput` | _type_ | the composed runtime surface and its builder: declared defaults, `replace`/`disable` by name, and the exact `{ tools, names }` a mount receives |
 | `defineToolRegistry` | function | compose runtime tools over one declared default set; an unknown `replace`/`disable` name is refused instead of silently leaving the default in place |
 | `AgentContext` | _type_ | the context merged into agent tool handlers |
-| `CliConfig` | _type_ | config for `createCli`, including program-level `defaultCommand` selection, application-wide `globalOptions` and command-scoped `optionAliases` / `positionals` policy |
-| `CliPresentationPolicyConfig` | _type_ | reusable default-command, short-alias and explicit-positional policy inherited by `CliConfig` |
-| `CliSurfaceSource` | _type_ | static managed surface or identity-dependent surface factory for `createCli` |
-| `CliCommandDefinition` | _type_ | Zod-first CLI-only command union |
-| `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
-| `CliCommandDefinitionWithOutput` | _type_ | native command with declared output schema, validated handler result and typed optional `present` / `exitCode` callbacks |
-| `CliCommandDefinitionWithoutOutput` | _type_ | void native command with no output schema |
-| `CliCommandContext` | _type_ | parsed native command input, framework run options, the application's `globals` and injected writers |
-| `CliWaitConfig` | _type_ | `--wait` polling config |
-| `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
 | `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
 | `ToolExtend` | _type_ | extra-args extension for `mountMcp` / `mountAgent` |
 | `ToolLifecycle` | _type_ | `beforeHandle` / `afterHandle` gate for tool calls — [guide](../guide/mcp-and-agents.md#guarding-tools--lifecycle) |
@@ -17470,7 +17705,6 @@ payload.
 | `ToolInvoker` | _type_ | immutable compiled dispatcher (`names`, envelope `invoke`, throwing `invokeOrThrow`) |
 | `ToolInvokerConfig` | _type_ | compile-time exposure, extension and presentation options |
 | `ToolInvocationOptions` | _type_ | per-call source, context, lifecycle, hooks and output-strip reporter |
-| `ToolInvokerTransport` | _type_ | invoker exposure policy: `MCP \| AGENT \| CLI` |
 | `ToolCallContext` | _type_ | the context every tool hook receives — `{ source, mcp? }` plus whatever the mount's `context` added |
 | `ViewFileOptions` | _type_ | shared URL/managed-file-boundary policy for `defineViewFileTool`, `mountViewFile` and `resolveMedia` |
 | `ViewFileOutput` | _type_ | neutral managed batch result with multimodal `content` and per-item `errors` |
@@ -17637,7 +17871,6 @@ 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 |
-| `ToolSurfaceTransport` | _type_ | tool collector transport: `'MCP' \| 'AGENT' \| 'CLI'` |
 | `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; divergent fields retain every provable base kind in a deterministic `type` array, and the projection never executes validation |
@@ -17670,7 +17903,6 @@ and approval path.
 | `ConnectionMountOptions` | _type_ | shared `{ lifecycle?, budget?, onSkippedTool? }` mount policy |
 | `ConnectionToolSkipReporter` | _type_ | `(skipped) => void` — called per discovered tool the mount could not build; defaults to a stderr line, and the rest of the surface still mounts |
 | `SkippedConnectionTool` | _type_ | `{ connection, tool, reason }` — which tool was not mounted, and why |
-| `RuntimeToolTransport` | _type_ | `'MCP' \| 'AGENT' \| 'CLI'` — the surfaces a connection's `transports` may name |
 | `McpClientConnection` | _type_ | a defined MCP client connection |
 | `McpClientConnectionConfig` | _type_ | name, transport, tool filter, token provider, instance key, allowed hosts and `transports` — naming `['CLI']` makes the whole server's discovered tools commands, with no per-definition rewriting |
 | `McpConnectionTransport` | _type_ | `{ url, headers? }` for one MCP endpoint |
@@ -17689,9 +17921,6 @@ handler pipeline without opening a TCP port.
 |--------|------|---------|
 | `createHandlerTestClient` | function | one contract client backed by an in-process `FetchHandler` |
 | `createHandlerTestClients` | function | exact contract-registry batch form |
-| `runAgentStoreConformance` | function | reusable black-box duplicate/coalescing/stale/recovery contract for durable agent-store adapters |
-| `AgentStoreConformanceConfig` | _type_ | `{ createStore(context), cleanup?(context) }` — the factory the contract runs against, plus a teardown that runs once whether the scenario passed or failed |
-| `AgentStoreConformanceContext` | _type_ | `{ conversationIds }` — every conversation the scenario will mutate, handed over **before** the first mutation so an adapter can provision application-owned parent rows; a zero-argument factory stays valid |
 | `runManagedResourceConformance` | function | run the canonical deterministic lifecycle matrix against a fresh consumer-owned `ManagedResource` fixture; resolves `void` or throws `ManagedResourceConformanceError` with a stable scenario ID and normalized trace |
 | `ManagedResourceConformanceScenarioIdSchema` / `ManagedResourceConformanceScenarioId` | schema / _type_ | stable clean, rollback, readiness/completion, activation, shutdown-race and forced-cleanup scenario vocabulary |
 | `ManagedResourceConformanceScenarioSchema` / `ManagedResourceConformanceScenario` | schema / _type_ | discriminated scenario record including whether the controlled resource is required |
@@ -17702,8 +17931,6 @@ handler pipeline without opening a TCP port.
 | `ManagedResourceConformanceFactoryInput` / `ManagedResourceConformanceControls` | _type_ | current discriminated scenario and caller-controlled startup, readiness, completion, activation, close and force promises |
 | `ManagedResourceConformanceFixture` | _type_ | tested resource plus required bounded disposal callback |
 | `ManagedResourceConformanceError` | class | `MANAGED_RESOURCE_CONFORMANCE_FAILED` diagnostic carrying scenario, expected phase subsequence and observed trace |
-| `createAgentRaceBarrier` / `createAgentRaceDriver` / `createAgentRaceTrace` | function | bounded named barriers and exact partial-order traces for deterministic runtime race probes |
-| `AgentRaceBarrier` / `AgentRaceDriver` / `AgentRaceTrace` / `AgentRaceTraceEntry` | _type_ | public packed-consumer types for the deterministic race harness |
 | `HandlerTestClientDefaults` | _type_ | ordinary bare-client defaults with handler-owned `baseUrl` and `fetch` removed |
 | `HandlerTestClientConfig` | _type_ | handler, contract, path prefix, scoped config and client request defaults |
 | `HandlerTestClientsConfig` | _type_ | batch helper configuration |
@@ -17732,6 +17959,9 @@ handler pipeline without opening a TCP port.
 | `TransportObservation` | _type_ | validated normalized driver result |
 | `SurfaceManifest` / `SurfaceManifestConfig` | _type_ | deterministic surface snapshot and its inputs |
 | `SurfaceManifestOperation` / `SurfaceManifestOperationSchema` | _type_ / schema | one contract or runtime operation row |
+| `SurfaceManifestOperationMcp` / `SurfaceManifestOperationMcpSchema` | _type_ / schema | the rounds an operation declares before it runs: a fixed list, `'resolved-per-call'`, or `null` for no MCP policy |
+| `SurfaceManifestOperationToolView` / `SurfaceManifestOperationToolViewSchema` | _type_ / schema | an operation's declared tool view — digests of its defaults and output, and whether it projects; present only where a view is declared |
+| `SURFACE_MANIFEST_VERSION` | const | the format version this build writes; a committed snapshot on an older one is refused by name |
 | `SurfaceManifestTool` / `SurfaceManifestToolSchema` | _type_ / schema | one mounted tool row with advertised input digest |
 | `SurfaceManifestToolSurface` / `SurfaceManifestToolSurfaceSchema` | _type_ / schema | one static transport projection, optionally keyed for a finite MCP surface |
 | `SurfaceManifestRealtimeEvent` / `SurfaceManifestRealtimeEventSchema` | _type_ / schema | one named directional realtime event with input/output args and ack digests |