@ai-sdk/harness-acp 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -27,8 +27,8 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@ai-sdk/harness": "1.0.64",
-    "@ai-sdk/provider-utils": "5.0.25"
+    "@ai-sdk/harness": "1.0.66",
+    "@ai-sdk/provider-utils": "5.0.26"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

package/src/acp-harness.ts

@@ -2,6 +2,7 @@ import type { HarnessV1 } from '@ai-sdk/harness';
 import type { ToolSet } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import type { ACPClientApp } from './acp-auth';
+import type { ACPToolCall } from './acp-tool-call';
 import { createACPV1, type ACPV1Settings } from './v1';
 import {
   acpColdSessionStateSchema,
@@ -16,6 +17,12 @@ const ACP_CLIENT_APP = {
 
 export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly builtinTools?: TBuiltinTools;
+  /**
+   * MCP server definitions keyed by server name. Each definition uses the
+   * underlying runtime's native MCP server configuration format.
+   */
+  readonly mcpServers?: Record<string, unknown>;
+  readonly isMcpToolCall?: (toolCall: ACPToolCall) => boolean;
   readonly port?: number;
   readonly startupTimeoutMs?: number;
   readonly clientApp?: ACPClientApp;
@@ -30,8 +37,10 @@ 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'];
 };
 
 const ACP_BUILTIN_TOOLS = {} as const satisfies ToolSet;
@@ -85,6 +94,17 @@ const acpResumeStateSchema = z.object({
 export function createACP<TBuiltinTools extends ToolSet = {}>(
   settings: ACPHarnessSettings<TBuiltinTools>,
 ): HarnessV1<TBuiltinTools> {
+  if (
+    settings.mcpServers != null &&
+    Object.prototype.hasOwnProperty.call(
+      settings.mcpServers,
+      'ai-sdk-harness-tools',
+    )
+  ) {
+    throw new Error(
+      'ACP MCP server name "ai-sdk-harness-tools" is reserved for HarnessAgent tools.',
+    );
+  }
   const version = (settings as { readonly version?: string }).version ?? 'v1';
   switch (version) {
     case 'v1': {

package/src/acp-tool-call.ts

@@ -0,0 +1,124 @@
+export type ACPMetadata = Record<string, unknown>;
+
+export type ACPRole = 'assistant' | 'user';
+
+export type ACPAnnotations = {
+  audience?: Array<ACPRole> | null;
+  lastModified?: string | null;
+  priority?: number | null;
+  _meta?: ACPMetadata | null;
+};
+
+export type ACPTextContent = {
+  annotations?: ACPAnnotations | null;
+  text: string;
+  _meta?: ACPMetadata | null;
+};
+
+export type ACPImageContent = {
+  annotations?: ACPAnnotations | null;
+  data: string;
+  mimeType: string;
+  uri?: string | null;
+  _meta?: ACPMetadata | null;
+};
+
+export type ACPAudioContent = {
+  annotations?: ACPAnnotations | null;
+  data: string;
+  mimeType: string;
+  _meta?: ACPMetadata | null;
+};
+
+export type ACPResourceLink = {
+  annotations?: ACPAnnotations | null;
+  description?: string | null;
+  mimeType?: string | null;
+  name: string;
+  size?: number | null;
+  title?: string | null;
+  uri: string;
+  _meta?: ACPMetadata | null;
+};
+
+export type ACPTextResourceContents = {
+  mimeType?: string | null;
+  text: string;
+  uri: string;
+  _meta?: ACPMetadata | null;
+};
+
+export type ACPBlobResourceContents = {
+  blob: string;
+  mimeType?: string | null;
+  uri: string;
+  _meta?: ACPMetadata | null;
+};
+
+export type ACPEmbeddedResource = {
+  annotations?: ACPAnnotations | null;
+  resource: ACPTextResourceContents | ACPBlobResourceContents;
+  _meta?: ACPMetadata | null;
+};
+
+export type ACPContentBlock =
+  | (ACPTextContent & { type: 'text' })
+  | (ACPImageContent & { type: 'image' })
+  | (ACPAudioContent & { type: 'audio' })
+  | (ACPResourceLink & { type: 'resource_link' })
+  | (ACPEmbeddedResource & { type: 'resource' });
+
+export type ACPToolCallContent =
+  | {
+      type: 'content';
+      content: ACPContentBlock;
+      _meta?: ACPMetadata | null;
+    }
+  | {
+      type: 'diff';
+      path: string;
+      oldText?: string | null;
+      newText: string;
+      _meta?: ACPMetadata | null;
+    }
+  | {
+      type: 'terminal';
+      terminalId: string;
+      _meta?: ACPMetadata | null;
+    };
+
+export type ACPToolKind =
+  | 'read'
+  | 'edit'
+  | 'delete'
+  | 'move'
+  | 'search'
+  | 'execute'
+  | 'think'
+  | 'fetch'
+  | 'switch_mode'
+  | 'other';
+
+export type ACPToolCallStatus =
+  | 'pending'
+  | 'in_progress'
+  | 'completed'
+  | 'failed';
+
+export type ACPToolCallLocation = {
+  path: string;
+  line?: number | null;
+  _meta?: ACPMetadata | null;
+};
+
+export type ACPToolCall = {
+  toolCallId: string;
+  title: string;
+  kind?: ACPToolKind;
+  status?: ACPToolCallStatus;
+  content?: Array<ACPToolCallContent>;
+  locations?: Array<ACPToolCallLocation>;
+  rawInput?: unknown;
+  rawOutput?: unknown;
+  _meta?: ACPMetadata | null;
+};

package/src/index.ts

@@ -1,8 +1,27 @@
 export { createACP } from './acp-harness';
 export type { ACPAuthOptions, ACPClientApp } from './acp-auth';
 export type { ACPHarnessSettings } from './acp-harness';
+export type {
+  ACPAnnotations,
+  ACPAudioContent,
+  ACPBlobResourceContents,
+  ACPContentBlock,
+  ACPEmbeddedResource,
+  ACPImageContent,
+  ACPMetadata,
+  ACPResourceLink,
+  ACPRole,
+  ACPTextContent,
+  ACPTextResourceContents,
+  ACPToolCall,
+  ACPToolCallContent,
+  ACPToolCallLocation,
+  ACPToolCallStatus,
+  ACPToolKind,
+} from './acp-tool-call';
 export type {
   ACPAuthentication,
+  ACPInstructionMapping,
   ACPNpmLockedSource,
   ACPNpmSimpleSource,
   ACPPermissionModeMapping,

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

@@ -11,7 +11,11 @@ import {
   type HarnessV1ToolSpec,
 } from '@ai-sdk/harness';
 import { z } from 'zod/v4';
-import type { ACPPermissionModeMapping } from './acp-v1-settings';
+import type { ACPToolCall } from '../acp-tool-call';
+import type {
+  ACPInstructionMapping,
+  ACPPermissionModeMapping,
+} from './acp-v1-settings';
 import { acpTextContentBlockSchema } from './acp-v1-prompt';
 
 export type ACPBuiltinToolMapping = {
@@ -81,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;
@@ -126,11 +145,28 @@ const coldRestoreSchema = z.object({
   acpSessionId: z.string(),
 });
 
-export const outboundMessageSchema = harnessV1BridgeOutboundMessageSchema;
+const acpToolCallCandidateSchema = z.object({
+  type: z.literal('acp-tool-call-candidate'),
+  toolCall: z.custom<ACPToolCall>(
+    value =>
+      value != null &&
+      typeof value === 'object' &&
+      typeof (value as { toolCallId?: unknown }).toolCallId === 'string' &&
+      typeof (value as { title?: unknown }).title === 'string',
+  ),
+});
+
+export const outboundMessageSchema = z.union([
+  harnessV1BridgeOutboundMessageSchema,
+  acpToolCallCandidateSchema,
+]);
 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([]),
   permissionModeMapping: permissionModeMappingSchema.optional(),

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

@@ -40,6 +40,7 @@ import {
   type ACPAuthenticationProfileIdentity,
   type ACPClientApp,
 } from '../acp-auth';
+import type { ACPToolCall } from '../acp-tool-call';
 import {
   createACPV1Implementation,
   createImplementationDescriptor,
@@ -76,6 +77,7 @@ import {
   type ACPSkillCatalogEntry,
 } from './acp-v1-prompt';
 import type {
+  ACPInstructionMapping,
   ACPPermissionModeMapping,
   ACPPermissionModeTarget,
   ACPSerializableValue,
@@ -126,6 +128,17 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
     HarnessV1<TBuiltinTools>['lifecycleStateSchema']
   >;
 }): HarnessV1<TBuiltinTools> {
+  if (
+    settings.mcpServers != null &&
+    Object.prototype.hasOwnProperty.call(
+      settings.mcpServers,
+      'ai-sdk-harness-tools',
+    )
+  ) {
+    throw new Error(
+      'ACP MCP server name "ai-sdk-harness-tools" is reserved for HarnessAgent tools.',
+    );
+  }
   if (!HARNESS_ID_REGEXP.test(settings.harnessId)) {
     throw new Error(
       `ACP harnessId must be a stable kebab-case identifier; received ${JSON.stringify(settings.harnessId)}.`,
@@ -364,12 +377,15 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               proc: undefined,
               modelId: settings.modelId,
               sessionMeta: settings.session?.meta,
+              instructionMapping: settings.instructionMapping,
               debug: startOptions.observability?.debug,
               implementationIdentity,
               authenticationProfile,
               builtinTools: builtinToolCatalog,
               permissionMode,
               permissionModeMapping,
+              mcpServers: settings.mcpServers,
+              isMcpToolCall: settings.isMcpToolCall,
               initialGuidanceApplied: resolveACPInitialGuidanceApplied({
                 isResume: true,
                 lifecycleState: lifecycleData,
@@ -419,8 +435,10 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
                   turnStartConfig,
                   authenticationProfile,
                   sessionMeta: settings.session?.meta,
+                  instructionMapping: settings.instructionMapping,
                   builtinTools: builtinToolCatalog,
                   permissionModeMapping,
+                  mcpServers: settings.mcpServers,
                 });
                 respawnStrategy = {
                   mode: 'lossy-rerun',
@@ -448,8 +466,10 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
             permissionMode,
             authenticationProfile,
             sessionMeta: settings.session?.meta,
+            instructionMapping: settings.instructionMapping,
             builtinTools: builtinToolCatalog,
             permissionModeMapping,
+            mcpServers: settings.mcpServers,
             debug: startOptions.observability?.debug,
           });
           respawnStrategy = {
@@ -465,7 +485,10 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         override: portOverride,
         harnessId: settings.harnessId,
       });
-      const token = randomBytes(32).toString('hex');
+      const token =
+        settings.mintBridgeToken == null
+          ? randomBytes(32).toString('hex')
+          : settings.mintBridgeToken(sandboxSession.id);
       await sandbox.run({
         command: `mkdir -p ${shellQuote(workDir)} ${shellQuote(bridgeStateDir)}`,
         abortSignal: startOptions.abortSignal,
@@ -570,6 +593,12 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               builtinTools: builtinToolCatalog,
               permissionMode,
               permissionModeMapping,
+              ...(settings.instructionMapping == null
+                ? {}
+                : { instructionMapping: settings.instructionMapping }),
+              ...(settings.mcpServers == null
+                ? {}
+                : { mcpServers: settings.mcpServers }),
               tools: respawnStrategy.turnStartConfig.tools,
               turnStartConfig: respawnStrategy.turnStartConfig,
               recoveryMode: {
@@ -600,12 +629,15 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         proc,
         modelId: settings.modelId,
         sessionMeta: settings.session?.meta,
+        instructionMapping: settings.instructionMapping,
         debug: startOptions.observability?.debug,
         implementationIdentity,
         authenticationProfile,
         builtinTools: builtinToolCatalog,
         permissionMode,
         permissionModeMapping,
+        mcpServers: settings.mcpServers,
+        isMcpToolCall: settings.isMcpToolCall,
         initialGuidanceApplied: resolveACPInitialGuidanceApplied({
           isResume,
           lifecycleState: lifecycleData,
@@ -801,12 +833,15 @@ function createSession({
   proc,
   modelId,
   sessionMeta,
+  instructionMapping,
   debug,
   implementationIdentity,
   authenticationProfile,
   builtinTools,
   permissionMode,
   permissionModeMapping,
+  mcpServers,
+  isMcpToolCall,
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
   skillCatalog,
   skillsFingerprint,
@@ -829,12 +864,15 @@ 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;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   permissionMode: NonNullable<StartMessage['permissionMode']>;
   permissionModeMapping: StartMessage['permissionModeMapping'];
+  mcpServers: Record<string, unknown> | undefined;
+  isMcpToolCall: ((toolCall: ACPToolCall) => boolean) | undefined;
   initialGuidanceApplied: boolean;
   skillCatalog: ReadonlyArray<ACPSkillCatalogEntry>;
   skillsFingerprint: string;
@@ -889,6 +927,8 @@ function createSession({
     let openBlock:
       | { readonly type: 'text' | 'reasoning'; readonly id: string }
       | undefined;
+    const dynamicToolCalls = new Map<string, boolean>();
+    const toolCallClassificationErrors = new Map<string, unknown>();
     const subscriptions: Array<() => void> = [];
     const forward = (event: HarnessV1StreamPart) => {
       if (event.type === 'text-start' || event.type === 'reasoning-start') {
@@ -923,9 +963,7 @@ function createSession({
       'reasoning-start',
       'reasoning-delta',
       'reasoning-end',
-      'tool-call',
       'tool-approval-request',
-      'tool-result',
       'file-change',
       'finish-step',
       'raw',
@@ -954,6 +992,45 @@ function createSession({
         settle({ error: abortError });
       }
     };
+    subscriptions.push(
+      channel.on('acp-tool-call-candidate', event => {
+        try {
+          dynamicToolCalls.set(
+            event.toolCall.toolCallId,
+            isMcpToolCall?.(event.toolCall) === true,
+          );
+        } catch (error) {
+          toolCallClassificationErrors.set(event.toolCall.toolCallId, error);
+        }
+      }),
+    );
+    subscriptions.push(
+      channel.on('tool-call', event => {
+        if (toolCallClassificationErrors.has(event.toolCallId)) {
+          const error = toolCallClassificationErrors.get(event.toolCallId);
+          closeForwardedBlock();
+          forward({ type: 'error', error });
+          try {
+            channel.send({ type: 'abort' });
+          } catch {}
+          settle({ error });
+          return;
+        }
+        forward(
+          dynamicToolCalls.get(event.toolCallId) === true
+            ? { ...event, dynamic: true }
+            : event,
+        );
+      }),
+    );
+    subscriptions.push(
+      channel.on('tool-result', event => {
+        const dynamic = dynamicToolCalls.get(event.toolCallId) === true;
+        dynamicToolCalls.delete(event.toolCallId);
+        toolCallClassificationErrors.delete(event.toolCallId);
+        forward(dynamic ? { ...event, dynamic: true } : event);
+      }),
+    );
     for (const type of eventTypes) {
       subscriptions.push(channel.on(type, event => forward(event)));
     }
@@ -1110,9 +1187,11 @@ function createSession({
         builtinTools,
         permissionMode,
         permissionModeMapping,
+        mcpServers,
         debug,
         authenticationProfile,
         sessionMeta,
+        instructionMapping,
       });
       const control = wireTurn({
         emit: options.emit,
@@ -1130,13 +1209,25 @@ 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,
             permissionModeMapping,
+            ...(mcpServers == null ? {} : { mcpServers }),
             tools: options.tools == null ? undefined : turnStartConfig.tools,
             turnStartConfig,
           });
@@ -1174,6 +1265,15 @@ 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,
             recoveryMode: {
@@ -1336,14 +1436,18 @@ function validateACPTurnStartConfig({
   turnStartConfig,
   authenticationProfile,
   sessionMeta,
+  instructionMapping,
   builtinTools,
   permissionModeMapping,
+  mcpServers,
 }: {
   turnStartConfig: ACPTurnStartConfig;
   authenticationProfile: ACPAuthenticationProfileIdentity;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
+  instructionMapping: ACPInstructionMapping | undefined;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   permissionModeMapping: ACPPermissionModeMapping | undefined;
+  mcpServers: Record<string, unknown> | undefined;
 }): void {
   const current = createACPTurnStartConfig({
     prompt: turnStartConfig.prompt,
@@ -1351,9 +1455,11 @@ function validateACPTurnStartConfig({
     builtinTools,
     permissionMode: turnStartConfig.permissionMode,
     permissionModeMapping,
+    mcpServers,
     debug: turnStartConfig.debug,
     authenticationProfile,
     sessionMeta,
+    instructionMapping,
   });
   if (
     current.configurationFingerprint !==
@@ -1371,8 +1477,10 @@ function validateACPColdSessionConfiguration({
   permissionMode,
   authenticationProfile,
   sessionMeta,
+  instructionMapping,
   builtinTools,
   permissionModeMapping,
+  mcpServers,
   debug,
 }: {
   coldSession: ACPColdSessionState;
@@ -1380,8 +1488,10 @@ 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;
   debug: HarnessV1DebugConfig | undefined;
 }): ACPTurnStartConfig {
   const current = createACPTurnStartConfig({
@@ -1390,9 +1500,11 @@ function validateACPColdSessionConfiguration({
     builtinTools,
     permissionMode,
     permissionModeMapping,
+    mcpServers,
     debug,
     authenticationProfile,
     sessionMeta,
+    instructionMapping,
   });
   if (
     current.configurationFingerprint !== coldSession.configurationFingerprint ||

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

@@ -1,4 +1,5 @@
 import type { HarnessV1PermissionMode } from '@ai-sdk/harness';
+import type { ACPToolCall } from '../acp-tool-call';
 
 export type ACPSerializablePrimitive = string | number | boolean | null;
 
@@ -74,9 +75,27 @@ 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;
+  readonly mcpServers?: Record<string, unknown>;
+  readonly isMcpToolCall?: (toolCall: ACPToolCall) => boolean;
   readonly auth?: ACPProviderAuthenticationMode;
   readonly source: ACPSource;
   readonly executable: string;
@@ -90,8 +109,18 @@ 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>>;
   };
+  /**
+   * Creates the authentication token used by the sandbox bridge. Defaults to
+   * a random 32-byte hexadecimal token.
+   */
+  readonly mintBridgeToken?: (sandboxId: string) => string;
 };