@ai-sdk/harness-claude-code 1.0.80 → 1.0.82

package/src/bridge/index.ts

@@ -8,6 +8,8 @@ import {
   runBridge,
   type BridgeEvent,
   type BridgeTurn,
+  type Experimental_BridgeUserMessage,
+  type Experimental_BridgeUserMessageQueue,
 } from '@ai-sdk/harness/bridge';
 import { createCompactionLatch } from './compaction-latch';
 import type { StartMessage } from '../claude-code-bridge-protocol';
@@ -314,7 +316,7 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
 
   const queryInput = createQueryInput({
     initialUserMessage: start.prompt,
-    pendingUserMessages: turn.pendingUserMessages,
+    userMessages: turn.experimental_userMessages,
     abortSignal: abortCtl.signal,
   });
   const skillsOption = toClaudeSkillsOption(start.skills);
@@ -419,6 +421,10 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
 
       const type = msg.type;
 
+      if (type === 'command_lifecycle') {
+        queryInput.handleLifecycle(msg);
+      }
+
       emitStreamEvent(msg);
 
       if (type === 'result') {
@@ -430,7 +436,7 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
           }
           const usage = msg.usage ?? msg.message?.usage;
           const harnessUsage = mapUsage(usage);
-          if (harnessUsage) turnUsage = harnessUsage;
+          if (harnessUsage) turnUsage = addUsage(turnUsage, harnessUsage);
           if (typeof msg.total_cost_usd === 'number') {
             totalCostUsd = (totalCostUsd ?? 0) + msg.total_cost_usd;
           }
@@ -455,8 +461,11 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
               usage: harnessUsage ?? streamEventState.pendingStepUsage,
             });
           }
-          queryInput.close();
-          break;
+          queryInput.observeResult();
+          if (!queryInput.hasActiveUserMessages()) {
+            queryInput.close();
+            break;
+          }
         } else {
           emitTerminalError(
             (Array.isArray(msg.errors) ? msg.errors.join('\n') : undefined) ||
@@ -467,6 +476,11 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
         }
         continue;
       }
+
+      if (queryInput.hasObservedResult && !queryInput.hasActiveUserMessages()) {
+        queryInput.close();
+        break;
+      }
     }
   } catch (err) {
     if (!(abortCtl.signal.aborted && emittedTerminalError)) {
@@ -492,59 +506,122 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
 
 function createQueryInput({
   initialUserMessage,
-  pendingUserMessages,
+  userMessages,
   abortSignal,
 }: {
   initialUserMessage: string;
-  pendingUserMessages: string[];
+  userMessages: Experimental_BridgeUserMessageQueue;
   abortSignal: AbortSignal;
 }): {
   input: AsyncIterable<unknown>;
-  close(): void;
+  close(error?: unknown): void;
+  handleLifecycle(message: ClaudeMessage): void;
+  hasActiveUserMessages(): boolean;
+  observeResult(): void;
+  readonly hasObservedResult: boolean;
 } {
   let closed = false;
-  const close = (): void => {
+  let observedResult = false;
+  const submittedMessages = new Map<string, Experimental_BridgeUserMessage>();
+  const close = (error?: unknown): void => {
+    if (closed) return;
     closed = true;
+    userMessages.close(error);
   };
   if (abortSignal.aborted) {
-    close();
+    close(abortSignal.reason);
   } else {
-    abortSignal.addEventListener('abort', close, { once: true });
+    abortSignal.addEventListener('abort', () => close(abortSignal.reason), {
+      once: true,
+    });
   }
 
-  const toUserMessage = (text: string): unknown => ({
+  const toUserMessage = (options: {
+    text: string;
+    messageId: string;
+    priority?: 'next';
+  }): unknown => ({
     type: 'user',
     message: {
       role: 'user',
-      content: [{ type: 'text', text }],
+      content: [{ type: 'text', text: options.text }],
     },
+    parent_tool_use_id: null,
+    uuid: options.messageId,
+    ...(options.priority == null ? {} : { priority: options.priority }),
   });
 
+  const messageIterator = userMessages[Symbol.asyncIterator]();
+
   return {
     close,
+    handleLifecycle: message => {
+      const lifecycle = message as ClaudeMessage & {
+        command_uuid?: string;
+        state?: 'queued' | 'started' | 'completed' | 'cancelled' | 'discarded';
+      };
+      if (lifecycle.command_uuid == null || lifecycle.state == null) return;
+      const submitted = submittedMessages.get(lifecycle.command_uuid);
+      if (submitted == null) return;
+      if (lifecycle.state === 'queued' || lifecycle.state === 'started') {
+        submitted.accept();
+        return;
+      }
+      if (lifecycle.state === 'cancelled' || lifecycle.state === 'discarded') {
+        submitted.reject(
+          new Error(`Claude Code ${lifecycle.state} the user message.`),
+        );
+      }
+      submittedMessages.delete(lifecycle.command_uuid);
+    },
+    hasActiveUserMessages: () =>
+      submittedMessages.size > 0 || userMessages.pendingCount > 0,
+    observeResult: () => {
+      observedResult = true;
+    },
+    get hasObservedResult() {
+      return observedResult;
+    },
     input: {
       [Symbol.asyncIterator]() {
         let sentInitial = false;
         return {
           async next() {
-            // eslint-disable-next-line no-unmodified-loop-condition
-            while (!closed && !abortSignal.aborted) {
-              if (!sentInitial) {
-                sentInitial = true;
-                return {
-                  value: toUserMessage(initialUserMessage),
-                  done: false,
-                };
-              }
-              if (pendingUserMessages.length > 0) {
-                return {
-                  value: toUserMessage(pendingUserMessages.shift()!),
-                  done: false,
-                };
-              }
-              await new Promise(resolve => setTimeout(resolve, 50));
+            if (closed || abortSignal.aborted) {
+              return {
+                value: undefined,
+                done: true,
+              } as IteratorResult<unknown>;
+            }
+            if (!sentInitial) {
+              sentInitial = true;
+              return {
+                value: toUserMessage({
+                  text: initialUserMessage,
+                  messageId: randomUUID(),
+                }),
+                done: false,
+              };
             }
-            return { value: undefined, done: true } as IteratorResult<unknown>;
+            const nextMessage = await messageIterator.next();
+            if (nextMessage.done) {
+              return {
+                value: undefined,
+                done: true,
+              } as IteratorResult<unknown>;
+            }
+            submittedMessages.set(
+              nextMessage.value.messageId,
+              nextMessage.value,
+            );
+            return {
+              value: toUserMessage({
+                text: nextMessage.value.text,
+                messageId: nextMessage.value.messageId,
+                priority: 'next',
+              }),
+              done: false,
+            };
           },
         };
       },
@@ -552,6 +629,35 @@ function createQueryInput({
   };
 }
 
+function addUsage(
+  total: Record<string, unknown> | undefined,
+  usage: Record<string, unknown>,
+): Record<string, unknown> {
+  if (total == null) return usage;
+  const result: Record<string, unknown> = { ...total };
+  for (const [key, value] of Object.entries(usage)) {
+    const previous = result[key];
+    if (typeof value === 'number' && typeof previous === 'number') {
+      result[key] = previous + value;
+    } else if (
+      value != null &&
+      previous != null &&
+      typeof value === 'object' &&
+      typeof previous === 'object' &&
+      !Array.isArray(value) &&
+      !Array.isArray(previous)
+    ) {
+      result[key] = addUsage(
+        previous as Record<string, unknown>,
+        value as Record<string, unknown>,
+      );
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 function parseArgs(args: string[]): {
   workdir?: string;
   bridgeStateDir?: string;

package/src/claude-code-harness.ts

@@ -21,12 +21,15 @@ import {
 } from '@ai-sdk/harness';
 import {
   classifyDiskLog,
+  experimental_createBridgeUserMessageSubmitter,
   createBridgeErrorHandler,
   createBridgeStartupError,
   drainBridgeProcessStream,
   forwardBridgeProcessStream,
+  getRestrictedSandboxSession,
   markBridgeStarting,
   maskSandboxCredentials,
+  resolveSandboxDefaultWorkingDirectory,
   resolveSandboxHomeDir,
   SandboxChannel,
   shellQuote,
@@ -37,7 +40,7 @@ import {
 import {
   safeParseJSON,
   tool,
-  type Experimental_SandboxSession,
+  type Experimental_SandboxSession as SandboxSession,
   type Experimental_SandboxProcess,
 } from '@ai-sdk/provider-utils';
 import { WebSocket } from 'ws';
@@ -108,6 +111,11 @@ export type ClaudeCodeHarnessSettings = {
    * is reserved for something else.
    */
   readonly port?: number;
+  /**
+   * Override the host endpoint used to connect to the sandbox bridge. Required
+   * together with `port` when using a basic sandbox session.
+   */
+  readonly portEndpoint?: HarnessV1PortEndpoint;
   /** Maximum milliseconds to wait for the bridge to advertise its port. Defaults to 120000. */
   readonly startupTimeoutMs?: number;
   /**
@@ -813,13 +821,36 @@ export function createClaudeCode(
     getBootstrap: getClaudeCodeBootstrap,
     doStart: async startOpts => {
       const sandboxSession = startOpts.sandboxSession;
+      const toolSafeSandboxSession =
+        getRestrictedSandboxSession(sandboxSession);
+      const sandboxId = 'id' in sandboxSession ? sandboxSession.id : undefined;
+      validateBasicSandboxSettings({
+        sandboxSession,
+        port: settings.port,
+        portEndpoint: settings.portEndpoint,
+      });
+      if (settings.mintBridgeToken != null && sandboxId == null) {
+        throw new HarnessCapabilityUnsupportedError({
+          harnessId: 'claude-code',
+          message:
+            'The Claude Code harness cannot use `mintBridgeToken` with a sandbox session that does not expose an id.',
+        });
+      }
+      const defaultWorkingDirectory =
+        await resolveSandboxDefaultWorkingDirectory({
+          sandboxSession,
+          abortSignal: startOpts.abortSignal,
+        });
       const authenticationMode = resolveClaudeCodeAuthenticationMode(
         settings.auth,
       );
       const resolvedAuthEnvironment = resolveClaudeCodeEnv(settings.auth);
       let authEnv = resolvedAuthEnvironment;
       let sandboxTurnEnvironment = settings.env;
-      if (sandboxSession.addRequestTransformations != null) {
+      if (
+        'addRequestTransformations' in sandboxSession &&
+        sandboxSession.addRequestTransformations != null
+      ) {
         const requestTransformations = createClaudeCodeRequestTransformations(
           {
             ...resolvedAuthEnvironment,
@@ -845,10 +876,8 @@ export function createClaudeCode(
       } else {
         warnCredentialBrokeringUnavailable();
       }
-      const session = sandboxSession.restricted();
-      const sandboxId = sandboxSession.id;
       const bootstrapDir = posix.resolve(
-        sandboxSession.defaultWorkingDirectory,
+        defaultWorkingDirectory,
         BOOTSTRAP_DIR,
       );
       const lifecycleState = startOpts.continueFrom ?? startOpts.resumeFrom;
@@ -859,7 +888,7 @@ export function createClaudeCode(
         : undefined;
 
       const workDir = startOpts.sessionWorkDir;
-      const sessionDataDir = `${sandboxSession.defaultWorkingDirectory}/.agent-runs/${startOpts.sessionId}`;
+      const sessionDataDir = `${defaultWorkingDirectory}/.agent-runs/${startOpts.sessionId}`;
       const bridgeStateDir = `${sessionDataDir}/bridge`;
       const timeoutMs = settings.startupTimeoutMs ?? 120_000;
 
@@ -880,13 +909,20 @@ export function createClaudeCode(
         harnessId: 'claude-code',
         sessionId: startOpts.sessionId,
       });
+      let supportsUserMessageResponses = false;
 
       // Builds the `connect` thunk a `SandboxChannel` re-invokes on every
       // (re)connect: open the socket, then wait for `bridge-hello` so the
       // end-to-end link is proven live before any frame is sent.
       const buildConnect =
         (endpoint: HarnessV1PortEndpoint) => async (): Promise<WebSocket> => {
-          return openBridgeWebSocket({ endpoint, timeoutMs });
+          return openBridgeWebSocket({
+            endpoint,
+            timeoutMs,
+            onHello: supportsResponses => {
+              supportsUserMessageResponses = supportsResponses;
+            },
+          });
         };
 
       /*
@@ -899,9 +935,10 @@ export function createClaudeCode(
        */
       if (coords) {
         try {
-          const endpoint = await sandboxSession.getPortEndpoint({
+          const endpoint = await resolveBridgeEndpoint({
+            sandboxSession,
+            override: settings.portEndpoint,
             port: coords.port,
-            protocol: 'ws',
           });
           const attachEndpoint = withBridgeToken({
             endpoint,
@@ -938,6 +975,7 @@ export function createClaudeCode(
             builtinToolFiltering: startOpts.builtinToolFiltering,
             skills: startOpts.skills ?? [],
             mcpServers: settings.mcpServers,
+            supportsUserMessageResponses: () => supportsUserMessageResponses,
           });
         } catch {
           // Bridge no longer reachable — recover by respawning below.
@@ -958,7 +996,7 @@ export function createClaudeCode(
         : undefined;
       if (coords && isContinue) {
         const logRaw = await Promise.resolve(
-          session.readTextFile({
+          toolSafeSandboxSession.readTextFile({
             path: `${bridgeStateDir}/event-log.ndjson`,
             abortSignal: startOpts.abortSignal,
           }),
@@ -971,15 +1009,18 @@ export function createClaudeCode(
       const sandboxHomeDir =
         startOpts.skills && startOpts.skills.length > 0
           ? await resolveSandboxHomeDir({
-              sandbox: session,
+              sandbox: toolSafeSandboxSession,
               abortSignal: startOpts.abortSignal,
             })
           : undefined;
-      const port = resolveBridgePort(sandboxSession, settings.port);
+      const port = resolveBridgePort({
+        sandboxSession,
+        override: settings.port,
+      });
       const token =
         settings.mintBridgeToken == null
           ? randomBytes(32).toString('hex')
-          : settings.mintBridgeToken(sandboxId);
+          : settings.mintBridgeToken(sandboxId!);
       const env = {
         ...authEnv,
         /*
@@ -1006,7 +1047,7 @@ export function createClaudeCode(
        * spawn — `BRIDGE_CHANNEL_TOKEN` rotates per start.
        */
       if (respawnStrategy === undefined) {
-        await session.run({
+        await toolSafeSandboxSession.run({
           command: `mkdir -p ${shellQuote(workDir)} ${shellQuote(bridgeStateDir)}`,
           abortSignal: startOpts.abortSignal,
         });
@@ -1016,7 +1057,7 @@ export function createClaudeCode(
             throw new Error('Unable to resolve sandbox HOME directory.');
           }
           await writeClaudeCodeSkills({
-            sandbox: session,
+            sandbox: toolSafeSandboxSession,
             homeDir: sandboxHomeDir,
             skills: startOpts.skills,
             abortSignal: startOpts.abortSignal,
@@ -1025,13 +1066,13 @@ export function createClaudeCode(
       }
 
       await markBridgeStarting({
-        sandbox: session,
+        sandbox: toolSafeSandboxSession,
         bridgeStateDir,
         bridgeType: 'claude-code',
         abortSignal: startOpts.abortSignal,
       });
 
-      const proc = await session.spawn({
+      const proc = await toolSafeSandboxSession.spawn({
         command: `node ${shellQuote(`${bootstrapDir}/bridge.mjs`)} --workdir ${shellQuote(workDir)} --bridge-state-dir ${shellQuote(bridgeStateDir)}`,
         env,
         abortSignal: startOpts.abortSignal,
@@ -1047,7 +1088,7 @@ export function createClaudeCode(
       void bridgeStartupStderrDone;
       const { port: boundPort } = await waitForBridgeReady({
         proc,
-        sandbox: session,
+        sandbox: toolSafeSandboxSession,
         bridgeStateDir,
         bridgeType: 'claude-code',
         timeoutMs,
@@ -1071,9 +1112,10 @@ export function createClaudeCode(
       });
       void drainBridgeProcessStream(proc.stdout);
 
-      const endpoint = await sandboxSession.getPortEndpoint({
+      const endpoint = await resolveBridgeEndpoint({
+        sandboxSession,
+        override: settings.portEndpoint,
         port: boundPort,
-        protocol: 'ws',
       });
       const bridgeEndpoint = withBridgeToken({ endpoint, token });
 
@@ -1113,17 +1155,23 @@ export function createClaudeCode(
         builtinToolFiltering: startOpts.builtinToolFiltering,
         skills: startOpts.skills ?? [],
         mcpServers: settings.mcpServers,
+        supportsUserMessageResponses: () => supportsUserMessageResponses,
       });
     },
   };
 }
 
-function resolveBridgePort(
-  sandboxSession: HarnessV1NetworkSandboxSession,
-  override: number | undefined,
-): number {
+function resolveBridgePort({
+  sandboxSession,
+  override,
+}: {
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
+  override: number | undefined;
+}): number {
   if (override !== undefined) return override;
-  if (sandboxSession.ports.length > 0) return sandboxSession.ports[0];
+  if ('ports' in sandboxSession && sandboxSession.ports.length > 0) {
+    return sandboxSession.ports[0];
+  }
   throw new HarnessCapabilityUnsupportedError({
     harnessId: 'claude-code',
     message:
@@ -1132,6 +1180,52 @@ function resolveBridgePort(
   });
 }
 
+function validateBasicSandboxSettings({
+  sandboxSession,
+  port,
+  portEndpoint,
+}: {
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
+  port: number | undefined;
+  portEndpoint: HarnessV1PortEndpoint | undefined;
+}): void {
+  if ('getPortEndpoint' in sandboxSession) return;
+  if (port == null) {
+    throw new HarnessCapabilityUnsupportedError({
+      harnessId: 'claude-code',
+      message:
+        'The Claude Code harness requires an explicit `port` when using a basic sandbox session.',
+    });
+  }
+  if (portEndpoint == null) {
+    throw new HarnessCapabilityUnsupportedError({
+      harnessId: 'claude-code',
+      message:
+        'The Claude Code harness requires an explicit `portEndpoint` when using a basic sandbox session.',
+    });
+  }
+}
+
+async function resolveBridgeEndpoint({
+  sandboxSession,
+  override,
+  port,
+}: {
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
+  override: HarnessV1PortEndpoint | undefined;
+  port: number;
+}): Promise<HarnessV1PortEndpoint> {
+  if (override != null) return override;
+  if ('getPortEndpoint' in sandboxSession) {
+    return sandboxSession.getPortEndpoint({ port, protocol: 'ws' });
+  }
+  throw new HarnessCapabilityUnsupportedError({
+    harnessId: 'claude-code',
+    message:
+      'The Claude Code harness requires an explicit `portEndpoint` when using a basic sandbox session.',
+  });
+}
+
 /**
  * Materialise skill files into
  * `$HOME/.claude/skills/<name>/SKILL.md`. The `claude` CLI
@@ -1145,7 +1239,7 @@ async function writeClaudeCodeSkills({
   skills,
   abortSignal,
 }: {
-  sandbox: Experimental_SandboxSession;
+  sandbox: SandboxSession;
   homeDir: string;
   skills: ReadonlyArray<HarnessV1Skill>;
   abortSignal?: AbortSignal;
@@ -1178,10 +1272,12 @@ function openWebSocketAndWaitForBridgeHello({
   endpoint,
   openTimeoutMs,
   getHelloTimeoutMs,
+  onHello,
 }: {
   endpoint: HarnessV1PortEndpoint;
   openTimeoutMs: number;
   getHelloTimeoutMs: () => number;
+  onHello: (supportsUserMessageResponses: boolean) => void;
 }): Promise<WebSocket> {
   return new Promise<WebSocket>((resolve, reject) => {
     const ws = new WebSocket(endpoint.url, {
@@ -1253,6 +1349,12 @@ function openWebSocketAndWaitForBridgeHello({
           !Array.isArray(value) &&
           (value as { type?: unknown }).type === 'bridge-hello'
         ) {
+          const capabilities = (
+            value as {
+              capabilities?: { experimental_userMessageResponses?: unknown };
+            }
+          ).capabilities;
+          onHello(capabilities?.experimental_userMessageResponses === true);
           sawBridgeHello = true;
           tryResolve();
         }
@@ -1280,9 +1382,11 @@ function openWebSocketAndWaitForBridgeHello({
 async function openBridgeWebSocket({
   endpoint,
   timeoutMs,
+  onHello,
 }: {
   endpoint: HarnessV1PortEndpoint;
   timeoutMs: number;
+  onHello: (supportsUserMessageResponses: boolean) => void;
 }): Promise<WebSocket> {
   const deadline = Date.now() + timeoutMs;
   let attempt = 0;
@@ -1297,6 +1401,7 @@ async function openBridgeWebSocket({
         openTimeoutMs: Math.min(10_000, remaining),
         getHelloTimeoutMs: () =>
           Math.min(5_000, Math.max(1, deadline - Date.now())),
+        onHello,
       });
     } catch (err) {
       lastError = err;
@@ -1368,6 +1473,7 @@ function createSession({
   builtinToolFiltering,
   skills,
   mcpServers,
+  supportsUserMessageResponses,
 }: {
   sessionId: string;
   channel: ClaudeCodeChannel;
@@ -1383,12 +1489,13 @@ function createSession({
   rerunContinue: boolean;
   bridgePort: number;
   bridgeToken: string;
-  sandboxId: string;
+  sandboxId: string | undefined;
   debug: HarnessV1DebugConfig | undefined;
   permissionMode: HarnessV1PermissionMode | undefined;
   builtinToolFiltering: HarnessV1BuiltinToolFiltering | undefined;
   skills: ReadonlyArray<HarnessV1Skill>;
   mcpServers: Record<string, unknown> | undefined;
+  supportsUserMessageResponses: () => boolean;
 }): HarnessV1Session {
   let stopped = false;
   let stopPromise: Promise<void> | undefined;
@@ -1417,7 +1524,13 @@ function createSession({
       pendingResolve = resolve;
       pendingReject = reject;
     });
-
+    const userMessageSubmitter = supportsUserMessageResponses()
+      ? experimental_createBridgeUserMessageSubmitter({
+          send: message => channel.send(message),
+          onResponse: listener => channel.on('user-message-response', listener),
+          onReconnect: listener => channel.onReconnect(listener),
+        })
+      : undefined;
     const unsubs: Array<() => void> = [];
     const forward = (event: HarnessV1StreamPart) => {
       try {
@@ -1429,12 +1542,14 @@ function createSession({
     const settleSuccess = () => {
       if (isSettled) return;
       isSettled = true;
+      userMessageSubmitter?.close();
       for (const u of unsubs) u();
       pendingResolve!();
     };
     const settleError = (err: unknown) => {
       if (isSettled) return;
       isSettled = true;
+      userMessageSubmitter?.close(err);
       for (const u of unsubs) u();
       pendingReject!(err);
     };
@@ -1528,9 +1643,13 @@ function createSession({
           reason: input.reason,
         });
       },
-      submitUserMessage: async text => {
-        channel.send({ type: 'user-message', text });
-      },
+      ...(userMessageSubmitter == null
+        ? {}
+        : {
+            submitUserMessage: async (text: string) => {
+              await userMessageSubmitter.submit(text);
+            },
+          }),
       done,
     };
   };
@@ -1689,7 +1808,7 @@ function createSession({
             port: bridgePort,
             token: bridgeToken,
             lastSeenEventId,
-            sandboxId,
+            ...(sandboxId == null ? {} : { sandboxId }),
           },
         },
       };
@@ -1827,7 +1946,7 @@ function createSession({
             port: bridgePort,
             token: bridgeToken,
             lastSeenEventId,
-            sandboxId,
+            ...(sandboxId == null ? {} : { sandboxId }),
           },
         },
       };