@ai-sdk/harness-claude-code 1.0.74 → 1.0.76

package/src/bridge/index.ts

@@ -348,6 +348,15 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
       systemPrompt: createClaudeCodeSystemPrompt(start.instructions),
       thinking: start.thinking,
       ...(start.effort !== undefined ? { effort: start.effort } : {}),
+      ...(start.responseFormat?.type === 'json' &&
+      start.responseFormat.schema != null
+        ? {
+            outputFormat: {
+              type: 'json_schema' as const,
+              schema: start.responseFormat.schema,
+            },
+          }
+        : {}),
       includePartialMessages: true,
       // The `PostCompact` hook carries the compaction summary, which the
       // `compact_boundary` system message does not. Latch it for the unified
@@ -425,6 +434,20 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
           if (typeof msg.total_cost_usd === 'number') {
             totalCostUsd = (totalCostUsd ?? 0) + msg.total_cost_usd;
           }
+          if (
+            start.responseFormat?.type === 'json' &&
+            msg.structured_output !== undefined
+          ) {
+            const id = randomUUID();
+            emit({ type: 'text-start', id });
+            emit({
+              type: 'text-delta',
+              id,
+              delta: JSON.stringify(msg.structured_output),
+            });
+            emit({ type: 'text-end', id });
+            streamEventState.stepOpen = true;
+          }
           if (streamEventState.stepOpen) {
             emitFinishStep({
               state: streamEventState,

package/src/bridge/json-schema-to-zod.ts

@@ -43,7 +43,7 @@ function toZodType(schema: JsonSchemaObject | undefined): z.ZodTypeAny {
   let zType =
     zodForConst(schema) ??
     zodForEnum(schema) ??
-    zodForNullableUnion(schema) ??
+    zodForUnion(schema) ??
     zodForType(schema);
 
   if (isNullable(schema)) zType = zType.nullable();
@@ -90,16 +90,16 @@ function zodForEnum(schema: JsonSchemaObject): z.ZodTypeAny | undefined {
   return zodForLiterals(schema.enum);
 }
 
-function zodForNullableUnion(
-  schema: JsonSchemaObject,
-): z.ZodTypeAny | undefined {
+function zodForUnion(schema: JsonSchemaObject): z.ZodTypeAny | undefined {
   const unionSchemas = schema.anyOf ?? schema.oneOf;
   if (!unionSchemas || unionSchemas.length < 2) return undefined;
 
-  const nonNullSchemas = unionSchemas.filter(item => !isNullOnlySchema(item));
-  if (nonNullSchemas.length !== 1) return undefined;
-
-  return toZodType(nonNullSchemas[0]).nullable();
+  const options = unionSchemas.map(item => toZodType(item)) as unknown as [
+    z.ZodTypeAny,
+    z.ZodTypeAny,
+    ...z.ZodTypeAny[],
+  ];
+  return z.union(options);
 }
 
 function zodForLiterals(values: JsonLiteral[]): z.ZodTypeAny {
@@ -127,19 +127,6 @@ function isNullable(schema: JsonSchemaObject): boolean {
   );
 }
 
-function isNullOnlySchema(schema: JsonSchemaObject): boolean {
-  return (
-    schema.type === 'null' ||
-    (Array.isArray(schema.type) &&
-      schema.type.length === 1 &&
-      schema.type[0] === 'null') ||
-    schema.const === null ||
-    (Array.isArray(schema.enum) &&
-      schema.enum.length === 1 &&
-      schema.enum[0] === null)
-  );
-}
-
 function isJsonSchemaObject(input: unknown): input is JsonSchemaObject {
   return input != null && typeof input === 'object' && !Array.isArray(input);
 }

package/src/claude-code-auth.ts

@@ -2,9 +2,47 @@ import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { getAiGatewayAuthFromEnv } from '@ai-sdk/harness/utils';
+import type { HarnessV1RequestTransformation } from '@ai-sdk/harness';
+import {
+  createCredentialRequestTransformation,
+  getAiGatewayAuthFromEnv,
+} from '@ai-sdk/harness/utils';
 
-export type ClaudeCodeAuthenticationMode = 'auto' | 'direct' | 'ai-gateway';
+export const CLAUDE_CODE_CREDENTIAL_ENVIRONMENT_VARIABLES = [
+  'AI_GATEWAY_API_KEY',
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_AUTH_TOKEN',
+] as const;
+
+export function createClaudeCodeRequestTransformations(
+  env: Record<string, string>,
+  auth: ClaudeCodeResolvedAuthenticationMode,
+): HarnessV1RequestTransformation[] {
+  const headers: Record<string, string> = {};
+  if (env.ANTHROPIC_API_KEY) {
+    headers['x-api-key'] = env.ANTHROPIC_API_KEY;
+  }
+  if (env.ANTHROPIC_AUTH_TOKEN) {
+    headers.Authorization = `Bearer ${env.ANTHROPIC_AUTH_TOKEN}`;
+  }
+  return Object.keys(headers).length === 0
+    ? []
+    : [
+        createCredentialRequestTransformation({
+          baseUrl:
+            auth === 'ai-gateway'
+              ? env.ANTHROPIC_BASE_URL
+              : (env.ANTHROPIC_BASE_URL ?? 'https://api.anthropic.com'),
+          headers,
+        }),
+      ];
+}
+
+export type ClaudeCodeResolvedAuthenticationMode = 'direct' | 'ai-gateway';
+
+export type ClaudeCodeAuthenticationMode =
+  | ClaudeCodeResolvedAuthenticationMode
+  | 'auto';
 
 /**
  * @deprecated Passing an object to auth options is deprecated. Use a `ClaudeCodeAuthenticationMode` string value ("auto" | "direct" | "ai-gateway") instead, and pass credentials via environment variables.
@@ -79,6 +117,21 @@ export function resolveClaudeCodeEnv(
   return pickAnthropic({ processEnv, readApiKey });
 }
 
+export function resolveClaudeCodeAuthenticationMode(
+  auth: ClaudeCodeAuthOptions | undefined,
+  processEnv: Record<string, string | undefined> = process.env,
+): ClaudeCodeResolvedAuthenticationMode {
+  if (auth === 'direct' || (typeof auth !== 'string' && auth?.anthropic)) {
+    return 'direct';
+  }
+  if (auth === 'ai-gateway' || (typeof auth !== 'string' && auth?.gateway)) {
+    return 'ai-gateway';
+  }
+  return getAiGatewayAuthFromEnv({ env: processEnv }).apiKey
+    ? 'ai-gateway'
+    : 'direct';
+}
+
 function normalizeClaudeCodeAuthToLegacyAuth(
   auth: ClaudeCodeAuthOptions | undefined,
 ): LegacyClaudeCodeAuthOptions | undefined {

package/src/claude-code-bootstrap.ts

@@ -0,0 +1,65 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import type { HarnessV1Bootstrap } from '@ai-sdk/harness';
+
+/*
+ * Bootstrap is derived state stored under the sandbox's default working
+ * directory so snapshot-capable providers can preserve the installed CLI,
+ * bridge, and recipe marker without requiring root filesystem access.
+ *
+ * The session work dir (`startOpts.sessionWorkDir`) and the bridge-state dir
+ * derived from `sandboxSession.defaultWorkingDirectory` both live under the sandbox's
+ * default working directory — the provider's persistent mount — so the
+ * workdir's CLI state (Claude's `~/.claude/projects/<dir>/*.jsonl` thread
+ * history is keyed by working directory) and the bridge state files survive
+ * both detach -> attach/replay and stop -> snapshot -> resume cycles.
+ */
+export const CLAUDE_CODE_BOOTSTRAP_DIR = '.harness-bootstrap/claude-code';
+
+let cachedBootstrap: HarnessV1Bootstrap | undefined;
+
+export async function getClaudeCodeBootstrap(): Promise<HarnessV1Bootstrap> {
+  if (cachedBootstrap != null) return cachedBootstrap;
+  const [pkg, lock, bridge] = await Promise.all([
+    readBridgeAsset('package.json'),
+    readBridgeAsset('pnpm-lock.yaml'),
+    readBridgeAsset('index.mjs'),
+  ]);
+  cachedBootstrap = {
+    harnessId: 'claude-code',
+    bootstrapDir: CLAUDE_CODE_BOOTSTRAP_DIR,
+    files: [
+      { path: `${CLAUDE_CODE_BOOTSTRAP_DIR}/package.json`, content: pkg },
+      { path: `${CLAUDE_CODE_BOOTSTRAP_DIR}/pnpm-lock.yaml`, content: lock },
+      { path: `${CLAUDE_CODE_BOOTSTRAP_DIR}/bridge.mjs`, content: bridge },
+    ],
+    commands: [
+      {
+        command: 'pnpm install --frozen-lockfile --store-dir .pnpm-store',
+      },
+      {
+        command:
+          'if [ -f node_modules/@anthropic-ai/claude-code/install.cjs ]; then node node_modules/@anthropic-ai/claude-code/install.cjs; fi && ./node_modules/.bin/claude --version',
+      },
+    ],
+  };
+  return cachedBootstrap;
+}
+
+async function readBridgeAsset(name: string): Promise<string> {
+  const candidates = [
+    new URL(`./bridge/${name}`, import.meta.url),
+    new URL(`../bridge/${name}`, import.meta.url),
+  ];
+  let lastErr: unknown;
+  for (const url of candidates) {
+    try {
+      return await readFile(fileURLToPath(url), 'utf8');
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== 'ENOENT') throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr ?? new Error(`bridge asset not found: ${name}`);
+}

package/src/claude-code-harness.ts

@@ -1,13 +1,10 @@
 import { randomBytes } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
 import { posix } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import {
   commonTool,
   harnessV1DiagnosticFromBridgeFrame,
   HarnessCapabilityUnsupportedError,
   type HarnessV1,
-  type HarnessV1Bootstrap,
   type HarnessV1BuiltinToolFiltering,
   type HarnessV1BuiltinTool,
   type HarnessV1ContinueTurnState,
@@ -15,6 +12,7 @@ import {
   type HarnessV1PermissionMode,
   type HarnessV1Prompt,
   type HarnessV1PromptControl,
+  type HarnessV1PortEndpoint,
   type HarnessV1ResumeSessionState,
   type HarnessV1NetworkSandboxSession,
   type HarnessV1Session,
@@ -28,9 +26,11 @@ import {
   drainBridgeProcessStream,
   forwardBridgeProcessStream,
   markBridgeStarting,
+  maskSandboxCredentials,
   resolveSandboxHomeDir,
   SandboxChannel,
   shellQuote,
+  warnCredentialBrokeringUnavailable,
   waitForBridgeReady,
   writeSkills as writeHarnessSkills,
 } from '@ai-sdk/harness/utils';
@@ -43,6 +43,13 @@ import {
 import { WebSocket } from 'ws';
 import { z } from 'zod/v4';
 import {
+  CLAUDE_CODE_BOOTSTRAP_DIR as BOOTSTRAP_DIR,
+  getClaudeCodeBootstrap,
+} from './claude-code-bootstrap';
+import {
+  CLAUDE_CODE_CREDENTIAL_ENVIRONMENT_VARIABLES,
+  createClaudeCodeRequestTransformations,
+  resolveClaudeCodeAuthenticationMode,
   resolveClaudeCodeEnv,
   type ClaudeCodeAuthOptions,
 } from './claude-code-auth';
@@ -753,20 +760,6 @@ const CLAUDE_CODE_BUILTIN_TOOLS = {
   },
 } as const satisfies Record<string, HarnessV1BuiltinTool<any, any>>;
 
-/*
- * Bootstrap is derived state stored under the sandbox's default working
- * directory so snapshot-capable providers can preserve the installed CLI,
- * bridge, and recipe marker without requiring root filesystem access.
- *
- * The session work dir (`startOpts.sessionWorkDir`) and the bridge-state dir
- * derived from `sandboxSession.defaultWorkingDirectory` both live under the sandbox's
- * default working directory — the provider's persistent mount — so the
- * workdir's CLI state (Claude's `~/.claude/projects/<dir>/*.jsonl` thread
- * history is keyed by working directory) and the bridge state files survive
- * both detach -> attach/replay and stop -> snapshot -> resume cycles.
- */
-const BOOTSTRAP_DIR = '.harness-bootstrap/claude-code';
-
 /**
  * Live bridge coordinates returned by `doDetach()` and `doSuspendTurn()`. A
  * future process uses them to reopen a socket to the still-running bridge
@@ -805,7 +798,6 @@ export function createClaudeCode(
       'Claude Code MCP server name "harness-tools" is reserved for HarnessAgent tools.',
     );
   }
-  let cachedBootstrap: HarnessV1Bootstrap | undefined;
   const thinking = settings.thinking ?? {
     type: 'adaptive',
     display: 'summarized',
@@ -818,35 +810,41 @@ export function createClaudeCode(
     supportsBuiltinToolApprovals: true,
     supportsBuiltinToolFiltering: true,
     lifecycleStateSchema: claudeCodeResumeStateSchema,
-    getBootstrap: async () => {
-      if (cachedBootstrap != null) return cachedBootstrap;
-      const [pkg, lock, bridge] = await Promise.all([
-        readBridgeAsset('package.json'),
-        readBridgeAsset('pnpm-lock.yaml'),
-        readBridgeAsset('index.mjs'),
-      ]);
-      cachedBootstrap = {
-        harnessId: 'claude-code',
-        bootstrapDir: BOOTSTRAP_DIR,
-        files: [
-          { path: `${BOOTSTRAP_DIR}/package.json`, content: pkg },
-          { path: `${BOOTSTRAP_DIR}/pnpm-lock.yaml`, content: lock },
-          { path: `${BOOTSTRAP_DIR}/bridge.mjs`, content: bridge },
-        ],
-        commands: [
-          {
-            command: 'pnpm install --frozen-lockfile --store-dir .pnpm-store',
-          },
-          {
-            command:
-              'if [ -f node_modules/@anthropic-ai/claude-code/install.cjs ]; then node node_modules/@anthropic-ai/claude-code/install.cjs; fi && ./node_modules/.bin/claude --version',
-          },
-        ],
-      };
-      return cachedBootstrap;
-    },
+    getBootstrap: getClaudeCodeBootstrap,
     doStart: async startOpts => {
       const sandboxSession = startOpts.sandboxSession;
+      const authenticationMode = resolveClaudeCodeAuthenticationMode(
+        settings.auth,
+      );
+      const resolvedAuthEnvironment = resolveClaudeCodeEnv(settings.auth);
+      let authEnv = resolvedAuthEnvironment;
+      let sandboxTurnEnvironment = settings.env;
+      if (sandboxSession.addRequestTransformations != null) {
+        const requestTransformations = createClaudeCodeRequestTransformations(
+          {
+            ...resolvedAuthEnvironment,
+            ...settings.env,
+          },
+          authenticationMode,
+        );
+        if (requestTransformations.length > 0) {
+          await sandboxSession.addRequestTransformations(
+            requestTransformations,
+          );
+        }
+        authEnv = maskSandboxCredentials({
+          environment: resolvedAuthEnvironment,
+          credentialEnvironmentVariables:
+            CLAUDE_CODE_CREDENTIAL_ENVIRONMENT_VARIABLES,
+        });
+        sandboxTurnEnvironment = maskSandboxCredentials({
+          environment: settings.env ?? {},
+          credentialEnvironmentVariables:
+            CLAUDE_CODE_CREDENTIAL_ENVIRONMENT_VARIABLES,
+        });
+      } else {
+        warnCredentialBrokeringUnavailable();
+      }
       const session = sandboxSession.restricted();
       const sandboxId = sandboxSession.id;
       const bootstrapDir = posix.resolve(
@@ -886,9 +884,10 @@ export function createClaudeCode(
       // 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 = (wsUrl: string) => async (): Promise<WebSocket> => {
-        return openBridgeWebSocket({ wsUrl, timeoutMs });
-      };
+      const buildConnect =
+        (endpoint: HarnessV1PortEndpoint) => async (): Promise<WebSocket> => {
+          return openBridgeWebSocket({ endpoint, timeoutMs });
+        };
 
       /*
        * Rung 1 — ATTACH. When lifecycle state carries live bridge coordinates,
@@ -900,13 +899,16 @@ export function createClaudeCode(
        */
       if (coords) {
         try {
-          const attachUrl =
-            (await sandboxSession.getPortUrl({
-              port: coords.port,
-              protocol: 'ws',
-            })) + `?agent_bridge_token=${encodeURIComponent(coords.token)}`;
+          const endpoint = await sandboxSession.getPortEndpoint({
+            port: coords.port,
+            protocol: 'ws',
+          });
+          const attachEndpoint = withBridgeToken({
+            endpoint,
+            token: coords.token,
+          });
           const attachChannel: ClaudeCodeChannel = new SandboxChannel({
-            connect: buildConnect(attachUrl),
+            connect: buildConnect(attachEndpoint),
             outboundSchema: outboundMessageSchema,
             initialLastSeenEventId: coords.lastSeenEventId,
             onDiagnostic,
@@ -922,7 +924,7 @@ export function createClaudeCode(
             proc: undefined,
             model: settings.model,
             maxTurns: settings.maxTurns,
-            env: settings.env,
+            env: sandboxTurnEnvironment,
             thinking,
             effort: settings.effort,
             isResume: true,
@@ -978,7 +980,6 @@ export function createClaudeCode(
         settings.mintBridgeToken == null
           ? randomBytes(32).toString('hex')
           : settings.mintBridgeToken(sandboxId);
-      const authEnv = resolveClaudeCodeEnv(settings.auth);
       const env = {
         ...authEnv,
         /*
@@ -1070,14 +1071,14 @@ export function createClaudeCode(
       });
       void drainBridgeProcessStream(proc.stdout);
 
-      const wsUrl =
-        (await sandboxSession.getPortUrl({
-          port: boundPort,
-          protocol: 'ws',
-        })) + `?agent_bridge_token=${encodeURIComponent(token)}`;
+      const endpoint = await sandboxSession.getPortEndpoint({
+        port: boundPort,
+        protocol: 'ws',
+      });
+      const bridgeEndpoint = withBridgeToken({ endpoint, token });
 
       const channel: ClaudeCodeChannel = new SandboxChannel({
-        connect: buildConnect(wsUrl),
+        connect: buildConnect(bridgeEndpoint),
         outboundSchema: outboundMessageSchema,
         onDiagnostic,
         onBridgeError,
@@ -1098,7 +1099,7 @@ export function createClaudeCode(
         proc,
         model: settings.model,
         maxTurns: settings.maxTurns,
-        env: settings.env,
+        env: sandboxTurnEnvironment,
         thinking,
         effort: settings.effort,
         isResume: respawnStrategy !== undefined,
@@ -1162,24 +1163,6 @@ async function writeClaudeCodeSkills({
   });
 }
 
-async function readBridgeAsset(name: string): Promise<string> {
-  const candidates = [
-    new URL(`./bridge/${name}`, import.meta.url),
-    new URL(`../bridge/${name}`, import.meta.url),
-  ];
-  let lastErr: unknown;
-  for (const url of candidates) {
-    try {
-      return await readFile(fileURLToPath(url), 'utf8');
-    } catch (err) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code !== 'ENOENT') throw err;
-      lastErr = err;
-    }
-  }
-  throw lastErr ?? new Error(`bridge asset not found: ${name}`);
-}
-
 /**
  * Wait for the bridge's `bridge-hello` message to arrive on the freshly
  * opened WebSocket before any other host-side code touches it.
@@ -1192,16 +1175,18 @@ async function readBridgeAsset(name: string): Promise<string> {
  * is the only reliable evidence that the end-to-end link is live.
  */
 function openWebSocketAndWaitForBridgeHello({
-  url,
+  endpoint,
   openTimeoutMs,
   getHelloTimeoutMs,
 }: {
-  url: string;
+  endpoint: HarnessV1PortEndpoint;
   openTimeoutMs: number;
   getHelloTimeoutMs: () => number;
 }): Promise<WebSocket> {
   return new Promise<WebSocket>((resolve, reject) => {
-    const ws = new WebSocket(url);
+    const ws = new WebSocket(endpoint.url, {
+      headers: endpoint.headers == null ? undefined : { ...endpoint.headers },
+    });
     let opened = false;
     let sawBridgeHello = false;
     let settled = false;
@@ -1293,10 +1278,10 @@ function openWebSocketAndWaitForBridgeHello({
 }
 
 async function openBridgeWebSocket({
-  wsUrl,
+  endpoint,
   timeoutMs,
 }: {
-  wsUrl: string;
+  endpoint: HarnessV1PortEndpoint;
   timeoutMs: number;
 }): Promise<WebSocket> {
   const deadline = Date.now() + timeoutMs;
@@ -1308,7 +1293,7 @@ async function openBridgeWebSocket({
     try {
       const remaining = Math.max(1, deadline - Date.now());
       return await openWebSocketAndWaitForBridgeHello({
-        url: wsUrl,
+        endpoint,
         openTimeoutMs: Math.min(10_000, remaining),
         getHelloTimeoutMs: () =>
           Math.min(5_000, Math.max(1, deadline - Date.now())),
@@ -1339,6 +1324,18 @@ function webSocketMessageToString(raw: unknown): string {
   return String(raw);
 }
 
+function withBridgeToken({
+  endpoint,
+  token,
+}: {
+  endpoint: HarnessV1PortEndpoint;
+  token: string;
+}): HarnessV1PortEndpoint {
+  const bridgeUrl = new URL(endpoint.url);
+  bridgeUrl.searchParams.set('agent_bridge_token', token);
+  return { ...endpoint, url: bridgeUrl.toString() };
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise(resolve => {
     const timer = setTimeout(resolve, ms);
@@ -1543,6 +1540,16 @@ function createSession({
     isResume,
     modelId: model,
     doPromptTurn: async promptOpts => {
+      if (
+        promptOpts.responseFormat?.type === 'json' &&
+        promptOpts.responseFormat.schema == null
+      ) {
+        throw new HarnessCapabilityUnsupportedError({
+          message:
+            "Harness 'claude-code' requires a JSON schema for structured output.",
+          harnessId: 'claude-code',
+        });
+      }
       const control = wireTurn({
         emit: promptOpts.emit,
         abortSignal: promptOpts.abortSignal,
@@ -1556,6 +1563,9 @@ function createSession({
           description: t.description,
           inputSchema: t.inputSchema,
         })),
+        ...(promptOpts.responseFormat == null
+          ? {}
+          : { responseFormat: promptOpts.responseFormat }),
         ...(promptOpts.instructions
           ? { instructions: promptOpts.instructions }
           : {}),
@@ -1579,6 +1589,16 @@ function createSession({
       return control;
     },
     doContinueTurn: async continueOpts => {
+      if (
+        continueOpts.responseFormat?.type === 'json' &&
+        continueOpts.responseFormat.schema == null
+      ) {
+        throw new HarnessCapabilityUnsupportedError({
+          message:
+            "Harness 'claude-code' requires a JSON schema for structured output.",
+          harnessId: 'claude-code',
+        });
+      }
       const control = wireTurn({
         emit: continueOpts.emit,
         abortSignal: continueOpts.abortSignal,
@@ -1614,6 +1634,9 @@ function createSession({
             description: t.description,
             inputSchema: t.inputSchema,
           })),
+          ...(continueOpts.responseFormat == null
+            ? {}
+            : { responseFormat: continueOpts.responseFormat }),
           ...(continueOpts.instructions
             ? { instructions: continueOpts.instructions }
             : {}),