@ai-sdk/harness 0.0.0 → 1.0.0-canary.3

package/dist/observability/index.d.ts

@@ -0,0 +1,97 @@
+import { Telemetry } from 'ai';
+
+/** Severity of a diagnostic. */
+type HarnessDebugLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/**
+ * A forwarded bridge diagnostic, normalized for host consumers.
+ *
+ * The bridge emits two raw frame kinds — captured console lines (`sandbox-log`)
+ * and structured events (`debug-event`). The framework normalizes both into
+ * this single shape before handing them to a consumer's `onLog` callback, the
+ * `HARNESS_DEBUG` stderr default, and observability reporters. Diagnostics are
+ * kept first-class and per-line — they are never folded into telemetry spans.
+ */
+type HarnessDiagnostic = {
+    /**
+     * Severity. Structured events carry their own level; captured console lines
+     * map `stderr` → `'warn'` and `stdout` → `'info'`.
+     */
+    readonly level: HarnessDebugLevel;
+    /** Human-readable line (console capture) or message (structured event). */
+    readonly message: string;
+    /**
+     * Dotted subsystem. For captured console output this is
+     * `sandbox.log.<source>`; for structured events it is the adapter-supplied
+     * subsystem (e.g. `bridge.turn`).
+     */
+    readonly subsystem: string;
+    /** `'log'` = captured console line; `'event'` = structured `bridgeLog`. */
+    readonly kind: 'log' | 'event';
+    /** Originating sandbox source label (console capture). */
+    readonly source?: string;
+    /** Which standard stream the line came from (console capture). */
+    readonly stream?: 'stdout' | 'stderr';
+    /** Structured attributes (structured events only). */
+    readonly attrs?: Record<string, unknown>;
+    /** Error payload (structured events only). */
+    readonly error?: {
+        name?: string;
+        message: string;
+        stack?: string;
+    };
+    /** The harness session this diagnostic originated from. */
+    readonly sessionId?: string;
+    /** Host receipt time (epoch ms). */
+    readonly timestamp: number;
+};
+/**
+ * A telemetry integration that also wants the per-line diagnostics stream. The
+ * framework calls `ingestDiagnostic` for every forwarded bridge diagnostic in
+ * addition to driving the standard `Telemetry` span lifecycle, so a single
+ * reporter object (e.g. `createFileReporter`) registered in
+ * `telemetry.integrations` receives both spans and logs.
+ */
+interface HarnessDiagnosticConsumer {
+    ingestDiagnostic?(diagnostic: HarnessDiagnostic): void;
+}
+
+/**
+ * A harness observability reporter that writes a unified, non-lossy
+ * `events.jsonl` containing **both** the telemetry span lifecycle (turn / step
+ * / tool) **and** the forwarded bridge diagnostics (console lines + structured
+ * events). It is a single object registered in `telemetry.integrations`: the
+ * framework drives its `Telemetry` methods for spans and calls
+ * `ingestDiagnostic` for diagnostics.
+ *
+ * No external collector or OTel setup required — this is the AI-SDK-idiomatic
+ * replacement for the original SDK's host-side artifact files.
+ */
+interface FileReporterOptions {
+    /** Directory for `events.jsonl` (created if absent). */
+    dir: string;
+    /**
+     * Buffer a turn's records in memory and write them only if the turn produced
+     * an error (an `error`-level diagnostic, a failed tool, or an error finish).
+     * Default false (write everything).
+     */
+    failOnly?: boolean;
+    /** File name within `dir`. Default `events.jsonl`. */
+    fileName?: string;
+}
+type FileReporter = Telemetry & HarnessDiagnosticConsumer;
+declare function createFileReporter(options: FileReporterOptions): FileReporter;
+
+/**
+ * A harness observability reporter that renders an ASCII trace tree of a
+ * turn's span lifecycle (turn → steps → tools) to a stream at turn end. It is a
+ * `Telemetry` integration — register it in `telemetry.integrations`. Useful for
+ * zero-setup local debugging when no OTel collector is wired up; a real OTel
+ * backend (via `@ai-sdk/otel`) is a strict superset.
+ */
+interface TraceTreeReporterOptions {
+    /** Where to write the rendered tree. Default `process.stderr.write`. */
+    write?: (chunk: string) => void;
+}
+declare function createTraceTreeReporter(options?: TraceTreeReporterOptions): Telemetry;
+
+export { type FileReporter, type FileReporterOptions, type HarnessDiagnostic, type HarnessDiagnosticConsumer, type TraceTreeReporterOptions, createFileReporter, createTraceTreeReporter };

package/dist/observability/index.js

@@ -0,0 +1,225 @@
+// src/observability/file-reporter.ts
+import { appendFileSync, mkdirSync } from "fs";
+function createFileReporter(options) {
+  var _a, _b;
+  const fileName = (_a = options.fileName) != null ? _a : "events.jsonl";
+  const path = `${options.dir}/${fileName}`;
+  const failOnly = (_b = options.failOnly) != null ? _b : false;
+  const turns = /* @__PURE__ */ new Map();
+  let lastOpenCallId;
+  let dirReady = false;
+  const bucketFor = (callId) => {
+    let bucket = turns.get(callId);
+    if (!bucket) {
+      bucket = { lines: [], errored: false };
+      turns.set(callId, bucket);
+    }
+    return bucket;
+  };
+  const record = (callId, rec) => {
+    const id = callId != null ? callId : lastOpenCallId;
+    if (id == null) {
+      flushLines([rec]);
+      return;
+    }
+    bucketFor(id).lines.push(rec);
+  };
+  const flushLines = (lines) => {
+    if (lines.length === 0) return;
+    try {
+      if (!dirReady) {
+        mkdirSync(options.dir, { recursive: true });
+        dirReady = true;
+      }
+      appendFileSync(path, lines.map((l) => JSON.stringify(l)).join("\n") + "\n");
+    } catch (e) {
+    }
+  };
+  const finishTurn = (callId) => {
+    const bucket = turns.get(callId);
+    if (!bucket) return;
+    turns.delete(callId);
+    if (lastOpenCallId === callId) lastOpenCallId = void 0;
+    if (failOnly && !bucket.errored) return;
+    flushLines(bucket.lines);
+  };
+  return {
+    onStart(event) {
+      const e = event;
+      lastOpenCallId = e.callId;
+      record(e.callId, {
+        ts: Date.now(),
+        kind: "turn-start",
+        callId: e.callId,
+        operationId: e.operationId,
+        provider: e.provider,
+        modelId: e.modelId,
+        // Input prompt, unless the consumer opted out via `recordInputs: false`.
+        ...e.recordInputs === false ? {} : { input: { messages: e.messages, instructions: e.instructions } }
+      });
+    },
+    onStepStart(event) {
+      const e = event;
+      record(e.callId, {
+        ts: Date.now(),
+        kind: "step-start",
+        callId: e.callId,
+        step: e.stepNumber
+      });
+    },
+    onToolExecutionStart(event) {
+      const e = event;
+      record(e.callId, {
+        ts: Date.now(),
+        kind: "tool-start",
+        callId: e.callId,
+        toolName: e.toolCall.toolName,
+        toolCallId: e.toolCall.toolCallId,
+        input: e.toolCall.input
+      });
+    },
+    onToolExecutionEnd(event) {
+      const e = event;
+      const isError = e.toolOutput.type === "error";
+      if (isError) bucketFor(e.callId).errored = true;
+      record(e.callId, {
+        ts: Date.now(),
+        kind: "tool-end",
+        callId: e.callId,
+        toolCallId: e.toolCall.toolCallId,
+        isError,
+        output: isError ? e.toolOutput.error : e.toolOutput.output
+      });
+    },
+    onStepFinish(event) {
+      const e = event;
+      record(e.callId, {
+        ts: Date.now(),
+        kind: "step-finish",
+        callId: e.callId,
+        usage: e.usage,
+        // The model's output content, unless `recordOutputs: false`.
+        ...e.recordOutputs === false || e.content == null ? {} : { output: e.content }
+      });
+    },
+    onEnd(event) {
+      var _a2;
+      const e = event;
+      record(e.callId, {
+        ts: Date.now(),
+        kind: "turn-finish",
+        callId: e.callId,
+        finishReason: e.finishReason,
+        usage: (_a2 = e.totalUsage) != null ? _a2 : e.usage
+      });
+      finishTurn(e.callId);
+    },
+    onError(error) {
+      if (lastOpenCallId != null) bucketFor(lastOpenCallId).errored = true;
+      record(lastOpenCallId, {
+        ts: Date.now(),
+        kind: "error",
+        error: error instanceof Error ? { name: error.name, message: error.message } : error
+      });
+    },
+    ingestDiagnostic(diagnostic) {
+      if (diagnostic.level === "error" && lastOpenCallId != null) {
+        bucketFor(lastOpenCallId).errored = true;
+      }
+      record(lastOpenCallId, {
+        ts: diagnostic.timestamp,
+        kind: "diagnostic",
+        diagnostic
+      });
+    }
+  };
+}
+
+// src/observability/trace-tree-reporter.ts
+function createTraceTreeReporter(options = {}) {
+  var _a;
+  const write = (_a = options.write) != null ? _a : ((chunk) => void process.stderr.write(chunk));
+  const turns = /* @__PURE__ */ new Map();
+  const render = (node, depth) => {
+    const indent = "  ".repeat(depth);
+    const dur = node.endMs != null ? `${Math.max(0, Math.round(node.endMs - node.startMs))}ms` : "(open)";
+    let out = `${indent}- ${node.label} ${dur}
+`;
+    for (const child of node.children) out += render(child, depth + 1);
+    return out;
+  };
+  return {
+    onStart(event) {
+      var _a2;
+      const e = event;
+      turns.set(e.callId, {
+        root: {
+          label: `${(_a2 = e.operationId) != null ? _a2 : "turn"}${e.modelId ? ` ${e.modelId}` : ""}`,
+          startMs: Date.now(),
+          children: []
+        },
+        tools: /* @__PURE__ */ new Map()
+      });
+    },
+    onStepStart(event) {
+      var _a2;
+      const e = event;
+      const turn = turns.get(e.callId);
+      if (!turn) return;
+      const step = {
+        label: `step ${((_a2 = e.stepNumber) != null ? _a2 : turn.root.children.length) + 1}`,
+        startMs: Date.now(),
+        children: []
+      };
+      turn.step = step;
+      turn.root.children.push(step);
+    },
+    onToolExecutionStart(event) {
+      var _a2;
+      const e = event;
+      const turn = turns.get(e.callId);
+      const parent = (_a2 = turn == null ? void 0 : turn.step) != null ? _a2 : turn == null ? void 0 : turn.root;
+      if (!turn || !parent) return;
+      const node = {
+        label: `tool ${e.toolCall.toolName}`,
+        startMs: Date.now(),
+        children: []
+      };
+      turn.tools.set(e.toolCall.toolCallId, node);
+      parent.children.push(node);
+    },
+    onToolExecutionEnd(event) {
+      var _a2;
+      const e = event;
+      const node = (_a2 = turns.get(e.callId)) == null ? void 0 : _a2.tools.get(e.toolCall.toolCallId);
+      if (!node) return;
+      node.endMs = Date.now();
+      if (e.toolOutput.type === "error") node.label += " [error]";
+    },
+    onStepFinish(event) {
+      const e = event;
+      const turn = turns.get(e.callId);
+      if (turn == null ? void 0 : turn.step) {
+        turn.step.endMs = Date.now();
+        turn.step = void 0;
+      }
+    },
+    onEnd(event) {
+      const e = event;
+      const turn = turns.get(e.callId);
+      if (!turn) return;
+      turn.root.endMs = Date.now();
+      turns.delete(e.callId);
+      try {
+        write(`
+${render(turn.root, 0)}`);
+      } catch (e2) {
+      }
+    }
+  };
+}
+export {
+  createFileReporter,
+  createTraceTreeReporter
+};
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/observability/file-reporter.ts","../../src/observability/trace-tree-reporter.ts"],"sourcesContent":["import { appendFileSync, mkdirSync } from 'node:fs';\nimport type { Telemetry } from 'ai';\nimport type {\n  HarnessDiagnostic,\n  HarnessDiagnosticConsumer,\n} from '../agent/harness-diagnostics';\n\n/**\n * A harness observability reporter that writes a unified, non-lossy\n * `events.jsonl` containing **both** the telemetry span lifecycle (turn / step\n * / tool) **and** the forwarded bridge diagnostics (console lines + structured\n * events). It is a single object registered in `telemetry.integrations`: the\n * framework drives its `Telemetry` methods for spans and calls\n * `ingestDiagnostic` for diagnostics.\n *\n * No external collector or OTel setup required — this is the AI-SDK-idiomatic\n * replacement for the original SDK's host-side artifact files.\n */\nexport interface FileReporterOptions {\n  /** Directory for `events.jsonl` (created if absent). */\n  dir: string;\n  /**\n   * Buffer a turn's records in memory and write them only if the turn produced\n   * an error (an `error`-level diagnostic, a failed tool, or an error finish).\n   * Default false (write everything).\n   */\n  failOnly?: boolean;\n  /** File name within `dir`. Default `events.jsonl`. */\n  fileName?: string;\n}\n\ntype Record_ = { ts: number } & Record<string, unknown>;\n\nexport type FileReporter = Telemetry & HarnessDiagnosticConsumer;\n\nexport function createFileReporter(options: FileReporterOptions): FileReporter {\n  const fileName = options.fileName ?? 'events.jsonl';\n  const path = `${options.dir}/${fileName}`;\n  const failOnly = options.failOnly ?? false;\n\n  // Per-turn buffers, keyed by the telemetry callId. Diagnostics (which carry a\n  // sessionId, not a callId) attach to the most recently started, open turn.\n  const turns = new Map<string, { lines: Record_[]; errored: boolean }>();\n  let lastOpenCallId: string | undefined;\n  let dirReady = false;\n\n  const bucketFor = (callId: string) => {\n    let bucket = turns.get(callId);\n    if (!bucket) {\n      bucket = { lines: [], errored: false };\n      turns.set(callId, bucket);\n    }\n    return bucket;\n  };\n\n  const record = (callId: string | undefined, rec: Record_): void => {\n    const id = callId ?? lastOpenCallId;\n    if (id == null) {\n      // No active turn — write standalone (best-effort).\n      flushLines([rec]);\n      return;\n    }\n    bucketFor(id).lines.push(rec);\n  };\n\n  const flushLines = (lines: Record_[]): void => {\n    if (lines.length === 0) return;\n    try {\n      if (!dirReady) {\n        mkdirSync(options.dir, { recursive: true });\n        dirReady = true;\n      }\n      appendFileSync(path, lines.map(l => JSON.stringify(l)).join('\\n') + '\\n');\n    } catch {\n      // Best-effort: never let observability break a turn.\n    }\n  };\n\n  const finishTurn = (callId: string): void => {\n    const bucket = turns.get(callId);\n    if (!bucket) return;\n    turns.delete(callId);\n    if (lastOpenCallId === callId) lastOpenCallId = undefined;\n    if (failOnly && !bucket.errored) return;\n    flushLines(bucket.lines);\n  };\n\n  return {\n    onStart(event) {\n      const e = event as {\n        callId: string;\n        operationId?: string;\n        modelId?: string;\n        provider?: string;\n        messages?: unknown;\n        instructions?: unknown;\n        recordInputs?: boolean;\n      };\n      lastOpenCallId = e.callId;\n      record(e.callId, {\n        ts: Date.now(),\n        kind: 'turn-start',\n        callId: e.callId,\n        operationId: e.operationId,\n        provider: e.provider,\n        modelId: e.modelId,\n        // Input prompt, unless the consumer opted out via `recordInputs: false`.\n        ...(e.recordInputs === false\n          ? {}\n          : { input: { messages: e.messages, instructions: e.instructions } }),\n      });\n    },\n    onStepStart(event) {\n      const e = event as { callId: string; stepNumber?: number };\n      record(e.callId, {\n        ts: Date.now(),\n        kind: 'step-start',\n        callId: e.callId,\n        step: e.stepNumber,\n      });\n    },\n    onToolExecutionStart(event) {\n      const e = event as {\n        callId: string;\n        toolCall: { toolName: string; toolCallId: string; input: unknown };\n      };\n      record(e.callId, {\n        ts: Date.now(),\n        kind: 'tool-start',\n        callId: e.callId,\n        toolName: e.toolCall.toolName,\n        toolCallId: e.toolCall.toolCallId,\n        input: e.toolCall.input,\n      });\n    },\n    onToolExecutionEnd(event) {\n      const e = event as {\n        callId: string;\n        toolCall: { toolCallId: string };\n        toolOutput: { type: string; output?: unknown; error?: unknown };\n      };\n      const isError = e.toolOutput.type === 'error';\n      if (isError) bucketFor(e.callId).errored = true;\n      record(e.callId, {\n        ts: Date.now(),\n        kind: 'tool-end',\n        callId: e.callId,\n        toolCallId: e.toolCall.toolCallId,\n        isError,\n        output: isError ? e.toolOutput.error : e.toolOutput.output,\n      });\n    },\n    onStepFinish(event) {\n      const e = event as {\n        callId: string;\n        usage?: unknown;\n        content?: unknown[];\n        recordOutputs?: boolean;\n      };\n      record(e.callId, {\n        ts: Date.now(),\n        kind: 'step-finish',\n        callId: e.callId,\n        usage: e.usage,\n        // The model's output content, unless `recordOutputs: false`.\n        ...(e.recordOutputs === false || e.content == null\n          ? {}\n          : { output: e.content }),\n      });\n    },\n    onEnd(event) {\n      const e = event as {\n        callId: string;\n        finishReason?: unknown;\n        usage?: unknown;\n        totalUsage?: unknown;\n      };\n      record(e.callId, {\n        ts: Date.now(),\n        kind: 'turn-finish',\n        callId: e.callId,\n        finishReason: e.finishReason,\n        usage: e.totalUsage ?? e.usage,\n      });\n      finishTurn(e.callId);\n    },\n    onError(error) {\n      if (lastOpenCallId != null) bucketFor(lastOpenCallId).errored = true;\n      record(lastOpenCallId, {\n        ts: Date.now(),\n        kind: 'error',\n        error:\n          error instanceof Error\n            ? { name: error.name, message: error.message }\n            : error,\n      });\n    },\n    ingestDiagnostic(diagnostic: HarnessDiagnostic) {\n      if (diagnostic.level === 'error' && lastOpenCallId != null) {\n        bucketFor(lastOpenCallId).errored = true;\n      }\n      record(lastOpenCallId, {\n        ts: diagnostic.timestamp,\n        kind: 'diagnostic',\n        diagnostic,\n      });\n    },\n  };\n}\n","import type { Telemetry } from 'ai';\n\n/**\n * A harness observability reporter that renders an ASCII trace tree of a\n * turn's span lifecycle (turn → steps → tools) to a stream at turn end. It is a\n * `Telemetry` integration — register it in `telemetry.integrations`. Useful for\n * zero-setup local debugging when no OTel collector is wired up; a real OTel\n * backend (via `@ai-sdk/otel`) is a strict superset.\n */\nexport interface TraceTreeReporterOptions {\n  /** Where to write the rendered tree. Default `process.stderr.write`. */\n  write?: (chunk: string) => void;\n}\n\ntype Node = {\n  label: string;\n  startMs: number;\n  endMs?: number;\n  children: Node[];\n};\n\nexport function createTraceTreeReporter(\n  options: TraceTreeReporterOptions = {},\n): Telemetry {\n  const write =\n    options.write ?? ((chunk: string) => void process.stderr.write(chunk));\n\n  type TurnState = {\n    root: Node;\n    step?: Node;\n    tools: Map<string, Node>;\n  };\n  const turns = new Map<string, TurnState>();\n\n  const render = (node: Node, depth: number): string => {\n    const indent = '  '.repeat(depth);\n    const dur =\n      node.endMs != null\n        ? `${Math.max(0, Math.round(node.endMs - node.startMs))}ms`\n        : '(open)';\n    let out = `${indent}- ${node.label} ${dur}\\n`;\n    for (const child of node.children) out += render(child, depth + 1);\n    return out;\n  };\n\n  return {\n    onStart(event) {\n      const e = event as {\n        callId: string;\n        operationId?: string;\n        modelId?: string;\n      };\n      turns.set(e.callId, {\n        root: {\n          label: `${e.operationId ?? 'turn'}${e.modelId ? ` ${e.modelId}` : ''}`,\n          startMs: Date.now(),\n          children: [],\n        },\n        tools: new Map(),\n      });\n    },\n    onStepStart(event) {\n      const e = event as { callId: string; stepNumber?: number };\n      const turn = turns.get(e.callId);\n      if (!turn) return;\n      const step: Node = {\n        label: `step ${(e.stepNumber ?? turn.root.children.length) + 1}`,\n        startMs: Date.now(),\n        children: [],\n      };\n      turn.step = step;\n      turn.root.children.push(step);\n    },\n    onToolExecutionStart(event) {\n      const e = event as {\n        callId: string;\n        toolCall: { toolName: string; toolCallId: string };\n      };\n      const turn = turns.get(e.callId);\n      const parent = turn?.step ?? turn?.root;\n      if (!turn || !parent) return;\n      const node: Node = {\n        label: `tool ${e.toolCall.toolName}`,\n        startMs: Date.now(),\n        children: [],\n      };\n      turn.tools.set(e.toolCall.toolCallId, node);\n      parent.children.push(node);\n    },\n    onToolExecutionEnd(event) {\n      const e = event as {\n        callId: string;\n        toolCall: { toolCallId: string };\n        toolOutput: { type: string };\n      };\n      const node = turns.get(e.callId)?.tools.get(e.toolCall.toolCallId);\n      if (!node) return;\n      node.endMs = Date.now();\n      if (e.toolOutput.type === 'error') node.label += ' [error]';\n    },\n    onStepFinish(event) {\n      const e = event as { callId: string };\n      const turn = turns.get(e.callId);\n      if (turn?.step) {\n        turn.step.endMs = Date.now();\n        turn.step = undefined;\n      }\n    },\n    onEnd(event) {\n      const e = event as { callId: string };\n      const turn = turns.get(e.callId);\n      if (!turn) return;\n      turn.root.endMs = Date.now();\n      turns.delete(e.callId);\n      try {\n        write(`\\n${render(turn.root, 0)}`);\n      } catch {\n        // Never let rendering break the turn.\n      }\n    },\n  };\n}\n"],"mappings":"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","names":["_a","_a","e"]}

package/dist/utils/index.d.ts

@@ -0,0 +1,196 @@
+import { FlexibleSchema } from '@ai-sdk/provider-utils';
+import { WebSocket } from 'ws';
+
+/**
+ * Diagnostic event surfaced by {@link SandboxChannel} during its connection
+ * lifecycle. Silent unless a consumer wires `onDebug`. Reconnects are otherwise
+ * invisible — the channel reconnects transparently and the in-flight turn keeps
+ * streaming.
+ */
+type SandboxChannelDebugEvent = {
+    event: 'reconnect-attempt';
+    attempt: number;
+    lastSeenEventId: number;
+} | {
+    event: 'reconnected';
+    attempt: number;
+    lastSeenEventId: number;
+} | {
+    event: 'reconnect-failed';
+    attempts: number;
+    lastSeenEventId: number;
+    cause: unknown;
+};
+interface SandboxChannelReconnectOptions {
+    /** Give up reconnecting after this many milliseconds. Default 30_000. */
+    readonly maxElapsedMs?: number;
+    /** First backoff delay. Default 50. */
+    readonly initialDelayMs?: number;
+    /** Backoff ceiling. Default 2_000. */
+    readonly maxDelayMs?: number;
+}
+interface SandboxChannelOptions<TOut> {
+    /**
+     * Open a fresh WebSocket to the bridge and resolve once it is ready to carry
+     * frames (i.e. after any adapter-specific handshake such as Claude Code's
+     * `bridge-hello`). Called once by {@link SandboxChannel.open} and again on
+     * every transient reconnect. Must reject if the connection cannot be
+     * established.
+     */
+    connect: () => Promise<WebSocket>;
+    /** Schema validating inbound (bridge → host) frames. */
+    outboundSchema: FlexibleSchema<TOut>;
+    reconnect?: SandboxChannelReconnectOptions;
+    onDebug?: (event: SandboxChannelDebugEvent) => void;
+    /**
+     * Sink for forwarded bridge diagnostics — `sandbox-log` (captured
+     * console lines) and `debug-event` (structured) frames. When set, these
+     * frame types are routed here instead of the per-type listener dispatch, so
+     * they never reach the consumer's stream. Typed to the diagnostic members of
+     * `TOut`, so it is a no-op union for channels whose protocol has none.
+     */
+    onDiagnostic?: (event: Extract<TOut, {
+        type: 'sandbox-log' | 'debug-event';
+    }>) => void;
+    /**
+     * Seed the host-side cursor before the first connect. Pass the
+     * `lastSeenEventId` persisted from a prior process so the bridge replays only
+     * events past it when this channel opens with `{ resume: true }` — the
+     * cross-process attach handshake. Defaults to `0` (fresh session).
+     */
+    initialLastSeenEventId?: number;
+}
+type EventTypeOf<TOut extends {
+    type: string;
+}> = TOut['type'];
+type Listener<TOut extends {
+    type: string;
+}, T extends EventTypeOf<TOut>> = (event: Extract<TOut, {
+    type: T;
+}>) => void;
+/**
+ * Host-side typed wrapper around the bridge WebSocket connection.
+ *
+ * Buffers inbound messages until a listener for their type is registered, so
+ * callers that subscribe asynchronously do not miss early frames. Inbound
+ * dispatch is serialised through a promise chain so a `close` event that
+ * arrives on the same microtask as the final `finish` message does not fire
+ * close handlers until the message has been dispatched.
+ *
+ * Survives transient disconnects. The bridge keeps running and
+ * accumulates events in an in-memory log keyed by a monotonic `seq`; on an
+ * unexpected socket drop this channel re-invokes `connect`, re-wires the new
+ * socket, and asks the bridge to replay everything past `lastSeenEventId`. The
+ * in-flight turn never observes the blip — `onClose` fires only after a
+ * host-initiated close or once the reconnect budget is exhausted.
+ */
+declare class SandboxChannel<TOut extends {
+    type: string;
+}, TIn extends {
+    type: string;
+} = {
+    type: string;
+}> {
+    private readonly listeners;
+    private readonly buffered;
+    private readonly onCloseHandlers;
+    private readonly connectThunk;
+    private readonly outboundSchema;
+    private readonly onDebug;
+    private readonly onDiagnostic;
+    private readonly maxElapsedMs;
+    private readonly initialDelayMs;
+    private readonly maxDelayMs;
+    private ws;
+    private connected;
+    /** Host has begun teardown; suppresses reconnect so a bridge-side close finalises. */
+    private closing;
+    /**
+     * Host has gracefully suspended (slice boundary). Inbound frames are ignored
+     * from this point so the cursor stops advancing exactly at the last delivered
+     * event — the bridge keeps the turn running and the not-yet-delivered tail is
+     * replayed to the next process on `resume`.
+     */
+    private suspended;
+    /** Channel is fully torn down; `send` throws and `onClose` has fired. */
+    private terminal;
+    private _lastSeenEventId;
+    private readonly pendingSends;
+    private dispatchChain;
+    constructor(options: SandboxChannelOptions<TOut>);
+    /**
+     * Highest bridge event `seq` this channel has observed. Persist it (e.g. via
+     * the adapter's resume handle) so a future process can seed
+     * {@link SandboxChannelOptions.initialLastSeenEventId} and attach.
+     */
+    get lastSeenEventId(): number;
+    /**
+     * Establish the initial connection. A single attempt — startup failures
+     * reject so the caller can fail `doStart` cleanly. Reconnect retries apply
+     * only to drops after a successful open.
+     *
+     * Pass `{ resume: true }` to attach to a bridge that is already mid-session:
+     * after the socket opens, the channel sends `{ type: 'resume', lastSeenEventId }`
+     * so the bridge replays everything past the seeded cursor. This is the
+     * cross-process attach handshake — identical to what a transient reconnect
+     * does, but triggered by the initial open from a new process.
+     */
+    open(opts?: {
+        resume?: boolean;
+    }): Promise<void>;
+    on<T extends EventTypeOf<TOut>>(type: T, listener: Listener<TOut, T>): () => void;
+    onClose(handler: (code: number, reason: string) => void): void;
+    send(message: TIn): void;
+    /**
+     * Mark that the host is tearing the session down. The next socket close is
+     * then treated as terminal rather than triggering a reconnect. Call before
+     * sending a `shutdown` / `detach` message whose ack the bridge follows with a
+     * socket close.
+     */
+    beginClose(): void;
+    close(): void;
+    /**
+     * Gracefully suspend at a slice boundary: stop processing inbound frames
+     * (so the cursor freezes at the last delivered event), drain any frames
+     * already queued for dispatch, then close the socket and finalise with the
+     * close reason `'suspended'`. Resolves with the final `lastSeenEventId`.
+     *
+     * The bridge keeps the in-flight turn running (a host socket close never
+     * aborts it) and accumulates events past the cursor for the next process to
+     * `resume`. Unlike {@link close}, the consumer's active turn is wound down
+     * cleanly — adapters distinguish a suspend from an unexpected drop via the
+     * `'suspended'` close reason and resolve `done` successfully.
+     */
+    suspend(): Promise<number>;
+    isClosed(): boolean;
+    private wire;
+    private reconnectLoop;
+    private rawSend;
+    private flushPending;
+    private enqueue;
+    private handleIncoming;
+    private dispatch;
+    private finalizeClose;
+}
+
+/**
+ * Recovery rung selected from an on-disk bridge event log when attach is not
+ * possible (the bridge process is gone): `'replay'` when the log holds a
+ * complete turn the host can resume from its cursor, `'rerun'` otherwise.
+ */
+type DiskLogRecoveryMode = 'replay' | 'rerun';
+/**
+ * Decide whether a respawned bridge can `replay` a turn from its persisted
+ * `event-log.ndjson`, or must `rerun` it from scratch.
+ *
+ * A turn is replayable only when its log ends in a terminal `finish` event —
+ * a log that is missing, empty, or ends mid-turn means the bridge died before
+ * completing the turn, so there is no coherent tail to deliver and the runtime
+ * must re-run it (continuing its own thread from the sandbox snapshot).
+ *
+ * @param eventLog Raw contents of `event-log.ndjson` (newline-delimited JSON),
+ *   or `null`/`undefined`/empty when the file is absent.
+ */
+declare function classifyDiskLog(eventLog: string | null | undefined): Promise<DiskLogRecoveryMode>;
+
+export { type DiskLogRecoveryMode, SandboxChannel, type SandboxChannelDebugEvent, type SandboxChannelOptions, type SandboxChannelReconnectOptions, classifyDiskLog };