@ai-sdk/harness-acp 1.0.25 → 1.0.29

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @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
+
+- 0e590d2: feat(harness): harden credential brokering to only apply with correct ephemeral secret
+- Updated dependencies [3e125ba]
+- Updated dependencies [0e590d2]
+  - @ai-sdk/provider-utils@5.0.32
+  - @ai-sdk/harness@1.0.90
+
+## 1.0.27
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.89
+
+## 1.0.26
+
+### Patch Changes
+
+- Updated dependencies [32349cc]
+- Updated dependencies [a9782e1]
+- Updated dependencies [35841f5]
+- Updated dependencies [d2f3353]
+  - @ai-sdk/harness@1.0.88
+  - @ai-sdk/provider-utils@5.0.31
+
 ## 1.0.25
 
 ### Patch Changes

package/README.md

@@ -35,13 +35,20 @@ const codexACP = createACP({
   },
   executable: 'codex-acp',
   credentialEnv: ['CODEX_API_KEY', 'OPENAI_API_KEY'],
-  credentialBrokering: ({ env }) => {
-    const credential = env.CODEX_API_KEY ?? env.OPENAI_API_KEY;
-    if (!credential) return [];
+  credentialBrokering: ({ env, sandboxEnv }) => {
+    const environmentVariableName = env.CODEX_API_KEY
+      ? 'CODEX_API_KEY'
+      : 'OPENAI_API_KEY';
+    const credential = env[environmentVariableName];
+    const sandboxCredential = sandboxEnv?.[environmentVariableName];
+    if (!credential || !sandboxCredential) return [];
     return [
       createCredentialRequestTransformation({
-        baseUrl: 'https://api.openai.com/v1',
-        headers: { Authorization: `Bearer ${credential}` },
+        matchUrl: 'https://api.openai.com/v1',
+        matchHeaders: {
+          Authorization: `Bearer ${sandboxCredential}`,
+        },
+        transformHeaders: { Authorization: `Bearer ${credential}` },
       }),
     ];
   },
@@ -82,7 +89,8 @@ try {
 
 Set `CODEX_API_KEY` or `OPENAI_API_KEY` in the host environment. Sandboxes that
 support additive request transformations receive only credential placeholders;
-the real value is injected into matching outbound requests. Other sandboxes
+the real value is injected only when a matching outbound request contains the
+expected placeholder. Other sandboxes
 retain the legacy behavior of forwarding the value to the ACP process. Codex
 ACP supports only `permissionMode: 'allow-all'` because its
 restrictive modes enable Codex's internal sandbox. A bridge-backed ACP harness
@@ -95,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.25" : "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

@@ -145,8 +145,9 @@ type ACPProviderAuthentication = {
         readonly env: Readonly<Record<string, ACPProfileValue>>;
     };
 };
-type ACPCredentialBrokering = ({ env, }: {
+type ACPCredentialBrokering = ({ env, sandboxEnv, }: {
     env: Readonly<Record<string, string>>;
+    sandboxEnv?: Readonly<Record<string, string>>;
 }) => ReadonlyArray<HarnessV1RequestTransformation>;
 type ACPPermissionModeTarget = {
     readonly type: 'session-mode';
@@ -200,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.
@@ -262,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

@@ -13,12 +13,12 @@ import {
   applyCredentialForwarding,
   createBridgeErrorHandler,
   createBridgeStartupError,
+  createSandboxCredentialEnvironment,
   classifyDiskLog,
   drainBridgeProcessStream,
   forwardBridgeProcessStream,
   getRestrictedSandboxSession,
   markBridgeStarting,
-  maskSandboxCredentials,
   resolveSandboxDefaultWorkingDirectory,
   resolveSandboxHomeDir,
   SandboxChannel,
@@ -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
@@ -1318,6 +1305,21 @@ function createACPV1({
         sandboxSession,
         abortSignal: startOptions.abortSignal
       });
+      const continueFrom = startOptions.continueFrom ?? startOptions.resumeFrom?.continueFrom;
+      const lifecycleState = continueFrom ?? startOptions.resumeFrom;
+      const isContinue = continueFrom != null;
+      const isResume = lifecycleState != null;
+      const lifecycleData = lifecycleState != null ? lifecycleState.data : void 0;
+      if (lifecycleData != null && lifecycleState != null) {
+        validateACPLifecycleCompatibility({
+          harnessId: settings.harnessId,
+          lifecycleHarnessId: lifecycleState.harnessId,
+          implementationIdentity,
+          authenticationProfile,
+          lifecycleData,
+          sandboxId
+        });
+      }
       const implementationEnvironment = resolveImplementationEnvironment({
         implementation,
         env
@@ -1340,30 +1342,35 @@ function createACPV1({
           })
         ])
       ];
+      let sandboxCredentialEnvironment;
       if (settings.credentialBrokering != null && "addRequestTransformations" in sandboxSession && sandboxSession.addRequestTransformations != null) {
         const providerEnvironment = resolveProviderEnvironment({
           resolvedProviderAuthentication,
           clientApp
         });
+        const brokeringEnvironment = {
+          ...implementationEnvironment,
+          ...providerEnvironment
+        };
+        sandboxCredentialEnvironment = lifecycleData?.sandboxCredentialEnvironment ?? await createSandboxCredentialEnvironment({
+          environment: brokeringEnvironment,
+          credentialEnvironmentVariables: credentialForwardingEnvironmentVariables,
+          credentialForwarding: settings.credentialForwarding
+        });
+        sandboxImplementationEnvironment = {
+          ...brokeringEnvironment,
+          ...sandboxCredentialEnvironment
+        };
         const requestTransformations = settings.credentialBrokering({
-          env: {
-            ...implementationEnvironment,
-            ...providerEnvironment
-          }
+          env: brokeringEnvironment,
+          sandboxEnv: sandboxImplementationEnvironment
         });
         if (requestTransformations.length > 0) {
           await sandboxSession.addRequestTransformations(
             requestTransformations
           );
         }
-        sandboxImplementationEnvironment = maskSandboxCredentials({
-          environment: implementationEnvironment,
-          credentialEnvironmentVariables
-        });
-        sandboxProviderEnvironment = resolveBrokeredProviderEnvironment({
-          resolvedProviderAuthentication,
-          clientApp
-        });
+        sandboxProviderEnvironment = resolvedProviderAuthentication.providerAuthentication?.type === "ai-gateway" ? {} : void 0;
       } else if (settings.credentialBrokering != null) {
         warnCredentialBrokeringUnavailable();
       }
@@ -1400,41 +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 continueFrom = startOptions.continueFrom ?? startOptions.resumeFrom?.continueFrom;
-      const lifecycleState = continueFrom ?? startOptions.resumeFrom;
-      const isContinue = continueFrom != null;
-      const isResume = lifecycleState != null;
-      const lifecycleData = lifecycleState != null ? lifecycleState.data : void 0;
-      if (lifecycleData != null && lifecycleState != null) {
-        validateACPLifecycleCompatibility({
-          harnessId: settings.harnessId,
-          lifecycleHarnessId: lifecycleState.harnessId,
-          implementationIdentity,
-          authenticationProfile,
-          lifecycleData,
-          sandboxId
-        });
-      }
       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(
@@ -1501,8 +1496,8 @@ function createACPV1({
                 isResume: true,
                 lifecycleState: lifecycleData
               }),
-              skillCatalog,
               skillsFingerprint,
+              skillsDirectory,
               acpSessionId: lifecycleData.acpSessionId,
               bridgePort: coords.port,
               bridgeToken: coords.token,
@@ -1513,6 +1508,7 @@ function createACPV1({
               turnStartConfig: lifecycleData.turnStartConfig,
               recoveryStatus: lifecycleData.recovery,
               restoration: lifecycleData.restoration,
+              sandboxCredentialEnvironment,
               replayOnly: false,
               lossyRerun: false
             });
@@ -1590,11 +1586,11 @@ function createACPV1({
           };
         }
       }
-      const forwardedImplementationEnvironment = await applyCredentialForwarding({
+      const forwardedImplementationEnvironment = sandboxCredentialEnvironment == null ? await applyCredentialForwarding({
         environment: sandboxImplementationEnvironment,
         credentialEnvironmentVariables: credentialForwardingEnvironmentVariables,
         credentialForwarding: settings.credentialForwarding
-      });
+      }) : sandboxImplementationEnvironment;
       const port = resolveBridgePort({
         sandboxSession,
         override: portOverride,
@@ -1738,8 +1734,8 @@ function createACPV1({
           isResume,
           lifecycleState: lifecycleData
         }),
-        skillCatalog,
         skillsFingerprint,
+        skillsDirectory,
         acpSessionId: lifecycleData?.acpSessionId,
         bridgePort: boundPort,
         bridgeToken: token,
@@ -1753,6 +1749,7 @@ function createACPV1({
           reason: respawnStrategy.reason
         } : void 0,
         restoration: coldRestoration == null ? lifecycleData?.restoration : { method: coldRestoration },
+        sandboxCredentialEnvironment,
         replayOnly: respawnStrategy?.mode === "disk-replay",
         lossyRerun: respawnStrategy?.mode === "lossy-rerun"
       });
@@ -1782,36 +1779,6 @@ function resolveProviderEnvironment({
     }
   });
 }
-function resolveBrokeredProviderEnvironment({
-  resolvedProviderAuthentication,
-  clientApp
-}) {
-  const providerAuthentication = resolvedProviderAuthentication.providerAuthentication;
-  if (providerAuthentication?.type !== "ai-gateway") return {};
-  const baseUrl = requireResolvedEnvironmentValue({
-    environment: resolvedProviderAuthentication.env,
-    name: "AI_SDK_ACP_GATEWAY_BASE_URL"
-  });
-  return Object.fromEntries(
-    Object.entries(providerAuthentication.env).map(
-      ([environmentVariableName, value]) => {
-        const environment = resolveACPLaunchEnvironment({
-          providerAuthentication: {
-            type: "ai-gateway",
-            env: { [environmentVariableName]: value }
-          },
-          gateway: {
-            apiKey: environmentVariableName,
-            baseUrl,
-            clientAppName: clientApp.name,
-            clientAppVersion: clientApp.version
-          }
-        });
-        return [environmentVariableName, environment[environmentVariableName]];
-      }
-    )
-  );
-}
 function resolveACPProviderCredentialEnvironmentVariables({
   providerAuthentication
 }) {
@@ -2006,8 +1973,8 @@ function createSession({
   mcpServers,
   isMcpToolCall,
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
-  skillCatalog,
   skillsFingerprint,
+  skillsDirectory,
   acpSessionId: acpSessionIdAtStart,
   bridgePort,
   bridgeToken,
@@ -2018,6 +1985,7 @@ function createSession({
   turnStartConfig: turnStartConfigAtStart,
   recoveryStatus,
   restoration,
+  sandboxCredentialEnvironment,
   replayOnly,
   lossyRerun
 }) {
@@ -2253,6 +2221,7 @@ function createSession({
   }) => ({
     implementationIdentity,
     authenticationProfile,
+    ...sandboxCredentialEnvironment == null ? {} : { sandboxCredentialEnvironment },
     ...latestACPSessionId == null ? {} : { acpSessionId: latestACPSessionId },
     ...bridge == null ? {} : { bridge },
     ...latestTurnStartConfig == null ? {} : {
@@ -2266,7 +2235,8 @@ function createSession({
     ...restoration == null ? {} : { restoration },
     initialGuidanceApplied,
     skillsMaterialized: true,
-    skillsFingerprint
+    skillsFingerprint,
+    skillsDirectory
   });
   return {
     sessionId,
@@ -2327,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,
@@ -2632,7 +2601,7 @@ function deserializeBridgeError({
 }
 
 // src/version.ts
-var VERSION = true ? "1.0.25" : "0.0.0-test";
+var VERSION = true ? "1.0.29" : "0.0.0-test";
 
 // src/acp-harness.ts
 var ACP_CLIENT_APP = {
@@ -2658,6 +2627,7 @@ var acpResumeStateSchema = z4.object({
     providerMode: z4.enum(["auto", "direct", "ai-gateway"]).optional(),
     gatewayCredentialSource: z4.enum(["AI_GATEWAY_API_KEY", "VERCEL_OIDC_TOKEN"]).nullable().optional()
   }).optional(),
+  sandboxCredentialEnvironment: z4.record(z4.string(), z4.string()).optional(),
   acpSessionId: z4.string().optional(),
   bridge: acpBridgeCoordsSchema.optional(),
   coldSession: acpColdSessionStateSchema.optional(),
@@ -2671,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)) {