@ai-sdk/harness-acp 1.0.30 → 1.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.30",
+  "version": "1.0.31",
   "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.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-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

@@ -24,6 +24,8 @@ export type {
   ACPAuthentication,
   ACPInstallCommandSource,
   ACPInstructionMapping,
+  ACPModelResolution,
+  ACPModelResolver,
   ACPNpmLockedSource,
   ACPNpmSimpleSource,
   ACPOutputSchemaMapping,

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,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,
@@ -88,7 +88,6 @@ import type {
   ACPV1Settings,
 } from './acp-v1-settings';
 import {
-  createACPSkillsFingerprint,
   materializeACPSkills,
   resolveACPPrivateSessionDirectory,
   resolveACPSkillsDirectory,
@@ -159,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,
@@ -187,6 +186,24 @@ 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({
@@ -381,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]) =>
@@ -453,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,
@@ -469,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,
@@ -543,7 +544,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           }
           const turnStartConfig = validateACPColdSessionConfiguration({
             coldSession,
-            modelId: settings.modelId,
+            modelId,
             permissionMode,
             authenticationProfile,
             sessionMeta: settings.session?.meta,
@@ -607,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,
@@ -719,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,
@@ -735,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,
@@ -1054,7 +1059,9 @@ function createSession({
   mcpServers,
   isMcpToolCall,
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
-  skillsFingerprint,
+  instructionsFingerprint: instructionsFingerprintAtStart,
+  sandbox,
+  sessionWorkDir,
   skillsDirectory,
   acpSessionId: acpSessionIdAtStart,
   bridgePort,
@@ -1087,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;
@@ -1106,6 +1115,7 @@ function createSession({
   let stopped = false;
   let turnInFlight = turnInFlightAtStart;
   let initialGuidanceApplied = initialGuidanceAppliedAtStart;
+  let instructionsFingerprint = instructionsFingerprintAtStart;
   let latestACPSessionId = acpSessionIdAtStart;
   let latestTurnStartConfig = turnStartConfigAtStart;
 
@@ -1374,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({
@@ -1427,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,
@@ -1439,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
               ? {}
               : {
@@ -1472,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

@@ -75,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,
@@ -144,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
@@ -152,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;
   /**

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

@@ -1,39 +1,12 @@
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import type { HarnessV1Skill } from '@ai-sdk/harness';
-import { writeSkills } from '@ai-sdk/harness/utils';
+import { writeSkills, type WriteSkillsResult } from '@ai-sdk/harness/utils';
 import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
 
 const ACP_SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 export const DEFAULT_ACP_SKILLS_DIRECTORY = '.agents/skills';
 
-export function createACPSkillsFingerprint({
-  skills,
-}: {
-  skills: ReadonlyArray<HarnessV1Skill>;
-}): string {
-  const canonicalSkills = skills
-    .map(skill => ({
-      name: skill.name,
-      description: skill.description,
-      content: skill.content,
-      files: [...(skill.files ?? [])]
-        .map(file => ({
-          path: path.posix.normalize(file.path),
-          content: file.content,
-        }))
-        .sort((left, right) =>
-          compareCanonicalStrings({ left: left.path, right: right.path }),
-        ),
-    }))
-    .sort((left, right) =>
-      compareCanonicalStrings({ left: left.name, right: right.name }),
-    );
-  return createHash('sha256')
-    .update(JSON.stringify(canonicalSkills))
-    .digest('hex');
-}
-
 export function resolveACPPrivateSessionDirectory({
   sandboxHomeDir,
   sessionWorkDir,
@@ -62,34 +35,30 @@ export async function materializeACPSkills({
   rootDir,
   sessionWorkDir,
   skills,
-  shouldMaterialize,
   abortSignal,
 }: {
   sandbox: Experimental_SandboxSession;
   rootDir: string;
   sessionWorkDir: string;
   skills: ReadonlyArray<HarnessV1Skill>;
-  shouldMaterialize: boolean;
   abortSignal?: AbortSignal;
-}): Promise<void> {
+}): Promise<WriteSkillsResult> {
   validateACPSkills({ skills });
   assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
 
-  if (shouldMaterialize) {
-    await writeSkills({
-      sandbox,
-      rootDir,
-      skills,
-      abortSignal,
-      skillNamePattern: ACP_SKILL_NAME_PATTERN,
-      invalidSkillNameMessage: ({ name }) =>
-        `Invalid ACP skill name ${JSON.stringify(name)}: expected a kebab-case slug.`,
-      invalidSkillFilePathMessage: ({ skillName, filePath }) =>
-        `Invalid ACP skill file path ${JSON.stringify(filePath)} for skill ${JSON.stringify(
-          skillName,
-        )}: expected a relative POSIX path without traversal.`,
-    });
-  }
+  return writeSkills({
+    sandbox,
+    rootDir,
+    skills,
+    abortSignal,
+    skillNamePattern: ACP_SKILL_NAME_PATTERN,
+    invalidSkillNameMessage: ({ name }) =>
+      `Invalid ACP skill name ${JSON.stringify(name)}: expected a kebab-case slug.`,
+    invalidSkillFilePathMessage: ({ skillName, filePath }) =>
+      `Invalid ACP skill file path ${JSON.stringify(filePath)} for skill ${JSON.stringify(
+        skillName,
+      )}: expected a relative POSIX path without traversal.`,
+  });
 }
 
 export function resolveACPSkillsDirectory({
@@ -225,13 +194,3 @@ function assertOutsideSessionWorkDir({
     );
   }
 }
-
-function compareCanonicalStrings({
-  left,
-  right,
-}: {
-  left: string;
-  right: string;
-}): number {
-  return left < right ? -1 : left > right ? 1 : 0;
-}

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

@@ -59,6 +59,8 @@ export type ACPBridgeConfiguration = {
   readonly providerAuthentication?: ACPResolvedProviderAuthentication;
   readonly providerEnvironment?: Readonly<Record<string, string>>;
   readonly sessionMeta?: Readonly<Record<string, ACPSerializableValue>>;
+  readonly implementationArgs?: ReadonlyArray<string>;
+  readonly implementationEnv?: Readonly<Record<string, string>>;
 };
 
 const bridgeConfigurationSchema: z.ZodType<ACPBridgeConfiguration> = z.object({
@@ -66,6 +68,8 @@ const bridgeConfigurationSchema: z.ZodType<ACPBridgeConfiguration> = z.object({
   providerAuthentication: providerAuthenticationSchema.optional(),
   providerEnvironment: z.record(z.string(), z.string()).optional(),
   sessionMeta: serializableRecordSchema.optional(),
+  implementationArgs: z.array(z.string()).optional(),
+  implementationEnv: z.record(z.string(), z.string()).optional(),
 });
 
 export function createACPBridgeEnvironment({
@@ -73,6 +77,8 @@ export function createACPBridgeEnvironment({
   providerAuthentication,
   providerEnvironment,
   sessionMeta,
+  implementationArgs,
+  implementationEnv,
 }: ACPBridgeConfiguration): Record<string, string> {
   return {
     [ACP_BRIDGE_CONFIGURATION_ENV]: JSON.stringify({
@@ -80,6 +86,8 @@ export function createACPBridgeEnvironment({
       ...(providerAuthentication == null ? {} : { providerAuthentication }),
       ...(providerEnvironment == null ? {} : { providerEnvironment }),
       ...(sessionMeta == null ? {} : { sessionMeta }),
+      ...(implementationArgs == null ? {} : { implementationArgs }),
+      ...(implementationEnv == null ? {} : { implementationEnv }),
     }),
   };
 }

package/src/v1/bridge/index.ts

@@ -413,15 +413,18 @@ async function ensureSession({
     instructions: start.instructions,
     instructionMapping: start.instructionMapping,
     sessionMeta: bridgeConfiguration.sessionMeta,
-    environment: createChildEnvironment({
-      launchEnv,
-      implementationDir,
-      privateHome: implementation.privateHome,
-    }),
+    environment: {
+      ...createChildEnvironment({
+        launchEnv,
+        implementationDir,
+        privateHome: implementation.privateHome,
+      }),
+      ...bridgeConfiguration.implementationEnv,
+    },
   });
   child = spawn(
     `${implementationDir}/${implementation.executablePath}`,
-    [...implementation.args],
+    [...(bridgeConfiguration.implementationArgs ?? implementation.args)],
     {
       cwd: workDir,
       env: instructionConfiguration.environment,

package/src/v1/bridge/package.json

@@ -4,8 +4,8 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@agentclientprotocol/sdk": "1.2.1",
-    "@modelcontextprotocol/sdk": "1.29.0",
+    "@agentclientprotocol/sdk": "1.4.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "ws": "8.21.0",
     "zod": "4.4.3"
   }