stitchkit 0.94.0 → 0.95.0

package/llms/tools.3.txt

@@ -0,0 +1,288 @@
+# stitchkit/tools — stitchkit docs slice, part 3 of 3
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Parts of this slice:
+- `llms/tools.txt`: Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
+- `llms/tools.2.txt`: Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
+- `llms/tools.3.txt`: API reference: `stitchkit/tools`  (docs/api/reference.md)
+
+==============================================================================
+# API reference: `stitchkit/tools`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/tools`
+
+Server-only. Turns contracts into MCP and AI-agent tools. MCP server surfaces
+need the `@modelcontextprotocol/server` v2 peer; MCP hosts/tests use the separate
+`@modelcontextprotocol/client` package. Agent surfaces need the `ai` peer.
+
+Framework-owned MCP tools advertise the exact declared output schema and return
+the validated value unchanged as `structuredContent`, including arrays, scalars
+and `null`. Tools without an output contract advertise and return no structured
+payload.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createMcpHandler` | function | a stateless dual-era Streamable-HTTP MCP handler — [guide](../guide/mcp-and-agents.md#mcp--createmcphandler) |
+| `createMcpHttpRoute` | function | framework-owned `RawRoute` adapter for an MCP HTTP handler |
+| `createStdioMcpServer` | function | a complete stdio MCP server — [guide](../guide/mcp-and-agents.md#mcp-over-stdio--createstdiomcpserver) |
+| `bindStdioProcessSignals` | function | explicitly bind OS signals to one close-only stdio handle — [guide](../guide/testing-and-deployment.md#stdio-process-signals) |
+| `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces; no-auth configs omit the second argument |
+| `mountMcp` | function | add contract tools to an existing `McpServer` — [guide](../guide/mcp-and-agents.md#mountmcp) |
+| `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service; failed executions reject through the SDK tool-error channel with a safe typed envelope, while successful output is never classified by field name — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
+| `defineRuntimeTool` | function | define one validated pathless operation for explicit MCP, Agent and/or CLI surfaces — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
+| `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
+| `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner; use peer-free `stitchkit/tools/invoker`, or the full `stitchkit/tools` adapter barrel — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
+| `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
+| `mountViewFile` | function | a native multimodal "view file" MCP tool |
+| `resolveMedia` | function | resolve a media reference for a tool result |
+| `validateMcpSchemas` | function | object-shaped assertion over the exact advertised schema surface — compatibility, typed properties and portable formats ([guide](../guide/mcp-and-agents.md#mcp-schema-validation-profile)) |
+| `listToolNames` | function | every contract/runtime tool name with origin, identity and transports — for stable snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
+| `listContractToolNames` | function | the same listing straight from contracts — no handlers or stub services needed |
+| `describeToolCatalog` | function | inspect the exact model-facing names, source identities, schema byte sizes and deferred state; an explicit total byte budget fails closed |
+| `ToolCatalogConfig` / `ToolCatalogEntry` | _type_ | catalog source, transport, optional explicit schema budget and one inspectable result row |
+| `McpHandlerConfig` | _type_ | server surface plus stateless HTTP transport config |
+| `McpHttpConfig` | _type_ | HTTP auth, protected-resource, legacy-era and security options |
+| `McpHttpHandler` | _type_ | framework-owned `{ fetch(request), close() }` lifecycle |
+| `McpHttpSecurityConfig` | _type_ | Fetch-boundary Host and Origin allowlists |
+| `McpLegacyPolicy` | _type_ | `'serve' \| 'reject'` protocol-era compatibility policy |
+| `McpStdioHandle` | _type_ | closeable official stdio transport handle |
+| `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
+| `StdioCloseTarget` | _type_ | minimal close-only target accepted by `bindStdioProcessSignals` |
+| `StdioProcessSignalsOptions` | _type_ | signal source, close callbacks and phased error reporting |
+| `StdioProcessSignalsBinding` | _type_ | close-only signal binding with observed `promise` and listener `close()` |
+| `StdioProcessSignalsErrorPhase` | _type_ | `'prepare' \| 'close' \| 'complete'` reporting phase |
+| `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
+| `McpServerSharedConfig` | _type_ | transport-neutral options shared by direct and finite surface configs |
+| `McpServer` | _type_ | official split-SDK server instance accepted by raw extension points |
+| `DirectMcpSurfaceConfig` | _type_ | static or identity-dynamic `services` / `runtimeTools` source |
+| `FiniteMcpSurfaceConfig` | _type_ | bounded `surfaces` registry plus typed selector |
+| `McpSurfaceDefinition` | _type_ | one immutable `{ services, runtimeTools }` MCP surface |
+| `McpSurfaceRegistry` | _type_ | finite keyed surface registry for eager preparation |
+| `StdioAuthConfig` | _type_ | startup identity composed into `StdioMcpServerConfig` |
+| `McpMountConfig` | _type_ | config for `mountMcp` |
+| `McpSchemaValidationConfig` | _type_ | shared `{ policy, requireTypedProperties, allowUntyped, requirePortableFormats, allowFormats }` profile |
+| `ValidateMcpSchemasConfig` | _type_ | standalone validation profile plus `services`, `extend`, flattening and logger |
+| `RuntimeToolDefinition` | _type_ | transport-neutral pathless operation with identity, schemas, handler and optional presenters |
+| `RuntimeToolDefinitionBase` | _type_ | common name, identity, input, exposure and MCP metadata fields |
+| `RuntimeToolDefinitionWithOutput` | _type_ | runtime definition whose handler and presenters share a validated output type |
+| `RuntimeToolDefinitionWithoutOutput` | _type_ | runtime definition with a void handler and no presentation callbacks |
+| `RuntimeToolFactory` | _type_ | identity/context-bound runtime-tool definition factory |
+| `RuntimeToolFactoryConfig` | _type_ | factory service identity and context schema |
+| `RuntimeToolFactoryDefinitionWithOutput` | _type_ | factory-authored runtime tool with a validated output schema |
+| `RuntimeToolFactoryDefinitionWithoutOutput` | _type_ | factory-authored void runtime tool without presenters |
+| `RuntimeToolFactoryHandlerContext` | _type_ | parsed factory context plus parsed tool input |
+| `RuntimeToolFactoryIdentityFields` | _type_ | per-tool action, semantic method and optional identity metadata |
+| `RuntimeToolIdentity` | _type_ | `{ serviceName, action, scope?, method, meta? }` for runtime lifecycle/audit |
+| `RuntimeToolHandlerContext` | _type_ | runtime context with the definition's parsed input |
+| `RuntimeToolOutput` | _type_ | output inferred from a runtime tool's optional Zod schema |
+| `RuntimeToolPresenters` | _type_ | optional MCP and AI SDK `toModelOutput` presentation callbacks |
+| `RuntimeMcpPresentation` | _type_ | MCP content/metadata result without framework-owned `structuredContent` or `isError` |
+| `RuntimeMcpInput` | _type_ | typed accepted multi-round input for an opted-in runtime tool |
+| `OAuthClientRegistrationConfig` | _type_ | deterministic pre-registered → CIMD → explicit-DCR client resolution |
+| `CimdClientMetadata` | _type_ | validated Client ID Metadata Document |
+| `CimdClientMetadataFetcher` | _type_ | injectable secure network boundary for metadata loading |
+| `CimdFetchResponse` | _type_ | bounded metadata fetch result passed across the injectable network boundary |
+| `CimdFetchPolicy` | _type_ | CIMD timeout, redirect and size limits |
+| `CimdCachePolicy` | _type_ | bounded HTTP-aware cache policy: separate positive/negative pools (`maxEntries`), per-client and server-wide resolution rate limits (`maxResolutionsPerClient` / `maxResolutions` per `resolutionWindowMs`) |
+| `CimdCacheEvent` | _type_ | observable CIMD cache hit, miss, revalidation and eviction event |
+| `createSecureClientMetadataFetcher` | function | production HTTPS, DNS/IP-pinned CIMD fetcher |
+| `RuntimeAgentModelOutput` | _type_ | AI SDK model-facing text/JSON/content output returned by `present.agent` |
+| `AgentMountConfig` | _type_ | config for `mountAgent` |
+| `AgentToolRegistry` / `AgentToolRegistryBuilder` / `AgentToolRegistryInput` | _type_ | the composed runtime surface and its builder: declared defaults, `replace`/`disable` by name, and the exact `{ tools, names }` a mount receives |
+| `defineToolRegistry` | function | compose runtime tools over one declared default set; an unknown `replace`/`disable` name is refused instead of silently leaving the default in place |
+| `AgentContext` | _type_ | the context merged into agent tool handlers |
+| `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
+| `ToolExtend` | _type_ | extra-args extension for `mountMcp` / `mountAgent` |
+| `ToolLifecycle` | _type_ | `beforeHandle` / `afterHandle` gate for tool calls — [guide](../guide/mcp-and-agents.md#guarding-tools--lifecycle) |
+| `ToolExecutionControlReason` | _type_ | internal managed-execution stop reason: stale run or requested interruption |
+| `ToolExecutionControlError` | class | control-flow error used to unwind a superseded managed tool call without presenting it as a model-facing tool failure |
+| `isToolExecutionControlError` | function | narrow an unknown thrown value to the managed execution control error |
+| `ToolOperation` | _type_ | executable path-free operation shape shared by contract and framework-native runners |
+| `ToolCallHooks` | _type_ | object-shaped `beforeToolCall` / `afterToolCall` / `onToolError` observability hooks; the raw thrown value reaches the last two as `error` ([guide](../guide/observability.md#the-cause-behind-a-failed-tool-call)) |
+| `BeforeToolCallOptions` | _type_ | `{ toolName, args, context, endpoint }` passed before execution |
+| `AfterToolCallOptions` | _type_ | completed call options plus `{ result, durationMs, error? }` |
+| `ToolErrorOptions` | _type_ | `{ toolName, error, context, endpoint }` for a thrown handler-path value |
+| `ErrorHintFn` | _type_ | `(toolName, errorCode) => string \| null` — a per-tool recovery hint, shared by every mount |
+| `ToolResult` | _type_ | the result of one tool call |
+| `ToolInvoker` | _type_ | immutable compiled dispatcher (`names`, envelope `invoke`, throwing `invokeOrThrow`) |
+| `ToolInvokerConfig` | _type_ | compile-time exposure, extension and presentation options |
+| `ToolInvocationOptions` | _type_ | per-call source, context, lifecycle, hooks and output-strip reporter |
+| `ToolCallContext` | _type_ | the context every tool hook receives — `{ source, mcp? }` plus whatever the mount's `context` added |
+| `ViewFileOptions` | _type_ | shared URL/managed-file-boundary policy for `defineViewFileTool`, `mountViewFile` and `resolveMedia` |
+| `ViewFileOutput` | _type_ | neutral managed batch result with multimodal `content` and per-item `errors` |
+| `ViewFileInputSchema` | constant | fixed one-or-many media path/URL input schema |
+| `ViewFileOutputSchema` | constant | Zod schema for the neutral managed view-file batch result |
+| `ViewFileErrorSchema` | constant | Zod schema for one structured per-item view failure |
+| `McpAnnotations` | _type_ | MCP annotations on a media result |
+| `McpAnnotationsSchema` | constant | Zod schema for MCP media annotations |
+| `McpMediaContentSchema` | constant | Zod schema for text/image/audio media content |
+| `CollectToolsConfig` | _type_ | options for `collectTools` |
+| `findUntypedProperties` | function | every property in a JSON Schema with no `type`/`enum`/`$ref` — what a model is shown and cannot obey ([guide](../guide/mcp-and-agents.md)) |
+| `UntypedProperty` | _type_ | one such property — `{ path, description? }` |
+| `findNonPortableFormats` | function | deep finder for formats outside the portable MCP/AJV baseline |
+| `NonPortableFormat` | _type_ | one `{ path, format }` portability finding |
+| `PORTABLE_JSON_SCHEMA_FORMATS` | constant | portable-format baseline used by MCP validation |
+| `ToolNameEntry` | _type_ | one `listToolNames` row — `{ kind, name, service, method, transports }` |
+| `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
+| `McpMediaContent` | _type_ | a multimodal MCP content item |
+
+### Native tools
+
+Generic host-supplied operations — managed definitions for the canonical
+runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `defineDownloadTool` | function | define a guarded, size-capped managed download for MCP/Agent `runtimeTools` |
+| `defineUploadTool` | function | define a typed managed local-file upload for MCP/Agent `runtimeTools` |
+| `defineWaitTool` | function | define a typed, cancellable managed polling operation for MCP/Agent `runtimeTools` |
+| `defineViewFileTool` | function | define a guarded, batch-capped managed multimodal operation for MCP/Agent `runtimeTools` |
+| `DefineDownloadToolConfig` | _type_ | Zod input, stable identity, URL resolver, storage policy and presenters for `defineDownloadTool` |
+| `DefineUploadToolConfig` | _type_ | stable identity, typed output, upload callback and presenters for `defineUploadTool` |
+| `DefineWaitToolConfig` | _type_ | Zod input/state, identity, poll/done/timeout policy and presenters for `defineWaitTool` |
+| `DefineViewFileToolConfig` | _type_ | identity, media security policy and optional presenters for `defineViewFileTool` |
+| `ManagedNativeToolConfig` | _type_ | shared name, description, identity, exposure and annotations for managed native factories |
+| `NativeToolIdentity` | _type_ | pathless service/action/scope/meta identity; semantic method is factory-owned |
+| `ManagedWaitRender` | _type_ | optional managed wait terminal text and failure classification |
+| `UploadToolInputSchema` | constant | fixed `{ path: string }` input schema for `defineUploadTool` |
+| `defineAsyncOperation` | function | runtime-only start/status/wait plus configured cancel/result/artifacts definitions; see the [durable application-owned recipe](../guide/mcp-and-agents.md#durable-application-owned-execution) |
+| `defineAsyncOperationContract` | function | define one canonical Zod-first HTTP contract for start/status/wait plus optional capabilities; execution and recovery remain application-owned |
+| `bindContractAsyncOperation` | function | bind literal methods from an existing contract without creating another HTTP surface |
+| `createAsyncOperationSnapshotSchema` | function | canonical pending/running/succeeded/failed/cancelled Zod snapshot |
+| `AsyncOperationSnapshotSchema` | _type_ | the snapshot union `createAsyncOperationSnapshotSchema` returns when no `progress` schema is configured |
+| `AsyncOperationSnapshotSchemaWithProgress` | _type_ | the same union with the configured `progress` schema optional on every phase |
+| `AsyncOperationCancelResultSchema` | constant | validated accepted/already_terminal/rejected cancellation result |
+| `AsyncOperationCancelResult` | _type_ | validated cancel capability result |
+| `AsyncOperationCancelCapability` | _type_ | optional typed domain cancellation callback |
+| `AsyncOperationCapability` | _type_ | generated capability-name union |
+| `AsyncOperationStartDefinition` / `AsyncOperationFollowDefinition` | _type_ | generated runtime definition types |
+| `AsyncOperationIdentity` | _type_ | shared service/action/scope/meta identity for an operation |
+| `AsyncOperationOutputCapability` | _type_ | optional result/artifact schema plus handler |
+| `RuntimeAsyncOperationConfig` | _type_ | runtime-only descriptor configuration |
+| `RuntimeAsyncOperation` | _type_ | inferred generated definitions and schemas |
+| `AsyncOperationContractConfig` | _type_ | canonical contract config where start returns the operation id; optional `expose` names the transports per capability, because this contract is built inside the framework and never passes through a consumer's `toolExposure: 'explicit'` factory |
+| `AsyncOperationContractWithStartOutputConfig` | _type_ | canonical contract config with an application start envelope and typed id extractor |
+| `DefinedAsyncOperationContract` | _type_ | generated contract, capability keys, schemas and parsed adapters |
+| `ContractAsyncOperationConfig` | _type_ | literal contract method binding and handlers |
+| `AdaptedContractAsyncOperationConfig` | _type_ | existing-contract binding with explicit id and per-capability input adapters |
+| `BoundAdaptedContractAsyncOperation` | _type_ | inferred adapted binding with parsed id/input projectors |
+| `AdaptedContractAsyncOperationStartKey` | _type_ | existing-contract keys with a declared start output |
+| `AdaptedContractAsyncOperationFollowKey` | _type_ | existing-contract keys with both input and output schemas |
+| `AdaptedContractAsyncOperationWaitKey` | _type_ | adapted follow-up keys whose output matches the selected status snapshot |
+| `ContractAsyncOperationInputAdapters` | _type_ | guaranteed direct-binding status/wait input adapters plus configured optional capabilities |
+| `ContractAsyncOperationKeys` | _type_ | literal method-key union of a bound contract |
+| `ContractAsyncOperationStartKey` | _type_ | direct-binding start keys whose declared ID schema has stable input/output |
+| `ContractAsyncOperationFollowKey` | _type_ | contract keys whose input schema type matches the selected start output |
+| `ContractAsyncOperationWaitKey` | _type_ | follow-up keys whose output schema type also matches the selected status output |
+| `composeToolLifecycle` | function | ordered composition of tool before/after phases |
+| `mountDownload` | function | raw MCP "download a URL to disk" adapter (SSRF-guarded, size-capped) |
+| `mountUpload` | function | raw MCP "upload a local file" adapter |
+| `mountWait` | function | raw MCP generic `--wait`-style polling adapter |
+| `DownloadToolConfig` | _type_ | config for `mountDownload` |
+| `UploadToolConfig` | _type_ | config for `mountUpload` |
+| `WaitToolConfig` | _type_ | config for `mountWait` |
+
+### OAuth 2.1 provider
+
+A native remote-connector auth surface for MCP — [guide](../guide/mcp-and-agents.md#oauth-21--a-native-remote-connector).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `mountOAuthProvider` | function | the OAuth 2.1 provider routes (DCR, PKCE, token) |
+| `oauthProtectedResourceRoute` | function | the RFC 9728 protected-resource-metadata route |
+| `protectedResourceMetadataUrl` | function | build the metadata URL for a resource |
+| `wwwAuthenticateHeader` | function | build the `WWW-Authenticate` challenge header |
+| `PROTECTED_RESOURCE_PATH` | const | the well-known metadata path |
+| `OAuthProviderConfig` | _type_ | config for `mountOAuthProvider` |
+| `ProtectedResourceConfig` | _type_ | config for `oauthProtectedResourceRoute` |
+| `ApplicationType` | _type_ | DCR `application_type` — `'native'` (loopback allowed) \| `'web'` (https only) |
+| `AuthCodeData` | _type_ | a stored authorization-code record |
+| `AuthRequest` | _type_ | a parsed authorization request |
+| `ClientMetadata` | _type_ | dynamic-client-registration metadata |
+| `RefreshData` | _type_ | a stored refresh-token record |
+| `RegisteredClient` | _type_ | a registered OAuth client |
+
+### Durable tool bodies
+
+A mounted tool body can be made restartable without adopting `agent-runtime`: declare a
+factory and `step` / `sleep` / `waitFor` appear in the handler context, backed by whatever
+ledger the application already has.
+
+```ts
+mountAgent(services, { durability: (toolCallId) => myLedgerFor(toolCallId) });
+```
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `ToolDurability` | _type_ | the port a tool body needs: `step`, `sleep`, `waitFor` |
+| `ToolDurabilityFactory` | _type_ | `(toolCallId, signal) => ToolDurability`, called once per call |
+| `DurableJsonValue` | _type_ | what a durable step result may hold — a record is read back in another process, so it must be JSON |
+| `createLocalStepDurability` | function | the durability engine — replay, absolute deadlines, park/deliver — over a two-method ledger the application owns |
+| `StepDurabilityLedger` | _type_ | the two methods an engine needs: `appendEvent`, `readEvents` |
+| `LocalStepDurability` | _type_ | what the engine returns; satisfies `ToolDurability` and adds `deliver`, `effect` and record introspection for the ledger's owner |
+| `EffectHandlers` / `EffectOutcome` / `EffectRunOptions` | _type_ | `effect(name, { run, reconcile }, { signal, reconcileTimeoutMs })`: the intent is recorded before `run`, an intent without an outcome is settled by `reconcile` and never run again; `accepted` with the proof or a recorded, final `uncertain` → ADR 0200 |
+| `EffectUnresolvedError` | class | an effect whose outcome this call could not settle — `run` or `reconcile` threw, `reconcile` overran, the proof was not recordable; the intent stands and the next call reconciles |
+| `LocalStepDurabilityOptions` | _type_ | `{ store, conversationId, runId, signal?, subscribe?, clock? }` |
+| `AppendAgentStoreEvent` / `ReadAgentStoreEvents` / `AgentStoreEventEnvelope` / `AgentStoreEventPage` | _type_ | the ledger's row shapes, re-exported so a ledger is typed from the entrypoint that consumes it |
+| `AgentToolError` | class | the model-safe envelope a failed agent tool throws |
+| `isAgentToolError` | function | brand check for it — a consumer running its own loop no longer parses the message |
+
+### Catalog stamp
+
+Every advertised tool and every tool result carries the fingerprint of the catalog it came
+from, so a long-lived consumer can see that its own copy is stale **without making a
+request for it**. `createMcpHandler` is stateless by construction and therefore has no
+retained session to push `notifications/tools/list_changed` down; the stamp needs none.
+
+Store the stamp beside the tools when you list them, compare it against the one on every
+result, and re-list when they differ — including on a refusal, which is exactly when a
+stale catalog is the likeliest explanation and the least visible one. The server side
+needs no wiring: every mount stamps what it advertises.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `readMcpCatalogStamp` | function | read a peer's stamp out of `_meta`, or `null` when there is none |
+| `mcpCatalogMeta` | function | the `_meta` fragment a stamped tool or result carries |
+| `MCP_CATALOG_META_KEY` | const | the namespaced `_meta` key (`stitchkit/catalog`) |
+| `McpCatalogStamp` | _type_ | `{ digest, tools }` — the catalog fingerprint and its tool count |
+
+### MCP Apps (widgets)
+
+Interactive MCP resources — [ADR 0019](../decisions/0019-generic-native-tools.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `mountMcpResource` | function | mount an MCP Apps widget resource |
+| `inlineMcpAppBundle` | function | inline a built widget bundle into a resource |
+| `EXT_APPS_BUNDLE_PLACEHOLDER` | const | the placeholder token `inlineMcpAppBundle` replaces |
+| `RESOURCE_MIME_TYPE` | const | the MCP Apps resource MIME type |
+| `McpResourceDef` | _type_ | an MCP Apps resource definition |
+| `McpAppResourceMeta` | _type_ | resource `_meta` for an MCP App |
+| `McpAppCsp` | _type_ | the widget content-security policy |
+
+### Introspection & internals
+
+Advanced building blocks — the shared machinery the mounts are built on.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `collectTools` | function | resolve a service's methods to mountable tools (the shared resolver) |
+| `createToolLogger` | function | a ready `afterToolCall` that logs every tool call — [guide](../guide/mcp-and-agents.md#logging-tool-calls--createtoollogger) |
+| `summarizeTransports` | function | mixed contract/runtime operation counts and per-source breakdown for a boot-time summary |
+| `buildToolManifest` | function | transport-aware searchable `{ name, description, inputSchema }` rows from a mixed surface |
+| `ToolLoggerConfig` | _type_ | config for `createToolLogger` |
+| `ToolCallRecord` | _type_ | the structured record `createToolLogger` passes to `onRecord` |
+| `TransportSummary` | _type_ | `{ contractServices, runtimeTools, totals, sources }` from `summarizeTransports` |
+| `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
+| `ToolSurfaceDefinition` | _type_ | shared object-shaped `{ services?, runtimeTools? }` introspection surface |
+| `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
+| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
+| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; divergent fields retain every provable base kind in a deterministic `type` array, and the projection never executes validation |
+| `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |
+| `MountableTool` | _type_ | one operation with separate executable CLI argument schema and model-facing presentation schema |
+| `ToolManifestEntry` | _type_ | one `buildToolManifest` row |
+
+---

package/llms/tools.txt

@@ -1,4 +1,4 @@
-# stitchkit/tools — stitchkit docs slice, part 1 of 2
+# stitchkit/tools — stitchkit docs slice, part 1 of 3
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
@@ -6,7 +6,8 @@
 
 Parts of this slice:
 - `llms/tools.txt`: Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
-- `llms/tools.2.txt`: Guide: MCP & agents  (docs/guide/mcp-and-agents.md) · API reference: `stitchkit/tools`  (docs/api/reference.md)
+- `llms/tools.2.txt`: Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
+- `llms/tools.3.txt`: API reference: `stitchkit/tools`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
@@ -406,6 +407,30 @@ enters the `stitchkit/tools` graph. An application that *does* run on
 `agent-runtime` gets durability through the run context and needs no option;
 where both exist the runtime's wins, because the run is recorded in its ledger.
 
+#### An effect in another system — `effect`, at most once
+
+`step` records its result **after** the body, so a body cut short by a crash
+runs again. For sending a message or starting a turn at a provider, a repeat is
+worse than a loss. The engine's `effect` records the intent **before** it runs:
+
+```ts
+const sent = await engine.effect('reply', {
+  run: () => chat.send({ clientId, text }),                 // → { messageId }
+  reconcile: (signal) => chat.findByClientId(clientId, { signal }), // → { messageId } | null
+})
+if (sent.outcome === 'uncertain') reportPossiblyLost(clientId)
+```
+
+A later call — the same process or a restarted one — that finds the intent with
+no outcome calls `reconcile`, never `run`. Found is `accepted` with the proof;
+not found is `uncertain`. Both are recorded and final: `run` is never called for
+that name again, and `uncertain` is not asked again — it is the honest third
+answer, and retrying it is the caller's decision under a new name. A `run` that
+throws, or a `reconcile` that throws or overruns `reconcileTimeoutMs` (default
+30 s), rejects with `EffectUnresolvedError` and leaves the intent for the next
+call. The proof is JSON of at most 64 KiB — the identity the recipient assigned,
+not a payload. → [ADR 0200](../decisions/0200-an-effect-is-recorded-before-it-runs.md)
+
 ### Typed MCP call metadata
 
 Contract handlers, runtime-tool handlers/factories, lifecycle and tool hooks all
@@ -939,66 +964,3 @@ official SDK.
 A tool without an output contract advertises no `outputSchema` and returns no
 invented structured value. Its successful MCP result has an empty `content`
 list.
-
-## A different answer for tools — `withToolView`
-
-An admin page wants the full record; a model wants a card. Every byte of a
-tool result enters the model's context and stays in its history, and personal
-fields a task does not need are better never shown to it. Two endpoints on one
-path (one `expose: ['HTTP']`, one for the tools) duplicate the description, the
-schemas and the handler; branching on `ctx.source` teaches every handler about
-transports and still advertises the full output schema.
-
-A **tool view** declares the difference on the endpoint instead:
-
-```ts
-import { defineContract, withToolView } from 'stitchkit';
-
-export const users = defineContract({ prefix: 'users' }, {
-  list: withToolView(
-    {
-      method: 'GET', path: '/', desc: 'List users', tool: { name: 'user_list' },
-      input: UserListQuery,        // include: z.array(...).default(['profile', 'stats'])
-      output: UserListResponse,    // HTTP, OpenAPI and the typed client — unchanged
-    },
-    {
-      defaults: { include: [] },                          // what a tool call gets when it passes nothing
-      output: UserCardList,                               // the tool answer and its schema
-      project: (full, { input }) => ({ items: full.items.map(toCard) }),  // optional: without it, `output` slices
-    },
-  ),
-});
-```
-
-- **One handler, one parser.** `defaults` joins the tool call's arguments
-  *before* the endpoint's own `input` parses them, so the handler receives an
-  ordinary `input` — `include: []` from a tool, the HTTP default from HTTP — and
-  loads only what was asked for. An explicit argument wins over the default.
-- **The answer is derived, then checked.** The handler's result is validated
-  against the full `output` first, as always; then `project` (a pure,
-  synchronous function of the full result and the parsed input) or a slice by
-  the view's `output`, then validation against the view's schema. A projection
-  that throws, returns a Promise or breaks its schema is `INTERNAL_SERVER_ERROR`
-  — a server fault, like any output mismatch.
-- **Where it applies.** The MCP, agent and CLI mounts answer with the view;
-  `outputSchema`, `structuredContent`, the advertised input `default`, the
-  catalog stamp and the surface snapshot follow it. HTTP, OpenAPI, the typed
-  client and the in-process [`createToolInvoker`](#in-process-calls--createtoolinvoker)
-  keep the full answer — code, not a model, is calling there.
-- **Three forms, one helper.** With `output` and `project` the answer has its
-  own schema. With `project` alone it reshapes values inside the full schema.
-  With `output` alone it is a slice, and the full result must fit that schema —
-  `withToolView` refuses the endpoint at compile time when it does not.
-- **Exposure.** A view needs a tool transport. With `createContractFactory({
-  toolExposure: 'explicit' })` an endpoint without `expose` is HTTP-only, so an
-  endpoint with a view names its tool transports in `expose`.
-- **What it refuses.** `defineContract` rejects a view on an endpoint with no
-  tool transport or no full `output`, on a raw, `rawBody`, multipart,
-  `responseMeta` or streaming endpoint, a view that declares neither `output`
-  nor `project`, and a default for a key the input does not have, for a path
-  param, or with a value the input would reject.
-
-A projection adds nothing the full result does not carry: a field the tool
-answer needs belongs in the full answer, loaded by the handler. Keys a
-projection returns beyond its schema are reported by `onOutputStrip`; a slice
-removes keys on purpose and is not reported. → [ADR 0196](../decisions/0196-a-tool-answer-is-a-declared-view.md)

package/llms/{upgrading-0.37.0-0.50.0.txt → upgrading-0.37.0-0.53.0.txt}

@@ -1,14 +1,36 @@
-# Upgrading 0.37.0 → 0.50.0 — stitchkit docs slice
+# Upgrading 0.37.0 → 0.53.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.37.0 → 0.50.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.37.0 → 0.53.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.37.0 → 0.50.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.37.0 → 0.53.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.53.0
+
+### Realtime `emit` returns `boolean` instead of `void`
+
+Every **call site** compiles and behaves exactly as before — the return value
+is new information (`true` = accepted by the transport, `false` = dropped
+while the browser client was disconnected), not a behavior change. What breaks
+is **implementing** the interfaces: a test mock or app-side adapter of
+`SocketIOClient` / `RealtimeClient` / `ValidatedRealtimeSocket` /
+`RealtimeServer` whose `emit` returns `void` no longer typechecks.
+
+```ts
+// before — a void mock satisfied the interface
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => {} }
+// after — report acceptance (true is what a live server-side emit reports)
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => true }
+```
+
+While migrating, consider replacing hand-rolled `if (client.connected)` guards
+with the new honest surface: check `client.emit(...) === false`, or observe
+drops centrally with `onDroppedEmit`.
+
 ## Released migration: 0.50.0
 
 ### The factory's scope union now covers per-endpoint overrides

package/llms/{upgrading-0.53.0-0.67.0.txt → upgrading-0.55.0-0.68.0.txt}

@@ -1,14 +1,64 @@
-# Upgrading 0.53.0 → 0.67.0 — stitchkit docs slice
+# Upgrading 0.55.0 → 0.68.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.53.0 → 0.67.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.55.0 → 0.68.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.53.0 → 0.67.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.55.0 → 0.68.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.68.0
+
+### Make Unix transport selection explicit outside Bun
+
+The legacy `unix` option remains a Bun convenience, but on Node or another
+runtime it now fails before dispatch. Replace it with the owned adapter and close
+that adapter with the application:
+
+```ts
+// before — unsafe outside Bun: an unsupported fetch could dial baseUrl over TCP
+const http = createHttpClient({ baseUrl, unix: '/run/service.sock' })
+
+// after — Bun and Node; every dispatch and redirect stays on the socket
+import { createUnixClientTransport } from 'stitchkit/server' // or stitchkit/node
+const transport = createUnixClientTransport({ socketPath: '/run/service.sock' })
+const http = createHttpClient({ baseUrl, fetch: transport.fetch })
+// during shutdown
+await transport.close()
+```
+
+Do not automatically replay `possibly-dispatched`: a timeout or connection loss
+after bytes left the process does not prove that a write did not happen.
+
+### Choose tolerant stream parsing explicitly
+
+`parseNDJSON` and `parseSSE` now throw on malformed JSON, invalid UTF-8 and an
+over-limit line. The default line ceiling is 1 MiB. If a feed deliberately skips
+bad records, retain that policy explicitly:
+
+```ts
+// before — malformed input disappeared implicitly
+parseNDJSON(response)
+
+// after — ordinary fail-closed path
+parseNDJSON(response, { maxLineBytes: 256 * 1024 })
+
+// after — deliberately tolerant path
+parseNDJSON(response, { onParseError: (raw, error) => report(raw, error) })
+```
+
+### Extend exhaustive framework-error handling
+
+If a switch makes `StitchErrorCode` exhaustive, add
+`STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
+`STREAM_TERMINAL_MISSING` and `STREAM_LIFETIME_EXCEEDED`. A partial application
+status map needs no change (ADR 0105).
+
+The admission/channel APIs and endpoint `stream` descriptor are additive; raw
+responses and raw `streamingRoute` remain supported.
+
 ## Released migration: 0.67.0
 
 Three application-kernel changes. Two of them fix silent failures, so the most
@@ -1150,25 +1200,3 @@ Downloaded `path` is now relative to the boundary and MIME metadata is named
 same way. Auth predicates must explicitly return `true`, `false`, or a plain
 object of context fields; replace accidental `undefined` fallthroughs with the
 intended boolean.
-
-## Released migration: 0.53.0
-
-### Realtime `emit` returns `boolean` instead of `void`
-
-Every **call site** compiles and behaves exactly as before — the return value
-is new information (`true` = accepted by the transport, `false` = dropped
-while the browser client was disconnected), not a behavior change. What breaks
-is **implementing** the interfaces: a test mock or app-side adapter of
-`SocketIOClient` / `RealtimeClient` / `ValidatedRealtimeSocket` /
-`RealtimeServer` whose `emit` returns `void` no longer typechecks.
-
-```ts
-// before — a void mock satisfied the interface
-const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => {} }
-// after — report acceptance (true is what a live server-side emit reports)
-const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => true }
-```
-
-While migrating, consider replacing hand-rolled `if (client.connected)` guards
-with the new honest surface: check `client.emit(...) === false`, or observe
-drops centrally with `onDroppedEmit`.