@ai-sdk/harness-acp 1.0.30 → 1.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,16 +26,16 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.92",
-    "@ai-sdk/provider-utils": "5.0.32",
+    "@ai-sdk/harness": "1.0.94",
+    "@ai-sdk/provider-utils": "5.0.34",
     "ws": "^8.21.0"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"
   },
   "devDependencies": {
-    "@agentclientprotocol/sdk": "1.2.1",
-    "@modelcontextprotocol/sdk": "1.29.0",
+    "@agentclientprotocol/sdk": "1.4.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "@types/node": "22.19.19",
     "@types/ws": "^8.5.13",
     "@vercel/ai-tsconfig": "0.0.0",

package/src/acp-harness.ts

@@ -48,7 +48,15 @@ export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly credentialForwarding?: ACPV1Settings['credentialForwarding'];
   readonly env?: ACPV1Settings['env'];
   readonly authentication?: ACPV1Settings['authentication'];
+  readonly clientCapabilities?: ACPV1Settings['clientCapabilities'];
   readonly providerAuthentication?: ACPV1Settings['providerAuthentication'];
+  /**
+   * Maps the HarnessAgent model identifier to an ACP session operation.
+   */
+  readonly modelMapping: ACPV1Settings['modelMapping'];
+  /**
+   * @deprecated Use `model` on `HarnessAgent` instead.
+   */
   readonly modelId?: ACPV1Settings['modelId'];
   readonly skillsDirectory?: ACPV1Settings['skillsDirectory'];
   readonly instructionMapping?: ACPV1Settings['instructionMapping'];
@@ -103,8 +111,7 @@ const acpResumeStateSchema = z.object({
     })
     .optional(),
   initialGuidanceApplied: z.boolean().optional(),
-  skillsMaterialized: z.boolean().optional(),
-  skillsFingerprint: z.string().optional(),
+  instructionsFingerprint: z.string().optional(),
   skillsDirectory: z.string().optional(),
 });
 

package/src/index.ts

@@ -24,6 +24,7 @@ export type {
   ACPAuthentication,
   ACPInstallCommandSource,
   ACPInstructionMapping,
+  ACPModelMapping,
   ACPNpmLockedSource,
   ACPNpmSimpleSource,
   ACPOutputSchemaMapping,

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

@@ -14,6 +14,7 @@ import { z } from 'zod/v4';
 import type { ACPToolCall } from '../acp-tool-call';
 import type {
   ACPInstructionMapping,
+  ACPModelMapping,
   ACPPermissionModeMapping,
 } from './acp-v1-settings';
 import { acpTextContentBlockSchema } from './acp-v1-prompt';
@@ -125,6 +126,20 @@ const outputSchemaMappingSchema: z.ZodType<ACPSerializableOutputSchemaMapping> =
     path: z.array(z.string().min(1)).min(1),
   });
 
+const modelMappingSchema: z.ZodType<ACPModelMapping> = z.discriminatedUnion(
+  'type',
+  [
+    z.object({
+      type: z.literal('session-config-option'),
+      path: z.string().min(1),
+    }),
+    z.object({
+      type: z.literal('session-model'),
+      path: z.string().min(1),
+    }),
+  ],
+);
+
 export type ACPTurnStartConfig = {
   readonly version: 1;
   readonly configurationFingerprint: string;
@@ -133,6 +148,8 @@ export type ACPTurnStartConfig = {
   readonly builtinTools: Array<ACPBuiltinToolMapping>;
   readonly permissionMode: HarnessV1PermissionMode;
   readonly permissionModeMapping?: ACPPermissionModeMapping;
+  readonly model?: string;
+  readonly modelMapping?: ACPModelMapping;
   readonly debug?: HarnessV1DebugConfig;
   readonly responseFormat?: z.infer<
     typeof harnessV1BridgeStartBaseSchema
@@ -148,6 +165,8 @@ export const acpTurnStartConfigSchema = z.object({
   builtinTools: z.array(builtinToolSchema).default([]),
   permissionMode: harnessV1BridgeStartBaseSchema.shape.permissionMode.unwrap(),
   permissionModeMapping: permissionModeMappingSchema.optional(),
+  model: harnessV1BridgeStartBaseSchema.shape.model.optional(),
+  modelMapping: modelMappingSchema.optional(),
   debug: harnessV1BridgeStartBaseSchema.shape.debug.optional(),
   responseFormat:
     harnessV1BridgeStartBaseSchema.shape.responseFormat.optional(),
@@ -156,14 +175,15 @@ export const acpTurnStartConfigSchema = z.object({
 
 export type ACPColdSessionState = Omit<
   ACPTurnStartConfig,
-  'prompt' | 'debug'
-> & {
-  readonly modelId?: string;
-};
+  'prompt' | 'debug' | 'model' | 'modelMapping'
+>;
 
 export const acpColdSessionStateSchema: z.ZodType<ACPColdSessionState> =
-  acpTurnStartConfigSchema.omit({ prompt: true, debug: true }).extend({
-    modelId: z.string().optional(),
+  acpTurnStartConfigSchema.omit({
+    prompt: true,
+    debug: true,
+    model: true,
+    modelMapping: true,
   });
 
 const lossyRecoverySchema = z.object({
@@ -203,6 +223,7 @@ export const startMessageSchema = harnessV1BridgeStartBaseSchema.extend({
   tools: z.array(acpSerializableToolSpecSchema).optional(),
   builtinTools: z.array(builtinToolSchema).readonly().default([]),
   permissionModeMapping: permissionModeMappingSchema.optional(),
+  modelMapping: modelMappingSchema.optional(),
   turnStartConfig: acpTurnStartConfigSchema,
   recoveryMode: z
     .discriminatedUnion('type', [lossyRecoverySchema, coldRestoreSchema])

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

@@ -9,6 +9,7 @@ import {
   type HarnessV1PortEndpoint,
   type HarnessV1PromptControl,
   type HarnessV1Session,
+  type HarnessV1Skill,
   type HarnessV1StreamPart,
   type HarnessV1ToolSpec,
 } from '@ai-sdk/harness';
@@ -70,16 +71,16 @@ import {
 } from './acp-v1-turn-start-config';
 import {
   resolveACPInitialGuidanceApplied,
-  shouldMaterializeACPSkills,
   validateACPLifecycleCompatibility,
   type ACPLifecycleData,
 } from './acp-v1-lifecycle';
 import {
   convertHarnessPromptToACPTextBlocks,
-  prependACPInitialGuidance,
+  prependACPInstructionGuidance,
 } from './acp-v1-prompt';
 import type {
   ACPInstructionMapping,
+  ACPModelMapping,
   ACPOutputSchemaMapping,
   ACPPermissionModeMapping,
   ACPPermissionModeTarget,
@@ -88,7 +89,6 @@ import type {
   ACPV1Settings,
 } from './acp-v1-settings';
 import {
-  createACPSkillsFingerprint,
   materializeACPSkills,
   resolveACPPrivateSessionDirectory,
   resolveACPSkillsDirectory,
@@ -204,6 +204,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         acpVersion: 'v1',
         implementation,
         clientApp,
+        clientCapabilities: settings.clientCapabilities,
+        modelMapping: settings.modelMapping,
         providerAuthentication: providerAuthenticationCompatibility,
         permissionModeMapping: settings.permissionModeMapping,
       });
@@ -381,24 +383,6 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         sessionWorkDir: workDir,
       });
       const bridgeStateDir = `${privateSessionDir}/bridge`;
-      const skills = startOptions.skills ?? [];
-      const skillsFingerprint = createACPSkillsFingerprint({ skills });
-      const shouldMaterializeSkills = shouldMaterializeACPSkills({
-        isResume,
-        lifecycleState: lifecycleData,
-        skillsFingerprint,
-        skillsDirectory,
-      });
-      if (skills.length > 0) {
-        await materializeACPSkills({
-          sandbox: toolSafeSandboxSession,
-          rootDir: skillsDirectory,
-          sessionWorkDir: workDir,
-          skills,
-          shouldMaterialize: shouldMaterializeSkills,
-          abortSignal: startOptions.abortSignal,
-        });
-      }
       const report = startOptions.observability?.report;
       const onDiagnostic = report
         ? (frame: Parameters<typeof harnessV1DiagnosticFromBridgeFrame>[0]) =>
@@ -453,7 +437,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               harnessId: settings.harnessId,
               channel: attachChannel,
               proc: undefined,
-              modelId: settings.modelId,
+              modelMapping: settings.modelMapping,
+              defaultModelId: settings.modelId,
               sessionMeta: settings.session?.meta,
               instructionMapping: settings.instructionMapping,
               outputSchemaMapping: settings.outputSchemaMapping,
@@ -469,7 +454,9 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
                 isResume: true,
                 lifecycleState: lifecycleData,
               }),
-              skillsFingerprint,
+              instructionsFingerprint: lifecycleData.instructionsFingerprint,
+              sandbox: toolSafeSandboxSession,
+              sessionWorkDir: workDir,
               skillsDirectory,
               acpSessionId: lifecycleData.acpSessionId,
               bridgePort: coords.port,
@@ -517,6 +504,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
                   sessionMeta: settings.session?.meta,
                   instructionMapping: settings.instructionMapping,
                   outputSchemaMapping: settings.outputSchemaMapping,
+                  modelMapping: settings.modelMapping,
                   builtinTools: builtinToolCatalog,
                   permissionModeMapping,
                   mcpServers: settings.mcpServers,
@@ -543,12 +531,12 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           }
           const turnStartConfig = validateACPColdSessionConfiguration({
             coldSession,
-            modelId: settings.modelId,
             permissionMode,
             authenticationProfile,
             sessionMeta: settings.session?.meta,
             instructionMapping: settings.instructionMapping,
             outputSchemaMapping: settings.outputSchemaMapping,
+            modelMapping: settings.modelMapping,
             builtinTools: builtinToolCatalog,
             permissionModeMapping,
             mcpServers: settings.mcpServers,
@@ -607,6 +595,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
             providerEnvironment:
               sandboxProviderEnvironment == null ? undefined : {},
             sessionMeta: settings.session?.meta,
+            clientCapabilities: settings.clientCapabilities,
           }),
           ...sandboxProviderAuthenticationEnvironment,
           BRIDGE_CHANNEL_TOKEN: token,
@@ -719,7 +708,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         harnessId: settings.harnessId,
         channel,
         proc,
-        modelId: settings.modelId,
+        modelMapping: settings.modelMapping,
+        defaultModelId: settings.modelId,
         sessionMeta: settings.session?.meta,
         instructionMapping: settings.instructionMapping,
         outputSchemaMapping: settings.outputSchemaMapping,
@@ -735,7 +725,9 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           isResume,
           lifecycleState: lifecycleData,
         }),
-        skillsFingerprint,
+        instructionsFingerprint: lifecycleData?.instructionsFingerprint,
+        sandbox: toolSafeSandboxSession,
+        sessionWorkDir: workDir,
         skillsDirectory,
         acpSessionId: lifecycleData?.acpSessionId,
         bridgePort: boundPort,
@@ -1041,7 +1033,8 @@ function createSession({
   harnessId,
   channel,
   proc,
-  modelId,
+  modelMapping,
+  defaultModelId,
   sessionMeta,
   instructionMapping,
   outputSchemaMapping,
@@ -1054,7 +1047,9 @@ function createSession({
   mcpServers,
   isMcpToolCall,
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
-  skillsFingerprint,
+  instructionsFingerprint: instructionsFingerprintAtStart,
+  sandbox,
+  sessionWorkDir,
   skillsDirectory,
   acpSessionId: acpSessionIdAtStart,
   bridgePort,
@@ -1074,7 +1069,8 @@ function createSession({
   harnessId: string;
   channel: ACPChannel;
   proc: Experimental_SandboxProcess | undefined;
-  modelId: string | undefined;
+  modelMapping: ACPModelMapping;
+  defaultModelId: string | undefined;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
   instructionMapping: ACPInstructionMapping | undefined;
   outputSchemaMapping: ACPOutputSchemaMapping | undefined;
@@ -1087,7 +1083,9 @@ function createSession({
   mcpServers: Record<string, unknown> | undefined;
   isMcpToolCall: ((toolCall: ACPToolCall) => boolean) | undefined;
   initialGuidanceApplied: boolean;
-  skillsFingerprint: string;
+  instructionsFingerprint: string | undefined;
+  sandbox: SandboxSession;
+  sessionWorkDir: string;
   skillsDirectory: string;
   acpSessionId: string | undefined;
   bridgePort: number;
@@ -1106,6 +1104,7 @@ function createSession({
   let stopped = false;
   let turnInFlight = turnInFlightAtStart;
   let initialGuidanceApplied = initialGuidanceAppliedAtStart;
+  let instructionsFingerprint = instructionsFingerprintAtStart;
   let latestACPSessionId = acpSessionIdAtStart;
   let latestTurnStartConfig = turnStartConfigAtStart;
 
@@ -1365,7 +1364,6 @@ function createSession({
       : {
           coldSession: createACPColdSessionState({
             turnStartConfig: latestTurnStartConfig,
-            modelId,
           }),
         }),
     ...(!includeTurnStartConfig || latestTurnStartConfig == null
@@ -1374,16 +1372,34 @@ function createSession({
     ...(recoveryStatus == null ? {} : { recovery: recoveryStatus }),
     ...(restoration == null ? {} : { restoration }),
     initialGuidanceApplied,
-    skillsMaterialized: true,
-    skillsFingerprint,
+    ...(instructionsFingerprint == null ? {} : { instructionsFingerprint }),
     skillsDirectory,
   });
 
+  const synchronizeSkills = async ({
+    skills,
+    abortSignal,
+  }: {
+    skills: ReadonlyArray<HarnessV1Skill>;
+    abortSignal?: AbortSignal;
+  }): Promise<void> => {
+    await materializeACPSkills({
+      sandbox,
+      rootDir: skillsDirectory,
+      sessionWorkDir,
+      skills,
+      abortSignal,
+    });
+  };
+
   return {
     sessionId,
     isResume,
-    ...(modelId == null ? {} : { modelId }),
     doPromptTurn: async options => {
+      await synchronizeSkills({
+        skills: options.skills,
+        abortSignal: options.abortSignal,
+      });
       if (options.responseFormat?.type === 'json') {
         if (options.responseFormat.schema == null) {
           throw unsupported({
@@ -1413,6 +1429,7 @@ function createSession({
         prompt: options.prompt,
         harnessId,
       });
+      const model = options.model ?? defaultModelId;
       const turnStartConfig = createACPTurnStartConfig({
         prompt,
         tools: options.tools ?? [],
@@ -1426,6 +1443,11 @@ function createSession({
         instructionMapping,
         responseFormat: options.responseFormat,
         outputSchemaMapping,
+        model,
+        modelMapping,
+      });
+      const nextInstructionsFingerprint = fingerprintValue({
+        value: options.instructions ?? null,
       });
       const control = wireTurn({
         emit: options.emit,
@@ -1439,15 +1461,14 @@ function createSession({
           turnInFlight = true;
           channel.send({
             type: 'start',
-            prompt: initialGuidanceApplied
-              ? prompt
-              : prependACPInitialGuidance({
-                  prompt,
-                  instructions:
-                    instructionMapping == null
-                      ? options.instructions
-                      : undefined,
-                }),
+            prompt:
+              instructionsFingerprint !== nextInstructionsFingerprint &&
+              (instructionMapping == null || initialGuidanceApplied)
+                ? prependACPInstructionGuidance({
+                    prompt,
+                    instructions: options.instructions,
+                  })
+                : prompt,
             ...(instructionMapping == null
               ? {}
               : {
@@ -1460,6 +1481,7 @@ function createSession({
             builtinTools,
             permissionMode,
             permissionModeMapping,
+            ...(model == null ? {} : { model, modelMapping }),
             ...(options.responseFormat == null
               ? {}
               : { responseFormat: options.responseFormat }),
@@ -1472,11 +1494,16 @@ function createSession({
           });
           latestTurnStartConfig = turnStartConfig;
           initialGuidanceApplied = true;
+          instructionsFingerprint = nextInstructionsFingerprint;
         },
       });
       return control;
     },
     doContinueTurn: async options => {
+      await synchronizeSkills({
+        skills: options.skills,
+        abortSignal: options.abortSignal,
+      });
       if (options.responseFormat?.type === 'json') {
         if (options.responseFormat.schema == null) {
           throw unsupported({
@@ -1518,6 +1545,12 @@ function createSession({
             builtinTools: turnStartConfig.builtinTools,
             permissionMode: turnStartConfig.permissionMode,
             permissionModeMapping: turnStartConfig.permissionModeMapping,
+            ...(turnStartConfig.model == null
+              ? {}
+              : {
+                  model: turnStartConfig.model,
+                  modelMapping: turnStartConfig.modelMapping,
+                }),
             ...(turnStartConfig.responseFormat == null
               ? {}
               : { responseFormat: turnStartConfig.responseFormat }),
@@ -1715,6 +1748,7 @@ function validateACPTurnStartConfig({
   sessionMeta,
   instructionMapping,
   outputSchemaMapping,
+  modelMapping,
   builtinTools,
   permissionModeMapping,
   mcpServers,
@@ -1724,6 +1758,7 @@ function validateACPTurnStartConfig({
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
   instructionMapping: ACPInstructionMapping | undefined;
   outputSchemaMapping: ACPOutputSchemaMapping | undefined;
+  modelMapping: ACPModelMapping;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   permissionModeMapping: ACPPermissionModeMapping | undefined;
   mcpServers: Record<string, unknown> | undefined;
@@ -1741,6 +1776,8 @@ function validateACPTurnStartConfig({
     instructionMapping,
     responseFormat: turnStartConfig.responseFormat,
     outputSchemaMapping,
+    model: turnStartConfig.model,
+    modelMapping,
   });
   if (
     current.configurationFingerprint !==
@@ -1754,24 +1791,24 @@ function validateACPTurnStartConfig({
 
 function validateACPColdSessionConfiguration({
   coldSession,
-  modelId,
   permissionMode,
   authenticationProfile,
   sessionMeta,
   instructionMapping,
   outputSchemaMapping,
+  modelMapping,
   builtinTools,
   permissionModeMapping,
   mcpServers,
   debug,
 }: {
   coldSession: ACPColdSessionState;
-  modelId: string | undefined;
   permissionMode: NonNullable<StartMessage['permissionMode']>;
   authenticationProfile: ACPAuthenticationProfileIdentity;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
   instructionMapping: ACPInstructionMapping | undefined;
   outputSchemaMapping: ACPOutputSchemaMapping | undefined;
+  modelMapping: ACPModelMapping;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   permissionModeMapping: ACPPermissionModeMapping | undefined;
   mcpServers: Record<string, unknown> | undefined;
@@ -1790,11 +1827,12 @@ function validateACPColdSessionConfiguration({
     instructionMapping,
     responseFormat: coldSession.responseFormat,
     outputSchemaMapping,
+    model: undefined,
+    modelMapping,
   });
   if (
     current.configurationFingerprint !== coldSession.configurationFingerprint ||
-    coldSession.permissionMode !== permissionMode ||
-    coldSession.modelId !== modelId
+    coldSession.permissionMode !== permissionMode
   ) {
     throw new Error(
       'ACP cold-session state is incompatible with the current non-secret session configuration.',

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

@@ -6,8 +6,7 @@ import type {
 
 export type ACPPromptGuidanceLifecycleState = {
   readonly initialGuidanceApplied?: boolean;
-  readonly skillsMaterialized?: boolean;
-  readonly skillsFingerprint?: string;
+  readonly instructionsFingerprint?: string;
   readonly skillsDirectory?: string;
 };
 
@@ -47,33 +46,6 @@ export function resolveACPInitialGuidanceApplied({
   return lifecycleState?.initialGuidanceApplied ?? true;
 }
 
-export function shouldMaterializeACPSkills({
-  isResume,
-  lifecycleState,
-  skillsFingerprint,
-  skillsDirectory,
-}: {
-  isResume: boolean;
-  lifecycleState: ACPPromptGuidanceLifecycleState | undefined;
-  skillsFingerprint: string;
-  skillsDirectory: string;
-}): boolean {
-  if (
-    isResume &&
-    lifecycleState?.skillsFingerprint != null &&
-    lifecycleState.skillsFingerprint !== skillsFingerprint
-  ) {
-    throw new Error(
-      'ACP lifecycle state was created with a different set of skills.',
-    );
-  }
-  return (
-    !isResume ||
-    lifecycleState?.skillsMaterialized !== true ||
-    lifecycleState.skillsDirectory !== skillsDirectory
-  );
-}
-
 export function validateACPLifecycleCompatibility({
   harnessId,
   lifecycleHarnessId,

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

@@ -66,7 +66,7 @@ export function convertHarnessPromptToACPTextBlocks({
   return content;
 }
 
-export function prependACPInitialGuidance({
+export function prependACPInstructionGuidance({
   prompt,
   instructions,
 }: {

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

@@ -75,6 +75,16 @@ export type ACPProviderAuthentication = {
   };
 };
 
+export type ACPModelMapping =
+  | {
+      readonly type: 'session-config-option';
+      readonly path: string;
+    }
+  | {
+      readonly type: 'session-model';
+      readonly path: string;
+    };
+
 export type ACPCredentialBrokering = ({
   env,
   sandboxEnv,
@@ -143,7 +153,15 @@ export type ACPV1Settings = {
    */
   readonly env?: Readonly<Record<string, string>>;
   readonly authentication?: ACPAuthentication;
+  readonly clientCapabilities?: Readonly<Record<string, ACPSerializableValue>>;
   readonly providerAuthentication?: ACPProviderAuthentication;
+  /**
+   * Maps the HarnessAgent model identifier to an ACP session operation.
+   */
+  readonly modelMapping: ACPModelMapping;
+  /**
+   * @deprecated Use `model` on `HarnessAgent` instead.
+   */
   readonly modelId?: string;
   /**
    * Native skills directory relative to the ACP implementation's home
@@ -152,7 +170,8 @@ export type ACPV1Settings = {
   readonly skillsDirectory?: string;
   /**
    * Routes HarnessAgent instructions to a runtime-native system or developer
-   * prompt. When omitted, instructions are prepended to the first user prompt.
+   * prompt. Changed instructions are prepended to the next user prompt when
+   * ACP does not expose a native per-turn instruction update.
    */
   readonly instructionMapping?: ACPInstructionMapping;
   /**