@ai-sdk/harness 1.0.22 → 1.0.23

package/src/bridge/index.ts

@@ -57,6 +57,14 @@ function formatBridgeError(err: unknown): {
   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) };
 }
 
@@ -112,6 +120,13 @@ export interface BridgeTurn {
   /** 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;
 
@@ -128,6 +143,15 @@ export interface BridgeTurn {
     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;
 }
 
 export interface RunBridgeOptions<TStart extends { type: 'start' }> {
@@ -167,6 +191,7 @@ type InboundControl =
     }
   | { type: 'user-message'; text: string }
   | { type: 'abort' }
+  | { type: 'interrupt' }
   | { type: 'shutdown' }
   | { type: 'detach' }
   | { type: 'resume'; lastSeenEventId: number };
@@ -212,6 +237,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
   let isFirstTurn = true;
   let turnAbort: AbortController | undefined;
   let currentUserMessages: string[] | undefined;
+  let currentInterruptHandler: (() => void | Promise<void>) | undefined;
 
   // Diagnostics. Resolved per turn from `start.debug` with a sandbox-side
   // env fallback; gates console capture + structured `debug-event`s.
@@ -402,6 +428,40 @@ export async function runBridge<TStart extends { type: 'start' }>(
    */
   const rawStdoutWrite = process.stdout.write.bind(process.stdout);
   const rawStderrWrite = process.stderr.write.bind(process.stderr);
+
+  const writeErrorToStderr = (input: {
+    message: string;
+    error: unknown;
+  }): void => {
+    try {
+      const formatted = formatBridgeError(input.error);
+      rawStderrWrite(
+        `[harness:${bridgeType}:error] ${input.message}: ${formatted.message}\n`,
+      );
+      if (formatted.stack) {
+        rawStderrWrite(`${formatted.stack}\n`);
+      }
+    } catch {}
+  };
+
+  const emitWarning = (input: { message: string }): void => {
+    try {
+      for (const line of input.message.split('\n')) {
+        if (line.trim().length > 0) {
+          rawStderrWrite(`[harness:${bridgeType}:warn] ${line}\n`);
+        }
+      }
+    } catch {}
+  };
+
+  const emitError = (input: { error: unknown; message?: string }): void => {
+    writeErrorToStderr({
+      message: input.message ?? 'bridge error',
+      error: input.error,
+    });
+    emit({ type: 'error', error: serialiseError(input.error) });
+  };
+
   const installConsoleCapture = (): void => {
     if (consoleCaptureInstalled) return;
     consoleCaptureInstalled = true;
@@ -471,6 +531,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
         void writeFile(eventLogPath, '').catch(() => {});
         turnAbort = new AbortController();
         currentTurnState = 'running';
+        currentInterruptHandler = undefined;
         void writeStartConfig(msg);
         void writeBridgeMeta('running');
         const startDebug = (msg as { debug?: BridgeDebugConfig }).debug;
@@ -498,6 +559,9 @@ export async function runBridge<TStart extends { type: 'start' }>(
             }),
           pendingUserMessages: [],
           abortSignal: turnAbort.signal,
+          onInterrupt: handler => {
+            currentInterruptHandler = handler;
+          },
           firstTurn,
           bridgeLog: input => {
             const level = input.level ?? 'debug';
@@ -513,13 +577,16 @@ export async function runBridge<TStart extends { type: 'start' }>(
                 : {}),
             });
           },
+          emitWarning,
+          emitError,
         };
         currentUserMessages = turn.pendingUserMessages;
         try {
           await onStart(msg as TStart, turn);
         } catch (err) {
-          emit({ type: 'error', error: serialiseError(err) });
+          emitError({ error: err, message: 'bridge turn failed' });
         } finally {
+          currentInterruptHandler = undefined;
           currentTurnState = 'waiting';
           void writeBridgeMeta('waiting');
         }
@@ -547,6 +614,22 @@ export async function runBridge<TStart extends { type: 'start' }>(
       case 'abort':
         turnAbort?.abort();
         return;
+      case 'interrupt':
+        try {
+          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;
@@ -669,10 +752,10 @@ export async function runBridge<TStart extends { type: 'start' }>(
 
   // Surface bridge-internal crashes to the host instead of dying silently.
   process.on('uncaughtException', err => {
-    emit({ type: 'error', error: serialiseError(err) });
+    emitError({ error: err, message: 'uncaught exception' });
   });
   process.on('unhandledRejection', err => {
-    emit({ type: 'error', error: serialiseError(err) });
+    emitError({ error: err, message: 'unhandled rejection' });
   });
 
   await new Promise<void>((resolve, reject) => {

package/src/utils/bridge-diagnostics.ts

@@ -0,0 +1,213 @@
+import type { Experimental_SandboxProcess } from '@ai-sdk/provider-utils';
+
+const DEFAULT_TAIL_LIMIT = 20;
+
+type BridgeProcessStreamName = 'stdout' | 'stderr';
+
+type SerializedError = {
+  name?: string;
+  message: string;
+  stack?: string;
+};
+
+function isSerializedError(error: unknown): error is SerializedError {
+  return (
+    typeof error === 'object' &&
+    error != null &&
+    typeof (error as { message?: unknown }).message === 'string'
+  );
+}
+
+function stringifyUnknown(value: unknown): string {
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export function formatBridgeError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.stack ?? `${error.name}: ${error.message}`;
+  }
+  if (isSerializedError(error)) {
+    return (
+      error.stack ?? `${error.name ? `${error.name}: ` : ''}${error.message}`
+    );
+  }
+  return stringifyUnknown(error);
+}
+
+function writeToStderr(line: string): void {
+  try {
+    process.stderr.write(line);
+  } catch {}
+}
+
+export function logBridgeError({
+  harnessId,
+  sessionId,
+  context,
+  error,
+  write = writeToStderr,
+}: {
+  harnessId: string;
+  sessionId?: string;
+  context?: string;
+  error: unknown;
+  write?: (line: string) => void;
+}): void {
+  const prefix = `[harness:${harnessId}:error${
+    sessionId ? ` session=${sessionId}` : ''
+  }]`;
+  const message = context
+    ? `${context}: ${formatBridgeError(error)}`
+    : formatBridgeError(error);
+  for (const line of message.split('\n')) {
+    if (line.trim().length > 0) {
+      write(`${prefix} ${line}\n`);
+    }
+  }
+}
+
+export function createBridgeErrorHandler({
+  harnessId,
+  sessionId,
+}: {
+  harnessId: string;
+  sessionId?: string;
+}): (event: { type: 'error'; error: unknown }) => void {
+  return event => {
+    logBridgeError({
+      harnessId,
+      sessionId,
+      context: 'bridge emitted an error frame',
+      error: event.error,
+    });
+  };
+}
+
+export async function createBridgeStartupError({
+  message,
+  proc,
+  stdoutTail,
+  stderrTail,
+  stderrDone,
+}: {
+  message: string;
+  proc: Experimental_SandboxProcess;
+  stdoutTail: string[];
+  stderrTail: string[];
+  stderrDone?: Promise<void>;
+}): Promise<Error> {
+  if (stderrDone) {
+    await Promise.race([stderrDone, sleep(250)]).catch(() => {});
+  }
+
+  let exitStatus = '';
+  try {
+    const result = (await Promise.race([
+      proc.wait(),
+      sleep(250).then(() => undefined),
+    ])) as { exitCode?: number } | undefined;
+    if (result?.exitCode !== undefined) {
+      exitStatus = ` Exit code: ${result.exitCode}.`;
+    }
+  } catch {}
+
+  const details: string[] = [];
+  if (stdoutTail.length > 0) {
+    details.push(`stdout:\n${stdoutTail.join('\n')}`);
+  }
+  if (stderrTail.length > 0) {
+    details.push(`stderr:\n${stderrTail.join('\n')}`);
+  }
+
+  return new Error(
+    `${message}${exitStatus}${
+      details.length > 0 ? `\n\n${details.join('\n\n')}` : ''
+    }`,
+  );
+}
+
+export async function forwardBridgeProcessStream({
+  stream,
+  streamName,
+  source = 'bridge',
+  collectTail,
+  tailLimit = DEFAULT_TAIL_LIMIT,
+}: {
+  stream: ReadableStream<Uint8Array>;
+  streamName: BridgeProcessStreamName;
+  source?: string;
+  collectTail?: string[];
+  tailLimit?: number;
+}): Promise<void> {
+  try {
+    const reader = stream.pipeThrough(new TextDecoderStream()).getReader();
+    const decoder = lineDecoder();
+    while (true) {
+      const { value, done } = await reader.read();
+      const lines = done ? decoder.flush() : value ? decoder.push(value) : [];
+      for (const line of lines) {
+        recordTail({ lines: collectTail, line, limit: tailLimit });
+        writeToStderr(`[harness:${source}:${streamName}] ${line}\n`);
+      }
+      if (done) return;
+    }
+  } catch {}
+}
+
+export async function drainBridgeProcessStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<void> {
+  try {
+    const reader = stream.pipeThrough(new TextDecoderStream()).getReader();
+    while (true) {
+      const { done } = await reader.read();
+      if (done) return;
+    }
+  } catch {}
+}
+
+function recordTail({
+  lines,
+  line,
+  limit,
+}: {
+  lines: string[] | undefined;
+  line: string;
+  limit: number;
+}): void {
+  if (!lines) return;
+  lines.push(line);
+  while (lines.length > limit) lines.shift();
+}
+
+function lineDecoder() {
+  let buffer = '';
+  return {
+    push(chunk: string): string[] {
+      buffer += chunk;
+      const lines: string[] = [];
+      let nl: number;
+      while ((nl = buffer.indexOf('\n')) !== -1) {
+        const raw = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        const line = raw.replace(/\r$/, '').trim();
+        if (line.length > 0) lines.push(line);
+      }
+      return lines;
+    },
+    flush(): string[] {
+      const line = buffer.replace(/\r$/, '').trim();
+      buffer = '';
+      return line.length > 0 ? [line] : [];
+    },
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/utils/index.ts

@@ -21,3 +21,11 @@ export {
   type WaitForBridgeReadyOptions,
   type WaitForBridgeReadyResult,
 } from './bridge-ready';
+export {
+  createBridgeErrorHandler,
+  createBridgeStartupError,
+  drainBridgeProcessStream,
+  formatBridgeError,
+  forwardBridgeProcessStream,
+  logBridgeError,
+} from './bridge-diagnostics';

package/src/utils/sandbox-channel.ts

@@ -58,6 +58,8 @@ export interface SandboxChannelOptions<TOut> {
     event: Extract<TOut, { type: 'sandbox-log' | 'debug-event' }>,
   ) => void;
 
+  onBridgeError?: (event: Extract<TOut, { type: 'error' }>) => void;
+
   /**
    * Seed the host-side cursor before the first connect. Pass the
    * `lastSeenEventId` persisted from a prior process so the bridge replays only
@@ -116,6 +118,9 @@ export class SandboxChannel<
   private readonly onDiagnostic:
     | ((event: Extract<TOut, { type: 'sandbox-log' | 'debug-event' }>) => void)
     | undefined;
+  private readonly onBridgeError:
+    | ((event: Extract<TOut, { type: 'error' }>) => void)
+    | undefined;
   private readonly maxElapsedMs: number;
   private readonly initialDelayMs: number;
   private readonly maxDelayMs: number;
@@ -142,6 +147,7 @@ export class SandboxChannel<
     this.outboundSchema = options.outboundSchema;
     this.onDebug = options.onDebug;
     this.onDiagnostic = options.onDiagnostic;
+    this.onBridgeError = options.onBridgeError;
     this.maxElapsedMs = options.reconnect?.maxElapsedMs ?? 30_000;
     this.initialDelayMs = options.reconnect?.initialDelayMs ?? 50;
     this.maxDelayMs = options.reconnect?.maxDelayMs ?? 2_000;
@@ -244,6 +250,59 @@ export class SandboxChannel<
     this.enqueue(() => this.finalizeClose(1000, 'closed'));
   }
 
+  interrupt(options?: { timeoutMs?: number }): Promise<void> {
+    const timeoutMs = options?.timeoutMs ?? 5000;
+    return new Promise<void>((resolve, reject) => {
+      let settled = false;
+      let unsub = (): void => {};
+      const timer = setTimeout(() => {
+        complete(
+          new Error(
+            `SandboxChannel: interrupt was not acknowledged within ${timeoutMs}ms.`,
+          ),
+        );
+      }, timeoutMs);
+      timer.unref?.();
+
+      const complete = (error?: unknown): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        unsub();
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      };
+
+      unsub = this.on('bridge-interrupted' as EventTypeOf<TOut>, event => {
+        const response = event as unknown as {
+          type: 'bridge-interrupted';
+          ok: boolean;
+          error?: unknown;
+        };
+        if (response.ok) {
+          complete();
+          return;
+        }
+        complete(
+          new Error(
+            `SandboxChannel: interrupt failed: ${formatControlError(
+              response.error,
+            )}`,
+          ),
+        );
+      });
+
+      try {
+        this.send({ type: 'interrupt' } as TIn);
+      } catch (err) {
+        complete(err);
+      }
+    });
+  }
+
   /**
    * Gracefully suspend at a slice boundary: stop processing inbound frames
    * (so the cursor freezes at the last delivered event), drain any frames
@@ -428,6 +487,9 @@ export class SandboxChannel<
       );
       return;
     }
+    if (message.type === 'error') {
+      this.onBridgeError?.(message as Extract<TOut, { type: 'error' }>);
+    }
     const type = message.type as EventTypeOf<TOut>;
     const set = this.listeners.get(type);
     if (!set || set.size === 0) {
@@ -451,3 +513,13 @@ export class SandboxChannel<
     for (const h of this.onCloseHandlers) h(code, reason);
   }
 }
+
+function formatControlError(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (error && typeof error === 'object') {
+    const message = (error as { message?: unknown }).message;
+    if (typeof message === 'string' && message.length > 0) return message;
+  }
+  if (typeof error === 'string' && error.length > 0) return error;
+  return 'unknown error';
+}

package/src/v1/harness-v1-bridge-protocol.ts

@@ -140,6 +140,17 @@ export const harnessV1BridgeThreadSchema = z.object({
   threadId: z.string(),
 });
 
+/**
+ * Acknowledgement for an inbound `interrupt` command. The host waits for this
+ * before freezing its replay cursor so the adapter-specific interrupt has
+ * actually reached the underlying runtime.
+ */
+export const harnessV1BridgeInterruptedSchema = z.object({
+  type: z.literal('bridge-interrupted'),
+  ok: z.boolean(),
+  error: z.unknown().optional(),
+});
+
 // --- Diagnostics frames (outbound, not consumer events) ---
 
 /**
@@ -200,6 +211,7 @@ export const harnessV1BridgeOutboundMessageSchema = z.discriminatedUnion(
     harnessV1BridgeHelloSchema,
     harnessV1BridgeDetachSchema,
     harnessV1BridgeThreadSchema,
+    harnessV1BridgeInterruptedSchema,
     harnessV1BridgeSandboxLogSchema,
     harnessV1BridgeDebugEventSchema,
   ],
@@ -277,6 +289,10 @@ export const harnessV1BridgeAbortInboundSchema = z.object({
   type: z.literal('abort'),
 });
 
+export const harnessV1BridgeInterruptInboundSchema = z.object({
+  type: z.literal('interrupt'),
+});
+
 export const harnessV1BridgeShutdownInboundSchema = z.object({
   type: z.literal('shutdown'),
 });
@@ -308,6 +324,7 @@ export const harnessV1BridgeInboundCommandSchemas = [
   harnessV1BridgeToolApprovalResponseInboundSchema,
   harnessV1BridgeUserMessageInboundSchema,
   harnessV1BridgeAbortInboundSchema,
+  harnessV1BridgeInterruptInboundSchema,
   harnessV1BridgeShutdownInboundSchema,
   harnessV1BridgeResumeInboundSchema,
   harnessV1BridgeDetachInboundSchema,