stitchkit 0.94.0 → 0.94.1

package/llms/cli.txt

@@ -1,9 +1,12 @@
-# stitchkit/cli — stitchkit docs slice
+# stitchkit/cli — stitchkit docs slice, part 1 of 2
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
+> Continues in `llms/cli.2.txt`.
 
-Contains: Guide: CLI  (docs/guide/cli.md) · API reference: `stitchkit/cli`  (docs/api/reference.md)
+Parts of this slice:
+- `llms/cli.txt`: Guide: CLI  (docs/guide/cli.md)
+- `llms/cli.2.txt`: API reference: `stitchkit/cli`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: CLI  (docs/guide/cli.md)
@@ -202,6 +205,15 @@ fields in declaration order, so `myapp generate "a fox"` is
 `--prompt "a fox"`. A piped value fills the first required unset field:
 `echo "a fox" | myapp generate`.
 
+A token is an option only when it is a long form (`--name`, `--name=value`,
+`--`) or `-` followed by a letter. Anything else that starts with `-` is data:
+`myapp note a "- item"` fills a positional, and after an option that expects a
+value the next token is that value — `--grep -foo`, `--count -5`. The next
+token is refused as a value only when it is itself an option, so `--grep --json`
+still reports that `--grep` requires a value. A value that cannot be read as
+its field's type is refused naming the flag and what was typed:
+`--tail expects a whole number, got "abc"`.
+
 For a stable shell grammar, declare the default command, short aliases and the
 exact positional fields on `createCli`:
 
@@ -674,6 +686,37 @@ nothing to keep, which is not a failure.
 happens to be at the backup path is a second install of an unverified binary,
 and the day it is used is the day nobody is in a position to check.
 
+### Run it before it replaces anything — `verify`
+
+A digest proves the bytes are the ones published, not that they load. A tool
+that updates itself unattended — a daemon — and installs a build that does not
+start takes its own updater down with it, and every machine is then repaired by
+hand. `verify` is the step between "digest matched" and "target replaced":
+
+```ts
+await applyCliUpdate({
+  asset, targetPath, backupPath,
+  verify: async (candidate, signal) => {
+    const child = Bun.spawn(['bun', candidate, 'version'], { signal, stdout: 'pipe' })
+    const printed = (await new Response(child.stdout).text()).trim()
+    if ((await child.exited) !== 0 || printed !== check.version) {
+      throw new Error(`printed ${printed}, expected ${check.version}`)
+    }
+  },
+  verifyTimeoutMs: 15_000,   // default 30 000
+})
+```
+
+The verified bytes are written beside the target as an executable candidate
+with the target's extension, and `verify` gets its path — a path rather than a
+command, because a JavaScript bundle is started through its runtime. It runs
+before the backup and the replacement. If it throws or outlives
+`verifyTimeoutMs` (its `signal` aborts at the deadline), the candidate is
+removed, the target and any earlier backup are untouched, and the update is
+refused with the reason as its cause. The target is written from the checked
+bytes in memory, never from the candidate file, so nothing the candidate did
+while it ran can change what is installed.
+
 ### Two release tracks
 
 `assertCliPublishable` takes one manifest **or every manifest already
@@ -903,75 +946,3 @@ File-upload (`multipart`) contract endpoints remain CLI-invisible, the same as
 on MCP/Agent: their wire body is not a JSON tool form. Model file-oriented
 application behavior as a managed pathless command, or binary-only behavior as
 a native command. Streaming (SSE) output is not yet piped to stdout.
-
-==============================================================================
-# API reference: `stitchkit/cli`  (docs/api/reference.md)
-==============================================================================
-
-## `stitchkit/cli`
-
-Server-only. Composes contract/runtime managed operations and CLI-only native
-commands into one command-line program. Light by design: needs neither the MCP
-SDK nor the `ai` peer.
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
-| `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
-| `parseCliArgs` | function | argv → typed tool args against a schema (advanced) |
-| `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |
-| `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
-| `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, without the `stitchkit/tools` barrel |
-| `CliArgumentError` | class | the refusal `parseCliArgs` and the view flags raise; a CLI reports it and exits `2` |
-| `renderCliView` | function | compute an aggregate over a result (`--count-by`, `--sum`, `--top`, `--table`) — [guide](../guide/cli.md#aggregate-views) |
-| `createCliProfileStore` | function | named `0600` credential profiles resolved by name, with the never-substitute rule built in — [guide](../guide/cli.md#named-profiles) |
-| `CliProfileError` | class | an `AppError` refusing a named profile that is missing, unreadable or shared between users |
-| `renderCliInstaller` | function | generate the one-line installer from a build manifest, with the URL and digest substituted — [guide](../guide/cli.md#distribution-and-self-update) |
-| `checkCliUpdate` | function | bounded, interval-limited, never-throwing check for a newer published build |
-| `applyCliUpdate` | function | download, verify the decompressed digest and replace the binary by rename |
-| `assertCliPublishable` | function | refuse republishing one version from a different commit — takes one manifest or every manifest already published, because the promise a version makes does not stop at a channel boundary |
-| `rollbackCliUpdate` / `CliRollbackConfig` / `RolledBackCliUpdate` | function / _types_ | put the kept previous build back, digest-checked first and written by the same atomic rename the update uses |
-| `signCliManifest` / `verifyCliManifest` / `cliManifestSigningPayload` | function | Ed25519 over `{name, version, commit, builtAt, assets[]}` — every asset's digest included, so the chain closes on the file that executes |
-| `cliSignatureAccepted` / `CliSignatureVerdict` | function / _type_ | `valid` \| `unenforced` \| `missing` \| `unknown-key` \| `invalid`; `unenforced` keeps an unpinned build updating while making the absence of a check visible |
-| `CliTrustRoot` / `CliSigningKey` / `CliBuildSignature` / `CliBuildSignatureSchema` | _types_ / schema | the keys a build trusts, by id, and the detached signature a manifest carries |
-| `selectCliBuildAsset` | function | the asset for one target, or `undefined` |
-| `currentCliBuildTarget` | function | `{ platform, arch }` of the running process |
-| `formatCliBuildStamp` | function | one line saying what the running build is |
-| `compareCliVersions` | function | compare two versions, or `undefined` when they are not comparable |
-| `CliBuildManifestSchema` / `CliBuildManifest` | schema / _type_ | name, version, commit, build time and assets |
-| `CliBuildAssetSchema` / `CliBuildAsset` | schema / _type_ | one download; `size` and `sha256` describe the **decompressed** bytes |
-| `CliBuildTargetSchema` / `CliBuildTarget` | schema / _type_ | `{ platform, arch }` |
-| `CliBuildStampSchema` / `CliBuildStamp` | schema / _type_ | the version/commit/build time carried inside a binary |
-| `CliInstallerConfig` | _type_ | manifest, binary name, default install directory, and an optional `asset` — omit it for one script that selects the target by `uname` |
-| `CliUpdateCheckConfig` / `CliUpdateCheck` | _type_ | check inputs, and its four answers — `skipped`, `current`, `outdated`, `unknown` |
-| `CliUpdateApplyConfig` / `AppliedCliUpdate` | _type_ | apply inputs and the replaced path, byte count and digest |
-| `CliProfileStore` / `CliProfileStoreConfig` / `ResolvedCliProfile` | _type_ | the profile store, its directory/schema/hint config, and one resolution |
-| `CliResultView` | _type_ | the requested view — `count`, `sum`, or `records` (ordered and/or table-rendered) |
-| `CliViewOutput` | _type_ | a JSON value, or the one human-facing text shape |
-| `CliGlobalOptionsParse` | _type_ | `{ argv, globals }` returned by `extractCliGlobalOptions` |
-| `CliArgvRoute` | _type_ | `{ command, commandArgv, topLevelHelp, version, error? }` returned by `routeCliArgv` |
-| `pollUntilDone` | function | the generic `--wait` poller (advanced) |
-| `emitResult` | function | write a pretty or compact `ToolResult` record to stdout/stderr + exit code (advanced) |
-| `cliExitCode` | function | the exit code a result earns, from the same table, without writing anything — so an in-process run and the printed path cannot disagree |
-| `createCliInvoker` / `CliInvoker` / `CliInvokerConfig` / `CliInvocationResult` / `CliInvokerCommand` / `cliInvocationResult` | function / _types_ | compile the managed surface once and run parsed calls against it in process — no argv round-trip, no child process, no writing |
-| `defineCliStreamCommand` / `CliStreamCommandConfig` / `CliStreamAnswer` / `CliStreamHooks` / `runCliStream` | function / _types_ | one operation per JSON line of stdin, answered with the same `id`; a bad line answers and the stream continues |
-| `defineCliBatchCommand` / `CliBatchCommandConfig` | function / _type_ | the same loop, resumable: a recorded line replays, a line whose content changed under the same id is refused |
-| `readCliCheckpoint` / `writeCliCheckpoint` / `CliCheckpoint` / `CliCheckpointEntry` | function / _types_ | the batch's record — id plus a digest of the line, written by atomic rename after every line |
-| `DEFAULT_EXIT_CODES` | const | the default `ToolResult.code` → exit-code map |
-| `CliConfig` | _type_ | config for `createCli`; `defaultCommand`, `globalOptions`, `optionAliases` and `positionals` define the shared command presentation policy |
-| `CliPresentationPolicyConfig` | _type_ | shared command presentation-policy subset of `CliConfig` |
-| `CliSurfaceSource` | _type_ | static service/runtime array or identity-dependent factory |
-| `CliCommandDefinition` | _type_ | native command definition union |
-| `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
-| `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output and typed optional `present` / successful `exitCode` callbacks |
-| `CliCommandDefinitionWithoutOutput` | _type_ | native void command without an output contract |
-| `CliCommandContext` | _type_ | parsed input, framework run options, the application's `globals` and stdout/stderr writers |
-| `CliRunOptions` | _type_ | parsed global flags (`--json` compacts success/error records, `--wait`, …) |
-| `ParsedCliArgs` | _type_ | result of `parseCliArgs` |
-| `CliWaitConfig` | _type_ | per-command `--wait` polling config; optional `failed(result)` maps a terminal domain failure to `WAIT_FAILED` and a non-zero exit |
-| `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
-| `PollParams` | _type_ | params for `pollUntilDone` |
-| `CliWriters` | _type_ | stdout/stderr sinks for `emitResult` |
-| `EmitOptions` | _type_ | options for `emitResult` |
-
----

package/llms/contract.txt

@@ -213,7 +213,7 @@ endpoint that can never be a tool (a raw response, a stream, `responseMeta`,
 | `tool.` | Purpose |
 |---------|---------|
 | `name` | explicit tool name (default: a verb-aware derivation, below) |
-| `view` | a different answer on MCP / agent / CLI — input defaults and a projected, separately validated output; declared only with `withToolView` — see [MCP & agents](./mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
+| `view` | a different call or answer on MCP / agent / CLI — input defaults alone, or with a projected, separately validated output; declared only with `withToolView` — see [MCP & agents](./mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
 | `ui` | MCP Apps widget for the tool's results — see [MCP & agents](./mcp-and-agents.md) |
 | `annotations` | MCP behavioural hints (`readOnlyHint`, `destructiveHint`, `title`, …) |
 | `mcp` | elicitation rounds asked before the handler runs (`inputRequired`) |
@@ -518,12 +518,12 @@ from the root `stitchkit`.
 | `PathParams` | _type_ | infer named `:segments` and a terminal `*wildcard` from a path literal as string params |
 | `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
 | `EndpointDef` | _type_ | a single endpoint definition; `output` declares JSON response presence (`null` is data, `undefined` is invalid); `safelistedBody: true` admits the JSON body as `text/plain` from an allow-listed `Origin` — [guide](../guide/server.md#safelisted-request-bodies-beacons) |
-| `withToolView` | function | declare an endpoint's answer on the tool surface (MCP, AGENT, CLI): input `defaults`, a view `output` and an optional `project`, typed against the endpoint's own schemas; HTTP keeps the full answer — [guide](../guide/mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
+| `withToolView` | function | declare an endpoint's call and answer on the tool surface (MCP, AGENT, CLI): input `defaults`, and optionally a view `output` and a `project`, typed against the endpoint's own schemas; HTTP keeps the full answer — [guide](../guide/mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
 | `EndpointToolOptions` | _type_ | an endpoint's `tool` group — `name`, `view`, `ui`, `annotations`, `mcp`: what the tool surfaces read that HTTP does not |
 | `EndpointToolView` | _type_ | the stored shape of a tool view (`MethodDef.toolView`) |
 | `DeclaredToolView` | _type_ | a tool view as `withToolView` produces it — the only form `tool.view` accepts |
 | `WithToolView` | _type_ | the endpoint `withToolView` returns: its own tool options plus the declared view in `tool.view` — name it when a helper returns such an endpoint |
-| `ProjectedToolView` / `ReshapedToolView` / `SlicedToolView` | _type_ | the three forms `withToolView` accepts: own schema + `project`, `project` inside the full schema, a slice by `output` |
+| `DefaultsOnlyToolView` / `ProjectedToolView` / `ReshapedToolView` / `SlicedToolView` | _type_ | the four forms `withToolView` accepts: input `defaults` alone with the full answer, own schema + `project`, `project` inside the full schema, a slice by `output` |
 | `ToolViewCall` | _type_ | what `project` is told besides the full result: the parsed `input` and the `source` |
 | `ToolViewSliceMismatch` | _type_ | the compile-time refusal of a slice whose schema does not accept the full output |
 | `ToolViewNeedsToolTransport` | _type_ | the compile-time refusal of a view on an `expose: ['HTTP']` endpoint |

package/llms/files.txt

@@ -26,5 +26,8 @@ available from `stitchkit/contract`.
 | `ManagedFileError` / `ManagedFileErrorCode` | class / _type_ | stable boundary failures; registered `FILE_*` mistakes are caller-safe while `FILE_IO_ERROR` remains internal |
 | `ManagedFileInspector` | _type_ | bounded-prefix read/write inspection callback with a finite cancellation signal that cannot own path or size |
 | `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
+| `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
+| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
+| `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 
 ---

package/llms/tools.2.txt

@@ -1,16 +1,102 @@
-# stitchkit/tools — stitchkit docs slice, part 2 of 2
+# stitchkit/tools — stitchkit docs slice, part 2 of 3
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
+> Continues in `llms/tools.3.txt`.
 
 Parts of this slice:
 - `llms/tools.txt`: Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
-- `llms/tools.2.txt`: Guide: MCP & agents  (docs/guide/mcp-and-agents.md) · API reference: `stitchkit/tools`  (docs/api/reference.md)
+- `llms/tools.2.txt`: Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
+- `llms/tools.3.txt`: API reference: `stitchkit/tools`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: MCP & agents  (docs/guide/mcp-and-agents.md)  (continued)
 ==============================================================================
 
+## A different answer for tools — `withToolView`
+
+An admin page wants the full record; a model wants a card. Every byte of a
+tool result enters the model's context and stays in its history, and personal
+fields a task does not need are better never shown to it. Two endpoints on one
+path (one `expose: ['HTTP']`, one for the tools) duplicate the description, the
+schemas and the handler; branching on `ctx.source` teaches every handler about
+transports and still advertises the full output schema.
+
+A **tool view** declares the difference on the endpoint instead. Most often the
+difference is only the call — a model needs a lighter one, and the answer keeps
+its one shape:
+
+```ts
+import { defineContract, withToolView } from 'stitchkit';
+
+export const items = defineContract({ prefix: 'items' }, {
+  list: withToolView(
+    {
+      method: 'GET', path: '/:slug/items', desc: 'List items', tool: { name: 'db_items' },
+      input: ItemsQuery,        // include: z.array(...).default(['relations'])
+      output: ItemsResponse,    // one answer on HTTP and on the tools
+    },
+    { defaults: { include: [] } },   // what a tool call gets when it passes nothing
+  ),
+});
+```
+
+When the answer itself differs, the view carries its own schema too:
+
+```ts
+import { defineContract, withToolView } from 'stitchkit';
+
+export const users = defineContract({ prefix: 'users' }, {
+  list: withToolView(
+    {
+      method: 'GET', path: '/', desc: 'List users', tool: { name: 'user_list' },
+      input: UserListQuery,        // include: z.array(...).default(['profile', 'stats'])
+      output: UserListResponse,    // HTTP, OpenAPI and the typed client — unchanged
+    },
+    {
+      defaults: { include: [] },                          // what a tool call gets when it passes nothing
+      output: UserCardList,                               // the tool answer and its schema
+      project: (full, { input }) => ({ items: full.items.map(toCard) }),  // optional: without it, `output` slices
+    },
+  ),
+});
+```
+
+- **One handler, one parser.** `defaults` joins the tool call's arguments
+  *before* the endpoint's own `input` parses them, so the handler receives an
+  ordinary `input` — `include: []` from a tool, the HTTP default from HTTP — and
+  loads only what was asked for. An explicit argument wins over the default.
+- **The answer is derived, then checked.** The handler's result is validated
+  against the full `output` first, as always; then `project` (a pure,
+  synchronous function of the full result and the parsed input) or a slice by
+  the view's `output`, then validation against the view's schema. A projection
+  that throws, returns a Promise or breaks its schema is `INTERNAL_SERVER_ERROR`
+  — a server fault, like any output mismatch.
+- **Where it applies.** The MCP, agent and CLI mounts answer with the view;
+  `outputSchema`, `structuredContent`, the advertised input `default`, the
+  catalog stamp and the surface snapshot follow it. HTTP, OpenAPI, the typed
+  client and the in-process [`createToolInvoker`](#in-process-calls--createtoolinvoker)
+  keep the full answer — code, not a model, is calling there.
+- **Four forms, one helper.** With `defaults` alone the call changes and the
+  answer is the full `output`, validated by it and advertised as it. With
+  `output` and `project` the answer has its own schema. With `project` alone it
+  reshapes values inside the full schema. With `output` alone it is a slice, and
+  the full result must fit that schema — `withToolView` refuses the endpoint at
+  compile time when it does not.
+- **Exposure.** A view needs a tool transport. With `createContractFactory({
+  toolExposure: 'explicit' })` an endpoint without `expose` is HTTP-only, so an
+  endpoint with a view names its tool transports in `expose`.
+- **What it refuses.** `defineContract` rejects a view on an endpoint with no
+  tool transport or no full `output`, on a raw, `rawBody`, multipart,
+  `responseMeta` or streaming endpoint, a view that declares no `defaults`,
+  `output` or `project` — it would change nothing — and a default for a key the input does not have, for a path
+  param, or with a value the input would reject.
+
+A projection adds nothing the full result does not carry: a field the tool
+answer needs belongs in the full answer, loaded by the handler. Keys a
+projection returns beyond its schema are reported by `onOutputStrip`; a slice
+removes keys on purpose and is not reported. → [ADR 0196](../decisions/0196-a-tool-answer-is-a-declared-view.md)
+
 ## AI agents — `mountAgent`
 
 `mountAgent` remains the low-level path when the application owns its own model
@@ -559,280 +645,3 @@ A contract handler runs the same for an HTTP request, an MCP tool call and an
 agent tool call. `ctx.source` (`'http'` · `'mcp'` · `'agent'`) tells it which —
 the rest of the context (`params`, `input`, anything `context` injects) is
 identical. Write the handler once; it serves every surface.
-
-==============================================================================
-# API reference: `stitchkit/tools`  (docs/api/reference.md)
-==============================================================================
-
-## `stitchkit/tools`
-
-Server-only. Turns contracts into MCP and AI-agent tools. MCP server surfaces
-need the `@modelcontextprotocol/server` v2 peer; MCP hosts/tests use the separate
-`@modelcontextprotocol/client` package. Agent surfaces need the `ai` peer.
-
-Framework-owned MCP tools advertise the exact declared output schema and return
-the validated value unchanged as `structuredContent`, including arrays, scalars
-and `null`. Tools without an output contract advertise and return no structured
-payload.
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `createMcpHandler` | function | a stateless dual-era Streamable-HTTP MCP handler — [guide](../guide/mcp-and-agents.md#mcp--createmcphandler) |
-| `createMcpHttpRoute` | function | framework-owned `RawRoute` adapter for an MCP HTTP handler |
-| `createStdioMcpServer` | function | a complete stdio MCP server — [guide](../guide/mcp-and-agents.md#mcp-over-stdio--createstdiomcpserver) |
-| `bindStdioProcessSignals` | function | explicitly bind OS signals to one close-only stdio handle — [guide](../guide/testing-and-deployment.md#stdio-process-signals) |
-| `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces; no-auth configs omit the second argument |
-| `mountMcp` | function | add contract tools to an existing `McpServer` — [guide](../guide/mcp-and-agents.md#mountmcp) |
-| `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service; failed executions reject through the SDK tool-error channel with a safe typed envelope, while successful output is never classified by field name — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
-| `defineRuntimeTool` | function | define one validated pathless operation for explicit MCP, Agent and/or CLI surfaces — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
-| `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
-| `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner; use peer-free `stitchkit/tools/invoker`, or the full `stitchkit/tools` adapter barrel — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
-| `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
-| `mountViewFile` | function | a native multimodal "view file" MCP tool |
-| `resolveMedia` | function | resolve a media reference for a tool result |
-| `validateMcpSchemas` | function | object-shaped assertion over the exact advertised schema surface — compatibility, typed properties and portable formats ([guide](../guide/mcp-and-agents.md#mcp-schema-validation-profile)) |
-| `listToolNames` | function | every contract/runtime tool name with origin, identity and transports — for stable snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
-| `listContractToolNames` | function | the same listing straight from contracts — no handlers or stub services needed |
-| `describeToolCatalog` | function | inspect the exact model-facing names, source identities, schema byte sizes and deferred state; an explicit total byte budget fails closed |
-| `ToolCatalogConfig` / `ToolCatalogEntry` | _type_ | catalog source, transport, optional explicit schema budget and one inspectable result row |
-| `McpHandlerConfig` | _type_ | server surface plus stateless HTTP transport config |
-| `McpHttpConfig` | _type_ | HTTP auth, protected-resource, legacy-era and security options |
-| `McpHttpHandler` | _type_ | framework-owned `{ fetch(request), close() }` lifecycle |
-| `McpHttpSecurityConfig` | _type_ | Fetch-boundary Host and Origin allowlists |
-| `McpLegacyPolicy` | _type_ | `'serve' \| 'reject'` protocol-era compatibility policy |
-| `McpStdioHandle` | _type_ | closeable official stdio transport handle |
-| `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
-| `StdioCloseTarget` | _type_ | minimal close-only target accepted by `bindStdioProcessSignals` |
-| `StdioProcessSignalsOptions` | _type_ | signal source, close callbacks and phased error reporting |
-| `StdioProcessSignalsBinding` | _type_ | close-only signal binding with observed `promise` and listener `close()` |
-| `StdioProcessSignalsErrorPhase` | _type_ | `'prepare' \| 'close' \| 'complete'` reporting phase |
-| `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
-| `McpServerSharedConfig` | _type_ | transport-neutral options shared by direct and finite surface configs |
-| `McpServer` | _type_ | official split-SDK server instance accepted by raw extension points |
-| `DirectMcpSurfaceConfig` | _type_ | static or identity-dynamic `services` / `runtimeTools` source |
-| `FiniteMcpSurfaceConfig` | _type_ | bounded `surfaces` registry plus typed selector |
-| `McpSurfaceDefinition` | _type_ | one immutable `{ services, runtimeTools }` MCP surface |
-| `McpSurfaceRegistry` | _type_ | finite keyed surface registry for eager preparation |
-| `StdioAuthConfig` | _type_ | startup identity composed into `StdioMcpServerConfig` |
-| `McpMountConfig` | _type_ | config for `mountMcp` |
-| `McpSchemaValidationConfig` | _type_ | shared `{ policy, requireTypedProperties, allowUntyped, requirePortableFormats, allowFormats }` profile |
-| `ValidateMcpSchemasConfig` | _type_ | standalone validation profile plus `services`, `extend`, flattening and logger |
-| `RuntimeToolDefinition` | _type_ | transport-neutral pathless operation with identity, schemas, handler and optional presenters |
-| `RuntimeToolDefinitionBase` | _type_ | common name, identity, input, exposure and MCP metadata fields |
-| `RuntimeToolDefinitionWithOutput` | _type_ | runtime definition whose handler and presenters share a validated output type |
-| `RuntimeToolDefinitionWithoutOutput` | _type_ | runtime definition with a void handler and no presentation callbacks |
-| `RuntimeToolFactory` | _type_ | identity/context-bound runtime-tool definition factory |
-| `RuntimeToolFactoryConfig` | _type_ | factory service identity and context schema |
-| `RuntimeToolFactoryDefinitionWithOutput` | _type_ | factory-authored runtime tool with a validated output schema |
-| `RuntimeToolFactoryDefinitionWithoutOutput` | _type_ | factory-authored void runtime tool without presenters |
-| `RuntimeToolFactoryHandlerContext` | _type_ | parsed factory context plus parsed tool input |
-| `RuntimeToolFactoryIdentityFields` | _type_ | per-tool action, semantic method and optional identity metadata |
-| `RuntimeToolIdentity` | _type_ | `{ serviceName, action, scope?, method, meta? }` for runtime lifecycle/audit |
-| `RuntimeToolHandlerContext` | _type_ | runtime context with the definition's parsed input |
-| `RuntimeToolOutput` | _type_ | output inferred from a runtime tool's optional Zod schema |
-| `RuntimeToolPresenters` | _type_ | optional MCP and AI SDK `toModelOutput` presentation callbacks |
-| `RuntimeMcpPresentation` | _type_ | MCP content/metadata result without framework-owned `structuredContent` or `isError` |
-| `RuntimeMcpInput` | _type_ | typed accepted multi-round input for an opted-in runtime tool |
-| `OAuthClientRegistrationConfig` | _type_ | deterministic pre-registered → CIMD → explicit-DCR client resolution |
-| `CimdClientMetadata` | _type_ | validated Client ID Metadata Document |
-| `CimdClientMetadataFetcher` | _type_ | injectable secure network boundary for metadata loading |
-| `CimdFetchResponse` | _type_ | bounded metadata fetch result passed across the injectable network boundary |
-| `CimdFetchPolicy` | _type_ | CIMD timeout, redirect and size limits |
-| `CimdCachePolicy` | _type_ | bounded HTTP-aware cache policy: separate positive/negative pools (`maxEntries`), per-client and server-wide resolution rate limits (`maxResolutionsPerClient` / `maxResolutions` per `resolutionWindowMs`) |
-| `CimdCacheEvent` | _type_ | observable CIMD cache hit, miss, revalidation and eviction event |
-| `createSecureClientMetadataFetcher` | function | production HTTPS, DNS/IP-pinned CIMD fetcher |
-| `RuntimeAgentModelOutput` | _type_ | AI SDK model-facing text/JSON/content output returned by `present.agent` |
-| `AgentMountConfig` | _type_ | config for `mountAgent` |
-| `AgentToolRegistry` / `AgentToolRegistryBuilder` / `AgentToolRegistryInput` | _type_ | the composed runtime surface and its builder: declared defaults, `replace`/`disable` by name, and the exact `{ tools, names }` a mount receives |
-| `defineToolRegistry` | function | compose runtime tools over one declared default set; an unknown `replace`/`disable` name is refused instead of silently leaving the default in place |
-| `AgentContext` | _type_ | the context merged into agent tool handlers |
-| `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
-| `ToolExtend` | _type_ | extra-args extension for `mountMcp` / `mountAgent` |
-| `ToolLifecycle` | _type_ | `beforeHandle` / `afterHandle` gate for tool calls — [guide](../guide/mcp-and-agents.md#guarding-tools--lifecycle) |
-| `ToolExecutionControlReason` | _type_ | internal managed-execution stop reason: stale run or requested interruption |
-| `ToolExecutionControlError` | class | control-flow error used to unwind a superseded managed tool call without presenting it as a model-facing tool failure |
-| `isToolExecutionControlError` | function | narrow an unknown thrown value to the managed execution control error |
-| `ToolOperation` | _type_ | executable path-free operation shape shared by contract and framework-native runners |
-| `ToolCallHooks` | _type_ | object-shaped `beforeToolCall` / `afterToolCall` / `onToolError` observability hooks; the raw thrown value reaches the last two as `error` ([guide](../guide/observability.md#the-cause-behind-a-failed-tool-call)) |
-| `BeforeToolCallOptions` | _type_ | `{ toolName, args, context, endpoint }` passed before execution |
-| `AfterToolCallOptions` | _type_ | completed call options plus `{ result, durationMs, error? }` |
-| `ToolErrorOptions` | _type_ | `{ toolName, error, context, endpoint }` for a thrown handler-path value |
-| `ErrorHintFn` | _type_ | `(toolName, errorCode) => string \| null` — a per-tool recovery hint, shared by every mount |
-| `ToolResult` | _type_ | the result of one tool call |
-| `ToolInvoker` | _type_ | immutable compiled dispatcher (`names`, envelope `invoke`, throwing `invokeOrThrow`) |
-| `ToolInvokerConfig` | _type_ | compile-time exposure, extension and presentation options |
-| `ToolInvocationOptions` | _type_ | per-call source, context, lifecycle, hooks and output-strip reporter |
-| `ToolCallContext` | _type_ | the context every tool hook receives — `{ source, mcp? }` plus whatever the mount's `context` added |
-| `ViewFileOptions` | _type_ | shared URL/managed-file-boundary policy for `defineViewFileTool`, `mountViewFile` and `resolveMedia` |
-| `ViewFileOutput` | _type_ | neutral managed batch result with multimodal `content` and per-item `errors` |
-| `ViewFileInputSchema` | constant | fixed one-or-many media path/URL input schema |
-| `ViewFileOutputSchema` | constant | Zod schema for the neutral managed view-file batch result |
-| `ViewFileErrorSchema` | constant | Zod schema for one structured per-item view failure |
-| `McpAnnotations` | _type_ | MCP annotations on a media result |
-| `McpAnnotationsSchema` | constant | Zod schema for MCP media annotations |
-| `McpMediaContentSchema` | constant | Zod schema for text/image/audio media content |
-| `CollectToolsConfig` | _type_ | options for `collectTools` |
-| `findUntypedProperties` | function | every property in a JSON Schema with no `type`/`enum`/`$ref` — what a model is shown and cannot obey ([guide](../guide/mcp-and-agents.md)) |
-| `UntypedProperty` | _type_ | one such property — `{ path, description? }` |
-| `findNonPortableFormats` | function | deep finder for formats outside the portable MCP/AJV baseline |
-| `NonPortableFormat` | _type_ | one `{ path, format }` portability finding |
-| `PORTABLE_JSON_SCHEMA_FORMATS` | constant | portable-format baseline used by MCP validation |
-| `ToolNameEntry` | _type_ | one `listToolNames` row — `{ kind, name, service, method, transports }` |
-| `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
-| `McpMediaContent` | _type_ | a multimodal MCP content item |
-
-### Native tools
-
-Generic host-supplied operations — managed definitions for the canonical
-runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `defineDownloadTool` | function | define a guarded, size-capped managed download for MCP/Agent `runtimeTools` |
-| `defineUploadTool` | function | define a typed managed local-file upload for MCP/Agent `runtimeTools` |
-| `defineWaitTool` | function | define a typed, cancellable managed polling operation for MCP/Agent `runtimeTools` |
-| `defineViewFileTool` | function | define a guarded, batch-capped managed multimodal operation for MCP/Agent `runtimeTools` |
-| `DefineDownloadToolConfig` | _type_ | Zod input, stable identity, URL resolver, storage policy and presenters for `defineDownloadTool` |
-| `DefineUploadToolConfig` | _type_ | stable identity, typed output, upload callback and presenters for `defineUploadTool` |
-| `DefineWaitToolConfig` | _type_ | Zod input/state, identity, poll/done/timeout policy and presenters for `defineWaitTool` |
-| `DefineViewFileToolConfig` | _type_ | identity, media security policy and optional presenters for `defineViewFileTool` |
-| `ManagedNativeToolConfig` | _type_ | shared name, description, identity, exposure and annotations for managed native factories |
-| `NativeToolIdentity` | _type_ | pathless service/action/scope/meta identity; semantic method is factory-owned |
-| `ManagedWaitRender` | _type_ | optional managed wait terminal text and failure classification |
-| `UploadToolInputSchema` | constant | fixed `{ path: string }` input schema for `defineUploadTool` |
-| `defineAsyncOperation` | function | runtime-only start/status/wait plus configured cancel/result/artifacts definitions; see the [durable application-owned recipe](../guide/mcp-and-agents.md#durable-application-owned-execution) |
-| `defineAsyncOperationContract` | function | define one canonical Zod-first HTTP contract for start/status/wait plus optional capabilities; execution and recovery remain application-owned |
-| `bindContractAsyncOperation` | function | bind literal methods from an existing contract without creating another HTTP surface |
-| `createAsyncOperationSnapshotSchema` | function | canonical pending/running/succeeded/failed/cancelled Zod snapshot |
-| `AsyncOperationSnapshotSchema` | _type_ | the snapshot union `createAsyncOperationSnapshotSchema` returns when no `progress` schema is configured |
-| `AsyncOperationSnapshotSchemaWithProgress` | _type_ | the same union with the configured `progress` schema optional on every phase |
-| `AsyncOperationCancelResultSchema` | constant | validated accepted/already_terminal/rejected cancellation result |
-| `AsyncOperationCancelResult` | _type_ | validated cancel capability result |
-| `AsyncOperationCancelCapability` | _type_ | optional typed domain cancellation callback |
-| `AsyncOperationCapability` | _type_ | generated capability-name union |
-| `AsyncOperationStartDefinition` / `AsyncOperationFollowDefinition` | _type_ | generated runtime definition types |
-| `AsyncOperationIdentity` | _type_ | shared service/action/scope/meta identity for an operation |
-| `AsyncOperationOutputCapability` | _type_ | optional result/artifact schema plus handler |
-| `RuntimeAsyncOperationConfig` | _type_ | runtime-only descriptor configuration |
-| `RuntimeAsyncOperation` | _type_ | inferred generated definitions and schemas |
-| `AsyncOperationContractConfig` | _type_ | canonical contract config where start returns the operation id; optional `expose` names the transports per capability, because this contract is built inside the framework and never passes through a consumer's `toolExposure: 'explicit'` factory |
-| `AsyncOperationContractWithStartOutputConfig` | _type_ | canonical contract config with an application start envelope and typed id extractor |
-| `DefinedAsyncOperationContract` | _type_ | generated contract, capability keys, schemas and parsed adapters |
-| `ContractAsyncOperationConfig` | _type_ | literal contract method binding and handlers |
-| `AdaptedContractAsyncOperationConfig` | _type_ | existing-contract binding with explicit id and per-capability input adapters |
-| `BoundAdaptedContractAsyncOperation` | _type_ | inferred adapted binding with parsed id/input projectors |
-| `AdaptedContractAsyncOperationStartKey` | _type_ | existing-contract keys with a declared start output |
-| `AdaptedContractAsyncOperationFollowKey` | _type_ | existing-contract keys with both input and output schemas |
-| `AdaptedContractAsyncOperationWaitKey` | _type_ | adapted follow-up keys whose output matches the selected status snapshot |
-| `ContractAsyncOperationInputAdapters` | _type_ | guaranteed direct-binding status/wait input adapters plus configured optional capabilities |
-| `ContractAsyncOperationKeys` | _type_ | literal method-key union of a bound contract |
-| `ContractAsyncOperationStartKey` | _type_ | direct-binding start keys whose declared ID schema has stable input/output |
-| `ContractAsyncOperationFollowKey` | _type_ | contract keys whose input schema type matches the selected start output |
-| `ContractAsyncOperationWaitKey` | _type_ | follow-up keys whose output schema type also matches the selected status output |
-| `composeToolLifecycle` | function | ordered composition of tool before/after phases |
-| `mountDownload` | function | raw MCP "download a URL to disk" adapter (SSRF-guarded, size-capped) |
-| `mountUpload` | function | raw MCP "upload a local file" adapter |
-| `mountWait` | function | raw MCP generic `--wait`-style polling adapter |
-| `DownloadToolConfig` | _type_ | config for `mountDownload` |
-| `UploadToolConfig` | _type_ | config for `mountUpload` |
-| `WaitToolConfig` | _type_ | config for `mountWait` |
-
-### OAuth 2.1 provider
-
-A native remote-connector auth surface for MCP — [guide](../guide/mcp-and-agents.md#oauth-21--a-native-remote-connector).
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `mountOAuthProvider` | function | the OAuth 2.1 provider routes (DCR, PKCE, token) |
-| `oauthProtectedResourceRoute` | function | the RFC 9728 protected-resource-metadata route |
-| `protectedResourceMetadataUrl` | function | build the metadata URL for a resource |
-| `wwwAuthenticateHeader` | function | build the `WWW-Authenticate` challenge header |
-| `PROTECTED_RESOURCE_PATH` | const | the well-known metadata path |
-| `OAuthProviderConfig` | _type_ | config for `mountOAuthProvider` |
-| `ProtectedResourceConfig` | _type_ | config for `oauthProtectedResourceRoute` |
-| `ApplicationType` | _type_ | DCR `application_type` — `'native'` (loopback allowed) \| `'web'` (https only) |
-| `AuthCodeData` | _type_ | a stored authorization-code record |
-| `AuthRequest` | _type_ | a parsed authorization request |
-| `ClientMetadata` | _type_ | dynamic-client-registration metadata |
-| `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).
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `mountMcpResource` | function | mount an MCP Apps widget resource |
-| `inlineMcpAppBundle` | function | inline a built widget bundle into a resource |
-| `EXT_APPS_BUNDLE_PLACEHOLDER` | const | the placeholder token `inlineMcpAppBundle` replaces |
-| `RESOURCE_MIME_TYPE` | const | the MCP Apps resource MIME type |
-| `McpResourceDef` | _type_ | an MCP Apps resource definition |
-| `McpAppResourceMeta` | _type_ | resource `_meta` for an MCP App |
-| `McpAppCsp` | _type_ | the widget content-security policy |
-
-### Introspection & internals
-
-Advanced building blocks — the shared machinery the mounts are built on.
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `collectTools` | function | resolve a service's methods to mountable tools (the shared resolver) |
-| `createToolLogger` | function | a ready `afterToolCall` that logs every tool call — [guide](../guide/mcp-and-agents.md#logging-tool-calls--createtoollogger) |
-| `summarizeTransports` | function | mixed contract/runtime operation counts and per-source breakdown for a boot-time summary |
-| `buildToolManifest` | function | transport-aware searchable `{ name, description, inputSchema }` rows from a mixed surface |
-| `ToolLoggerConfig` | _type_ | config for `createToolLogger` |
-| `ToolCallRecord` | _type_ | the structured record `createToolLogger` passes to `onRecord` |
-| `TransportSummary` | _type_ | `{ contractServices, runtimeTools, totals, sources }` from `summarizeTransports` |
-| `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
-| `ToolSurfaceDefinition` | _type_ | shared object-shaped `{ services?, runtimeTools? }` introspection surface |
-| `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
-| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
-| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; divergent fields retain every provable base kind in a deterministic `type` array, and the projection never executes validation |
-| `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |
-| `MountableTool` | _type_ | one operation with separate executable CLI argument schema and model-facing presentation schema |
-| `ToolManifestEntry` | _type_ | one `buildToolManifest` row |
-
----