@ai-sdk/harness-acp 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @ai-sdk/harness-acp
 
+## 1.0.3
+
+### Patch Changes
+
+- 9ee30bf: fix(harness): pass instructions appended to system / developer prompt instead of using the workaround of first user prompt
+- Updated dependencies [9ee30bf]
+  - @ai-sdk/harness@1.0.66
+
+## 1.0.2
+
+### Patch Changes
+
+- a03ff6c: feat(harness): add support for per-harness MCP servers
+- fc3baaf: feat(harness): add optional `mintBridgeToken(sandboxId)` to harness settings to control the bridge token value
+- Updated dependencies [401a4ba]
+- Updated dependencies [a03ff6c]
+  - @ai-sdk/provider-utils@5.0.26
+  - @ai-sdk/harness@1.0.65
+
 ## 1.0.1
 
 ### Patch Changes

package/README.md

@@ -34,6 +34,11 @@ const codexACP = createACP({
   },
   executable: 'codex-acp',
   forwardEnv: ['CODEX_API_KEY', 'OPENAI_API_KEY'],
+  instructionMapping: {
+    type: 'launch-env-json',
+    variable: 'CODEX_CONFIG',
+    path: ['developer_instructions'],
+  },
   permissionModeMapping: {
     'allow-reads': null,
     'allow-edits': null,
@@ -69,3 +74,11 @@ resolves the value when the ACP process starts and does not store it in the
 profile. Codex ACP supports only `permissionMode: 'allow-all'` because its
 restrictive modes enable Codex's internal sandbox. A bridge-backed ACP harness
 requires a sandbox with at least one exposed port.
+
+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.

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

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

package/dist/bridge/index.mjs

@@ -890,6 +890,7 @@ function monitorACPAgentStderr({
 // src/v1/bridge/stream-translator.ts
 function createACPStreamTranslator({
   emit,
+  emitToolCallCandidate,
   builtinTools = []
 }) {
   let openBlock;
@@ -1000,13 +1001,12 @@ function createACPStreamTranslator({
       if (builtin != null) {
         state.toolName = builtin.toolName;
         state.nativeName = builtin.nativeName != null && builtin.toolName !== builtin.nativeName ? builtin.nativeName : void 0;
-        state.dynamic = false;
       } else {
         state.toolName = createDynamicToolName({
           programmaticName,
           toolCallId: state.toolCallId
         });
-        state.dynamic = true;
+        emitToolCallCandidate?.({ toolCall: createACPToolCall({ state }) });
       }
       emit({
         type: "tool-call",
@@ -1014,7 +1014,6 @@ function createACPStreamTranslator({
         toolName: state.toolName,
         input: stringifyToolInput({ input: state.values.rawInput }),
         providerExecuted: true,
-        ...state.dynamic ? { dynamic: true } : {},
         ...state.nativeName == null ? {} : { nativeName: state.nativeName }
       });
       state.emittedCall = true;
@@ -1029,8 +1028,7 @@ function createACPStreamTranslator({
         toolCallId: state.toolCallId,
         toolName: state.toolName,
         result: createToolResult({ state }),
-        ...state.values.status === "failed" ? { isError: true } : {},
-        ...state.dynamic ? { dynamic: true } : {}
+        ...state.values.status === "failed" ? { isError: true } : {}
       });
       state.emittedResult = true;
       pendingToolCallIds.delete(state.toolCallId);
@@ -1345,6 +1343,31 @@ function mergeToolUpdate({
   });
   if (programmaticName != null) state.values.name = programmaticName;
 }
+function createACPToolCall({ state }) {
+  const title = getStringProperty2({
+    value: state.values,
+    property: "title"
+  });
+  const kind = state.values.kind;
+  const status = state.values.status;
+  return {
+    toolCallId: state.toolCallId,
+    title: title ?? state.toolName ?? `Tool ${state.toolCallId}`,
+    ...isACPToolKind(kind) ? { kind } : {},
+    ...isACPToolCallStatus(status) ? { status } : {},
+    ...Array.isArray(state.values.content) ? { content: state.values.content } : {},
+    ...Array.isArray(state.values.locations) ? { locations: state.values.locations } : {},
+    ...Object.prototype.hasOwnProperty.call(state.values, "rawInput") ? { rawInput: state.values.rawInput } : {},
+    ...Object.prototype.hasOwnProperty.call(state.values, "rawOutput") ? { rawOutput: state.values.rawOutput } : {},
+    ...state.values._meta === null || isRecord3(state.values._meta) ? { _meta: state.values._meta } : {}
+  };
+}
+function isACPToolKind(value) {
+  return value === "read" || value === "edit" || value === "delete" || value === "move" || value === "search" || value === "execute" || value === "think" || value === "fetch" || value === "switch_mode" || value === "other";
+}
+function isACPToolCallStatus(value) {
+  return value === "pending" || value === "in_progress" || value === "completed" || value === "failed";
+}
 function emitFileChanges({
   state,
   emit
@@ -1946,11 +1969,16 @@ function isTerminalToolUpdate(message) {
 // src/v1/bridge/create-emit-stream-event.ts
 function createEmitStreamEvent({
   emit,
+  emitToolCallCandidate,
   builtinTools,
   hostToolServerName,
   hostTools
 }) {
-  const translator = createACPStreamTranslator({ emit, builtinTools });
+  const translator = createACPStreamTranslator({
+    emit,
+    emitToolCallCandidate,
+    builtinTools
+  });
   const correlation = createHostToolCorrelation({
     emitSemanticUpdate: ({ message, rawUpdate }) => {
       translator.update({
@@ -1996,6 +2024,90 @@ function createEmitStreamEvent({
   };
 }
 
+// src/v1/bridge/instruction-mapping.ts
+import { z as z2 } from "zod/v4";
+var UNSAFE_PATH_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var serializableRecordSchema2 = z2.record(z2.string(), z2.json());
+async function resolveACPInstructionConfiguration({
+  instructions,
+  instructionMapping,
+  sessionMeta,
+  environment
+}) {
+  const resolvedEnvironment = { ...environment };
+  if (instructionMapping == null || instructions == null || instructions.length === 0) {
+    return { sessionMeta, environment: resolvedEnvironment };
+  }
+  assertSafePath({ path: instructionMapping.path });
+  if (instructionMapping.type === "session-meta") {
+    return {
+      sessionMeta: setStringAtPath({
+        record: sessionMeta ?? {},
+        path: instructionMapping.path,
+        value: instructions
+      }),
+      environment: resolvedEnvironment
+    };
+  }
+  const serialized = resolvedEnvironment[instructionMapping.variable];
+  let configuration = {};
+  if (serialized != null && serialized.length > 0) {
+    configuration = parseSerializableRecord({
+      serialized,
+      variable: instructionMapping.variable
+    });
+  }
+  resolvedEnvironment[instructionMapping.variable] = JSON.stringify(
+    setStringAtPath({
+      record: configuration,
+      path: instructionMapping.path,
+      value: instructions
+    })
+  );
+  return { sessionMeta, environment: resolvedEnvironment };
+}
+function parseSerializableRecord({
+  serialized,
+  variable
+}) {
+  try {
+    const result = serializableRecordSchema2.safeParse(JSON.parse(serialized));
+    if (result.success) return result.data;
+  } catch {
+  }
+  throw new Error(
+    `ACP instruction mapping environment variable ${JSON.stringify(variable)} must contain a JSON object.`
+  );
+}
+function setStringAtPath({
+  record,
+  path,
+  value
+}) {
+  const [key, ...remainingPath] = path;
+  if (key == null) return { ...record };
+  return {
+    ...record,
+    [key]: remainingPath.length === 0 ? value : setStringAtPath({
+      record: isRecord5(record[key]) ? record[key] : {},
+      path: remainingPath,
+      value
+    })
+  };
+}
+function assertSafePath({ path }) {
+  if (path.length === 0 || path.some(
+    (segment) => segment.length === 0 || UNSAFE_PATH_SEGMENTS.has(segment)
+  )) {
+    throw new Error(
+      "ACP instruction mapping path must contain only safe, non-empty property names."
+    );
+  }
+}
+function isRecord5(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
 // src/v1/bridge/host-tool-relay.ts
 import { randomBytes, timingSafeEqual } from "crypto";
 import { createServer } from "http";
@@ -2122,7 +2234,7 @@ async function handleCatalogNext({
   body,
   state
 }) {
-  if (!isRecord5(body) || !Number.isSafeInteger(body.afterRevision) || body.afterRevision < 0) {
+  if (!isRecord6(body) || !Number.isSafeInteger(body.afterRevision) || body.afterRevision < 0) {
     throw new RelayRequestError({
       status: 400,
       message: "Invalid host tool catalog poll request."
@@ -2141,7 +2253,7 @@ function handleCatalogSeen({
   body,
   state
 }) {
-  if (!isRecord5(body) || !Number.isSafeInteger(body.revision) || body.revision < 1 || body.revision > state.revision) {
+  if (!isRecord6(body) || !Number.isSafeInteger(body.revision) || body.revision < 1 || body.revision > state.revision) {
     throw new RelayRequestError({
       status: 400,
       message: "Invalid host tool catalog acknowledgment."
@@ -2167,7 +2279,7 @@ async function handleInvocation({
       message: "No ACP prompt turn is active."
     });
   }
-  if (!isRecord5(body) || typeof body.requestId !== "string" || typeof body.toolName !== "string" || !isRecord5(body.input) || !Number.isSafeInteger(body.catalogRevision)) {
+  if (!isRecord6(body) || typeof body.requestId !== "string" || typeof body.toolName !== "string" || !isRecord6(body.input) || !Number.isSafeInteger(body.catalogRevision)) {
     throw new RelayRequestError({
       status: 400,
       message: "Invalid host tool relay request."
@@ -2283,7 +2395,7 @@ function canonicalizeJSON2({ value }) {
   if (Array.isArray(value)) {
     return value.map((item) => canonicalizeJSON2({ value: item }));
   }
-  if (!isRecord5(value)) return value;
+  if (!isRecord6(value)) return value;
   return Object.fromEntries(
     Object.keys(value).sort().filter((key) => value[key] !== void 0).map((key) => [key, canonicalizeJSON2({ value: value[key] })])
   );
@@ -2341,7 +2453,7 @@ function closeServer({ server }) {
     });
   });
 }
-function isRecord5(value) {
+function isRecord6(value) {
   return value != null && typeof value === "object" && !Array.isArray(value);
 }
 var RelayRequestError = class extends Error {
@@ -2906,6 +3018,12 @@ async function runTurn(start, turn) {
   turn.emit({ type: "stream-start" });
   const emitStreamEvent = createEmitStreamEvent({
     emit: (event) => turn.emit(event),
+    emitToolCallCandidate: ({ toolCall }) => {
+      turn.emit({
+        type: "acp-tool-call-candidate",
+        toolCall
+      });
+    },
     builtinTools: start.builtinTools,
     hostToolServerName: HOST_TOOL_MCP_SERVER_NAME,
     hostTools: start.tools ?? []
@@ -2990,8 +3108,10 @@ async function ensureSession({
     authentication: bridgeConfiguration.authentication,
     providerAuthentication: bridgeConfiguration.providerAuthentication,
     sessionMeta: bridgeConfiguration.sessionMeta,
+    instructionMapping: start.instructionMapping,
     permissionMode: start.permissionMode,
-    permissionModeMapping: start.permissionModeMapping
+    permissionModeMapping: start.permissionModeMapping,
+    mcpServers: start.mcpServers
   });
   if (session != null) {
     if (catalogRefreshError != null) throw catalogRefreshError;
@@ -3026,12 +3146,18 @@ async function ensureSession({
     providerAuthentication: bridgeConfiguration.providerAuthentication,
     gateway
   });
+  const instructionConfiguration = await resolveACPInstructionConfiguration({
+    instructions: start.instructions,
+    instructionMapping: start.instructionMapping,
+    sessionMeta: bridgeConfiguration.sessionMeta,
+    environment: createChildEnvironment({ launchEnv })
+  });
   child = spawn(
     `${implementationDir}/node_modules/.bin/${implementation.executable}`,
     [...implementation.args],
     {
       cwd: workDir,
-      env: createChildEnvironment({ launchEnv }),
+      env: instructionConfiguration.environment,
       shell: false,
       stdio: ["pipe", "pipe", "pipe"]
     }
@@ -3088,6 +3214,10 @@ async function ensureSession({
       authentication
     });
   }
+  const externalMcpServers = createExternalMcpServers({
+    mcpServers: start.mcpServers,
+    initialization
+  });
   const tools = start.tools ?? [];
   const catalogPath = `${bridgeStateDir}/host-tools.json`;
   await writeFile2(catalogPath, JSON.stringify(tools), { mode: 384 });
@@ -3096,6 +3226,7 @@ async function ensureSession({
     serverName: HOST_TOOL_MCP_SERVER_NAME
   });
   const mcpServers = [
+    ...externalMcpServers,
     {
       name: HOST_TOOL_MCP_SERVER_NAME,
       command: process.execPath,
@@ -3125,7 +3256,7 @@ async function ensureSession({
       sessionId: recoveredSessionId,
       cwd: workDir,
       mcpServers,
-      ...bridgeConfiguration.sessionMeta == null ? {} : { _meta: bridgeConfiguration.sessionMeta }
+      ...instructionConfiguration.sessionMeta == null ? {} : { _meta: instructionConfiguration.sessionMeta }
     });
     createdSession = createACPRecoveredSession({
       agent: connection.agent,
@@ -3142,7 +3273,7 @@ async function ensureSession({
       sessionId: recoveredSessionId,
       cwd: workDir,
       mcpServers,
-      meta: bridgeConfiguration.sessionMeta,
+      meta: instructionConfiguration.sessionMeta,
       harnessId: bridgeType,
       setHistoricalUpdatesSuppressed: ({ suppressed }) => {
         historicalUpdatesSuppressed = suppressed;
@@ -3162,7 +3293,7 @@ async function ensureSession({
     createdSession = await connection.agent.buildSession({
       cwd: workDir,
       mcpServers,
-      ...bridgeConfiguration.sessionMeta == null ? {} : { _meta: bridgeConfiguration.sessionMeta }
+      ...instructionConfiguration.sessionMeta == null ? {} : { _meta: instructionConfiguration.sessionMeta }
     }).start();
   }
   try {
@@ -3197,6 +3328,33 @@ async function ensureSession({
   });
   sessionConfigurationFingerprint = fingerprint;
 }
+function createExternalMcpServers({
+  mcpServers,
+  initialization
+}) {
+  if (mcpServers == null) return [];
+  return Object.entries(mcpServers).map(([name2, value]) => {
+    if (!isRecord7(value)) {
+      throw new Error(
+        `ACP MCP server ${JSON.stringify(name2)} must be configured with an object value.`
+      );
+    }
+    if (value.type === "acp") {
+      throw new HarnessBridgeCapabilityUnsupportedError({
+        harnessId: bridgeType,
+        message: "ACP-transport MCP servers require client-side mcp/connect handling, which this harness does not provide."
+      });
+    }
+    const mcpCapabilities = initialization.agentCapabilities?.mcpCapabilities;
+    if (value.type === "http" && mcpCapabilities?.http !== true || value.type === "sse" && mcpCapabilities?.sse !== true) {
+      throw new HarnessBridgeCapabilityUnsupportedError({
+        harnessId: bridgeType,
+        message: `The ACP agent does not advertise support for ${value.type.toUpperCase()} MCP servers.`
+      });
+    }
+    return { ...value, name: name2 };
+  });
+}
 function unknownUsage2() {
   return {
     inputTokens: {
@@ -3272,7 +3430,7 @@ function createChildEnvironment({
     ...launchEnv
   };
 }
-function isRecord6(value) {
+function isRecord7(value) {
   return value != null && typeof value === "object" && !Array.isArray(value);
 }
 async function readImplementationDescriptor({
@@ -3282,7 +3440,7 @@ async function readImplementationDescriptor({
   const value = await new Response(text, {
     headers: { "content-type": "application/json" }
   }).json();
-  if (!isRecord6(value) || typeof value.executable !== "string" || !Array.isArray(value.args) || !value.args.every((item) => typeof item === "string") || !Array.isArray(value.envKeys) || !value.envKeys.every((item) => typeof item === "string")) {
+  if (!isRecord7(value) || typeof value.executable !== "string" || !Array.isArray(value.args) || !value.args.every((item) => typeof item === "string") || !Array.isArray(value.envKeys) || !value.envKeys.every((item) => typeof item === "string")) {
     throw new Error("Invalid ACP implementation descriptor.");
   }
   return {