@ai-sdk/harness-acp 1.0.39 → 1.0.41

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @ai-sdk/harness-acp
 
+## 1.0.41
+
+### Patch Changes
+
+- Updated dependencies [9e1d1b2]
+- Updated dependencies [a495511]
+  - @ai-sdk/provider-utils@5.0.37
+  - @ai-sdk/harness@1.0.103
+
+## 1.0.40
+
+### Patch Changes
+
+- ceb601c: fix(harness-acp): fix stream translator to match most appropriate tool based on input shape when no name is present and multiple candidates would match the required arguments
+- 255cccf: feat(harness): add `writeInstructions` helper and support filesystem based `instructionsMapping` in ACP backed harness adapters
+- 668b51d: fix(harness-acp): remove problematic condition that leads to errors when using `stopWhen`
+- eeed977: feat(harness): allow passing arbitrary headers with inference requests via `headers` property in `HarnessAgentSettings`
+- 1291df7: feat(harness-acp): support control over how host tools are exposed via `hostToolMcpTransport` config
+- a39c8bf: chore(harness): clarify `writeSkills` helper intent to require materializing skills in HOME directory
+- Updated dependencies [fe86f8f]
+- Updated dependencies [255cccf]
+- Updated dependencies [eeed977]
+- Updated dependencies [a39c8bf]
+  - @ai-sdk/harness@1.0.102
+
 ## 1.0.39
 
 ### Patch Changes

package/README.md

@@ -111,9 +111,10 @@ Use `instructionMapping` when the ACP implementation exposes a native system
 or developer prompt. A `session-meta` mapping writes `HarnessAgent`
 instructions below the ACP session request's `_meta` field. A
 `launch-env-json` mapping merges them into a JSON environment variable before
-the implementation starts. Without a mapping, the adapter preserves its
-backward-compatible behavior and prepends instructions to the first user
-prompt.
+the implementation starts. A `filesystem` mapping writes instructions to a
+markdown file at a relative path under the implementation's effective `$HOME`.
+Without a mapping, the adapter preserves its backward-compatible behavior and
+prepends instructions to the first user prompt.
 
 Skills are written to `.agents/skills` below the ACP implementation's effective
 `$HOME` and discovered natively by the implementation. Set `skillsDirectory`

package/dist/bridge/host-tool-mcp.mjs

@@ -12,7 +12,7 @@ import {
   ListToolsRequestSchema,
   McpError
 } from "@modelcontextprotocol/sdk/types.js";
-var VERSION = true ? "1.0.39" : "0.0.0-test";
+var VERSION = true ? "1.0.41" : "0.0.0-test";
 function createHostToolMCPServer({
   tools: tools2,
   revision = 1,

package/dist/bridge/index.mjs

@@ -664,7 +664,6 @@ function serialiseError(err) {
 import * as acp5 from "@agentclientprotocol/sdk";
 import { spawn } from "child_process";
 import { readFile, writeFile as writeFile2 } from "fs/promises";
-import { fileURLToPath } from "url";
 import { Readable, Writable } from "stream";
 import { argv, env as processEnv } from "process";
 
@@ -695,6 +694,10 @@ var profileValueSchema = z.lazy(
     z.record(z.string(), profileValueSchema)
   ])
 );
+var hostToolMcpTransportSchema = z.enum([
+  "stdio",
+  "http"
+]);
 var serializableRecordSchema = z.record(z.string(), serializableValueSchema);
 var profileRecordSchema = z.record(z.string(), profileValueSchema);
 var authenticationSchema = z.object({
@@ -715,7 +718,8 @@ var bridgeConfigurationSchema = z.object({
   providerEnvironment: z.record(z.string(), z.string()).optional(),
   sessionMeta: serializableRecordSchema.optional(),
   clientCapabilities: serializableRecordSchema.optional(),
-  askUserQuestionsRequestMethod: z.string().optional()
+  askUserQuestionsRequestMethod: z.string().optional(),
+  hostToolMcpTransport: hostToolMcpTransportSchema.optional()
 });
 async function readACPBridgeEnvironment({
   env
@@ -1417,7 +1421,24 @@ function resolveBuiltinTool({
   const schemaMatches = builtinTools.filter(
     (tool) => matchesBuiltinToolInput({ rawInput, inputSchema: tool.inputSchema })
   );
-  return schemaMatches.length === 1 ? schemaMatches[0] : void 0;
+  if (schemaMatches.length <= 1) return schemaMatches[0];
+  return findMostSpecificSchemaMatch({ rawInput, schemaMatches });
+}
+function findMostSpecificSchemaMatch({
+  rawInput,
+  schemaMatches
+}) {
+  if (!isRecord3(rawInput)) return void 0;
+  const rawInputKeys = Object.keys(rawInput);
+  const coverageOf = (tool) => {
+    const properties = isRecord3(tool.inputSchema) ? isRecord3(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] : void 0;
 }
 function findBuiltinToolByTitle({
   title,
@@ -2300,6 +2321,14 @@ async function resolveACPInstructionConfiguration({
   if (instructionMapping == null || instructions == null || instructions.length === 0) {
     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") {
     return {
@@ -2371,11 +2400,263 @@ function isRecord5(value) {
 }
 
 // src/v1/bridge/host-tool-relay.ts
-import { randomBytes, timingSafeEqual } from "crypto";
+import { randomBytes, randomUUID as randomUUID3, timingSafeEqual } from "crypto";
 import { createServer } from "http";
+
+// src/v1/bridge/host-tool-mcp-http.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+
+// src/v1/bridge/host-tool-mcp-server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError
+} from "@modelcontextprotocol/sdk/types.js";
+var VERSION = true ? "1.0.41" : "0.0.0-test";
+function createHostToolMCPServer({
+  tools,
+  revision = 1,
+  invoke,
+  onListTools
+}) {
+  let catalog = createCatalog({ revision, tools });
+  let catalogAcknowledgmentError;
+  const server = new Server(
+    {
+      name: "@ai-sdk/harness-acp-host-tools",
+      version: VERSION
+    },
+    { capabilities: { tools: { listChanged: true } } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    if (catalogAcknowledgmentError != null) {
+      throw catalogAcknowledgmentError;
+    }
+    const current = catalog;
+    if (onListTools != null) {
+      setImmediate(() => {
+        void onListTools({ revision: current.revision }).catch((error) => {
+          catalogAcknowledgmentError = error;
+        });
+      });
+    }
+    return { tools: current.tools.map(toMCPTool) };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const current = catalog;
+    const tool = current.byName.get(request.params.name);
+    if (tool == null) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `Unknown host tool: ${request.params.name}`
+      );
+    }
+    const input = request.params.arguments ?? {};
+    const result = await invoke({
+      toolName: tool.name,
+      input,
+      catalogRevision: current.revision
+    });
+    return toCallToolResult({ result });
+  });
+  return {
+    server,
+    updateCatalog: async ({ revision: nextRevision, tools: nextTools }) => {
+      catalog = createCatalog({
+        revision: nextRevision,
+        tools: nextTools
+      });
+      await server.sendToolListChanged();
+    }
+  };
+}
+function createCatalog({
+  revision,
+  tools
+}) {
+  return {
+    revision,
+    tools: [...tools],
+    byName: new Map(tools.map((tool) => [tool.name, tool]))
+  };
+}
+function toMCPTool(tool) {
+  return {
+    name: tool.name,
+    ...tool.description == null ? {} : { description: tool.description },
+    inputSchema: requireObjectSchema({
+      toolName: tool.name,
+      schema: tool.inputSchema ?? { type: "object" }
+    })
+  };
+}
+function requireObjectSchema({
+  toolName,
+  schema
+}) {
+  if (schema == null || typeof schema !== "object" || Array.isArray(schema) || Reflect.get(schema, "type") !== void 0 && Reflect.get(schema, "type") !== "object") {
+    throw new Error(
+      `Host tool ${toolName} must use an object JSON Schema for MCP.`
+    );
+  }
+  return schema;
+}
+function toCallToolResult({
+  result
+}) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: stringifyOutput({ output: result.output })
+      }
+    ],
+    ...result.isError ? { isError: true } : {},
+    _meta: {
+      "ai-sdk-harness-acp-correlation": result.correlationToken
+    }
+  };
+}
+function stringifyOutput({ output }) {
+  if (output === void 0) return "null";
+  try {
+    return JSON.stringify(output);
+  } catch {
+    return JSON.stringify({
+      error: "Host tool output could not be serialized as JSON."
+    });
+  }
+}
+
+// src/v1/bridge/host-tool-mcp-http.ts
+var HOST_TOOL_MCP_ENDPOINT_PATH = "/mcp";
+function createHostToolMCPHttpEndpoint({
+  tools,
+  revision,
+  invoke,
+  onListTools
+}) {
+  let catalog = { revision, tools: [...tools] };
+  const sessions = /* @__PURE__ */ new Map();
+  let closed = false;
+  async function openSession({
+    request,
+    response,
+    body
+  }) {
+    const hostToolServer = createHostToolMCPServer({
+      tools: catalog.tools,
+      revision: catalog.revision,
+      invoke,
+      onListTools
+    });
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID2(),
+      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: -32e3,
+          message: "The host tool MCP endpoint is closed."
+        });
+        return;
+      }
+      const sessionId = readSessionId({ request });
+      if (sessionId != null) {
+        const session2 = sessions.get(sessionId);
+        if (session2 == null) {
+          respondWithJSONRPCError({
+            response,
+            status: 404,
+            code: -32001,
+            message: "Unknown host tool MCP session."
+          });
+          return;
+        }
+        await session2.transport.handleRequest(request, response, body);
+        return;
+      }
+      if (request.method !== "POST" || !isInitializeRequest(body)) {
+        respondWithJSONRPCError({
+          response,
+          status: 400,
+          code: -32e3,
+          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(
+          (session2) => session2.hostToolServer.updateCatalog({
+            revision: nextRevision,
+            tools: nextTools
+          })
+        )
+      );
+    },
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      const live = [...sessions.values()];
+      sessions.clear();
+      await Promise.all(
+        live.map((session2) => session2.hostToolServer.server.close())
+      );
+    }
+  };
+}
+function readSessionId({
+  request
+}) {
+  const value = request.headers["mcp-session-id"];
+  const sessionId = Array.isArray(value) ? value[0] : value;
+  return sessionId == null || sessionId.length === 0 ? void 0 : sessionId;
+}
+function respondWithJSONRPCError({
+  response,
+  status,
+  code,
+  message
+}) {
+  response.writeHead(status, { "content-type": "application/json" });
+  response.end(
+    JSON.stringify({
+      jsonrpc: "2.0",
+      error: { code, message },
+      id: null
+    })
+  );
+}
+
+// src/v1/bridge/host-tool-relay.ts
 async function startHostToolRelay({
   tools,
-  serverName
+  serverName,
+  mcpTransport = "stdio"
 }) {
   const state = {
     tools: [...tools],
@@ -2390,8 +2671,44 @@ async function startHostToolRelay({
   let activeTurn;
   let invocationOrder = 0;
   let closePromise;
+  const mcpEndpoint = mcpTransport === "http" ? createHostToolMCPHttpEndpoint({
+    tools: state.tools,
+    revision: state.revision,
+    invoke: ({ toolName, input, catalogRevision }) => handleInvocation({
+      body: {
+        requestId: randomUUID3(),
+        toolName,
+        input,
+        catalogRevision
+      },
+      state,
+      serverName,
+      turn: activeTurn,
+      nextInvocationOrder: () => ++invocationOrder
+    }),
+    onListTools: async ({ revision }) => {
+      acknowledgeCatalog({ state, revision });
+    }
+  }) : void 0;
   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,
@@ -2403,6 +2720,10 @@ 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(
@@ -2416,6 +2737,9 @@ async function startHostToolRelay({
   const address = server.address();
   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) {
@@ -2435,6 +2759,10 @@ 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 }) => waitForCatalogRefresh({ state, revision, timeoutMs }),
@@ -2443,7 +2771,10 @@ 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;
     }
   };
@@ -2521,13 +2852,16 @@ function handleCatalogSeen({
       message: "Invalid host tool catalog acknowledgment."
     });
   }
-  state.servedRevision = Math.max(
-    state.servedRevision,
-    body.revision
-  );
-  resolveRefreshWaiters({ state, closing: false });
+  acknowledgeCatalog({ state, revision: body.revision });
   return { acknowledged: true };
 }
+function acknowledgeCatalog({
+  state,
+  revision
+}) {
+  state.servedRevision = Math.max(state.servedRevision, revision);
+  resolveRefreshWaiters({ state, closing: false });
+}
 async function handleInvocation({
   body,
   state,
@@ -2726,6 +3060,55 @@ var RelayRequestError = class extends Error {
   }
 };
 
+// src/v1/bridge/host-tool-mcp-definition.ts
+import { fileURLToPath } from "url";
+import { execPath } from "process";
+function createHostToolMcpServerDefinition({
+  mcpTransport,
+  relay,
+  serverName,
+  catalogPath,
+  initialization,
+  harnessId
+}) {
+  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}` }]
+  };
+}
+
 // src/v1/bridge/refresh-host-tool-catalog.ts
 async function promptAndRefreshInitialHostToolCatalog({
   startPrompt,
@@ -3654,33 +4037,26 @@ async function ensureSession({
     initialization
   });
   const tools = start.tools ?? [];
+  const mcpTransport = bridgeConfiguration.hostToolMcpTransport ?? "stdio";
   const catalogPath = `${bridgeStateDir}/host-tools.json`;
-  await writeFile2(catalogPath, JSON.stringify(tools), { mode: 384 });
+  if (mcpTransport === "stdio") {
+    await writeFile2(catalogPath, JSON.stringify(tools), { mode: 384 });
+  }
   hostToolRelay = await startHostToolRelay({
     tools,
-    serverName: HOST_TOOL_MCP_SERVER_NAME
+    serverName: HOST_TOOL_MCP_SERVER_NAME,
+    mcpTransport
   });
   const mcpServers = [
     ...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;
   if (start.recoveryMode?.type === "lossy-rerun") {