@ai-sdk/harness-acp 1.0.15 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@ai-sdk/harness": "1.0.77",
+    "@ai-sdk/harness": "1.0.78",
     "@ai-sdk/provider-utils": "5.0.28"
   },
   "peerDependencies": {

package/src/acp-harness.ts

@@ -1,4 +1,4 @@
-import type { HarnessV1 } from '@ai-sdk/harness';
+import type { HarnessV1, HarnessV1PortEndpoint } from '@ai-sdk/harness';
 import type { ToolSet } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import type { ACPClientApp } from './acp-auth';
@@ -24,6 +24,11 @@ export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly mcpServers?: Record<string, unknown>;
   readonly isMcpToolCall?: (toolCall: ACPToolCall) => boolean;
   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;
   readonly startupTimeoutMs?: number;
   readonly clientApp?: ACPClientApp;
   readonly version?: ACPV1Settings['version'];
@@ -125,6 +130,7 @@ export function createACP<TBuiltinTools extends ToolSet = {}>(
         builtinTools:
           settings.builtinTools ?? (ACP_BUILTIN_TOOLS as TBuiltinTools),
         port: settings.port,
+        portEndpoint: settings.portEndpoint,
         startupTimeoutMs: settings.startupTimeoutMs,
         clientApp,
         lifecycleStateSchema: acpResumeStateSchema,

package/src/v1/acp-v1-harness.ts

@@ -19,8 +19,10 @@ import {
   classifyDiskLog,
   drainBridgeProcessStream,
   forwardBridgeProcessStream,
+  getRestrictedSandboxSession,
   markBridgeStarting,
   maskSandboxCredentials,
+  resolveSandboxDefaultWorkingDirectory,
   resolveSandboxHomeDir,
   SandboxChannel,
   shellQuote,
@@ -30,6 +32,7 @@ import {
 import {
   asSchema,
   type Experimental_SandboxProcess,
+  type Experimental_SandboxSession as SandboxSession,
   type ToolSet,
 } from '@ai-sdk/provider-utils';
 import { WebSocket } from 'ws';
@@ -114,6 +117,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
   settings,
   builtinTools,
   port: portOverride,
+  portEndpoint: portEndpointOverride,
   startupTimeoutMs,
   clientApp,
   lifecycleStateSchema,
@@ -121,6 +125,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
   settings: ACPV1Settings;
   builtinTools: TBuiltinTools;
   port?: number;
+  portEndpoint?: HarnessV1PortEndpoint;
   startupTimeoutMs?: number;
   clientApp: ACPClientApp;
   lifecycleStateSchema: NonNullable<
@@ -210,6 +215,26 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         compatibility: providerAuthenticationCompatibility,
       });
       const sandboxSession = startOptions.sandboxSession;
+      const toolSafeSandboxSession =
+        getRestrictedSandboxSession(sandboxSession);
+      const sandboxId = 'id' in sandboxSession ? sandboxSession.id : undefined;
+      validateBasicSandboxSettings({
+        sandboxSession,
+        port: portOverride,
+        portEndpoint: portEndpointOverride,
+        harnessId: settings.harnessId,
+      });
+      if (settings.mintBridgeToken != null && sandboxId == null) {
+        throw unsupported({
+          harnessId: settings.harnessId,
+          message: `The ${settings.harnessId} ACP harness cannot use \`mintBridgeToken\` with a sandbox session that does not expose an id.`,
+        });
+      }
+      const defaultWorkingDirectory =
+        await resolveSandboxDefaultWorkingDirectory({
+          sandboxSession,
+          abortSignal: startOptions.abortSignal,
+        });
       const implementationEnvironment = resolveImplementationEnvironment({
         implementation,
         env,
@@ -221,6 +246,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
 
       if (
         settings.credentialBrokering != null &&
+        'addRequestTransformations' in sandboxSession &&
         sandboxSession.addRequestTransformations != null
       ) {
         const providerEnvironment = resolveProviderEnvironment({
@@ -275,15 +301,14 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       } else if (settings.credentialBrokering != null) {
         warnCredentialBrokeringUnavailable();
       }
-      const sandbox = sandboxSession.restricted();
       const resolvedBridgeDir = posix.resolve(
-        sandboxSession.defaultWorkingDirectory,
+        defaultWorkingDirectory,
         bootstrap.bootstrapDir,
       );
       const resolvedImplementationDir = `${resolvedBridgeDir}/implementation`;
       const workDir = startOptions.sessionWorkDir;
       const sandboxHomeDir = await resolveSandboxHomeDir({
-        sandbox,
+        sandbox: toolSafeSandboxSession,
         abortSignal: startOptions.abortSignal,
       });
       const privateSessionDir = resolveACPPrivateSessionDirectory({
@@ -309,7 +334,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           implementationIdentity,
           authenticationProfile,
           lifecycleData,
-          sandboxId: sandboxSession.id,
+          sandboxId,
         });
       }
       const skills = startOptions.skills ?? [];
@@ -323,7 +348,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       if (skills.length > 0) {
         skillCatalog = (
           await materializeACPSkills({
-            sandbox,
+            sandbox: toolSafeSandboxSession,
             sandboxHomeDir,
             sessionWorkDir: workDir,
             harnessId: settings.harnessId,
@@ -365,9 +390,11 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         }
         if (coords != null) {
           try {
-            const endpoint = await sandboxSession.getPortEndpoint({
+            const endpoint = await resolveBridgeEndpoint({
+              sandboxSession,
+              override: portEndpointOverride,
               port: coords.port,
-              protocol: 'ws',
+              harnessId: settings.harnessId,
             });
             const attachEndpoint = withBridgeToken({
               endpoint,
@@ -407,7 +434,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               acpSessionId: lifecycleData.acpSessionId,
               bridgePort: coords.port,
               bridgeToken: coords.token,
-              sandboxId: sandboxSession.id,
+              sandboxId,
               isResume: true,
               turnInFlight: isContinue,
               bridgeStateDir,
@@ -420,7 +447,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           } catch (error) {
             if (isContinue) {
               const eventLog = await Promise.resolve(
-                sandbox.readTextFile({
+                toolSafeSandboxSession.readTextFile({
                   path: `${bridgeStateDir}/event-log.ndjson`,
                   abortSignal: startOptions.abortSignal,
                 }),
@@ -502,19 +529,19 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       const token =
         settings.mintBridgeToken == null
           ? randomBytes(32).toString('hex')
-          : settings.mintBridgeToken(sandboxSession.id);
-      await sandbox.run({
+          : settings.mintBridgeToken(sandboxId!);
+      await toolSafeSandboxSession.run({
         command: `mkdir -p ${shellQuote(workDir)} ${shellQuote(bridgeStateDir)}`,
         abortSignal: startOptions.abortSignal,
       });
       await markBridgeStarting({
-        sandbox,
+        sandbox: toolSafeSandboxSession,
         bridgeStateDir,
         bridgeType: settings.harnessId,
         abortSignal: startOptions.abortSignal,
       });
 
-      const proc = await sandbox.spawn({
+      const proc = await toolSafeSandboxSession.spawn({
         command:
           `node ${shellQuote(`${resolvedBridgeDir}/bridge.mjs`)}` +
           ` --workdir ${shellQuote(workDir)}` +
@@ -551,7 +578,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       const timeoutMs = startupTimeoutMs ?? 120_000;
       const { port: boundPort } = await waitForBridgeReady({
         proc,
-        sandbox,
+        sandbox: toolSafeSandboxSession,
         bridgeStateDir,
         bridgeType: settings.harnessId,
         timeoutMs,
@@ -575,9 +602,11 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       });
       void drainBridgeProcessStream(proc.stdout);
 
-      const endpoint = await sandboxSession.getPortEndpoint({
+      const endpoint = await resolveBridgeEndpoint({
+        sandboxSession,
+        override: portEndpointOverride,
         port: boundPort,
-        protocol: 'ws',
+        harnessId: settings.harnessId,
       });
       const bridgeEndpoint = withBridgeToken({ endpoint, token });
       const channel: ACPChannel = new SandboxChannel({
@@ -660,7 +689,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         acpSessionId: lifecycleData?.acpSessionId,
         bridgePort: boundPort,
         bridgeToken: token,
-        sandboxId: sandboxSession.id,
+        sandboxId,
         isResume,
         turnInFlight:
           respawnStrategy?.mode === 'disk-replay' ||
@@ -745,12 +774,14 @@ function resolveBridgePort({
   override,
   harnessId,
 }: {
-  sandboxSession: HarnessV1NetworkSandboxSession;
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
   override: number | undefined;
   harnessId: string;
 }): 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 unsupported({
     harnessId,
     message:
@@ -759,6 +790,53 @@ function resolveBridgePort({
   });
 }
 
+function validateBasicSandboxSettings({
+  sandboxSession,
+  port,
+  portEndpoint,
+  harnessId,
+}: {
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
+  port: number | undefined;
+  portEndpoint: HarnessV1PortEndpoint | undefined;
+  harnessId: string;
+}): void {
+  if ('getPortEndpoint' in sandboxSession) return;
+  if (port == null) {
+    throw unsupported({
+      harnessId,
+      message: `The ${harnessId} ACP harness requires an explicit \`port\` when using a basic sandbox session.`,
+    });
+  }
+  if (portEndpoint == null) {
+    throw unsupported({
+      harnessId,
+      message: `The ${harnessId} ACP harness requires an explicit \`portEndpoint\` when using a basic sandbox session.`,
+    });
+  }
+}
+
+async function resolveBridgeEndpoint({
+  sandboxSession,
+  override,
+  port,
+  harnessId,
+}: {
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
+  override: HarnessV1PortEndpoint | undefined;
+  port: number;
+  harnessId: string;
+}): Promise<HarnessV1PortEndpoint> {
+  if (override != null) return override;
+  if ('getPortEndpoint' in sandboxSession) {
+    return sandboxSession.getPortEndpoint({ port, protocol: 'ws' });
+  }
+  throw unsupported({
+    harnessId,
+    message: `The ${harnessId} ACP harness requires an explicit \`portEndpoint\` when using a basic sandbox session.`,
+  });
+}
+
 function openWebSocket({
   url,
   headers,