@ai-sdk/harness-acp 1.0.28 → 1.0.30

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @ai-sdk/harness-acp
 
+## 1.0.30
+
+### Patch Changes
+
+- e0d7cfb: feat(harness): allow harness sessions to optionally authenticate from an isolated environment supplied through the `auth` option, and remove support for the formerly deprecated legacy auth options types
+- Updated dependencies [e0d7cfb]
+  - @ai-sdk/harness@1.0.92
+
+## 1.0.29
+
+### Patch Changes
+
+- 20312d6: fix(harness-acp): place skills in their harnesses' natively supported directory instead of applying a manual workaround
+  - @ai-sdk/harness@1.0.91
+
 ## 1.0.28
 
 ### Patch Changes

package/README.md

@@ -103,3 +103,8 @@ instructions below the ACP session request's `_meta` field. A
 the implementation starts. Without a mapping, the adapter preserves its
 backward-compatible behavior and prepends instructions to the first user
 prompt.
+
+Skills are written to `.agents/skills` below the ACP implementation's effective
+`$HOME` and discovered natively by the implementation. Set `skillsDirectory`
+to another relative path, such as `.claude/skills`, when required by the
+implementation.

package/dist/bridge/host-tool-mcp.mjs

@@ -12,7 +12,7 @@ import {
   ListToolsRequestSchema,
   McpError
 } from "@modelcontextprotocol/sdk/types.js";
-var VERSION = true ? "1.0.28" : "0.0.0-test";
+var VERSION = true ? "1.0.30" : "0.0.0-test";
 function createHostToolMCPServer({
   tools: tools2,
   revision = 1,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { HarnessV1RequestTransformation, HarnessV1CredentialForwarding, HarnessV1PermissionMode, HarnessV1PortEndpoint, HarnessV1 } from '@ai-sdk/harness';
+import { HarnessV1Authentication, HarnessV1RequestTransformation, HarnessV1CredentialForwarding, HarnessV1PermissionMode, HarnessV1PortEndpoint, HarnessV1 } from '@ai-sdk/harness';
 import { ToolSet } from '@ai-sdk/provider-utils';
 
 type ACPMetadata = Record<string, unknown>;
@@ -139,7 +139,7 @@ type ACPAuthentication = {
     readonly meta?: Readonly<Record<string, ACPSerializableValue>>;
     readonly clientCapabilities?: Readonly<Record<string, ACPSerializableValue>>;
 };
-type ACPProviderAuthenticationMode = 'auto' | 'direct' | 'ai-gateway';
+type ACPAuthenticationMode$1 = HarnessV1Authentication;
 type ACPProviderAuthentication = {
     readonly gateway: {
         readonly env: Readonly<Record<string, ACPProfileValue>>;
@@ -180,7 +180,7 @@ type ACPV1Settings = {
     readonly harnessId: string;
     readonly mcpServers?: Record<string, unknown>;
     readonly isMcpToolCall?: (toolCall: ACPToolCall) => boolean;
-    readonly auth?: ACPProviderAuthenticationMode;
+    readonly auth?: ACPAuthenticationMode$1;
     readonly source: ACPSource;
     readonly executable: string;
     readonly args?: ReadonlyArray<string>;
@@ -201,6 +201,11 @@ 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.
@@ -222,7 +227,7 @@ type ACPV1Settings = {
     readonly mintBridgeToken?: (sandboxId: string) => string;
 };
 
-type ACPAuthOptions = ACPProviderAuthenticationMode;
+type ACPAuthenticationMode = ACPAuthenticationMode$1;
 type ACPClientApp = {
     readonly name: string;
     readonly version: string;
@@ -263,6 +268,7 @@ 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'];
@@ -273,4 +279,4 @@ declare function createACP<TBuiltinTools extends ToolSet = {}>(settings: ACPHarn
 
 declare const VERSION: string;
 
-export { type ACPAnnotations, type ACPAudioContent, type ACPAuthOptions, type ACPAuthentication, type ACPBlobResourceContents, type ACPClientApp, type ACPContentBlock, type ACPCredentialBrokering, type ACPEmbeddedResource, type ACPHarnessSettings, type ACPImageContent, type ACPInstallCommandSource, type ACPInstructionMapping, type ACPMetadata, type ACPNpmLockedSource, type ACPNpmSimpleSource, type ACPOutputSchemaMapping, type ACPPermissionModeMapping, type ACPPermissionModeTarget, type ACPProfileValue, type ACPProviderAuthentication, type ACPProviderAuthenticationMode, type ACPResourceLink, type ACPRole, type ACPSerializablePrimitive, type ACPSerializableValue, type ACPSource, type ACPTextContent, type ACPTextResourceContents, type ACPToolCall, type ACPToolCallContent, type ACPToolCallLocation, type ACPToolCallStatus, type ACPToolKind, type ACPV1Settings, type ACPValueSource, VERSION, createACP };
+export { type ACPAnnotations, type ACPAudioContent, type ACPAuthentication, type ACPAuthenticationMode, type ACPBlobResourceContents, type ACPClientApp, type ACPContentBlock, type ACPCredentialBrokering, type ACPEmbeddedResource, type ACPHarnessSettings, type ACPImageContent, type ACPInstallCommandSource, type ACPInstructionMapping, type ACPMetadata, type ACPNpmLockedSource, type ACPNpmSimpleSource, type ACPOutputSchemaMapping, type ACPPermissionModeMapping, type ACPPermissionModeTarget, type ACPProfileValue, type ACPProviderAuthentication, type ACPResourceLink, type ACPRole, type ACPSerializablePrimitive, type ACPSerializableValue, type ACPSource, type ACPTextContent, type ACPTextResourceContents, type ACPToolCall, type ACPToolCallContent, type ACPToolCallLocation, type ACPToolCallStatus, type ACPToolKind, type ACPV1Settings, type ACPValueSource, VERSION, createACP };

package/dist/index.js

@@ -33,7 +33,10 @@ import { WebSocket } from "ws";
 
 // src/acp-auth.ts
 import { createHash } from "crypto";
-import { getAiGatewayAuthFromEnv } from "@ai-sdk/harness/utils";
+import {
+  getAiGatewayAuthFromEnv,
+  isHarnessAuthenticationEnvironment
+} from "@ai-sdk/harness/utils";
 var DEFAULT_AI_GATEWAY_BASE_URL = "https://ai-gateway.vercel.sh";
 function createACPAuthenticationProfileIdentity({
   authentication,
@@ -67,6 +70,10 @@ 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: void 0, env: clientAppEnv };
@@ -77,7 +84,7 @@ function resolveACPProviderAuthentication({
       env: clientAppEnv
     };
   }
-  const mode = auth.mode ?? "auto";
+  const mode = resolveACPProviderAuthenticationMode(auth.mode);
   if (mode === "direct") {
     return {
       providerAuthentication: { type: "direct" },
@@ -86,11 +93,11 @@ function resolveACPProviderAuthentication({
   }
   const gateway = 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 {
@@ -120,14 +127,16 @@ function resolveACPProviderAuthenticationCompatibility({
   providerAuthentication,
   env
 }) {
+  const resolvedEnv = resolveACPAuthenticationEnvironment({
+    auth,
+    env
+  });
   if (providerAuthentication == null) return void 0;
-  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 };
   }
@@ -136,9 +145,18 @@ 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) {
+  return typeof auth === "string" || auth == null ? auth ?? "auto" : "auto";
+}
+function resolveACPAuthenticationEnvironment({
+  auth,
+  env
+}) {
+  return isHarnessAuthenticationEnvironment(auth) ? auth : env;
+}
 function resolveGatewayCredentialSource({
   env
 }) {
@@ -366,18 +384,22 @@ ${implementation.source.command}
 }
 function resolveImplementationEnvironment({
   implementation,
-  env
+  env,
+  credentialEnv = env
 }) {
   const forwardedEnvironment = {};
-  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
@@ -639,28 +661,15 @@ function convertHarnessPromptToACPTextBlocks({
 }
 function prependACPInitialGuidance({
   prompt,
-  instructions,
-  skills
+  instructions
 }) {
   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];
 }
@@ -1015,14 +1024,15 @@ function resolveACPInitialGuidanceApplied({
 function shouldMaterializeACPSkills({
   isResume,
   lifecycleState,
-  skillsFingerprint
+  skillsFingerprint,
+  skillsDirectory
 }) {
   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;
+  return !isResume || lifecycleState?.skillsMaterialized !== true || lifecycleState.skillsDirectory !== skillsDirectory;
 }
 function validateACPLifecycleCompatibility({
   harnessId,
@@ -1064,6 +1074,7 @@ import { createHash as createHash4 } from "crypto";
 import path from "path";
 import { writeSkills } from "@ai-sdk/harness/utils";
 var ACP_SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var DEFAULT_ACP_SKILLS_DIRECTORY = ".agents/skills";
 function createACPSkillsFingerprint({
   skills
 }) {
@@ -1101,24 +1112,14 @@ function resolveACPPrivateSessionDirectory({
 }
 async function materializeACPSkills({
   sandbox,
-  sandboxHomeDir,
+  rootDir,
   sessionWorkDir,
-  harnessId,
-  sessionId,
   skills,
   shouldMaterialize,
   abortSignal
 }) {
   validateACPSkills({ skills });
-  const rootDir = path.posix.join(
-    resolveACPPrivateSessionDirectory({
-      sandboxHomeDir,
-      sessionWorkDir,
-      harnessId,
-      sessionId
-    }),
-    "skills"
-  );
+  assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
   if (shouldMaterialize) {
     await writeSkills({
       sandbox,
@@ -1132,14 +1133,22 @@ 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")
-    }))
-  };
+}
+function resolveACPSkillsDirectory({
+  implementationHomeDir,
+  skillsDirectory = DEFAULT_ACP_SKILLS_DIRECTORY,
+  sessionWorkDir
+}) {
+  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({
   skills
@@ -1273,6 +1282,10 @@ function createACPV1({
       }
       const permissionMode = startOptions.permissionMode ?? "allow-all";
       const env = { ...process.env };
+      const authenticationEnvironment = resolveACPAuthenticationEnvironment({
+        auth: settings.auth,
+        env
+      });
       const providerAuthenticationCompatibility = resolveACPProviderAuthenticationCompatibility({
         auth: settings.auth,
         providerAuthentication: settings.providerAuthentication,
@@ -1335,7 +1348,8 @@ function createACPV1({
       }
       const implementationEnvironment = resolveImplementationEnvironment({
         implementation,
-        env
+        env,
+        credentialEnv: authenticationEnvironment
       });
       let sandboxImplementationEnvironment = implementationEnvironment;
       let sandboxProviderAuthenticationEnvironment = resolvedProviderAuthentication.env;
@@ -1420,26 +1434,29 @@ function createACPV1({
         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 });
       const shouldMaterializeSkills = shouldMaterializeACPSkills({
         isResume,
         lifecycleState: lifecycleData,
-        skillsFingerprint
+        skillsFingerprint,
+        skillsDirectory
       });
-      let skillCatalog = [];
       if (skills.length > 0) {
-        skillCatalog = (await materializeACPSkills({
+        await materializeACPSkills({
           sandbox: toolSafeSandboxSession,
-          sandboxHomeDir,
+          rootDir: skillsDirectory,
           sessionWorkDir: workDir,
-          harnessId: settings.harnessId,
-          sessionId: startOptions.sessionId,
           skills,
           shouldMaterialize: shouldMaterializeSkills,
           abortSignal: startOptions.abortSignal
-        })).catalog;
+        });
       }
       const report = startOptions.observability?.report;
       const onDiagnostic = report ? (frame) => report(
@@ -1506,8 +1523,8 @@ function createACPV1({
                 isResume: true,
                 lifecycleState: lifecycleData
               }),
-              skillCatalog,
               skillsFingerprint,
+              skillsDirectory,
               acpSessionId: lifecycleData.acpSessionId,
               bridgePort: coords.port,
               bridgeToken: coords.token,
@@ -1744,8 +1761,8 @@ function createACPV1({
           isResume,
           lifecycleState: lifecycleData
         }),
-        skillCatalog,
         skillsFingerprint,
+        skillsDirectory,
         acpSessionId: lifecycleData?.acpSessionId,
         bridgePort: boundPort,
         bridgeToken: token,
@@ -1983,8 +2000,8 @@ function createSession({
   mcpServers,
   isMcpToolCall,
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
-  skillCatalog,
   skillsFingerprint,
+  skillsDirectory,
   acpSessionId: acpSessionIdAtStart,
   bridgePort,
   bridgeToken,
@@ -2245,7 +2262,8 @@ function createSession({
     ...restoration == null ? {} : { restoration },
     initialGuidanceApplied,
     skillsMaterialized: true,
-    skillsFingerprint
+    skillsFingerprint,
+    skillsDirectory
   });
   return {
     sessionId,
@@ -2306,8 +2324,7 @@ function createSession({
             type: "start",
             prompt: initialGuidanceApplied ? prompt : prependACPInitialGuidance({
               prompt,
-              instructions: instructionMapping == null ? options.instructions : void 0,
-              skills: skillCatalog
+              instructions: instructionMapping == null ? options.instructions : void 0
             }),
             ...instructionMapping == null ? {} : {
               instructionMapping,
@@ -2611,7 +2628,7 @@ function deserializeBridgeError({
 }
 
 // src/version.ts
-var VERSION = true ? "1.0.28" : "0.0.0-test";
+var VERSION = true ? "1.0.30" : "0.0.0-test";
 
 // src/acp-harness.ts
 var ACP_CLIENT_APP = {
@@ -2651,7 +2668,8 @@ var acpResumeStateSchema = z4.object({
   }).optional(),
   initialGuidanceApplied: z4.boolean().optional(),
   skillsMaterialized: z4.boolean().optional(),
-  skillsFingerprint: z4.string().optional()
+  skillsFingerprint: z4.string().optional(),
+  skillsDirectory: z4.string().optional()
 });
 function createACP(settings) {
   if (settings.credentialEnv == null !== (settings.credentialBrokering == null)) {