stitchkit 0.104.2 → 0.105.1

package/llms/react-keyboard.txt

@@ -9,15 +9,6 @@ Contains: Guide: Keyboard layers and list zones  (docs/guide/keyboard.md) · API
 # Guide: Keyboard layers and list zones  (docs/guide/keyboard.md)
 ==============================================================================
 
----
-title: Keyboard layers and list zones
-description: One listener decides which part of a screen gets a key; lists move real focus with the arrows
-type: guide
-status: active
-created: 2026-09-29
-updated: 2026-09-29
----
-
 # Keyboard layers and list zones
 
 `stitchkit/react/keyboard` answers one question for a React screen: **who gets

package/llms/react.txt

@@ -12,15 +12,6 @@ Also read:
 # Guide: Frontend integrations  (docs/guide/frontend-integrations.md)
 ==============================================================================
 
----
-title: Frontend integrations
-description: Compose Stitchkit with Next.js, React Router or a separate Vite development server
-type: architecture
-status: active
-created: 2026-08-08
-updated: 2026-08-08
----
-
 # Frontend integrations
 
 The official `bun create stitchkit` application uses Next.js with a separate
@@ -81,15 +72,6 @@ shared contract remains the only transport schema source.
 # Guide: React Query policy  (docs/guide/react.md)
 ==============================================================================
 
----
-title: React Query policy
-description: One request-local server client, one browser singleton and explicit retry rules for Stitchkit API errors
-type: guide
-status: active
-created: 2026-09-06
-updated: 2026-09-06
----
-
 # React Query policy
 
 `stitchkit/react` contains policy adapters for TanStack Query. It does not own

package/llms/server.4.txt

@@ -684,7 +684,7 @@ whether the code declares `details`:
 
 The model-facing envelope is `{ error, retryable, details?, _hint? }`; for a code with no
 details schema the framework fills `details` with `{ message }`, so declaring a
-message changes what the model reads there — it used to be the code itself. Put
+message changes what the model reads there; without one it is the code itself. Put
 anything the model must reliably read in `details` or `hint`, not in `message`.
 
 With no `details` schema, the options object forbids `details`. A required

package/llms/server.5.txt

@@ -168,7 +168,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 ### Primitives
 
 | `createFileStateStore` | function | cross-process locked atomic JSON state updates over one Zod schema |
-| `FileStateStoreCorruption` / `FileStateStoreOptions` | _type_ | explicit corrupt-state report/policy and lock timing configuration |
+| `FileStateStoreCorruption` / `FileStateStoreOptions` | _type_ | explicit corrupt-state report/policy, lock timing and the state read cap `maxBytes`; a transition whose resulting state encodes to the bytes it started from writes nothing |
 | Export | Kind | Summary |
 |--------|------|---------|
 | `streamSSE` | function | an async generator → SSE `Response` — [guide](../guide/server.md#sse-streaming) |

package/llms/server.txt

@@ -108,7 +108,7 @@ Three boundaries worth knowing:
 
 - A field of another scope is not a compile error on access — `RuntimeContext`
   keeps its `[key: string]: unknown` index signature (transports write through
-  it). It degrades to `unknown`, so it can no longer pose as a `string`; using it
+  it). It degrades to `unknown`, so it cannot pose as a `string`; using it
   in a typed position fails.
 - The map states what **your** `beforeHandle` / `createAuthHook.inject` puts on
   the context. The framework does not verify a hand-written claim (→ ADR 0075) —

package/llms/stitchkit.txt

@@ -68,6 +68,7 @@ own, recorded as an ADR.
 | `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 |
 | `stitchkit/cli` | server | stable | `createCli` / `createCliInvoker` — runtime and strict NodeNext declarations without MCP SDK / `ai` |
+| `stitchkit/cli/publish` | build and release tooling (Bun or Node, POSIX) | evolving | `publishCli` — commit a verified CLI distribution and move its public manifest last; see [CLI guide](cli.md#publishing-a-complete-version) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture and process-group cancellation |
 | `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity and Bun packaging plugin; no runtime install policy |
@@ -82,25 +83,24 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `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 49 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 50 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, plus the managed-resource conformance kit |
 | `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/agent-runtime` | server | evolving<br>_redefined in 22 of the 49 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 50 minors since 0.56.2, most recently 0.105.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 |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
 | `stitchkit/agent-runtime/browser` | browser + server | evolving | canonical agent records, events, reconnect cursor and optional conversation controller |
-| `stitchkit/agent-runtime/harness-tools` | server | evolving | full mountAgent configuration with the current run fence |
-| `stitchkit/agent-runtime/react` | browser + server | evolving | React subscription to an application-owned agent controller |
-| `stitchkit/agent-runtime/realtime` | server (Bun or Node) | evolving | authorized agent control over the existing Socket.IO server |
+| `stitchkit/agent-runtime/react` | browser + server | evolving, experimental: no committed consumer | React subscription to an application-owned agent controller |
+| `stitchkit/agent-runtime/realtime` | server (Bun or Node) | evolving, experimental: no committed consumer | authorized agent control over the existing Socket.IO server |
 | `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 12 of the 49 minors since 0.56.2, most recently 0.104.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 13 of the 50 minors since 0.56.2, most recently 0.105.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 |
@@ -206,7 +206,6 @@ map — feature → packages:
 | MCP / agent adapters (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
 | Agent application runtime (`stitchkit/agent-runtime`) | `ai` |
 | Headless Agent harness (`stitchkit/agent-runtime/harness`) | `ai` |
-| Harness tools (`stitchkit/agent-runtime/harness-tools`) | `ai` `@modelcontextprotocol/server` (tool declarations) |
 | Agent coding tools (`stitchkit/agent-runtime/coding-tools`) | — |
 | OpenRouter runtime adapter (`stitchkit/agent-runtime/openrouter`) | `ai` `@openrouter/ai-sdk-provider` |
 | SQLite agent store (`stitchkit/agent-runtime/sqlite/bun` or `/node`) | — (runtime built-in) |

package/llms/telegram-screens.txt

@@ -215,8 +215,8 @@ the press was forged (a client can send any bytes) and goes to `onStale`.
 
 A press on a message the record does not know — an older menu higher up — is
 answered in place: a one-message view takes that message over, a longer view is
-sent below it and the pressed message is deleted. Either way the previously
-recorded view is removed: one live menu per chat.
+sent below it and the pressed message is deleted. Either way the recorded
+view is removed: one live menu per chat.
 
 For a message the screens do not own — a notification from the backend —
 `screens.button(link('🔑 Refresh token', refreshToken, { botId }))` makes a

package/llms/testing.txt

@@ -671,6 +671,5 @@ handler pipeline without opening a TCP port.
 | `McpSchemaValidationConfig` / `IncompatibleSchemaPolicy` | _type_ | canonical MCP schema-preparation policy used by real mounts and manifests |
 | `SurfaceRealtimeSchemaPairSchema` | schema | input/output digest pair for args or acknowledgements |
 | `SurfaceSchemaDigestsSchema` | schema | params/input/output/multipart digest object |
-| `serializeSurfaceValue` | function | canonical versioned serialization used for deterministic digests |
 
 ---

package/llms/tools-mcp.txt

@@ -23,7 +23,6 @@ behavior and names. See [MCP guide](../guide/mcp-and-agents.md#mcp--createmcphan
 |--------|------|---------|
 | `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 |
-| `RuntimeMcpToolDefinitionWithOutput` | _type_ | schema-aware MCP-only construction with concrete handler output and presenter input |
-| `RuntimeMcpToolDefinition` | _type_ | heterogeneous MCP registration; the canonical runner validates input/output before invocation |
+| `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 |
-| `RuntimeToolDefinitionWithoutOutput` | _type_ | the shared neutral void definition |

package/llms/tools.2.txt

@@ -59,6 +59,18 @@ An explicit `AppError.retryable` boolean also survives this remote hop. `false`
 `true` on409 remain the application's recommendation through HTTP, CLI, MCP and AI tools.
 Absent metadata keeps the previous defaults and does not alter HTTP transport retries.
 
+A remote failure that carries no stitchkit error envelope — an HTML `503` from a proxy
+during a deploy, a `429` from a rate limiter, a `404` page, a refused connection — keeps
+what the caller can act on and drops what it must not see. A response with a status
+becomes `HTTP_ERROR` with that status and a fixed message; a failure with no response
+becomes `CONNECTION_REQUEST_FAILED` (`502`). Neither carries `details`: the upstream
+body, URL and credentials stay in the raw cause that `onToolError` and `AgentToolError.cause`
+expose in-process. One rule decides `retryable` for every origin: the declared value wins,
+otherwise the status decides (`408`, `429`, `502`, `503`, `504` are retryable, as for any
+local tool). A call the caller cancelled (`REQUEST_ABORTED`) declares `retryable: false`;
+a deadline the remote client hit (`REQUEST_TIMEOUT`, `408`) follows the status like a
+`408` from a local handler.
+
 ## Structured output
 
 When a contract endpoint or runtime tool declares `output`, its MCP tool

package/llms/tools.3.txt

@@ -65,10 +65,10 @@ payload.
 | `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 |
+| `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_ | runtime definition whose handler and presenters share a validated output type |
-| `RuntimeToolDefinitionWithoutOutput` | _type_ | runtime definition with a void handler and no presentation callbacks |
+| `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) |
+| `RuntimeToolDefinitionWithoutOutput` | _type_ | the same construction 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 |
@@ -277,10 +277,9 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `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 |
-| `ToolSurfaceProjection` | _type_ | one readonly services/runtime container shared by full and MCP-only surfaces; executable mounts specialize the runtime definition without pulling in another adapter's peers |
+| `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 |
+| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments; 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 |

package/llms/tools.txt

@@ -749,15 +749,17 @@ For example, an optional object `value` in `single` and a required array `value`
 in `group` advertise:
 
 ```text
-When kind = group: Two to ten references.
 When kind = single: One reference.
-Available if kind = group | single. Required if kind = group
+When kind = group: Two to ten references.
+Available if kind = single | group. Required if kind = group
 ```
 
 A third branch without `value` is absent from those labels. The object and array
 retain their separate shapes; the array's minimum length does not apply to the object.
-Discriminator values, branch explanation labels and joined property order are
-deterministic under branch reordering. → ADR [0221](../decisions/0221-flat-field-explanations-retain-branch-meaning.md).
+Discriminator values, branch explanation labels, enum values and joined
+properties keep the order of their first appearance across the variants, so the
+order you declare is the order the model reads. Alternatives of different kinds
+keep one canonical order, so one declaration always yields one document. → ADR [0221](../decisions/0221-flat-field-explanations-retain-branch-meaning.md).
 
 **A field several variants declare keeps its type.** Flattening puts every
 variant's fields side by side, so a key two variants share has to be advertised