stitchkit 0.102.0 → 0.103.1

package/dist/index-z94wht4y.js

@@ -0,0 +1,156 @@
+import {
+  isRecord
+} from "./index-9jfdm5tg.js";
+
+// src/application/diagnostic-journal-frame.ts
+import { z } from "zod";
+var DiagnosticJournalFrameSchema2 = z.object({
+  schemaVersion: z.literal(1),
+  epoch: z.uuid(),
+  sequence: z.number().int().positive(),
+  event: z.json()
+}).strict().readonly();
+
+// src/application/diagnostic-journal-read-contract.ts
+import { z as z2 } from "zod";
+var ByteCountSchema = z2.number().int().nonnegative();
+var LocationSchema = z2.object({
+  file: z2.string(),
+  offset: ByteCountSchema,
+  line: z2.number().int().positive()
+});
+var DiagnosticJournalAnomalySchema2 = LocationSchema.extend({
+  reason: z2.enum([
+    "nul-byte",
+    "unterminated-line",
+    "invalid-utf8",
+    "invalid-json",
+    "invalid-frame",
+    "invalid-event",
+    "oversized-line"
+  ]),
+  position: z2.enum(["tail", "interior"]),
+  terminated: z2.boolean(),
+  skippedBytes: ByteCountSchema
+}).strict().readonly();
+function createDiagnosticJournalReadResultSchema2(eventSchema) {
+  return z2.discriminatedUnion("type", [
+    LocationSchema.extend({
+      type: z2.literal("frame"),
+      bytes: ByteCountSchema,
+      frame: DiagnosticJournalFrameSchema2.unwrap().extend({ event: eventSchema }).readonly()
+    }).strict().readonly(),
+    z2.object({ type: z2.literal("anomaly"), anomaly: DiagnosticJournalAnomalySchema2 }).strict().readonly()
+  ]);
+}
+var DiagnosticJournalRecoveryStatusSchema2 = z2.object({
+  filesChecked: ByteCountSchema,
+  anomalies: ByteCountSchema,
+  skippedBytes: ByteCountSchema,
+  firstAnomaly: DiagnosticJournalAnomalySchema2.optional(),
+  lastAnomaly: DiagnosticJournalAnomalySchema2.optional()
+}).strict().readonly();
+
+class DiagnosticJournalRecoveryError2 extends Error {
+  recovery;
+  constructor(recovery) {
+    super("Diagnostic journal tail recovery requires maxFiles >= 2; no data was removed");
+    this.recovery = recovery;
+    this.name = "DiagnosticJournalRecoveryError";
+  }
+}
+
+// src/application/diagnostic-journal-contract.ts
+import { z as z3 } from "zod";
+var PositiveSafeIntegerSchema = z3.number().int().positive();
+var FileModeSchema = z3.number().int().min(0).max(511);
+var DiagnosticJournalLimitsSchema2 = z3.object({
+  maxEventBytes: PositiveSafeIntegerSchema,
+  maxPendingItems: PositiveSafeIntegerSchema,
+  maxPendingBytes: PositiveSafeIntegerSchema,
+  maxFileBytes: PositiveSafeIntegerSchema,
+  maxFiles: PositiveSafeIntegerSchema
+}).strict().readonly();
+var DiagnosticJournalLockPolicySchema2 = z3.enum(["refuse", "reclaim-stale"]);
+var DiagnosticJournalStateSchema2 = z3.enum(["open", "draining", "closed", "failed"]);
+var DiagnosticJournalRefusalReasonSchema2 = z3.enum([
+  "closed",
+  "failed",
+  "invalid",
+  "oversized",
+  "item-capacity",
+  "byte-capacity"
+]);
+var DiagnosticJournalRefusalCountersSchema = z3.object({
+  closed: z3.number().int().nonnegative(),
+  failed: z3.number().int().nonnegative(),
+  invalid: z3.number().int().nonnegative(),
+  oversized: z3.number().int().nonnegative(),
+  "item-capacity": z3.number().int().nonnegative(),
+  "byte-capacity": z3.number().int().nonnegative()
+}).strict().readonly();
+var DiagnosticJournalFailurePhaseSchema2 = z3.enum(["write", "rotation", "close"]);
+var DiagnosticJournalStatusSchema2 = z3.object({
+  state: DiagnosticJournalStateSchema2,
+  epoch: z3.uuid(),
+  limits: DiagnosticJournalLimitsSchema2,
+  lock: z3.object({
+    policy: DiagnosticJournalLockPolicySchema2,
+    reclaimedStale: z3.boolean()
+  }).strict().readonly(),
+  received: z3.number().int().nonnegative(),
+  accepted: z3.number().int().nonnegative(),
+  refused: z3.number().int().nonnegative(),
+  refusals: DiagnosticJournalRefusalCountersSchema,
+  written: z3.number().int().nonnegative(),
+  failedRecords: z3.number().int().nonnegative(),
+  pendingItems: z3.number().int().nonnegative(),
+  pendingBytes: z3.number().int().nonnegative(),
+  inFlight: z3.boolean(),
+  rotations: z3.number().int().nonnegative(),
+  rotationFailures: z3.number().int().nonnegative(),
+  partialTails: z3.number().int().nonnegative(),
+  currentFileBytes: z3.number().int().nonnegative(),
+  retainedFiles: z3.number().int().nonnegative(),
+  recovery: DiagnosticJournalRecoveryStatusSchema2.optional(),
+  lastAcceptedSequence: z3.number().int().positive().optional(),
+  lastWrittenSequence: z3.number().int().positive().optional(),
+  lastSettledSequence: z3.number().int().positive().optional(),
+  lastFailure: z3.object({
+    phase: DiagnosticJournalFailurePhaseSchema2,
+    sequence: z3.number().int().positive().optional()
+  }).strict().readonly().optional()
+}).strict().readonly();
+var DiagnosticJournalSubmitResultSchema2 = z3.discriminatedUnion("outcome", [
+  z3.object({
+    outcome: z3.literal("accepted"),
+    epoch: z3.uuid(),
+    sequence: z3.number().int().positive()
+  }).strict().readonly(),
+  z3.object({
+    outcome: z3.literal("refused"),
+    reason: DiagnosticJournalRefusalReasonSchema2
+  }).strict().readonly()
+]);
+var DiagnosticJournalWaitResultSchema2 = z3.object({
+  outcome: z3.enum(["settled", "timed-out", "cancelled"]),
+  state: DiagnosticJournalStateSchema2,
+  throughSequence: z3.number().int().nonnegative(),
+  settledSequence: z3.number().int().nonnegative()
+}).strict().readonly();
+var DiagnosticJournalCloseResultSchema2 = z3.object({
+  outcome: z3.enum(["closed", "timed-out", "cancelled"]),
+  state: DiagnosticJournalStateSchema2,
+  pendingItems: z3.number().int().nonnegative()
+}).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 { DiagnosticJournalFrameSchema2, DiagnosticJournalAnomalySchema2, createDiagnosticJournalReadResultSchema2, DiagnosticJournalRecoveryStatusSchema2, DiagnosticJournalRecoveryError2, DiagnosticJournalLimitsSchema2, DiagnosticJournalLockPolicySchema2, DiagnosticJournalStateSchema2, DiagnosticJournalRefusalReasonSchema2, DiagnosticJournalFailurePhaseSchema2, DiagnosticJournalStatusSchema2, DiagnosticJournalSubmitResultSchema2, DiagnosticJournalWaitResultSchema2, DiagnosticJournalCloseResultSchema2, parseDiagnosticJournalMode, readDiagnosticJournalLockDiagnosis2 };

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/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/application-diagnostic-journal.txt

@@ -17,6 +17,8 @@ Also read:
 | 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