@ai-sdk/harness-acp 1.0.38 → 1.0.40

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

@@ -3,7 +3,9 @@ import type {
   HarnessV1CredentialForwarding,
   HarnessV1PermissionMode,
   HarnessV1RequestTransformation,
+  HarnessV1StreamPart,
 } from '@ai-sdk/harness';
+import type { ToolResultPart } from '@ai-sdk/provider-utils';
 import type { ACPToolCall } from '../acp-tool-call';
 
 export type ACPSerializablePrimitive = string | number | boolean | null;
@@ -88,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 =
@@ -122,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 = {
@@ -129,6 +137,31 @@ 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: {
+    nativeToolCall: ACPToolCall;
+  }) => boolean;
+  readonly fromNativeRequest: (options: {
+    nativeRequest: unknown;
+    nativeToolCall?: ACPToolCall;
+  }) => Extract<HarnessV1StreamPart, { type: 'tool-call' }> | null;
+  readonly toNativeResponse: (options: {
+    nativeRequest: unknown;
+    toolResult: ToolResultPart;
+  }) => unknown;
+  readonly matchesNativeRequest?: (options: {
+    previousNativeRequest: unknown;
+    nativeRequest: unknown;
+  }) => boolean;
+};
+
 export type ACPV1Settings = {
   readonly version?: 'v1';
   readonly harnessId: string;
@@ -179,6 +212,15 @@ 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?: {
     readonly meta?: Readonly<Record<string, ACPSerializableValue>>;

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);
 
@@ -60,6 +66,8 @@ export type ACPBridgeConfiguration = {
   readonly providerEnvironment?: Readonly<Record<string, string>>;
   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({
@@ -68,6 +76,8 @@ const bridgeConfigurationSchema: z.ZodType<ACPBridgeConfiguration> = z.object({
   providerEnvironment: z.record(z.string(), z.string()).optional(),
   sessionMeta: serializableRecordSchema.optional(),
   clientCapabilities: serializableRecordSchema.optional(),
+  askUserQuestionsRequestMethod: z.string().optional(),
+  hostToolMcpTransport: hostToolMcpTransportSchema.optional(),
 });
 
 export function createACPBridgeEnvironment({
@@ -76,6 +86,8 @@ export function createACPBridgeEnvironment({
   providerEnvironment,
   sessionMeta,
   clientCapabilities,
+  askUserQuestionsRequestMethod,
+  hostToolMcpTransport,
 }: ACPBridgeConfiguration): Record<string, string> {
   return {
     [ACP_BRIDGE_CONFIGURATION_ENV]: JSON.stringify({
@@ -84,6 +96,10 @@ export function createACPBridgeEnvironment({
       ...(providerEnvironment == null ? {} : { providerEnvironment }),
       ...(sessionMeta == null ? {} : { sessionMeta }),
       ...(clientCapabilities == null ? {} : { clientCapabilities }),
+      ...(askUserQuestionsRequestMethod == null
+        ? {}
+        : { askUserQuestionsRequestMethod }),
+      ...(hostToolMcpTransport == null ? {} : { hostToolMcpTransport }),
     }),
   };
 }

package/src/v1/bridge/create-emit-stream-event.ts

@@ -51,6 +51,8 @@ export function createEmitStreamEvent({
     order: number;
   }) => void;
   removeHostToolCorrelationInvocation: (options: { token: string }) => void;
+  suppressToolCall: (options: { toolCallId: string }) => void;
+  getToolCall: (options: { toolCallId: string }) => ACPToolCall | undefined;
 } {
   const translator = createACPStreamTranslator({
     emit,
@@ -100,5 +102,9 @@ export function createEmitStreamEvent({
     hostToolResult: translator.hostToolResult,
     registerHostToolCorrelationInvocation: correlation.registerInvocation,
     removeHostToolCorrelationInvocation: correlation.removeInvocation,
+    suppressToolCall: correlation.suppressToolCall,
+    getToolCall: ({ toolCallId }) =>
+      correlation.getToolCall({ toolCallId }) ??
+      translator.getToolCall({ toolCallId }),
   };
 }

package/src/v1/bridge/host-tool-correlation.ts

@@ -2,6 +2,7 @@ import type {
   ActiveSessionMessage,
   ToolCallUpdate,
 } from '@agentclientprotocol/sdk';
+import type { ACPToolCall } from '../../acp-tool-call';
 
 type SessionUpdateMessage = Extract<
   ActiveSessionMessage,
@@ -55,6 +56,8 @@ export function createHostToolCorrelation({
     order: number;
   }): void;
   claimHostToolPermission(options: { toolCall: ToolCallUpdate }): boolean;
+  suppressToolCall(options: { toolCallId: string }): void;
+  getToolCall(options: { toolCallId: string }): ACPToolCall | undefined;
   flush(): void;
   removeInvocation(options: { token: string }): void;
   close(): void;
@@ -63,6 +66,7 @@ export function createHostToolCorrelation({
   const candidates = new Map<string, CorrelationCandidate>();
   const suppressedToolCallIds = new Set<string>();
   const releasedToolCallIds = new Set<string>();
+  const observedToolCalls = new Map<string, ACPToolCall>();
   let nextCandidateOrder = 0;
   let buffered: BufferedUpdate[] = [];
   let flushTimer: ReturnType<typeof setTimeout> | undefined;
@@ -155,6 +159,13 @@ export function createHostToolCorrelation({
       }
 
       const toolCallId = message.update.toolCallId;
+      observedToolCalls.set(
+        toolCallId,
+        mergeObservedToolCall({
+          previous: observedToolCalls.get(toolCallId),
+          update: message.update,
+        }),
+      );
       if (suppressedToolCallIds.has(toolCallId)) {
         if (isTerminalToolUpdate(message)) {
           suppressedToolCallIds.delete(toolCallId);
@@ -242,6 +253,8 @@ export function createHostToolCorrelation({
       suppressToolCallUpdate({ toolCallId: toolCall.toolCallId });
       return true;
     },
+    suppressToolCall: suppressToolCallUpdate,
+    getToolCall: ({ toolCallId }) => observedToolCalls.get(toolCallId),
     flush,
     removeInvocation: ({ token }) => {
       deleteInvocation({ invocations, token });
@@ -257,10 +270,31 @@ export function createHostToolCorrelation({
       candidates.clear();
       suppressedToolCallIds.clear();
       releasedToolCallIds.clear();
+      observedToolCalls.clear();
     },
   };
 }
 
+function mergeObservedToolCall({
+  previous,
+  update,
+}: {
+  previous: ACPToolCall | undefined;
+  update: ToolCallUpdate;
+}): ACPToolCall {
+  return {
+    toolCallId: update.toolCallId,
+    title: update.title ?? previous?.title ?? `Tool ${update.toolCallId}`,
+    ...(update.kind == null ? {} : { kind: update.kind }),
+    ...(update.status == null ? {} : { status: update.status }),
+    ...(update.content == null ? {} : { content: update.content }),
+    ...(update.locations == null ? {} : { locations: update.locations }),
+    ...(update.rawInput === undefined ? {} : { rawInput: update.rawInput }),
+    ...(update.rawOutput === undefined ? {} : { rawOutput: update.rawOutput }),
+    ...(update._meta === undefined ? {} : { _meta: update._meta }),
+  };
+}
+
 function hasPortableEvidence({
   candidate,
   invocation,

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}` }],
+  };
+}

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

@@ -0,0 +1,182 @@
+import { randomUUID } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { HarnessV1BridgeToolWire } from '@ai-sdk/harness';
+import {
+  createHostToolMCPServer,
+  type HostToolMCPInvocationResult,
+  type HostToolMCPServer,
+} from './host-tool-mcp-server';
+
+export const HOST_TOOL_MCP_ENDPOINT_PATH = '/mcp';
+
+export type HostToolMCPHttpEndpoint = {
+  handleRequest(options: {
+    request: IncomingMessage;
+    response: ServerResponse;
+    body?: unknown;
+  }): Promise<void>;
+  updateCatalog(options: {
+    revision: number;
+    tools: ReadonlyArray<HarnessV1BridgeToolWire>;
+  }): Promise<void>;
+  close(): Promise<void>;
+};
+
+type EndpointSession = {
+  readonly transport: StreamableHTTPServerTransport;
+  readonly hostToolServer: HostToolMCPServer;
+};
+
+/*
+ * The ACP host tool catalog is shared by every MCP session opened against this
+ * endpoint. Each session needs its own MCP `Server` instance because a server
+ * can be connected to a single transport at a time, so catalog updates are
+ * fanned out to all live sessions and also retained for sessions opened later.
+ */
+export function createHostToolMCPHttpEndpoint({
+  tools,
+  revision,
+  invoke,
+  onListTools,
+}: {
+  tools: ReadonlyArray<HarnessV1BridgeToolWire>;
+  revision: number;
+  invoke: (options: {
+    toolName: string;
+    input: Readonly<Record<string, unknown>>;
+    catalogRevision: number;
+  }) => Promise<HostToolMCPInvocationResult>;
+  onListTools: (options: { revision: number }) => Promise<void>;
+}): HostToolMCPHttpEndpoint {
+  let catalog: {
+    revision: number;
+    tools: ReadonlyArray<HarnessV1BridgeToolWire>;
+  } = { revision, tools: [...tools] };
+  const sessions = new Map<string, EndpointSession>();
+  let closed = false;
+
+  async function openSession({
+    request,
+    response,
+    body,
+  }: {
+    request: IncomingMessage;
+    response: ServerResponse;
+    body: unknown;
+  }): Promise<void> {
+    const hostToolServer = createHostToolMCPServer({
+      tools: catalog.tools,
+      revision: catalog.revision,
+      invoke,
+      onListTools,
+    });
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: sessionId => {
+        sessions.set(sessionId, { transport, hostToolServer });
+      },
+      onsessionclosed: sessionId => {
+        sessions.delete(sessionId);
+      },
+    });
+    transport.onclose = () => {
+      const { sessionId } = transport;
+      if (sessionId != null) sessions.delete(sessionId);
+    };
+    await hostToolServer.server.connect(transport);
+    await transport.handleRequest(request, response, body);
+  }
+
+  return {
+    handleRequest: async ({ request, response, body }) => {
+      if (closed) {
+        respondWithJSONRPCError({
+          response,
+          status: 503,
+          code: -32000,
+          message: 'The host tool MCP endpoint is closed.',
+        });
+        return;
+      }
+      const sessionId = readSessionId({ request });
+      if (sessionId != null) {
+        const session = sessions.get(sessionId);
+        if (session == null) {
+          respondWithJSONRPCError({
+            response,
+            status: 404,
+            code: -32001,
+            message: 'Unknown host tool MCP session.',
+          });
+          return;
+        }
+        await session.transport.handleRequest(request, response, body);
+        return;
+      }
+      if (request.method !== 'POST' || !isInitializeRequest(body)) {
+        respondWithJSONRPCError({
+          response,
+          status: 400,
+          code: -32000,
+          message:
+            'Host tool MCP requests without a session id must be an initialize request.',
+        });
+        return;
+      }
+      await openSession({ request, response, body });
+    },
+    updateCatalog: async ({ revision: nextRevision, tools: nextTools }) => {
+      catalog = { revision: nextRevision, tools: [...nextTools] };
+      await Promise.all(
+        [...sessions.values()].map(session =>
+          session.hostToolServer.updateCatalog({
+            revision: nextRevision,
+            tools: nextTools,
+          }),
+        ),
+      );
+    },
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      const live = [...sessions.values()];
+      sessions.clear();
+      await Promise.all(
+        live.map(session => session.hostToolServer.server.close()),
+      );
+    },
+  };
+}
+
+function readSessionId({
+  request,
+}: {
+  request: IncomingMessage;
+}): string | undefined {
+  const value = request.headers['mcp-session-id'];
+  const sessionId = Array.isArray(value) ? value[0] : value;
+  return sessionId == null || sessionId.length === 0 ? undefined : sessionId;
+}
+
+function respondWithJSONRPCError({
+  response,
+  status,
+  code,
+  message,
+}: {
+  response: ServerResponse;
+  status: number;
+  code: number;
+  message: string;
+}): void {
+  response.writeHead(status, { 'content-type': 'application/json' });
+  response.end(
+    JSON.stringify({
+      jsonrpc: '2.0',
+      error: { code, message },
+      id: null,
+    }),
+  );
+}