@ai-sdk/harness-acp 1.0.39 → 1.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,8 +26,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.101",
-    "@ai-sdk/provider-utils": "5.0.36",
+    "@ai-sdk/harness": "1.0.103",
+    "@ai-sdk/provider-utils": "5.0.37",
     "ws": "^8.21.0"
   },
   "peerDependencies": {

package/src/acp-harness.ts

@@ -74,6 +74,14 @@ export type ACPHarnessSettings<
   readonly skillsDirectory?: ACPV1Settings['skillsDirectory'];
   readonly instructionMapping?: ACPV1Settings['instructionMapping'];
   readonly outputSchemaMapping?: ACPV1Settings['outputSchemaMapping'];
+  /**
+   * Transport used for the harness-owned MCP server that exposes host tools to
+   * the ACP implementation. Defaults to `stdio`. Set this to `http` for
+   * implementations that only accept HTTP or SSE MCP servers from the client,
+   * which requires the implementation to advertise
+   * `agentCapabilities.mcpCapabilities.http`.
+   */
+  readonly hostToolMcpTransport?: ACPV1Settings['hostToolMcpTransport'];
   readonly askUserQuestions?: TAskUserQuestions;
   readonly permissionModeMapping?: ACPV1Settings['permissionModeMapping'];
   readonly session?: ACPV1Settings['session'];

package/src/index.ts

@@ -23,6 +23,7 @@ export type {
   ACPAskUserQuestionsSettings,
   ACPCredentialBrokering,
   ACPAuthentication,
+  ACPHostToolMCPTransport,
   ACPInstallCommandSource,
   ACPInstructionMapping,
   ACPModelMapping,

package/src/v1/acp-v1-bridge-protocol.ts

@@ -113,6 +113,10 @@ const instructionMappingSchema: z.ZodType<ACPInstructionMapping> =
       variable: z.string().min(1),
       path: instructionMappingPathSchema,
     }),
+    z.object({
+      type: z.literal('filesystem'),
+      path: z.string().min(1),
+    }),
   ]);
 
 type ACPSerializableOutputSchemaMapping = {

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

@@ -32,6 +32,8 @@ import {
   warnCredentialBrokeringUnavailable,
   waitForBridgeReady,
   withBridgeToken,
+  writeInstructions,
+  writeSkills,
 } from '@ai-sdk/harness/utils';
 import {
   asSchema,
@@ -93,9 +95,11 @@ import type {
   ACPV1Settings,
 } from './acp-v1-settings';
 import {
-  materializeACPSkills,
+  ACP_SKILL_NAME_PATTERN,
+  DEFAULT_ACP_SKILLS_DIRECTORY,
   resolveACPPrivateSessionDirectory,
   resolveACPSkillsDirectory,
+  validateACPSkills,
 } from './acp-v1-skills';
 
 const HARNESS_ID_REGEXP = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -324,6 +328,9 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         const requestTransformations = settings.credentialBrokering({
           env: brokeringEnvironment,
           sandboxEnv: sandboxImplementationEnvironment,
+          ...(startOptions.headers == null
+            ? {}
+            : { headers: startOptions.headers }),
         });
         if (requestTransformations.length > 0) {
           await sandboxSession.addRequestTransformations(
@@ -372,17 +379,18 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       });
       const privateSessionDir = resolveACPPrivateSessionDirectory({
         sandboxHomeDir,
-        sessionWorkDir: workDir,
         harnessId: settings.harnessId,
         sessionId: startOptions.sessionId,
       });
+      const implementationHomeDir =
+        implementation.source.type === 'install-command'
+          ? `${resolvedImplementationDir}/home`
+          : sandboxHomeDir;
+      const skillsDir =
+        settings.skillsDirectory ?? DEFAULT_ACP_SKILLS_DIRECTORY;
       const skillsDirectory = resolveACPSkillsDirectory({
-        implementationHomeDir:
-          implementation.source.type === 'install-command'
-            ? `${resolvedImplementationDir}/home`
-            : sandboxHomeDir,
+        implementationHomeDir,
         skillsDirectory: settings.skillsDirectory,
-        sessionWorkDir: workDir,
       });
       const bridgeStateDir = `${privateSessionDir}/bridge`;
       const report = startOptions.observability?.report;
@@ -459,7 +467,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               }),
               instructionsFingerprint: lifecycleData.instructionsFingerprint,
               sandbox: toolSafeSandboxSession,
-              sessionWorkDir: workDir,
+              homePath: implementationHomeDir,
+              skillsDir,
               skillsDirectory,
               acpSessionId: lifecycleData.acpSessionId,
               bridgePort: coords.port,
@@ -620,6 +629,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
             clientCapabilities: settings.clientCapabilities,
             askUserQuestionsRequestMethod:
               settings.askUserQuestions?.requestMethod,
+            hostToolMcpTransport: settings.hostToolMcpTransport,
           }),
           ...sandboxProviderAuthenticationEnvironment,
           BRIDGE_CHANNEL_TOKEN: token,
@@ -752,7 +762,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         }),
         instructionsFingerprint: lifecycleData?.instructionsFingerprint,
         sandbox: toolSafeSandboxSession,
-        sessionWorkDir: workDir,
+        homePath: implementationHomeDir,
+        skillsDir,
         skillsDirectory,
         acpSessionId: lifecycleData?.acpSessionId,
         bridgePort: boundPort,
@@ -1063,7 +1074,8 @@ function createSession({
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
   instructionsFingerprint: instructionsFingerprintAtStart,
   sandbox,
-  sessionWorkDir,
+  homePath,
+  skillsDir,
   skillsDirectory,
   acpSessionId: acpSessionIdAtStart,
   bridgePort,
@@ -1100,7 +1112,8 @@ function createSession({
   initialGuidanceApplied: boolean;
   instructionsFingerprint: string | undefined;
   sandbox: SandboxSession;
-  sessionWorkDir: string;
+  homePath: string;
+  skillsDir: string;
   skillsDirectory: string;
   acpSessionId: string | undefined;
   bridgePort: number;
@@ -1571,15 +1584,41 @@ function createSession({
     skills: ReadonlyArray<HarnessV1Skill>;
     abortSignal?: AbortSignal;
   }): Promise<void> => {
-    await materializeACPSkills({
+    validateACPSkills({ skills });
+    await writeSkills({
       sandbox,
-      rootDir: skillsDirectory,
-      sessionWorkDir,
+      homePath,
+      skillsDir,
       skills,
       abortSignal,
+      skillNamePattern: ACP_SKILL_NAME_PATTERN,
+      invalidSkillNameMessage: ({ name }) =>
+        `Invalid ACP skill name ${JSON.stringify(name)}: expected a kebab-case slug.`,
+      invalidSkillFilePathMessage: ({ skillName, filePath }) =>
+        `Invalid ACP skill file path ${JSON.stringify(filePath)} for skill ${JSON.stringify(
+          skillName,
+        )}: expected a relative POSIX path without traversal.`,
     });
   };
 
+  const synchronizeInstructions = async ({
+    instructions,
+    abortSignal,
+  }: {
+    instructions: string | undefined;
+    abortSignal?: AbortSignal;
+  }): Promise<void> => {
+    if (instructionMapping?.type === 'filesystem') {
+      await writeInstructions({
+        sandbox,
+        homePath,
+        instructionsFile: instructionMapping.path,
+        instructions,
+        abortSignal,
+      });
+    }
+  };
+
   return {
     sessionId,
     isResume,
@@ -1588,6 +1627,10 @@ function createSession({
         skills: options.skills,
         abortSignal: options.abortSignal,
       });
+      await synchronizeInstructions({
+        instructions: options.instructions,
+        abortSignal: options.abortSignal,
+      });
       if (options.responseFormat?.type === 'json') {
         if (options.responseFormat.schema == null) {
           throw unsupported({
@@ -1650,6 +1693,7 @@ function createSession({
           channel.send({
             type: 'start',
             prompt:
+              instructionMapping?.type !== 'filesystem' &&
               instructionsFingerprint !== nextInstructionsFingerprint &&
               (instructionMapping == null || initialGuidanceApplied)
                 ? prependACPInstructionGuidance({
@@ -1692,6 +1736,10 @@ function createSession({
         skills: options.skills,
         abortSignal: options.abortSignal,
       });
+      await synchronizeInstructions({
+        instructions: options.instructions,
+        abortSignal: options.abortSignal,
+      });
       if (options.responseFormat?.type === 'json') {
         if (options.responseFormat.schema == null) {
           throw unsupported({
@@ -1777,11 +1825,6 @@ function createSession({
           `${harnessId} ACP session ${sessionId} is stopped; cannot suspend.`,
         );
       }
-      if (!turnInFlight) {
-        throw new Error(
-          `${harnessId} ACP session ${sessionId} has no in-flight turn to suspend.`,
-        );
-      }
       stopped = true;
       const lastSeenEventId = await channel.suspend();
       return {

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

@@ -90,9 +90,11 @@ export type ACPModelMapping =
 export type ACPCredentialBrokering = ({
   env,
   sandboxEnv,
+  headers,
 }: {
   env: Readonly<Record<string, string>>;
   sandboxEnv?: Readonly<Record<string, string>>;
+  headers?: Readonly<Record<string, string>>;
 }) => ReadonlyArray<HarnessV1RequestTransformation>;
 
 export type ACPPermissionModeTarget =
@@ -124,6 +126,10 @@ export type ACPInstructionMapping =
       readonly type: 'launch-env-json';
       readonly variable: string;
       readonly path: ReadonlyArray<string>;
+    }
+  | {
+      readonly type: 'filesystem';
+      readonly path: string;
     };
 
 export type ACPOutputSchemaMapping = {
@@ -131,6 +137,12 @@ export type ACPOutputSchemaMapping = {
   readonly path: ReadonlyArray<string>;
 };
 
+/**
+ * Transport used for the harness-owned MCP server that exposes host tools to
+ * an ACP implementation.
+ */
+export type ACPHostToolMCPTransport = 'stdio' | 'http';
+
 export type ACPAskUserQuestionsSettings = {
   readonly requestMethod: string;
   readonly isNativeToolCall?: (options: {
@@ -200,6 +212,14 @@ export type ACPV1Settings = {
    * below the ACP session prompt's `_meta` field.
    */
   readonly outputSchemaMapping?: ACPOutputSchemaMapping;
+  /**
+   * Transport used for the harness-owned MCP server that exposes host tools to
+   * the ACP implementation. Defaults to `stdio`. Set this to `http` for
+   * implementations that only accept HTTP or SSE MCP servers from the client,
+   * which requires the implementation to advertise
+   * `agentCapabilities.mcpCapabilities.http`.
+   */
+  readonly hostToolMcpTransport?: ACPHostToolMCPTransport;
   readonly askUserQuestions?: ACPAskUserQuestionsSettings;
   readonly permissionModeMapping?: ACPPermissionModeMapping;
   readonly session?: {

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

@@ -1,74 +1,35 @@
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import type { HarnessV1Skill } from '@ai-sdk/harness';
-import { writeSkills, type WriteSkillsResult } from '@ai-sdk/harness/utils';
-import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
 
-const ACP_SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const ACP_SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 export const DEFAULT_ACP_SKILLS_DIRECTORY = '.agents/skills';
 
 export function resolveACPPrivateSessionDirectory({
   sandboxHomeDir,
-  sessionWorkDir,
   harnessId,
   sessionId,
 }: {
   sandboxHomeDir: string;
-  sessionWorkDir: string;
   harnessId: string;
   sessionId: string;
 }): string {
   const sessionKey = createHash('sha256').update(sessionId).digest('hex');
-  const rootDir = path.posix.join(
+  return path.posix.join(
     sandboxHomeDir,
     '.ai-sdk',
     'harness-acp',
     harnessId,
     sessionKey,
   );
-  assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
-  return rootDir;
-}
-
-export async function materializeACPSkills({
-  sandbox,
-  rootDir,
-  sessionWorkDir,
-  skills,
-  abortSignal,
-}: {
-  sandbox: Experimental_SandboxSession;
-  rootDir: string;
-  sessionWorkDir: string;
-  skills: ReadonlyArray<HarnessV1Skill>;
-  abortSignal?: AbortSignal;
-}): Promise<WriteSkillsResult> {
-  validateACPSkills({ skills });
-  assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
-
-  return writeSkills({
-    sandbox,
-    rootDir,
-    skills,
-    abortSignal,
-    skillNamePattern: ACP_SKILL_NAME_PATTERN,
-    invalidSkillNameMessage: ({ name }) =>
-      `Invalid ACP skill name ${JSON.stringify(name)}: expected a kebab-case slug.`,
-    invalidSkillFilePathMessage: ({ skillName, filePath }) =>
-      `Invalid ACP skill file path ${JSON.stringify(filePath)} for skill ${JSON.stringify(
-        skillName,
-      )}: expected a relative POSIX path without traversal.`,
-  });
 }
 
 export function resolveACPSkillsDirectory({
   implementationHomeDir,
   skillsDirectory = DEFAULT_ACP_SKILLS_DIRECTORY,
-  sessionWorkDir,
 }: {
   implementationHomeDir: string;
   skillsDirectory?: string;
-  sessionWorkDir: string;
 }): string {
   const containsTraversal = skillsDirectory
     .split(/[\\/]/)
@@ -90,12 +51,10 @@ export function resolveACPSkillsDirectory({
     );
   }
 
-  const rootDir = path.posix.join(implementationHomeDir, normalizedDirectory);
-  assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
-  return rootDir;
+  return path.posix.join(implementationHomeDir, normalizedDirectory);
 }
 
-function validateACPSkills({
+export function validateACPSkills({
   skills,
 }: {
   skills: ReadonlyArray<HarnessV1Skill>;
@@ -174,23 +133,3 @@ function validateACPAttachedFilePath({
   }
   return normalizedPath;
 }
-
-function assertOutsideSessionWorkDir({
-  rootDir,
-  sessionWorkDir,
-}: {
-  rootDir: string;
-  sessionWorkDir: string;
-}): void {
-  const relative = path.posix.relative(sessionWorkDir, rootDir);
-  const isInside =
-    relative === '' ||
-    (!relative.startsWith('../') && !path.posix.isAbsolute(relative));
-  if (isInside) {
-    throw new Error(
-      `ACP skill directory ${JSON.stringify(rootDir)} must be outside sessionWorkDir ${JSON.stringify(
-        sessionWorkDir,
-      )}.`,
-    );
-  }
-}

package/src/v1/bridge/acp-v1-bridge-environment.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod/v4';
 import type {
   ACPAuthentication,
+  ACPHostToolMCPTransport,
   ACPProfileValue,
   ACPSerializableValue,
 } from '../acp-v1-settings';
@@ -33,6 +34,11 @@ const profileValueSchema: z.ZodType<ACPProfileValue> = z.lazy(() =>
   ]),
 );
 
+const hostToolMcpTransportSchema: z.ZodType<ACPHostToolMCPTransport> = z.enum([
+  'stdio',
+  'http',
+]);
+
 const serializableRecordSchema = z.record(z.string(), serializableValueSchema);
 const profileRecordSchema = z.record(z.string(), profileValueSchema);
 
@@ -61,6 +67,7 @@ export type ACPBridgeConfiguration = {
   readonly sessionMeta?: Readonly<Record<string, ACPSerializableValue>>;
   readonly clientCapabilities?: Readonly<Record<string, ACPSerializableValue>>;
   readonly askUserQuestionsRequestMethod?: string;
+  readonly hostToolMcpTransport?: ACPHostToolMCPTransport;
 };
 
 const bridgeConfigurationSchema: z.ZodType<ACPBridgeConfiguration> = z.object({
@@ -70,6 +77,7 @@ const bridgeConfigurationSchema: z.ZodType<ACPBridgeConfiguration> = z.object({
   sessionMeta: serializableRecordSchema.optional(),
   clientCapabilities: serializableRecordSchema.optional(),
   askUserQuestionsRequestMethod: z.string().optional(),
+  hostToolMcpTransport: hostToolMcpTransportSchema.optional(),
 });
 
 export function createACPBridgeEnvironment({
@@ -79,6 +87,7 @@ export function createACPBridgeEnvironment({
   sessionMeta,
   clientCapabilities,
   askUserQuestionsRequestMethod,
+  hostToolMcpTransport,
 }: ACPBridgeConfiguration): Record<string, string> {
   return {
     [ACP_BRIDGE_CONFIGURATION_ENV]: JSON.stringify({
@@ -90,6 +99,7 @@ export function createACPBridgeEnvironment({
       ...(askUserQuestionsRequestMethod == null
         ? {}
         : { askUserQuestionsRequestMethod }),
+      ...(hostToolMcpTransport == null ? {} : { hostToolMcpTransport }),
     }),
   };
 }

package/src/v1/bridge/host-tool-mcp-definition.ts

@@ -0,0 +1,69 @@
+import { fileURLToPath } from 'node:url';
+import { execPath } from 'node:process';
+import type * as acp from '@agentclientprotocol/sdk';
+import { HarnessBridgeCapabilityUnsupportedError } from '@ai-sdk/harness/bridge';
+import type { ACPHostToolMCPTransport } from '../acp-v1-settings';
+import type { HostToolRelay } from './host-tool-relay';
+
+/*
+ * Builds the ACP `session/new` definition for the harness-owned MCP server
+ * that exposes host tools. The stdio transport launches `host-tool-mcp.mjs`,
+ * which bridges back to the relay over its private HTTP protocol. The http
+ * transport points the ACP implementation straight at the relay's own MCP
+ * endpoint, which is required by implementations that reject client-supplied
+ * stdio MCP servers.
+ */
+export function createHostToolMcpServerDefinition({
+  mcpTransport,
+  relay,
+  serverName,
+  catalogPath,
+  initialization,
+  harnessId,
+}: {
+  mcpTransport: ACPHostToolMCPTransport;
+  relay: Pick<HostToolRelay, 'url' | 'mcpUrl' | 'credential'>;
+  serverName: string;
+  catalogPath: string;
+  initialization: Pick<acp.InitializeResponse, 'agentCapabilities'>;
+  harnessId: string;
+}): acp.McpServer {
+  if (mcpTransport === 'stdio') {
+    return {
+      name: serverName,
+      command: execPath,
+      args: [fileURLToPath(new URL('./host-tool-mcp.mjs', import.meta.url))],
+      env: [
+        {
+          name: 'AI_SDK_ACP_HOST_TOOLS_FILE',
+          value: catalogPath,
+        },
+        {
+          name: 'AI_SDK_ACP_HOST_TOOL_RELAY_URL',
+          value: relay.url,
+        },
+        {
+          name: 'AI_SDK_ACP_HOST_TOOL_RELAY_CREDENTIAL',
+          value: relay.credential,
+        },
+      ],
+    };
+  }
+  if (initialization.agentCapabilities?.mcpCapabilities?.http !== true) {
+    throw new HarnessBridgeCapabilityUnsupportedError({
+      harnessId,
+      message:
+        'This harness exposes host tools through an HTTP MCP server, but ' +
+        'the ACP agent does not advertise support for HTTP MCP servers.',
+    });
+  }
+  if (relay.mcpUrl == null) {
+    throw new Error('The host tool MCP HTTP endpoint is unavailable.');
+  }
+  return {
+    type: 'http',
+    name: serverName,
+    url: relay.mcpUrl,
+    headers: [{ name: 'Authorization', value: `Bearer ${relay.credential}` }],
+  };
+}