stitchkit 0.91.2 → 0.93.0

package/llms-full.txt

@@ -66,11 +66,11 @@ 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 1 of the 36 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 38 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/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 36 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 20 of the 38 minors since 0.56.2, most recently 0.89.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/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -80,7 +80,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 36 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 38 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 |
@@ -3639,6 +3639,48 @@ never for authentication, RBAC, tenant selection or rate limiting. Verified
 identity still comes from `auth`; the `context(auth)` callback remains the
 application-context factory and receives no protocol metadata.
 
+### Telling the host what a long call is doing — `ctx.reportProgress`
+
+A tool that takes ten minutes tells a text host nothing: the call is made, and
+the next thing the host shows is the answer. The protocol has a channel for
+this — the host sends a `progressToken` with the call, the server relates
+progress notifications to it — and a handler reaches it through
+`ctx.reportProgress`:
+
+```ts
+render: async (ctx) => {
+  await ctx.reportProgress?.({ message: 'queued' })
+  const job = await jobs.start(ctx.input)
+  await ctx.reportProgress?.({ message: 'rendering', progress: 1, total: 3 })
+  return await jobs.finish(job)
+}
+```
+
+`reportProgress` is present on every **tool** call — MCP, agent and CLI — so a
+handler never branches on transport, and it does nothing wherever nobody is
+listening. It is absent on the HTTP transport, which has no channel for it, so a
+handler that also serves HTTP writes `ctx.reportProgress?.(…)`. It never throws and never
+rejects: a message about work must not be able to kill the work it describes, so
+a refused notification leaves the host exactly where a host that never asked for
+progress already is.
+
+`progress` is a number the protocol requires and a handler often does not have —
+there is a stage to name and no scale to name it on. Omit it and the ordinal of
+the update is sent, with no `total`, so the host shows a counter rather than a
+bar stuck at 3%. That is a fact about what happened; a synthesised percentage
+would be a claim nobody measured.
+
+The framework sends nothing on its own. Progress is meaningful only where an
+operation has observable stages, and manufacturing one per call would be
+inventing a second transport beside the one the protocol already provides. The
+one exception is the managed wait tool (`mountWait`), which already polls and
+therefore already knows: when the host asked for progress it reports each poll
+and the phase it last saw, which is the tool whose silence raised the question
+in the first place.
+
+The token itself is on `ctx.mcp.progressToken` when a caller wants to know
+whether anyone is listening.
+
 ### Multi-round tool input (`input_required`)
 
 An MCP-only operation can require typed user input before its final side effect:
@@ -3690,6 +3732,58 @@ ordinary unsupported result rather than a falsely advertised round. Signed
 state is tamper-resistant, not an exactly-once replay store; destructive
 handlers must still be idempotent where retries matter.
 
+#### Questions chosen from the arguments
+
+The list above is fixed when the contract is written, which is right when the
+questions belong to the operation. It is not enough when they belong to the
+**arguments** — one model takes `aspect_ratio`, another `duration`, a third an
+input image — and there a declared list can only be empty. `inputRequired` also
+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?' }]
+      : []
+  },
+}
+```
+
+It receives the same `params` / `input` the handler receives — parsed, so
+defaults and coercions are already applied. Returning an empty array means this
+call needs nothing and runs straight through. Everything else is unchanged: the
+state is still signed and bound to principal, operation and argument digest, the
+rounds are still counted against `maxRounds`, and a resolved list with duplicate
+keys or more rounds than allowed is refused.
+
+**The plan is fingerprinted, and that matters more than it looks.** Between two
+rounds there is a full round trip to the host, and a resolver that reads
+anything outside its arguments — a model catalog, a feature flag — can answer
+differently the second time. Every other check would still pass: same principal,
+same operation, same arguments, round still in range. Round 2's question would
+be asked under round 1's key, and if the schemas happened to be compatible the
+user's answer would be accepted for a question nobody asked. So the resolved
+list is fingerprinted into the signed state and re-checked every round; a plan
+that moved is refused, not asked. A resolver that reads only its arguments never
+sees this.
+
+**What a dynamic declaration costs.** One extra pass through the contract
+pipeline per round — `lifecycle.beforeHandle` runs once more and one more
+`toolPhase: 'input-round'` audit row is written. That is the price of ordering:
+the resolver is your code and may reach a network, so it runs **after**
+authorisation, never before, and the only thing that can authorise is a pipeline
+pass. Resolving itself is free — the arguments are parsed by the same pure
+function the call parses with, not by a second run of anything. A fixed list
+pays none of this; its call sequence is unchanged.
+
+One thing does change for a fixed list: the signed round state now carries a
+fingerprint of the question plan, and it is checked on every round. A
+conversation already in flight when you deploy this has no fingerprint in its
+state and is refused once with `INVALID_REQUEST_STATE`; the host re-asks and the
+retry succeeds.
+
 ### Guarding tools — `lifecycle`
 
 A tool call runs the same handler an HTTP request would. `lifecycle` makes it
@@ -7976,6 +8070,223 @@ 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.
+It proves nothing about who named them: the manifest and the assets come from
+one origin, so whoever can replace one can replace the other. Authorship needs a
+key the build carries and the server never holds.
+
+```ts
+// Publishing — the only side that holds a private key.
+const signature = signCliManifest(manifest, { keyId: 'release-2026', privateKey })
+publish({ ...manifest, signature })
+
+// Installing — the trust root is compiled into the binary. One fetched at run
+// time from the same origin as the manifest would prove nothing.
+const trust = { keys: { 'release-2026': PUBLISHED_KEY } }
+const check = await checkCliUpdate({ manifestUrl, currentVersion, trust })
+if (check.status === 'outdated' && check.asset) {
+  await applyCliUpdate({ asset: check.asset, manifest: check.manifest, trust, backupPath })
+}
+```
+
+The signature covers `{name, version, commit, builtAt, assets[]}` with **every
+asset's digest**, so the chain closes on the file that will execute rather than
+on the document describing it; moving an asset to a new URL does not invalidate
+it, changing what an asset contains does.
+
+Five verdicts, and `unenforced` is the one that earns its keep: a build with no
+pinned key keeps updating, and the fact that nothing was checked is *visible*
+rather than assumed. `missing`, `unknown-key` and `invalid` are distinguished
+because they need different answers — a key you forgot to pin is not a forged
+signature.
+
+A bad verdict does not produce a fifth status. `outdated` is an instruction to
+install, and a manifest that failed its signature has not established that there
+is a newer build worth installing — only that a document claims one. The check
+answers `unknown` with the verdict in its reason, so it is never mistaken for a
+network failure. `applyCliUpdate` checks again and refuses **before** the
+download: a signature verified after the bytes are on the machine produces a
+cleanup problem rather than a refusal.
+
+### A way back — `backupPath` and `rollbackCliUpdate`
+
+Rolling back is a property of updating, not of the application:
+
+```ts
+const applied = await applyCliUpdate({ asset, targetPath, backupPath })
+// …the new build turns out to be wrong. `backupSha256` is absent when there was
+// nothing to keep — a first install — and that is the case with nothing to roll
+// back to:
+if (applied.backupSha256) {
+  rollbackCliUpdate({ targetPath, backupPath, expectedSha256: applied.backupSha256 })
+}
+```
+
+The copy is taken between "the new bytes verified" and the replacement — earlier
+would preserve a binary about to be replaced by a download that then failed its
+digest, later has nothing left to copy — and it carries the target's file mode,
+because a backup that cannot be executed is not a way back. A first install has
+nothing to keep, which is not a failure.
+
+`expectedSha256` is required, not optional. A rollback that installs whatever
+happens to be at the backup path is a second install of an unverified binary,
+and the day it is used is the day nobody is in a position to check.
+
+### Two release tracks
+
+`assertCliPublishable` takes one manifest **or every manifest already
+published**:
+
+```ts
+assertCliPublishable([stableManifest, betaManifest], next)
+```
+
+With a single argument and two tracks the check is silently useless: `1.2.3`
+goes to beta from one commit and to stable from another, the function is called
+with the track being published and sees no conflict, and the person who
+installed the beta is told they are current forever. Nothing on their machine
+looks wrong.
+
+**The channel itself is not an argument of the framework, and will not become
+one.** The framework has no model of how your URLs are built and should not: an
+asset's address comes from the manifest, and the manifest's address belongs to
+your server. A channel is two documents at two addresses — which of them a build
+consults is your decision, and `assertCliPublishable` is told about all of them
+rather than taught the shape of any.
+
+## One operation per line — `createCliInvoker`
+
+The most common way an agent drives a CLI is not one command: it is a stream —
+a JSON line per operation, an answer per line — and a resumable batch of the
+same. The mechanics contain nothing product-specific, and until now the
+framework left the one piece that cannot be written outside it: running an
+already-parsed call.
+
+```ts
+import { createCliInvoker, defineCliStreamCommand, defineCliBatchCommand } from 'stitchkit/cli'
+
+const invoker = await createCliInvoker({ name: 'myapp', services })
+
+const outcome = await invoker.invoke('create_item', { title: 'hello', tags: ['a'] })
+// { ok: true, exitCode: 0, data: { … } }   — nothing written, nothing exited
+```
+
+`invoke` runs the same pipeline a typed command runs — the same validation, the
+same `lifecycle` gate, the same hooks — and returns the handler's validated
+output with **the exit code the printed path would give**, from the same table.
+`data` is typed `unknown`: the surface is resolved at run time from services and
+runtime tools, so there is no compile-time name to key a result type on. Narrow
+it with the contract's own output schema. That table used to
+live inside the function that prints, so the only way to learn a code was to
+print it.
+
+Without this, a stream loop had to re-spawn the binary per line: arguments
+serialised back into `--flag value` strings, nested objects pushed through
+`JSON.stringify` into one argv slot and parsed again on the other side, the
+result read back out of stdout text. Three conversions of data the framework was
+already holding, plus a process start measured at 0.15 s — thirty seconds for a
+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
+await createCli({
+  name: 'myapp', version, services,
+  commands: [
+    defineCliStreamCommand({ name: 'jsonl', invoker }),
+    defineCliBatchCommand({ name: 'batch', invoker, checkpointPath: '.myapp-batch.json' }),
+  ],
+})
+```
+
+They are factories, not framework-owned names. Reserving `jsonl` and `batch`
+would take two names out of a namespace that belongs to the application — one
+that already has a `batch` command would either fail at startup or find its own
+command silently shadowed — so you mount them under whatever you call them, like
+any other command of yours.
+
+Each line is `{ id, command, args }`; each answer is the invocation result plus
+that `id`. A line that is not JSON, or has no `id`, is **answered** and the
+stream continues: a stream that goes quiet on one line leaves its consumer
+unable to tell which request it lost. Answers go to stdout, one object per line,
+and nothing else does.
+
+### Resuming a batch
+
+The checkpoint records, per id, a digest of the line that produced the recorded
+answer, and is written after **every** line by atomic rename — a checkpoint that
+only survives a clean finish protects against exactly the case that does not
+happen.
+
+A re-run replays what already ran. A line whose content changed under the same
+id is **refused**: replaying it would report success for an operation nobody
+ran, and re-running it would repeat a paid call. Both answer a question nobody
+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
@@ -10453,7 +10764,7 @@ export const observability = createObservability({
     write,
     includePayload: false, // default: no Request.clone(), payload is null
     includeCancelled: false, // default: keep client closes in access logs only
-    filter: (event) => event.method !== 'GET',
+    filter: (event) => event.method !== 'GET', // see the note on jobs below
   },
   tools: {
     write,
@@ -10639,21 +10950,56 @@ queryable across all three:
 
 | Field | Notes |
 |-------|-------|
-| `source` | `http` \| `mcp` \| `agent` |
-| `method` / `path` | the verb + path, or `TOOL` + `/{source}/{tool}` |
+| `source` | `http` \| `mcp` \| `agent` \| `job` |
+| `kind` | `request` \| `job` — written on **every** row, so a filter never has to read it off an absent `method` |
+| `name` | what the work is, on a job (`agent-loop`, `broadcast-send`); absent on a request, which its method and path name |
+| `method` / `path` | the verb + path, or `TOOL` + `/{source}/{tool}` — **absent** on a job, which arrived over no transport |
 | `serviceName` / `action` | stable contract identity of the operation (→ ADR 0022) — from the contract, not parsed from `path`; set on every surface, present even on a pre-handler 400 |
 | `toolName` | tool calls only |
 | `httpMethod` | the contract verb on **tool** events (their `method` is `TOOL`) — filter reads vs writes across both surfaces with `(event.httpMethod ?? event.method) !== 'GET'` |
 | `dimensions` | app-defined domain dimensions (tenant / project / entity id) — see [request context](#request-context) |
 | `traceId` / `spanId` / `parentSpanId` | [W3C trace context](#trace-context) |
 | `outcome` | optional `'cancelled'` on explicitly enabled HTTP client-close rows; ordinary rows omit it |
-| `ok` / `statusCode` | legacy success bit plus real HTTP status, or `200`/`400` for a tool; an opted-in cancellation is `false` / `499` |
+| `ok` / `statusCode` | legacy success bit plus real HTTP status, or `200`/`400` for a tool; an opted-in cancellation is `false` / `499`. `statusCode` is **absent** on a job — it had no transport to have a status on, and inventing one would be the same defect as the `method: 'AGENT'` this replaced. A job's outcome is `ok`, plus `errorCode` when it failed |
 | `durationMs` / `startedAt` | timing |
 | `errorCode` / `errorMessage` / `errorDetail` | failures only — `errorDetail` carries the structure the message flattens (e.g. Zod issues) |
 | `payload` | sanitised tool arguments; HTTP is `null` unless request `includePayload` is enabled |
 | `resultSize` / `responseBytes` | result item count + serialised size |
 | `userId` / `ipAddress` / `userAgent` | identity |
 
+### Work that is not a request — `runUnitOfWork`
+
+An agent loop launched fire-and-forget, a scheduled broadcast, a scenario engine
+tick: each has a start, a duration and an outcome, and none of them arrived over
+a transport. Run one inside a context and it is audited like everything else:
+
+```ts
+await runUnitOfWork({ name: 'broadcast-send', observability }, async () => {
+  setRequestDimensions({ projectId })
+  await send()
+})
+```
+
+The row carries `kind: 'job'`, the `name`, the duration and the outcome, and
+carries **no** `method`, `path` or `statusCode`, because the work had none. That
+absence is the point. The alternative is what consuming code had to do before —
+write `method: 'AGENT'` into the field for verbs — and a row that names a verb
+nobody used is worse than a row that names none, because a filter reading
+`method !== 'GET'` counts it as a write and nothing looks wrong.
+
+Which is why **a filter on `method` needs a decision about jobs.** `auditChanges`
+makes it explicitly: a row with no verb is kept, because whether it changed
+anything cannot be answered from the row, and an audit that drops what it did not
+examine reports zero and looks exactly like a system in which nothing happened.
+A hand-written `event.method !== 'GET'` keeps jobs too (`undefined !== 'GET'`);
+`event.kind === 'request' && event.method !== 'GET'` is how you exclude them on
+purpose.
+
+Without an `observability` the work still runs inside a context, so trace ids,
+`setRequestDimensions` and the bounded logger behave — recording is a separate
+decision from having a context. `traceparent` continues the trace of whatever
+scheduled the work, instead of starting an unrelated one.
+
 ### Write the calls that changed something
 
 `auditChanges` is the filter most projects end up writing, shipped so they do not
@@ -12132,6 +12478,84 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## 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
+   not arrive over a transport now records their **absence** instead of inventing
+   values — a background loop used to write `method: 'AGENT'`, which is not a
+   verb. **Who must act:** anyone whose `RequestEventSinkConfig.write` puts these
+   into NOT NULL columns, or whose filter reads `event.method`.
+
+   ```ts
+   // before
+   write: (event) => db.audit.create({ data: { method: event.method, path: event.path, status: event.statusCode } })
+   // after — a job has none of the three; `kind` says which kind of row it is
+   write: (event) => db.audit.create({ data: {
+     kind: event.kind,
+     name: event.name ?? null,
+     method: event.method ?? null,
+     path: event.path ?? null,
+     status: event.statusCode ?? null,
+   } })
+   ```
+
+   A filter written as `event.method !== 'GET'` keeps jobs (`undefined !== 'GET'`),
+   which is usually what you want. To exclude them deliberately:
+   `event.kind === 'request' && event.method !== 'GET'`.
+
+2. **`applyCliUpdate` needs the manifest when given a trust root.** The signature
+   covers the manifest and every asset digest together, so an asset alone cannot
+   be verified. **Who must act:** only callers adopting signature verification;
+   the unsigned call is unchanged.
+
+   ```ts
+   // before
+   await applyCliUpdate({ asset })
+   // after
+   await applyCliUpdate({ asset, manifest: check.manifest, trust })
+   ```
+
+3. **An MCP continuation minted before this release is refused once.** The signed
+   round state now carries a fingerprint of the question plan, checked on every
+   round, so a plan that moved between rounds is a refusal rather than a
+   different question asked under the previous one's key. A conversation already
+   in flight at deploy time has no fingerprint and gets
+   `INVALID_REQUEST_STATE`; the host re-asks and the second attempt succeeds.
+   **Who must act:** nobody — but expect a small number of these in the minutes
+   after a deploy, and do not read them as tampering.
+
 ## Released migration: 0.91.0
 
 1. `STITCH_ERROR_STATUS` gained `NOT_IMPLEMENTED` (501). An **exhaustive** error
@@ -15832,6 +16256,10 @@ from the root `stitchkit`.
 | `HandlerContext` | _type_ | the typed context seen by a handler, including optional typed `mcp` metadata |
 | `McpCallContext` | _type_ | validated metadata for the active managed MCP call (`era`, method, tool, client and multi-round fields) |
 | `McpClientInfo` | _type_ | self-reported MCP host name/version; attribution only, never application identity |
+| `McpInputRequiredCall` | _type_ | the parsed `params` / `input` an elicitation resolver chooses its questions from |
+| `McpInputRequiredResolver` | _type_ | `mcp.inputRequired` as a function of the parsed arguments — returns the rounds for this call, or none |
+| `McpProgressUpdate` | _type_ | one mid-call progress update — `message`, and `progress`/`total` when the operation knows a scale |
+| `McpReportProgress` | _type_ | `ctx.reportProgress` — sends one update to the host that asked for progress; a no-op when none did, and never throws |
 | `McpRoundOutcome` | _type_ | managed multi-round attempt outcome |
 | `EndpointHandlerContext` | _type_ | one endpoint handler's fully inferred params, input, files and runtime context |
 | `EndpointFn` | _type_ | the call signature of one client method |
@@ -16949,6 +17377,8 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `DEFAULT_REDACT_PATHS` | constant | baseline credential/token paths added to the sanitizer's sensitive-key policy |
 | `BoundedLoggerBounds` / `BoundedLoggerOptions` | _type_ | per-value and total record ceilings (`stringLengthByKey` raises the string bound for named keys such as `stack`) plus sink/redaction configuration |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink; opt-in HTTP cancellation rows carry `outcome: 'cancelled'` |
+| `runUnitOfWork` / `RunUnitOfWorkOptions` | function / _type_ | run work that did not arrive over a transport — an agent loop, a scheduled broadcast — inside one context, with the same completion record a request gets |
+| `RequestContextKind` | _type_ | `'request'` \| `'job'` — what the row describes, written on every event so a filter never has to read it off an absent `method` |
 | `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
 | `Observability` | _type_ | `{ request?, toolCall, getStatus(), flush(bound?): Promise<boolean>, close(bound?) }` with bounded sink lifecycle |
 | `ObservabilityDrainBound` | _type_ | `timeoutMs` and/or `signal` limiting how long `flush`/`close` wait; the wait ends, outstanding writes do not |
@@ -17391,6 +17821,8 @@ 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 |
+| `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 |
@@ -17690,7 +18122,11 @@ SDK nor the `ai` peer.
 | `renderCliInstaller` | function | generate the one-line installer from a build manifest, with the URL and digest substituted — [guide](../guide/cli.md#distribution-and-self-update) |
 | `checkCliUpdate` | function | bounded, interval-limited, never-throwing check for a newer published build |
 | `applyCliUpdate` | function | download, verify the decompressed digest and replace the binary by rename |
-| `assertCliPublishable` | function | refuse republishing one version from a different commit |
+| `assertCliPublishable` | function | refuse republishing one version from a different commit — takes one manifest or every manifest already published, because the promise a version makes does not stop at a channel boundary |
+| `rollbackCliUpdate` / `CliRollbackConfig` / `RolledBackCliUpdate` | function / _types_ | put the kept previous build back, digest-checked first and written by the same atomic rename the update uses |
+| `signCliManifest` / `verifyCliManifest` / `cliManifestSigningPayload` | function | Ed25519 over `{name, version, commit, builtAt, assets[]}` — every asset's digest included, so the chain closes on the file that executes |
+| `cliSignatureAccepted` / `CliSignatureVerdict` | function / _type_ | `valid` \| `unenforced` \| `missing` \| `unknown-key` \| `invalid`; `unenforced` keeps an unpinned build updating while making the absence of a check visible |
+| `CliTrustRoot` / `CliSigningKey` / `CliBuildSignature` / `CliBuildSignatureSchema` | _types_ / schema | the keys a build trusts, by id, and the detached signature a manifest carries |
 | `selectCliBuildAsset` | function | the asset for one target, or `undefined` |
 | `currentCliBuildTarget` | function | `{ platform, arch }` of the running process |
 | `formatCliBuildStamp` | function | one line saying what the running build is |
@@ -17709,6 +18145,11 @@ SDK nor the `ai` peer.
 | `CliArgvRoute` | _type_ | `{ command, commandArgv, topLevelHelp, version, error? }` returned by `routeCliArgv` |
 | `pollUntilDone` | function | the generic `--wait` poller (advanced) |
 | `emitResult` | function | write a pretty or compact `ToolResult` record to stdout/stderr + exit code (advanced) |
+| `cliExitCode` | function | the exit code a result earns, from the same table, without writing anything — so an in-process run and the printed path cannot disagree |
+| `createCliInvoker` / `CliInvoker` / `CliInvokerConfig` / `CliInvocationResult` / `CliInvokerCommand` / `cliInvocationResult` | function / _types_ | compile the managed surface once and run parsed calls against it in process — no argv round-trip, no child process, no writing |
+| `defineCliStreamCommand` / `CliStreamCommandConfig` / `CliStreamAnswer` / `CliStreamHooks` / `runCliStream` | function / _types_ | one operation per JSON line of stdin, answered with the same `id`; a bad line answers and the stream continues |
+| `defineCliBatchCommand` / `CliBatchCommandConfig` | function / _type_ | the same loop, resumable: a recorded line replays, a line whose content changed under the same id is refused |
+| `readCliCheckpoint` / `writeCliCheckpoint` / `CliCheckpoint` / `CliCheckpointEntry` | function / _types_ | the batch's record — id plus a digest of the line, written by atomic rename after every line |
 | `DEFAULT_EXIT_CODES` | const | the default `ToolResult.code` → exit-code map |
 | `CliConfig` | _type_ | config for `createCli`; `defaultCommand`, `globalOptions`, `optionAliases` and `positionals` define the shared command presentation policy |
 | `CliPresentationPolicyConfig` | _type_ | shared command presentation-policy subset of `CliConfig` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.91.2",
+  "version": "0.93.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",