@ai-sdk/harness 1.0.72 → 1.0.73

package/src/bridge/index.ts

@@ -1,10 +1,11 @@
 // Shared in-sandbox bridge runtime. Adapter `bridge.mjs` bundles re-bundle
 // this module (tsup inlines it; `ws` stays external and resolves from the
 // sandbox-installed node_modules). It owns everything generic to the bridge
-// transport — the WebSocket server, token auth, single-flight connection
-// replacement, the in-memory event log + monotonic `seq`, resume replay, and
-// the lifecycle/meta files. The adapter supplies only `onStart` (drive its
-// CLI/SDK and translate to wire events) and lifecycle-specific cleanup hooks.
+// transport — the WebSocket server, token auth, the in-memory event log +
+// monotonic `seq`, resume replay, and the lifecycle/meta files. Any number of
+// hosts may be connected; exactly one of them owns the event stream, and
+// `start`/`resume` transfer that ownership. The adapter supplies only `onStart`
+// (drive its CLI/SDK and translate to wire events) and lifecycle cleanup hooks.
 
 import { appendFile, mkdir, writeFile } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
@@ -234,8 +235,14 @@ export async function runBridge<TStart extends { type: 'start' }>(
   // ─── mutable runtime state ──────────────────────────────────────────
   let currentBoundPort = 0;
   let currentTurnState: BridgeState = 'init';
+  /*
+   * The one connection turn events stream to. A socket claims it by asking for
+   * work — `start` (a turn) or `resume` (a catch-up) — never by connecting:
+   * every event goes here alone, so claiming on connect would silence a turn
+   * already streaming to someone else. Any number of sockets may be connected;
+   * the others still exchange control frames, they just get no events.
+   */
   let activeSocket: WebSocket | undefined;
-  let activeSocketReadyForLiveEvents = false;
   let isFirstTurn = true;
   let turnAbort: AbortController | undefined;
   let currentUserMessages: string[] | undefined;
@@ -374,26 +381,13 @@ export async function runBridge<TStart extends { type: 'start' }>(
   };
 
   // ─── wire send + replay ─────────────────────────────────────────────
-  const sendControl = (msg: Record<string, unknown>): void => {
-    if (activeSocket?.readyState === WS_OPEN) {
-      try {
-        activeSocket.send(JSON.stringify(msg));
-      } catch {
-        // best-effort
-      }
-    }
-  };
-
   const emit = (event: BridgeEvent): void => {
     const seq = ++seqCounter;
     const line = JSON.stringify({ ...event, seq });
     eventLog.push({ seq, line });
     diskBuffer += `${line}\n`;
     scheduleEventFlush();
-    if (
-      activeSocketReadyForLiveEvents &&
-      activeSocket?.readyState === WS_OPEN
-    ) {
+    if (activeSocket?.readyState === WS_OPEN) {
       try {
         activeSocket.send(line);
       } catch {
@@ -526,8 +520,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
   ): Promise<void> => {
     switch (msg.type) {
       case 'start': {
-        if (activeSocket !== ws) return;
-        activeSocketReadyForLiveEvents = true;
+        activeSocket = ws; // asking for a turn claims the event stream
         const firstTurn = isFirstTurn;
         isFirstTurn = false;
         eventLog = []; // clear previous turn; keep seqCounter monotonic
@@ -616,9 +609,9 @@ export async function runBridge<TStart extends { type: 'start' }>(
         turnAbort?.abort();
         return;
       case 'resume':
-        if (activeSocket !== ws) return;
+        activeSocket = ws; // asking for a catch-up claims it too
+        // Synchronous, so no event can slip out live ahead of the replayed tail.
         replay(ws, msg.lastSeenEventId);
-        activeSocketReadyForLiveEvents = true;
         return;
       case 'destroy':
         currentTurnState = 'done';
@@ -630,7 +623,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
         currentTurnState = 'done';
         void writeBridgeMeta('done');
         const data = (await onStop?.()) ?? {};
-        sendControl({ type: 'bridge-stop', data });
+        sendControl(ws, { type: 'bridge-stop', data });
         drainThenExit(ws, 1000, 'stop');
         return;
       }
@@ -693,16 +686,10 @@ export async function runBridge<TStart extends { type: 'start' }>(
       return;
     }
 
-    // Single-flight: a fresh authorized connection *replaces* the active one
-    // (the host reconnecting after a drop). The previous socket's close is a
-    // no-op below because it is no longer `activeSocket`.
-    activeSocket = ws;
-    activeSocketReadyForLiveEvents = false;
-
     // Announce liveness the instant we accept. Some sandbox runtimes complete
     // the host-side WS handshake before the connection is forwarded here; the
     // host waits for this frame before sending `start`/`resume`.
-    sendControl({
+    sendControl(ws, {
       type: 'bridge-hello',
       state: currentTurnState,
       lastSeq: seqCounter,
@@ -715,7 +702,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
           typeof raw === 'string' ? raw : Buffer.from(raw).toString('utf8');
         parsed = JSON.parse(text) as TStart | InboundControl;
       } catch (err) {
-        sendControl({
+        sendControl(ws, {
           type: 'error',
           error: `protocol parse error: ${(err as Error).message}`,
         });
@@ -725,13 +712,12 @@ export async function runBridge<TStart extends { type: 'start' }>(
     });
 
     ws.on('close', () => {
-      // Only the *current* socket's close matters. A stale socket (already
-      // replaced by a reconnect) closing is a no-op. Crucially we do NOT abort
-      // the in-flight turn — it keeps running and its events accumulate in the
-      // log for replay when the host reconnects.
+      // Only the stream owner's close matters; a socket that never claimed it,
+      // or that a later `start`/`resume` displaced, closes as a no-op.
+      // Crucially we do NOT abort the in-flight turn: it keeps running and its
+      // events accumulate in the log for replay on reconnect.
       if (activeSocket === ws) {
         activeSocket = undefined;
-        activeSocketReadyForLiveEvents = false;
       }
     });
 
@@ -767,6 +753,24 @@ export async function runBridge<TStart extends { type: 'start' }>(
   };
 }
 
+/*
+ * Control frames answer the socket that sent the frame they reply to, so the
+ * target is always explicit. Event streaming is the separate, stateful path
+ * (`emit` → `activeSocket`); this one carries no state at all.
+ */
+function sendControl(
+  socket: WebSocket | undefined,
+  message: Record<string, unknown>,
+): void {
+  if (socket?.readyState === WS_OPEN) {
+    try {
+      socket.send(JSON.stringify(message));
+    } catch {
+      // best-effort
+    }
+  }
+}
+
 function serialiseError(err: unknown): unknown {
   if (err instanceof Error) {
     return { name: err.name, message: err.message, stack: err.stack };

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

@@ -4,6 +4,7 @@ import {
   harnessV1DebugLevelSchema,
   type HarnessV1Diagnostic,
 } from './harness-v1-diagnostic';
+import type { HarnessV1ResponseFormat } from './harness-v1-response-format';
 import {
   harnessV1CompactionPartSchema,
   harnessV1ErrorPartSchema,
@@ -87,6 +88,17 @@ export const harnessV1BridgeBuiltinToolFilteringSchema = z.discriminatedUnion(
   ],
 );
 
+export const harnessV1BridgeResponseFormatSchema: z.ZodType<HarnessV1ResponseFormat> =
+  z.discriminatedUnion('type', [
+    z.object({ type: z.literal('text') }),
+    z.object({
+      type: z.literal('json'),
+      schema: z.record(z.string(), z.json()).optional(),
+      name: z.string().optional(),
+      description: z.string().optional(),
+    }),
+  ]);
+
 /**
  * Common fields of the inbound `start` message. Each adapter extends this with
  * its runtime-specific configuration (e.g. `thinking`/`continue` for Claude
@@ -105,6 +117,7 @@ export const harnessV1BridgeStartBaseSchema = z.object({
   debug: harnessV1DebugConfigSchema.optional(),
   permissionMode: harnessV1BridgePermissionModeSchema.optional(),
   builtinToolFiltering: harnessV1BridgeBuiltinToolFilteringSchema.optional(),
+  responseFormat: harnessV1BridgeResponseFormatSchema.optional(),
 });
 
 // --- Transport / control frames (outbound, not consumer events) ---

package/src/v1/harness-v1-response-format.ts

@@ -0,0 +1,32 @@
+export type HarnessV1JSONValue =
+  | null
+  | boolean
+  | number
+  | string
+  | HarnessV1JSONArray
+  | HarnessV1JSONObject;
+
+export interface HarnessV1JSONArray extends Array<HarnessV1JSONValue> {}
+
+export interface HarnessV1JSONObject {
+  [key: string]: HarnessV1JSONValue | undefined;
+}
+
+export type HarnessV1JSONSchema = HarnessV1JSONObject;
+
+/**
+ * Requested response format for one harness turn.
+ *
+ * This intentionally mirrors the AI SDK provider response-format shape
+ * without depending on `@ai-sdk/provider`. Harness implementations receive
+ * JSON Schema rather than the caller's original Zod or Standard Schema so the
+ * contract can cross process and package boundaries.
+ */
+export type HarnessV1ResponseFormat =
+  | { readonly type: 'text' }
+  | {
+      readonly type: 'json';
+      readonly schema?: HarnessV1JSONSchema;
+      readonly name?: string;
+      readonly description?: string;
+    };

package/src/v1/harness-v1-session.ts

@@ -3,6 +3,7 @@ import type { HarnessV1Observability } from './harness-v1-observability';
 import type { HarnessV1PermissionMode } from './harness-v1-permission-mode';
 import type { HarnessV1Prompt } from './harness-v1-prompt';
 import type { HarnessV1PromptControl } from './harness-v1-prompt-control';
+import type { HarnessV1ResponseFormat } from './harness-v1-response-format';
 import type {
   HarnessV1ContinueTurnState,
   HarnessV1ResumeSessionState,
@@ -105,6 +106,12 @@ export type HarnessV1PromptTurnOptions = {
    */
   readonly prompt: HarnessV1Prompt;
 
+  /**
+   * Response format requested for this turn. Adapters that cannot honor a
+   * JSON response format must throw `HarnessCapabilityUnsupportedError`.
+   */
+  readonly responseFormat?: HarnessV1ResponseFormat;
+
   /**
    * Host-defined tools to make available to the underlying runtime for this
    * turn. The harness emits `tool-call` events when the runtime calls one
@@ -144,6 +151,12 @@ export type HarnessV1PromptTurnOptions = {
  * that was previously suspended temporarily, e.g. by the workflow slice loop.
  */
 export type HarnessV1ContinueTurnOptions = {
+  /**
+   * Response format of the in-flight turn. Rerun-based adapters use this when
+   * reconstructing the turn; attach-based adapters may ignore it.
+   */
+  readonly responseFormat?: HarnessV1ResponseFormat;
+
   /**
    * Host-defined tools to make available for the continued turn. Same shape
    * as `doPromptTurn`'s `tools`. An adapter that purely attaches to a live turn

package/src/v1/index.ts

@@ -25,6 +25,13 @@ export {
 } from './harness-v1-builtin-tool';
 export type { HarnessV1Metadata } from './harness-v1-metadata';
 export type { HarnessV1Prompt } from './harness-v1-prompt';
+export type {
+  HarnessV1JSONSchema,
+  HarnessV1JSONArray,
+  HarnessV1JSONObject,
+  HarnessV1JSONValue,
+  HarnessV1ResponseFormat,
+} from './harness-v1-response-format';
 export type { HarnessV1SandboxProvider } from './harness-v1-sandbox-provider';
 export type {
   HarnessV1ContinueTurnState,
@@ -68,6 +75,7 @@ export {
   harnessV1BridgeInboundCommandSchemas,
   harnessV1BridgeOutboundMessageSchema,
   harnessV1BridgeReadySchema,
+  harnessV1BridgeResponseFormatSchema,
   harnessV1BridgeResumeInboundSchema,
   harnessV1BridgeSandboxLogSchema,
   harnessV1BridgeStopInboundSchema,