@ai-sdk/harness-acp 1.0.39 → 1.0.41

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

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,
@@ -593,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') {

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

@@ -526,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

@@ -4,6 +4,7 @@ export type {
   ACPCredentialBrokering,
   ACPAuthentication,
   ACPAuthenticationMode,
+  ACPHostToolMCPTransport,
   ACPInstallCommandSource,
   ACPInstructionMapping,
   ACPModelMapping,