@ai-sdk/harness-acp 1.0.28 → 1.0.29

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @ai-sdk/harness-acp
 
+## 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.29" : "0.0.0-test";
 function createHostToolMCPServer({
   tools: tools2,
   revision = 1,

package/dist/index.d.ts

@@ -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.
@@ -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'];

package/dist/index.js

@@ -639,28 +639,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 +1002,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 +1052,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 +1090,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 +1111,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
@@ -1420,26 +1407,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 +1496,8 @@ function createACPV1({
                 isResume: true,
                 lifecycleState: lifecycleData
               }),
-              skillCatalog,
               skillsFingerprint,
+              skillsDirectory,
               acpSessionId: lifecycleData.acpSessionId,
               bridgePort: coords.port,
               bridgeToken: coords.token,
@@ -1744,8 +1734,8 @@ function createACPV1({
           isResume,
           lifecycleState: lifecycleData
         }),
-        skillCatalog,
         skillsFingerprint,
+        skillsDirectory,
         acpSessionId: lifecycleData?.acpSessionId,
         bridgePort: boundPort,
         bridgeToken: token,
@@ -1983,8 +1973,8 @@ function createSession({
   mcpServers,
   isMcpToolCall,
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
-  skillCatalog,
   skillsFingerprint,
+  skillsDirectory,
   acpSessionId: acpSessionIdAtStart,
   bridgePort,
   bridgeToken,
@@ -2245,7 +2235,8 @@ function createSession({
     ...restoration == null ? {} : { restoration },
     initialGuidanceApplied,
     skillsMaterialized: true,
-    skillsFingerprint
+    skillsFingerprint,
+    skillsDirectory
   });
   return {
     sessionId,
@@ -2306,8 +2297,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 +2601,7 @@ function deserializeBridgeError({
 }
 
 // src/version.ts
-var VERSION = true ? "1.0.28" : "0.0.0-test";
+var VERSION = true ? "1.0.29" : "0.0.0-test";
 
 // src/acp-harness.ts
 var ACP_CLIENT_APP = {
@@ -2651,7 +2641,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)) {