stitchkit 0.90.8 → 0.91.0

package/llms-full.txt

@@ -66,11 +66,11 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 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.
@@ -3482,6 +3519,102 @@ schema and annotations, and nothing else — it moves when the contract moves an
 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
@@ -5511,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.
 
@@ -9903,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`,
@@ -10031,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`.
@@ -11003,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)
@@ -11971,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`,
@@ -15702,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
 
@@ -15813,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 |
@@ -16766,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 |
@@ -16820,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` |
 
 ---
@@ -17044,6 +17216,29 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.90.8",
+  "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",

package/dist/index-7rkhw9ec.js

@@ -1,34 +0,0 @@
-// src/tools/agent-tool-error.ts
-var AGENT_TOOL_ERROR_BRAND = Symbol.for("stitchkit.AgentToolError");
-
-class AgentToolError extends Error {
-  output;
-  constructor(output, cause) {
-    let message = "Tool execution failed";
-    try {
-      message = JSON.stringify(output);
-    } catch {}
-    super(message, cause === undefined ? undefined : { cause });
-    this.name = "AgentToolError";
-    this.output = output;
-    Object.defineProperty(this, AGENT_TOOL_ERROR_BRAND, { value: true });
-  }
-}
-function isAgentToolError(value) {
-  return typeof value === "object" && value !== null && AGENT_TOOL_ERROR_BRAND in value;
-}
-
-// src/tools/durability-context.ts
-var contexts = new WeakMap;
-function createToolDurabilityContext(factory) {
-  const context = {};
-  contexts.set(context, factory);
-  return context;
-}
-function resolveToolDurability(context, callId, signal) {
-  if (typeof context !== "object" || context === null)
-    return;
-  return contexts.get(context)?.(callId, signal);
-}
-
-export { AgentToolError, isAgentToolError, createToolDurabilityContext, resolveToolDurability };