stitchkit 0.119.0 → 0.120.0

package/llms-full.txt

@@ -55,8 +55,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 |
@@ -82,13 +84,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 65 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 25 of the 65 minors since 0.56.2, most recently 0.115.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 |
@@ -100,7 +102,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 65 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 |
@@ -203,7 +205,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`) | — |
@@ -232,15 +237,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
@@ -3936,10 +3942,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
@@ -3961,9 +3967,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,
@@ -4687,7 +4692,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'
@@ -4948,7 +4954,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' } })
@@ -5032,7 +5038,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({
@@ -5398,7 +5406,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' },
@@ -5506,16 +5515,16 @@ identical. Write the handler once; it serves every surface.
 > **Maturity: evolving.** This surface is still finding its shape and may be
 > redefined in any minor release — always with a `### ⚠️ Breaking changes` entry
 > and a migration section, never silently. If your application already owns the
-> conversation loop, `mountAgent` from `stitchkit/tools` is the stable path.
+> conversation loop, `mountAgent` from `stitchkit/tools/agent` is the direct path.
 
 `stitchkit/agent-runtime` is the server-only, opinionated layer above
 `mountAgent`. Use it when the application wants Stitchkit to own conversation
 mechanics: durable acceptance, history projection, the AI SDK stream loop,
 checkpoints, keyed interruption, terminal commit and stable application events.
 
-If the application already owns that loop, continue importing `mountAgent` from
-`stitchkit/tools`. `stitchkit/tools` does not depend on this entrypoint at all;
-this entrypoint uses the tool executor from it, but pulls no MCP peer, so
+If the application already owns that loop, import `mountAgent` from
+`stitchkit/tools/agent`. Neither `stitchkit/tools` nor `stitchkit/tools/agent` depends on
+this entrypoint; this entrypoint uses the tool executor, but pulls no MCP peer, so
 choosing `mountAgent` alone costs you nothing from here.
 
 UI and shared DTO code must import canonical records and delivery validation from
@@ -5539,12 +5548,8 @@ persistence, event sinks and every Node context dependency.
 bun add stitchkit ai zod
 ```
 
-`mountAgent` from `stitchkit/tools` — used in the composition below — additionally
-needs the MCP peer, which that entrypoint imports statically:
-
-```sh
-bun add @modelcontextprotocol/server
-```
+`mountAgent` from `stitchkit/tools/agent` — used in the composition below — needs no
+peer beyond `ai`.
 
 OpenRouter is isolated so other runtime users do not resolve its package:
 
@@ -5565,7 +5570,8 @@ import {
   defineModelRegistry,
 } from 'stitchkit/agent-runtime'
 import { openRouterProvider } from 'stitchkit/agent-runtime/openrouter'
-import { composeToolLifecycle, mountAgent } from 'stitchkit/tools'
+import { composeToolLifecycle } from 'stitchkit/tools'
+import { mountAgent } from 'stitchkit/tools/agent'
 
 const protocol = defineAgentProtocol({
   context: z.object({ userId: z.string() }),
@@ -7279,7 +7285,8 @@ import {
   createAgentHarnessFileResources,
   createHeadlessAgentHarness,
 } from 'stitchkit/agent-runtime/harness';
-import { composeToolLifecycle, mountAgent } from 'stitchkit/tools';
+import { composeToolLifecycle } from 'stitchkit/tools';
+import { mountAgent } from 'stitchkit/tools/agent';
 
 const resources = createAgentHarnessFileResources({
   roots: [{ id: 'guide', kind: 'instruction', path: instructionRoot }],
@@ -7303,8 +7310,8 @@ compose your authorization with the run's `toolFenceLifecycle` by `composeToolLi
 fence rejects a call from a run that no longer owns the conversation, and it must run exactly
 once. Every mount option remains available, including registry, runtime tools, extension,
 coercion, output stripping, hooks and durability, and the callback may be async. The same callback
-still accepts arbitrary typed AI SDK tools and prepareStep. `stitchkit/tools` needs the same `ai` and
-`@modelcontextprotocol/server` peers as any `mountAgent` use; the base harness stays AI-only.
+still accepts arbitrary typed AI SDK tools and prepareStep. `mountAgent` comes from `stitchkit/tools/agent`, which needs only the `ai` peer the
+harness already has; the base harness stays AI-only.
 The resource reader is explicitly selected: filtered allowlists do not gain tools merely
 because a loader exists. Root IDs, kinds, provenance and limits are unchanged.
 
@@ -8657,7 +8664,7 @@ Storage is process-durable, without a power-loss/fsync guarantee.
 
 ```ts
 import { createSandboxCodingTools } from 'stitchkit/agent-runtime/sandbox';
-import { mountAgent } from 'stitchkit/tools';
+import { mountAgent } from 'stitchkit/tools/agent';
 
 const tools = mountAgent([], {
   runtimeTools: createSandboxCodingTools(handle, {
@@ -10040,7 +10047,7 @@ types; the package keeps its required dependencies separate from optional SDKs.
 CLI runtime tools use the one runtime-tool declaration: identity, input and output
 schemas, handler, and explicit CLI exposure. SDK presenters are the adapter's extension
 of that declaration (the fourth type argument of `RuntimeToolDefinitionWithOutput`, or
-`defineRuntimeTool` in `stitchkit/tools`), which requires the corresponding peers. A typed
+`defineRuntimeTool` in `stitchkit/tools`), whose presenter types name the corresponding SDKs. A typed
 definition returned by `defineRuntimeTool` or `createRuntimeToolFactory` can be
 passed directly to both CLI and SDK mounts.
 
@@ -14917,8 +14924,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
@@ -15147,10 +15155,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, {
@@ -17144,6 +17149,37 @@ charts, no merged cells and no streaming: an application that needs them takes a
 
 # Upgrading stitchkit
 
+## 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
@@ -23813,8 +23849,8 @@ Separate optional evolving Bun/OpenTUI package over a caller-composed headless h
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `defineAgentTui` | function | typed config for title/theme/status rows, model catalog, context, commands, runtime bundle and optional host-evidenced recovery policy; the default never requeues acquired effects |
-| `runAgentTui` | function | start one fresh durable conversation and terminal controller, recover durable work and publish its authenticated local session; `initialConversationId` is an explicit resume override |
+| `defineAgentTui` | function | typed config for title, `theme` (a `TerminalPalette` override) and `themeMode`, status rows, model catalog, context, commands, runtime bundle and optional host-evidenced recovery policy; the default never requeues acquired effects |
+| `runAgentTui` | function | start one fresh durable conversation and terminal controller, recover durable work and publish its authenticated local session; `initialConversationId` is an explicit resume override; it closes the session and exits the process on Ctrl-C and every signal OpenTUI catches unless `exitSignals: []` |
 | `defineTuiCommand` / `resolveTuiCommand` | function | typed composable slash-command registry; unknown slash input remains an ordinary model prompt |
 | `createAgentTuiController` | function | single admission, selection, approval, interruption and conversation-switch owner over the harness |
 | `startAgentTuiSessionHost` / `createAgentTuiClient` | function | authenticated mode-`0600` Unix-socket host/client for status, submit and interrupt through that controller |
@@ -23823,7 +23859,7 @@ Separate optional evolving Bun/OpenTUI package over a caller-composed headless h
 | `defaultAgentTuiStatusLine` / `AgentTuiStatusLineFormatter` | function / _type_ | terminal-native default rows and a host formatter over model capacity, durable snapshot, activity, workspace and local identities; `statusLine: false` hides the rows |
 | `createAgentTuiDiagnosticRecorder` / `AgentTuiDiagnosticEventSchema` | function / schema | bounded per-session metadata journal that rejects prompt, reasoning, tool-input and provider-cause payloads before disk admission |
 
-The `stitchkit-agent` binary loads `stitchkit.agent.ts` by default and also exposes `sessions`,
+The `stitchkit-agent` binary runs React's production build unless `NODE_ENV` says otherwise and loads `stitchkit.agent.ts` by default and also exposes `sessions`,
 `status`, `send` and `interrupt`. `--workspace` addresses a host outside the caller's cwd,
 `send --idempotency-key` accepts caller-owned retry identity, and `interrupt` defaults to the
 active run returned by `status`. Session descriptors and sockets are local control credentials,
@@ -23846,6 +23882,65 @@ Renderer-neutral state only. This entrypoint imports neither React/OpenTUI nor t
 | `createTerminalCommandPalette` / `terminalCommandMatches` | function | bounded command filtering and keyboard selection over a collision-validated registry |
 | `resolveExactTerminalCommand` / `validateTerminalCommands` | function | exact dispatch and fail-closed name/alias validation |
 | `createTerminalOperationState` / `reduceTerminalOperationState` | function | confirmation and single-pending-operation lifecycle |
+| `createTerminalTable` / `reduceTerminalTable` / `projectTerminalTable` | function | live table: typed columns, rows validated on entry, sort with key tie-break and missing values last, tree expansion pruned to present rows, filter on displayed text, selection kept across data; a row's `tone` and a column's `tone(value, row)` colour state |
+| `layoutTerminalTableColumns` / `formatTerminalTableCell` / `visibleTerminalTableRows` / `terminalTableTreePrefix` | function | fixed and flexible column widths, `—` for missing values, the virtualized window, tree indentation |
+| `createTerminalList` / `reduceTerminalList` / `visibleTerminalListLines` | function | picker with sections, fuzzy query with title highlight ranges, multi-select, disabled items and "more above/below" counts |
+| `createTerminalForm` / `reduceTerminalForm` / `readTerminalForm` / `terminalFormFieldsFromJsonSchema` | function | typed fields (text, secret, number, integer, boolean, choice, JSON) from a JSON Schema, relative text edits, validation on leave and submit |
+| `createTerminalTabs` / `reduceTerminalTabs` | function | tabs with badges, wrap-around movement, digit selection and reconcile that keeps the selected tab |
+| `createTerminalNavigation` / `reduceTerminalNavigation` / `terminalBreadcrumbs` | function | screen stack keeping each level's state, root never popped |
+| `createTerminalFocus` / `reduceTerminalFocus` | function | focus ring plus layers that take the keyboard and give it back |
+| `createTerminalNotices` / `reduceTerminalNotices` / `nextTerminalNoticeExpiry` | function | bounded toasts on a caller clock, replaced by id |
+| `createTerminalTimeSeries` / `appendTerminalSample` / `sampleTerminalTimeSeries` | function | time window bounded by duration and sample count, value-in-force sampling with explicit gaps |
+| `terminalBrailleChart` / `terminalSparkline` / `terminalTimeAxis` / `terminalChartScale` | function | multi-series braille line or area chart as toned runs, sparkline, time axis |
+| `terminalMeter` / `layoutTerminalMeterGrid` | function | eighth-block bar toned by thresholds, unmeasured as muted; column-major core grid |
+| `terminalProgress` / `terminalSpinnerFrame` / `terminalIndeterminateBlock` / `formatTerminalDuration` | function | ratio, rate and ETA only when knowable; spinner frames; indeterminate bar; elapsed time |
+| `defineTerminalKeymap` / `matchTerminalKey` / `fitTerminalKeyHints` | function | conflict-checked bindings that both answer keys and draw a footer fitted to the width |
+| `terminalTableKeymap` / `terminalTableKey` / `terminalTabsKeymap` / `terminalTabsKey` | function | htop-style table bindings and tab bindings as keymaps |
+| `matchTerminalSearch` / `searchTerminalItems` / `terminalHighlightRuns` | function | multi-word fuzzy match with ranges, stable ranking, highlight runs |
+| `sanitizeTerminalText` / `terminalTextWidth` / `truncateTerminalText` / `fitTerminalText` / `wrapTerminalText` | function | strip escape and control sequences; measure, cut, pad and wrap by terminal cells |
+| `terminalTextEdit` / `applyTerminalTextEdit` | function | one-line edits as relative actions, so fast input is never lost |
+| `terminalJsonLines` / `layoutTerminalDetails` | function | toned, sanitized JSON lines; aligned key/value pairs |
+| `terminalPalettes` / `resolveTerminalPalette` / `TerminalPalette` / `TerminalTone` | value / function / _type_ | one semantic palette (surfaces plus `primary`, `muted`, `accent`, `success`, `warning`, `danger`) for dark and light terminals |
+| `terminalLabelsEn` / `terminalLabelsRu` / `TerminalLabels` | value / _type_ | every word the widgets draw |
+
+### `stitchkit-tui/widgets`
+
+OpenTUI React widgets over the core state. React, `@opentui/core` and `@opentui/react` are peers;
+this entrypoint never loads `stitchkit`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `TerminalAppShell` / `TerminalPanel` / `TerminalStatusBar` / `TerminalKeyHints` | component | breadcrumbs, status lines, body, fitted key hints and toast overlay; titled rounded panels with a focus frame |
+| `TerminalTable` | component | virtualized live table with header sort marks, tree, filter line and htop keys; row and cell tones in the palette, bold or dim where colour is missing |
+| `terminalToneAttributes` | function | the text attribute that carries a tone without colour: `danger` and `warning` bold, `muted` dim |
+| `TerminalList` | component | sections, fuzzy search line with highlights, `›` cursor, meta, badges, multi-select, description |
+| `runTerminalApp` / `RunTerminalAppOptions` / `RunningTerminalApp` | function / _type_ | start an application: renderer, theme and labels providers, the error boundary, and an exit with 128 + signal after `onClose` on Ctrl-C and every signal OpenTUI catches — a closed window leaves no orphan |
+| `TerminalErrorBoundary` / `TERMINAL_EXIT_SIGNALS` / `TerminalExitSignal` | component / value / _type_ | draws a render error and its stack in place of the screen, where OpenTUI's own boundary renders nothing under production React |
+| `TerminalForm` | component | fields edited in place, cycling choices, masked secrets, inline errors; a form without fields says so and submits `{}` on Enter |
+| `TerminalTextView` / `TerminalJsonView` | component | pager over sanitized wrapped text or toned JSON |
+| `TerminalMeter` / `TerminalMeterGrid` / `TerminalChart` / `TerminalSparkline` | component | htop meters and core grid; btop braille charts with axis |
+| `TerminalTabs` / `TerminalDialog` / `TerminalSpinner` / `TerminalProgressBar` / `TerminalAsyncView` / `TerminalDetails` / `TerminalNotices` / `TerminalHelp` | component | views, confirmation, loading, progress, async states, details, toasts, key help |
+| `TerminalThemeProvider` / `useTerminalPalette` / `useTerminalThemeMode` | component / hook | palette from the terminal's reported background (`auto`) or a fixed mode |
+| `TerminalLabelsProvider` / `TerminalFocusProvider` / `useTerminalFocused` | component / hook | product language and shared focus |
+
+The `stitchkit-tui-gallery` binary shows every widget live.
+
+### `stitchkit-tui/build`
+
+Build-time only; imports Bun and no React.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `compileTerminalApp` / `CompileTerminalAppOptions` | function / _type_ | one standalone executable for any Bun compile target, from any machine, with React's production build defined |
+| `terminalNativePlugin` / `TerminalNativePluginOptions` | function / _type_ | the `Bun.build` plugin behind it: the target's `@opentui/core-<os>-<arch>` at the pinned version from the registry, verified against `bun.lock`; other platforms' packages throw; musl refused |
+| `terminalNativeTarget` / `TerminalNativeTarget` | function / _type_ | the native package a compile target needs |
+
+### `stitchkit-tui/testing`
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `renderTerminalTest` / `TerminalTestScreen` / `TerminalTestOptions` | function / _type_ | a screen inside the kit's providers on a test terminal; `press`, `type`, `burst`, `advance`, `waitForText`, `resize` run inside React's `act` and wait out a lone Esc |
+| `TerminalTestKey` / `TerminalTestModifiers` | _type_ | the mock input's key names and modifiers |
 
 ## `stitchkit/agent-runtime/sqlite/node`
 
@@ -23955,57 +24050,25 @@ SDK, `ai`, or other optional tool peers, so it is safe in a thin CLI bundle.
 
 ## `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) |
@@ -24031,11 +24094,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 |
@@ -24067,7 +24127,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
@@ -24171,6 +24230,77 @@ 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 |
 
+### 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 }`) |
+| `ToolSurfaceProjection` | _type_ | the one readonly `{ services?, runtimeTools? }` container shared by full, MCP-only and introspection surfaces (`buildToolManifest`, `listToolNames`, `summarizeTransports` take `ToolSurfaceProjection<RuntimeToolDefinition>`) |
+| `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
+| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments, including object guards restored from JSON Schema; arbitrary transform pipes stay untouched; throws a `ZodError` naming the field when a union that keeps a string member receives a string that parses to an array its array member accepts |
+| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; 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 |
+
+---
+
+## `stitchkit/tools/mcp`
+
+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` | 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
@@ -24204,44 +24334,26 @@ Interactive MCP resources — [ADR 0019](../decisions/0019-generic-native-tools.
 | `McpAppResourceMeta` | _type_ | resource `_meta` for an MCP App |
 | `McpAppCsp` | _type_ | the widget content-security policy |
 
-### Introspection & internals
+## `stitchkit/tools/agent`
 
-Advanced building blocks — the shared machinery the mounts are built on.
+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 |
 |--------|------|---------|
-| `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 }`) |
-| `ToolSurfaceProjection` | _type_ | the one readonly `{ services?, runtimeTools? }` container shared by full, MCP-only and introspection surfaces (`buildToolManifest`, `listToolNames`, `summarizeTransports` take `ToolSurfaceProjection<RuntimeToolDefinition>`) |
-| `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
-| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments, including object guards restored from JSON Schema; arbitrary transform pipes stay untouched; throws a `ZodError` naming the field when a union that keeps a string member receives a string that parses to an array its array member accepts |
-| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; 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 |
-
----
+| `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 |
 
-## `stitchkit/tools/mcp`
+## `stitchkit/tools/toolkit`
 
-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. 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 | Purpose |
+| Export | Kind | Summary |
 |--------|------|---------|
-| `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 |
-| `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 |
+| `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
+| `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
 
 ## `stitchkit/tools/connections`