stitchkit 0.90.7 → 0.91.0

package/dist/tools.js

@@ -1,10 +1,14 @@
+import {
+  compareCodepoints,
+  serializeCanonicalJson
+} from "./index-0j3vcp5m.js";
 import {
   ManagedFileError
 } from "./index-actkayzn.js";
 import {
   signJwt,
   verifyPkce
-} from "./index-bva395we.js";
+} from "./index-bv7mytab.js";
 import"./index-hr4tzbwq.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
@@ -14,16 +18,20 @@ import {
   guardSignalCallback,
   mediaTypeEssence,
   reportSignalError
-} from "./index-aj9geeez.js";
+} from "./index-709nh7z7.js";
 import {
   redact
-} from "./index-xbppf54a.js";
+} from "./index-6kyksz9y.js";
 import {
   buildToolManifest,
   describeToolCatalog,
   mountAgent
-} from "./index-83fafqw8.js";
-import"./index-7rkhw9ec.js";
+} from "./index-f4p4b8f6.js";
+import {
+  AgentToolError,
+  createLocalStepDurability,
+  isAgentToolError
+} from "./index-kw9t5ayn.js";
 import {
   argumentsDigest
 } from "./index-a916km3r.js";
@@ -38,7 +46,7 @@ import {
 } from "./index-4fpa9dy2.js";
 import {
   createToolInvoker
-} from "./index-tgh3ksfh.js";
+} from "./index-bh70rk41.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -47,22 +55,22 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-fqg5mfk7.js";
+} from "./index-ya611vx3.js";
 import"./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-zsdgd1tz.js";
+} from "./index-qrbdq8jk.js";
 import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-1bnkzq95.js";
+} from "./index-1qvdwnp2.js";
 import {
   ToolExecutionControlError,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-8pjqv3zh.js";
+} from "./index-mqhjmadk.js";
 import {
   getRequestContext,
   getTraceId,
@@ -71,10 +79,10 @@ import {
 import"./index-f9mb610r.js";
 import {
   normalizeError
-} from "./index-2hryh65w.js";
+} from "./index-13cjtmrw.js";
 import {
   defineContract
-} from "./index-nrqg8tks.js";
+} from "./index-0a349c33.js";
 import"./index-rxfy4cq7.js";
 import {
   ManagedFilePathSchema,
@@ -101,11 +109,13 @@ import {
   presentationMetadata,
   validateMcpRoundPolicy
 } from "./index-fenaekmk.js";
-import"./index-cby4ar3v.js";
+import {
+  toJsonSchema
+} from "./index-cby4ar3v.js";
 import {
   AppError,
   STITCH_ERROR_STATUS
-} from "./index-scs3f1eg.js";
+} from "./index-2vtcmrj9.js";
 import"./index-kzfs85xp.js";
 import {
   isRecord
@@ -946,6 +956,63 @@ function inlineMcpAppBundle(html) {
   return html.replace(EXT_APPS_BUNDLE_PLACEHOLDER, () => bundle);
 }
 
+// src/tools/mcp-catalog.ts
+import { createHash } from "node:crypto";
+var MCP_CATALOG_META_KEY = "stitchkit/catalog";
+var stampCache = new WeakMap;
+function toolFingerprint(descriptor) {
+  const { mountable } = descriptor;
+  return {
+    name: mountable.name,
+    description: mountable.method.desc,
+    input: descriptor.inputSchema,
+    output: descriptor.outputSchema ? toJsonSchema(descriptor.outputSchema, "output", "any") : null,
+    annotations: mountable.method.annotations ?? null
+  };
+}
+function mcpCatalogStamp(surface) {
+  const cached = stampCache.get(surface);
+  if (cached)
+    return cached;
+  const descriptors = [
+    ...surface.contractTools,
+    ...surface.runtimeTools.map((entry) => entry.descriptor)
+  ].sort((left, right) => compareCodepoints(left.mountable.name, right.mountable.name));
+  const bytes = serializeCanonicalJson(descriptors.map(toolFingerprint));
+  const stamp = {
+    digest: createHash("sha256").update(bytes).digest("hex").slice(0, 16),
+    tools: descriptors.length
+  };
+  stampCache.set(surface, stamp);
+  return stamp;
+}
+function mcpCatalogMeta(stamp) {
+  return { [MCP_CATALOG_META_KEY]: { ...stamp } };
+}
+function readMcpCatalogStamp(meta) {
+  if (!isRecord(meta))
+    return null;
+  const value = meta[MCP_CATALOG_META_KEY];
+  if (!isRecord(value))
+    return null;
+  const { digest, tools } = value;
+  if (typeof digest !== "string" || digest.length === 0)
+    return null;
+  if (typeof tools !== "number" || !Number.isInteger(tools) || tools < 0)
+    return null;
+  return { digest, tools };
+}
+function stampToolRegistration(config, stamp) {
+  if (!stamp)
+    return config;
+  return { ...config, _meta: { ...config._meta, ...mcpCatalogMeta(stamp) } };
+}
+function stampToolResult(result, stamp) {
+  if (!stamp)
+    return result;
+  return { ...result, _meta: { ...result._meta, ...mcpCatalogMeta(stamp) } };
+}
+
 // src/tools/mcp-prepare.ts
 function textBlock(text) {
   return [{ type: "text", text }];
@@ -1283,7 +1350,7 @@ function mountPreparedRuntimeMcp(server, tools, config) {
         "ui/resourceUri": definition.ui.resourceUri
       };
     }
-    server.registerTool(definition.name, toolConfig, async (rawArgs, mcpContext) => runInMcpRequestContext(mcpContext, definition.name, async () => {
+    server.registerTool(definition.name, stampToolRegistration(toolConfig, config.catalog), async (rawArgs, mcpContext) => stampToolResult(await runInMcpRequestContext(mcpContext, definition.name, async () => {
       const args = isRecord(rawArgs) ? rawArgs : {};
       const runTool = (tool, toolArgs, roundContext) => executeToolMethod(tool.method, definition.name, toolArgs, { ...config.context, ...roundContext, source: "mcp" }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(definition.name, paths) : undefined);
       const round = await resolveMcpRound({
@@ -1323,7 +1390,7 @@ function mountPreparedRuntimeMcp(server, tools, config) {
         throw new Error("[stitchkit] Runtime MCP presenter invariant failed");
       }
       return presentedResult.data;
-    }));
+    }), config.catalog));
   }
 }
 
@@ -1343,7 +1410,10 @@ function mountMcp(mcpServer, services, config = {}) {
     schemaValidation: config.schemaValidation,
     logger: config.logger
   });
-  mountPreparedMcp(mcpServer, prepared, config);
+  mountPreparedMcp(mcpServer, prepared, {
+    ...config,
+    catalog: mcpCatalogStamp({ contractTools: prepared, runtimeTools: [] })
+  });
 }
 function mountPreparedMcp(mcpServer, prepared, config = {}) {
   const runTool = createToolRunner({
@@ -1373,7 +1443,7 @@ function mountPreparedMcp(mcpServer, prepared, config = {}) {
         "ui/resourceUri": mountable.method.ui.resourceUri
       };
     }
-    mcpServer.registerTool(mountable.name, toolConfig, async (rawArgs, mcpContext) => runInMcpRequestContext(mcpContext, mountable.name, async () => {
+    mcpServer.registerTool(mountable.name, stampToolRegistration(toolConfig, config.catalog), async (rawArgs, mcpContext) => stampToolResult(await runInMcpRequestContext(mcpContext, mountable.name, async () => {
       const args = isRecord(rawArgs) ? rawArgs : {};
       try {
         const round = await resolveMcpRound({
@@ -1392,7 +1462,7 @@ function mountPreparedMcp(mcpServer, prepared, config = {}) {
       } catch (err) {
         return formatMcpResult(toolResultFromError(err), "none", mountable.name, config.errorHint);
       }
-    }));
+    }), config.catalog));
   }
 }
 function buildMcpServer(config, auth) {
@@ -1454,7 +1524,9 @@ function buildMcpServerFromPrepared(config, auth, prepared) {
   };
   const server = new McpServer(config.serverInfo, serverOptions);
   const context = config.context?.(auth);
+  const catalog = mcpCatalogStamp(prepared);
   mountPreparedMcp(server, prepared.contractTools, {
+    catalog,
     context,
     hooks: config.hooks,
     lifecycle: config.lifecycle,
@@ -1473,6 +1545,7 @@ function buildMcpServerFromPrepared(config, auth, prepared) {
     }
   });
   mountPreparedRuntimeMcp(server, prepared.runtimeTools, {
+    catalog,
     context,
     hooks: config.hooks,
     lifecycle: config.lifecycle,
@@ -2683,6 +2756,7 @@ export {
   validateMcpSchemas,
   summarizeTransports,
   resolveMedia,
+  readMcpCatalogStamp,
   protectedResourceMetadataUrl,
   oauthProtectedResourceRoute,
   mountWait,
@@ -2693,9 +2767,11 @@ export {
   mountMcp,
   mountDownload,
   mountAgent,
+  mcpCatalogMeta,
   listToolNames,
   listContractToolNames,
   isToolExecutionControlError,
+  isAgentToolError,
   inlineMcpAppBundle,
   flattenToolJsonSchema,
   findUntypedProperties,
@@ -2718,6 +2794,7 @@ export {
   createRuntimeToolFactory,
   createMcpHttpRoute,
   createMcpHandler,
+  createLocalStepDurability,
   createCli,
   createAsyncOperationSnapshotSchema,
   composeToolLifecycle,
@@ -2737,6 +2814,8 @@ export {
   PORTABLE_JSON_SCHEMA_FORMATS,
   McpMediaContentSchema,
   McpAnnotationsSchema,
+  MCP_CATALOG_META_KEY,
   EXT_APPS_BUNDLE_PLACEHOLDER,
-  AsyncOperationCancelResultSchema
+  AsyncOperationCancelResultSchema,
+  AgentToolError
 };

package/dist/tracking.js

@@ -3,11 +3,11 @@ import {
 } from "./index-3xwxfj4z.js";
 import {
   defineContract
-} from "./index-nrqg8tks.js";
+} from "./index-0a349c33.js";
 import"./index-rxfy4cq7.js";
 import"./index-6k1937bx.js";
 import"./index-zcgf3gqf.js";
-import"./index-scs3f1eg.js";
+import"./index-2vtcmrj9.js";
 import"./index-kzfs85xp.js";
 import"./index-77fekveh.js";
 

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 35 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 1 of the 36 minors since 0.56.2, most recently 0.83.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 35 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 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/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 35 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 36 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 |
@@ -1252,6 +1252,43 @@ scope** — the same prefix under two different group scopes is legal (their URL
 are separated by `scopePrefixes`, and a genuine path clash is the router's own
 construction error).
 
+#### A dev stand that survives half a feature — `onMissingHandler`
+
+Adding an endpoint is two edits by construction: the contract, then the handler.
+An editor saves one file at a time and a watcher restarts on the first save, so
+between the two the application refuses to start — and on a shared dev stand that
+is everyone's stand, not just yours. A project rule ("make both edits at once")
+cannot outrun the filesystem.
+
+```ts
+implementRegistry(apiContractRegistry, handlers, {
+  onMissingHandler: process.env.NODE_ENV === 'production' ? 'throw' : 'stub',
+})
+```
+
+With `'stub'` the application starts, the unimplemented endpoint answers `501` and
+names itself in the log at every mount, so it cannot be forgotten. Both save
+orders are covered: a contract ahead of its handler, and a handler ahead of its
+contract. The option is accepted by `implement`, `implementRegistry`,
+`createImplement`, `createScopedImplement`, `createImplementRegistry` and
+`createScopedImplementRegistry`.
+
+Three things it deliberately does not do. It stays `'throw'` by default, and
+`'throw'` is the only right answer in production: a release is atomic, so there is
+no window to protect, and a surface with a hole must not ship. It does not relax
+the **compile-time** exactness check — that lives in the generic constraint, your
+editor still shows the missing handler, and a watcher that only transpiles is
+precisely why the runtime refusal was the one that bit. And it does not stub a
+streaming multipart endpoint, which needs `defineMultipartStream()` receivers; the
+stand still stops on one of those.
+
+The stub answers `NOT_IMPLEMENTED` with status `501` everywhere — over HTTP and on
+a tool call that crosses a process boundary alike, because the code is registered
+in `STITCH_ERROR_STATUS`. One consequence follows from that and is worth knowing:
+a stubbed endpoint keeps its `expose`, so on a dev stand it is advertised to a
+model as a real tool that always refuses. The refusal is not retryable, so a model
+stops rather than loops; it still costs one turn to find out.
+
 The registry is intentionally flat: every key must point to one concrete
 `defineContract()` result. Composed namespace arrays are mounted explicitly with
 `implement()` because they do not have a one-key-to-one-handler-map boundary.
@@ -3446,6 +3483,138 @@ finite `surfaces` registry when identities share a provably immutable surface.
 Stitchkit never advertises list-change or subscription capabilities
 without an implementation.
 
+### Knowing your catalog is stale — the catalog stamp
+
+A client lists the tools once and keeps that list. If the server's contract
+moves afterwards, the client's copy is wrong and *nothing tells it so*: calls
+are refused, and from inside the client a refusal looks like a broken server.
+This is the most expensive shape a contract disagreement takes, because the
+party able to fix it is the one with no evidence.
+
+Every advertised tool and every tool result therefore carries the fingerprint of
+the catalog it came from:
+
+```ts
+import { readMcpCatalogStamp } from 'stitchkit/tools';
+
+const listed = await client.listTools();
+let known = readMcpCatalogStamp(listed.tools[0]?._meta); // { digest, tools }
+
+const result = await client.callTool({ name: 'record_journal', arguments });
+const live = readMcpCatalogStamp(result._meta);
+if (live && known && live.digest !== known.digest) {
+  // The catalog moved under us. Re-list before blaming the result.
+  known = readMcpCatalogStamp((await client.listTools()).tools[0]?._meta);
+}
+```
+
+The comparison costs nothing and runs on a response you were already receiving —
+including a refusal, which is exactly when a stale catalog is the likeliest
+explanation. `notifications/tools/list_changed` is the push-shaped answer to the
+same problem and `createMcpHandler` cannot send it: it is stateless by
+construction, so there is no retained session to push down.
+
+The digest covers each advertised tool's name, description, input schema, output
+schema and annotations, and nothing else — it moves when the contract moves and
+not when a handler does. Raw SDK registrations stay consumer-owned and are
+outside it.
+
+### Shaping arguments before validation — `beforeToolCall`
+
+`beforeToolCall` sees the arguments as they arrived and may **replace** them:
+
+```ts
+hooks: {
+  beforeToolCall: async ({ args }) =>
+    typeof args.id === 'string' && args.id.startsWith('@')
+      ? { ...args, id: await resolveReference(args.id) }
+      : undefined,       // undefined / null / nothing → unchanged
+}
+```
+
+The replacement is validated by the contract schema like any other input, so this
+shapes a call and never bypasses the schema — a hook returning something the
+contract refuses produces an ordinary `VALIDATION_ERROR`. It runs before the
+params/input split, before argument coercion and before both schemas, which is
+why a field declared `z.string()` can receive a reference and still be a string by
+the time it is checked. `lifecycle.beforeHandle` is too late for this: the schemas
+have already answered.
+
+The audit trail is unaffected. `afterToolCall` reports what the caller sent as
+`args` and the replacement separately as `effectiveArgs`, so a rewrite is visible
+as a rewrite rather than by overwriting the evidence.
+
+### Knowing the outcome of a call — `afterToolCall` and `toolCallId`
+
+`afterToolCall` receives the whole `ToolResult` — `{ok: true, data}` or
+`{ok: false, code, …}` — on every exit, including a validation failure that never
+reached the handler, and on all three transports. It is the answer to "did this
+call fail"; deriving that from the serialized error text instead is the mistake
+this section exists to prevent, and it is a mistake that does not announce itself:
+one consumer had five places asking the question and getting five answers.
+
+To correlate an outcome with the call the model made, read `context.toolCallId`:
+
+```ts
+hooks: {
+  afterToolCall: ({ context, result }) => {
+    loop.record(context.toolCallId, result.ok ? 'ok' : result.code);
+  },
+}
+```
+
+Two exits are deliberately **not** reported: a runtime tool presenter that throws
+on the agent surface (the AI SDK calls it after `execute` has already returned)
+and `ToolExecutionControlError`, which is a run being stopped rather than a tool
+failing — check it with `isToolExecutionControlError`.
+
+### Restartable tool bodies — `durability`
+
+A tool that starts slow work and must report exactly once, including after a host
+restart, can keep that bookkeeping **inside** the tool:
+
+```ts
+mountAgent(services, {
+  durability: (toolCallId, signal) => myLedgerFor(toolCallId, signal),
+});
+
+// in the handler
+const asset = await ctx.step('render', () => renderAsset(ctx.input));
+await ctx.waitFor({ event: 'render-done', id: assetId });
+```
+
+`ToolDurability` is the port a tool body sees — `step`, `sleep`, `waitFor`. You
+do not have to implement it: the engine ships from `stitchkit/tools`, and it needs
+a ledger of two methods over storage you already have:
+
+```ts
+import { createLocalStepDurability, type StepDurabilityLedger } from 'stitchkit/tools';
+
+const ledger: StepDurabilityLedger = {
+  appendEvent: (event) => db.durabilityEvents.insert(event),   // returns the row with `seq`
+  readEvents: ({ conversationId, fromSeq, toSeq }) => db.durabilityEvents.page(…),
+};
+
+mountAgent(services, {
+  durability: (toolCallId, signal) =>
+    createLocalStepDurability({ store: ledger, conversationId, runId: toolCallId, signal }),
+});
+```
+
+That gives replay, absolute deadlines and decode refusal without writing them.
+The port is there for an application that already has its own ledger engine.
+
+One thing the port deliberately leaves out: **delivery**. `waitFor` parks until
+`{ event, id }` arrives, and a tool body has no business delivering to itself —
+so `deliver` lives on the engine object you constructed, not in the handler
+context. Whatever produces the event (a webhook, a queue consumer, a cron) calls
+`engine.deliver({ event, id, payload })` against the same ledger; the parked
+`waitFor` resolves, and a `waitFor` that starts after the delivery returns at
+once. Taking `agent-runtime` is not required and nothing of the runtime proper
+enters the `stitchkit/tools` graph. An application that *does* run on
+`agent-runtime` gets durability through the run context and needs no option;
+where both exist the runtime's wins, because the run is recorded in its ledger.
+
 ### Typed MCP call metadata
 
 Contract handlers, runtime-tool handlers/factories, lifecycle and tool hooks all
@@ -5475,7 +5644,7 @@ or it keeps the failed attempt's partial text on screen.
   usage, files and sources do not count;
 - `tool-status` is transient lifecycle presentation with JSON-safe input on
   start and output on completion. A mounted typed failure carries the same safe
-  `{ error, details?, _hint? }` envelope as the durable result; an unknown
+  `{ error, retryable, details?, _hint? }` envelope as the durable result; an unknown
   internal cause remains generic and stays in local observability only;
 - `terminal` follows the winning terminal CAS.
 
@@ -9867,7 +10036,8 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `CONFLICT`, `RATE_LIMITED`, `VALIDATION_ERROR`, `FILE_INVALID_PATH`,
 `FILE_OUTSIDE_ROOT`, `FILE_NOT_FOUND`, `FILE_NOT_REGULAR`,
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
-`REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `WAIT_TIMEOUT`,
+`REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
+`WAIT_TIMEOUT`,
 `WAIT_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
 `STREAM_TERMINAL_MISSING`, `STREAM_LIFETIME_EXCEEDED`,
@@ -9995,7 +10165,7 @@ whether the code declares `details`:
 | code **with** a `details` schema | the declared message | no text at all — only `details` and `hint` |
 | code **without** one | the declared message | the same text, delivered as `details.message` |
 
-The model-facing envelope is `{ error, details?, _hint? }`; for a code with no
+The model-facing envelope is `{ error, retryable, details?, _hint? }`; for a code with no
 details schema the framework fills `details` with `{ message }`, so declaring a
 message changes what the model reads there — it used to be the code itself. Put
 anything the model must reliably read in `details` or `hint`, not in `message`.
@@ -10967,6 +11137,24 @@ applied. Active trace, span, user and dimensions are reserved framework fields;
 caller data cannot overwrite them. A throwing getter, cyclic value or failing
 sink never escapes into application code.
 
+One string bound for the whole record cuts an error's stack from the bottom —
+which is exactly where your own frames are. Raise the ceiling for that key alone,
+wherever it sits (`stack` at the top of one record and under `errorDetail` in the
+next is the same field), without touching the bound for everything else:
+
+```ts
+createBoundedLogger({
+  sink,
+  bounds: { stringLength: 4_000, stringLengthByKey: { stack: 32_000 } },
+})
+// or directly: redact(value, { maxStringLength: 4_000, maxStringLengthByKey: { stack: 32_000 } })
+```
+
+Keyed by name, not by path — the question is "what is this field", not "where is
+it". The entry ceiling (`entryBytes`) keeps the last word: a record that does not
+fit still collapses, but the decision is made for the record, not by cutting one
+field short in advance.
+
 
 ==============================================================================
 # Guide: Testing & deployment  (docs/guide/testing-and-deployment.md)
@@ -11935,6 +12123,23 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.91.0
+
+1. `STITCH_ERROR_STATUS` gained `NOT_IMPLEMENTED` (501). An **exhaustive** error
+   vocabulary must name it — without the row `defineErrors({ mapping: { exhaustive:
+   true } })` stops compiling and then throws at startup. Nothing else in this
+   release requires action.
+
+   ```ts
+   // before
+   map: { …, WAIT_TIMEOUT: 'timeout' }
+   // after
+   map: { …, NOT_IMPLEMENTED: 'not_implemented', WAIT_TIMEOUT: 'timeout' }
+   ```
+
+   The code is thrown only by the new dev-only `onMissingHandler: 'stub'` policy;
+   a vocabulary that is not exhaustive is unaffected.
+
 ## Released migration: 0.90.0
 
 1. `stitchkit.watch.value` is a discriminated union on `kind` — `full`, `delta`,
@@ -15666,6 +15871,7 @@ from the root `stitchkit`.
 | `STITCH_ERROR_STATUS` | const | `code → HTTP status` map for stitchkit's own error codes — [guide](../guide/auth-and-errors.md#stitch-codes-vs-your-codes) |
 | `StitchErrorCode` | _type_ | a code stitchkit itself emits (`keyof STITCH_ERROR_STATUS`) |
 | `isStitchErrorCode` | function | type guard — is a code one of stitchkit's own? |
+| `isRetryableStatus` | function | whether a status class means "the same call could work later" — `408`, `429`, `502`, `503`, `504`, and deliberately not every `5xx` |
 
 ### Pagination
 
@@ -15777,6 +15983,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `implementRegistry` | function | bind one exact contract registry to one exact backend handler registry |
 | `createImplementRegistry` | function | context-typed factory for `implementRegistry` |
 | `ImplementationRegistry` | _type_ | flat literal registry of concrete contracts accepted by `implementRegistry` |
+| `ImplementOptions` | _type_ | `{ onMissingHandler }` — how a binding treats a contract endpoint with no handler |
+| `MissingHandlerPolicy` | _type_ | `'throw'` (default) or `'stub'`, the dev-stand policy that mounts a `501` instead of refusing to start |
 | `KeyedServices` | _type_ | registry result: the mount-ordered `ServiceDef[]` carrying the same services under `.byKey` |
 | `RegistryHandlers` | _type_ | exact backend handler registry inferred from a contract registry |
 | `ExactRegistryHandlers` | _type_ | fail-first handler shape that rejects extra registry and endpoint keys |
@@ -16730,7 +16938,7 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `DimensionCollision` / `SetRequestDimensionsOptions` | _type_ | explicit overwrite, preserve or error policy for dimension keys |
 | `createBoundedLogger` | function | decorate a `StitchLogger` with request context, shared sanitisation, redaction and total bounds |
 | `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 plus sink/redaction configuration |
+| `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'` |
 | `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
 | `Observability` | _type_ | `{ request?, toolCall, getStatus(), flush(bound?): Promise<boolean>, close(bound?) }` with bounded sink lifecycle |
@@ -16784,7 +16992,7 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `truncatePreview` | function | cap a value by serialised size |
 | `measureSize` | function | item count + byte size of a result |
 | `JsonValue` | _type_ | a JSON-serialisable value |
-| `SanitizeOptions` | _type_ | tuning for `redact` / `sanitizePayload` |
+| `SanitizeOptions` | _type_ | tuning for `redact` / `sanitizePayload` — `maxStringLengthByKey` bounds a named key wherever it sits without changing the record-wide bound |
 | `SizeMeasure` | _type_ | the result of `measureSize` |
 
 ---
@@ -17008,6 +17216,48 @@ A native remote-connector auth surface for MCP — [guide](../guide/mcp-and-agen
 | `RefreshData` | _type_ | a stored refresh-token record |
 | `RegisteredClient` | _type_ | a registered OAuth client |
 
+### Durable tool bodies
+
+A mounted tool body can be made restartable without adopting `agent-runtime`: declare a
+factory and `step` / `sleep` / `waitFor` appear in the handler context, backed by whatever
+ledger the application already has.
+
+```ts
+mountAgent(services, { durability: (toolCallId) => myLedgerFor(toolCallId) });
+```
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `ToolDurability` | _type_ | the port a tool body needs: `step`, `sleep`, `waitFor` |
+| `ToolDurabilityFactory` | _type_ | `(toolCallId, signal) => ToolDurability`, called once per call |
+| `DurableJsonValue` | _type_ | what a durable step result may hold — a record is read back in another process, so it must be JSON |
+| `createLocalStepDurability` | function | the durability engine — replay, absolute deadlines, park/deliver — over a two-method ledger the application owns |
+| `StepDurabilityLedger` | _type_ | the two methods an engine needs: `appendEvent`, `readEvents` |
+| `LocalStepDurability` | _type_ | what the engine returns; satisfies `ToolDurability` and adds `deliver` and record introspection for the ledger's owner |
+| `LocalStepDurabilityOptions` | _type_ | `{ store, conversationId, runId, signal?, subscribe?, clock? }` |
+| `AppendAgentStoreEvent` / `ReadAgentStoreEvents` / `AgentStoreEventEnvelope` / `AgentStoreEventPage` | _type_ | the ledger's row shapes, re-exported so a ledger is typed from the entrypoint that consumes it |
+| `AgentToolError` | class | the model-safe envelope a failed agent tool throws |
+| `isAgentToolError` | function | brand check for it — a consumer running its own loop no longer parses the message |
+
+### Catalog stamp
+
+Every advertised tool and every tool result carries the fingerprint of the catalog it came
+from, so a long-lived consumer can see that its own copy is stale **without making a
+request for it**. `createMcpHandler` is stateless by construction and therefore has no
+retained session to push `notifications/tools/list_changed` down; the stamp needs none.
+
+Store the stamp beside the tools when you list them, compare it against the one on every
+result, and re-list when they differ — including on a refusal, which is exactly when a
+stale catalog is the likeliest explanation and the least visible one. The server side
+needs no wiring: every mount stamps what it advertises.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `readMcpCatalogStamp` | function | read a peer's stamp out of `_meta`, or `null` when there is none |
+| `mcpCatalogMeta` | function | the `_meta` fragment a stamped tool or result carries |
+| `MCP_CATALOG_META_KEY` | const | the namespaced `_meta` key (`stitchkit/catalog`) |
+| `McpCatalogStamp` | _type_ | `{ digest, tools }` — the catalog fingerprint and its tool count |
+
 ### MCP Apps (widgets)
 
 Interactive MCP resources — [ADR 0019](../decisions/0019-generic-native-tools.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.90.7",
+  "version": "0.91.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",
@@ -211,7 +211,7 @@
     "build:js": "bun run build:entrypoints && bun scripts/preserve-webpack-ignore.mjs",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly && bun scripts/rewrite-declaration-specifiers.mjs",
     "build": "bun ../../scripts/package-build-lock.ts -- bun run build:unlocked",
-    "build:unlocked": "rm -rf dist && cp ../../CHANGELOG.md ./CHANGELOG.md && bun run build:js && chmod +x dist/upgrade-cli.js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-browser-executes.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs && bun scripts/check-declarations-strict.mjs",
+    "build:unlocked": "rm -rf dist && cp ../../CHANGELOG.md ./CHANGELOG.md && bun run build:js && chmod +x dist/upgrade-cli.js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-browser-executes.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs && bun scripts/check-durability-port-standalone.mjs && bun scripts/check-declarations-strict.mjs",
     "dev": "bun run build:entrypoints -- --watch",
     "prepack": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",