@ai-sdk/harness-claude-code 1.0.73 → 1.0.75

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @ai-sdk/harness-claude-code
 
+## 1.0.75
+
+### Patch Changes
+
+- 69bb613: feat(harness): support request transformations in network sandbox abstraction and use it to apply credential brokering when available
+- 52bc889: feat(harness): add `getPortEndpoint()` as more comprehensive replacement to `getPortUrl()` (now deprecated) in `HarnessV1NetworkSandboxSession`
+- 4cd4989: chore(harness): decouple bridge based harness bootstrap recipe logic from dynamic params and enforce unique harnesses in `prepareSandboxForHarness()` helper
+- Updated dependencies [69bb613]
+- Updated dependencies [52bc889]
+- Updated dependencies [4cd4989]
+  - @ai-sdk/harness@1.0.72
+
+## 1.0.74
+
+### Patch Changes
+
+- 83fe754: chore(harness): simplify the `auth` param to be a simple string to choose the auth method
+- Updated dependencies [8d717b3]
+  - @ai-sdk/harness@1.0.71
+
 ## 1.0.73
 
 ### Patch Changes

package/dist/index.d.ts

@@ -4,7 +4,12 @@ import { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
 import * as _ai_sdk_harness from '@ai-sdk/harness';
 import { HarnessV1, HarnessV1BuiltinTool } from '@ai-sdk/harness';
 
-type ClaudeCodeAuthOptions = {
+type ClaudeCodeResolvedAuthenticationMode = 'direct' | 'ai-gateway';
+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.
+ */
+type LegacyClaudeCodeAuthOptions = {
     readonly anthropic?: {
         readonly apiKey?: string;
         readonly authToken?: string;
@@ -15,6 +20,7 @@ type ClaudeCodeAuthOptions = {
         readonly baseUrl?: string;
     };
 };
+type ClaudeCodeAuthOptions = ClaudeCodeAuthenticationMode | LegacyClaudeCodeAuthOptions;
 
 type ClaudeCodeThinkingConfig = {
     readonly type: 'adaptive' | 'enabled';
@@ -25428,4 +25434,4 @@ declare const claudeCode: _ai_sdk_harness.HarnessV1<{
     };
 }>;
 
-export { type ClaudeCodeAuthOptions, type ClaudeCodeHarnessSettings, type ClaudeCodeThinkingConfig, VERSION, claudeCode, createClaudeCode };
+export { type ClaudeCodeAuthOptions, type ClaudeCodeAuthenticationMode, type ClaudeCodeHarnessSettings, type ClaudeCodeThinkingConfig, VERSION, claudeCode, createClaudeCode };

package/dist/index.js

@@ -1,8 +1,6 @@
 // src/claude-code-harness.ts
 import { randomBytes } from "crypto";
-import { readFile } from "fs/promises";
 import { posix } from "path";
-import { fileURLToPath } from "url";
 import {
   commonTool,
   harnessV1DiagnosticFromBridgeFrame,
@@ -15,9 +13,11 @@ import {
   drainBridgeProcessStream,
   forwardBridgeProcessStream,
   markBridgeStarting,
+  maskSandboxCredentials,
   resolveSandboxHomeDir,
   SandboxChannel,
   shellQuote,
+  warnCredentialBrokeringUnavailable,
   waitForBridgeReady,
   writeSkills as writeHarnessSkills
 } from "@ai-sdk/harness/utils";
@@ -28,21 +28,98 @@ import {
 import { WebSocket } from "ws";
 import { z as z2 } from "zod/v4";
 
+// src/claude-code-bootstrap.ts
+import { readFile } from "fs/promises";
+import { fileURLToPath } from "url";
+var CLAUDE_CODE_BOOTSTRAP_DIR = ".harness-bootstrap/claude-code";
+var cachedBootstrap;
+async function getClaudeCodeBootstrap() {
+  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) {
+  const candidates = [
+    new URL(`./bridge/${name}`, import.meta.url),
+    new URL(`../bridge/${name}`, import.meta.url)
+  ];
+  let lastErr;
+  for (const url of candidates) {
+    try {
+      return await readFile(fileURLToPath(url), "utf8");
+    } catch (err) {
+      const code = err.code;
+      if (code !== "ENOENT") throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr ?? new Error(`bridge asset not found: ${name}`);
+}
+
 // src/claude-code-auth.ts
 import { execFileSync } from "child_process";
 import { readFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-import { getAiGatewayAuthFromEnv } from "@ai-sdk/harness/utils";
+import {
+  createCredentialRequestTransformation,
+  getAiGatewayAuthFromEnv
+} from "@ai-sdk/harness/utils";
+var CLAUDE_CODE_CREDENTIAL_ENVIRONMENT_VARIABLES = [
+  "AI_GATEWAY_API_KEY",
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN"
+];
+function createClaudeCodeRequestTransformations(env, auth) {
+  const headers = {};
+  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
+    })
+  ];
+}
 function resolveClaudeCodeEnv(auth, processEnv = process.env, options = {}) {
+  const normalizedAuth = normalizeClaudeCodeAuthToLegacyAuth(auth);
   const readApiKey = options.readApiKeyHelper ?? readApiKeyHelper;
-  if (auth?.anthropic) {
-    return pickAnthropic({ explicit: auth.anthropic, processEnv, readApiKey });
+  if (normalizedAuth?.anthropic) {
+    return pickAnthropic({
+      explicit: normalizedAuth.anthropic,
+      processEnv,
+      readApiKey
+    });
   }
   const gatewayAuthFromEnv = getAiGatewayAuthFromEnv({ env: processEnv });
-  if (auth?.gateway) {
+  if (normalizedAuth?.gateway) {
     return pickGateway({
-      explicit: auth.gateway,
+      explicit: normalizedAuth.gateway,
       gatewayAuthFromEnv
     });
   }
@@ -54,6 +131,34 @@ function resolveClaudeCodeEnv(auth, processEnv = process.env, options = {}) {
   }
   return pickAnthropic({ processEnv, readApiKey });
 }
+function resolveClaudeCodeAuthenticationMode(auth, processEnv = process.env) {
+  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) {
+  if (auth == null || auth === "auto") {
+    return void 0;
+  }
+  if (typeof auth === "string") {
+    switch (auth) {
+      case "direct":
+        return { anthropic: {} };
+      case "ai-gateway":
+        return { gateway: {} };
+      default:
+        return void 0;
+    }
+  }
+  console.warn(
+    '[claude-code] Passing an object to auth options is deprecated. Use a string mode ("auto" | "direct" | "ai-gateway") instead, and pass credentials via environment variables.'
+  );
+  return auth;
+}
 function pickAnthropic({
   explicit,
   processEnv,
@@ -153,7 +258,7 @@ var inboundMessageSchema = z.discriminatedUnion("type", [
 ]);
 
 // src/version.ts
-var VERSION = true ? "1.0.73" : "0.0.0-test";
+var VERSION = true ? "1.0.75" : "0.0.0-test";
 
 // src/claude-code-harness.ts
 var CLAUDE_CODE_CLIENT_APP = `ai-sdk/harness-claude-code/${VERSION}`;
@@ -750,7 +855,6 @@ var CLAUDE_CODE_BUILTIN_TOOLS = {
     toolUseKind: "edit"
   }
 };
-var BOOTSTRAP_DIR = ".harness-bootstrap/claude-code";
 var claudeCodeBridgeCoordsSchema = z2.object({
   port: z2.number(),
   token: z2.string(),
@@ -766,7 +870,6 @@ function createClaudeCode(settings = {}) {
       'Claude Code MCP server name "harness-tools" is reserved for HarnessAgent tools.'
     );
   }
-  let cachedBootstrap;
   const thinking = settings.thinking ?? {
     type: "adaptive",
     display: "summarized"
@@ -778,39 +881,44 @@ function createClaudeCode(settings = {}) {
     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(
         sandboxSession.defaultWorkingDirectory,
-        BOOTSTRAP_DIR
+        CLAUDE_CODE_BOOTSTRAP_DIR
       );
       const lifecycleState = startOpts.continueFrom ?? startOpts.resumeFrom;
       const isResume = lifecycleState != null;
@@ -831,17 +939,21 @@ function createClaudeCode(settings = {}) {
         harnessId: "claude-code",
         sessionId: startOpts.sessionId
       });
-      const buildConnect = (wsUrl2) => async () => {
-        return openBridgeWebSocket({ wsUrl: wsUrl2, timeoutMs });
+      const buildConnect = (endpoint2) => async () => {
+        return openBridgeWebSocket({ endpoint: endpoint2, timeoutMs });
       };
       if (coords) {
         try {
-          const attachUrl = await sandboxSession.getPortUrl({
+          const endpoint2 = await sandboxSession.getPortEndpoint({
             port: coords.port,
             protocol: "ws"
-          }) + `?agent_bridge_token=${encodeURIComponent(coords.token)}`;
+          });
+          const attachEndpoint = withBridgeToken({
+            endpoint: endpoint2,
+            token: coords.token
+          });
           const attachChannel = new SandboxChannel({
-            connect: buildConnect(attachUrl),
+            connect: buildConnect(attachEndpoint),
             outboundSchema: outboundMessageSchema,
             initialLastSeenEventId: coords.lastSeenEventId,
             onDiagnostic,
@@ -857,7 +969,7 @@ function createClaudeCode(settings = {}) {
             proc: void 0,
             model: settings.model,
             maxTurns: settings.maxTurns,
-            env: settings.env,
+            env: sandboxTurnEnvironment,
             thinking,
             effort: settings.effort,
             isResume: true,
@@ -893,7 +1005,6 @@ function createClaudeCode(settings = {}) {
       }) : void 0;
       const port = resolveBridgePort(sandboxSession, settings.port);
       const token = settings.mintBridgeToken == null ? randomBytes(32).toString("hex") : settings.mintBridgeToken(sandboxId);
-      const authEnv = resolveClaudeCodeEnv(settings.auth);
       const env = {
         ...authEnv,
         /*
@@ -967,12 +1078,13 @@ function createClaudeCode(settings = {}) {
         })
       });
       void drainBridgeProcessStream(proc.stdout);
-      const wsUrl = await sandboxSession.getPortUrl({
+      const endpoint = await sandboxSession.getPortEndpoint({
         port: boundPort,
         protocol: "ws"
-      }) + `?agent_bridge_token=${encodeURIComponent(token)}`;
+      });
+      const bridgeEndpoint = withBridgeToken({ endpoint, token });
       const channel = new SandboxChannel({
-        connect: buildConnect(wsUrl),
+        connect: buildConnect(bridgeEndpoint),
         outboundSchema: outboundMessageSchema,
         onDiagnostic,
         onBridgeError,
@@ -990,7 +1102,7 @@ function createClaudeCode(settings = {}) {
         proc,
         model: settings.model,
         maxTurns: settings.maxTurns,
-        env: settings.env,
+        env: sandboxTurnEnvironment,
         thinking,
         effort: settings.effort,
         isResume: respawnStrategy !== void 0,
@@ -1032,30 +1144,15 @@ async function writeClaudeCodeSkills({
     trailingNewline: true
   });
 }
-async function readBridgeAsset(name) {
-  const candidates = [
-    new URL(`./bridge/${name}`, import.meta.url),
-    new URL(`../bridge/${name}`, import.meta.url)
-  ];
-  let lastErr;
-  for (const url of candidates) {
-    try {
-      return await readFile(fileURLToPath(url), "utf8");
-    } catch (err) {
-      const code = err.code;
-      if (code !== "ENOENT") throw err;
-      lastErr = err;
-    }
-  }
-  throw lastErr ?? new Error(`bridge asset not found: ${name}`);
-}
 function openWebSocketAndWaitForBridgeHello({
-  url,
+  endpoint,
   openTimeoutMs,
   getHelloTimeoutMs
 }) {
   return new Promise((resolve, reject) => {
-    const ws = new WebSocket(url);
+    const ws = new WebSocket(endpoint.url, {
+      headers: endpoint.headers == null ? void 0 : { ...endpoint.headers }
+    });
     let opened = false;
     let sawBridgeHello = false;
     let settled = false;
@@ -1139,7 +1236,7 @@ function openWebSocketAndWaitForBridgeHello({
   });
 }
 async function openBridgeWebSocket({
-  wsUrl,
+  endpoint,
   timeoutMs
 }) {
   const deadline = Date.now() + timeoutMs;
@@ -1150,7 +1247,7 @@ async function openBridgeWebSocket({
     try {
       const remaining = Math.max(1, deadline - Date.now());
       return await openWebSocketAndWaitForBridgeHello({
-        url: wsUrl,
+        endpoint,
         openTimeoutMs: Math.min(1e4, remaining),
         getHelloTimeoutMs: () => Math.min(5e3, Math.max(1, deadline - Date.now()))
       });
@@ -1177,6 +1274,14 @@ function webSocketMessageToString(raw) {
   }
   return String(raw);
 }
+function withBridgeToken({
+  endpoint,
+  token
+}) {
+  const bridgeUrl = new URL(endpoint.url);
+  bridgeUrl.searchParams.set("agent_bridge_token", token);
+  return { ...endpoint, url: bridgeUrl.toString() };
+}
 function sleep(ms) {
   return new Promise((resolve) => {
     const timer = setTimeout(resolve, ms);