stitchkit 0.93.0 → 0.94.0

package/llms/tools.2.txt

@@ -0,0 +1,838 @@
+# stitchkit/tools — stitchkit docs slice, part 2 of 2
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+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)
+
+==============================================================================
+# Guide: MCP & agents  (docs/guide/mcp-and-agents.md)  (continued)
+==============================================================================
+
+## AI agents — `mountAgent`
+
+`mountAgent` remains the low-level path when the application owns its own model
+loop and conversation state. For the optional Stitchkit-owned run/history loop,
+see [Agent application runtime](./agent-runtime.md).
+
+`mountAgent` turns a service into a Vercel AI SDK `ToolSet`, ready for
+`generateText` / `streamText`:
+
+```ts
+import { mountAgent } from 'stitchkit/tools'
+import { generateText } from 'ai'
+
+const tools = mountAgent(usersService, { context: { userId: 'agent-1' } })
+
+const result = await generateText({
+  model,
+  tools,
+  prompt: 'Create a user named Max',
+})
+```
+
+Each contract endpoint exposed on `AGENT` becomes a tool whose input schema is
+the merged `params` + `input`. `context` is merged into every tool handler's
+`ctx`, alongside `source: 'agent'`.
+
+### `AgentMountConfig`
+
+| Field | Purpose |
+|-------|---------|
+| `context` | values merged into every tool handler's `ctx` |
+| `lifecycle` | `beforeHandle` / `afterHandle` — the tool-side auth gate (see [Guarding tools](#guarding-tools--lifecycle)) |
+| `hooks` | tool-call observability hooks — `afterToolCall` fires on every result |
+| `extend` | add extra args resolved before the handler runs (see below) |
+| `runtimeTools` | framework-managed pathless operations from `defineRuntimeTool` |
+
+`lifecycle` works the same as on the MCP server — without it an agent tool call
+bypasses the HTTP `authorize` gate. Pass your `createAuthHook` result.
+
+### Adding tool-only args — `extend`
+
+`extend` adds **tool-only** arguments — fields the model fills that are resolved
+into context, then stripped before the contract handler sees them. Use it when a
+tool needs an argument the HTTP endpoint does not — the classic case being a
+**multi-tenant** server reached by one API key, where the model passes `tenantId`
+on every call. It is the same `ToolExtend` shape on `mountMcp`, `createMcpHandler`
+and `mountAgent`:
+
+```ts
+interface ToolExtend {
+  /** Extra Zod fields added to every matching tool's input schema. */
+  schema: Record<string, z.ZodType>
+  /** Turn the extra args into context merged into the handler's ctx. */
+  resolve: (args: Record<string, unknown>) => Partial<Ctx> | Promise<Partial<Ctx>>
+  /** Limit the extension to specific methods — default: every method. */
+  filter?: (service: ServiceDef, method: MethodDef) => boolean
+}
+```
+
+On the MCP server — add `tenantId` to each tool, validate access in `resolve`,
+inject the resolved tenant into `ctx`, and `filter` to the tenant-scoped tools:
+
+```ts
+createMcpHandler({
+  serverInfo, auth,
+  services: [widgetsService],
+  extend: {
+    schema: { tenantId: z.string().describe('Tenant to act on') },
+    resolve: async ({ tenantId }) => {
+      const id = String(tenantId)
+      if (!(await tenantExists(id))) throw new Error(`unknown tenant ${id}`)
+      return { tenantId: id }          // merged into ctx → ctx.tenantId
+    },
+    filter: (_service, method) => method.scope === 'tenant',
+  },
+})
+```
+
+The model calls `widgets_list({ tenantId: 't_123' })`; `resolve` checks access and
+puts `tenantId` on `ctx`; the contract handler reads `ctx.tenantId` (same place
+as the HTTP prefix param — see
+[Route groups → param prefixes](./server.md#param-prefixes-resource-scoped-paths)),
+so one handler serves both surfaces. Pair `extend` with `lifecycle` (your
+`createAuthHook`) so the tool call is still scope-gated.
+
+## Pathless runtime tools and multimodal results
+
+Use `defineRuntimeTool` for an operation that has no HTTP path but still needs
+the same validation, isolated per-call context, lifecycle/RBAC and hooks as a
+contract tool. The handler returns one transport-neutral, schema-validated
+result. Optional presentation callbacks map that result to MCP content and AI
+SDK model output without coupling the handler to either SDK:
+
+```ts
+import { createMcpHandler, defineRuntimeTool, mountAgent } from 'stitchkit/tools'
+import { z } from 'zod'
+
+const renderPreview = defineRuntimeTool({
+  name: 'render_preview',
+  description: 'Render and inspect a preview',
+  identity: {
+    serviceName: 'mediaTools',
+    action: 'renderPreview',
+    scope: 'admin',
+    method: 'POST',
+  },
+  input: z.object({ prompt: z.string() }),
+  output: z.object({ assetId: z.string(), imageBase64: z.string() }),
+  handler: async ({ input }) => renderAndSave(input.prompt),
+  present: {
+    mcp: (output) => ({
+      content: [
+        { type: 'image', data: output.imageBase64, mimeType: 'image/png' },
+        { type: 'text', text: output.assetId },
+      ],
+    }),
+    agent: (output) => ({
+      type: 'content',
+      value: [{
+        type: 'file',
+        data: { type: 'data', data: output.imageBase64 },
+        mediaType: 'image/png',
+        filename: `${output.assetId}.png`,
+      }],
+    }),
+  },
+})
+
+const handleMcp = createMcpHandler({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth,
+  services: [service],
+  runtimeTools: [renderPreview],
+  lifecycle: { beforeHandle: authHook },
+  hooks: audit.toolCall,
+})
+
+const agentTools = mountAgent([service], {
+  runtimeTools: [renderPreview],
+  lifecycle: { beforeHandle: authHook },
+  hooks: audit.toolCall,
+})
+```
+
+When several runtime tools share application context and identity, bind both
+once with `createRuntimeToolFactory`. Its Zod context schema is parsed once per
+call inside the same runner; the authored handler receives validated context and
+parsed `input`, while lifecycle, hooks, output validation and presenters remain
+unchanged:
+
+```ts
+const knowledgeTools = createRuntimeToolFactory({
+  serviceName: 'agentKnowledge',
+  scope: 'user',
+  context: z.object({ userId: z.string(), tz: z.string() }),
+})
+
+const countRecords = knowledgeTools.define({
+  name: 'count_records',
+  action: 'countRecords',
+  method: 'GET',
+  description: 'Count records',
+  input: z.object({ kind: z.string() }),
+  output: z.object({ count: z.number() }),
+  handler: async ({ userId, tz, input }) => countFor(userId, tz, input.kind),
+})
+```
+
+`serviceName` and `scope` cannot be overridden by one definition. Use standalone
+`defineRuntimeTool` when tools do not share a context schema or identity.
+
+`transports` defaults to `['MCP', 'AGENT']`; set an explicit subset when an
+operation belongs on only one surface. Include `'CLI'` explicitly to reuse the
+definition through `createCli({ runtimeTools })`; adding CLI support never
+widens existing definitions silently. The configured identity becomes the
+hook/lifecycle `OperationIdentity` and the tool `RequestEvent`
+(`serviceName`, `action`, `httpMethod`). A runtime operation has no HTTP route,
+so no fake `path` is added.
+
+When `output` is declared, Stitchkit validates the neutral handler result after
+`afterHandle`. MCP owns `structuredContent` and `isError`: a presenter supplies
+only rich `content`/metadata, while the framework inserts the validated
+structured result and normalises failures. The Agent adapter uses the AI SDK's
+official `toModelOutput` callback, so `execute` and application UI keep the
+neutral output while the model receives text/file content. Presentation
+callbacks require an output schema.
+
+The MCP registration uses an identity carrier: the SDK advertises the compiled
+JSON Schema but forwards the raw object into Stitchkit. Input failures therefore
+use the same validation, lifecycle and hook path as contract tools.
+
+### Managed wait, download, upload and view-file
+
+The common imperative shapes have typed definition factories. They produce
+ordinary runtime-tool definitions, so one value can enter `runtimeTools` on MCP
+and Agent and receives the same lifecycle, hooks, context, cancellation,
+collision checks and introspection as any `defineRuntimeTool` operation:
+
+```ts
+import {
+  defineDownloadTool,
+  defineUploadTool,
+  defineViewFileTool,
+  defineWaitTool,
+} from 'stitchkit/tools'
+import { createManagedFileBoundary } from 'stitchkit/files'
+import { z } from 'zod'
+
+const files = await createManagedFileBoundary({
+  root: '/srv/job-media',
+  createRoot: true, // creates only this final directory; /srv must already be trusted
+  inspectionTimeoutMs: 15_000,
+  inspect: ({ prefix, name, declaredMediaType, signal }) =>
+    inspectFile(prefix, { name, declaredMediaType, signal }),
+})
+
+const waitForJob = defineWaitTool({
+  name: 'wait_for_job',
+  description: 'Wait for a job to finish',
+  identity: { serviceName: 'jobs', action: 'waitForJob', scope: 'user' },
+  input: z.object({ id: z.string() }),
+  state: z.object({ id: z.string(), status: z.enum(['RUNNING', 'DONE']) }),
+  poll: ({ id }, context) => getJob(id, context.signal),
+  done: (state) => state.status === 'DONE',
+  backoff: [2, 3, 5],
+  defaultTimeout: 120,
+})
+
+const downloadResult = defineDownloadTool({
+  name: 'download_result',
+  description: 'Download a completed result',
+  identity: { serviceName: 'jobs', action: 'downloadResult', scope: 'user' },
+  input: z.object({ id: z.string() }),
+  resolveUrl: ({ id }) => resolveResultUrl(id),
+  files,
+  pathFromInput: ({ id }) => `results/${id}.bin`,
+})
+
+const uploadInput = defineUploadTool({
+  name: 'upload_input',
+  description: 'Upload a local input file',
+  identity: { serviceName: 'jobs', action: 'uploadInput', scope: 'user' },
+  output: z.object({ url: z.url() }),
+  files,
+  upload: (source, context) => uploadBytes(source.bytes, context.signal),
+})
+
+const viewResult = defineViewFileTool({
+  name: 'view_result',
+  description: 'Inspect generated media',
+  identity: { serviceName: 'jobs', action: 'viewResult', scope: 'user' },
+  // Local files are disabled when files is omitted. URL fetches retain SSRF
+  // protection; use allowPrivateHosts only for an explicitly trusted network.
+  files,
+})
+
+const runtimeTools = [waitForJob, downloadResult, uploadInput, viewResult]
+```
+
+Managed factories return neutral validated data. Expected failures go through
+the standard failed `ToolResult` path rather than masquerading as a successful
+payload with `isError`. Wait sleep is abort-aware, guarded downloads receive the
+active signal, and upload implementations receive it on their typed context.
+Managed view-file accepts one or several paths/URLs, retains successful
+multimodal content beside structured per-item `errors`, and charges every item
+to one total 20 MB batch budget. Its MCP and Agent presenters are built in;
+remote fetch cancellation follows the active call signal.
+
+The older `mountWait`, `mountDownload`, `mountUpload` and `mountViewFile`
+functions remain
+intentional raw MCP adapters with their text-envelope behavior. Use them under
+`rawTools` only when opting out of managed policy is deliberate; they share the
+same neutral mechanics but do not gain lifecycle or hooks. The raw view-file
+adapter preserves its content-only MCP envelope while using the same bounded
+batch operation.
+
+### Async-operation protocol
+
+For a complete long-running operation, define the linked runtime-only surface
+once. Stitchkit owns transport names, validation and wait mechanics; the
+application still owns storage, execution, retries and domain states:
+
+```ts
+import {
+  createAsyncOperationSnapshotSchema,
+  defineAsyncOperation,
+} from 'stitchkit/tools'
+
+const id = z.object({ id: z.string() })
+const state = z.object({
+  phase: z.enum(['pending', 'running', 'succeeded']),
+  value: z.string().optional(),
+})
+const snapshot = createAsyncOperationSnapshotSchema({
+  failure: z.object({ code: z.string() }),
+  progress: z.object({ current: z.number(), total: z.number() }),
+})
+
+const exportOperation = defineAsyncOperation({
+  mode: 'runtime-only',
+  name: 'export',
+  description: 'Export project data',
+  identity: { serviceName: 'exports', action: 'export', scope: 'user' },
+  startInput: z.object({ projectId: z.string() }),
+  id,
+  state,
+  snapshot,
+  start: ({ projectId }) => enqueueExport(projectId),
+  authorize: ({ id }, capability, ctx) => authorizeExport(id, capability, ctx),
+  inspect: ({ id }, ctx) => readExport(id, ctx.signal),
+  classify: (job) => ({ phase: job.phase }),
+  result: {
+    output: z.object({ value: z.string() }),
+    handler: (job) => ({ value: job.value ?? '' }),
+  },
+})
+
+const runtimeTools = exportOperation.runtimeTools
+```
+
+#### Durable application-owned execution
+
+The executable reference
+[`durable-async-operation-harness.ts`](../../packages/core/examples/tools/durable-async-operation-harness.ts)
+shows the complete boundary behind that surface. It composes
+`defineAsyncOperationContract`, `defineAsyncOperation`, `createApplication`,
+`createBoundedAdmission`, managed shutdown and `createAgentToolFenceLifecycle`
+around an injected store and provider.
+
+The store transactionally owns the idempotency key **and normalized request
+hash**. Reusing both returns the existing operation; reusing the key with a
+different hash conflicts. Every mutation is an expected-revision CAS. Before an
+external call, the application persists a unique attempt/effect key and marks
+the dispatch `possibly-dispatched`; a lost response is therefore reconciled by
+that key after restart and is never treated as permission to submit the effect
+again. Provider acknowledgement, progress, cancellation intent, result and
+artifact references remain durable application state.
+
+Agent tool fencing and operation idempotency are separate guarantees. The fence
+prevents a stale run owner from crossing an effect boundary; the transactional
+idempotency record makes a repeated current call converge on one operation.
+Neither replaces the other.
+
+Stitchkit deliberately does **not** own the durable queue, operation database,
+lease renewal, provider retry/reconciliation protocol, asset catalog or domain
+states. The process-local application resource stops admission and drains
+accepted work; unresolved durable records survive shutdown for the next
+recovery pass. The packed consumer lane executes this composition from the
+published package on Bun and Node.
+
+Every follow-up repeats `authorize`; an opaque id is never authority. Aborting
+`wait` only stops waiting and never calls optional domain `cancel`.
+
+For a new HTTP surface, derive the canonical capability contract once. The
+factory defines schemas and routes only; the application still supplies normal
+handlers to `implement` and owns the job:
+
+```ts
+import { defineAsyncOperationContract } from 'stitchkit/tools'
+import { z } from 'zod'
+
+const operationId = z.object({ id: z.string() })
+const operationSnapshot = z.object({
+  phase: z.enum(['pending', 'running', 'succeeded', 'failed', 'cancelled']),
+})
+
+const operations = defineAsyncOperationContract({
+  prefix: 'exports',
+  scope: 'user',
+  description: 'Export project data',
+  startInput: z.object({ projectId: z.string() }),
+  id: operationId,
+  snapshot: operationSnapshot,
+  cancel: true,
+  result: z.object({ downloadUrl: z.url() }),
+})
+
+// Pass operations.contract and ordinary handlers to implement(...).
+// operations.capabilities/schemas/adapters are the canonical protocol metadata.
+```
+
+If an existing dedicated contract has a different wire shape — for example
+`start` returns a snapshot while follow-ups accept separate envelopes — bind it
+without casts or duplicate endpoints. Inline callbacks are contextually typed;
+every returned id/input is parsed by the destination schema:
+
+```ts
+import { defineContract } from 'stitchkit/contract'
+import { bindContractAsyncOperation } from 'stitchkit/tools'
+
+const startOutput = z.object({ operation: operationId, acceptedAt: z.string() })
+const statusInput = z.object({ operationId: z.string() })
+const waitInput = z.object({ lookup: operationId })
+
+const existing = defineContract({ prefix: 'exports' }, {
+  start: {
+    method: 'POST', path: '/', desc: 'Start export',
+    input: z.object({ projectId: z.string() }), output: startOutput,
+  },
+  status: {
+    method: 'POST', path: '/status', desc: 'Read export status',
+    input: statusInput, output: operationSnapshot,
+  },
+  wait: {
+    method: 'POST', path: '/wait', desc: 'Wait for export',
+    input: waitInput, output: operationSnapshot,
+  },
+})
+
+const operationHandlers = {
+  start: () => ({ operation: { id: 'example' }, acceptedAt: new Date().toISOString() }),
+  status: (): z.output<typeof operationSnapshot> => ({ phase: 'pending' }),
+  wait: (): z.output<typeof operationSnapshot> => ({ phase: 'succeeded' }),
+}
+
+const bound = bindContractAsyncOperation({
+  mode: 'contract-backed',
+  binding: 'adapted',
+  contract: existing,
+  id: operationId,
+  capabilities: { start: 'start', status: 'status', wait: 'wait' },
+  adapters: {
+    idFromStart: (output) => output.operation,
+    inputFor: {
+      status: (id) => ({ operationId: id.id }),
+      wait: (id) => ({ lookup: id }),
+    },
+  },
+  handlers: operationHandlers,
+})
+```
+
+Direct binding remains the short form when start already returns the id and
+every follow-up reuses that exact schema instance. Its ID schema must be
+wire-stable: input and output types match and parsing has no transform,
+coercion, default or overwrite. This also excludes same-type transforms because
+the direct adapters would parse an already parsed ID again. Use adapted binding
+and explicitly project the parsed ID back into each follow-up input. In both
+modes the binder creates no router;
+it returns the existing contract, handlers and protocol metadata for
+application composition.
+
+### Explicit raw SDK registration
+
+`rawTools` is deliberately named as an escape hatch. A tool registered there
+does **not** receive stitchkit schema policy, lifecycle, per-call context or
+hooks. The built-in `mountViewFile`, `mountWait`, `mountDownload` and
+`mountUpload` helpers remain raw for callers that choose that boundary; the
+media helper fetches with SSRF and path-traversal defenses:
+
+```ts
+import { createMcpHandler, mountViewFile } from 'stitchkit/tools'
+
+const handleMcp = createMcpHandler({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth,
+  services: [service],
+  rawTools: (server) => mountViewFile(server, { files }),
+})
+```
+
+Use raw registration only when opting out is intentional. For a protected
+`view_file`, use `defineViewFileTool` in `runtimeTools`; it supplies the
+canonical schemas, shared batch budget, structured partial failures and both
+multimodal presenters. `resolveMedia` remains the single-item core for custom
+operations whose contract intentionally differs.
+
+## Introspecting the complete tool surface
+
+Deferred tool search, name snapshots and boot diagnostics accept the same
+object-shaped surface as the mounts. Contract operations are followed by
+runtime definitions, matching mount order; exposure filters and collisions are
+resolved by Stitchkit rather than by consumer code:
+
+```ts
+import {
+  buildToolManifest,
+  listToolNames,
+  summarizeTransports,
+} from 'stitchkit/tools'
+
+const surface = { services, runtimeTools: [renderPreview] }
+
+const manifest = buildToolManifest({
+  ...surface,
+  transport: 'AGENT',
+  flattenUnionInput: true,
+})
+
+const names = listToolNames(surface)
+const summary = summarizeTransports(surface)
+```
+
+`buildToolManifest` returns the exact immutable presentation schema shown to
+the selected MCP or Agent transport. It does not execute validation effects and
+fails first on duplicate contract/runtime names. There is no runtime-only
+manifest helper or public mount adapter: the framework owns merging and schema
+projection.
+
+Applications using Stitchkit's durable runtime can compose this manifest with
+bounded per-run activation through `createDeferredAgentToolSurface` from
+`stitchkit/agent-runtime`. It keeps selected calls as direct `mountAgent` tools
+rather than routing them through a generic executor. Search receipts live in
+ordinary durable tool-result history, so recovery restores activation and a
+queued successor cannot inherit it. See
+[Bounded deferred tool catalogs](./agent-runtime.md#bounded-deferred-tool-catalogs)
+and ADR 0129. Raw `mountAgent`, `mountMcp` and `buildToolManifest` behavior is
+unchanged.
+
+`listToolNames` remains diagnostic and reports `kind: 'contract' | 'runtime'`
+for every identity. `summarizeTransports` returns `contractServices`,
+`runtimeTools`, aggregate `totals`, and a `sources` breakdown. Runtime tools
+contribute only to MCP/Agent according to their `transports`; they never inflate
+HTTP or CLI counts.
+
+## Logging tool calls — `createToolLogger`
+
+Every tool mount fires an `afterToolCall` hook. `createToolLogger` is a ready
+preset for it — one line logs each call (ok / failed, duration, which endpoint,
+keyed by the endpoint's stable `serviceName` / `key` identity):
+
+```ts
+import { createToolLogger } from 'stitchkit/tools'
+
+mountMcp(server, services, { hooks: createToolLogger() })
+// [tool] ok list_widgets (widgets.list) 12ms
+// [tool] warn get_widget (widgets.get) NOT_FOUND 4ms
+```
+
+By default the line goes to `console.error` — **stderr, never stdout**. That is
+deliberate: in a stdio-MCP server stdout is the JSON-RPC protocol channel, and a
+log line written there corrupts the stream. If you pass your own `log`, keep it
+off stdout for any stdio deployment.
+
+Pass `log` to redirect the line, or `onRecord` to feed a metrics sink the
+structured `ToolCallRecord`. That record carries `traceId` whenever an
+observability context is active, so a tool call made inside an HTTP request
+joins that request's log line on one key — see
+[Observability](./observability.md). For a boot-time picture of what is exposed
+where, `summarizeTransports({ services, runtimeTools })` returns the mixed
+per-transport counts for you to log.
+
+## One handler, three callers
+
+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 |
+
+---