@ai-sdk/harness-acp 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @ai-sdk/harness-acp
 
+## 1.0.4
+
+### Patch Changes
+
+- Updated dependencies [7fbfc6d]
+  - @ai-sdk/provider-utils@5.0.27
+  - @ai-sdk/harness@1.0.67
+
+## 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

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.2" : "0.0.0-test";
+var VERSION = true ? "1.0.4" : "0.0.0-test";
 function createHostToolMCPServer({
   tools: tools2,
   revision = 1,

package/dist/bridge/index.mjs

@@ -2024,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";
@@ -2150,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."
@@ -2169,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."
@@ -2195,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."
@@ -2311,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] })])
   );
@@ -2369,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 {
@@ -3024,6 +3108,7 @@ async function ensureSession({
     authentication: bridgeConfiguration.authentication,
     providerAuthentication: bridgeConfiguration.providerAuthentication,
     sessionMeta: bridgeConfiguration.sessionMeta,
+    instructionMapping: start.instructionMapping,
     permissionMode: start.permissionMode,
     permissionModeMapping: start.permissionModeMapping,
     mcpServers: start.mcpServers
@@ -3061,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"]
     }
@@ -3165,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,
@@ -3182,7 +3273,7 @@ async function ensureSession({
       sessionId: recoveredSessionId,
       cwd: workDir,
       mcpServers,
-      meta: bridgeConfiguration.sessionMeta,
+      meta: instructionConfiguration.sessionMeta,
       harnessId: bridgeType,
       setHistoricalUpdatesSuppressed: ({ suppressed }) => {
         historicalUpdatesSuppressed = suppressed;
@@ -3202,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 {
@@ -3243,7 +3334,7 @@ function createExternalMcpServers({
 }) {
   if (mcpServers == null) return [];
   return Object.entries(mcpServers).map(([name2, value]) => {
-    if (!isRecord6(value)) {
+    if (!isRecord7(value)) {
       throw new Error(
         `ACP MCP server ${JSON.stringify(name2)} must be configured with an object value.`
       );
@@ -3339,7 +3430,7 @@ function createChildEnvironment({
     ...launchEnv
   };
 }
-function isRecord6(value) {
+function isRecord7(value) {
   return value != null && typeof value === "object" && !Array.isArray(value);
 }
 async function readImplementationDescriptor({
@@ -3349,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 {