stitchkit 0.119.0 → 0.121.0

package/llms/stitchkit.txt

@@ -63,8 +63,10 @@ own, recorded as an ADR.
 | `stitchkit/primitives` | browser **and** server | evolving | generic values and declarations for lifecycle, access, audit, delivery and exports, exact money and rounding tables |
 | `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
 | `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
-| `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
+| `stitchkit/tools` | server | stable | the transport-neutral tool layer — registry, tool names and manifest, runtime tools, native tools, the OAuth provider, the durability engine; loads no optional peer at runtime |
 | `stitchkit/tools/mcp` | server (Bun or Node) | evolving | the canonical MCP HTTP/stdio server, schemas and typed MCP presenters; only Zod and the MCP server SDK peers |
+| `stitchkit/tools/agent` | server (Bun or Node) | evolving | `mountAgent` — a contract's operations as AI SDK tools; only Zod and the `ai` peer |
+| `stitchkit/tools/toolkit` | server (Bun or Node) | evolving | `createToolkit` — one tool set served over MCP and to an AI SDK agent; the MCP server SDK and `ai` peers |
 | `stitchkit/tools/contract` | browser + server | evolving | the shapes a tool surface speaks — async-operation contract, snapshot and cancel schemas, view-file input/output — without the runtime that serves them |
 | `stitchkit/tools/invoker` | server | stable | peer-free `createToolInvoker` over the canonical contract tool runner |
 | `stitchkit/tools/connections` | server (Bun or Node) | evolving | consume external MCP servers and a bounded OpenAPI subset — typed reauthorization, a per-request host fence and per-call credentials |
@@ -90,13 +92,13 @@ own, recorded as an ADR.
 | `stitchkit/xlsx` | browser **and** server | evolving | a workbook from rows and typed columns, with no dependency; text never runs as a formula |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 64 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 66 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 64 minors since 0.56.2, most recently 0.115.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 26 of the 66 minors since 0.56.2, most recently 0.121.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -108,7 +110,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 64 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 66 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -211,7 +213,10 @@ map — feature → packages:
 | `createServer` (Bun) | — (uses `Bun.serve`) |
 | `serveNode` (Node ≥ 22) | `srvx` (+ `@types/bun` dev) |
 | In-process contract tools (`stitchkit/tools/invoker`) | — |
-| MCP / agent adapters (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
+| Tool layer — registry, tool names, runtime tools (`stitchkit/tools`) | — |
+| MCP server (`stitchkit/tools/mcp`) | `@modelcontextprotocol/server` |
+| AI SDK agent tools (`stitchkit/tools/agent`) | `ai` |
+| MCP and agent toolkit (`stitchkit/tools/toolkit`) | `@modelcontextprotocol/server` `ai` |
 | Agent application runtime (`stitchkit/agent-runtime`) | `ai` |
 | Headless Agent harness (`stitchkit/agent-runtime/harness`) | `ai` |
 | Agent coding tools (`stitchkit/agent-runtime/coding-tools`) | — |
@@ -240,15 +245,16 @@ bun add socket.io @socket.io/bun-engine    # e.g. the Socket.IO server on Bun
 ```
 
 Dynamic optional-peer adapters fail with an actionable error naming the package
-and install command. Static entrypoints such as `stitchkit/tools` fail during
+and install command. Static entrypoints such as `stitchkit/tools/mcp` fail during
 ESM resolution by naming the exact missing package; the feature-to-peer matrix
 below is the canonical install command.
 
-The combined tools entry owns MCP and AI-agent adapters, so install both runtime
-peers before importing `stitchkit/tools`:
+`stitchkit/tools` itself loads no optional peer. Install the peer of the adapter
+you import — both for `stitchkit/tools/toolkit`:
 
 ```bash
-bun add @modelcontextprotocol/server@^2 ai@^7
+bun add @modelcontextprotocol/server@^2   # stitchkit/tools/mcp
+bun add ai@^7                             # stitchkit/tools/agent
 ```
 
 Browser, HTTP-client and React entrypoints remain usable without either MCP

package/llms/testing.txt

@@ -326,8 +326,9 @@ fixture's transitive dependency.
 
 That includes `stitchkit/tools/invoker`: a minimal packed consumer imports it
 without MCP/AI peers and executes validation, output projection and normalized
-errors on Bun and Node. The broader `stitchkit/tools` barrel deliberately keeps
-the adapter peer budget.
+errors on Bun and Node, and so does `stitchkit/tools`, which loads no optional peer at
+runtime. The adapters keep their peer budgets on their own subpaths:
+`stitchkit/tools/mcp`, `stitchkit/tools/agent` and `stitchkit/tools/toolkit`.
 
 Beside the matrix, one case is about the ARTIFACT rather than the inventory: a
 program that injects the Socket.IO peer loaders is bundled and started in a
@@ -556,10 +557,7 @@ signal and deadline. Bind its process lifecycle with the truthful close-only
 sibling from `stitchkit/tools`:
 
 ```ts
-import {
-  bindStdioProcessSignals,
-  createStdioMcpServer,
-} from 'stitchkit/tools'
+import { bindStdioProcessSignals, createStdioMcpServer } from 'stitchkit/tools/mcp'
 
 const stdio = await createStdioMcpServer(config)
 const binding = bindStdioProcessSignals(stdio, {

package/llms/tools-agent.txt

@@ -0,0 +1,24 @@
+# stitchkit/tools/agent — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/tools/agent`  (docs/api/reference.md)
+
+Also read:
+- see `llms/tools.txt` for the MCP & agents guide
+
+==============================================================================
+# API reference: `stitchkit/tools/agent`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/tools/agent`
+
+Server-only. A contract's operations as Vercel AI SDK tools; needs Zod and the `ai`
+peer, not the MCP server SDK. → ADR 0284.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `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) |
+| `AgentMountConfig` | _type_ | config for `mountAgent` |
+| `AgentContext` | _type_ | the context merged into agent tool handlers |

package/llms/tools-mcp.txt

@@ -14,15 +14,80 @@ Also read:
 
 ## `stitchkit/tools/mcp`
 
-A server-only leaf over the same MCP owner as `stitchkit/tools`. Its runtime and strict
-NodeNext declarations require Zod and `@modelcontextprotocol/server`, with no AI SDK peer.
-HTTP/stdio factories, mounts, schema policy, catalog and resource helpers keep their canonical
-behavior and names. See [MCP guide](../guide/mcp-and-agents.md#mcp--createmcphandler).
+Server-only, and the one place the MCP server is exported. Its runtime and strict NodeNext
+declarations require Zod and the `@modelcontextprotocol/server` v2 peer, with no AI SDK peer;
+MCP hosts and tests use the separate `@modelcontextprotocol/client` package.
+
+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. See [MCP guide](../guide/mcp-and-agents.md#mcp--createmcphandler).
 
 | Export | Kind | Purpose |
 |--------|------|---------|
-| `createMcpHandler` / `createMcpHttpRoute` / `buildMcpServer` / `mountMcp` | function | the shared authenticated HTTP handler, raw-route adapter, SDK server and contract mount |
-| `createStdioMcpServer` / `bindStdioProcessSignals` | function | the shared stdio server and bounded process cleanup |
+| `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) |
+| `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)) |
+| `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 |
+| `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
 | `RuntimeToolDefinitionWithOutput` / `RuntimeToolDefinitionWithoutOutput` | _type_ | the one neutral construction, shared with `stitchkit/cli` and `stitchkit/tools`; MCP-only presenters are its fourth type argument, `RuntimeMcpToolPresenters<z.output<typeof output>>` |
 | `RuntimeToolDefinition` | _type_ | heterogeneous registration; the canonical runner validates input/output before invocation |
 | `RuntimeMcpToolPresenters` / `RuntimeMcpPresentation` | _type_ | official SDK content without framework-owned `structuredContent` or `isError`; one presenter owner shared with the full SDK surface |
+
+### 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 |

package/llms/tools-toolkit.txt

@@ -0,0 +1,23 @@
+# stitchkit/tools/toolkit — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/tools/toolkit`  (docs/api/reference.md)
+
+Also read:
+- see `llms/tools.txt` for the MCP & agents guide
+
+==============================================================================
+# API reference: `stitchkit/tools/toolkit`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/tools/toolkit`
+
+Server-only. One context-typed tool set served over MCP and to an AI SDK agent, so it
+needs both the `@modelcontextprotocol/server` and `ai` peers. → ADR 0284.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
+| `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |

package/llms/tools.2.txt

@@ -178,7 +178,7 @@ see [Agent application runtime](./agent-runtime.md).
 `generateText` / `streamText`:
 
 ```ts
-import { mountAgent } from 'stitchkit/tools'
+import { mountAgent } from 'stitchkit/tools/agent'
 import { generateText } from 'ai'
 
 const tools = mountAgent(usersService, { context: { userId: 'agent-1' } })
@@ -262,7 +262,9 @@ 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 { defineRuntimeTool } from 'stitchkit/tools'
+import { createMcpHandler } from 'stitchkit/tools/mcp'
+import { mountAgent } from 'stitchkit/tools/agent'
 import { z } from 'zod'
 
 const renderPreview = defineRuntimeTool({
@@ -628,7 +630,8 @@ hooks. The built-in `mountViewFile`, `mountWait`, `mountDownload` and
 media helper fetches with SSRF and path-traversal defenses:
 
 ```ts
-import { createMcpHandler, mountViewFile } from 'stitchkit/tools'
+import { mountViewFile } from 'stitchkit/tools'
+import { createMcpHandler } from 'stitchkit/tools/mcp'
 
 const handleMcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },

package/llms/tools.3.txt

@@ -14,57 +14,25 @@ Parts of this slice:
 
 ## `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.
+Server-only, and imported without any optional peer: the transport-neutral tool layer —
+the registry, tool names and manifest, runtime tools, native tools, the invoker, the OAuth
+provider and the durability engine. An application that serves its operations over HTTP and
+CLI lists its tool names here with neither MCP nor the AI SDK installed. The adapters that
+need a peer have their own subpaths: [`stitchkit/tools/mcp`](#stitchkittoolsmcp) (the MCP
+server SDK), [`stitchkit/tools/agent`](#stitchkittoolsagent) (the `ai` peer) and
+[`stitchkit/tools/toolkit`](#stitchkittoolstoolkit) (both). → ADR 0284.
 
 | 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) |
+| `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner; use `stitchkit/tools/invoker` or `stitchkit/tools`, both peer-free — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
 | `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_ | heterogeneous registration of pathless operations in `runtimeTools: [...]`; an inline handler is contextually typed by the parsed object, a definition constructed with its own schema registers unchanged, and the runner validates input before the handler |
 | `RuntimeToolDefinitionBase` | _type_ | common name, identity, input, exposure and MCP metadata fields |
 | `RuntimeToolDefinitionWithOutput` | _type_ | the one neutral construction: identity, schemas and a handler typed from them; the fourth type argument names the adapter's `present` extension (`RuntimeToolPresenters<…>` here, `RuntimeMcpToolPresenters<…>` on `stitchkit/tools/mcp`, none by default) |
@@ -90,11 +58,8 @@ payload.
 | `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 |
@@ -126,7 +91,6 @@ payload.
 | `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
@@ -230,39 +194,6 @@ mountAgent(services, { durability: (toolCallId) => myLedgerFor(toolCallId) });
 | `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.

package/llms/tools.txt

@@ -125,10 +125,10 @@ recursive calls without retaining request state. Every invocation gets a fresh
 tool-call context and runs the same extension resolution, input/output
 validation, lifecycle, hooks and output-strip reporter as mounted tools.
 
-The dedicated entrypoint needs only the normal `stitchkit`/`zod` install. Use
-the broader `stitchkit/tools` barrel when the same program also mounts MCP or AI
-adapters and has installed their optional peers. Both imports reach the same
-runner; this is dependency isolation, not a second execution implementation.
+The dedicated entrypoint needs only the normal `stitchkit`/`zod` install, and so does
+`stitchkit/tools`, which exports the same invoker beside the rest of the tool layer. Both
+imports reach the same runner; this is dependency isolation, not a second execution
+implementation.
 
 `invoke` returns the canonical discriminated `ToolResult`, not an AI SDK or MCP
 presentation envelope. `invokeOrThrow` returns validated data and throws the
@@ -150,9 +150,8 @@ get the view's defaults and projected answer, which is what `collectTools` and
 An MCP-only server imports `stitchkit/tools/mcp` and installs
 `stitchkit`, `zod` and `@modelcontextprotocol/server`. The leaf's runtime and strict
 NodeNext declarations require no `ai`. It exports the existing HTTP/stdio server,
-schema policy, catalog and resource helpers; their implementation and security are shared
-with the full `stitchkit/tools` barrel. Use that full barrel when the application also
-needs its AI SDK features.
+schema policy, catalog and resource helpers, and it is the only entrypoint that does:
+`stitchkit/tools` loads no optional peer. AI SDK tools come from `stitchkit/tools/agent`.
 
 `createMcpHandler` builds a complete stateless Streamable-HTTP MCP endpoint on
 the official TypeScript SDK v2 server package. It owns server creation,
@@ -876,7 +875,8 @@ stitchkit ships the OAuth **protocol mechanics**; the app supplies only
 **identity and storage**. Three pieces wire it together:
 
 ```ts
-import { createMcpHandler, createMcpHttpRoute, mountOAuthProvider, oauthProtectedResourceRoute } from 'stitchkit/tools'
+import { mountOAuthProvider, oauthProtectedResourceRoute } from 'stitchkit/tools'
+import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools/mcp'
 import { createServer } from 'stitchkit/server'
 
 const resource = 'https://api.example.com/mcp'

package/llms/{upgrading-0.106.0-0.119.0.txt → upgrading-0.106.0-0.121.0.txt}

@@ -1,14 +1,95 @@
-# Upgrading 0.106.0 → 0.119.0 — stitchkit docs slice
+# Upgrading 0.106.0 → 0.121.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.106.0 → 0.119.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.106.0 → 0.121.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.106.0 → 0.119.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.106.0 → 0.121.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.121.0
+
+### bounded-coding-search
+
+**Who must act:** hosts that construct a complete `AgentCodingToolLimits` value, inspect exact
+`list_directory`, `glob` or `search_files` output objects, rely on symlink cwd aliases, call `glob` on a path that may not exist, or send regex named backreferences or counted repetition above 1,000.
+
+Partial `limits` still fill finite defaults. Complete values add:
+
+```ts
+maxSearchDirectories: 1_000,
+maxSearchEntries: 20_000,
+maxSearchBytes: 16_777_216,
+maxSearchOutputBytes: 65_536,
+searchTimeoutMs: 5_000,
+```
+
+Read `coverage.complete` on list, glob and search before interpreting an empty result.
+List raw enumeration is also capped by `maxListEntries`; glob patterns have a 4,096-unit ceiling.
+The ordinary command cwd is a pinned directory, so descendant symlink cwd aliases are refused;
+use the real relative directory name. Custom sandbox launchers own atomic cwd capture.
+`coverage.reasons` names stopped
+budgets, cancellation, denial, unreadable files and lines beyond the searchable byte ceiling.
+`coverage.scope` names the workspace-relative include, exclusion policy and symlink policy;
+directory/entry/read-byte counters report work reached by the bounded reader. Denied and error
+lists can themselves be truncated. The entire UTF-8 JSON result fits `maxSearchOutputBytes`
+(minimum 1,024); an input whose minimum envelope cannot fit refuses before I/O.
+
+Regex queries keep JavaScript syntax, `(?ims-ims:…)` modifiers and Annex B forms, and their
+cost is bounded per line: a line whose backtracking work, repetition capped at the line's length,
+stays within 2^24 steps runs natively, any other line in linear time. Named backreferences,
+counted repetition above 1,000 and patterns needing the automaton with more than 16,384 automaton states, 65,536
+construction steps (nested repetition of an empty group such as `(?:(?:){1000}){1000}`) or
+4,194,304 overlapping character-set memberships now return `BAD_REQUEST`
+before authorization or file access, as
+numbered backreferences and lookaround already did. Spell the repeated text out, for example
+replace `{ query: '(?<w>ab)\\k<w>', regex: true }` with `{ query: '(ab)ab', regex: true }`.
+
+`glob` with a `path` that is missing, a file or a symlink now refuses (`NOT_FOUND` or
+`BAD_REQUEST`, with a hint) instead of returning no paths; treat that refusal as "nothing
+there". `run_command` refuses such a `cwd` the same way.
+
+Glob matching preserves `**`, `*`, `?` and literal punctuation, including embedded `**`.
+A pattern that prunes directories may produce an explanatory `hint` without counting unseen
+files. `glob` confines traversal to its requested path and viable pattern prefixes.
+
+Traversal checks cancellation and deadlines at CPU checkpoints and races asynchronous waits.
+Late opened handles are closed; in-flight operating-system calls are not claimed to be interrupted.
+Reaching an entry or result ceiling conservatively reports partial coverage without a lookahead.
+
+## Released migration: 0.120.0
+
+### tools-barrel-subpaths
+
+**Who must act:** code importing the MCP server, `mountAgent` or `createToolkit` from
+`stitchkit/tools`. Imports of the registry, tool names, manifest, runtime and native tools, the
+invoker, the OAuth provider and the durability engine stay where they are.
+
+`stitchkit/tools` now loads no optional peer, so an application without
+`@modelcontextprotocol/server` and `ai` can import it. Move each adapter import to its subpath:
+
+```ts
+// before
+import { createMcpHandler, listToolNames, mountAgent } from 'stitchkit/tools'
+import { createToolkit } from 'stitchkit/tools'
+// after
+import { listToolNames } from 'stitchkit/tools'
+import { createMcpHandler } from 'stitchkit/tools/mcp'
+import { mountAgent } from 'stitchkit/tools/agent'
+import { createToolkit } from 'stitchkit/tools/toolkit'
+```
+
+| Names | New subpath | Peers it needs |
+|-------|-------------|----------------|
+| `createMcpHandler`, `createMcpHttpRoute`, `buildMcpServer`, `mountMcp`, `mountMcpResource`, `validateMcpSchemas`, `createStdioMcpServer`, `bindStdioProcessSignals`, `inlineMcpAppBundle`, `mcpCatalogMeta`, `readMcpCatalogStamp`, `EXT_APPS_BUNDLE_PLACEHOLDER`, `MCP_CATALOG_META_KEY`, `RESOURCE_MIME_TYPE` and their config types, `McpServer`, `IncompatibleSchemaPolicy`, `McpSchemaValidationConfig` | `stitchkit/tools/mcp` | `@modelcontextprotocol/server` |
+| `mountAgent`, `AgentMountConfig`, `AgentContext` | `stitchkit/tools/agent` | `ai` |
+| `createToolkit`, `Toolkit` | `stitchkit/tools/toolkit` | `@modelcontextprotocol/server`, `ai` |
+
+The move is mechanical: `bunx stitchkit upgrade --from 0.119.0` lists every import it touches, and
+`tsc` names any name still imported from `stitchkit/tools`. Behaviour is unchanged.
+
 ## Released migration: 0.119.0
 
 ### factory-default-exposure

package/llms/upgrading.txt

@@ -11,7 +11,7 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.106.0 → 0.119.0: `llms/upgrading-0.106.0-0.119.0.txt`
+- 0.106.0 → 0.121.0: `llms/upgrading-0.106.0-0.121.0.txt`
 - 0.96.0 → 0.105.0: `llms/upgrading-0.96.0-0.105.0.txt`
 - 0.69.0 → 0.95.0: `llms/upgrading-0.69.0-0.95.0.txt`
 - 0.55.0 → 0.68.0: `llms/upgrading-0.55.0-0.68.0.txt`