@ai-sdk/harness 0.0.0 → 1.0.0-beta.14

package/dist/utils/index.d.ts

@@ -0,0 +1,225 @@
+import { FlexibleSchema, Experimental_SandboxProcess, Experimental_SandboxSession } 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>;
+
+type BridgeReadySource = 'stdout' | 'metadata';
+type BridgeReadyErrorContext = {
+    proc: Experimental_SandboxProcess;
+    stdoutTail: string[];
+};
+type WaitForBridgeReadyOptions = {
+    proc: Experimental_SandboxProcess;
+    sandbox: Experimental_SandboxSession;
+    bridgeStateDir: string;
+    bridgeType: string;
+    timeoutMs: number;
+    abortSignal?: AbortSignal;
+    pollIntervalMs?: number;
+    createTimeoutError?: (context: BridgeReadyErrorContext) => Error | Promise<Error>;
+    createExitError?: (context: BridgeReadyErrorContext) => Error | Promise<Error>;
+};
+type WaitForBridgeReadyResult = {
+    port: number;
+    source: BridgeReadySource;
+    stdoutTail: string[];
+};
+declare function markBridgeStarting({ sandbox, bridgeStateDir, bridgeType, abortSignal, }: {
+    sandbox: Experimental_SandboxSession;
+    bridgeStateDir: string;
+    bridgeType: string;
+    abortSignal?: AbortSignal;
+}): Promise<void>;
+declare function waitForBridgeReady({ proc, sandbox, bridgeStateDir, bridgeType, timeoutMs, abortSignal, pollIntervalMs, createTimeoutError, createExitError, }: WaitForBridgeReadyOptions): Promise<WaitForBridgeReadyResult>;
+
+export { type BridgeReadyErrorContext, type BridgeReadySource, type DiskLogRecoveryMode, SandboxChannel, type SandboxChannelDebugEvent, type SandboxChannelOptions, type SandboxChannelReconnectOptions, type WaitForBridgeReadyOptions, type WaitForBridgeReadyResult, classifyDiskLog, markBridgeStarting, waitForBridgeReady };