stitchkit 0.103.0 → 0.103.2

package/dist/index-vgkbcnkc.js

@@ -0,0 +1,29 @@
+import {
+  createBoundedSinkManager
+} from "./index-h97tqqp1.js";
+import {
+  AgentRuntimeEventSchema2
+} from "./index-mnkk1ffz.js";
+
+// src/agent-runtime/events.ts
+function createAgentRuntimeEventSink2(config) {
+  const manager = createBoundedSinkManager({
+    write: config.write,
+    ...config.maxPending !== undefined && { maxPending: config.maxPending },
+    ...config.onSinkError && { onSinkError: config.onSinkError },
+    ...config.onDrop && { onDrop: config.onDrop }
+  });
+  return {
+    publish(rawEvent) {
+      const event = AgentRuntimeEventSchema2.parse(rawEvent);
+      const projected = config.project?.(event) ?? (config.project ? undefined : event);
+      if (projected)
+        manager.submit(() => AgentRuntimeEventSchema2.parse(projected));
+    },
+    flush: (bound) => manager.flush(bound),
+    getStatus: () => manager.getStatus(),
+    close: (bound) => manager.close(bound)
+  };
+}
+
+export { createAgentRuntimeEventSink2 };

package/dist/{index-7z9ym7t8.js → index-x87j7csh.js}

@@ -308,7 +308,26 @@ function commonBaseType(schemas) {
   const types = normalizeTypes(nullable ? [...bases, "null"] : bases);
   return types.length > 0 ? { type: types } : {};
 }
-function mergePropertySchemas(properties) {
+function describeVariants(properties, discriminator) {
+  const groups = new Map;
+  for (const { schema, labels } of properties) {
+    if (typeof schema.description !== "string")
+      continue;
+    const group = groups.get(schema.description) ?? [];
+    group.push(...labels);
+    groups.set(schema.description, group);
+  }
+  if (groups.size === 0)
+    return;
+  if (groups.size === 1 && properties.every(({ schema }) => typeof schema.description === "string")) {
+    return groups.keys().next().value;
+  }
+  return [...groups].map(([description, labels]) => ({
+    description,
+    labels: [...new Set(labels)].sort().join(" | ")
+  })).sort((left, right) => left.labels < right.labels ? -1 : left.labels > right.labels ? 1 : 0).map(({ description, labels }) => `When ${discriminator} = ${labels}: ${description}`).join(" ");
+}
+function mergePropertySchemas(properties, discriminator) {
   const schemas = properties.map((property) => nullableProjection(property.schema));
   const structural = schemas.map(withoutAnnotations);
   const [first] = structural;
@@ -318,13 +337,14 @@ function mergePropertySchemas(properties) {
   } else {
     const values = schemas.map(stringValues);
     const allStrings = values.every((value) => value !== null);
-    merged = allStrings ? { type: "string", enum: [...new Set(values.flatMap((value) => value ?? []))] } : commonBaseType(structural);
-  }
-  const descriptions = [
-    ...new Set(schemas.map((schema) => schema.description).filter((value) => typeof value === "string"))
-  ];
-  if (descriptions.length === 1)
-    merged.description = descriptions[0];
+    merged = allStrings ? { type: "string", enum: [...new Set(values.flatMap((value) => value ?? []))].sort() } : commonBaseType(structural);
+  }
+  const description = describeVariants(properties.map((property, index) => ({
+    ...property,
+    schema: typeof property.schema.description === "string" ? property.schema : schemas[index] ?? property.schema
+  })), discriminator);
+  if (description !== undefined)
+    merged.description = description;
   return merged;
 }
 
@@ -434,20 +454,21 @@ function flattenNode(node) {
     });
   }
   const properties = {
-    [discriminator.key]: mergePropertySchemas(discriminatorProperties)
+    [discriminator.key]: mergePropertySchemas(discriminatorProperties, discriminator.key)
   };
   const required = [discriminator.key];
-  for (const [key, entries] of perKey) {
-    let merged = mergePropertySchemas(entries);
+  for (const [key, entries] of [...perKey].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) {
+    let merged = mergePropertySchemas(entries, discriminator.key);
     const requiredEverywhere = entries.length === variants.length && entries.every((entry) => entry.required);
     if (requiredEverywhere) {
       required.push(key);
     } else {
       const requiredLabels = entries.filter((entry) => entry.required).flatMap((entry) => entry.labels);
       const presentLabels = entries.flatMap((entry) => entry.labels);
-      const labels = requiredLabels.length > 0 ? requiredLabels : presentLabels;
-      const verb = requiredLabels.length > 0 ? "Required" : "Available";
-      merged = appendHint(merged, `${verb} if ${discriminator.key} = ${[...new Set(labels)].join(" | ")}`);
+      merged = appendHint(merged, `Available if ${discriminator.key} = ${[...new Set(presentLabels)].sort().join(" | ")}.`);
+      if (requiredLabels.length > 0) {
+        merged = appendHint(merged, `Required if ${discriminator.key} = ${[...new Set(requiredLabels)].sort().join(" | ")}`);
+      }
     }
     properties[key] = merged;
   }

package/dist/{index-3ct7hhq6.js → index-xwq9j1sf.js}

@@ -17,7 +17,7 @@ import {
 } from "./index-b2bz0kdm.js";
 import {
   resolveTraceContext2
-} from "./index-hby4qhax.js";
+} from "./index-yex7eg1v.js";
 import {
   DEFAULT_CONTRACT_STREAM_FRAME_BYTES2
 } from "./index-r5c4fedv.js";
@@ -25,13 +25,12 @@ import {
   joinRoutePath,
   parseTrailingWildcard
 } from "./index-m38ej7e5.js";
-import {
-  createValidatedRealtimeSocket,
-  isModuleNotFound
-} from "./index-m79yr938.js";
 import {
   RELEASE_HEADER2
 } from "./index-n15jny5b.js";
+import {
+  isModuleNotFound
+} from "./index-srs8hj9c.js";
 import {
   assertCorsConfig,
   isOriginAllowed,
@@ -50,7 +49,7 @@ import {
   getRequestContext2,
   setRequestEndpoint2,
   setRequestError2
-} from "./index-r1z0rd9c.js";
+} from "./index-7n68nmc6.js";
 import {
   resolveTraceId2,
   resolveSocketIp2,
@@ -2341,55 +2340,6 @@ function bindProcessSignals2(handle, options = {}) {
   return { promise, close };
 }
 
-// src/server/realtime.ts
-function bindRealtimeServer2(contract, handle, options = {}) {
-  const outbound = (target) => createValidatedRealtimeSocket({
-    target,
-    inbound: {},
-    outbound: contract.serverToClient,
-    inboundDirection: "server-inbound",
-    outboundDirection: "server-outbound",
-    onRejected: options.onRejected,
-    logger: options.logger
-  });
-  const broadcast = outbound(handle.io);
-  return {
-    onConnection: (handler) => {
-      const listener = (raw) => {
-        const events = createValidatedRealtimeSocket({
-          target: raw,
-          inbound: contract.clientToServer,
-          outbound: contract.serverToClient,
-          inboundDirection: "server-inbound",
-          outboundDirection: "server-outbound",
-          onRejected: options.onRejected,
-          logger: options.logger
-        });
-        const failed = (error) => {
-          try {
-            raw.disconnect(true);
-          } catch {}
-          if (options.logger)
-            options.logger.error("Realtime connection handler failed", { error });
-          else
-            console.error("[stitchkit] realtime connection handler failed", error);
-        };
-        try {
-          Promise.resolve(handler({ raw, events, to: (room) => outbound(raw.to(room)) })).catch(failed);
-        } catch (error) {
-          failed(error);
-        }
-      };
-      handle.io.on("connection", listener);
-      return () => {
-        handle.io.off("connection", listener);
-      };
-    },
-    emit: broadcast.emit,
-    to: (room) => outbound(handle.io.to(room))
-  };
-}
-
 // src/server/websocket.ts
 function webSocketLane2(lane) {
   const { match, handlers } = lane;
@@ -3499,4 +3449,4 @@ function createUnixClientTransport2(config) {
   };
 }
 
-export { contextContributionDelta, prepareContextContribution, mergeContextContribution, parseMultipart2, DEFAULT_STREAM_HEARTBEAT_MS2, streamingRoute2, ndjsonRoute2, sseRoute2, createHandler2, createScopedImplementRegistry2, implementRegistry2, createImplementRegistry2, bindProcessSignals2, bindRealtimeServer2, webSocketLane2, composeWebSocketHandlers2, createSocketIOServer2, socketIoLane2, UnixClientTransportError2, createUnixClientTransport2 };
+export { contextContributionDelta, prepareContextContribution, mergeContextContribution, parseMultipart2, DEFAULT_STREAM_HEARTBEAT_MS2, streamingRoute2, ndjsonRoute2, sseRoute2, createHandler2, createScopedImplementRegistry2, implementRegistry2, createImplementRegistry2, bindProcessSignals2, webSocketLane2, composeWebSocketHandlers2, createSocketIOServer2, socketIoLane2, UnixClientTransportError2, createUnixClientTransport2 };

package/dist/{index-hby4qhax.js → index-yex7eg1v.js}

@@ -1,12 +1,6 @@
-// src/internal/random-hex.ts
-function randomHex(bytes) {
-  const arr = new Uint8Array(bytes);
-  crypto.getRandomValues(arr);
-  let hex = "";
-  for (const byte of arr)
-    hex += byte.toString(16).padStart(2, "0");
-  return hex;
-}
+import {
+  randomHex
+} from "./index-c9d05kvt.js";
 
 // src/observability/trace.ts
 var TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(.*)$/i;
@@ -80,4 +74,4 @@ function resolvePropagationContext2(metadata, fallback) {
   };
 }
 
-export { randomHex, createTraceContext2, parseTraceparent2, formatTraceparent2, resolveTraceContext2, childSpan2, resolvePropagationContext2 };
+export { createTraceContext2, parseTraceparent2, formatTraceparent2, resolveTraceContext2, childSpan2, resolvePropagationContext2 };

package/dist/{index-1h6gtdrj.js → index-ygkka6zn.js}

@@ -1,7 +1,7 @@
 import {
   createTraceContext2,
   formatTraceparent2
-} from "./index-hby4qhax.js";
+} from "./index-yex7eg1v.js";
 import {
   isRecord,
   transportResult

package/dist/index-ze1eph1k.js

@@ -0,0 +1,20 @@
+// src/tools/lifecycle.ts
+function composeToolLifecycle2(...hooks) {
+  return {
+    beforeHandle: async (ctx, endpoint) => {
+      for (const hook of hooks)
+        await hook?.beforeHandle?.(ctx, endpoint);
+    },
+    afterHandle: async (ctx, result, endpoint) => {
+      let current = result;
+      for (const hook of hooks) {
+        const transformed = await hook?.afterHandle?.(ctx, current, endpoint);
+        if (transformed !== undefined)
+          current = transformed;
+      }
+      return current;
+    }
+  };
+}
+
+export { composeToolLifecycle2 };

package/dist/tools/schema/flatten-join.d.ts

@@ -6,5 +6,5 @@ export interface VariantProperty {
 }
 /** The string members of a `const`/`enum`, or `null` when any member is not one. */
 export declare function stringValues(schema: ToolPresentationSchema): string[] | null;
-export declare function mergePropertySchemas(properties: VariantProperty[]): ToolPresentationSchema;
+export declare function mergePropertySchemas(properties: VariantProperty[], discriminator: string): ToolPresentationSchema;
 //# sourceMappingURL=flatten-join.d.ts.map

package/dist/tools/schema/flatten-join.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten-join.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/flatten-join.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAsED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,EAAE,GAAG,IAAI,CAK5E;AAuID,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,sBAAsB,CA4B1F"}
+{"version":3,"file":"flatten-join.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/flatten-join.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAsED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,EAAE,GAAG,IAAI,CAK5E;AAsKD,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,eAAe,EAAE,EAC7B,aAAa,EAAE,MAAM,GACpB,sBAAsB,CAiCxB"}

package/dist/tools/schema/flatten.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/flatten.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAsJ7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAG5F;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAG3F"}
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../../src/tools/schema/flatten.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA4J7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAG5F;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAG3F"}

package/llms/agent-runtime-browser.txt

@@ -7,6 +7,7 @@ Contains: API reference: `stitchkit/agent-runtime/browser`  (docs/api/reference.
 
 Also read:
 - see `llms/agent-runtime.txt` for the Agent application runtime guide
+- see `llms/agent-runtime-harness.txt` for the Agent composition guide
 
 ==============================================================================
 # API reference: `stitchkit/agent-runtime/browser`  (docs/api/reference.md)
@@ -31,3 +32,28 @@ Use this entrypoint from client components and shared DTO packages. The full
 `stitchkit/agent-runtime` entrypoint remains server-only.
 
 ---
+
+### 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.

package/llms/agent-runtime-harness-tools.txt

@@ -0,0 +1,25 @@
+# stitchkit/agent-runtime/harness-tools — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/agent-runtime/harness-tools`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+- see `llms/agent-runtime-harness.txt` for the Agent composition guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/harness-tools`  (docs/api/reference.md)
+==============================================================================
+
+## `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/agent-runtime-harness.txt

@@ -3,11 +3,150 @@
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: API reference: `stitchkit/agent-runtime/harness`  (docs/api/reference.md)
+Contains: Guide: Agent composition  (docs/guide/agent-composition.md) · API reference: `stitchkit/agent-runtime/harness`  (docs/api/reference.md)
 
 Also read:
 - see `llms/agent-runtime.txt` for the Agent application runtime guide
 
+==============================================================================
+# 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.
+
 ==============================================================================
 # API reference: `stitchkit/agent-runtime/harness`  (docs/api/reference.md)
 ==============================================================================

package/llms/agent-runtime-react.txt

@@ -0,0 +1,21 @@
+# stitchkit/agent-runtime/react — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/agent-runtime/react`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+- see `llms/agent-runtime-harness.txt` for the Agent composition guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/react`  (docs/api/reference.md)
+==============================================================================
+
+## `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.

package/llms/agent-runtime-realtime.txt

@@ -0,0 +1,30 @@
+# stitchkit/agent-runtime/realtime — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/agent-runtime/realtime`  (docs/api/reference.md)
+
+Also read:
+- see `llms/agent-runtime.txt` for the Agent application runtime guide
+- see `llms/agent-runtime-harness.txt` for the Agent composition guide
+
+==============================================================================
+# API reference: `stitchkit/agent-runtime/realtime`  (docs/api/reference.md)
+==============================================================================
+
+## `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.

package/llms/agent-runtime-testing.txt

@@ -7,6 +7,7 @@ Contains: API reference: `stitchkit/agent-runtime/testing`  (docs/api/reference.
 
 Also read:
 - see `llms/agent-runtime.txt` for the Agent application runtime guide
+- see `llms/agent-runtime-harness.txt` for the Agent composition guide
 
 ==============================================================================
 # API reference: `stitchkit/agent-runtime/testing`  (docs/api/reference.md)
@@ -28,3 +29,8 @@ Credential-free provider and concurrency fixtures for Bun and Node tests.
 | `runAgentStoreConformance` | function | reusable black-box duplicate/coalescing/stale/recovery contract for durable agent-store adapters |
 | `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.

package/llms/stitchkit.txt

@@ -90,7 +90,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 |
@@ -200,6 +203,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) |

package/llms/tools.3.txt

@@ -280,7 +280,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 |

package/llms/tools.txt

@@ -714,7 +714,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