@ai-sdk/harness-acp 1.0.29 → 1.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,16 +26,16 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.91",
-    "@ai-sdk/provider-utils": "5.0.32",
+    "@ai-sdk/harness": "1.0.93",
+    "@ai-sdk/provider-utils": "5.0.33",
     "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-auth.ts

@@ -1,15 +1,18 @@
 import { createHash } from 'node:crypto';
-import { getAiGatewayAuthFromEnv } from '@ai-sdk/harness/utils';
+import {
+  getAiGatewayAuthFromEnv,
+  isHarnessAuthenticationEnvironment,
+} from '@ai-sdk/harness/utils';
 import type {
   ACPAuthentication,
+  ACPAuthenticationMode as ACPV1AuthenticationMode,
   ACPProviderAuthentication,
-  ACPProviderAuthenticationMode,
 } from './v1';
 import type { ACPResolvedProviderAuthentication } from './v1/bridge/acp-v1-bridge-environment';
 
 const DEFAULT_AI_GATEWAY_BASE_URL = 'https://ai-gateway.vercel.sh';
 
-export type ACPAuthOptions = ACPProviderAuthenticationMode;
+export type ACPAuthenticationMode = ACPV1AuthenticationMode;
 
 export type ACPClientApp = {
   readonly name: string;
@@ -17,7 +20,7 @@ export type ACPClientApp = {
 };
 
 type ACPAuthResolutionOptions = {
-  readonly mode?: ACPAuthOptions;
+  readonly mode?: ACPAuthenticationMode;
   readonly providerAuthentication: ACPProviderAuthentication | undefined;
   readonly clientApp: ACPClientApp;
 };
@@ -102,6 +105,10 @@ export function resolveACPProviderAuthentication({
     AI_SDK_ACP_CLIENT_APP_NAME: auth.clientApp.name,
     AI_SDK_ACP_CLIENT_APP_VERSION: auth.clientApp.version,
   };
+  const resolvedEnv = resolveACPAuthenticationEnvironment({
+    auth: auth.mode,
+    env,
+  });
   const providerAuthentication = auth.providerAuthentication;
   if (providerAuthentication == null) {
     return { providerAuthentication: undefined, env: clientAppEnv };
@@ -114,7 +121,7 @@ export function resolveACPProviderAuthentication({
     };
   }
 
-  const mode = auth.mode ?? 'auto';
+  const mode = resolveACPProviderAuthenticationMode(auth.mode);
   if (mode === 'direct') {
     return {
       providerAuthentication: { type: 'direct' },
@@ -126,12 +133,12 @@ export function resolveACPProviderAuthentication({
     compatibility?.type === 'ai-gateway'
       ? {
           apiKey: resolveGatewayCredential({
-            env,
+            env: resolvedEnv,
             credentialSource: compatibility.credentialSource,
           }),
           baseUrl: compatibility.baseUrl,
         }
-      : getAiGatewayAuthFromEnv({ env });
+      : getAiGatewayAuthFromEnv({ env: resolvedEnv });
   const apiKey = gateway.apiKey;
   if (compatibility == null && mode === 'auto' && apiKey == null) {
     return {
@@ -166,20 +173,22 @@ export function resolveACPProviderAuthenticationCompatibility({
   providerAuthentication,
   env,
 }: {
-  auth?: ACPProviderAuthenticationMode;
+  auth?: ACPAuthenticationMode;
   providerAuthentication: ACPProviderAuthentication | undefined;
   env: Record<string, string | undefined>;
 }): ACPProviderAuthenticationCompatibility | undefined {
+  const resolvedEnv = resolveACPAuthenticationEnvironment({
+    auth,
+    env,
+  });
   if (providerAuthentication == null) return undefined;
 
-  const mode = auth;
+  const mode = resolveACPProviderAuthenticationMode(auth);
   if (mode === 'direct') {
     return { type: 'direct', mode };
   }
 
-  const credentialSource = resolveGatewayCredentialSource({
-    env,
-  });
+  const credentialSource = resolveGatewayCredentialSource({ env: resolvedEnv });
   if (mode === 'auto' && credentialSource == null) {
     return { type: 'direct', mode };
   }
@@ -189,10 +198,26 @@ export function resolveACPProviderAuthenticationCompatibility({
     mode,
     env: providerAuthentication.gateway.env,
     credentialSource,
-    baseUrl: env.AI_GATEWAY_BASE_URL ?? DEFAULT_AI_GATEWAY_BASE_URL,
+    baseUrl: resolvedEnv.AI_GATEWAY_BASE_URL ?? DEFAULT_AI_GATEWAY_BASE_URL,
   };
 }
 
+function resolveACPProviderAuthenticationMode(
+  auth: ACPAuthenticationMode | undefined,
+): Extract<ACPAuthenticationMode, string> {
+  return typeof auth === 'string' || auth == null ? (auth ?? 'auto') : 'auto';
+}
+
+export function resolveACPAuthenticationEnvironment({
+  auth,
+  env,
+}: {
+  auth: ACPAuthenticationMode | undefined;
+  env: Record<string, string | undefined>;
+}): Record<string, string | undefined> {
+  return isHarnessAuthenticationEnvironment(auth) ? auth : env;
+}
+
 export function resolveACPEnv({
   auth,
   env,

package/src/acp-harness.ts

@@ -49,6 +49,13 @@ export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly env?: ACPV1Settings['env'];
   readonly authentication?: ACPV1Settings['authentication'];
   readonly providerAuthentication?: ACPV1Settings['providerAuthentication'];
+  /**
+   * Maps a HarnessAgent model identifier to implementation launch settings.
+   */
+  readonly resolveModel: ACPV1Settings['resolveModel'];
+  /**
+   * @deprecated Use `model` on `HarnessAgent` instead.
+   */
   readonly modelId?: ACPV1Settings['modelId'];
   readonly skillsDirectory?: ACPV1Settings['skillsDirectory'];
   readonly instructionMapping?: ACPV1Settings['instructionMapping'];
@@ -103,8 +110,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

@@ -1,5 +1,5 @@
 export { createACP } from './acp-harness';
-export type { ACPAuthOptions, ACPClientApp } from './acp-auth';
+export type { ACPAuthenticationMode, ACPClientApp } from './acp-auth';
 export type { ACPHarnessSettings } from './acp-harness';
 export type {
   ACPAnnotations,
@@ -24,6 +24,8 @@ export type {
   ACPAuthentication,
   ACPInstallCommandSource,
   ACPInstructionMapping,
+  ACPModelResolution,
+  ACPModelResolver,
   ACPNpmLockedSource,
   ACPNpmSimpleSource,
   ACPOutputSchemaMapping,
@@ -31,7 +33,6 @@ export type {
   ACPPermissionModeTarget,
   ACPProfileValue,
   ACPProviderAuthentication,
-  ACPProviderAuthenticationMode,
   ACPSerializablePrimitive,
   ACPSerializableValue,
   ACPSource,

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';
@@ -39,6 +40,7 @@ import {
 import { WebSocket } from 'ws';
 import {
   createACPAuthenticationProfileIdentity,
+  resolveACPAuthenticationEnvironment,
   resolveACPProviderAuthentication,
   resolveACPProviderAuthenticationCompatibility,
   type ACPAuthenticationProfileIdentity,
@@ -69,13 +71,12 @@ 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,
@@ -87,7 +88,6 @@ import type {
   ACPV1Settings,
 } from './acp-v1-settings';
 import {
-  createACPSkillsFingerprint,
   materializeACPSkills,
   resolveACPPrivateSessionDirectory,
   resolveACPSkillsDirectory,
@@ -158,11 +158,11 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       `ACP harnessId must be a stable kebab-case identifier; received ${JSON.stringify(settings.harnessId)}.`,
     );
   }
-  const implementation = createACPV1Implementation({ settings });
-  validateACPV1Implementation(implementation);
+  const baseImplementation = createACPV1Implementation({ settings });
+  validateACPV1Implementation(baseImplementation);
   const bootstrap = createACPBootstrap({
     harnessId: settings.harnessId,
-    implementation,
+    implementation: baseImplementation,
   });
   const permissionModeMapping = isCompletePermissionModeMapping({
     value: settings.permissionModeMapping,
@@ -186,8 +186,30 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
             'ACP built-in tool filtering is not available in this initial ACP v1 implementation.',
         });
       }
+      const modelId = startOptions.model ?? settings.modelId;
+      const modelConfiguration =
+        modelId == null ? undefined : settings.resolveModel({ model: modelId });
+      const implementation = {
+        ...baseImplementation,
+        ...(modelConfiguration?.args == null
+          ? {}
+          : { args: modelConfiguration.args }),
+        ...(modelConfiguration?.env == null
+          ? {}
+          : {
+              env: {
+                ...baseImplementation.env,
+                ...modelConfiguration.env,
+              },
+            }),
+      };
+      validateACPV1Implementation(implementation);
       const permissionMode = startOptions.permissionMode ?? 'allow-all';
       const env = { ...process.env };
+      const authenticationEnvironment = resolveACPAuthenticationEnvironment({
+        auth: settings.auth,
+        env,
+      });
       const providerAuthenticationCompatibility =
         resolveACPProviderAuthenticationCompatibility({
           auth: settings.auth,
@@ -259,6 +281,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       const implementationEnvironment = resolveImplementationEnvironment({
         implementation,
         env,
+        credentialEnv: authenticationEnvironment,
       });
       let sandboxImplementationEnvironment = implementationEnvironment;
       let sandboxProviderAuthenticationEnvironment =
@@ -375,24 +398,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]) =>
@@ -447,7 +452,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               harnessId: settings.harnessId,
               channel: attachChannel,
               proc: undefined,
-              modelId: settings.modelId,
+              modelId,
               sessionMeta: settings.session?.meta,
               instructionMapping: settings.instructionMapping,
               outputSchemaMapping: settings.outputSchemaMapping,
@@ -463,7 +468,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,
@@ -537,7 +544,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           }
           const turnStartConfig = validateACPColdSessionConfiguration({
             coldSession,
-            modelId: settings.modelId,
+            modelId,
             permissionMode,
             authenticationProfile,
             sessionMeta: settings.session?.meta,
@@ -601,6 +608,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
             providerEnvironment:
               sandboxProviderEnvironment == null ? undefined : {},
             sessionMeta: settings.session?.meta,
+            implementationArgs: modelConfiguration?.args,
+            implementationEnv: modelConfiguration?.env,
           }),
           ...sandboxProviderAuthenticationEnvironment,
           BRIDGE_CHANNEL_TOKEN: token,
@@ -713,7 +722,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         harnessId: settings.harnessId,
         channel,
         proc,
-        modelId: settings.modelId,
+        modelId,
         sessionMeta: settings.session?.meta,
         instructionMapping: settings.instructionMapping,
         outputSchemaMapping: settings.outputSchemaMapping,
@@ -729,7 +738,9 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           isResume,
           lifecycleState: lifecycleData,
         }),
-        skillsFingerprint,
+        instructionsFingerprint: lifecycleData?.instructionsFingerprint,
+        sandbox: toolSafeSandboxSession,
+        sessionWorkDir: workDir,
         skillsDirectory,
         acpSessionId: lifecycleData?.acpSessionId,
         bridgePort: boundPort,
@@ -1048,7 +1059,9 @@ function createSession({
   mcpServers,
   isMcpToolCall,
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
-  skillsFingerprint,
+  instructionsFingerprint: instructionsFingerprintAtStart,
+  sandbox,
+  sessionWorkDir,
   skillsDirectory,
   acpSessionId: acpSessionIdAtStart,
   bridgePort,
@@ -1081,7 +1094,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;
@@ -1100,6 +1115,7 @@ function createSession({
   let stopped = false;
   let turnInFlight = turnInFlightAtStart;
   let initialGuidanceApplied = initialGuidanceAppliedAtStart;
+  let instructionsFingerprint = instructionsFingerprintAtStart;
   let latestACPSessionId = acpSessionIdAtStart;
   let latestTurnStartConfig = turnStartConfigAtStart;
 
@@ -1368,16 +1384,35 @@ 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({
@@ -1421,6 +1456,9 @@ function createSession({
         responseFormat: options.responseFormat,
         outputSchemaMapping,
       });
+      const nextInstructionsFingerprint = fingerprintValue({
+        value: options.instructions ?? null,
+      });
       const control = wireTurn({
         emit: options.emit,
         abortSignal: options.abortSignal,
@@ -1433,15 +1471,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
               ? {}
               : {
@@ -1466,11 +1503,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({

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

@@ -1,4 +1,5 @@
 import type {
+  HarnessV1Authentication,
   HarnessV1CredentialForwarding,
   HarnessV1PermissionMode,
   HarnessV1RequestTransformation,
@@ -66,7 +67,7 @@ export type ACPAuthentication = {
   readonly clientCapabilities?: Readonly<Record<string, ACPSerializableValue>>;
 };
 
-export type ACPProviderAuthenticationMode = 'auto' | 'direct' | 'ai-gateway';
+export type ACPAuthenticationMode = HarnessV1Authentication;
 
 export type ACPProviderAuthentication = {
   readonly gateway: {
@@ -74,6 +75,21 @@ export type ACPProviderAuthentication = {
   };
 };
 
+export type ACPModelResolution = {
+  /**
+   * Replaces the implementation's static launch arguments.
+   */
+  readonly args?: ReadonlyArray<string>;
+  /**
+   * Overlays the implementation's static launch environment.
+   */
+  readonly env?: Readonly<Record<string, string>>;
+};
+
+export type ACPModelResolver = (options: {
+  readonly model: string;
+}) => ACPModelResolution;
+
 export type ACPCredentialBrokering = ({
   env,
   sandboxEnv,
@@ -123,7 +139,7 @@ export type ACPV1Settings = {
   readonly harnessId: string;
   readonly mcpServers?: Record<string, unknown>;
   readonly isMcpToolCall?: (toolCall: ACPToolCall) => boolean;
-  readonly auth?: ACPProviderAuthenticationMode;
+  readonly auth?: ACPAuthenticationMode;
   readonly source: ACPSource;
   readonly executable: string;
   readonly args?: ReadonlyArray<string>;
@@ -143,6 +159,13 @@ export type ACPV1Settings = {
   readonly env?: Readonly<Record<string, string>>;
   readonly authentication?: ACPAuthentication;
   readonly providerAuthentication?: ACPProviderAuthentication;
+  /**
+   * Maps a HarnessAgent model identifier to implementation launch settings.
+   */
+  readonly resolveModel: ACPModelResolver;
+  /**
+   * @deprecated Use `model` on `HarnessAgent` instead.
+   */
   readonly modelId?: string;
   /**
    * Native skills directory relative to the ACP implementation's home
@@ -151,7 +174,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;
   /**