stitchkit 0.118.1 → 0.120.0

package/llms/agent-runtime.3.txt

@@ -1,12 +1,14 @@
-# stitchkit/agent-runtime — stitchkit docs slice, part 3 of 3
+# stitchkit/agent-runtime — stitchkit docs slice, part 3 of 4
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
+> Continues in `llms/agent-runtime.4.txt`.
 
 Parts of this slice:
 - `llms/agent-runtime.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 - `llms/agent-runtime.2.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
-- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md)
+- `llms/agent-runtime.4.txt`: API reference: `stitchkit-tui`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
@@ -431,47 +433,3 @@ is an optional atomic capability required by receipt admission, and
 stores supply both; custom adapters must honor the once-only transaction contract.
 A driver's optional `events.find(transaction, { conversationId, eventId })` makes
 both one lookup instead of a scan of the conversation log.
-
-==============================================================================
-# API reference: `stitchkit-tui`  (docs/api/reference.md)
-==============================================================================
-
-## `stitchkit-tui`
-
-Separate optional evolving Bun/OpenTUI package over a caller-composed headless harness.
-
-| 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 |
-| `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 |
-| `listAgentTuiSessions` | function | discover live local terminal session IDs and their current conversation |
-| `createAgentTuiComposer` / `navigateAgentTuiHistory` | function | multiline draft and reversible prompt-history state |
-| `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`,
-`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,
-not a remote API.
-Interactive `/resume` and `/sessions` open the durable conversation picker. `/clear` creates a new
-conversation and keeps the previous one available there; it is not a viewport-only operation.
-The slash palette owns its highlighted selection: Up/Down move it, Tab completes it, Enter runs
-the exact command and Escape dismisses it. Partial input is never submitted while the palette is
-active; unknown slash text with no match remains an ordinary model prompt.
-
-### `stitchkit-tui/core`
-
-Renderer-neutral state only. This entrypoint imports neither React/OpenTUI nor the agent runtime.
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `createTerminalCollection` / `reduceTerminalCollection` | function | identity-stable live collection selection, reconciliation, windowing and resize |
-| `createTerminalFeedViewport` / `reduceTerminalFeedViewport` | function | generic follow-tail, history anchoring, unseen and bounded visible-range state |
-| `createTerminalPaneState` / `reduceTerminalPaneState` | function | bounded split-pane focus, resize and single-pane collapse |
-| `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 |

package/llms/agent-runtime.4.txt

@@ -0,0 +1,113 @@
+# stitchkit/agent-runtime — stitchkit docs slice, part 4 of 4
+
+> 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/agent-runtime.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
+- `llms/agent-runtime.2.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
+- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md)
+- `llms/agent-runtime.4.txt`: API reference: `stitchkit-tui`  (docs/api/reference.md)
+
+==============================================================================
+# API reference: `stitchkit-tui`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit-tui`
+
+Separate optional evolving Bun/OpenTUI package over a caller-composed headless harness.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `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 |
+| `listAgentTuiSessions` | function | discover live local terminal session IDs and their current conversation |
+| `createAgentTuiComposer` / `navigateAgentTuiHistory` | function | multiline draft and reversible prompt-history state |
+| `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 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,
+not a remote API.
+Interactive `/resume` and `/sessions` open the durable conversation picker. `/clear` creates a new
+conversation and keeps the previous one available there; it is not a viewport-only operation.
+The slash palette owns its highlighted selection: Up/Down move it, Tab completes it, Enter runs
+the exact command and Escape dismisses it. Partial input is never submitted while the palette is
+active; unknown slash text with no match remains an ordinary model prompt.
+
+### `stitchkit-tui/core`
+
+Renderer-neutral state only. This entrypoint imports neither React/OpenTUI nor the agent runtime.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createTerminalCollection` / `reduceTerminalCollection` | function | identity-stable live collection selection, reconciliation, windowing and resize |
+| `createTerminalFeedViewport` / `reduceTerminalFeedViewport` | function | generic follow-tail, history anchoring, unseen and bounded visible-range state |
+| `createTerminalPaneState` / `reduceTerminalPaneState` | function | bounded split-pane focus, resize and single-pane collapse |
+| `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 |

package/llms/agent-runtime.txt

@@ -1,4 +1,4 @@
-# stitchkit/agent-runtime — stitchkit docs slice, part 1 of 3
+# stitchkit/agent-runtime — stitchkit docs slice, part 1 of 4
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
@@ -7,7 +7,8 @@
 Parts of this slice:
 - `llms/agent-runtime.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 - `llms/agent-runtime.2.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
-- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md)
+- `llms/agent-runtime.4.txt`: API reference: `stitchkit-tui`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)
@@ -18,16 +19,16 @@ Parts of this slice:
 > **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
@@ -51,12 +52,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:
 
@@ -77,7 +74,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() }),

package/llms/cli.txt

@@ -36,7 +36,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.
 

package/llms/contract.txt

@@ -176,33 +176,55 @@ tools. Narrow it with `expose`:
 
 - `expose: ['HTTP']` — HTTP only. The endpoint never becomes a tool.
 - `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
-- omit `expose` — all transports.
+- `expose: []` — no transport; the endpoint stays hidden.
+- omit `expose` — HTTP, MCP and AGENT; CLI is opt-in.
 
-For a curated or security-sensitive tool surface, opt into explicit tool
-exposure at the scoped factory:
+Choose an application's default surface at its scoped factory. Scope and policy
+are inferred in separate calls, so the returned endpoint types retain exact transports:
 
 ```ts
-const { defineContract } = createContractFactory<AppScope>({
-  toolExposure: 'explicit',
+const { defineContract } = createContractFactory<AppScope>().configure({
+  toolExposure: { default: ['HTTP', 'CLI'] },
 })
 ```
 
-With this policy, omitting `expose` materializes `['HTTP']` on the returned
-endpoint. MCP, Agent and CLI then require an explicit endpoint array. The plain
-factory and `defineContract` keep the default-on behaviour above.
+An omitted `expose` (including `undefined`) materializes this array on the returned
+endpoint before validation. An explicit endpoint array **replaces** it, never merges
+with it: `['HTTP']` stays HTTP-only, `['MCP']` enables only MCP, and `[]` hides the
+operation everywhere. Types, HTTP routes, typed clients, tools, CLI, OpenAPI and
+transport summaries read that same materialized exposure.
 
-Consequently, `expose: ['HTTP']` is redundant inside a factory configured with
-`toolExposure: 'explicit'`: omit it unless the explicit spelling is useful to a
-local reader. Add `MCP`, `AGENT` or `CLI` only on endpoints that intentionally
-join those surfaces.
+HTTP client methods and URL builders require a **guaranteed** HTTP transport:
+pass a literal policy array directly to `configure` so its const generic infers
+the tuple. A stored array, even with `satisfies ContractFactoryConfig`, can widen
+to `Transport[]` and contain no HTTP at runtime,
+so it does not promise an HTTP method. Optional capabilities preserve both
+possible effective exposures rather than claiming an unfiltered default tuple.
 
-Tool transports (`MCP`, `AGENT`) skip four kinds of endpoint automatically:
-`multipart` (a file upload is not a tool call),
-[`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
-a tool result cannot carry — it would serialize to `{}`),
-[`responseMeta`](./server.md#typed-json-response-metadata) (outbound HTTP
-headers have no meaning on a tool call) and `rawBody` (HTTP-only by
-construction).
+The same holds for an endpoint whose own type is broad, with or without a factory:
+a value annotated as `EndpointDef` or `FactoryScopedEndpoint<Scope>` carries
+`expose?: readonly Transport[]`, which may hold no HTTP, so it has no client method
+or URL. A helper that builds endpoints keeps their literal type with a const generic:
+
+```ts
+const endpoint = <const Endpoint extends FactoryScopedEndpoint<AppScope>>(value: Endpoint) => value
+```
+
+For a curated tool surface use `toolExposure: { default: ['HTTP'] }`, then name
+tool transports only on endpoints that intentionally join them. An empty default
+is legal. Each `configure` snapshots its array independently; it does not change
+the base factory, sibling configurations or authored endpoints. The no-config
+factory and plain `defineContract` keep the default-on behaviour above.
+
+Six intrinsic HTTP-only forms intersect an **implicit factory default** with HTTP:
+`multipart`, [`rawResponse`](./server.md#raw-response-endpoints),
+[`responseMeta`](./server.md#typed-json-response-metadata), `rawBody`, streaming
+responses and `HEAD`. Under `['HTTP', 'CLI']` they receive `['HTTP']`; under
+`['CLI']` or `[]` they receive `[]`, not an implicitly reopened HTTP route.
+An **explicit** non-HTTP exposure on any of them is a definition error, not a
+silent downgrade. `safelistedBody` only changes HTTP parsing and remains
+multi-transport. A factory policy applies only to contracts authored through
+that factory, not to contracts another helper builds internally.
 
 ## Tool options (`tool`)
 
@@ -220,7 +242,7 @@ endpoint that can never be a tool (a raw response, a stream, `responseMeta`,
 
 `expose` stays outside the group: it chooses transports, HTTP included.
 Setting `tool` on an endpoint with no tool transport — `expose: ['HTTP']`, or an
-omitted `expose` under a factory with `toolExposure: 'explicit'` — throws at
+omitted `expose` under a factory with a default containing no tool transport — throws at
 definition time. The pre-0.94 top-level keys (`toolName`, `toolView`, `ui`,
 `annotations`, `mcp`) are refused by name, with where each one went.
 
@@ -504,11 +526,11 @@ from the root `stitchkit`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `defineContract` | function | declare a contract — [guide](../guide/contracts.md#definecontract) |
+| `ConfiguredScopedDefineContract` | _type_ | scoped authoring parameterized by the exact default transport tuple; explicit endpoint exposure replaces it |
+| `ConfiguredToolExposureEndpoints` | _type_ | endpoint map with materialized exposure; a second generic selects defaults (HTTP when omitted), preserving explicit, optional and conditional overrides |
 | `createContractFactory` | function | a `defineContract` whose scope — on the contract **and** on any endpoint override — is required and held to your union, retaining each concrete literal — [guide](../guide/contracts.md#scope) |
-| `ContractFactoryConfig` | _type_ | optional scoped-factory policy, including explicit tool exposure |
-| `ContractFactoryToolExposure` | _type_ | `'explicit'` — omitted endpoint exposure materializes as HTTP-only |
-| `ExplicitScopedDefineContract` | _type_ | scoped factory authoring with explicit tool opt-in |
-| `ExplicitToolExposureEndpoints` | _type_ | endpoint map after missing exposure is materialized as `['HTTP']` |
+| `ContractFactoryConfig` | _type_ | configuration passed to `createContractFactory<Scope>().configure({ toolExposure: { default: [...] } })`; the constructor itself takes no arguments |
+| `ContractFactoryToolExposure` | _type_ | `default: readonly Transport[]`; omitted endpoint exposure uses the immutable policy snapshot, intersected with intrinsic HTTP-only capabilities |
 | `FactoryScopedEndpoint` | _type_ | an endpoint authored through the factory — its own `scope` override is held to the same union |
 | `ScopedContractDef` | _type_ | a factory-defined contract whose `meta.scope` is the required concrete literal |
 | `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns — endpoint `scope` overrides join the union |

package/llms/geo-contract.txt

@@ -0,0 +1,23 @@
+# stitchkit/geo/contract — 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/geo/contract`  (docs/api/reference.md)
+
+Also read:
+- see `llms/geo.txt` for the GeoIP guide
+
+==============================================================================
+# API reference: `stitchkit/geo/contract`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/geo/contract`
+
+The place snapshot's schema, browser-safe, for a shared contract. Brings `zod`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `GeoAttributionSchema` / `GeoAttribution` | schema / _type_ | the strict readonly Zod owner of the snapshot `stitchkit/geo` resolves — [guide](../guide/geo.md#lookups) |
+
+---

package/llms/geo.txt

@@ -70,7 +70,45 @@ const attribution = await geo.resolve(requestIp);
 `resolve` returns `null` for invalid, loopback, private, link-local and otherwise
 non-public addresses without querying the reader. A database miss or lookup
 failure also returns `null`; `onError` receives operational failures. A result
-may include country, region, city, postal, coordinates, timezone and ASN fields.
+is a sparse `GeoAttribution`: absent facts have no own property, not `null` or
+an own `undefined` value. City and ASN can be present independently. The default
+mapper preserves the complete City + ASN place snapshot:
+
+| Fields | Meaning |
+|--------|---------|
+| `continentCode`, `continentName`, `continentGeonameId` | continent code, English name and GeoNames identifier |
+| `countryCode`, `countryName`, `countryGeonameId` | the country the database locates the address in; absent when the record locates none |
+| `registeredCountryCode`, `registeredCountryName`, `registeredCountryGeonameId` | the country the address block is registered to, a separate fact |
+| `regionCode`, `regionName`, `regionGeonameId` | first subdivision |
+| `city`, `cityGeonameId`, `postalCode` | city and postal facts; no city is required |
+| `latitude`, `longitude`, `timezone`, `accuracyRadiusKm` | coordinates, timezone and accuracy radius in kilometres; zero is a value |
+| `autonomousSystemNumber`, `autonomousSystemOrganization` | finite autonomous system number and organisation |
+| `localizedNames` | every available language under optional `continent`, `country`, `registeredCountry`, `region` and `city` dictionaries |
+
+No locale is synthesised: without English names, localized dictionaries make a
+meaningful result, but `countryName`, `regionName` or `city` stays absent. The
+located country is never inferred from the registered one — an application that
+wants a country for every address chooses `countryCode ?? registeredCountryCode`
+itself, knowing which fact it used. Empty localized groups are omitted. Each field
+is validated on its own by the schema: text is nonempty, GeoNames identifiers and
+`accuracyRadiusKm` are nonnegative safe integers, latitude and longitude are in
+range. A malformed field is omitted without erasing the other valid facts. Unknown
+vendor fields are not projected.
+
+A snapshot carries every language the database has: with the eight GeoLite2
+languages in all five groups it is 1–1.5 KB of JSON. An application that stores
+one per visit and needs fewer languages maps the result to its own shape.
+
+`GeoAttributionSchema` is the strict, readonly Zod owner of the DTO. It lives in
+the browser-safe `stitchkit/geo/contract`, so a shared contract validates a stored
+or transported snapshot without the server-only resolver. Every field is optional
+and readonly; use `.unwrap()` before composing the underlying object schema. The
+mapper copies localized dictionaries, so later reader mutations do not change a
+snapshot. An empty or unrecognised record returns `null`.
+
+An explicit `map` callback receives the raw reader result and owns its
+answer. The resolver does not apply `GeoAttributionSchema` after a custom mapper,
+strip its application fields or replace its returned object.
 
 When a reload succeeds, new lookups move to the new generation immediately.
 The previous reader closes only after its in-flight lookups finish.
@@ -100,6 +138,4 @@ adapter is used.
 | `createGeoIpResolver` / `GeoIpResolver` / `GeoIpResolverOptions` / `GeoIpSnapshot` | function / _type_ | public-IP lookup over one stable reader generation; unavailable start, last-known-good degraded reload and cleanup are explicit states |
 | `createMaxMindGeoIpLoader` / `MaxMindGeoIpLoaderOptions` / `MaxMindGeoIpPaths` | function / _type_ | lazy optional-peer City+ASN loader with stable before/after file revision checks |
 | `GeoIpReader` / `GeoIpReaderLoader` | _type_ | peer-neutral reader/generation seam for adapters and tests |
-| `GeoAttribution` / `mapGeoIpRecord` | _type_ / function | generic optional place and autonomous-system projection; application-specific fields remain outside |
-
----
+| `GeoAttribution` / `mapGeoIpRecord` | _type_ / function | strict readonly sparse City + ASN snapshot: continent, located and registered country as separate facts, GeoNames IDs, first region/city/postal, coordinates/timezone, `accuracyRadiusKm`, autonomous system and all source languages in five `localizedNames` groups; each malformed field is omitted on its own; custom resolver mappers remain app-owned — [guide](../guide/geo.md#lookups) |

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 |
@@ -86,16 +88,17 @@ own, recorded as an ADR.
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
 | `stitchkit/voice` | browser **and** server | evolving | the mechanics of a live voice reply — `SentenceCutter`, `speakableText`, a `SpeechQueue` that synthesises ahead and stops on interruption, the conversation phases |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
+| `stitchkit/geo/contract` | browser **and** server | evolving | the place snapshot schema, for a shared contract that stores or sends `GeoAttribution`; brings `zod` |
 | `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 63 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 63 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 |
@@ -107,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 63 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 |
@@ -210,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`) | — |
@@ -239,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 |