@ai-sdk/harness 1.0.163 → 1.0.164

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness",
-  "version": "1.0.163",
+  "version": "1.0.164",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -44,9 +44,9 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.33",
-    "@ai-sdk/provider-utils": "5.0.67",
-    "ai": "7.0.152"
+    "@ai-sdk/provider": "4.0.34",
+    "@ai-sdk/provider-utils": "5.0.68",
+    "ai": "7.0.153"
   },
   "peerDependencies": {
     "ws": "^8.21.0",
@@ -58,7 +58,7 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/otel": "1.0.152",
+    "@ai-sdk/otel": "1.0.153",
     "@opentelemetry/sdk-trace-base": "2.7.1",
     "@types/node": "22.19.19",
     "@types/ws": "^8.5.13",

package/src/utils/bridge-endpoint.ts

@@ -0,0 +1,106 @@
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import { HarnessCapabilityUnsupportedError } from '../errors/harness-capability-unsupported-error';
+import type {
+  HarnessV1MintBridgeTokenCallback,
+  HarnessV1NetworkSandboxSession,
+  HarnessV1PortEndpoint,
+} from '../v1';
+import { withBridgeToken } from './bridge-token';
+
+/**
+ * Validates the bridge connection settings against the sandbox session before
+ * any bridge work starts.
+ *
+ * Basic sandbox sessions cannot expose ports, so they need both an explicit
+ * `port` and `portEndpoint` setting. A custom `mintBridgeToken` callback needs
+ * a sandbox id to mint the token for.
+ */
+export function validateBridgeSandboxSettings({
+  sandboxSession,
+  sandboxId,
+  portOverride,
+  portEndpointOverride,
+  mintBridgeToken,
+}: {
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
+  sandboxId: string | undefined;
+  portOverride: number | undefined;
+  portEndpointOverride: HarnessV1PortEndpoint | undefined;
+  mintBridgeToken: HarnessV1MintBridgeTokenCallback | undefined;
+}): void {
+  if (!('getPortEndpoint' in sandboxSession)) {
+    if (portOverride == null) {
+      throw new HarnessCapabilityUnsupportedError({
+        message:
+          'The harness requires an explicit `port` setting when using a basic sandbox session.',
+      });
+    }
+    if (portEndpointOverride == null) {
+      throw createMissingPortEndpointError();
+    }
+  }
+  if (mintBridgeToken != null && sandboxId == null) {
+    throw new HarnessCapabilityUnsupportedError({
+      message:
+        'The harness cannot use `mintBridgeToken` with a sandbox session that does not expose an id.',
+    });
+  }
+}
+
+/**
+ * Resolves the port the bridge listens on inside the sandbox: the `port`
+ * setting if present, otherwise the first port the sandbox exposes.
+ */
+export function resolveBridgePort({
+  sandboxSession,
+  portOverride,
+}: {
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
+  portOverride: number | undefined;
+}): number {
+  if (portOverride !== undefined) return portOverride;
+  if ('ports' in sandboxSession && sandboxSession.ports.length > 0) {
+    return sandboxSession.ports[0];
+  }
+  throw new HarnessCapabilityUnsupportedError({
+    message:
+      'The harness needs a TCP port exposed by the sandbox. ' +
+      'Create the sandbox with `ports: [<port>]` or configure the harness `port` setting.',
+  });
+}
+
+/**
+ * Resolves the host-reachable WebSocket endpoint for a bridge port and
+ * authenticates it with the bridge token.
+ *
+ * A `portEndpoint` setting takes precedence and is used as-is regardless of
+ * `port`, so it must point at the port the bridge actually listens on.
+ */
+export async function resolveBridgeEndpoint({
+  sandboxSession,
+  port,
+  portEndpointOverride,
+  token,
+}: {
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
+  port: number;
+  portEndpointOverride: HarnessV1PortEndpoint | undefined;
+  token: string;
+}): Promise<HarnessV1PortEndpoint> {
+  let endpoint: HarnessV1PortEndpoint;
+  if (portEndpointOverride != null) {
+    endpoint = portEndpointOverride;
+  } else if ('getPortEndpoint' in sandboxSession) {
+    endpoint = await sandboxSession.getPortEndpoint({ port, protocol: 'ws' });
+  } else {
+    throw createMissingPortEndpointError();
+  }
+  return withBridgeToken({ endpoint, token });
+}
+
+function createMissingPortEndpointError(): HarnessCapabilityUnsupportedError {
+  return new HarnessCapabilityUnsupportedError({
+    message:
+      'The harness requires an explicit `portEndpoint` setting when using a basic sandbox session.',
+  });
+}

package/src/utils/bridge-web-socket.ts

@@ -0,0 +1,286 @@
+import { safeParseJSON } from '@ai-sdk/provider-utils';
+import type { WebSocket } from 'ws';
+import type { z } from 'zod/v4';
+import { HarnessError } from '../errors/harness-error';
+import type { HarnessV1PortEndpoint } from '../v1';
+import { harnessV1BridgeHelloSchema } from '../v1/harness-v1-bridge-protocol';
+import type { SandboxChannelConnectOptions } from './sandbox-channel';
+import { sleep } from './sleep';
+
+export type BridgeHello = z.infer<typeof harnessV1BridgeHelloSchema>;
+
+export interface CreateBridgeWebSocketConnectOptions {
+  /** Bridge endpoint, already authenticated with the bridge token. */
+  endpoint: HarnessV1PortEndpoint;
+
+  /**
+   * `WebSocket` class from the `ws` package. Passed in by the adapter because
+   * `ws` is an optional peer dependency of `@ai-sdk/harness`.
+   */
+  webSocketConstructor: typeof WebSocket;
+
+  /**
+   * Retry budget in milliseconds for the channel's initial open (connect
+   * reason `'open'`). Omit for a single attempt. Reconnects always make a
+   * single attempt, because the channel retries them itself.
+   */
+  openRetryTimeoutMs?: number;
+
+  /**
+   * Abort signal that additionally cancels the channel's initial open, e.g.
+   * the abort signal of the harness start call. Not applied to reconnects.
+   */
+  startAbortSignal?: AbortSignal;
+
+  /** Called with the `bridge-hello` frame after every successful connect. */
+  onHello?: (hello: BridgeHello) => void;
+}
+
+const OPEN_TIMEOUT_MS = 10_000;
+const HELLO_TIMEOUT_MS = 5_000;
+const UNAUTHORIZED_CLOSE_CODE = 1008;
+
+/**
+ * Creates the `connect` function for a bridge `SandboxChannel`.
+ *
+ * A connection only counts as established once the socket is open and the
+ * bridge has sent `bridge-hello`. Some sandbox runtimes complete the host-side
+ * WebSocket upgrade before the connection reaches the bridge process, and
+ * frames sent in that gap are dropped. The bridge sends `bridge-hello` the
+ * instant it accepts a connection, and sends nothing else until the host sends
+ * `start` or `resume`, so no frame is lost between the handshake and the
+ * channel wiring the socket.
+ */
+export function createBridgeWebSocketConnect({
+  endpoint,
+  webSocketConstructor,
+  openRetryTimeoutMs,
+  startAbortSignal,
+  onHello,
+}: CreateBridgeWebSocketConnectOptions): (
+  options: SandboxChannelConnectOptions,
+) => Promise<WebSocket> {
+  return async ({ abortSignal, reason }) => {
+    const isInitialOpen = reason === 'open';
+    const connectAbortSignal =
+      isInitialOpen && startAbortSignal != null
+        ? AbortSignal.any([abortSignal, startAbortSignal])
+        : abortSignal;
+
+    const { ws, hello } =
+      isInitialOpen && openRetryTimeoutMs != null
+        ? await openBridgeWebSocketWithRetry({
+            endpoint,
+            webSocketConstructor,
+            abortSignal: connectAbortSignal,
+            retryTimeoutMs: openRetryTimeoutMs,
+          })
+        : await openBridgeWebSocket({
+            endpoint,
+            webSocketConstructor,
+            abortSignal: connectAbortSignal,
+            openTimeoutMs: OPEN_TIMEOUT_MS,
+            getHelloTimeoutMs: () => HELLO_TIMEOUT_MS,
+          });
+    onHello?.(hello);
+    return ws;
+  };
+}
+
+class BridgeWebSocketUnauthorizedError extends Error {}
+
+async function openBridgeWebSocketWithRetry({
+  endpoint,
+  webSocketConstructor,
+  abortSignal,
+  retryTimeoutMs,
+}: {
+  endpoint: HarnessV1PortEndpoint;
+  webSocketConstructor: typeof WebSocket;
+  abortSignal: AbortSignal;
+  retryTimeoutMs: number;
+}): Promise<{ ws: WebSocket; hello: BridgeHello }> {
+  const deadline = Date.now() + retryTimeoutMs;
+  let attempt = 0;
+  let lastError: unknown;
+
+  while (!abortSignal.aborted && Date.now() < deadline) {
+    attempt++;
+    try {
+      const remaining = Math.max(1, deadline - Date.now());
+      return await openBridgeWebSocket({
+        endpoint,
+        webSocketConstructor,
+        abortSignal,
+        openTimeoutMs: Math.min(OPEN_TIMEOUT_MS, remaining),
+        getHelloTimeoutMs: () =>
+          Math.min(HELLO_TIMEOUT_MS, Math.max(1, deadline - Date.now())),
+      });
+    } catch (error) {
+      if (abortSignal.aborted) throw getAbortReason({ abortSignal });
+      if (error instanceof BridgeWebSocketUnauthorizedError) throw error;
+      lastError = error;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await sleep({
+        ms: Math.min(250 * attempt, 1_000, remaining),
+        abortSignal,
+      });
+    }
+  }
+
+  if (abortSignal.aborted) throw getAbortReason({ abortSignal });
+
+  throw new HarnessError({
+    message: `The harness bridge did not complete the WebSocket handshake within ${retryTimeoutMs}ms after ${attempt} attempt(s).`,
+    cause: lastError,
+  });
+}
+
+function openBridgeWebSocket({
+  endpoint,
+  webSocketConstructor,
+  abortSignal,
+  openTimeoutMs,
+  getHelloTimeoutMs,
+}: {
+  endpoint: HarnessV1PortEndpoint;
+  webSocketConstructor: typeof WebSocket;
+  abortSignal: AbortSignal;
+  openTimeoutMs: number;
+  getHelloTimeoutMs: () => number;
+}): Promise<{ ws: WebSocket; hello: BridgeHello }> {
+  return new Promise((resolve, reject) => {
+    if (abortSignal.aborted) {
+      reject(getAbortReason({ abortSignal }));
+      return;
+    }
+
+    const ws = new webSocketConstructor(endpoint.url, {
+      headers: endpoint.headers == null ? undefined : { ...endpoint.headers },
+    });
+    let opened = false;
+    let hello: BridgeHello | undefined;
+    let settled = false;
+    let openTimer: ReturnType<typeof setTimeout> | undefined;
+    let helloTimer: ReturnType<typeof setTimeout> | undefined;
+
+    const cleanup = () => {
+      clearTimeout(openTimer);
+      clearTimeout(helloTimer);
+      ws.off('open', onOpen);
+      ws.off('message', onMessage);
+      ws.off('close', onClose);
+      ws.off('error', onError);
+      abortSignal.removeEventListener('abort', onAbort);
+    };
+    const fail = (error: unknown) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      /*
+       * Terminating a socket that is still connecting makes `ws` emit an
+       * `error` event. Keep a no-op listener so that event cannot surface as
+       * an unhandled error and the original failure reason is preserved.
+       */
+      ws.on('error', () => {});
+      try {
+        ws.terminate();
+      } catch {
+        try {
+          ws.close();
+        } catch {
+          // best-effort
+        }
+      }
+      reject(error);
+    };
+    const tryResolve = () => {
+      if (settled || !opened || hello == null) return;
+      settled = true;
+      cleanup();
+      resolve({ ws, hello });
+    };
+    const onOpen = () => {
+      opened = true;
+      clearTimeout(openTimer);
+      const helloTimeoutMs = getHelloTimeoutMs();
+      helloTimer = setTimeout(
+        () =>
+          fail(
+            new Error(
+              `The harness bridge did not send bridge-hello within ${helloTimeoutMs}ms.`,
+            ),
+          ),
+        helloTimeoutMs,
+      );
+      unrefTimer(helloTimer);
+      tryResolve();
+    };
+    const onMessage = (raw: unknown) => {
+      void (async () => {
+        const parsed = await safeParseJSON({
+          text: webSocketMessageToString(raw),
+          schema: harnessV1BridgeHelloSchema,
+        });
+        if (!parsed.success || settled) return;
+        hello = parsed.value;
+        tryResolve();
+      })();
+    };
+    const onClose = (code: number) => {
+      fail(
+        code === UNAUTHORIZED_CLOSE_CODE
+          ? new BridgeWebSocketUnauthorizedError(
+              `The harness bridge rejected the WebSocket connection as unauthorized (code ${code}).`,
+            )
+          : new Error(
+              `The harness bridge closed the WebSocket (code ${code}) before sending bridge-hello.`,
+            ),
+      );
+    };
+    const onError = (error: Error) => fail(error);
+    const onAbort = () => fail(getAbortReason({ abortSignal }));
+
+    ws.on('open', onOpen);
+    ws.on('message', onMessage);
+    ws.on('close', onClose);
+    ws.on('error', onError);
+    abortSignal.addEventListener('abort', onAbort, { once: true });
+    openTimer = setTimeout(
+      () =>
+        fail(
+          new Error(
+            `The harness bridge WebSocket did not open within ${openTimeoutMs}ms.`,
+          ),
+        ),
+      openTimeoutMs,
+    );
+    unrefTimer(openTimer);
+  });
+}
+
+function getAbortReason({
+  abortSignal,
+}: {
+  abortSignal: AbortSignal;
+}): unknown {
+  return abortSignal.reason ?? new Error('WebSocket connection aborted');
+}
+
+function unrefTimer(timer: ReturnType<typeof setTimeout>): void {
+  (timer as { unref?: () => void }).unref?.();
+}
+
+function webSocketMessageToString(raw: unknown): string {
+  if (typeof raw === 'string') return raw;
+  if (Buffer.isBuffer(raw)) return raw.toString('utf8');
+  if (Array.isArray(raw)) return Buffer.concat(raw).toString('utf8');
+  if (raw instanceof ArrayBuffer) return Buffer.from(raw).toString('utf8');
+  if (ArrayBuffer.isView(raw)) {
+    return Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString(
+      'utf8',
+    );
+  }
+  return String(raw);
+}

package/src/utils/index.ts

@@ -58,7 +58,17 @@ export {
   type WaitForBridgeReadyOptions,
   type WaitForBridgeReadyResult,
 } from './bridge-ready';
-export { createBridgeToken, withBridgeToken } from './bridge-token';
+export { createBridgeToken } from './bridge-token';
+export {
+  resolveBridgeEndpoint,
+  resolveBridgePort,
+  validateBridgeSandboxSettings,
+} from './bridge-endpoint';
+export {
+  createBridgeWebSocketConnect,
+  type BridgeHello,
+  type CreateBridgeWebSocketConnectOptions,
+} from './bridge-web-socket';
 export { createReadBridgeAsset } from './bridge-asset';
 export {
   createBridgeErrorHandler,

package/src/utils/sandbox-channel.ts

@@ -36,6 +36,13 @@ export interface SandboxChannelReconnectOptions {
 
 export interface SandboxChannelConnectOptions {
   readonly abortSignal: AbortSignal;
+
+  /**
+   * Why the channel is connecting: `'open'` for the initial
+   * {@link SandboxChannel.open} call, `'reconnect'` for an attempt to recover
+   * from a transient disconnect.
+   */
+  readonly reason: 'open' | 'reconnect';
 }
 
 export interface SandboxChannelOptions<TOut> {
@@ -296,6 +303,7 @@ export class SandboxChannel<
     try {
       const ws = await this.connect({
         abortSignal: abortController.signal,
+        reason: 'open',
       });
       this.wire(ws);
       this.ws = ws;
@@ -528,6 +536,7 @@ export class SandboxChannel<
         try {
           const ws = await this.connect({
             abortSignal: abortController.signal,
+            reason: 'reconnect',
           });
           if (this.terminal || this.closing) {
             closeWebSocket({ ws });
@@ -590,10 +599,11 @@ export class SandboxChannel<
 
   private connect({
     abortSignal,
+    reason,
   }: SandboxChannelConnectOptions): Promise<WebSocket> {
     return awaitWebSocketConnection({
       connection: Promise.resolve().then(() =>
-        this.connectThunk({ abortSignal }),
+        this.connectThunk({ abortSignal, reason }),
       ),
       abortSignal,
     });