@ai-sdk/harness-acp 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@ai-sdk/harness": "1.0.65",
+    "@ai-sdk/harness": "1.0.66",
     "@ai-sdk/provider-utils": "5.0.26"
   },
   "peerDependencies": {

package/src/acp-harness.ts

@@ -37,6 +37,7 @@ export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly authentication?: ACPV1Settings['authentication'];
   readonly providerAuthentication?: ACPV1Settings['providerAuthentication'];
   readonly modelId?: ACPV1Settings['modelId'];
+  readonly instructionMapping?: ACPV1Settings['instructionMapping'];
   readonly permissionModeMapping?: ACPV1Settings['permissionModeMapping'];
   readonly session?: ACPV1Settings['session'];
   readonly mintBridgeToken?: ACPV1Settings['mintBridgeToken'];

package/src/index.ts

@@ -21,6 +21,7 @@ export type {
 } from './acp-tool-call';
 export type {
   ACPAuthentication,
+  ACPInstructionMapping,
   ACPNpmLockedSource,
   ACPNpmSimpleSource,
   ACPPermissionModeMapping,

package/src/v1/acp-v1-bridge-protocol.ts

@@ -12,7 +12,10 @@ import {
 } from '@ai-sdk/harness';
 import { z } from 'zod/v4';
 import type { ACPToolCall } from '../acp-tool-call';
-import type { ACPPermissionModeMapping } from './acp-v1-settings';
+import type {
+  ACPInstructionMapping,
+  ACPPermissionModeMapping,
+} from './acp-v1-settings';
 import { acpTextContentBlockSchema } from './acp-v1-prompt';
 
 export type ACPBuiltinToolMapping = {
@@ -82,6 +85,21 @@ const permissionModeMappingSchema: z.ZodType<ACPPermissionModeMapping> =
     'allow-all': permissionModeTargetSchema.nullable(),
   });
 
+const instructionMappingPathSchema = z.array(z.string().min(1)).min(1);
+
+const instructionMappingSchema: z.ZodType<ACPInstructionMapping> =
+  z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('session-meta'),
+      path: instructionMappingPathSchema,
+    }),
+    z.object({
+      type: z.literal('launch-env-json'),
+      variable: z.string().min(1),
+      path: instructionMappingPathSchema,
+    }),
+  ]);
+
 export type ACPTurnStartConfig = {
   readonly version: 1;
   readonly configurationFingerprint: string;
@@ -146,6 +164,8 @@ export type OutboundMessage = z.infer<typeof outboundMessageSchema>;
 
 export const startMessageSchema = harnessV1BridgeStartBaseSchema.extend({
   prompt: z.array(acpTextContentBlockSchema),
+  instructions: z.string().optional(),
+  instructionMapping: instructionMappingSchema.optional(),
   mcpServers: z.record(z.string(), z.unknown()).optional(),
   tools: z.array(acpSerializableToolSpecSchema).optional(),
   builtinTools: z.array(builtinToolSchema).readonly().default([]),

package/src/v1/acp-v1-harness.ts

@@ -77,6 +77,7 @@ import {
   type ACPSkillCatalogEntry,
 } from './acp-v1-prompt';
 import type {
+  ACPInstructionMapping,
   ACPPermissionModeMapping,
   ACPPermissionModeTarget,
   ACPSerializableValue,
@@ -376,6 +377,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               proc: undefined,
               modelId: settings.modelId,
               sessionMeta: settings.session?.meta,
+              instructionMapping: settings.instructionMapping,
               debug: startOptions.observability?.debug,
               implementationIdentity,
               authenticationProfile,
@@ -433,6 +435,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
                   turnStartConfig,
                   authenticationProfile,
                   sessionMeta: settings.session?.meta,
+                  instructionMapping: settings.instructionMapping,
                   builtinTools: builtinToolCatalog,
                   permissionModeMapping,
                   mcpServers: settings.mcpServers,
@@ -463,6 +466,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
             permissionMode,
             authenticationProfile,
             sessionMeta: settings.session?.meta,
+            instructionMapping: settings.instructionMapping,
             builtinTools: builtinToolCatalog,
             permissionModeMapping,
             mcpServers: settings.mcpServers,
@@ -589,6 +593,9 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               builtinTools: builtinToolCatalog,
               permissionMode,
               permissionModeMapping,
+              ...(settings.instructionMapping == null
+                ? {}
+                : { instructionMapping: settings.instructionMapping }),
               ...(settings.mcpServers == null
                 ? {}
                 : { mcpServers: settings.mcpServers }),
@@ -622,6 +629,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         proc,
         modelId: settings.modelId,
         sessionMeta: settings.session?.meta,
+        instructionMapping: settings.instructionMapping,
         debug: startOptions.observability?.debug,
         implementationIdentity,
         authenticationProfile,
@@ -825,6 +833,7 @@ function createSession({
   proc,
   modelId,
   sessionMeta,
+  instructionMapping,
   debug,
   implementationIdentity,
   authenticationProfile,
@@ -855,6 +864,7 @@ function createSession({
   proc: Experimental_SandboxProcess | undefined;
   modelId: string | undefined;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
+  instructionMapping: ACPInstructionMapping | undefined;
   debug: HarnessV1DebugConfig | undefined;
   implementationIdentity: string;
   authenticationProfile: ACPAuthenticationProfileIdentity;
@@ -1181,6 +1191,7 @@ function createSession({
         debug,
         authenticationProfile,
         sessionMeta,
+        instructionMapping,
       });
       const control = wireTurn({
         emit: options.emit,
@@ -1198,9 +1209,20 @@ function createSession({
               ? prompt
               : prependACPInitialGuidance({
                   prompt,
-                  instructions: options.instructions,
+                  instructions:
+                    instructionMapping == null
+                      ? options.instructions
+                      : undefined,
                   skills: skillCatalog,
                 }),
+            ...(instructionMapping == null
+              ? {}
+              : {
+                  instructionMapping,
+                  ...(options.instructions == null
+                    ? {}
+                    : { instructions: options.instructions }),
+                }),
             debug,
             builtinTools,
             permissionMode,
@@ -1243,6 +1265,14 @@ function createSession({
             builtinTools: turnStartConfig.builtinTools,
             permissionMode: turnStartConfig.permissionMode,
             permissionModeMapping: turnStartConfig.permissionModeMapping,
+            ...(instructionMapping == null
+              ? {}
+              : {
+                  instructionMapping,
+                  ...(options.instructions == null
+                    ? {}
+                    : { instructions: options.instructions }),
+                }),
             ...(mcpServers == null ? {} : { mcpServers }),
             tools: turnStartConfig.tools,
             turnStartConfig,
@@ -1406,6 +1436,7 @@ function validateACPTurnStartConfig({
   turnStartConfig,
   authenticationProfile,
   sessionMeta,
+  instructionMapping,
   builtinTools,
   permissionModeMapping,
   mcpServers,
@@ -1413,6 +1444,7 @@ function validateACPTurnStartConfig({
   turnStartConfig: ACPTurnStartConfig;
   authenticationProfile: ACPAuthenticationProfileIdentity;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
+  instructionMapping: ACPInstructionMapping | undefined;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   permissionModeMapping: ACPPermissionModeMapping | undefined;
   mcpServers: Record<string, unknown> | undefined;
@@ -1427,6 +1459,7 @@ function validateACPTurnStartConfig({
     debug: turnStartConfig.debug,
     authenticationProfile,
     sessionMeta,
+    instructionMapping,
   });
   if (
     current.configurationFingerprint !==
@@ -1444,6 +1477,7 @@ function validateACPColdSessionConfiguration({
   permissionMode,
   authenticationProfile,
   sessionMeta,
+  instructionMapping,
   builtinTools,
   permissionModeMapping,
   mcpServers,
@@ -1454,6 +1488,7 @@ function validateACPColdSessionConfiguration({
   permissionMode: NonNullable<StartMessage['permissionMode']>;
   authenticationProfile: ACPAuthenticationProfileIdentity;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
+  instructionMapping: ACPInstructionMapping | undefined;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   permissionModeMapping: ACPPermissionModeMapping | undefined;
   mcpServers: Record<string, unknown> | undefined;
@@ -1469,6 +1504,7 @@ function validateACPColdSessionConfiguration({
     debug,
     authenticationProfile,
     sessionMeta,
+    instructionMapping,
   });
   if (
     current.configurationFingerprint !== coldSession.configurationFingerprint ||

package/src/v1/acp-v1-settings.ts

@@ -75,6 +75,22 @@ export type ACPPermissionModeMapping = Readonly<
   Record<HarnessV1PermissionMode, ACPPermissionModeTarget | null>
 >;
 
+/**
+ * Describes where an ACP implementation accepts native session instructions.
+ * Session metadata paths are relative to `_meta`; launch environment paths are
+ * relative to the parsed JSON object stored in `variable`.
+ */
+export type ACPInstructionMapping =
+  | {
+      readonly type: 'session-meta';
+      readonly path: ReadonlyArray<string>;
+    }
+  | {
+      readonly type: 'launch-env-json';
+      readonly variable: string;
+      readonly path: ReadonlyArray<string>;
+    };
+
 export type ACPV1Settings = {
   readonly version?: 'v1';
   readonly harnessId: string;
@@ -93,6 +109,11 @@ export type ACPV1Settings = {
   readonly authentication?: ACPAuthentication;
   readonly providerAuthentication?: ACPProviderAuthentication;
   readonly modelId?: string;
+  /**
+   * Routes HarnessAgent instructions to a runtime-native system or developer
+   * prompt. When omitted, instructions are prepended to the first user prompt.
+   */
+  readonly instructionMapping?: ACPInstructionMapping;
   readonly permissionModeMapping?: ACPPermissionModeMapping;
   readonly session?: {
     readonly meta?: Readonly<Record<string, ACPSerializableValue>>;

package/src/v1/acp-v1-turn-start-config.ts

@@ -10,6 +10,7 @@ import {
 } from './acp-v1-bridge-protocol';
 import type { ACPTextContentBlock } from './acp-v1-prompt';
 import type {
+  ACPInstructionMapping,
   ACPPermissionModeMapping,
   ACPSerializableValue,
 } from './acp-v1-settings';
@@ -24,6 +25,7 @@ export function createACPTurnStartConfig({
   debug,
   authenticationProfile,
   sessionMeta,
+  instructionMapping,
 }: {
   prompt: ReadonlyArray<ACPTextContentBlock>;
   tools: ReadonlyArray<HarnessV1ToolSpec>;
@@ -34,6 +36,7 @@ export function createACPTurnStartConfig({
   debug: HarnessV1DebugConfig | undefined;
   authenticationProfile: ACPAuthenticationProfileIdentity;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
+  instructionMapping: ACPInstructionMapping | undefined;
 }): ACPTurnStartConfig {
   return {
     version: 1,
@@ -42,6 +45,7 @@ export function createACPTurnStartConfig({
         stableStringify({
           authenticationProfile,
           sessionMeta: sessionMeta ?? null,
+          ...(instructionMapping == null ? {} : { instructionMapping }),
           builtinTools,
           permissionModeMapping: permissionModeMapping ?? null,
           mcpServers: mcpServers ?? null,

package/src/v1/bridge/index.ts

@@ -32,6 +32,7 @@ import {
 } from './acp-diagnostics';
 import { monitorACPAgentStderr } from './agent-stderr-monitor';
 import { createEmitStreamEvent } from './create-emit-stream-event';
+import { resolveACPInstructionConfiguration } from './instruction-mapping';
 import {
   startHostToolRelay,
   type HostToolRelay,
@@ -326,6 +327,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,
@@ -367,12 +369,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'],
     },
@@ -490,9 +498,9 @@ async function ensureSession({
       sessionId: recoveredSessionId,
       cwd: workDir,
       mcpServers,
-      ...(bridgeConfiguration.sessionMeta == null
+      ...(instructionConfiguration.sessionMeta == null
         ? {}
-        : { _meta: bridgeConfiguration.sessionMeta }),
+        : { _meta: instructionConfiguration.sessionMeta }),
     });
     createdSession = createACPRecoveredSession({
       agent: connection.agent,
@@ -509,7 +517,7 @@ async function ensureSession({
       sessionId: recoveredSessionId,
       cwd: workDir,
       mcpServers,
-      meta: bridgeConfiguration.sessionMeta,
+      meta: instructionConfiguration.sessionMeta,
       harnessId: bridgeType,
       setHistoricalUpdatesSuppressed: ({ suppressed }) => {
         historicalUpdatesSuppressed = suppressed;
@@ -530,9 +538,9 @@ async function ensureSession({
       .buildSession({
         cwd: workDir,
         mcpServers,
-        ...(bridgeConfiguration.sessionMeta == null
+        ...(instructionConfiguration.sessionMeta == null
           ? {}
-          : { _meta: bridgeConfiguration.sessionMeta }),
+          : { _meta: instructionConfiguration.sessionMeta }),
       })
       .start();
   }

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

@@ -0,0 +1,132 @@
+import { z } from 'zod/v4';
+import type {
+  ACPInstructionMapping,
+  ACPSerializableValue,
+} from '../acp-v1-settings';
+
+const UNSAFE_PATH_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+
+const serializableRecordSchema: z.ZodType<
+  Readonly<Record<string, ACPSerializableValue>>
+> = z.record(z.string(), z.json());
+
+export async function resolveACPInstructionConfiguration({
+  instructions,
+  instructionMapping,
+  sessionMeta,
+  environment,
+}: {
+  instructions: string | undefined;
+  instructionMapping: ACPInstructionMapping | undefined;
+  sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
+  environment: Readonly<Record<string, string | undefined>>;
+}): Promise<{
+  sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
+  environment: Record<string, string | undefined>;
+}> {
+  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: Readonly<Record<string, ACPSerializableValue>> = {};
+  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 };
+}
+
+/*
+ * The bridge runs in an isolated runtime whose dependencies are limited to the
+ * ones declared in this directory's package.json, so AI SDK JSON helpers are
+ * unavailable here. Schema validation plus a guarded `JSON.parse` provides the
+ * same guarantee: nothing but a validated serializable record escapes.
+ */
+function parseSerializableRecord({
+  serialized,
+  variable,
+}: {
+  serialized: string;
+  variable: string;
+}): Readonly<Record<string, ACPSerializableValue>> {
+  try {
+    const result = serializableRecordSchema.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,
+}: {
+  record: Readonly<Record<string, ACPSerializableValue>>;
+  path: ReadonlyArray<string>;
+  value: string;
+}): Record<string, ACPSerializableValue> {
+  const [key, ...remainingPath] = path;
+  if (key == null) return { ...record };
+  return {
+    ...record,
+    [key]:
+      remainingPath.length === 0
+        ? value
+        : setStringAtPath({
+            record: isRecord(record[key]) ? record[key] : {},
+            path: remainingPath,
+            value,
+          }),
+  };
+}
+
+function assertSafePath({ path }: { path: ReadonlyArray<string> }): void {
+  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 isRecord(
+  value: ACPSerializableValue | undefined,
+): value is Readonly<Record<string, ACPSerializableValue>> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/v1/index.ts

@@ -1,6 +1,7 @@
 export { createACPV1 } from './acp-v1-harness';
 export type {
   ACPAuthentication,
+  ACPInstructionMapping,
   ACPNpmLockedSource,
   ACPNpmSimpleSource,
   ACPPermissionModeMapping,