@cyanheads/mcp-ts-core 0.13.9 → 0.13.10

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.13.9
+**Version:** 0.13.10
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.1.0 (protocol revisions 2026-07-28 and 2025-*)
 **Zod:** ^4.6.5
@@ -45,7 +45,7 @@ Both paths share the same public API. Init copies starter `package.json`, config
 
 | Subpath | Key Exports | Purpose |
 |:--------|:------------|:--------|
-| `@cyanheads/mcp-ts-core` | `createApp`, `tool`, `resource`, `prompt`, `appTool`, `appResource`, `APP_RESOURCE_MIME_TYPE`, `headerParam`, `Context`, `createFail`, `createRecoveryFor`, `TypedFail`, `TypedRecoveryFor`, `ReasonOf`, `HandlerContext`, `Enrich`, `EnrichHelpers`, `TypedEnrich`, `ContentCollect`, `ContentBlock`, `z`, `inputRequired`, `completable`, `isCompletable`, `CompleteCallback`, `CompleteResourceTemplateCallback`, `CacheHint`, `CacheHints`, `CacheScope`, `SessionMode`, `ResolvedSessionMode` | Main entry point |
+| `@cyanheads/mcp-ts-core` | `createApp`, `tool`, `resource`, `prompt`, `appTool`, `appResource`, `APP_RESOURCE_MIME_TYPE`, `headerParam`, `Context`, `ClientCapabilities`, `createFail`, `createRecoveryFor`, `TypedFail`, `TypedRecoveryFor`, `ReasonOf`, `HandlerContext`, `Enrich`, `EnrichHelpers`, `TypedEnrich`, `ContentCollect`, `ContentBlock`, `z`, `inputRequired`, `completable`, `isCompletable`, `CompleteCallback`, `CompleteResourceTemplateCallback`, `CacheHint`, `CacheHints`, `CacheScope`, `SessionMode`, `ResolvedSessionMode` | Main entry point |
 | `/worker` | `createWorkerHandler`, `CloudflareBindings` | Cloudflare Workers entry |
 | `/tools` | `ToolDefinition`, `AnyToolDefinition`, `ToolAnnotations` | Tool definition types |
 | `/resources` | `ResourceDefinition`, `AnyResourceDefinition` | Resource definition types |
@@ -300,10 +300,11 @@ interface Context {
   readonly traceId?: string;
   readonly spanId?: string;
   readonly auth?: AuthContext;
+  readonly clientCapabilities: ClientCapabilities | undefined; // what the client declared; undefined when no view (2025-era stateless HTTP)
   readonly log: ContextLogger;                // auto-correlated: requestId, traceId, tenantId
   readonly state: ContextState;               // tenant-scoped KV storage
   readonly requestInput: RequestInputFn;      // (spec, options?) => never — suspends and asks the caller for input
-  readonly inputs: ContextInputs;             // reader over a retried request's responses
+  readonly inputs: ContextInputs;             // the request's responses, limited to what the client declared
   readonly notifyPromptListChanged?: (() => void) | undefined;     // prompt list changed
   readonly notifyResourceListChanged?: (() => void) | undefined;   // resource list changed
   readonly notifyResourceUpdated?: ((uri: string) => void) | undefined; // resource content changed
@@ -312,7 +313,7 @@ interface Context {
   readonly uri?: URL;                         // present for resource handlers
   readonly content: ContentCollect;           // media blocks → prepended to content[]; never in structuredContent
   readonly enrich: Enrich;                    // success-path agent context → structuredContent + content[]; typed on HandlerContext<R, E>
-  recoveryFor(reason: string): { recovery: { hint: string } } | Record<string, never>; // opt-in contract resolver
+  recoveryFor(reason: string): { recovery: { hint: string } } | Record<string, never>; // a declared entry's hint, in wire shape
 }
 ```
 
@@ -367,11 +368,33 @@ useFormat(answer.format);
 cancelled prompt is terminal, not a round to retry. `inputRequired.elicitUrl({ message, url })`
 hands the user an external link instead of a form.
 
+A client can send responses on a call nothing asked for, so only what it declared reaches
+`ctx.inputs`, at the mode level the request would need: an elicit result needs `elicitation` —
+`elicitation.form` when it carries `content` — a sampling result `sampling` (`sampling.tools` when it
+holds a tool block), a roots result `roots`, and a request with no capability view gets none.
+`ctx.clientCapabilities` — the SDK-parsed `initialize` value on 2025-era connections (a bare
+`elicitation: {}` reads back as `{ elicitation: { form: {} } }`), the request's envelope as sent on
+2026-07-28 — decides whether to *ask* for optional context (request roots only when `roots` is
+declared, else fall through); it is never a reason to skip a consent prompt.
+
 A 2025-era client that declared no matching capability is refused as `client_capability_missing`,
 with a hint that ends at reconnecting. When the tool's own arguments can stand in for the answer,
 say so per call — `ctx.requestInput(spec, { fallbackHint: 'Or call again with noun supplied.' })` —
 and the sentence is appended to that hint. A consent gate passes none: it has no such field.
 
+**Consent gates redeem a server record.** A capable client can still pre-answer, and any
+`requestState` can be replayed within its lifetime, so a destructive handler first redeems (reads and
+deletes) a `ctx.state` record `{ operation, clientId, subject, target, contentHash }` stored under a
+random id — the id is all `requestState` carries — and asks again on an unknown, used, or expired id,
+or when any field differs from this call. Carrying the target in `requestState` and comparing on
+re-entry is replayable. Redeeming stops a sequential replay, not concurrent retries: until an atomic
+`ctx.state.take` exists (#593), an action that must not repeat is made idempotent per record. The
+record's storage is shared by every instance a 2026-07-28 retry can reach — `filesystem`, `supabase`,
+or `cloudflare-d1`, never `cloudflare-kv`. `MCP_REQUEST_STATE_KEY` (≥ 32 bytes, the same on every
+instance) opts into sealing: the framework signs the string a handler returns, the SDK rejects any
+other as `-32602` `invalid_request_state` before the handler runs, and `ctx.inputs.state()` still
+returns the original string. See `api-context` for the full pattern.
+
 ### `ctx.content`
 
 Accumulates non-text content blocks — image/audio bytes, embedded resources, resource links — onto the response: `ctx.content.image(data, mimeType)`, `ctx.content.audio(data, mimeType)`, or `ctx.content(block)` for a raw `ContentBlock`. Blocks are prepended to `content[]` after `format()` runs and never enter `structuredContent`, so a handler can emit media for the calling model without the base64 duplicating into typed output. Always present (no-op when unused); callable from handler and service layer.
@@ -382,7 +405,7 @@ See `api-context` skill for full details.
 
 ## Error Handling
 
-**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` to `tool()` / `resource()`. Handler gets `ctx.fail(reason, msg?, data?)` typed against the reason union — typos fail at compile time. Runtime auto-populates `data.reason` for observability; linter enforces conformance against the handler body. `recovery` is required (≥5 words, lint-validated) — the single source of truth for the wire hint. Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire (framework mirrors `data.recovery.hint` into `content[]` text); override with explicit `{ recovery: { hint: '...' } }` when runtime context matters. Optional `severity` (`debug`/`info`/`notice`/`warning`) logs a modeled outcome below `error` — tools only, logging only: the wire envelope, the span status, and the `mcp.tool.*` metrics are untouched. Optional `thrownBy: 'service'` marks an entry the service layer produces, so `error-contract-unthrown` skips it while still checking the handler's own reasons — lint-only metadata, nothing at runtime reads it.
+**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` to `tool()` / `resource()`. Handler gets `ctx.fail(reason, msg?, data?)` typed against the reason union — typos fail at compile time. Runtime auto-populates `data.reason` for observability; linter enforces conformance against the handler body. `recovery` is required (≥5 words, lint-validated) — the wire hint for its reason: when a failure whose `data.reason` names the entry reaches the tool or resource factory without `data.recovery`, the framework fills `data.recovery.hint` from it — a bare `ctx.fail('reason')` and a service throw carrying `{ reason }` alike, matched on the reason alone — and mirrors it into `content[]` text. Override with explicit `{ recovery: { hint: '...' } }` when runtime context matters; a throw-site `recovery` always wins, and the thrown `McpError` itself is never changed. Optional `severity` (`debug`/`info`/`notice`/`warning`) logs a modeled outcome below `error` — tools only, logging only: the wire envelope, the span status, and the `mcp.tool.*` metrics are untouched. The framework's own `invalid_arguments` and `client_capability_missing` refusals log at `notice` unless an entry naming them declares otherwise. Optional `thrownBy: 'service'` marks an entry the service layer produces, so `error-contract-unthrown` skips it while still checking the handler's own reasons — lint-only metadata, nothing at runtime reads it.
 
 ```ts
 errors: [
@@ -394,8 +417,8 @@ errors: [
     recovery: 'Wait 30 seconds before retrying or reduce batch size.' },
 ],
 async handler(input, ctx) {
-  // Static recovery — pulled from the contract via ctx.recoveryFor.
-  if (queue.full()) throw ctx.fail('queue_full', undefined, { ...ctx.recoveryFor('queue_full') });
+  // Static recovery — the framework fills the contract's hint onto the wire.
+  if (queue.full()) throw ctx.fail('queue_full');
   // Dynamic recovery — interpolate runtime context, override the contract default.
   if (!matched) throw ctx.fail('no_match', `No data for ${input.pmids.length} PMIDs`, {
     pmids: input.pmids,
@@ -404,7 +427,7 @@ async handler(input, ctx) {
 }
 ```
 
-**`ctx.recoveryFor(reason)`** returns `{}` when no contract exists (spread-safe). Typed against the declared reason union on `HandlerContext<R>`. Works in services: `throw validationError(msg, { reason: 'X', ...ctx.recoveryFor('X') })`. Opt-in — author spreads explicitly.
+**`ctx.recoveryFor(reason)`** returns the entry's hint in wire shape, `{}` when no contract exists (spread-safe). Typed against the declared reason union on `HandlerContext<R>`. Not needed to put a declared hint on the wire — the fill does that — only when the hint must ride the thrown error itself, as in a test of the handler's own throw.
 
 **Contracts are inline, per-tool.** Don't extract shared `errors[]` constants — locality is the point, and dynamic `recovery` hints need tool-specific context. Declare domain-specific failures only; **baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) are auto-allowed by conformance lint. The lint scans handler source only — service-layer throws still reach clients via auto-classification.
 
@@ -422,9 +445,9 @@ For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { se
 
 **Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: request signal already aborted (→ `RequestCancelled`, outranking the thrown value's own code, `McpError` included) → `McpError` code (preserved as-is) → SDK `ConnectionClosed` (→ `RequestCancelled`) → engine resource-limit `RangeError` by whole message — stack overflow, maximum string size (→ `InternalError`) → JS constructor name (`SyntaxError` → `ValidationError`; `TypeError` is excluded) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name (→ `Timeout`) → `InternalError` fallback. A result that breaks the definition's own `output` or `enrichment` schema fails as `InternalError` naming that contract, not `ValidationError`.
 
-**Error-path parity.** Tool errors: `content[]` carries `Error: <message>`, then `Recovery: <hint>` when the hint says something the message does not already contain, then a closing `(reason … · not retryable)` for whichever of `data.reason` / `data.retryable` is present; the numeric code and `data.issues` stay JSON-only. `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope. An argument rejection is one of them: `-32602` with `data.issues`, plus `data.reason: 'invalid_arguments'` and a hint synthesized from the issues and the root schema — never a tool-declared `reason`, since the handler never ran. When pre-validation rewrote or dropped a key the caller wrote, `data.input` (`{ aliased: [{ alias, target }], ignored }`) names it and the hint closes with `Validated … as ….` / `Dropped undeclared key ….`; an ignore-list drop is never reported. `client_capability_missing` is the second framework-owned reason: a `ctx.requestInput` return a 2025-era connection cannot serve is refused before any wire traffic as `-32600` carrying that reason and a hint naming the capability.
+**Error-path parity.** Tool errors: `content[]` carries `Error: <message>`, then `Recovery: <hint>` when the hint says something the message does not already contain, then a closing `(reason … · not retryable · request <id>)` for whichever of `data.reason` / `data.retryable` / `data.requestId` is present; the numeric code and `data.issues` stay JSON-only. `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope. An argument rejection is one of them: `-32602` with `data.issues`, plus `data.reason: 'invalid_arguments'` and a hint synthesized from the issues and the root schema — never a tool-declared `reason`, since the handler never ran. When pre-validation rewrote or dropped a key the caller wrote, `data.input` (`{ aliased: [{ alias, target }], ignored }`) names it and the hint closes with `Validated … as ….` / `Dropped undeclared key ….`; an ignore-list drop is never reported. `client_capability_missing` is the second framework-owned reason: a `ctx.requestInput` return a 2025-era connection cannot serve is refused before any wire traffic as `-32600` carrying that reason and a hint naming the capability. **`data.requestId`** is set on every error envelope the framework builds — tool results, resource reads, prompts, `httpErrorHandler`'s JSON-RPC errors — equal to the `requestId` of that call's log records: a generated token, or the client's JSON-RPC id when it is a string (`httpErrorHandler` always generates its own). A resource read refused before it is measured (auth, `params`) carries an id no record shares. It replaces a thrown `data.requestId`, is never added to the thrown `McpError`, and is left off a resource `-32602` whose `data` is exactly `{ uri }` and off `runToolContract` results.
 
-**Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`, `error-contract-unthrown` (a declared reason no literal `ctx.fail`/`ctx.recoveryFor` in the handler names, unless marked `thrownBy: 'service'`), `error-contract-recovery-unforwarded` (a `ctx.fail` site carrying neither `ctx.recoveryFor('<reason>')` nor its own `recovery` key, so the declared hint reaches neither client surface). See `api-linter` skill.
+**Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`, `error-contract-unthrown` (a declared reason no literal `ctx.fail`/`ctx.recoveryFor` in the handler names, unless marked `thrownBy: 'service'`). See `api-linter` skill.
 
 See `api-errors` skill for the full pattern-matching table, error code reference, and detailed examples.
 
@@ -458,7 +481,7 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod. Precedence: `createApp()
 | Category | Key Variables |
 |:---------|:-------------|
 | Transport | `MCP_TRANSPORT_TYPE` (`stdio`\|`http`), `MCP_HTTP_PORT`, `MCP_HTTP_HOST`, `MCP_HTTP_ENDPOINT_PATH` |
-| Auth | `MCP_AUTH_MODE`, `MCP_AUTH_SECRET_KEY`, `MCP_AUTH_DISABLE_SCOPE_CHECKS`, `OAUTH_*` |
+| Auth | `MCP_AUTH_MODE`, `MCP_AUTH_SECRET_KEY`, `MCP_AUTH_DISABLE_SCOPE_CHECKS`, `OAUTH_*`, `MCP_REQUEST_STATE_KEY` (opt-in `requestState` sealing) |
 | Storage | `STORAGE_PROVIDER_TYPE` (`in-memory`\|`filesystem`\|`supabase`\|`cloudflare-r2`\|`cloudflare-kv`\|`cloudflare-d1`) |
 | LLM | `OPENROUTER_API_KEY`, `OPENROUTER_APP_URL/NAME`, `LLM_DEFAULT_*` |
 | Telemetry | `OTEL_ENABLED`, `OTEL_SERVICE_NAME/VERSION`, `OTEL_EXPORTER_OTLP_*` |
@@ -485,7 +508,7 @@ describe('myTool', () => {
 });
 ```
 
-**`createMockContext` options:** `createMockContext()` (state included), `{ tenantId: 'test-tenant' }` (explicit tenant; defaults to `'default'`, as stdio resolves it), `{ errors: myTool.errors }` (typed `ctx.fail`), `{ inputResponses }` / `{ requestState }` (seed `ctx.inputs` to drive a multi-round-trip handler's second round directly), plus `auth`, `sessionId`, `signal`, `requestId`, `uri`, and the four `notify*` callbacks.
+**`createMockContext` options:** `createMockContext()` (state included), `{ tenantId: 'test-tenant' }` (explicit tenant; defaults to `'default'`, as stdio resolves it), `{ errors: myTool.errors }` (typed `ctx.fail`), `{ inputResponses }` / `{ requestState }` (seed `ctx.inputs` to drive a multi-round-trip handler's second round directly), `{ clientCapabilities }` (seeds `ctx.clientCapabilities` and filters the seeded responses to the declared kinds, as production does — omitted, nothing is filtered), plus `auth`, `sessionId`, `signal`, `requestId`, `uri`, and the four `notify*` callbacks.
 
 **`ctx.state` in tests is the production path.** The mock backs it with a real `StorageService` over an `InMemoryProvider`, so key validation (`[a-zA-Z0-9_.\-/]+` — colons rejected), the JSON round-trip of every value, and TTL expiry behave exactly as they do in a deployment. Passing `errors` narrows the return type to `HandlerContext<ReasonOf<…>>`, which is what a definition declaring a contract types its handler's `ctx` as — so `definition.handler(input, ctx)` typechecks.
 
@@ -495,7 +518,7 @@ describe('myTool', () => {
 
 **Fixture-based tests:** `mcpTest` from `/testing/vitest` (optional peer `vitest`) extends Vitest's `test` with per-test fixtures: `ctx` (fresh mock context), `session` (session-bound context), `fetchMock` (strict fetch fake, installed/restored around the test), and `storage` (fresh in-memory `StorageService`). Override fixtures via `.extend` with the function form only — a bare value would share one mutable context across every test in the file.
 
-**Tool contracts:** `runToolContract(definition, input)` from `/testing` validates input/output, invokes the handler, formats content, and returns production-shaped success/error surfaces without transport auth or telemetry. `toolContractSuite(definition, { success, errors })` from `/testing/vitest` registers reusable schema/handler/error-envelope conformance cases for a server's own tool definitions.
+**Tool contracts:** `runToolContract(definition, input)` from `/testing` validates input/output, invokes the handler, formats content, and returns production-shaped success/error surfaces — the declared `recovery` fill included — without transport auth, telemetry, or `data.requestId`. `toolContractSuite(definition, { success, errors })` from `/testing/vitest` registers reusable schema/handler/error-envelope conformance cases for a server's own tool definitions.
 
 **Fuzz testing:** `fuzzTool`/`fuzzResource`/`fuzzPrompt` from `/testing/fuzz` generate valid and adversarial inputs from Zod schemas via `fast-check`, then assert handler invariants (no crashes, no prototype pollution, no stack trace leaks). Returns a `FuzzReport` for custom assertions.
 

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.13.9
+**Version:** 0.13.10
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.1.0 (protocol revisions 2026-07-28 and 2025-*)
 **Zod:** ^4.6.5
@@ -45,7 +45,7 @@ Both paths share the same public API. Init copies starter `package.json`, config
 
 | Subpath | Key Exports | Purpose |
 |:--------|:------------|:--------|
-| `@cyanheads/mcp-ts-core` | `createApp`, `tool`, `resource`, `prompt`, `appTool`, `appResource`, `APP_RESOURCE_MIME_TYPE`, `headerParam`, `Context`, `createFail`, `createRecoveryFor`, `TypedFail`, `TypedRecoveryFor`, `ReasonOf`, `HandlerContext`, `Enrich`, `EnrichHelpers`, `TypedEnrich`, `ContentCollect`, `ContentBlock`, `z`, `inputRequired`, `completable`, `isCompletable`, `CompleteCallback`, `CompleteResourceTemplateCallback`, `CacheHint`, `CacheHints`, `CacheScope`, `SessionMode`, `ResolvedSessionMode` | Main entry point |
+| `@cyanheads/mcp-ts-core` | `createApp`, `tool`, `resource`, `prompt`, `appTool`, `appResource`, `APP_RESOURCE_MIME_TYPE`, `headerParam`, `Context`, `ClientCapabilities`, `createFail`, `createRecoveryFor`, `TypedFail`, `TypedRecoveryFor`, `ReasonOf`, `HandlerContext`, `Enrich`, `EnrichHelpers`, `TypedEnrich`, `ContentCollect`, `ContentBlock`, `z`, `inputRequired`, `completable`, `isCompletable`, `CompleteCallback`, `CompleteResourceTemplateCallback`, `CacheHint`, `CacheHints`, `CacheScope`, `SessionMode`, `ResolvedSessionMode` | Main entry point |
 | `/worker` | `createWorkerHandler`, `CloudflareBindings` | Cloudflare Workers entry |
 | `/tools` | `ToolDefinition`, `AnyToolDefinition`, `ToolAnnotations` | Tool definition types |
 | `/resources` | `ResourceDefinition`, `AnyResourceDefinition` | Resource definition types |
@@ -300,10 +300,11 @@ interface Context {
   readonly traceId?: string;
   readonly spanId?: string;
   readonly auth?: AuthContext;
+  readonly clientCapabilities: ClientCapabilities | undefined; // what the client declared; undefined when no view (2025-era stateless HTTP)
   readonly log: ContextLogger;                // auto-correlated: requestId, traceId, tenantId
   readonly state: ContextState;               // tenant-scoped KV storage
   readonly requestInput: RequestInputFn;      // (spec, options?) => never — suspends and asks the caller for input
-  readonly inputs: ContextInputs;             // reader over a retried request's responses
+  readonly inputs: ContextInputs;             // the request's responses, limited to what the client declared
   readonly notifyPromptListChanged?: (() => void) | undefined;     // prompt list changed
   readonly notifyResourceListChanged?: (() => void) | undefined;   // resource list changed
   readonly notifyResourceUpdated?: ((uri: string) => void) | undefined; // resource content changed
@@ -312,7 +313,7 @@ interface Context {
   readonly uri?: URL;                         // present for resource handlers
   readonly content: ContentCollect;           // media blocks → prepended to content[]; never in structuredContent
   readonly enrich: Enrich;                    // success-path agent context → structuredContent + content[]; typed on HandlerContext<R, E>
-  recoveryFor(reason: string): { recovery: { hint: string } } | Record<string, never>; // opt-in contract resolver
+  recoveryFor(reason: string): { recovery: { hint: string } } | Record<string, never>; // a declared entry's hint, in wire shape
 }
 ```
 
@@ -367,11 +368,33 @@ useFormat(answer.format);
 cancelled prompt is terminal, not a round to retry. `inputRequired.elicitUrl({ message, url })`
 hands the user an external link instead of a form.
 
+A client can send responses on a call nothing asked for, so only what it declared reaches
+`ctx.inputs`, at the mode level the request would need: an elicit result needs `elicitation` —
+`elicitation.form` when it carries `content` — a sampling result `sampling` (`sampling.tools` when it
+holds a tool block), a roots result `roots`, and a request with no capability view gets none.
+`ctx.clientCapabilities` — the SDK-parsed `initialize` value on 2025-era connections (a bare
+`elicitation: {}` reads back as `{ elicitation: { form: {} } }`), the request's envelope as sent on
+2026-07-28 — decides whether to *ask* for optional context (request roots only when `roots` is
+declared, else fall through); it is never a reason to skip a consent prompt.
+
 A 2025-era client that declared no matching capability is refused as `client_capability_missing`,
 with a hint that ends at reconnecting. When the tool's own arguments can stand in for the answer,
 say so per call — `ctx.requestInput(spec, { fallbackHint: 'Or call again with noun supplied.' })` —
 and the sentence is appended to that hint. A consent gate passes none: it has no such field.
 
+**Consent gates redeem a server record.** A capable client can still pre-answer, and any
+`requestState` can be replayed within its lifetime, so a destructive handler first redeems (reads and
+deletes) a `ctx.state` record `{ operation, clientId, subject, target, contentHash }` stored under a
+random id — the id is all `requestState` carries — and asks again on an unknown, used, or expired id,
+or when any field differs from this call. Carrying the target in `requestState` and comparing on
+re-entry is replayable. Redeeming stops a sequential replay, not concurrent retries: until an atomic
+`ctx.state.take` exists (#593), an action that must not repeat is made idempotent per record. The
+record's storage is shared by every instance a 2026-07-28 retry can reach — `filesystem`, `supabase`,
+or `cloudflare-d1`, never `cloudflare-kv`. `MCP_REQUEST_STATE_KEY` (≥ 32 bytes, the same on every
+instance) opts into sealing: the framework signs the string a handler returns, the SDK rejects any
+other as `-32602` `invalid_request_state` before the handler runs, and `ctx.inputs.state()` still
+returns the original string. See `api-context` for the full pattern.
+
 ### `ctx.content`
 
 Accumulates non-text content blocks — image/audio bytes, embedded resources, resource links — onto the response: `ctx.content.image(data, mimeType)`, `ctx.content.audio(data, mimeType)`, or `ctx.content(block)` for a raw `ContentBlock`. Blocks are prepended to `content[]` after `format()` runs and never enter `structuredContent`, so a handler can emit media for the calling model without the base64 duplicating into typed output. Always present (no-op when unused); callable from handler and service layer.
@@ -382,7 +405,7 @@ See `api-context` skill for full details.
 
 ## Error Handling
 
-**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` to `tool()` / `resource()`. Handler gets `ctx.fail(reason, msg?, data?)` typed against the reason union — typos fail at compile time. Runtime auto-populates `data.reason` for observability; linter enforces conformance against the handler body. `recovery` is required (≥5 words, lint-validated) — the single source of truth for the wire hint. Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire (framework mirrors `data.recovery.hint` into `content[]` text); override with explicit `{ recovery: { hint: '...' } }` when runtime context matters. Optional `severity` (`debug`/`info`/`notice`/`warning`) logs a modeled outcome below `error` — tools only, logging only: the wire envelope, the span status, and the `mcp.tool.*` metrics are untouched. Optional `thrownBy: 'service'` marks an entry the service layer produces, so `error-contract-unthrown` skips it while still checking the handler's own reasons — lint-only metadata, nothing at runtime reads it.
+**Recommended path: declare a typed error contract.** Add `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` to `tool()` / `resource()`. Handler gets `ctx.fail(reason, msg?, data?)` typed against the reason union — typos fail at compile time. Runtime auto-populates `data.reason` for observability; linter enforces conformance against the handler body. `recovery` is required (≥5 words, lint-validated) — the wire hint for its reason: when a failure whose `data.reason` names the entry reaches the tool or resource factory without `data.recovery`, the framework fills `data.recovery.hint` from it — a bare `ctx.fail('reason')` and a service throw carrying `{ reason }` alike, matched on the reason alone — and mirrors it into `content[]` text. Override with explicit `{ recovery: { hint: '...' } }` when runtime context matters; a throw-site `recovery` always wins, and the thrown `McpError` itself is never changed. Optional `severity` (`debug`/`info`/`notice`/`warning`) logs a modeled outcome below `error` — tools only, logging only: the wire envelope, the span status, and the `mcp.tool.*` metrics are untouched. The framework's own `invalid_arguments` and `client_capability_missing` refusals log at `notice` unless an entry naming them declares otherwise. Optional `thrownBy: 'service'` marks an entry the service layer produces, so `error-contract-unthrown` skips it while still checking the handler's own reasons — lint-only metadata, nothing at runtime reads it.
 
 ```ts
 errors: [
@@ -394,8 +417,8 @@ errors: [
     recovery: 'Wait 30 seconds before retrying or reduce batch size.' },
 ],
 async handler(input, ctx) {
-  // Static recovery — pulled from the contract via ctx.recoveryFor.
-  if (queue.full()) throw ctx.fail('queue_full', undefined, { ...ctx.recoveryFor('queue_full') });
+  // Static recovery — the framework fills the contract's hint onto the wire.
+  if (queue.full()) throw ctx.fail('queue_full');
   // Dynamic recovery — interpolate runtime context, override the contract default.
   if (!matched) throw ctx.fail('no_match', `No data for ${input.pmids.length} PMIDs`, {
     pmids: input.pmids,
@@ -404,7 +427,7 @@ async handler(input, ctx) {
 }
 ```
 
-**`ctx.recoveryFor(reason)`** returns `{}` when no contract exists (spread-safe). Typed against the declared reason union on `HandlerContext<R>`. Works in services: `throw validationError(msg, { reason: 'X', ...ctx.recoveryFor('X') })`. Opt-in — author spreads explicitly.
+**`ctx.recoveryFor(reason)`** returns the entry's hint in wire shape, `{}` when no contract exists (spread-safe). Typed against the declared reason union on `HandlerContext<R>`. Not needed to put a declared hint on the wire — the fill does that — only when the hint must ride the thrown error itself, as in a test of the handler's own throw.
 
 **Contracts are inline, per-tool.** Don't extract shared `errors[]` constants — locality is the point, and dynamic `recovery` hints need tool-specific context. Declare domain-specific failures only; **baseline codes** (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) are auto-allowed by conformance lint. The lint scans handler source only — service-layer throws still reach clients via auto-classification.
 
@@ -422,9 +445,9 @@ For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { se
 
 **Auto-classification.** Plain `Error`, `ZodError`, and any other thrown value are caught and classified automatically. Resolution order: request signal already aborted (→ `RequestCancelled`, outranking the thrown value's own code, `McpError` included) → `McpError` code (preserved as-is) → SDK `ConnectionClosed` (→ `RequestCancelled`) → engine resource-limit `RangeError` by whole message — stack overflow, maximum string size (→ `InternalError`) → JS constructor name (`SyntaxError` → `ValidationError`; `TypeError` is excluded) → provider patterns (HTTP status codes, AWS errors, DB errors) → common message patterns → `AbortError` name (→ `Timeout`) → `InternalError` fallback. A result that breaks the definition's own `output` or `enrichment` schema fails as `InternalError` naming that contract, not `ValidationError`.
 
-**Error-path parity.** Tool errors: `content[]` carries `Error: <message>`, then `Recovery: <hint>` when the hint says something the message does not already contain, then a closing `(reason … · not retryable)` for whichever of `data.reason` / `data.retryable` is present; the numeric code and `data.issues` stay JSON-only. `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope. An argument rejection is one of them: `-32602` with `data.issues`, plus `data.reason: 'invalid_arguments'` and a hint synthesized from the issues and the root schema — never a tool-declared `reason`, since the handler never ran. When pre-validation rewrote or dropped a key the caller wrote, `data.input` (`{ aliased: [{ alias, target }], ignored }`) names it and the hint closes with `Validated … as ….` / `Dropped undeclared key ….`; an ignore-list drop is never reported. `client_capability_missing` is the second framework-owned reason: a `ctx.requestInput` return a 2025-era connection cannot serve is refused before any wire traffic as `-32600` carrying that reason and a hint naming the capability.
+**Error-path parity.** Tool errors: `content[]` carries `Error: <message>`, then `Recovery: <hint>` when the hint says something the message does not already contain, then a closing `(reason … · not retryable · request <id>)` for whichever of `data.reason` / `data.retryable` / `data.requestId` is present; the numeric code and `data.issues` stay JSON-only. `structuredContent.error` carries `{ code, message, data? }`. No `_meta.error`. Resources re-throw via JSON-RPC error envelope. An argument rejection is one of them: `-32602` with `data.issues`, plus `data.reason: 'invalid_arguments'` and a hint synthesized from the issues and the root schema — never a tool-declared `reason`, since the handler never ran. When pre-validation rewrote or dropped a key the caller wrote, `data.input` (`{ aliased: [{ alias, target }], ignored }`) names it and the hint closes with `Validated … as ….` / `Dropped undeclared key ….`; an ignore-list drop is never reported. `client_capability_missing` is the second framework-owned reason: a `ctx.requestInput` return a 2025-era connection cannot serve is refused before any wire traffic as `-32600` carrying that reason and a hint naming the capability. **`data.requestId`** is set on every error envelope the framework builds — tool results, resource reads, prompts, `httpErrorHandler`'s JSON-RPC errors — equal to the `requestId` of that call's log records: a generated token, or the client's JSON-RPC id when it is a string (`httpErrorHandler` always generates its own). A resource read refused before it is measured (auth, `params`) carries an id no record shares. It replaces a thrown `data.requestId`, is never added to the thrown `McpError`, and is left off a resource `-32602` whose `data` is exactly `{ uri }` and off `runToolContract` results.
 
-**Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`, `error-contract-unthrown` (a declared reason no literal `ctx.fail`/`ctx.recoveryFor` in the handler names, unless marked `thrownBy: 'service'`), `error-contract-recovery-unforwarded` (a `ctx.fail` site carrying neither `ctx.recoveryFor('<reason>')` nor its own `recovery` key, so the declared hint reaches neither client surface). See `api-linter` skill.
+**Lint rules** (all warnings, surfaced in `devcheck`): `prefer-mcp-error-in-handler`, `prefer-error-factory`, `preserve-cause-on-rethrow`, `no-stringify-upstream-error`, `error-contract-conformance`, `error-contract-prefer-fail`, `error-contract-unthrown` (a declared reason no literal `ctx.fail`/`ctx.recoveryFor` in the handler names, unless marked `thrownBy: 'service'`). See `api-linter` skill.
 
 See `api-errors` skill for the full pattern-matching table, error code reference, and detailed examples.
 
@@ -458,7 +481,7 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod. Precedence: `createApp()
 | Category | Key Variables |
 |:---------|:-------------|
 | Transport | `MCP_TRANSPORT_TYPE` (`stdio`\|`http`), `MCP_HTTP_PORT`, `MCP_HTTP_HOST`, `MCP_HTTP_ENDPOINT_PATH` |
-| Auth | `MCP_AUTH_MODE`, `MCP_AUTH_SECRET_KEY`, `MCP_AUTH_DISABLE_SCOPE_CHECKS`, `OAUTH_*` |
+| Auth | `MCP_AUTH_MODE`, `MCP_AUTH_SECRET_KEY`, `MCP_AUTH_DISABLE_SCOPE_CHECKS`, `OAUTH_*`, `MCP_REQUEST_STATE_KEY` (opt-in `requestState` sealing) |
 | Storage | `STORAGE_PROVIDER_TYPE` (`in-memory`\|`filesystem`\|`supabase`\|`cloudflare-r2`\|`cloudflare-kv`\|`cloudflare-d1`) |
 | LLM | `OPENROUTER_API_KEY`, `OPENROUTER_APP_URL/NAME`, `LLM_DEFAULT_*` |
 | Telemetry | `OTEL_ENABLED`, `OTEL_SERVICE_NAME/VERSION`, `OTEL_EXPORTER_OTLP_*` |
@@ -485,7 +508,7 @@ describe('myTool', () => {
 });
 ```
 
-**`createMockContext` options:** `createMockContext()` (state included), `{ tenantId: 'test-tenant' }` (explicit tenant; defaults to `'default'`, as stdio resolves it), `{ errors: myTool.errors }` (typed `ctx.fail`), `{ inputResponses }` / `{ requestState }` (seed `ctx.inputs` to drive a multi-round-trip handler's second round directly), plus `auth`, `sessionId`, `signal`, `requestId`, `uri`, and the four `notify*` callbacks.
+**`createMockContext` options:** `createMockContext()` (state included), `{ tenantId: 'test-tenant' }` (explicit tenant; defaults to `'default'`, as stdio resolves it), `{ errors: myTool.errors }` (typed `ctx.fail`), `{ inputResponses }` / `{ requestState }` (seed `ctx.inputs` to drive a multi-round-trip handler's second round directly), `{ clientCapabilities }` (seeds `ctx.clientCapabilities` and filters the seeded responses to the declared kinds, as production does — omitted, nothing is filtered), plus `auth`, `sessionId`, `signal`, `requestId`, `uri`, and the four `notify*` callbacks.
 
 **`ctx.state` in tests is the production path.** The mock backs it with a real `StorageService` over an `InMemoryProvider`, so key validation (`[a-zA-Z0-9_.\-/]+` — colons rejected), the JSON round-trip of every value, and TTL expiry behave exactly as they do in a deployment. Passing `errors` narrows the return type to `HandlerContext<ReasonOf<…>>`, which is what a definition declaring a contract types its handler's `ctx` as — so `definition.handler(input, ctx)` typechecks.
 
@@ -495,7 +518,7 @@ describe('myTool', () => {
 
 **Fixture-based tests:** `mcpTest` from `/testing/vitest` (optional peer `vitest`) extends Vitest's `test` with per-test fixtures: `ctx` (fresh mock context), `session` (session-bound context), `fetchMock` (strict fetch fake, installed/restored around the test), and `storage` (fresh in-memory `StorageService`). Override fixtures via `.extend` with the function form only — a bare value would share one mutable context across every test in the file.
 
-**Tool contracts:** `runToolContract(definition, input)` from `/testing` validates input/output, invokes the handler, formats content, and returns production-shaped success/error surfaces without transport auth or telemetry. `toolContractSuite(definition, { success, errors })` from `/testing/vitest` registers reusable schema/handler/error-envelope conformance cases for a server's own tool definitions.
+**Tool contracts:** `runToolContract(definition, input)` from `/testing` validates input/output, invokes the handler, formats content, and returns production-shaped success/error surfaces — the declared `recovery` fill included — without transport auth, telemetry, or `data.requestId`. `toolContractSuite(definition, { success, errors })` from `/testing/vitest` registers reusable schema/handler/error-envelope conformance cases for a server's own tool definitions.
 
 **Fuzz testing:** `fuzzTool`/`fuzzResource`/`fuzzPrompt` from `/testing/fuzz` generate valid and adversarial inputs from Zod schemas via `fast-check`, then assert handler invariants (no crashes, no prototype pollution, no stack trace leaks). Returns a `FuzzReport` for custom assertions.
 

package/README.md

@@ -6,7 +6,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.13.9-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2026--07--28-8A2BE2.svg?style=flat-square)](https://modelcontextprotocol.io/specification/2026-07-28)
+[![Version](https://img.shields.io/badge/Version-0.13.10-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2026--07--28-8A2BE2.svg?style=flat-square)](https://modelcontextprotocol.io/specification/2026-07-28)
 
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.1.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
@@ -127,9 +127,7 @@ const search = tool('search', {
   ],
   handler: async (input, ctx) => {
     const res = await runSearch(input.query, input.limit);
-    if (!res) {
-      throw ctx.fail('index_unavailable', undefined, ctx.recoveryFor('index_unavailable'));
-    }
+    if (!res) throw ctx.fail('index_unavailable');
     ctx.enrich({ effectiveQuery: res.parsed, totalCount: res.total });
     if (res.items.length === 0) {
       ctx.enrich({ notice: `No matches for "${input.query}". Try broader terms.` });
@@ -141,7 +139,7 @@ const search = tool('search', {
 await createApp({ tools: [search] });
 ```
 
-Both contracts are advertised in `tools/list`, so clients see them before calling, and the definition linter checks the handler against them. `ctx.recoveryFor()` adds the declared recovery hint to the error response.
+Both contracts are advertised in `tools/list`, so clients see them before calling, and the definition linter checks the handler against them. A failure with a declared reason reaches the client carrying that entry's recovery hint, and every tool error carries the request ID its server log records share.
 
 ### Same data across client surfaces
 
@@ -236,6 +234,7 @@ Core config comes from environment variables, validated with Zod. Server-specifi
 | `MCP_HTTP_HOST` | HTTP server hostname | `127.0.0.1` |
 | `MCP_AUTH_MODE` | `none`, `jwt`, or `oauth` | `none` |
 | `MCP_AUTH_SECRET_KEY` | JWT signing secret (required for `jwt` mode) | — |
+| `MCP_REQUEST_STATE_KEY` | Opt-in key (≥ 32 bytes, the same on every instance) that seals the `requestState` handlers return and rejects any a client did not get from this server | — |
 | `STORAGE_PROVIDER_TYPE` | `in-memory`, `filesystem`, `supabase`, `cloudflare-d1`/`kv`/`r2` | `in-memory` |
 | `CANVAS_PROVIDER_TYPE` | `none` or `duckdb` (optional peer dependency `@duckdb/node-api`) | `none` |
 | `OTEL_ENABLED` | Enable OpenTelemetry | `false` |
@@ -273,17 +272,18 @@ Tool and resource handlers receive a `Context`. `ctx.enrich` and `ctx.fail` are
 | `ctx.log` | `ContextLogger` | Request-scoped logger (auto-correlates requestId, traceId, tenantId); also mirrored to the client as `notifications/message` |
 | `ctx.state` | `ContextState` | Tenant-scoped key-value storage |
 | `ctx.requestInput` | `(spec) => never` | Suspend and ask the caller for more input; the handler is re-entered with the answers |
-| `ctx.inputs` | `ContextInputs` | Reader over a retried request's responses — `.accepted()`, `.view()`, `.state()`, `.dropped` |
+| `ctx.inputs` | `ContextInputs` | The request's responses, limited to the kinds the client declared — `.accepted()`, `.view()`, `.state()`, `.dropped` |
+| `ctx.clientCapabilities` | `ClientCapabilities \| undefined` | What the client declared for this request; decides whether to ask for optional context, never whether to skip a consent prompt |
 | `ctx.enrich` | `Enrich` / `TypedEnrich<E>` | Add declared result context to structured output and text content |
 | `ctx.content` | `ContentCollect` | Attach image/audio blocks to `content[]` — `content.image(data, mimeType)`, `content.audio(...)`, or a raw block |
 | `ctx.fail` | `(reason, msg?, data?) => McpError` | Creates an error for `throw ctx.fail(...)`; available with a declared `errors` contract |
-| `ctx.recoveryFor` | `(reason) => object` | Resolves a declared recovery hint to `{ recovery: { hint } }`, for `ctx.fail`'s data argument |
+| `ctx.recoveryFor` | `(reason) => object` | Resolves a declared recovery hint to `{ recovery: { hint } }`; the framework already sends it with any failure carrying that reason and no hint of its own |
 | `ctx.signal` | `AbortSignal` | Cancellation signal |
 | `ctx.notifyResourceUpdated` | `Function?` | Notify subscribed clients a resource changed |
 | `ctx.notifyResourceListChanged` | `Function?` | Notify clients the resource list changed |
 | `ctx.notifyPromptListChanged` | `Function?` | Notify clients the prompt list changed |
 | `ctx.notifyToolListChanged` | `Function?` | Notify clients the tool list changed |
-| `ctx.requestId` | `string` | Unique request ID |
+| `ctx.requestId` | `string` | Request ID — shared by the call's log records and returned on its errors as `data.requestId` |
 | `ctx.tenantId` | `string?` | Tenant ID (JWT `tid` claim, or `'default'` for stdio and HTTP+`MCP_AUTH_MODE=none`) |
 | `ctx.auth` | `AuthContext?` | Token claims and scopes when the request is authenticated |
 | `ctx.sessionId` | `string?` | HTTP session ID in stateful/`auto` session mode — a scoping key, not an authorization principal |
@@ -334,7 +334,7 @@ const input = myTool.input.parse({ query: 'test' });
 const result = await myTool.handler(input, ctx);
 ```
 
-`createMockContext()` gives you a recording `log`, a `signal`, and a `state` backed by a real `StorageService` over an in-memory provider, so key validation, TTL expiry, and the JSON round-trip of stored values behave as they do in production: a `Date` reads back as its ISO string, and a value JSON cannot encode rejects. It uses tenant `'default'` unless you pass `{ tenantId }`. Pass `{ errors: myTool.errors }` for a typed `ctx.fail`, or `{ inputResponses, requestState }` to start a multi-round-trip handler at its second round.
+`createMockContext()` gives you a recording `log`, a `signal`, and a `state` backed by a real `StorageService` over an in-memory provider, so key validation, TTL expiry, and the JSON round-trip of stored values behave as they do in production: a `Date` reads back as its ISO string, and a value JSON cannot encode rejects. It uses tenant `'default'` unless you pass `{ tenantId }`. Pass `{ errors: myTool.errors }` for a typed `ctx.fail`, `{ inputResponses, requestState }` to start a multi-round-trip handler at its second round, or `{ clientCapabilities }` to set what the client declared (seeded responses are then filtered to the declared kinds, as in production).
 
 `/testing` also exports `createMockSession()` for session-bound contexts, `createFetchMock()` as a strict fake for upstream HTTP, and `runToolContract()`, which runs a definition through schema, handler, formatting, and error-envelope checks. `/testing/vitest` adds the `mcpTest` fixtures (`ctx`, `session`, `fetchMock`, `storage`) and `toolContractSuite()`.
 

package/changelog/0.13.x/0.13.10.md

@@ -0,0 +1,118 @@
+---
+summary: "A client can no longer pre-answer a consent gate with a response its declared capabilities do not cover, framework-built errors carry their request ID and fill a declared recovery hint, and multi-arch Docker builds stop running Bun under QEMU."
+breaking: false
+security: true
+agent-notes: |
+  Adoption steps for a consumer upgrading from 0.13.9.
+
+  1. Dockerfile — move every install into a `deps` stage. These steps
+     replace 0.13.8's agent-notes step 7. A production stage that copies
+     `bunfig.toml` (the 0.13.8 / 0.13.9 scaffold) fails `lint:packaging`
+     check 15 once `scripts/lint-packaging.ts` is resynced, and its
+     multi-arch build aborts on the non-native leg. `init` never overwrites
+     `Dockerfile`, so port by hand:
+     a. Resync the framework scripts (maintenance Phase C, or `init` in
+        place) so `scripts/install-otel.ts` exists. Commit it, and keep
+        `scripts/` out of `.dockerignore`: the image build copies it.
+     b. Copy the scaffold `Dockerfile`'s `deps` stage — its
+        `FROM --platform=$BUILDPLATFORM` on the build stage's `oven/bun` tag,
+        manifest copy, scanner seed, `TARGETARCH` → `.bun-cpu` mapping,
+        cross-install, `install-otel.ts` step, and scanner removal — in
+        between the build and production stages.
+     c. In the production stage, delete the `package.json`/`bun.lock`/
+        `bunfig.toml` copy, the scanner seed, the `bun install`,
+        `ARG OTEL_ENABLED`, and the OTel `RUN` (the `bun -e` range lookup
+        plus `bun add`, or an older plain `bun add` list). Before the `dist`
+        copy, add `COPY package.json ./` and
+        `COPY --from=deps /usr/src/app/node_modules ./node_modules`. Keep
+        everything else.
+     d. Move any other build-time `bun` / `bunx` call out of a stage not
+        pinned to `$BUILDPLATFORM`; check 15 names each line. Verify with
+        `bun run lint:packaging`.
+     A server still on the pre-0.13.8 production stage lints clean, but its
+     image installs skip the release-age gate and scanner; port it too.
+  2. Drop redundant recovery forwards. `ctx.fail('x', msg, ctx.recoveryFor('x'))`
+     becomes `ctx.fail('x', msg)`, and a service throw keeps only
+     `{ reason: 'x', … }` (a service that took `ctx` only for the spread can
+     drop it). Keep explicit `recovery: { hint }` overrides, deliberate
+     cross-reason forwards, and forwards a test asserts on a direct
+     `definition.handler(...)` throw — or move that assertion to
+     `runToolContract`, which applies the fill. The lint rule
+     `error-contract-recovery-unforwarded` is gone: swap its mentions in
+     `CLAUDE.md` / `AGENTS.md` for the template's Errors wording, and drop it
+     from any script that greps lint output.
+  3. Tests pinning exact error text or `data`: a tool error's `content[]`
+     now closes with `request <id>`, and tool, resource, and prompt error
+     `data` gain `requestId` (a classified plain `Error` returns
+     `data: { requestId }`). Assert with the envelope's own value or
+     `expect.any(String)`. `runToolContract` adds no request id but now
+     fills a declared hint, adding a `Recovery:` line. A server that put an
+     upstream id in `data.requestId` renames it (`upstreamRequestId`); one
+     that copied `ctx.requestId` there drops it.
+  4. Alerts: `invalid_arguments` and `client_capability_missing` records
+     now log at `notice`, tagged `mcp.error.severity: "notice"`. The
+     `Prompt generation failed.` record is gone — key prompt alerts on
+     `Error in prompt:<name>`.
+  5. Consent gates: a destructive handler that acts on `ctx.inputs` alone,
+     compares a target carried in `requestState`, or stores a record without
+     the operation and caller moves to the `api-context` § Consent gates
+     pattern: redeem a `ctx.state` record
+     `{ operation, clientId, subject, target, contentHash }` first and ask
+     again on any mismatch. Keep the record where every instance a retry
+     reaches can read it (`filesystem`, `supabase`, or `cloudflare-d1`,
+     never `cloudflare-kv`), and make an action that must not repeat
+     idempotent per record until an atomic `ctx.state.take` exists (#593).
+     Tests copy the round-one record into the round-two mock context
+     (`api-testing` § Mock inputs).
+  6. Set `MCP_REQUEST_STATE_KEY` (≥ 32 bytes, e.g. `openssl rand -base64 32`,
+     the same on every instance and Worker isolate) on any server whose
+     `requestState` drives a mutation or carries ids across rounds. A
+     startup `info` record naming the variable confirms it took. A client
+     or test that builds `requestState` by hand then gets `-32602`
+     `invalid_request_state`.
+  7. Replace a catch of `client_capability_missing` used to fall through to
+     another source with a `ctx.clientCapabilities` check before
+     `ctx.requestInput`, after reading `ctx.inputs`. Treat `undefined` as
+     cannot-ask, and never use it to skip a consent prompt.
+  8. `Context` gains a required `clientCapabilities` key, so a hand-built
+     `Context` literal (a custom mock typed `Context`) needs it.
+     `createMockContext` tests change only when they seed
+     `clientCapabilities`, which applies the production filter.
+---
+
+# 0.13.10 — 2026-09-26
+
+## Added
+
+- **`ctx.clientCapabilities`** ([#580](https://github.com/cyanheads/mcp-ts-core/issues/580)) — what the client declared for this request (`undefined` for a 2025-era request under stateless HTTP), for deciding whether to ask for optional context, never whether to skip a consent prompt. `ClientCapabilities` is exported from the main entry, and `createMockContext({ clientCapabilities })` seeds it.
+- **`MCP_REQUEST_STATE_KEY`** ([#496](https://github.com/cyanheads/mcp-ts-core/issues/496)) — opt-in key (≥ 32 bytes, the same on every instance) that seals the `requestState` a handler returns, bound to the caller for 900 s. Any other state is rejected as `-32602` `invalid_request_state` before the handler runs; also a Worker core binding.
+- **`scripts/install-otel.ts`** ([#578](https://github.com/cyanheads/mcp-ts-core/issues/578)) — ships in the package and the scaffold, installing every `@opentelemetry/*` peer plus `@hono/otel` at the framework's declared ranges and passing extra arguments (`--os`, `--cpu`) to its `bun install`. The Dockerfiles run it in place of a hand-kept list.
+
+## Changed
+
+- **A declared `recovery` reaches the wire without `ctx.recoveryFor`** ([#579](https://github.com/cyanheads/mcp-ts-core/issues/579)) — a tool or resource failure whose `data.reason` names an `errors[]` entry and carries no `data.recovery` gets that entry's hint, service throws included, and `runToolContract` does the same. A throw-site hint still wins.
+- **Error envelopes carry `data.requestId`** ([#576](https://github.com/cyanheads/mcp-ts-core/issues/576)) — tool, resource, prompt, and `httpErrorHandler` errors return the `requestId` their log records carry, and a tool's `content[]` closes with `request <id>`. A resource `-32602` whose `data` is exactly `{ uri }` and `runToolContract` results go without.
+- **Framework refusals log at `notice`** ([#567](https://github.com/cyanheads/mcp-ts-core/issues/567)) — `Error in tool:<name>` for `invalid_arguments` and `client_capability_missing` drops from `error` to `notice`, and `mcp.errors.classified` tags them `mcp.error.severity: "notice"`. A declared `severity` naming either reason still wins.
+- **`lint:packaging` check 15 flags JavaScript in any target-platform stage** ([#575](https://github.com/cyanheads/mcp-ts-core/issues/575)) — a Dockerfile stage not starting `FROM --platform=$BUILDPLATFORM` fails when a `RUN` invokes `bun` for anything but `install`/`add`, or installs once `bunfig.toml` is in the stage, naming each line.
+- **The release review pass may ship caller-handed work** — `release-pr-review` commits uncommitted work the caller explicitly hands over on top of the stack and adds it to the changelog entry; `release-and-publish` admits those commits above the release commit.
+- Skill versions: `add-service` 1.11 → 1.12, `add-test` 1.7 → 1.8, `add-tool` 2.31 → 2.32, `api-config` 1.22 → 1.23, `api-context` 2.8 → 2.9, `api-errors` 1.18 → 1.19, `api-linter` 1.20 → 1.21, `api-telemetry` 1.15 → 1.16, `api-testing` 1.12 → 1.13, `api-workers` 1.8 → 1.9, `design-mcp-server` 2.30 → 2.31, `field-test` 2.17 → 2.18, `polish-docs-meta` 2.20 → 2.21, `release-and-publish` 2.22 → 2.23, `release-pr-review` 1.6 → 1.7, `security-pass` 1.11 → 1.12.
+
+## Removed
+
+- **`error-contract-recovery-unforwarded`** ([#579](https://github.com/cyanheads/mcp-ts-core/issues/579)) — the lint rule is gone; with the recovery fill, a bare `ctx.fail('<reason>')` reaches the client with its hint.
+
+## Fixed
+
+- **Multi-arch Docker builds no longer run Bun under QEMU** ([#575](https://github.com/cyanheads/mcp-ts-core/issues/575)) — the framework and scaffold Dockerfiles install production dependencies in a `deps` stage on `$BUILDPLATFORM`, cross-installing with `--os`/`--cpu`, so the production stage's only Bun calls are `HEALTHCHECK` and `CMD`. Existing servers port by hand.
+- **An argless prompt's `generate` receives `{}`** ([#581](https://github.com/cyanheads/mcp-ts-core/issues/581)) — not the SDK's request context, and its input measures 0 bytes.
+- **A failed prompt writes one error record, under its own request id** ([#582](https://github.com/cyanheads/mcp-ts-core/issues/582)) — `Error in prompt:<name>` at `error`, and a completion record of `Prompt generation finished.` at `info` with `metrics.isSuccess: false` in place of `Prompt generation failed.` at `error`. Each `prompts/get` logs under its own `requestId`.
+
+## Security
+
+- **`ctx.inputs` keeps only responses the client declared** ([#496](https://github.com/cyanheads/mcp-ts-core/issues/496)) — a client that did not declare `elicitation`, or declared only its URL mode, could pre-answer a consent gate on its first call. A response now reaches `ctx.inputs` only when the client's declared capabilities and modes cover it, on both protocol eras.
+- **Consent gates redeem a server record** — a client that declared `elicitation` can still pre-answer, so `api-context` § *Consent gates* documents storing `{ operation, clientId, subject, target, contentHash }` in `ctx.state` under a random id and redeeming it before acting. That stops a sequential replay, not concurrent retries, until an atomic `ctx.state.take` exists ([#593](https://github.com/cyanheads/mcp-ts-core/issues/593)).
+
+## Dependencies
+
+- `hono` ^4.13.8 → ^4.13.9.
+- Dev: `@cloudflare/workers-types` 5.20260922.1 → 5.20260924.1.

package/dist/config/index.d.ts

@@ -60,6 +60,7 @@ declare const ConfigSchema: z.ZodObject<{
     mcpGcPressureIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     mcpAllowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
     mcpAuthSecretKey: z.ZodOptional<z.ZodString>;
+    mcpRequestStateKey: z.ZodOptional<z.ZodString>;
     mcpJwtExpectedIssuer: z.ZodOptional<z.ZodString>;
     mcpJwtExpectedAudience: z.ZodOptional<z.ZodString>;
     mcpAuthMode: z.ZodPreprocess<z.ZodDefault<z.ZodEnum<{
@@ -197,6 +198,7 @@ declare const parseConfig: (envOverrides?: Record<string, string | undefined>) =
     mcpGcPressureIntervalMs: number;
     mcpAllowedOrigins?: string[] | undefined;
     mcpAuthSecretKey?: string | undefined;
+    mcpRequestStateKey?: string | undefined;
     mcpJwtExpectedIssuer?: string | undefined;
     mcpJwtExpectedAudience?: string | undefined;
     mcpAuthMode: "jwt" | "none" | "oauth";
@@ -325,6 +327,7 @@ declare const config: {
     mcpGcPressureIntervalMs: number;
     mcpAllowedOrigins?: string[] | undefined;
     mcpAuthSecretKey?: string | undefined;
+    mcpRequestStateKey?: string | undefined;
     mcpJwtExpectedIssuer?: string | undefined;
     mcpJwtExpectedAudience?: string | undefined;
     mcpAuthMode: "jwt" | "none" | "oauth";

package/dist/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,wEAAwE;AACxE,eAAO,MAAM,cAAc,2BAA2B,CAAC;AACvD,eAAO,MAAM,iBAAiB,QAAkC,CAAC;AA6DjE,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiYd,CAAC;AAGL,QAAA,MAAM,WAAW,kBAAmB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8MrE,CAAC;AAIF;;;;;;;;GAQG;AACH,QAAA,MAAM,WAAW,kBAAmB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAG,IAExE,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuBV,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAErD;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,wEAAwE;AACxE,eAAO,MAAM,cAAc,2BAA2B,CAAC;AACvD,eAAO,MAAM,iBAAiB,QAAkC,CAAC;AA6DjE,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2Yd,CAAC;AAGL,QAAA,MAAM,WAAW,kBAAmB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+MrE,CAAC;AAIF;;;;;;;;GAQG;AACH,QAAA,MAAM,WAAW,kBAAmB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAG,IAExE,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuBV,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAErD;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC"}

package/dist/config/index.js

@@ -204,6 +204,16 @@ const ConfigSchema = z
     mcpGcPressureIntervalMs: z.coerce.number().min(0).default(0),
     mcpAllowedOrigins: z.array(z.string()).optional(),
     mcpAuthSecretKey: z.string().optional(),
+    /**
+     * Opt-in HMAC key for multi-round-trip `requestState`. When set, the
+     * framework seals the state a handler returns with `ctx.requestInput` and
+     * the SDK verifies every echoed state before the handler runs, so a retry
+     * can only carry state this server minted, for the same principal, within
+     * 900 s. Every instance a retry can reach needs the same key. Unset, state
+     * round-trips raw. At least 32 bytes; the length is checked where the
+     * codec is built, so the startup error names this variable.
+     */
+    mcpRequestStateKey: z.string().optional(),
     mcpJwtExpectedIssuer: z.string().optional(),
     mcpJwtExpectedAudience: z.string().optional(),
     mcpAuthMode: z.preprocess(emptyStringAsUndefined, z.enum(['jwt', 'oauth', 'none']).default('none')),
@@ -481,6 +491,7 @@ const parseConfig = (envOverrides) => {
             .map((o) => o.trim())
             .filter(Boolean),
         mcpAuthSecretKey: env.MCP_AUTH_SECRET_KEY,
+        mcpRequestStateKey: env.MCP_REQUEST_STATE_KEY,
         mcpJwtExpectedIssuer: env.MCP_JWT_EXPECTED_ISSUER,
         mcpJwtExpectedAudience: env.MCP_JWT_EXPECTED_AUDIENCE,
         mcpAuthMode: env.MCP_AUTH_MODE,