@ai-sdk/harness 1.0.76 → 1.0.78

package/src/bridge/index.ts

@@ -9,6 +9,7 @@
 
 import { appendFile, mkdir, writeFile } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { env as procEnv, pid, stdout } from 'node:process';
 import { WebSocketServer, type WebSocket } from 'ws';
 
@@ -21,6 +22,29 @@ export type BridgeEvent = Record<string, unknown> & { type: string };
 
 export type BridgeDebugLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
 
+export interface Experimental_BridgeUserMessage {
+  readonly messageId: string;
+  readonly text: string;
+  accept(): void;
+  reject(error: unknown): void;
+}
+
+export interface Experimental_BridgeUserMessageQueue extends AsyncIterable<Experimental_BridgeUserMessage> {
+  readonly pendingCount: number;
+  close(error?: unknown): void;
+}
+
+type InternalBridgeUserMessageQueue = Experimental_BridgeUserMessageQueue & {
+  enqueue(input: { messageId: string; text: string }): void;
+};
+
+type BridgeUserMessageResponse = {
+  type: 'user-message-response';
+  messageId: string;
+  accepted: boolean;
+  error?: { message: string };
+};
+
 /**
  * Per-session diagnostics config. The host resolves it from settings +
  * env and sends it on `start.debug`; the bridge gates console capture and
@@ -71,6 +95,125 @@ function formatBridgeError(err: unknown): {
   return { message: String(err) };
 }
 
+function createBridgeUserMessageQueue(options: {
+  respond(response: BridgeUserMessageResponse): void;
+}): InternalBridgeUserMessageQueue {
+  const messages: Experimental_BridgeUserMessage[] = [];
+  const waiters: Array<
+    (result: IteratorResult<Experimental_BridgeUserMessage>) => void
+  > = [];
+  const entries = new Map<
+    string,
+    {
+      response?: BridgeUserMessageResponse;
+      reject(error: unknown): void;
+    }
+  >();
+  let closed = false;
+  let pendingCount = 0;
+
+  const enqueue = (input: { messageId: string; text: string }): void => {
+    const existing = entries.get(input.messageId);
+    if (existing != null) {
+      if (existing.response != null) {
+        options.respond(existing.response);
+      }
+      return;
+    }
+
+    let settled = false;
+    const settle = (response: BridgeUserMessageResponse): void => {
+      if (settled) return;
+      settled = true;
+      pendingCount--;
+      const entry = entries.get(input.messageId);
+      if (entry != null) entry.response = response;
+      options.respond(response);
+    };
+    const message: Experimental_BridgeUserMessage = {
+      messageId: input.messageId,
+      text: input.text,
+      accept: () => {
+        settle({
+          type: 'user-message-response',
+          messageId: input.messageId,
+          accepted: true,
+        });
+      },
+      reject: error => {
+        settle({
+          type: 'user-message-response',
+          messageId: input.messageId,
+          accepted: false,
+          error: { message: formatBridgeError(error).message },
+        });
+      },
+    };
+    entries.set(input.messageId, {
+      reject: message.reject,
+    });
+    pendingCount++;
+
+    if (closed) {
+      message.reject(
+        new Error('The bridge turn is no longer accepting user messages.'),
+      );
+      return;
+    }
+
+    const waiter = waiters.shift();
+    if (waiter != null) {
+      waiter({ done: false, value: message });
+    } else {
+      messages.push(message);
+    }
+  };
+
+  const close = (error?: unknown): void => {
+    if (closed) return;
+    closed = true;
+    const reason =
+      error ??
+      new Error('The bridge turn ended before accepting the user message.');
+    for (const entry of entries.values()) {
+      if (entry.response == null) entry.reject(reason);
+    }
+    messages.length = 0;
+    while (waiters.length > 0) {
+      waiters.shift()!({ done: true, value: undefined });
+    }
+  };
+
+  return {
+    get pendingCount() {
+      return pendingCount;
+    },
+    enqueue,
+    close,
+    [Symbol.asyncIterator]() {
+      return {
+        next: () => {
+          const message = messages.shift();
+          if (message != null) {
+            return Promise.resolve({ done: false as const, value: message });
+          }
+          if (closed) {
+            return Promise.resolve({
+              done: true as const,
+              value: undefined,
+            });
+          }
+          return new Promise<IteratorResult<Experimental_BridgeUserMessage>>(
+            resolve => {
+              waiters.push(resolve);
+            },
+          );
+        },
+      };
+    },
+  };
+}
+
 function parseEnvList(value: string | undefined): string[] | undefined {
   if (!value) return undefined;
   const items = value
@@ -113,12 +256,7 @@ export interface BridgeTurn {
     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[];
+  readonly experimental_userMessages: Experimental_BridgeUserMessageQueue;
 
   /** Aborts when the host sends `abort`. */
   readonly abortSignal: AbortSignal;
@@ -192,7 +330,7 @@ type InboundControl =
       approved: boolean;
       reason?: string;
     }
-  | { type: 'user-message'; text: string }
+  | { type: 'user-message'; messageId?: string; text: string }
   | { type: 'abort' }
   | { type: 'stop' }
   | { type: 'destroy' }
@@ -245,7 +383,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
   let activeSocket: WebSocket | undefined;
   let isFirstTurn = true;
   let turnAbort: AbortController | undefined;
-  let currentUserMessages: string[] | undefined;
+  let currentUserMessages: InternalBridgeUserMessageQueue | undefined;
 
   // Diagnostics. Resolved per turn from `start.debug` with a sandbox-side
   // env fallback; gates console capture + structured `debug-event`s.
@@ -521,6 +659,9 @@ export async function runBridge<TStart extends { type: 'start' }>(
     switch (msg.type) {
       case 'start': {
         activeSocket = ws; // asking for a turn claims the event stream
+        currentUserMessages?.close(
+          new Error('A new bridge turn replaced the active turn.'),
+        );
         const firstTurn = isFirstTurn;
         isFirstTurn = false;
         eventLog = []; // clear previous turn; keep seqCounter monotonic
@@ -545,6 +686,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
         if (debugConfig.enabled) {
           installConsoleCapture();
         }
+        const userMessages = createBridgeUserMessageQueue({ respond: emit });
         const turn: BridgeTurn = {
           emit,
           requestToolResult: toolCallId =>
@@ -555,7 +697,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
             new Promise(resolve => {
               pendingToolApprovals.set(approvalId, resolve);
             }),
-          pendingUserMessages: [],
+          experimental_userMessages: userMessages,
           abortSignal: turnAbort.signal,
           firstTurn,
           bridgeLog: input => {
@@ -575,12 +717,16 @@ export async function runBridge<TStart extends { type: 'start' }>(
           emitWarning,
           emitError,
         };
-        currentUserMessages = turn.pendingUserMessages;
+        currentUserMessages = userMessages;
         try {
           await onStart(msg as TStart, turn);
         } catch (err) {
           emitError({ error: err, message: 'bridge turn failed' });
         } finally {
+          userMessages.close();
+          if (currentUserMessages === userMessages) {
+            currentUserMessages = undefined;
+          }
           currentTurnState = 'waiting';
           void writeBridgeMeta('waiting');
         }
@@ -602,9 +748,34 @@ export async function runBridge<TStart extends { type: 'start' }>(
         }
         return;
       }
-      case 'user-message':
-        currentUserMessages?.push(msg.text);
+      case 'user-message': {
+        const messageId = msg.messageId ?? randomUUID();
+        if (currentUserMessages == null) {
+          sendControl(ws, {
+            type: 'user-message-response',
+            messageId,
+            accepted: false,
+            error: { message: 'The bridge has no active turn to steer.' },
+          });
+          return;
+        }
+        if (ws !== activeSocket) {
+          sendControl(ws, {
+            type: 'user-message-response',
+            messageId,
+            accepted: false,
+            error: {
+              message: 'The connection does not own the active bridge turn.',
+            },
+          });
+          return;
+        }
+        currentUserMessages.enqueue({
+          messageId,
+          text: msg.text,
+        });
         return;
+      }
       case 'abort':
         turnAbort?.abort();
         return;
@@ -693,6 +864,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
       type: 'bridge-hello',
       state: currentTurnState,
       lastSeq: seqCounter,
+      capabilities: { experimental_userMessageResponses: true },
     });
 
     ws.on('message', (raw: ArrayBufferLike | string) => {

package/src/utils/bridge-user-message-submitter.ts

@@ -0,0 +1,96 @@
+export type Experimental_BridgeUserMessageRequest = {
+  type: 'user-message';
+  messageId: string;
+  text: string;
+};
+
+export type Experimental_BridgeUserMessageResponse = {
+  type: 'user-message-response';
+  messageId: string;
+  accepted: boolean;
+  error?: { message: string };
+};
+
+export type Experimental_BridgeUserMessageSubmitter = {
+  submit(text: string): Promise<void>;
+  close(error?: unknown): void;
+};
+
+export function experimental_createBridgeUserMessageSubmitter(options: {
+  send(message: Experimental_BridgeUserMessageRequest): void;
+  onResponse(
+    listener: (response: Experimental_BridgeUserMessageResponse) => void,
+  ): () => void;
+  onReconnect(listener: () => void): () => void;
+}): Experimental_BridgeUserMessageSubmitter {
+  const pending = new Map<
+    string,
+    {
+      request: Experimental_BridgeUserMessageRequest;
+      resolve(): void;
+      reject(error: unknown): void;
+    }
+  >();
+  let closed = false;
+
+  const send = (request: Experimental_BridgeUserMessageRequest): void => {
+    try {
+      options.send(request);
+    } catch (error) {
+      const entry = pending.get(request.messageId);
+      if (entry == null) return;
+      pending.delete(request.messageId);
+      entry.reject(error);
+    }
+  };
+
+  const unsubscribeResponse = options.onResponse(response => {
+    const entry = pending.get(response.messageId);
+    if (entry == null) return;
+    pending.delete(response.messageId);
+    if (response.accepted) {
+      entry.resolve();
+    } else {
+      entry.reject(
+        new Error(
+          response.error?.message ?? 'The runtime rejected the user message.',
+        ),
+      );
+    }
+  });
+  const unsubscribeReconnect = options.onReconnect(() => {
+    for (const entry of pending.values()) send(entry.request);
+  });
+
+  return {
+    submit: text => {
+      if (closed) {
+        return Promise.reject(
+          new Error('The bridge turn is no longer accepting user messages.'),
+        );
+      }
+      const messageId = crypto.randomUUID();
+      const request: Experimental_BridgeUserMessageRequest = {
+        type: 'user-message',
+        messageId,
+        text,
+      };
+      const promise = new Promise<void>((resolve, reject) => {
+        pending.set(messageId, { request, resolve, reject });
+      });
+      send(request);
+      return promise;
+    },
+    close: error => {
+      if (closed) return;
+      closed = true;
+      unsubscribeResponse();
+      unsubscribeReconnect();
+      const reason =
+        error ??
+        new Error('The bridge turn ended before accepting the user message.');
+      for (const entry of pending.values()) entry.reject(reason);
+      pending.clear();
+    },
+  };
+}

package/src/utils/get-restricted-sandbox-session.ts

@@ -0,0 +1,10 @@
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import type { HarnessV1NetworkSandboxSession } from '../v1';
+
+export function getRestrictedSandboxSession(
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession,
+): SandboxSession {
+  return 'restricted' in sandboxSession
+    ? sandboxSession.restricted()
+    : sandboxSession;
+}

package/src/utils/index.ts

@@ -4,6 +4,12 @@ export {
   type SandboxChannelOptions,
   type SandboxChannelReconnectOptions,
 } from './sandbox-channel';
+export {
+  experimental_createBridgeUserMessageSubmitter,
+  type Experimental_BridgeUserMessageRequest,
+  type Experimental_BridgeUserMessageResponse,
+  type Experimental_BridgeUserMessageSubmitter,
+} from './bridge-user-message-submitter';
 export { classifyDiskLog, type DiskLogRecoveryMode } from './classify-disk-log';
 export { getAiGatewayAuthFromEnv } from './ai-gateway-auth';
 export {
@@ -34,3 +40,5 @@ export {
   forwardBridgeProcessStream,
   logBridgeError,
 } from './bridge-diagnostics';
+export { resolveSandboxDefaultWorkingDirectory } from './resolve-sandbox-default-working-directory';
+export { getRestrictedSandboxSession } from './get-restricted-sandbox-session';

package/src/utils/resolve-sandbox-default-working-directory.ts

@@ -0,0 +1,33 @@
+import { posix } from 'node:path';
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import type { HarnessV1NetworkSandboxSession } from '../v1';
+
+export async function resolveSandboxDefaultWorkingDirectory({
+  sandboxSession,
+  abortSignal,
+}: {
+  readonly sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
+  readonly abortSignal?: AbortSignal;
+}): Promise<string> {
+  if ('defaultWorkingDirectory' in sandboxSession) {
+    return sandboxSession.defaultWorkingDirectory;
+  }
+
+  const result = await sandboxSession.run({
+    command: 'pwd',
+    abortSignal,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Failed to resolve sandbox default working directory (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
+    );
+  }
+
+  const cwd = result.stdout.trim();
+  if (!posix.isAbsolute(cwd)) {
+    throw new Error(
+      `Failed to resolve sandbox default working directory: expected an absolute path, got ${JSON.stringify(cwd)}.`,
+    );
+  }
+  return cwd === '/' ? cwd : cwd.replace(/\/+$/, '');
+}

package/src/utils/sandbox-channel.ts

@@ -133,6 +133,7 @@ export class SandboxChannel<
   private readonly onCloseHandlers = new Set<
     (code: number, reason: string) => void
   >();
+  private readonly onReconnectHandlers = new Set<() => void>();
 
   private readonly connectThunk: () => Promise<WebSocket>;
   private readonly outboundSchema: FlexibleSchema<TOut>;
@@ -247,6 +248,13 @@ export class SandboxChannel<
     this.onCloseHandlers.add(handler);
   }
 
+  onReconnect(handler: () => void): () => void {
+    this.onReconnectHandlers.add(handler);
+    return () => {
+      this.onReconnectHandlers.delete(handler);
+    };
+  }
+
   send(message: TIn): void {
     if (this.terminal) {
       throw new Error(
@@ -386,6 +394,7 @@ export class SandboxChannel<
           }),
         );
         this.flushPending();
+        for (const handler of this.onReconnectHandlers) handler();
         this.onDebug?.({
           event: 'reconnected',
           attempt,

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

@@ -133,6 +133,18 @@ export const harnessV1BridgeHelloSchema = z.object({
   type: z.literal('bridge-hello'),
   state: z.string().optional(),
   lastSeq: z.number().optional(),
+  capabilities: z
+    .object({
+      experimental_userMessageResponses: z.boolean().optional(),
+    })
+    .optional(),
+});
+
+export const experimental_harnessV1BridgeUserMessageResponseSchema = z.object({
+  type: z.literal('user-message-response'),
+  messageId: z.string(),
+  accepted: z.boolean(),
+  error: z.object({ message: z.string() }).optional(),
 });
 
 /**
@@ -211,6 +223,7 @@ export const harnessV1BridgeOutboundMessageSchema = z.discriminatedUnion(
     harnessV1ErrorPartSchema,
     harnessV1RawPartSchema,
     harnessV1BridgeHelloSchema,
+    experimental_harnessV1BridgeUserMessageResponseSchema,
     harnessV1BridgeStopSchema,
     harnessV1BridgeThreadSchema,
     harnessV1BridgeSandboxLogSchema,
@@ -222,6 +235,10 @@ export type HarnessV1BridgeOutboundMessage = z.infer<
   typeof harnessV1BridgeOutboundMessageSchema
 >;
 
+export type Experimental_HarnessV1BridgeUserMessageResponse = z.infer<
+  typeof experimental_harnessV1BridgeUserMessageResponseSchema
+>;
+
 export type HarnessV1BridgeSandboxLog = z.infer<
   typeof harnessV1BridgeSandboxLogSchema
 >;
@@ -283,9 +300,15 @@ export const harnessV1BridgeToolApprovalResponseInboundSchema = z.object({
 
 export const harnessV1BridgeUserMessageInboundSchema = z.object({
   type: z.literal('user-message'),
+  messageId: z.string().optional(),
   text: z.string(),
 });
 
+export const experimental_harnessV1BridgeUserMessageInboundSchema =
+  harnessV1BridgeUserMessageInboundSchema.extend({
+    messageId: z.string(),
+  });
+
 export const harnessV1BridgeAbortInboundSchema = z.object({
   type: z.literal('abort'),
 });

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

@@ -1,4 +1,5 @@
 import type { HarnessV1NetworkSandboxSession } from './harness-v1-network-sandbox-session';
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
 import type { HarnessV1Observability } from './harness-v1-observability';
 import type { HarnessV1PermissionMode } from './harness-v1-permission-mode';
 import type { HarnessV1Prompt } from './harness-v1-prompt';
@@ -76,21 +77,17 @@ export type HarnessV1StartOptions = {
    */
   readonly observability?: HarnessV1Observability;
   /**
-   * Network sandbox session the adapter operates against. It is owned and
-   * lifecycled by `HarnessAgent`. Adapters call `restricted()` for the
-   * tool-safe filesystem/exec/spawn surface, and use the infra methods
-   * (`getPortEndpoint`, `ports`, `setNetworkPolicy`,
-   * `setRequestTransformations`, `addRequestTransformations`) for bridge
-   * wiring. Adapters must not call `stop()` themselves; the agent does that
-   * during cleanup.
+   * Sandbox session the adapter operates against. Network sandbox sessions
+   * expose optional infrastructure capabilities for bridge wiring; caller-
+   * provided basic sandbox sessions expose only filesystem and process APIs.
+   * Adapters must not stop or destroy the sandbox themselves.
    */
-  readonly sandboxSession: HarnessV1NetworkSandboxSession;
+  readonly sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
 
   /**
-   * Absolute path the adapter runs the agent in for this session. Composed by
-   * the framework as `<sandboxSession.defaultWorkingDirectory>/<harnessId>-<sessionId>`
-   * and created before `doStart`, so the adapter uses it directly instead of
-   * deriving its own provider-specific path.
+   * Absolute path the adapter runs the agent in for this session. Composed
+   * underneath the sandbox's resolved default working directory and created
+   * before `doStart`.
    */
   readonly sessionWorkDir: string;
 };

package/src/v1/index.ts

@@ -73,6 +73,7 @@ export {
   harnessV1BridgeDestroyInboundSchema,
   harnessV1BridgeHelloSchema,
   harnessV1BridgeInboundCommandSchemas,
+  harnessV1BridgeUserMessageInboundSchema,
   harnessV1BridgeOutboundMessageSchema,
   harnessV1BridgeReadySchema,
   harnessV1BridgeResponseFormatSchema,
@@ -86,13 +87,15 @@ export {
   harnessV1BridgeToolResultInboundSchema,
   harnessV1BridgePermissionModeSchema,
   harnessV1BridgeToolWireSchema,
-  harnessV1BridgeUserMessageInboundSchema,
+  experimental_harnessV1BridgeUserMessageInboundSchema,
+  experimental_harnessV1BridgeUserMessageResponseSchema,
   harnessV1DiagnosticFromBridgeFrame,
   type HarnessV1BridgeDebugEvent,
   type HarnessV1BridgeOutboundMessage,
   type HarnessV1BridgeReady,
   type HarnessV1BridgeSandboxLog,
   type HarnessV1BridgeToolWire,
+  type Experimental_HarnessV1BridgeUserMessageResponse,
 } from './harness-v1-bridge-protocol';
 export {
   harnessV1DebugConfigSchema,