@ai-sdk/harness-acp 1.0.38 → 1.0.40

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

@@ -1,7 +1,13 @@
-import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { createServer, type IncomingMessage, type Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import type { HarnessV1BridgeToolWire } from '@ai-sdk/harness';
+import type { ACPHostToolMCPTransport } from '../acp-v1-settings';
+import {
+  createHostToolMCPHttpEndpoint,
+  HOST_TOOL_MCP_ENDPOINT_PATH,
+  type HostToolMCPHttpEndpoint,
+} from './host-tool-mcp-http';
 
 export type HostToolCorrelationInvocation = {
   readonly token: string;
@@ -34,6 +40,11 @@ export type HostToolRelayTurn = {
 
 export type HostToolRelay = {
   readonly url: string;
+  /**
+   * MCP endpoint that exposes the host tool catalog over Streamable HTTP.
+   * Only present when the relay was started with the `http` MCP transport.
+   */
+  readonly mcpUrl?: string;
   readonly credential: string;
   bindTurn(options: { turn: HostToolRelayTurn }): void;
   unbindTurn(options: { turn: HostToolRelayTurn }): void;
@@ -64,9 +75,11 @@ type CatalogState = {
 export async function startHostToolRelay({
   tools,
   serverName,
+  mcpTransport = 'stdio',
 }: {
   tools: ReadonlyArray<HarnessV1BridgeToolWire>;
   serverName: string;
+  mcpTransport?: ACPHostToolMCPTransport;
 }): Promise<HostToolRelay> {
   const state: CatalogState = {
     tools: [...tools],
@@ -81,8 +94,52 @@ export async function startHostToolRelay({
   let activeTurn: HostToolRelayTurn | undefined;
   let invocationOrder = 0;
   let closePromise: Promise<void> | undefined;
+  const mcpEndpoint: HostToolMCPHttpEndpoint | undefined =
+    mcpTransport === 'http'
+      ? createHostToolMCPHttpEndpoint({
+          tools: state.tools,
+          revision: state.revision,
+          invoke: ({ toolName, input, catalogRevision }) =>
+            handleInvocation({
+              body: {
+                requestId: randomUUID(),
+                toolName,
+                input,
+                catalogRevision,
+              },
+              state,
+              serverName,
+              turn: activeTurn,
+              nextInvocationOrder: () => ++invocationOrder,
+            }),
+          onListTools: async ({ revision }) => {
+            acknowledgeCatalog({ state, revision });
+          },
+        })
+      : undefined;
   const server = createServer(async (request, response) => {
     try {
+      if (mcpEndpoint != null && request.url === HOST_TOOL_MCP_ENDPOINT_PATH) {
+        if (
+          !credentialsMatch({
+            expected: credential,
+            actual: request.headers.authorization,
+          })
+        ) {
+          throw new RelayRequestError({
+            status: 401,
+            message: 'Invalid host tool relay credential.',
+          });
+        }
+        await mcpEndpoint.handleRequest({
+          request,
+          response,
+          ...(request.method === 'POST'
+            ? { body: await readJSONBody({ request }) }
+            : {}),
+        });
+        return;
+      }
       const result = await handleRequest({
         request,
         credential,
@@ -94,6 +151,10 @@ export async function startHostToolRelay({
       response.writeHead(200, { 'content-type': 'application/json' });
       response.end(JSON.stringify(result));
     } catch (error) {
+      if (response.headersSent) {
+        response.end();
+        return;
+      }
       const status = error instanceof RelayRequestError ? error.status : 500;
       response.writeHead(status, { 'content-type': 'application/json' });
       response.end(
@@ -108,6 +169,11 @@ export async function startHostToolRelay({
 
   return {
     url: `http://127.0.0.1:${address.port}/invoke`,
+    ...(mcpEndpoint == null
+      ? {}
+      : {
+          mcpUrl: `http://127.0.0.1:${address.port}${HOST_TOOL_MCP_ENDPOINT_PATH}`,
+        }),
     credential,
     bindTurn: ({ turn }) => {
       if (activeTurn != null && activeTurn !== turn) {
@@ -127,6 +193,10 @@ export async function startHostToolRelay({
       state.fingerprint = fingerprint;
       state.revision += 1;
       resolveCatalogChanges({ state });
+      void mcpEndpoint?.updateCatalog({
+        revision: state.revision,
+        tools: state.tools,
+      });
       return { changed: true, revision: state.revision };
     },
     waitForCatalogRefresh: ({ revision, timeoutMs }) =>
@@ -136,7 +206,10 @@ export async function startHostToolRelay({
       state.closed = true;
       resolveCatalogChanges({ state });
       resolveRefreshWaiters({ state, closing: true });
-      closePromise = closeServer({ server });
+      closePromise = (async () => {
+        await mcpEndpoint?.close();
+        await closeServer({ server });
+      })();
       return closePromise;
     },
   };
@@ -243,14 +316,21 @@ function handleCatalogSeen({
       message: 'Invalid host tool catalog acknowledgment.',
     });
   }
-  state.servedRevision = Math.max(
-    state.servedRevision,
-    body.revision as number,
-  );
-  resolveRefreshWaiters({ state, closing: false });
+  acknowledgeCatalog({ state, revision: body.revision as number });
   return { acknowledged: true };
 }
 
+function acknowledgeCatalog({
+  state,
+  revision,
+}: {
+  state: CatalogState;
+  revision: number;
+}): void {
+  state.servedRevision = Math.max(state.servedRevision, revision);
+  resolveRefreshWaiters({ state, closing: false });
+}
+
 async function handleInvocation({
   body,
   state,

package/src/v1/bridge/index.ts

@@ -7,7 +7,6 @@ import {
 import * as acp from '@agentclientprotocol/sdk';
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { readFile, writeFile } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
 import { Readable, Writable } from 'node:stream';
 import { argv, env as processEnv } from 'node:process';
 import {
@@ -38,6 +37,7 @@ import {
   type HostToolRelay,
   type HostToolRelayTurn,
 } from './host-tool-relay';
+import { createHostToolMcpServerDefinition } from './host-tool-mcp-definition';
 import {
   promptAndRefreshInitialHostToolCatalog,
   refreshHostToolCatalog,
@@ -104,6 +104,13 @@ let coldRestorationMethod: ACPSessionRestorationMethod | undefined;
 let activePermissionController:
   | ReturnType<typeof createACPPermissionController>
   | undefined;
+let activeQuestionRequest:
+  | {
+      method: string;
+      turn: BridgeTurn;
+      emitStreamEvent: ReturnType<typeof createEmitStreamEvent>;
+    }
+  | undefined;
 
 await runBridge<StartMessage>({
   bridgeType,
@@ -252,15 +259,36 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
   const emitStreamEvent = createEmitStreamEvent({
     emit: event => turn.emit(event as BridgeEvent),
     emitToolCallCandidate: ({ toolCall }) => {
+      const requestId = crypto.randomUUID();
       turn.emit({
         type: 'acp-tool-call-candidate',
+        requestId,
         toolCall,
       });
+      void turn.requestToolResult(requestId).then(result => {
+        if (
+          result.output != null &&
+          typeof result.output === 'object' &&
+          'suppress' in result.output &&
+          result.output.suppress === true
+        ) {
+          emitStreamEvent.suppressToolCall({
+            toolCallId: toolCall.toolCallId,
+          });
+        }
+      });
     },
     builtinTools: start.builtinTools,
     hostToolServerName: HOST_TOOL_MCP_SERVER_NAME,
     hostTools: start.tools ?? [],
   });
+  if (bridgeConfiguration.askUserQuestionsRequestMethod != null) {
+    activeQuestionRequest = {
+      method: bridgeConfiguration.askUserQuestionsRequestMethod,
+      turn,
+      emitStreamEvent,
+    };
+  }
   const permissionController = createACPPermissionController({
     turn,
     sessionId: activeSession.sessionId,
@@ -353,6 +381,9 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
       if (emitStreamEvent.message({ message })) return;
     }
   } finally {
+    if (activeQuestionRequest?.turn === turn) {
+      activeQuestionRequest = undefined;
+    }
     permissionController.cancelAll();
     activePermissionController = undefined;
     activeHostToolRelay.unbindTurn({ turn: relayTurn });
@@ -458,7 +489,7 @@ async function ensureSession({
     stream: acp.ndJsonStream(input, output),
   });
   streamCapture = capturedStream.capture;
-  connection = acp
+  let client = acp
     .client({ name: clientApp.name })
     .onRequest(
       acp.methods.client.session.requestPermission,
@@ -475,8 +506,58 @@ async function ensureSession({
         notification: params,
         update: params.update,
       });
-    })
-    .connect(capturedStream.stream);
+    });
+  if (bridgeConfiguration.askUserQuestionsRequestMethod != null) {
+    const method = bridgeConfiguration.askUserQuestionsRequestMethod;
+    client = client.onRequest<unknown, unknown>(
+      method,
+      value => value,
+      async ({ params }) => {
+        const active = activeQuestionRequest;
+        if (active == null || active.method !== method) {
+          throw acp.RequestError.methodNotFound(method);
+        }
+        const requestId = crypto.randomUUID();
+        const nativeToolCallId = getNativeQuestionToolCallId({ params });
+        active.turn.emit({
+          type: 'acp-question-request',
+          requestId,
+          nativeRequest: params,
+          ...(nativeToolCallId == null
+            ? {}
+            : {
+                nativeToolCall:
+                  active.emitStreamEvent.getToolCall({
+                    toolCallId: nativeToolCallId,
+                  }) ?? undefined,
+              }),
+        });
+        const result = await active.turn.requestToolResult(requestId);
+        const classification = result.output as
+          | { type: 'unhandled' }
+          | { type: 'handled'; toolCallId: string }
+          | undefined;
+        if (classification?.type !== 'handled') {
+          throw acp.RequestError.methodNotFound(method);
+        }
+        active.emitStreamEvent.suppressToolCall({
+          toolCallId: nativeToolCallId ?? classification.toolCallId,
+        });
+        try {
+          const nativeResult = await active.turn.requestToolResult(
+            classification.toolCallId,
+          );
+          return nativeResult.output;
+        } finally {
+          active.turn.emit({
+            type: 'acp-question-resolved',
+            requestId,
+          });
+        }
+      },
+    );
+  }
+  connection = client.connect(capturedStream.stream);
 
   const initializeRequest = createACPInitializeRequest({
     protocolVersion: acp.PROTOCOL_VERSION,
@@ -512,34 +593,27 @@ async function ensureSession({
     initialization,
   });
   const tools = start.tools ?? [];
+  const mcpTransport = bridgeConfiguration.hostToolMcpTransport ?? 'stdio';
   const catalogPath = `${bridgeStateDir}/host-tools.json`;
-  await writeFile(catalogPath, JSON.stringify(tools), { mode: 0o600 });
+  if (mcpTransport === 'stdio') {
+    await writeFile(catalogPath, JSON.stringify(tools), { mode: 0o600 });
+  }
   hostToolRelay = await startHostToolRelay({
     tools,
     serverName: HOST_TOOL_MCP_SERVER_NAME,
+    mcpTransport,
   });
 
   const mcpServers: acp.McpServer[] = [
     ...externalMcpServers,
-    {
-      name: HOST_TOOL_MCP_SERVER_NAME,
-      command: process.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: hostToolRelay.url,
-        },
-        {
-          name: 'AI_SDK_ACP_HOST_TOOL_RELAY_CREDENTIAL',
-          value: hostToolRelay.credential,
-        },
-      ],
-    },
+    createHostToolMcpServerDefinition({
+      mcpTransport,
+      relay: hostToolRelay,
+      serverName: HOST_TOOL_MCP_SERVER_NAME,
+      catalogPath,
+      initialization,
+      harnessId: bridgeType,
+    }),
   ];
   let createdSession: ACPActiveSession;
   if (start.recoveryMode?.type === 'lossy-rerun') {
@@ -627,6 +701,19 @@ async function ensureSession({
   return { initialHostToolCatalogRefreshRequired: tools.length > 0 };
 }
 
+function getNativeQuestionToolCallId({
+  params,
+}: {
+  params: unknown;
+}): string | undefined {
+  if (!isRecord(params)) return undefined;
+  if (typeof params.toolCallId === 'string') return params.toolCallId;
+  const nestedParams = params.params;
+  return isRecord(nestedParams) && typeof nestedParams.toolCallId === 'string'
+    ? nestedParams.toolCallId
+    : undefined;
+}
+
 function createExternalMcpServers({
   mcpServers,
   initialization,

package/src/v1/bridge/instruction-mapping.ts

@@ -33,6 +33,18 @@ export async function resolveACPInstructionConfiguration({
     return { sessionMeta, environment: resolvedEnvironment };
   }
 
+  if (instructionMapping.type === 'filesystem') {
+    if (
+      typeof instructionMapping.path !== 'string' ||
+      instructionMapping.path.trim().length === 0
+    ) {
+      throw new Error(
+        'ACP instruction mapping filesystem path must be a non-empty string.',
+      );
+    }
+    return { sessionMeta, environment: resolvedEnvironment };
+  }
+
   assertSafePath({ path: instructionMapping.path });
 
   if (instructionMapping.type === 'session-meta') {

package/src/v1/bridge/stream-translator.ts

@@ -68,6 +68,7 @@ export function createACPStreamTranslator({
     output: unknown;
     isError?: boolean;
   }) => void;
+  getToolCall: (options: { toolCallId: string }) => ACPToolCall | undefined;
 } {
   let openBlock:
     | {
@@ -215,6 +216,7 @@ export function createACPStreamTranslator({
         builtinTools,
         builtinToolsByName,
       });
+      emitToolCallCandidate?.({ toolCall: createACPToolCall({ state }) });
       if (
         !forceEmit &&
         builtin?.inputSchema != null &&
@@ -238,7 +240,6 @@ export function createACPStreamTranslator({
           programmaticName,
           toolCallId: state.toolCallId,
         });
-        emitToolCallCandidate?.({ toolCall: createACPToolCall({ state }) });
       }
       emit({
         type: 'tool-call',
@@ -381,6 +382,10 @@ export function createACPStreamTranslator({
     close: closeBlock,
     hostToolCall,
     hostToolResult,
+    getToolCall: ({ toolCallId }) => {
+      const state = toolStates.get(toolCallId);
+      return state == null ? undefined : createACPToolCall({ state });
+    },
     finish: response => {
       if (finished) return;
       finished = true;
@@ -521,7 +526,41 @@ function resolveBuiltinTool({
   const schemaMatches = builtinTools.filter(tool =>
     matchesBuiltinToolInput({ rawInput, inputSchema: tool.inputSchema }),
   );
-  return schemaMatches.length === 1 ? schemaMatches[0] : undefined;
+  if (schemaMatches.length <= 1) return schemaMatches[0];
+  return findMostSpecificSchemaMatch({ rawInput, schemaMatches });
+}
+
+/*
+ * Multiple schemas can pass `matchesBuiltinToolInput` at once: a tool whose
+ * only required field is optional on a richer sibling tool (e.g. `bash`'s
+ * optional `shellId` versus `stop_bash`'s required `shellId`) matches any
+ * rawInput the richer tool also matches. Preferring whichever candidate
+ * declares the most of rawInput's own keys resolves that in favor of the
+ * richer, more specific schema, while two equally specific schemas (e.g.
+ * identical schemas under different names) still resolve to `undefined`.
+ */
+function findMostSpecificSchemaMatch({
+  rawInput,
+  schemaMatches,
+}: {
+  rawInput: unknown;
+  schemaMatches: ReadonlyArray<ACPBuiltinToolMapping>;
+}): ACPBuiltinToolMapping | undefined {
+  if (!isRecord(rawInput)) return undefined;
+  const rawInputKeys = Object.keys(rawInput);
+  const coverageOf = (tool: ACPBuiltinToolMapping): number => {
+    const properties = isRecord(tool.inputSchema)
+      ? isRecord(tool.inputSchema.properties)
+        ? tool.inputSchema.properties
+        : {}
+      : {};
+    return rawInputKeys.filter(key => key in properties).length;
+  };
+  const highestCoverage = Math.max(...schemaMatches.map(coverageOf));
+  const mostSpecificMatches = schemaMatches.filter(
+    tool => coverageOf(tool) === highestCoverage,
+  );
+  return mostSpecificMatches.length === 1 ? mostSpecificMatches[0] : undefined;
 }
 
 function findBuiltinToolByTitle({

package/src/v1/index.ts

@@ -1,8 +1,10 @@
 export { createACPV1 } from './acp-v1-harness';
 export type {
+  ACPAskUserQuestionsSettings,
   ACPCredentialBrokering,
   ACPAuthentication,
   ACPAuthenticationMode,
+  ACPHostToolMCPTransport,
   ACPInstallCommandSource,
   ACPInstructionMapping,
   ACPModelMapping,