@ai-sdk/harness 1.0.71 → 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/errors/harness-capability-unsupported-error.ts

@@ -8,8 +8,8 @@ const symbol = Symbol.for(marker);
 /**
  * Thrown when a caller asks the harness to do something the adapter (or the
  * supplied sandbox) does not support, e.g. requesting manual compaction from
- * an adapter that only auto-compacts, or invoking `getPortUrl` on a sandbox
- * that does not expose one.
+ * an adapter that only auto-compacts, or invoking `getPortEndpoint` on a
+ * sandbox that does not expose one.
  *
  * The caller supplies the full human-readable message. Optional `harnessId`
  * is recorded as structured context for tooling.

package/src/utils/index.ts

@@ -6,6 +6,11 @@ export {
 } from './sandbox-channel';
 export { classifyDiskLog, type DiskLogRecoveryMode } from './classify-disk-log';
 export { getAiGatewayAuthFromEnv } from './ai-gateway-auth';
+export {
+  createCredentialRequestTransformation,
+  maskSandboxCredentials,
+  warnCredentialBrokeringUnavailable,
+} from './sandbox-credential-brokering';
 export { resolveSandboxHomeDir } from './sandbox-home-dir';
 export { shellQuote } from './shell-quote';
 export {

package/src/utils/sandbox-credential-brokering.ts

@@ -0,0 +1,41 @@
+import type { HarnessV1RequestTransformation } from '../v1';
+
+export function warnCredentialBrokeringUnavailable(): void {
+  console.warn(
+    'The sandbox implementation does not support configuring request transformations, so credential brokering does not work. Falling back to less secure credential forwarding.',
+  );
+}
+
+export function maskSandboxCredentials({
+  environment,
+  credentialEnvironmentVariables,
+}: {
+  environment: Readonly<Record<string, string>>;
+  credentialEnvironmentVariables: ReadonlyArray<string>;
+}): Record<string, string> {
+  const maskedEnvironment = { ...environment };
+  for (const name of credentialEnvironmentVariables) {
+    if (maskedEnvironment[name] != null) {
+      maskedEnvironment[name] = name;
+    }
+  }
+  return maskedEnvironment;
+}
+
+export function createCredentialRequestTransformation({
+  baseUrl,
+  headers,
+}: {
+  baseUrl: string;
+  headers: Readonly<Record<string, string>>;
+}): HarnessV1RequestTransformation {
+  const url = new URL(baseUrl);
+  const pathname = url.pathname.replace(/\/+$/, '');
+  return {
+    match: {
+      host: url.hostname,
+      ...(pathname.length === 0 ? {} : { path: { startsWith: pathname } }),
+    },
+    transform: { headers },
+  };
+}

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-network-sandbox-session.ts

@@ -1,5 +1,14 @@
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
 
+/**
+ * Connection details for a sandbox-exposed port. Headers are scoped to the
+ * returned URL and must be included when opening the connection.
+ */
+export type HarnessV1PortEndpoint = {
+  readonly url: string;
+  readonly headers?: Readonly<Record<string, string>>;
+};
+
 /**
  * Network sandbox session returned by `HarnessV1SandboxProvider.createSession()`. The
  * harness keeps this for the lifetime of a session. It is itself a
@@ -8,8 +17,8 @@ import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/prov
  *
  * Code that should only touch the filesystem and spawn processes receives the
  * reduced view from {@link HarnessV1NetworkSandboxSession.restricted}, never the
- * network sandbox session itself — so it cannot stop the sandbox or change its
- * network policy.
+ * network sandbox session itself — so it cannot stop the sandbox, change
+ * network access, or transform requests.
  */
 export interface HarnessV1NetworkSandboxSession extends SandboxSession {
   /**
@@ -36,13 +45,23 @@ export interface HarnessV1NetworkSandboxSession extends SandboxSession {
    */
   readonly defaultWorkingDirectory: string;
 
-  /** Ports the sandbox exposes; resolvable to public URLs via `getPortUrl`. */
+  /** Ports the sandbox exposes; resolvable via `getPortEndpoint`. */
   readonly ports: ReadonlyArray<number>;
 
   /**
-   * Resolve a publicly-reachable URL for a sandbox-exposed port. Bridge-backed
+   * Resolve the connection details for a sandbox-exposed port. Bridge-backed
    * adapters call this to open their WebSocket to the in-sandbox bridge.
    */
+  readonly getPortEndpoint: (options: {
+    port: number;
+    protocol?: 'http' | 'https' | 'ws';
+  }) => PromiseLike<HarnessV1PortEndpoint>;
+
+  /**
+   * Resolve a publicly-reachable URL for a sandbox-exposed port.
+   *
+   * @deprecated Use `getPortEndpoint` instead.
+   */
   readonly getPortUrl: (options: {
     port: number;
     protocol?: 'http' | 'https' | 'ws';
@@ -68,6 +87,29 @@ export interface HarnessV1NetworkSandboxSession extends SandboxSession {
     policy: HarnessV1NetworkPolicy,
   ) => PromiseLike<void>;
 
+  /**
+   * Replace the sandbox's outbound request-transformation rules. Optional —
+   * implementations expose this only when credentials can be injected outside
+   * the sandbox security boundary. Calling this method assumes authority over
+   * the complete transformation set; harness adapters should normally use
+   * `addRequestTransformations` instead. Adapters may preserve legacy
+   * credential-forwarding behavior when additive request transformations are
+   * unavailable.
+   */
+  readonly setRequestTransformations?: (
+    transformations: ReadonlyArray<HarnessV1RequestTransformation>,
+  ) => PromiseLike<void>;
+
+  /**
+   * Add outbound request-transformation rules without replacing rules already
+   * managed by the sandbox session. Optional for the same reason as
+   * `setRequestTransformations`. Harness adapters should use this additive
+   * capability unless they explicitly own the complete transformation set.
+   */
+  readonly addRequestTransformations?: (
+    transformations: ReadonlyArray<HarnessV1RequestTransformation>,
+  ) => PromiseLike<void>;
+
   /**
    * Replace the set of ports exposed by the sandbox. Full-replacement
    * semantics: ports omitted from the array are deregistered. Optional —
@@ -86,7 +128,8 @@ export interface HarnessV1NetworkSandboxSession extends SandboxSession {
    *
    * The returned object points at exactly the same underlying sandbox
    * resource as the network sandbox session it was produced from; it is only a
-   * narrower surface over the same resource, not a separate sandbox.
+   * narrower surface over the same resource, not a separate sandbox. In
+   * particular, it cannot mutate network access or request transformations.
    */
   readonly restricted: () => SandboxSession;
 }
@@ -121,3 +164,42 @@ export type HarnessV1NetworkPolicy =
       allowedCIDRs: ReadonlyArray<string>;
       deniedCIDRs?: ReadonlyArray<string>;
     };
+
+type HarnessV1RequestTransformationPathMatcher =
+  | { exact: string }
+  | { startsWith: string }
+  | { regex: string };
+
+type HarnessV1RequestTransformationKeyValuePartMatcher =
+  | { exact: string }
+  | { startsWith: string }
+  | { regex: string };
+
+type HarnessV1RequestTransformationKeyValueMatcher = {
+  readonly key?: HarnessV1RequestTransformationKeyValuePartMatcher;
+  readonly value?: HarnessV1RequestTransformationKeyValuePartMatcher;
+};
+
+/**
+ * Outbound HTTPS request transformation applied outside the sandbox security
+ * boundary. The host is part of the match so each rule is self-contained and
+ * several rules, including several for the same host, can be installed at
+ * once.
+ *
+ * Credential values belong in `transform.headers`, while the sandbox process
+ * receives only a non-secret placeholder. Implementations must overwrite
+ * matching request headers after the request leaves the sandbox rather than
+ * making transformed values available inside it.
+ */
+export type HarnessV1RequestTransformation = {
+  readonly match: {
+    readonly host: string;
+    readonly path?: HarnessV1RequestTransformationPathMatcher;
+    readonly method?: ReadonlyArray<string>;
+    readonly queryString?: ReadonlyArray<HarnessV1RequestTransformationKeyValueMatcher>;
+    readonly headers?: ReadonlyArray<HarnessV1RequestTransformationKeyValueMatcher>;
+  };
+  readonly transform: {
+    readonly headers: Readonly<Record<string, string>>;
+  };
+};

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,
@@ -78,8 +79,10 @@ export type HarnessV1StartOptions = {
    * 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
-   * (`getPortUrl`, `ports`, `setNetworkPolicy`) for bridge wiring. Adapters
-   * must not call `stop()` themselves; the agent does that during cleanup.
+   * (`getPortEndpoint`, `ports`, `setNetworkPolicy`,
+   * `setRequestTransformations`, `addRequestTransformations`) for bridge
+   * wiring. Adapters must not call `stop()` themselves; the agent does that
+   * during cleanup.
    */
   readonly sandboxSession: HarnessV1NetworkSandboxSession;
 
@@ -103,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
@@ -142,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,
@@ -36,6 +43,8 @@ export type {
 export type {
   HarnessV1NetworkPolicy,
   HarnessV1NetworkSandboxSession,
+  HarnessV1PortEndpoint,
+  HarnessV1RequestTransformation,
 } from './harness-v1-network-sandbox-session';
 export type { HarnessV1Skill } from './harness-v1-skill';
 export type { HarnessV1StreamPart } from './harness-v1-stream-part';
@@ -66,6 +75,7 @@ export {
   harnessV1BridgeInboundCommandSchemas,
   harnessV1BridgeOutboundMessageSchema,
   harnessV1BridgeReadySchema,
+  harnessV1BridgeResponseFormatSchema,
   harnessV1BridgeResumeInboundSchema,
   harnessV1BridgeSandboxLogSchema,
   harnessV1BridgeStopInboundSchema,