@ai-sdk/harness-acp 1.0.28 → 1.0.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.90",
+    "@ai-sdk/harness": "1.0.92",
     "@ai-sdk/provider-utils": "5.0.32",
     "ws": "^8.21.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

@@ -50,6 +50,7 @@ export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly authentication?: ACPV1Settings['authentication'];
   readonly providerAuthentication?: ACPV1Settings['providerAuthentication'];
   readonly modelId?: ACPV1Settings['modelId'];
+  readonly skillsDirectory?: ACPV1Settings['skillsDirectory'];
   readonly instructionMapping?: ACPV1Settings['instructionMapping'];
   readonly outputSchemaMapping?: ACPV1Settings['outputSchemaMapping'];
   readonly permissionModeMapping?: ACPV1Settings['permissionModeMapping'];
@@ -104,6 +105,7 @@ const acpResumeStateSchema = z.object({
   initialGuidanceApplied: z.boolean().optional(),
   skillsMaterialized: z.boolean().optional(),
   skillsFingerprint: z.string().optional(),
+  skillsDirectory: z.string().optional(),
 });
 
 export function createACP<TBuiltinTools extends ToolSet = {}>(

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,
@@ -31,7 +31,6 @@ export type {
   ACPPermissionModeTarget,
   ACPProfileValue,
   ACPProviderAuthentication,
-  ACPProviderAuthenticationMode,
   ACPSerializablePrimitive,
   ACPSerializableValue,
   ACPSource,

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

@@ -39,6 +39,7 @@ import {
 import { WebSocket } from 'ws';
 import {
   createACPAuthenticationProfileIdentity,
+  resolveACPAuthenticationEnvironment,
   resolveACPProviderAuthentication,
   resolveACPProviderAuthenticationCompatibility,
   type ACPAuthenticationProfileIdentity,
@@ -76,7 +77,6 @@ import {
 import {
   convertHarnessPromptToACPTextBlocks,
   prependACPInitialGuidance,
-  type ACPSkillCatalogEntry,
 } from './acp-v1-prompt';
 import type {
   ACPInstructionMapping,
@@ -91,6 +91,7 @@ import {
   createACPSkillsFingerprint,
   materializeACPSkills,
   resolveACPPrivateSessionDirectory,
+  resolveACPSkillsDirectory,
 } from './acp-v1-skills';
 
 const HARNESS_ID_REGEXP = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -188,6 +189,10 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       }
       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 +264,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       const implementationEnvironment = resolveImplementationEnvironment({
         implementation,
         env,
+        credentialEnv: authenticationEnvironment,
       });
       let sandboxImplementationEnvironment = implementationEnvironment;
       let sandboxProviderAuthenticationEnvironment =
@@ -366,6 +372,14 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         harnessId: settings.harnessId,
         sessionId: startOptions.sessionId,
       });
+      const skillsDirectory = resolveACPSkillsDirectory({
+        implementationHomeDir:
+          implementation.source.type === 'install-command'
+            ? `${resolvedImplementationDir}/home`
+            : sandboxHomeDir,
+        skillsDirectory: settings.skillsDirectory,
+        sessionWorkDir: workDir,
+      });
       const bridgeStateDir = `${privateSessionDir}/bridge`;
       const skills = startOptions.skills ?? [];
       const skillsFingerprint = createACPSkillsFingerprint({ skills });
@@ -373,21 +387,17 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         isResume,
         lifecycleState: lifecycleData,
         skillsFingerprint,
+        skillsDirectory,
       });
-      let skillCatalog: ReadonlyArray<ACPSkillCatalogEntry> = [];
       if (skills.length > 0) {
-        skillCatalog = (
-          await materializeACPSkills({
-            sandbox: toolSafeSandboxSession,
-            sandboxHomeDir,
-            sessionWorkDir: workDir,
-            harnessId: settings.harnessId,
-            sessionId: startOptions.sessionId,
-            skills,
-            shouldMaterialize: shouldMaterializeSkills,
-            abortSignal: startOptions.abortSignal,
-          })
-        ).catalog;
+        await materializeACPSkills({
+          sandbox: toolSafeSandboxSession,
+          rootDir: skillsDirectory,
+          sessionWorkDir: workDir,
+          skills,
+          shouldMaterialize: shouldMaterializeSkills,
+          abortSignal: startOptions.abortSignal,
+        });
       }
       const report = startOptions.observability?.report;
       const onDiagnostic = report
@@ -459,8 +469,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
                 isResume: true,
                 lifecycleState: lifecycleData,
               }),
-              skillCatalog,
               skillsFingerprint,
+              skillsDirectory,
               acpSessionId: lifecycleData.acpSessionId,
               bridgePort: coords.port,
               bridgeToken: coords.token,
@@ -725,8 +735,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           isResume,
           lifecycleState: lifecycleData,
         }),
-        skillCatalog,
         skillsFingerprint,
+        skillsDirectory,
         acpSessionId: lifecycleData?.acpSessionId,
         bridgePort: boundPort,
         bridgeToken: token,
@@ -1044,8 +1054,8 @@ function createSession({
   mcpServers,
   isMcpToolCall,
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
-  skillCatalog,
   skillsFingerprint,
+  skillsDirectory,
   acpSessionId: acpSessionIdAtStart,
   bridgePort,
   bridgeToken,
@@ -1077,8 +1087,8 @@ function createSession({
   mcpServers: Record<string, unknown> | undefined;
   isMcpToolCall: ((toolCall: ACPToolCall) => boolean) | undefined;
   initialGuidanceApplied: boolean;
-  skillCatalog: ReadonlyArray<ACPSkillCatalogEntry>;
   skillsFingerprint: string;
+  skillsDirectory: string;
   acpSessionId: string | undefined;
   bridgePort: number;
   bridgeToken: string;
@@ -1366,6 +1376,7 @@ function createSession({
     initialGuidanceApplied,
     skillsMaterialized: true,
     skillsFingerprint,
+    skillsDirectory,
   });
 
   return {
@@ -1436,7 +1447,6 @@ function createSession({
                     instructionMapping == null
                       ? options.instructions
                       : undefined,
-                  skills: skillCatalog,
                 }),
             ...(instructionMapping == null
               ? {}

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

@@ -8,6 +8,7 @@ export type ACPPromptGuidanceLifecycleState = {
   readonly initialGuidanceApplied?: boolean;
   readonly skillsMaterialized?: boolean;
   readonly skillsFingerprint?: string;
+  readonly skillsDirectory?: string;
 };
 
 export type ACPBridgeCoordinates = {
@@ -50,10 +51,12 @@ export function shouldMaterializeACPSkills({
   isResume,
   lifecycleState,
   skillsFingerprint,
+  skillsDirectory,
 }: {
   isResume: boolean;
   lifecycleState: ACPPromptGuidanceLifecycleState | undefined;
   skillsFingerprint: string;
+  skillsDirectory: string;
 }): boolean {
   if (
     isResume &&
@@ -64,7 +67,11 @@ export function shouldMaterializeACPSkills({
       'ACP lifecycle state was created with a different set of skills.',
     );
   }
-  return !isResume || lifecycleState?.skillsMaterialized !== true;
+  return (
+    !isResume ||
+    lifecycleState?.skillsMaterialized !== true ||
+    lifecycleState.skillsDirectory !== skillsDirectory
+  );
 }
 
 export function validateACPLifecycleCompatibility({

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

@@ -11,12 +11,6 @@ export const acpTextContentBlockSchema = z.object({
 
 export type ACPTextContentBlock = z.infer<typeof acpTextContentBlockSchema>;
 
-export type ACPSkillCatalogEntry = {
-  readonly name: string;
-  readonly description: string;
-  readonly path: string;
-};
-
 export function convertHarnessPromptToACPTextBlocks({
   prompt,
   harnessId,
@@ -75,32 +69,18 @@ export function convertHarnessPromptToACPTextBlocks({
 export function prependACPInitialGuidance({
   prompt,
   instructions,
-  skills,
 }: {
   prompt: ReadonlyArray<ACPTextContentBlock>;
   instructions: string | undefined;
-  skills: ReadonlyArray<ACPSkillCatalogEntry>;
 }): ACPTextContentBlock[] {
   const hasInstructions = instructions != null && instructions.length > 0;
-  if (!hasInstructions && skills.length === 0) return [...prompt];
+  if (!hasInstructions) return [...prompt];
 
   const lines = [
     '<session-guidance>',
     'This block is operating guidance from the harness, not user-authored content.',
   ];
-  if (hasInstructions) {
-    lines.push('<instructions>', instructions, '</instructions>');
-  }
-  if (skills.length > 0) {
-    lines.push(
-      '<available-skills>',
-      'Load a skill only when relevant by reading its SKILL.md file at the listed absolute path.',
-    );
-    for (const skill of skills) {
-      lines.push(`- ${skill.name}: ${skill.description} (${skill.path})`);
-    }
-    lines.push('</available-skills>');
-  }
+  lines.push('<instructions>', instructions, '</instructions>');
   lines.push('</session-guidance>');
 
   return [{ type: 'text', text: lines.join('\n') }, ...prompt];

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: {
@@ -123,7 +124,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>;
@@ -144,6 +145,11 @@ export type ACPV1Settings = {
   readonly authentication?: ACPAuthentication;
   readonly providerAuthentication?: ACPProviderAuthentication;
   readonly modelId?: string;
+  /**
+   * Native skills directory relative to the ACP implementation's home
+   * directory. Defaults to `.agents/skills`.
+   */
+  readonly skillsDirectory?: string;
   /**
    * Routes HarnessAgent instructions to a runtime-native system or developer
    * prompt. When omitted, instructions are prepended to the first user prompt.

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

@@ -3,9 +3,9 @@ import path from 'node:path';
 import type { HarnessV1Skill } from '@ai-sdk/harness';
 import { writeSkills } from '@ai-sdk/harness/utils';
 import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
-import type { ACPSkillCatalogEntry } from './acp-v1-prompt';
 
 const ACP_SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const DEFAULT_ACP_SKILLS_DIRECTORY = '.agents/skills';
 
 export function createACPSkillsFingerprint({
   skills,
@@ -59,37 +59,21 @@ export function resolveACPPrivateSessionDirectory({
 
 export async function materializeACPSkills({
   sandbox,
-  sandboxHomeDir,
+  rootDir,
   sessionWorkDir,
-  harnessId,
-  sessionId,
   skills,
   shouldMaterialize,
   abortSignal,
 }: {
   sandbox: Experimental_SandboxSession;
-  sandboxHomeDir: string;
+  rootDir: string;
   sessionWorkDir: string;
-  harnessId: string;
-  sessionId: string;
   skills: ReadonlyArray<HarnessV1Skill>;
   shouldMaterialize: boolean;
   abortSignal?: AbortSignal;
-}): Promise<{
-  readonly catalog: ReadonlyArray<ACPSkillCatalogEntry>;
-  readonly rootDir: string;
-}> {
+}): Promise<void> {
   validateACPSkills({ skills });
-
-  const rootDir = path.posix.join(
-    resolveACPPrivateSessionDirectory({
-      sandboxHomeDir,
-      sessionWorkDir,
-      harnessId,
-      sessionId,
-    }),
-    'skills',
-  );
+  assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
 
   if (shouldMaterialize) {
     await writeSkills({
@@ -106,15 +90,40 @@ export async function materializeACPSkills({
         )}: expected a relative POSIX path without traversal.`,
     });
   }
+}
 
-  return {
-    rootDir,
-    catalog: skills.map(skill => ({
-      name: skill.name,
-      description: skill.description,
-      path: path.posix.join(rootDir, skill.name, 'SKILL.md'),
-    })),
-  };
+export function resolveACPSkillsDirectory({
+  implementationHomeDir,
+  skillsDirectory = DEFAULT_ACP_SKILLS_DIRECTORY,
+  sessionWorkDir,
+}: {
+  implementationHomeDir: string;
+  skillsDirectory?: string;
+  sessionWorkDir: string;
+}): string {
+  const containsTraversal = skillsDirectory
+    .split(/[\\/]/)
+    .some(segment => segment === '..');
+  const normalizedDirectory = path.posix.normalize(skillsDirectory);
+  if (
+    skillsDirectory.length === 0 ||
+    skillsDirectory.includes('\\') ||
+    path.posix.isAbsolute(skillsDirectory) ||
+    path.win32.isAbsolute(skillsDirectory) ||
+    containsTraversal ||
+    normalizedDirectory === '.' ||
+    normalizedDirectory.startsWith('../') ||
+    normalizedDirectory.includes('/../') ||
+    normalizedDirectory.endsWith('/..')
+  ) {
+    throw new Error(
+      `ACP skillsDirectory ${JSON.stringify(skillsDirectory)} must be a relative POSIX path without traversal.`,
+    );
+  }
+
+  const rootDir = path.posix.join(implementationHomeDir, normalizedDirectory);
+  assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
+  return rootDir;
 }
 
 function validateACPSkills({

package/src/v1/implementation.ts

@@ -277,20 +277,25 @@ ${implementation.source.command}
 export function resolveImplementationEnvironment({
   implementation,
   env,
+  credentialEnv = env,
 }: {
   implementation: ACPImplementation;
   env: Readonly<Record<string, string | undefined>>;
+  credentialEnv?: Readonly<Record<string, string | undefined>>;
 }): Record<string, string> {
   const forwardedEnvironment: Record<string, string> = {};
-  for (const name of [
-    ...(implementation.forwardEnv ?? []),
-    ...(implementation.credentialEnv ?? []),
-  ]) {
+  for (const name of implementation.forwardEnv ?? []) {
     const value = env[name];
     if (value != null && value.length > 0) {
       forwardedEnvironment[name] = value;
     }
   }
+  for (const name of implementation.credentialEnv ?? []) {
+    const value = credentialEnv[name];
+    if (value != null && value.length > 0) {
+      forwardedEnvironment[name] = value;
+    }
+  }
   return {
     ...forwardedEnvironment,
     ...implementation.env,

package/src/v1/index.ts

@@ -2,6 +2,7 @@ export { createACPV1 } from './acp-v1-harness';
 export type {
   ACPCredentialBrokering,
   ACPAuthentication,
+  ACPAuthenticationMode,
   ACPInstallCommandSource,
   ACPInstructionMapping,
   ACPNpmLockedSource,
@@ -11,7 +12,6 @@ export type {
   ACPPermissionModeTarget,
   ACPProfileValue,
   ACPProviderAuthentication,
-  ACPProviderAuthenticationMode,
   ACPSerializablePrimitive,
   ACPSerializableValue,
   ACPSource,