stitchkit 0.103.0 → 0.103.2

package/llms-full.txt

@@ -81,7 +81,10 @@ own, recorded as an ADR.
 | `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 and reconnect cursor without execution or sinks |
+| `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/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 |
@@ -191,6 +194,7 @@ 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) |
@@ -4173,7 +4177,25 @@ Capable models (Claude, Gemini, GPT) handle that; weaker / cheaper ones can drop
 the field or mangle its strings. Set `flattenUnionInput: true` (on
 `createMcpHandler` / `mountMcp` / `mountAgent`) to advertise each discriminated
 union as a **single flat object** instead — the discriminator becomes an enum and
-each variant's fields become optional with a `Required if <disc> = …` hint.
+each field required by every variant stays required. Other fields become optional
+with `Available if <disc> = …` and, where applicable, `Required if <disc> = …` hints.
+
+**Branch explanations keep their meaning.** A shared description appears once;
+different descriptions are grouped by text and qualified with `When <disc> = …:`.
+A branch without a description does not inherit another branch's explanation.
+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
+```
+
+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).
 
 **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
@@ -6612,6 +6634,146 @@ for receipt queries; do not import runtime internals. Available since 0.100.0;
 existing runtime configurations need no migration.
 
 
+==============================================================================
+# Guide: Agent composition  (docs/guide/agent-composition.md)
+==============================================================================
+
+---
+title: "Agent composition without a second runtime"
+description: "Compose contract tools, authenticated realtime control, React views and exact-run behavioral checks."
+type: architecture
+status: active
+created: 2026-09-30 22:45 +07:00
+updated: 2026-09-30 23:03 +07:00
+participants:
+  - role: authored
+    harness: Codex
+    model: GPT-6
+    at: 2026-09-30 22:45 +07:00
+---
+
+# Compose an agent application
+
+Use these pieces when an application wants the existing headless harness and a generic
+conversation view. An application with its own AI SDK loop keeps `mountAgent`; a product
+with custom message projections can keep its transport and UI. No consumer migration is
+required. Model selection, storage, compaction, approvals and recovery stay with their
+existing owners.
+
+## Resources and tools
+
+```ts
+import {
+  createAgentHarnessFileResources,
+  createHeadlessAgentHarness,
+} from 'stitchkit/agent-runtime/harness';
+import { createAgentHarnessTools } from 'stitchkit/agent-runtime/harness-tools';
+
+const resources = createAgentHarnessFileResources({
+  roots: [{ id: 'guide', kind: 'instruction', path: instructionRoot }],
+  limits: { maxTotalBytes: 256 * 1024 },
+});
+const harness = createHeadlessAgentHarness({
+  protocol, store, models, promptBudget,
+  resources,
+  tools: createAgentHarnessTools(({ context, run }) => ({
+    services: [catalogService],
+    context: { ...context, messageId: run.assistantMessageId },
+    runtimeTools: resources.runtimeTools,
+    lifecycle: authorizeTools,
+    hooks: observeTools,
+  })),
+});
+```
+
+The factory composes application authorization then the runtime fence through `mountAgent`.
+The optional harness-tools leaf preserves the complete tool types, including MCP presenter
+declarations; install the same `ai` and `@modelcontextprotocol/server` peers as for
+`stitchkit/tools`. The base harness stays AI-only. Every mount option remains available, including registry, runtime tools, extension,
+coercion, output stripping, hooks and durability. Async per-run configuration is supported.
+The original tools callback still accepts arbitrary typed AI SDK tools and prepareStep.
+The resource reader is explicitly selected: filtered allowlists do not gain tools merely
+because a loader exists. Root IDs, kinds, provenance and limits are unchanged.
+
+## Server and browser
+
+```ts
+import { bindAgentHarnessRealtime } from 'stitchkit/agent-runtime/realtime';
+
+const binding = bindAgentHarnessRealtime(harness, socket, {
+  async authorize({ identity, request, signal }) {
+    // socket.data comes from your verified Socket.IO handshake, not a browser context.
+    if (!await mayAccessConversation(identity, request, signal)) return null;
+    return { context: { userId: identity.userId } };
+  },
+  onError: reportServerError,
+});
+```
+
+`socket` is the existing `createSocketIOServer` handle, attached to `createServer` (Bun)
+or the Node adapter. The access policy checks every operation, file/reference and metadata
+as well as snapshot/event reads. Session handshake authentication alone is insufficient.
+Conversation ownership and observer/controller roles are application policy; the canonical
+control server additionally enforces its exclusive controller lease.
+
+```ts
+import { createSocketIOClient } from 'stitchkit';
+import { createAgentController } from 'stitchkit/agent-runtime/browser';
+import { useAgent } from 'stitchkit/agent-runtime/react';
+
+const transport = createSocketIOClient({ url: serverUrl, auth: sessionAuth });
+const agent = createAgentController({ transport, conversationId, access: 'control' });
+transport.connect();
+
+function Conversation() {
+  const state = useAgent(agent);
+  const conversation = state.view.conversations[conversationId];
+  // Render canonical messages/parts, transient progress, approvals and state.error.
+  return <Transcript conversation={conversation} status={state.status} error={state.error} />;
+}
+
+await agent.request({
+  operation: 'submit', idempotencyKey: crypto.randomUUID(),
+  parts: [{ type: 'text', text: 'Find available items' }],
+});
+await agent.request({ operation: 'interrupt', runId });
+await agent.request({ operation: 'respond-approval', approvalId, approved: true });
+await agent.close(); // leaves transport and harness alive
+```
+
+Wait for `ready` before sending. Share a controller among views of the same conversation;
+create it at session scope, not during React render. Unmount only unsubscribes the view.
+To release the session, await `close`; to stop the application, separately close the
+binding, transport and harness through the application's shutdown lifecycle. Closing a
+view does not interrupt its remote run. Use explicit `interrupt` for cancellation.
+
+Reconnect reattaches and reads durable state. Mutations are not retried automatically:
+if an acknowledgement is lost, retain the original idempotency key. Incoming event
+buffers and outgoing requests have finite limits; capacity/overflow/lease failures stay
+visible. A server overflow deliberately disconnects the transport; reconnect explicitly.
+
+## Check behavior, not just admission
+
+```ts
+import { inspectAgentRun } from 'stitchkit/agent-runtime/testing';
+
+const ticket = harness.submit(input);
+const admitted = await ticket.admission;
+await ticket.result;
+const result = inspectAgentRun(await harness.snapshot(input.conversationId), admitted.runId);
+result.calledTool('catalog_search');
+result.toolSucceeded('catalog_search');
+result.notCalledTool('catalog_delete');
+result.completed();
+```
+
+`calledTool` proves a call record (including an approved continuation linked through that
+run’s exact input messages); `toolSucceeded` also needs a matching successful result.
+`completed` requires successful terminal output with no pending approval. Prior runs,
+provider/policy stops, failed calls and unfinished runs cannot satisfy those assertions.
+The helper does not invoke a model or poll; the existing runtime ticket owns execution.
+
+
 ==============================================================================
 # Guide: Managed application kernel  (docs/guide/application-kernel.md)
 ==============================================================================
@@ -19506,6 +19668,11 @@ Credential-free provider and concurrency fixtures for Bun and Node tests.
 | `AgentStoreConformanceConfig` | _type_ | `{ createStore(context), cleanup?(context) }` — the factory the contract runs against, plus a teardown that runs once whether the scenario passed or failed |
 | `AgentStoreConformanceContext` | _type_ | `{ conversationIds }` — every conversation the scenario will mutate, handed over **before** the first mutation so an adapter can provision application-owned parent rows; a zero-argument factory stays valid |
 
+`inspectAgentRun` takes `(snapshot, runId)` and returns `completed()`, `calledTool(name)`,
+`notCalledTool(name)` and `toolSucceeded(name)` assertions over durable evidence for
+that exact run. Completion requires terminal reason `success`, not `policy_stop` or
+`provider_stop`, and no pending approval. Successful tools require matching call/result IDs.
+
 ## `stitchkit/agent-runtime/harness`
 
 Server-only evolving facade over the canonical Agent runtime. It requires the optional `ai` peer
@@ -19603,6 +19770,31 @@ Use this entrypoint from client components and shared DTO packages. The full
 
 ---
 
+### Browser control composition
+
+`AgentBrowserRequestSchema` / `AgentBrowserRequest` derive from the trusted control
+protocol but exclude runtime `context`. Submit permits only strict text/file parts;
+file ownership and metadata policy are checked by server authorization. The shared
+`agentControlRealtimeContract` owns `agent:control` acknowledgements and `agent:delivery`.
+
+`createAgentController` / `AgentControllerConfig` take an existing Stitchkit
+realtime `transport`, `conversationId`, `access` (`observe` or `control`), optional
+`timeoutMs` (10000), `maxBufferedEvents` (256), `maxBufferedBytes` (1048576) and
+`maxPendingRequests` (32). All bounds are positive safe integers. One controller owns one
+attachment per conversation on that transport; share the controller between views.
+
+`AgentController` exposes stable `subscribe`, `getSnapshot`, `request(command)` and async
+`close`. `AgentBrowserCommand` uses the canonical operations, without request/conversation identity;
+`submit` requires a caller-owned idempotency key. Unknown-outcome mutations are never
+replayed automatically. `AgentControllerState` distinguishes connecting, ready,
+disconnected, error and closed and retains the canonical full `view` plus safe error
+code/message. Errors in automatic attach/refresh appear there. Reconnect attaches again
+and reads a snapshot; snapshot gaps coalesce, stale generations cannot overwrite state,
+and buffers/queues are bounded. Overflow or failed refresh is visible and requires
+explicit recovery. Closing detaches without closing the shared transport or remote run.
+
+See [agent composition](../guide/agent-composition.md) for a complete wiring example.
+
 ## `stitchkit/agent-runtime/openrouter`
 
 | Export | Kind | Summary |
@@ -20042,7 +20234,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `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 |
+| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; the projection never executes validation |
 | `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |
 | `MountableTool` | _type_ | one operation with separate executable CLI argument schema and model-facing presentation schema |
 | `ToolManifestEntry` | _type_ | one `buildToolManifest` row |
@@ -20668,3 +20860,37 @@ Its types are `BubblewrapSandboxConfig`, `SandboxBackend`, `SandboxCommand`,
 `SandboxPrewarmInput`, `SandboxProcess`, `SandboxRunOptions`, `SandboxSession`,
 and `SandboxState`. The [sandbox guide](../guide/sandbox.md) specifies lifecycle,
 network enforcement, gateway credentials and platform/resource boundaries.
+
+## `stitchkit/agent-runtime/realtime`
+
+Optional evolving Socket.IO server binding. `bindAgentHarnessRealtime` takes `(harness, socket, config)` and returns `close()` for its subscriptions and control connections, without closing
+socket or harness. `AgentHarnessRealtimeConfig` requires `authorize({ identity, request,
+signal })`: return `{ context }` after verifying the session principal, conversation,
+operation, files and metadata, or `null`. Identity is `socket.data` from the application's
+verified handshake. Every request and event delivery is authorized. Observe access does
+not grant mutation; controller leases and approval policy still belong to the harness.
+
+`maxPendingEvents` and `maxPendingAttachments` forward to the canonical control server;
+`maxPendingRequests` bounds in-flight authorization/control requests per socket (32);
+`authorizationTimeoutMs` bounds each authorization (10000 ms). Honor its AbortSignal.
+`onError` receives internal errors; peers receive generic denials. Revoking a conversation
+releases only its attachment. Event overflow closes the socket; explicitly reconnect the
+application transport. A transport's Engine.IO payload limit remains application-owned.
+
+## `stitchkit/agent-runtime/react`
+
+Optional evolving React peer leaf. `useAgent` takes a controller and subscribes through
+`useSyncExternalStore`, returning the same `AgentControllerState` as `getSnapshot()`.
+Create and close the controller at application/session scope. Multiple components can
+observe it; StrictMode and unmount release only the component's own subscription.
+
+## `stitchkit/agent-runtime/harness-tools`
+
+Optional evolving composition of the full `mountAgent` configuration with the runtime
+fence. Its runtime peer is `ai`; its full tool presenter declarations also require
+`@modelcontextprotocol/server`, as `stitchkit/tools` does. The base harness retains its
+AI-only peer boundary. Existing custom tool callbacks need no new import.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createAgentHarnessTools` / `AgentHarnessToolsConfig` | function / _type_ | async per-run full mount configuration (`services` plus all `AgentMountConfig` options); composes application lifecycle then runtime fence exactly once |

package/llms.txt

@@ -9,11 +9,11 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 16.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 45.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 17.1 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 17.0 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 45.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 17.1 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.6 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 9.0 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.4 KB
-- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 45.0 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.9 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
+- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 45.9 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.9 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.5 KB
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.1 KB
@@ -24,10 +24,10 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.1 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 44.8 KB
 - **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 36.8 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 34.3 KB
-- **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.2 KB
-- **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 4.1 KB
+- **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB
+- **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 10.1 KB
 - **stitchkit/agent-runtime/coding-tools**: [llms/agent-runtime-coding-tools.txt](llms/agent-runtime-coding-tools.txt) 4.9 KB
-- **stitchkit/agent-runtime/browser**: [llms/agent-runtime-browser.txt](llms/agent-runtime-browser.txt) 1.6 KB
+- **stitchkit/agent-runtime/browser**: [llms/agent-runtime-browser.txt](llms/agent-runtime-browser.txt) 3.3 KB
 - **stitchkit/agent-runtime/openrouter**: [llms/agent-runtime-openrouter.txt](llms/agent-runtime-openrouter.txt) 1.1 KB
 - **stitchkit/agent-runtime/sqlite/bun**: [llms/agent-runtime-sqlite-bun.txt](llms/agent-runtime-sqlite-bun.txt) 1.8 KB
 - **stitchkit/agent-runtime/sqlite/node**: [llms/agent-runtime-sqlite-node.txt](llms/agent-runtime-sqlite-node.txt) 1.7 KB
@@ -52,6 +52,9 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/google**: [llms/google.txt](llms/google.txt) 1.4 KB
 - **stitchkit/declaration**: [llms/declaration.txt](llms/declaration.txt) 16.0 KB
 - **stitchkit/node**: [llms/node.txt](llms/node.txt) 3.1 KB
+- **stitchkit/agent-runtime/react**: [llms/agent-runtime-react.txt](llms/agent-runtime-react.txt) 1.0 KB
+- **stitchkit/agent-runtime/realtime**: [llms/agent-runtime-realtime.txt](llms/agent-runtime-realtime.txt) 1.8 KB
+- **stitchkit/agent-runtime/harness-tools**: [llms/agent-runtime-harness-tools.txt](llms/agent-runtime-harness-tools.txt) 1.3 KB
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
@@ -69,6 +72,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - [Typed client](https://github.com/max-listov/stitchkit/blob/master/docs/guide/client.md): createClient/createHttpClient, the typed call surface, scoped clients, SSE
 - [MCP & agents](https://github.com/max-listov/stitchkit/blob/master/docs/guide/mcp-and-agents.md): contracts as MCP tools (createMcpHandler) and AI-agent tools (mountAgent); tool lifecycle, extend, identity, a separate tool answer (withToolView)
 - [Agent application runtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/agent-runtime.md): optional durable history, prompt/model composition, stream loop, coordination, fencing and events
+- [Agent composition](https://github.com/max-listov/stitchkit/blob/master/docs/guide/agent-composition.md): tool factories, authorized realtime control, shared React views and exact-run behavior checks
 - [Managed application kernel](https://github.com/max-listov/stitchkit/blob/master/docs/guide/application-kernel.md): process-local resources, readiness, admission, schedules, projections and optional provider adapters
 - [Optional process sandbox](https://github.com/max-listov/stitchkit/blob/master/docs/guide/sandbox.md): Linux Bubblewrap sessions, durable workspace reconnect, network policy and host credential brokering
 - [Generic application primitives](https://github.com/max-listov/stitchkit/blob/master/docs/guide/primitives.md): lifecycle transitions, owner scope, permissions, exact money and quantities, deadlines, audit, delivery and exports — declared, not persisted

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.103.0",
+  "version": "0.103.2",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -221,6 +221,18 @@
     "./node": {
       "types": "./dist/entrypoints/node.d.ts",
       "import": "./dist/entrypoints/node.js"
+    },
+    "./agent-runtime/react": {
+      "types": "./dist/entrypoints/agent-runtime/react.d.ts",
+      "import": "./dist/entrypoints/agent-runtime/react.js"
+    },
+    "./agent-runtime/realtime": {
+      "types": "./dist/entrypoints/agent-runtime/realtime.d.ts",
+      "import": "./dist/entrypoints/agent-runtime/realtime.js"
+    },
+    "./agent-runtime/harness-tools": {
+      "types": "./dist/entrypoints/agent-runtime/harness-tools.d.ts",
+      "import": "./dist/entrypoints/agent-runtime/harness-tools.js"
     }
   },
   "publishConfig": {