@ai-sdk/harness 0.0.0-6b196531-20260710185421

package/dist/bridge/index.d.ts

@@ -0,0 +1,129 @@
+type BridgeState = 'init' | 'waiting' | 'running' | 'draining' | 'done';
+/** Outbound turn event the adapter emits. `seq` is added by the runtime. */
+type BridgeEvent = Record<string, unknown> & {
+    type: string;
+};
+type BridgeDebugLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/**
+ * Per-session diagnostics config. The host resolves it from settings +
+ * env and sends it on `start.debug`; the bridge gates console capture and
+ * structured `debug-event`s on it. When disabled, nothing is captured or
+ * emitted and no `seq` is consumed.
+ */
+interface BridgeDebugConfig {
+    enabled?: boolean;
+    level?: BridgeDebugLevel;
+    subsystems?: string[];
+}
+/**
+ * Per-turn surface handed to {@link RunBridgeOptions.onStart}. The adapter
+ * drives its runtime against these primitives; the runtime owns the transport.
+ */
+interface BridgeTurn {
+    /**
+     * Emit a turn event to the host. Stamps a monotonic `seq`, appends to the
+     * in-memory replay log, and sends to the live socket (best-effort — if the
+     * host is mid-reconnect the event waits in the log and is replayed on
+     * resume).
+     */
+    emit(event: BridgeEvent): void;
+    /**
+     * Register interest in a host-executed tool result and resolve when the
+     * matching `tool-result` arrives. The adapter emits the `tool-call` event
+     * itself (via {@link emit}) using the same `toolCallId`.
+     */
+    requestToolResult(toolCallId: string): Promise<{
+        output: unknown;
+        isError?: boolean;
+    }>;
+    /**
+     * Register interest in a host approval decision and resolve when the matching
+     * `tool-approval-response` arrives. The adapter emits the
+     * `tool-approval-request` event itself using the same `approvalId`.
+     */
+    requestToolApproval(approvalId: string): Promise<{
+        approved: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Live queue of mid-turn user messages. The runtime pushes inbound
+     * `user-message` text here; the adapter drains it as its runtime accepts
+     * interactive input.
+     */
+    readonly pendingUserMessages: string[];
+    /** Aborts when the host sends `abort`. */
+    readonly abortSignal: AbortSignal;
+    /**
+     * Register the runtime-specific interrupt hook for this active turn. The
+     * shared bridge invokes it when the host sends `interrupt`, then acknowledges
+     * only after the hook settles.
+     */
+    onInterrupt(handler: () => void | Promise<void>): void;
+    /** True for the first turn since this bridge process started. */
+    readonly firstTurn: boolean;
+    /**
+     * Emit a structured diagnostic. Gated by the session's debug level +
+     * subsystem filter; a no-op when diagnostics are disabled. Adapters use this
+     * for runtime-level instrumentation; raw `console.*` output is captured and
+     * forwarded automatically.
+     */
+    bridgeLog(input: {
+        level?: BridgeDebugLevel;
+        subsystem: string;
+        message: string;
+        attrs?: Record<string, unknown>;
+        error?: unknown;
+    }): void;
+    /**
+     * Emit a non-fatal bridge warning to stderr using the runtime's harness
+     * prefix. This is diagnostic-only: it does not emit a stream event, does not
+     * consume a `seq`, and does not fail the turn.
+     */
+    emitWarning(input: {
+        message: string;
+    }): void;
+    emitError(input: {
+        error: unknown;
+        message?: string;
+    }): void;
+}
+interface RunBridgeOptions<TStart extends {
+    type: 'start';
+}> {
+    /** Identifier written into `bridge-meta.json` (`'claude-code'` / `'codex'`). */
+    bridgeType: string;
+    /** Directory for `bridge-meta.json` / `start-config.json`. Created if absent. */
+    bridgeStateDir: string;
+    /** Drive one prompt turn. Rejections surface to the host as an `error` event. */
+    onStart(start: TStart, turn: BridgeTurn): Promise<void>;
+    /** Produce the adapter-defined resume payload for a `detach`. Defaults to `{}`. */
+    onDetach?(): unknown | Promise<unknown>;
+    /** WS port. Defaults to `BRIDGE_WS_PORT` env (0 = OS-assigned). */
+    port?: number;
+    /** Auth token. Defaults to `BRIDGE_CHANNEL_TOKEN` env. */
+    token?: string;
+    /** Called with the bound port once the server is listening. */
+    onListening?(port: number): void;
+    /**
+     * Tear the process down after a `shutdown` / `detach`. Defaults to closing
+     * the server and calling `process.exit(0)`. Overridable for tests.
+     */
+    onExit?(): void;
+}
+/**
+ * Boot the bridge: bind the WebSocket server, announce `bridge-ready`, and
+ * service host connections for the lifetime of the process. Resolves once the
+ * server is listening; the process then stays alive on the server until a
+ * `shutdown` / `detach` exits it.
+ */
+interface BridgeHandle {
+    /** The port the WebSocket server bound to. */
+    readonly port: number;
+    /** Close the WebSocket server. Does not call `process.exit`. */
+    close(): Promise<void>;
+}
+declare function runBridge<TStart extends {
+    type: 'start';
+}>(options: RunBridgeOptions<TStart>): Promise<BridgeHandle>;
+
+export { type BridgeDebugConfig, type BridgeDebugLevel, type BridgeEvent, type BridgeHandle, type BridgeState, type BridgeTurn, type RunBridgeOptions, runBridge };

package/dist/bridge/index.js

@@ -0,0 +1,482 @@
+// src/bridge/index.ts
+import { appendFile, mkdir, writeFile } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import { env as procEnv, pid, stdout } from "process";
+import { WebSocketServer } from "ws";
+var DEBUG_LEVEL_WEIGHT = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+  trace: 4
+};
+function subsystemMatches(filters, subsystem) {
+  if (!filters || filters.length === 0) return true;
+  return filters.some(
+    (filter) => subsystem === filter || subsystem.startsWith(`${filter}.`)
+  );
+}
+function formatBridgeError(err) {
+  if (err instanceof Error) {
+    return { name: err.name, message: err.message, stack: err.stack };
+  }
+  if (typeof err === "string") {
+    return { message: err };
+  }
+  if (err !== null && typeof err === "object") {
+    try {
+      return { message: JSON.stringify(err) };
+    } catch {
+    }
+  }
+  return { message: String(err) };
+}
+function parseEnvList(value) {
+  if (!value) return void 0;
+  const items = value.split(",").map((item) => item.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+var ENV_TRUTHY = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+var WS_OPEN = 1;
+async function runBridge(options) {
+  const { bridgeType, bridgeStateDir, onStart, onDetach } = options;
+  const expectedToken = options.token ?? procEnv.BRIDGE_CHANNEL_TOKEN ?? "";
+  const bridgeWsPort = options.port ?? parseInt(procEnv.BRIDGE_WS_PORT ?? "0", 10);
+  const bridgeMetaPath = `${bridgeStateDir}/bridge-meta.json`;
+  const startConfigPath = `${bridgeStateDir}/start-config.json`;
+  const rerunStartConfigPath = `${bridgeStateDir}/rerun-start-config.json`;
+  const eventLogPath = `${bridgeStateDir}/event-log.ndjson`;
+  try {
+    await mkdir(bridgeStateDir, { recursive: true });
+  } catch {
+  }
+  let currentBoundPort = 0;
+  let currentTurnState = "init";
+  let activeSocket;
+  let isFirstTurn = true;
+  let turnAbort;
+  let currentUserMessages;
+  let currentInterruptHandler;
+  let debugConfig;
+  let consoleCaptureInstalled = false;
+  const envDebugEnabled = ENV_TRUTHY.has(
+    (procEnv.HARNESS_DEBUG ?? "").toLowerCase()
+  );
+  let seqCounter = 0;
+  let eventLog = [];
+  let diskBuffer = "";
+  let flushPromise = null;
+  const flushEventsToDisk = async () => {
+    while (diskBuffer.length > 0) {
+      const buf = diskBuffer;
+      diskBuffer = "";
+      await appendFile(eventLogPath, buf).catch(() => {
+      });
+    }
+  };
+  const scheduleEventFlush = () => {
+    if (flushPromise) return;
+    flushPromise = new Promise((resolve) => {
+      setImmediate(() => {
+        void flushEventsToDisk().finally(resolve);
+      });
+    }).finally(() => {
+      flushPromise = null;
+      if (diskBuffer.length > 0) {
+        scheduleEventFlush();
+      }
+    });
+  };
+  const flushPendingEventsToDisk = async () => {
+    if (diskBuffer.length > 0 && !flushPromise) {
+      scheduleEventFlush();
+    }
+    let inFlight = flushPromise;
+    while (inFlight) {
+      await inFlight;
+      inFlight = flushPromise;
+    }
+  };
+  const replayFromDisk = procEnv.BRIDGE_REPLAY_FROM_DISK === "1";
+  if (replayFromDisk && existsSync(eventLogPath)) {
+    try {
+      const lines = readFileSync(eventLogPath, "utf8").split("\n").map((line) => line.trim()).filter(Boolean);
+      eventLog = lines.map((line) => ({
+        seq: JSON.parse(line).seq,
+        line
+      }));
+      seqCounter = eventLog.at(-1)?.seq ?? 0;
+    } catch {
+      eventLog = [];
+      seqCounter = 0;
+    }
+  }
+  const pendingToolResults = /* @__PURE__ */ new Map();
+  const pendingToolApprovals = /* @__PURE__ */ new Map();
+  const writeBridgeMeta = async (state) => {
+    try {
+      await writeFile(
+        bridgeMetaPath,
+        JSON.stringify({
+          type: bridgeType,
+          port: currentBoundPort,
+          state,
+          pid
+        })
+      );
+    } catch {
+    }
+  };
+  const writeStartConfig = async (start) => {
+    try {
+      const serialized = JSON.stringify(start);
+      await writeFile(startConfigPath, serialized);
+      if (!existsSync(rerunStartConfigPath)) {
+        await writeFile(rerunStartConfigPath, serialized);
+      }
+    } catch {
+    }
+  };
+  const sendControl = (msg) => {
+    if (activeSocket?.readyState === WS_OPEN) {
+      try {
+        activeSocket.send(JSON.stringify(msg));
+      } catch {
+      }
+    }
+  };
+  const emit = (event) => {
+    const seq = ++seqCounter;
+    const line = JSON.stringify({ ...event, seq });
+    eventLog.push({ seq, line });
+    diskBuffer += `${line}
+`;
+    scheduleEventFlush();
+    if (activeSocket?.readyState === WS_OPEN) {
+      try {
+        activeSocket.send(line);
+      } catch {
+      }
+    }
+  };
+  const replay = (ws, afterSeq) => {
+    for (const entry of eventLog) {
+      if (entry.seq > afterSeq && ws.readyState === WS_OPEN) {
+        ws.send(entry.line);
+      }
+    }
+  };
+  const shouldEmitDebugEvent = (level, subsystem) => {
+    if (!debugConfig?.enabled) return false;
+    const threshold = debugConfig.level ?? "debug";
+    if (DEBUG_LEVEL_WEIGHT[level] > DEBUG_LEVEL_WEIGHT[threshold]) return false;
+    return subsystemMatches(debugConfig.subsystems, subsystem);
+  };
+  const rawStdoutWrite = process.stdout.write.bind(process.stdout);
+  const rawStderrWrite = process.stderr.write.bind(process.stderr);
+  const writeErrorToStderr = (input) => {
+    try {
+      const formatted = formatBridgeError(input.error);
+      rawStderrWrite(
+        `[harness:${bridgeType}:error] ${input.message}: ${formatted.message}
+`
+      );
+      if (formatted.stack) {
+        rawStderrWrite(`${formatted.stack}
+`);
+      }
+    } catch {
+    }
+  };
+  const emitWarning = (input) => {
+    try {
+      for (const line of input.message.split("\n")) {
+        if (line.trim().length > 0) {
+          rawStderrWrite(`[harness:${bridgeType}:warn] ${line}
+`);
+        }
+      }
+    } catch {
+    }
+  };
+  const emitError = (input) => {
+    writeErrorToStderr({
+      message: input.message ?? "bridge error",
+      error: input.error
+    });
+    emit({ type: "error", error: serialiseError(input.error) });
+  };
+  const installConsoleCapture = () => {
+    if (consoleCaptureInstalled) return;
+    consoleCaptureInstalled = true;
+    const buffers = {
+      stdout: "",
+      stderr: ""
+    };
+    const patch = (stream, raw) => (chunk, encoding, cb) => {
+      if (debugConfig?.enabled) {
+        try {
+          const enc = typeof encoding === "string" ? encoding : "utf8";
+          const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString(
+            enc
+          );
+          const combined = buffers[stream] + text.replace(/\r\n/g, "\n");
+          const parts = combined.split("\n");
+          buffers[stream] = parts.pop() ?? "";
+          for (const line of parts) {
+            const trimmed = line.replace(/\s+$/, "");
+            if (trimmed) {
+              emit({
+                type: "sandbox-log",
+                source: bridgeType,
+                stream,
+                line: trimmed
+              });
+            }
+          }
+        } catch {
+        }
+      }
+      return raw(
+        chunk,
+        encoding,
+        cb
+      );
+    };
+    process.stdout.write = patch(
+      "stdout",
+      rawStdoutWrite
+    );
+    process.stderr.write = patch(
+      "stderr",
+      rawStderrWrite
+    );
+  };
+  const handleInbound = async (msg, ws) => {
+    switch (msg.type) {
+      case "start": {
+        const firstTurn = isFirstTurn;
+        isFirstTurn = false;
+        eventLog = [];
+        diskBuffer = "";
+        void writeFile(eventLogPath, "").catch(() => {
+        });
+        turnAbort = new AbortController();
+        currentTurnState = "running";
+        currentInterruptHandler = void 0;
+        void writeStartConfig(msg);
+        void writeBridgeMeta("running");
+        const startDebug = msg.debug;
+        debugConfig = {
+          enabled: startDebug?.enabled ?? envDebugEnabled,
+          level: startDebug?.level ?? procEnv.HARNESS_DEBUG_LEVEL,
+          subsystems: startDebug?.subsystems ?? parseEnvList(procEnv.HARNESS_DEBUG_SUBSYSTEMS)
+        };
+        if (debugConfig.enabled) {
+          installConsoleCapture();
+        }
+        const turn = {
+          emit,
+          requestToolResult: (toolCallId) => new Promise((resolve) => {
+            pendingToolResults.set(toolCallId, resolve);
+          }),
+          requestToolApproval: (approvalId) => new Promise((resolve) => {
+            pendingToolApprovals.set(approvalId, resolve);
+          }),
+          pendingUserMessages: [],
+          abortSignal: turnAbort.signal,
+          onInterrupt: (handler) => {
+            currentInterruptHandler = handler;
+          },
+          firstTurn,
+          bridgeLog: (input) => {
+            const level = input.level ?? "debug";
+            if (!shouldEmitDebugEvent(level, input.subsystem)) return;
+            emit({
+              type: "debug-event",
+              level,
+              subsystem: input.subsystem,
+              message: input.message,
+              ...input.attrs ? { attrs: input.attrs } : {},
+              ...input.error !== void 0 ? { error: formatBridgeError(input.error) } : {}
+            });
+          },
+          emitWarning,
+          emitError
+        };
+        currentUserMessages = turn.pendingUserMessages;
+        try {
+          await onStart(msg, turn);
+        } catch (err) {
+          emitError({ error: err, message: "bridge turn failed" });
+        } finally {
+          currentInterruptHandler = void 0;
+          currentTurnState = "waiting";
+          void writeBridgeMeta("waiting");
+        }
+        return;
+      }
+      case "tool-result": {
+        const resolver = pendingToolResults.get(msg.toolCallId);
+        if (resolver) {
+          pendingToolResults.delete(msg.toolCallId);
+          resolver({ output: msg.output, isError: msg.isError });
+        }
+        return;
+      }
+      case "tool-approval-response": {
+        const resolver = pendingToolApprovals.get(msg.approvalId);
+        if (resolver) {
+          pendingToolApprovals.delete(msg.approvalId);
+          resolver({ approved: msg.approved, reason: msg.reason });
+        }
+        return;
+      }
+      case "user-message":
+        currentUserMessages?.push(msg.text);
+        return;
+      case "abort":
+        turnAbort?.abort();
+        return;
+      case "interrupt":
+        try {
+          if (pendingToolResults.size === 0 && pendingToolApprovals.size === 0) {
+            if (currentInterruptHandler) {
+              await currentInterruptHandler();
+            } else {
+              turnAbort?.abort();
+            }
+          }
+          sendControl({ type: "bridge-interrupted", ok: true });
+        } catch (err) {
+          sendControl({
+            type: "bridge-interrupted",
+            ok: false,
+            error: serialiseError(err)
+          });
+        }
+        return;
+      case "resume":
+        replay(ws, msg.lastSeenEventId);
+        return;
+      case "shutdown":
+        currentTurnState = "done";
+        void writeBridgeMeta("done");
+        drainThenExit(ws, 1e3, "shutdown");
+        return;
+      case "detach": {
+        currentTurnState = "done";
+        void writeBridgeMeta("done");
+        const data = await onDetach?.() ?? {};
+        sendControl({ type: "bridge-detach", data });
+        drainThenExit(ws, 1e3, "detach");
+        return;
+      }
+    }
+  };
+  void writeBridgeMeta("init");
+  const wss = new WebSocketServer({ port: bridgeWsPort, host: "0.0.0.0" });
+  const exit = () => {
+    if (options.onExit) {
+      options.onExit();
+      return;
+    }
+    wss.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 1e3).unref();
+  };
+  const drainThenExit = (ws, code, reason) => {
+    const start = Date.now();
+    const tick = () => {
+      const drained = ws.bufferedAmount === 0 || ws.readyState !== WS_OPEN;
+      if (drained || Date.now() - start >= 5e3) {
+        void flushPendingEventsToDisk().finally(() => {
+          try {
+            ws.close(code, reason);
+          } finally {
+            exit();
+          }
+        });
+        return;
+      }
+      setTimeout(tick, 10).unref();
+    };
+    tick();
+  };
+  wss.on("listening", () => {
+    const addr = wss.address();
+    currentBoundPort = typeof addr === "object" && addr ? addr.port : 0;
+    currentTurnState = "waiting";
+    void writeBridgeMeta("waiting");
+    stdout.write(
+      JSON.stringify({
+        type: "bridge-ready",
+        port: currentBoundPort
+      }) + "\n"
+    );
+    options.onListening?.(currentBoundPort);
+  });
+  wss.on("connection", (ws, req) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.searchParams.get("agent_bridge_token") !== expectedToken) {
+      ws.close(1008, "unauthorized");
+      return;
+    }
+    activeSocket = ws;
+    sendControl({
+      type: "bridge-hello",
+      state: currentTurnState,
+      lastSeq: seqCounter
+    });
+    ws.on("message", (raw) => {
+      let parsed;
+      try {
+        const text = typeof raw === "string" ? raw : Buffer.from(raw).toString("utf8");
+        parsed = JSON.parse(text);
+      } catch (err) {
+        sendControl({
+          type: "error",
+          error: `protocol parse error: ${err.message}`
+        });
+        return;
+      }
+      void handleInbound(parsed, ws);
+    });
+    ws.on("close", () => {
+      if (activeSocket === ws) {
+        activeSocket = void 0;
+      }
+    });
+    ws.on("error", () => {
+    });
+  });
+  process.on("uncaughtException", (err) => {
+    emitError({ error: err, message: "uncaught exception" });
+  });
+  process.on("unhandledRejection", (err) => {
+    emitError({ error: err, message: "unhandled rejection" });
+  });
+  await new Promise((resolve, reject) => {
+    if (wss.address() != null) {
+      resolve();
+      return;
+    }
+    wss.once("listening", resolve);
+    wss.once("error", reject);
+  });
+  return {
+    port: currentBoundPort,
+    close: () => new Promise((resolve) => {
+      wss.close(() => resolve());
+    })
+  };
+}
+function serialiseError(err) {
+  if (err instanceof Error) {
+    return { name: err.name, message: err.message, stack: err.stack };
+  }
+  return err;
+}
+export {
+  runBridge
+};
+//# sourceMappingURL=index.js.map