stitchkit 0.102.0 → 0.103.1

package/llms-full.txt

@@ -70,26 +70,29 @@ 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 47 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 48 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 47 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 22 of the 48 minors since 0.56.2, most recently 0.97.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 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 |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 10 of the 47 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 11 of the 48 minors since 0.56.2, most recently 0.103.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 |
-| `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — the one part of the kernel that spawns, locks and writes files |
+| `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — an exclusive bounded writer and snapshot reader with explicit anomalies |
 | `stitchkit/application/directory-inbox` | server | evolving | the directory inbox — entries another program drops into a directory, delivered to the application at least once |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
@@ -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) |
@@ -6612,6 +6616,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)
 ==============================================================================
@@ -6622,7 +6766,7 @@ description: Compose process-local resources, schedules, readiness, drain and op
 type: architecture
 status: active
 created: 2026-08-23
-updated: 2026-09-04 14:11 +07:00
+updated: 2026-09-30 17:41 +07:00
 ---
 
 # Managed application kernel
@@ -7269,10 +7413,47 @@ short-lived reclaim guard.
 
 `flush()` means every accepted append through that call's boundary settled. It is not `fsync`, a
 durable receipt, exactly-once execution or remote delivery. Timeout/cancellation bound only the
-waiter; the writer retains physical capacity until settlement. There is no reader or upload API.
-Use a durable application store or deployment-owned log collector when restart recovery, replay or
+waiter; the writer retains physical capacity until settlement. There is no upload or managed replay API.
+Use a durable application store or deployment-owned log collector when durable restart recovery, replay or
 aggregation is required. → [ADR 0134](../decisions/0134-diagnostic-journal-is-bounded-local-evidence.md).
 
+For finite inspection, use the shared reader with an explicit oldest-to-newest list of existing
+files. Keep anomaly reporting outside the journal being inspected:
+
+```ts
+import { readDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
+import { z } from 'zod'
+
+const eventSchema = z.object({
+  kind: z.enum(['resource_failed', 'recovery_started']),
+  resource: z.string().max(80),
+}).strict()
+
+for await (const row of readDiagnosticJournal({
+  paths: ['/var/lib/example/diagnostic.jsonl.1', '/var/lib/example/diagnostic.jsonl'],
+  eventSchema,
+  maxLineBytes: 4 * 1024,
+})) {
+  if (row.type === 'anomaly') internalLogger.warn(row.anomaly)
+  else inspectEvent(row.frame.event)
+}
+```
+
+The reader bounds memory by line size plus a fixed chunk, skips oversized/damaged rows with
+explicit anomalies, and still returns valid rows before and after them. `offset` is zero-based
+bytes; `line` is one-based. `position` distinguishes the file's tail from interior damage.
+A valid frame lacking its final LF yields a warning with `skippedBytes: 0` and its frame.
+Each file's size is captured at open; concurrent appends are excluded. Missing files, permissions,
+symlinks, non-regular files and mid-read truncation throw rather than masquerading as bad data.
+The caller owns file selection and coordination with an active rotator.
+
+Writer startup inspects retained and active files under its lock. On damage,
+`journal.getStatus().recovery` contains counts and first/last anomaly locations, reconstructed
+again on restart from the preserved bytes. This describes startup observations, not live
+continuous inspection. `maxFiles: 1` cannot preserve a torn active file by rotation and throws
+`DiagnosticJournalRecoveryError` before removing any evidence; configure at least two slots.
+Normal rotation retains the existing finite eviction policy. → [ADR 0219](../decisions/0219-journal-damage-is-data-and-io-failure-is-failure.md).
+
 Shutdown performs one phase barrier at a time: stop admission everywhere,
 cancel future schedules, drain admitted work, then close in reverse stable
 topological order. Every hook shares the same grace deadline. Forced cleanup
@@ -14238,6 +14419,35 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.103.0
+
+### Diagnostic journal startup preserves torn evidence and inspects archives
+
+**Who must act:** operators using `maxFiles: 1` who can encounter a torn active
+file, or whose retained files are unreadable by the writer. Clean single-file
+journals continue to work; successful startup now requires read access to every
+retained generation.
+
+```ts
+import { createDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
+
+// Before: a torn active file could be discarded during startup.
+await createDiagnosticJournal({ ...config, limits: { ...config.limits, maxFiles: 1 } })
+// After: retain the torn file while the fresh writer starts in a new active file.
+await createDiagnosticJournal({ ...config, limits: { ...config.limits, maxFiles: 2 } })
+```
+
+With single-file retention, a torn active file throws `DiagnosticJournalRecoveryError`
+from `stitchkit/application`, carrying `recovery` observations and releasing its lock
+without deleting evidence. Inspection I/O errors also fail startup and release the
+lock; restore filesystem access rather than treating that failure as a bad JSON row.
+Normal rotation retains the configured finite eviction policy.
+
+For archive inspection, replace ad hoc line parsing with `readDiagnosticJournal`
+from the same filesystem leaf. Handle its `frame | anomaly` stream explicitly;
+missing files, permissions and unsafe paths still throw. See the
+[journal guide](application-kernel.md#bounded-local-diagnostic-journal).
+
 ## Released migration: 0.102.0
 
 ### `view_file` receives an array, not an array encoded as text
@@ -18916,9 +19126,13 @@ cutovers are covered by the executable
 | `DiagnosticJournalRefusalReasonSchema` / `DiagnosticJournalRefusalReason` | schema / _type_ | `closed \| failed \| invalid \| oversized \| item-capacity \| byte-capacity` |
 | `DiagnosticJournalFailurePhaseSchema` / `DiagnosticJournalFailurePhase` | schema / _type_ | internal `write \| rotation \| close` failure phase exposed only to status and the isolated observer |
 | `DiagnosticJournalWaitOptions` / `DiagnosticJournalFailure` | _type_ | caller wait signal/timeout and isolated internal failure callback record |
+| `DiagnosticJournalAnomalySchema` / `DiagnosticJournalAnomaly` | schema / _type_ | corrupt-row reason, file, zero-based byte offset, one-based line, tail/interior position and skipped bytes |
+| `createDiagnosticJournalReadResultSchema` / `DiagnosticJournalReadResult` | function / _type_ | owner-schema frame output or explicit anomaly; retains transformed event output types |
+| `DiagnosticJournalRecoveryStatusSchema` / `DiagnosticJournalRecoveryStatus` | schema / _type_ | bounded startup inspection counts and first/last anomaly locations |
+| `DiagnosticJournalRecoveryError` | class | torn single-file startup refusal carrying recovery observations, preserving evidence and releasing its lock |
 
 `accepted` is bounded in-memory admission and `written` is completed append, not `fsync` or durable
-delivery. The journal has no reader/replay/upload API. See the
+delivery. Its filesystem reader is in the diagnostic-journal leaf; there is no managed replay/upload API. See the
 [guide](../guide/application-kernel.md#bounded-local-diagnostic-journal),
 [architecture](../architecture/diagnostic-journal.md) and [ADR
 0134](../decisions/0134-diagnostic-journal-is-bounded-local-evidence.md).
@@ -19093,6 +19307,8 @@ snapshots; the adapter owns no SDK lifecycle, polling or delta state.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createDiagnosticJournal` | function | the bounded local journal: a file lock, a spawn to diagnose a stale one, and framed writes |
+| `readDiagnosticJournal` | function | bounded async stream of validated frames and explicit anomalies from finite snapshots of caller-selected files; I/O failures throw |
+| `DiagnosticJournalReaderConfig` | _type_ | normalized absolute `paths`, owner `eventSchema`, positive safe-integer `maxLineBytes` and optional cancellation `signal` |
 
 Its own entrypoint because of what it reaches — `node:child_process`,
 `node:fs`, `node:os`, `node:util` — with `promisify(execFile)` evaluated while
@@ -19434,6 +19650,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
@@ -19531,6 +19752,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 |
@@ -20596,3 +20842,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,7 +9,7 @@ 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.5 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
@@ -24,18 +24,18 @@ 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
-- **stitchkit/application**: [llms/application.txt](llms/application.txt) 46.0 KB → [llms/application.2.txt](llms/application.2.txt) 40.0 KB
+- **stitchkit/application**: [llms/application.txt](llms/application.txt) 37.9 KB → [llms/application.2.txt](llms/application.2.txt) 24.1 KB → [llms/application.3.txt](llms/application.3.txt) 27.3 KB
 - **stitchkit/application/grammy**: [llms/application-grammy.txt](llms/application-grammy.txt) 2.3 KB
 - **stitchkit/application/opentelemetry**: [llms/application-opentelemetry.txt](llms/application-opentelemetry.txt) 1.6 KB
 - **stitchkit/application/directory-inbox**: [llms/application-directory-inbox.txt](llms/application-directory-inbox.txt) 0.3 KB
-- **stitchkit/application/diagnostic-journal**: [llms/application-diagnostic-journal.txt](llms/application-diagnostic-journal.txt) 1.4 KB
+- **stitchkit/application/diagnostic-journal**: [llms/application-diagnostic-journal.txt](llms/application-diagnostic-journal.txt) 1.8 KB
 - **stitchkit/application/schemas**: [llms/application-schemas.txt](llms/application-schemas.txt) 1.8 KB
 - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 30.8 KB
 - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.1 KB
@@ -52,10 +52,13 @@ 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
-- **Upgrading 0.75.0 → 0.102.0**: [llms/upgrading-0.75.0-0.102.0.txt](llms/upgrading-0.75.0-0.102.0.txt) 44.8 KB
+- **Upgrading 0.75.0 → 0.103.0**: [llms/upgrading-0.75.0-0.103.0.txt](llms/upgrading-0.75.0-0.103.0.txt) 46.3 KB
 - **Upgrading 0.61.0 → 0.74.0**: [llms/upgrading-0.61.0-0.74.0.txt](llms/upgrading-0.61.0-0.74.0.txt) 43.5 KB
 - **Upgrading 0.44.0 → 0.60.0**: [llms/upgrading-0.44.0-0.60.0.txt](llms/upgrading-0.44.0-0.60.0.txt) 43.9 KB
 - **Upgrading 0.37.0 → 0.37.0**: [llms/upgrading-0.37.0.txt](llms/upgrading-0.37.0.txt) 6.2 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.102.0",
+  "version": "0.103.1",
   "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": {

package/dist/index-h124epcf.js

@@ -1,103 +0,0 @@
-import {
-  isRecord
-} from "./index-9jfdm5tg.js";
-
-// src/application/diagnostic-journal-contract.ts
-import { z } from "zod";
-var PositiveSafeIntegerSchema = z.number().int().positive().safe();
-var FileModeSchema = z.number().int().min(0).max(511);
-var DiagnosticJournalLimitsSchema2 = z.object({
-  maxEventBytes: PositiveSafeIntegerSchema,
-  maxPendingItems: PositiveSafeIntegerSchema,
-  maxPendingBytes: PositiveSafeIntegerSchema,
-  maxFileBytes: PositiveSafeIntegerSchema,
-  maxFiles: PositiveSafeIntegerSchema
-}).strict().readonly();
-var DiagnosticJournalLockPolicySchema2 = z.enum(["refuse", "reclaim-stale"]);
-var DiagnosticJournalStateSchema2 = z.enum(["open", "draining", "closed", "failed"]);
-var DiagnosticJournalRefusalReasonSchema2 = z.enum([
-  "closed",
-  "failed",
-  "invalid",
-  "oversized",
-  "item-capacity",
-  "byte-capacity"
-]);
-var DiagnosticJournalRefusalCountersSchema = z.object({
-  closed: z.number().int().nonnegative(),
-  failed: z.number().int().nonnegative(),
-  invalid: z.number().int().nonnegative(),
-  oversized: z.number().int().nonnegative(),
-  "item-capacity": z.number().int().nonnegative(),
-  "byte-capacity": z.number().int().nonnegative()
-}).strict().readonly();
-var DiagnosticJournalFailurePhaseSchema2 = z.enum(["write", "rotation", "close"]);
-var DiagnosticJournalStatusSchema2 = z.object({
-  state: DiagnosticJournalStateSchema2,
-  epoch: z.uuid(),
-  limits: DiagnosticJournalLimitsSchema2,
-  lock: z.object({
-    policy: DiagnosticJournalLockPolicySchema2,
-    reclaimedStale: z.boolean()
-  }).strict().readonly(),
-  received: z.number().int().nonnegative(),
-  accepted: z.number().int().nonnegative(),
-  refused: z.number().int().nonnegative(),
-  refusals: DiagnosticJournalRefusalCountersSchema,
-  written: z.number().int().nonnegative(),
-  failedRecords: z.number().int().nonnegative(),
-  pendingItems: z.number().int().nonnegative(),
-  pendingBytes: z.number().int().nonnegative(),
-  inFlight: z.boolean(),
-  rotations: z.number().int().nonnegative(),
-  rotationFailures: z.number().int().nonnegative(),
-  partialTails: z.number().int().nonnegative(),
-  currentFileBytes: z.number().int().nonnegative(),
-  retainedFiles: z.number().int().nonnegative(),
-  lastAcceptedSequence: z.number().int().positive().optional(),
-  lastWrittenSequence: z.number().int().positive().optional(),
-  lastSettledSequence: z.number().int().positive().optional(),
-  lastFailure: z.object({
-    phase: DiagnosticJournalFailurePhaseSchema2,
-    sequence: z.number().int().positive().optional()
-  }).strict().readonly().optional()
-}).strict().readonly();
-var DiagnosticJournalSubmitResultSchema2 = z.discriminatedUnion("outcome", [
-  z.object({
-    outcome: z.literal("accepted"),
-    epoch: z.uuid(),
-    sequence: z.number().int().positive()
-  }).strict().readonly(),
-  z.object({
-    outcome: z.literal("refused"),
-    reason: DiagnosticJournalRefusalReasonSchema2
-  }).strict().readonly()
-]);
-var DiagnosticJournalWaitResultSchema2 = z.object({
-  outcome: z.enum(["settled", "timed-out", "cancelled"]),
-  state: DiagnosticJournalStateSchema2,
-  throughSequence: z.number().int().nonnegative(),
-  settledSequence: z.number().int().nonnegative()
-}).strict().readonly();
-var DiagnosticJournalCloseResultSchema2 = z.object({
-  outcome: z.enum(["closed", "timed-out", "cancelled"]),
-  state: DiagnosticJournalStateSchema2,
-  pendingItems: z.number().int().nonnegative()
-}).strict().readonly();
-var DiagnosticJournalFrameSchema2 = z.object({
-  schemaVersion: z.literal(1),
-  epoch: z.uuid(),
-  sequence: z.number().int().positive(),
-  event: z.json()
-}).strict().readonly();
-function parseDiagnosticJournalMode(mode) {
-  return FileModeSchema.parse(mode ?? 384);
-}
-function readDiagnosticJournalLockDiagnosis2(error) {
-  if (!isRecord(error))
-    return;
-  const diagnosis = error.journalLock;
-  return isRecord(diagnosis) ? diagnosis : undefined;
-}
-
-export { DiagnosticJournalLimitsSchema2, DiagnosticJournalLockPolicySchema2, DiagnosticJournalStateSchema2, DiagnosticJournalRefusalReasonSchema2, DiagnosticJournalFailurePhaseSchema2, DiagnosticJournalStatusSchema2, DiagnosticJournalSubmitResultSchema2, DiagnosticJournalWaitResultSchema2, DiagnosticJournalCloseResultSchema2, DiagnosticJournalFrameSchema2, parseDiagnosticJournalMode, readDiagnosticJournalLockDiagnosis2 };