@ai-sdk/harness-acp 1.0.1 → 1.0.3

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';
@@ -20,18 +21,22 @@ export function createACPTurnStartConfig({
   builtinTools,
   permissionMode,
   permissionModeMapping,
+  mcpServers,
   debug,
   authenticationProfile,
   sessionMeta,
+  instructionMapping,
 }: {
   prompt: ReadonlyArray<ACPTextContentBlock>;
   tools: ReadonlyArray<HarnessV1ToolSpec>;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   permissionMode: NonNullable<StartMessage['permissionMode']>;
   permissionModeMapping: ACPPermissionModeMapping | undefined;
+  mcpServers: Record<string, unknown> | undefined;
   debug: HarnessV1DebugConfig | undefined;
   authenticationProfile: ACPAuthenticationProfileIdentity;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
+  instructionMapping: ACPInstructionMapping | undefined;
 }): ACPTurnStartConfig {
   return {
     version: 1,
@@ -40,8 +45,10 @@ export function createACPTurnStartConfig({
         stableStringify({
           authenticationProfile,
           sessionMeta: sessionMeta ?? null,
+          ...(instructionMapping == null ? {} : { instructionMapping }),
           builtinTools,
           permissionModeMapping: permissionModeMapping ?? null,
+          mcpServers: mcpServers ?? null,
         }),
       )
       .digest('hex'),

package/src/v1/bridge/create-emit-stream-event.ts

@@ -6,17 +6,20 @@ import type {
   HarnessV1BridgeToolWire,
   HarnessV1StreamPart,
 } from '@ai-sdk/harness';
+import type { ACPToolCall } from '../../acp-tool-call';
 import type { ACPBuiltinToolMapping } from '../acp-v1-bridge-protocol';
 import { createACPStreamTranslator } from './stream-translator';
 import { createHostToolCorrelation } from './host-tool-correlation';
 
 export function createEmitStreamEvent({
   emit,
+  emitToolCallCandidate,
   builtinTools,
   hostToolServerName,
   hostTools,
 }: {
   emit: (event: HarnessV1StreamPart) => void;
+  emitToolCallCandidate: (options: { toolCall: ACPToolCall }) => void;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   hostToolServerName: string;
   hostTools: ReadonlyArray<HarnessV1BridgeToolWire>;
@@ -49,7 +52,11 @@ export function createEmitStreamEvent({
   }) => void;
   removeHostToolCorrelationInvocation: (options: { token: string }) => void;
 } {
-  const translator = createACPStreamTranslator({ emit, builtinTools });
+  const translator = createACPStreamTranslator({
+    emit,
+    emitToolCallCandidate,
+    builtinTools,
+  });
   const correlation = createHostToolCorrelation({
     emitSemanticUpdate: ({ message, rawUpdate }) => {
       translator.update({

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,
@@ -230,6 +231,12 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
   turn.emit({ type: 'stream-start' });
   const emitStreamEvent = createEmitStreamEvent({
     emit: event => turn.emit(event as BridgeEvent),
+    emitToolCallCandidate: ({ toolCall }) => {
+      turn.emit({
+        type: 'acp-tool-call-candidate',
+        toolCall,
+      });
+    },
     builtinTools: start.builtinTools,
     hostToolServerName: HOST_TOOL_MCP_SERVER_NAME,
     hostTools: start.tools ?? [],
@@ -320,8 +327,10 @@ async function ensureSession({
     authentication: bridgeConfiguration.authentication,
     providerAuthentication: bridgeConfiguration.providerAuthentication,
     sessionMeta: bridgeConfiguration.sessionMeta,
+    instructionMapping: start.instructionMapping,
     permissionMode: start.permissionMode,
     permissionModeMapping: start.permissionModeMapping,
+    mcpServers: start.mcpServers,
   });
   if (session != null) {
     if (catalogRefreshError != null) throw catalogRefreshError;
@@ -360,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'],
     },
@@ -437,6 +452,10 @@ async function ensureSession({
       authentication,
     });
   }
+  const externalMcpServers = createExternalMcpServers({
+    mcpServers: start.mcpServers,
+    initialization,
+  });
   const tools = start.tools ?? [];
   const catalogPath = `${bridgeStateDir}/host-tools.json`;
   await writeFile(catalogPath, JSON.stringify(tools), { mode: 0o600 });
@@ -446,6 +465,7 @@ async function ensureSession({
   });
 
   const mcpServers: acp.McpServer[] = [
+    ...externalMcpServers,
     {
       name: HOST_TOOL_MCP_SERVER_NAME,
       command: process.execPath,
@@ -478,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,
@@ -497,7 +517,7 @@ async function ensureSession({
       sessionId: recoveredSessionId,
       cwd: workDir,
       mcpServers,
-      meta: bridgeConfiguration.sessionMeta,
+      meta: instructionConfiguration.sessionMeta,
       harnessId: bridgeType,
       setHistoricalUpdatesSuppressed: ({ suppressed }) => {
         historicalUpdatesSuppressed = suppressed;
@@ -518,9 +538,9 @@ async function ensureSession({
       .buildSession({
         cwd: workDir,
         mcpServers,
-        ...(bridgeConfiguration.sessionMeta == null
+        ...(instructionConfiguration.sessionMeta == null
           ? {}
-          : { _meta: bridgeConfiguration.sessionMeta }),
+          : { _meta: instructionConfiguration.sessionMeta }),
       })
       .start();
   }
@@ -557,6 +577,41 @@ async function ensureSession({
   sessionConfigurationFingerprint = fingerprint;
 }
 
+function createExternalMcpServers({
+  mcpServers,
+  initialization,
+}: {
+  mcpServers: Record<string, unknown> | undefined;
+  initialization: acp.InitializeResponse;
+}): acp.McpServer[] {
+  if (mcpServers == null) return [];
+  return Object.entries(mcpServers).map(([name, value]) => {
+    if (!isRecord(value)) {
+      throw new Error(
+        `ACP MCP server ${JSON.stringify(name)} 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 } as acp.McpServer;
+  });
+}
+
 function unknownUsage() {
   return {
     inputTokens: {

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/bridge/stream-translator.ts

@@ -1,5 +1,10 @@
 import type { HarnessV1StreamPart } from '@ai-sdk/harness';
 import type { PromptResponse, SessionUpdate } from '@agentclientprotocol/sdk';
+import type {
+  ACPToolCall,
+  ACPToolCallStatus,
+  ACPToolKind,
+} from '../../acp-tool-call';
 import type { ACPBuiltinToolMapping } from '../acp-v1-bridge-protocol';
 
 type HarnessUsage = Extract<
@@ -20,7 +25,6 @@ type ToolState = {
   emittedResult: boolean;
   toolName?: string;
   nativeName?: string;
-  dynamic?: boolean;
 };
 
 export type ACPSessionUpdate = SessionUpdate;
@@ -28,9 +32,11 @@ export type ACPPromptResponse = PromptResponse;
 
 export function createACPStreamTranslator({
   emit,
+  emitToolCallCandidate,
   builtinTools = [],
 }: {
   emit: (event: HarnessV1StreamPart) => void;
+  emitToolCallCandidate?: (options: { toolCall: ACPToolCall }) => void;
   builtinTools?: ReadonlyArray<ACPBuiltinToolMapping>;
 }): {
   update: (
@@ -228,13 +234,12 @@ export function createACPStreamTranslator({
           builtin.nativeName != null && builtin.toolName !== builtin.nativeName
             ? builtin.nativeName
             : undefined;
-        state.dynamic = false;
       } else {
         state.toolName = createDynamicToolName({
           programmaticName,
           toolCallId: state.toolCallId,
         });
-        state.dynamic = true;
+        emitToolCallCandidate?.({ toolCall: createACPToolCall({ state }) });
       }
       emit({
         type: 'tool-call',
@@ -242,7 +247,6 @@ export 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;
@@ -263,7 +267,6 @@ export function createACPStreamTranslator({
         toolName: state.toolName!,
         result: createToolResult({ state }),
         ...(state.values.status === 'failed' ? { isError: true } : {}),
-        ...(state.dynamic ? { dynamic: true } : {}),
       });
       state.emittedResult = true;
       pendingToolCallIds.delete(state.toolCallId);
@@ -697,6 +700,60 @@ function mergeToolUpdate({
   if (programmaticName != null) state.values.name = programmaticName;
 }
 
+function createACPToolCall({ state }: { state: ToolState }): ACPToolCall {
+  const title = getStringProperty({
+    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 as ACPToolCall['content'] }
+      : {}),
+    ...(Array.isArray(state.values.locations)
+      ? { locations: state.values.locations as ACPToolCall['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 || isRecord(state.values._meta)
+      ? { _meta: state.values._meta }
+      : {}),
+  };
+}
+
+function isACPToolKind(value: unknown): value is ACPToolKind {
+  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: unknown): value is ACPToolCallStatus {
+  return (
+    value === 'pending' ||
+    value === 'in_progress' ||
+    value === 'completed' ||
+    value === 'failed'
+  );
+}
+
 function emitFileChanges({
   state,
   emit,

package/src/v1/index.ts

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