@ai-sdk/harness-acp 1.0.22 → 1.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -27,8 +27,8 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@ai-sdk/harness": "1.0.84",
-    "@ai-sdk/provider-utils": "5.0.28"
+    "@ai-sdk/harness": "1.0.86",
+    "@ai-sdk/provider-utils": "5.0.29"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

package/src/index.ts

@@ -22,6 +22,7 @@ export type {
 export type {
   ACPCredentialBrokering,
   ACPAuthentication,
+  ACPInstallCommandSource,
   ACPInstructionMapping,
   ACPNpmLockedSource,
   ACPNpmSimpleSource,

package/src/v1/acp-bootstrap.ts

@@ -5,8 +5,9 @@ import {
   createImplementationDescriptor,
   createImplementationInstallCommand,
   createImplementationManifest,
+  getImplementationInstallScript,
   getImplementationLockfile,
-  type ACPNpmImplementation,
+  type ACPImplementation,
 } from './implementation';
 
 export function createACPBootstrap({
@@ -14,7 +15,7 @@ export function createACPBootstrap({
   implementation,
 }: {
   readonly harnessId: string;
-  readonly implementation: ACPNpmImplementation;
+  readonly implementation: ACPImplementation;
 }): {
   readonly bootstrapDir: string;
   readonly getBootstrap: () => Promise<HarnessV1Bootstrap>;
@@ -33,9 +34,15 @@ export function createACPBootstrap({
           readBridgeAsset({ name: 'index.mjs' }),
           readBridgeAsset({ name: 'host-tool-mcp.mjs' }),
         ]);
+      const implementationManifest = createImplementationManifest({
+        implementation,
+      });
       const implementationLock = getImplementationLockfile({
         implementation,
       });
+      const implementationInstallScript = getImplementationInstallScript({
+        implementation,
+      });
       cachedBootstrap = {
         harnessId,
         bootstrapDir,
@@ -53,14 +60,18 @@ export function createACPBootstrap({
             path: `${bootstrapDir}/host-tool-mcp.mjs`,
             content: hostToolMCP,
           },
-          {
-            path: `${bootstrapDir}/implementation/package.json`,
-            content: createImplementationManifest({ implementation }),
-          },
           {
             path: `${bootstrapDir}/implementation/implementation.json`,
             content: createImplementationDescriptor({ implementation }),
           },
+          ...(implementationManifest == null
+            ? []
+            : [
+                {
+                  path: `${bootstrapDir}/implementation/package.json`,
+                  content: implementationManifest,
+                },
+              ]),
           ...(implementationLock == null
             ? []
             : [
@@ -69,6 +80,14 @@ export function createACPBootstrap({
                   content: implementationLock,
                 },
               ]),
+          ...(implementationInstallScript == null
+            ? []
+            : [
+                {
+                  path: `${bootstrapDir}/implementation/install.sh`,
+                  content: implementationInstallScript,
+                },
+              ]),
         ],
         commands: [
           {

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

@@ -47,7 +47,15 @@ export type ACPNpmLockedSource = {
   readonly pnpmLockYaml: string;
 };
 
-export type ACPSource = ACPNpmSimpleSource | ACPNpmLockedSource;
+export type ACPInstallCommandSource = {
+  readonly type: 'install-command';
+  readonly command: string;
+};
+
+export type ACPSource =
+  | ACPNpmSimpleSource
+  | ACPNpmLockedSource
+  | ACPInstallCommandSource;
 
 export type ACPAuthentication = {
   readonly methodId: string;

package/src/v1/bridge/index.ts

@@ -53,7 +53,8 @@ import {
 } from './session-lifecycle';
 
 type ImplementationDescriptor = {
-  readonly executable: string;
+  readonly executablePath: string;
+  readonly privateHome: boolean;
   readonly args: ReadonlyArray<string>;
   readonly envKeys: ReadonlyArray<string>;
 };
@@ -381,10 +382,14 @@ async function ensureSession({
     instructions: start.instructions,
     instructionMapping: start.instructionMapping,
     sessionMeta: bridgeConfiguration.sessionMeta,
-    environment: createChildEnvironment({ launchEnv }),
+    environment: createChildEnvironment({
+      launchEnv,
+      implementationDir,
+      privateHome: implementation.privateHome,
+    }),
   });
   child = spawn(
-    `${implementationDir}/node_modules/.bin/${implementation.executable}`,
+    `${implementationDir}/${implementation.executablePath}`,
     [...implementation.args],
     {
       cwd: workDir,
@@ -686,8 +691,12 @@ function resolveGatewayValues({
 
 function createChildEnvironment({
   launchEnv,
+  implementationDir,
+  privateHome,
 }: {
   launchEnv: Readonly<Record<string, string>>;
+  implementationDir: string;
+  privateHome: boolean;
 }): NodeJS.ProcessEnv {
   const blocked = new Set([
     'BRIDGE_CHANNEL_TOKEN',
@@ -698,7 +707,7 @@ function createChildEnvironment({
     'AI_SDK_ACP_CLIENT_APP_VERSION',
     ACP_BRIDGE_CONFIGURATION_ENV,
   ]);
-  return {
+  const environment = {
     ...Object.fromEntries(
       Object.entries(processEnv).filter(
         ([key, value]) => !blocked.has(key) && value != null,
@@ -706,6 +715,20 @@ function createChildEnvironment({
     ),
     ...launchEnv,
   };
+  if (!privateHome) return environment;
+
+  const home = `${implementationDir}/home`;
+  const inheritedPath = environment.PATH;
+  return {
+    ...environment,
+    HOME: home,
+    PATH: [
+      `${home}/.local/bin`,
+      ...(inheritedPath == null || inheritedPath.length === 0
+        ? []
+        : [inheritedPath]),
+    ].join(':'),
+  };
 }
 
 function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
@@ -798,7 +821,8 @@ async function readImplementationDescriptor({
   }).json();
   if (
     !isRecord(value) ||
-    typeof value.executable !== 'string' ||
+    typeof value.executablePath !== 'string' ||
+    typeof value.privateHome !== 'boolean' ||
     !Array.isArray(value.args) ||
     !value.args.every(item => typeof item === 'string') ||
     !Array.isArray(value.envKeys) ||
@@ -807,7 +831,8 @@ async function readImplementationDescriptor({
     throw new Error('Invalid ACP implementation descriptor.');
   }
   return {
-    executable: value.executable,
+    executablePath: value.executablePath,
+    privateHome: value.privateHome,
     args: value.args as string[],
     envKeys: value.envKeys as string[],
   };

package/src/v1/implementation.ts

@@ -18,7 +18,7 @@ import type {
  * two shapes are required to agree, and createACPV1Implementation is the only
  * place that maps between them.
  */
-export type ACPNpmImplementation = {
+export type ACPImplementation = {
   readonly source: ACPSource;
   readonly executable: string;
   readonly args?: ReadonlyArray<string>;
@@ -31,7 +31,7 @@ export function createACPV1Implementation({
   settings,
 }: {
   settings: ACPV1Settings;
-}): ACPNpmImplementation {
+}): ACPImplementation {
   return {
     source: settings.source,
     executable: settings.executable,
@@ -50,7 +50,7 @@ const EXECUTABLE_NAME_REGEXP = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const ENVIRONMENT_VARIABLE_NAME_REGEXP = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 export function validateACPV1Implementation(
-  implementation: ACPNpmImplementation,
+  implementation: ACPImplementation,
 ): void {
   const { source } = implementation;
   if (source.type === 'npm-locked') {
@@ -60,12 +60,14 @@ export function validateACPV1Implementation(
     if (source.pnpmLockYaml.length === 0) {
       throw new Error('ACP source.pnpmLockYaml must not be empty.');
     }
-  } else {
+  } else if (source.type === 'npm-simple') {
     validateNpmSimpleSource({ source });
+  } else if (source.command.trim().length === 0) {
+    throw new Error('ACP source.command must not be empty.');
   }
   if (!EXECUTABLE_NAME_REGEXP.test(implementation.executable)) {
     throw new Error(
-      `ACP executable must be a package bin name without a path; received ${JSON.stringify(implementation.executable)}.`,
+      `ACP executable must be a bare command name without a path; received ${JSON.stringify(implementation.executable)}.`,
     );
   }
 
@@ -98,9 +100,10 @@ export function validateACPV1Implementation(
 export function createImplementationManifest({
   implementation,
 }: {
-  implementation: ACPNpmImplementation;
-}): string {
+  implementation: ACPImplementation;
+}): string | undefined {
   const { source } = implementation;
+  if (source.type === 'install-command') return undefined;
   if (source.type === 'npm-locked') {
     return source.packageJson;
   }
@@ -124,7 +127,7 @@ export function createImplementationManifest({
 export function getImplementationLockfile({
   implementation,
 }: {
-  implementation: ACPNpmImplementation;
+  implementation: ACPImplementation;
 }): string | undefined {
   const { source } = implementation;
   return source.type === 'npm-locked' ? source.pnpmLockYaml : undefined;
@@ -133,12 +136,16 @@ export function getImplementationLockfile({
 export function createImplementationDescriptor({
   implementation,
 }: {
-  implementation: ACPNpmImplementation;
+  implementation: ACPImplementation;
 }): string {
   return (
     JSON.stringify(
       {
-        executable: implementation.executable,
+        executablePath:
+          implementation.source.type === 'install-command'
+            ? `home/.local/bin/${implementation.executable}`
+            : `node_modules/.bin/${implementation.executable}`,
+        privateHome: implementation.source.type === 'install-command',
         args: implementation.args ?? [],
         envKeys: getImplementationEnvironmentKeys({ implementation }),
       },
@@ -158,7 +165,7 @@ export function createImplementationIdentity({
 }: {
   harnessId: string;
   acpVersion: 'v1';
-  implementation: ACPNpmImplementation;
+  implementation: ACPImplementation;
   clientApp: ACPClientApp;
   providerAuthentication: ACPProviderAuthenticationCompatibility | undefined;
   permissionModeMapping?: ACPPermissionModeMapping;
@@ -171,13 +178,18 @@ export function createImplementationIdentity({
           packageJson: source.packageJson,
           pnpmLockYaml: source.pnpmLockYaml,
         }
-      : {
-          type: source.type,
-          packageName: source.packageName,
-          ...(source.packageVersion == null
-            ? {}
-            : { packageVersion: source.packageVersion }),
-        };
+      : source.type === 'npm-simple'
+        ? {
+            type: source.type,
+            packageName: source.packageName,
+            ...(source.packageVersion == null
+              ? {}
+              : { packageVersion: source.packageVersion }),
+          }
+        : {
+            type: source.type,
+            command: source.command,
+          };
   const forwardedEnvironment = [
     ...new Set(implementation.forwardEnv ?? []),
   ].sort();
@@ -216,8 +228,11 @@ export function createImplementationInstallCommand({
 }: {
   implementationDir: string;
   storeDir: string;
-  implementation: ACPNpmImplementation;
+  implementation: ACPImplementation;
 }): string {
+  if (implementation.source.type === 'install-command') {
+    return 'bash implementation/install.sh';
+  }
   return (
     `pnpm --dir ${implementationDir} install` +
     (implementation.source.type === 'npm-locked' ? ' --frozen-lockfile' : '') +
@@ -225,11 +240,32 @@ export function createImplementationInstallCommand({
   );
 }
 
+export function getImplementationInstallScript({
+  implementation,
+}: {
+  implementation: ACPImplementation;
+}): string | undefined {
+  if (implementation.source.type !== 'install-command') return undefined;
+  return `#!/usr/bin/env bash
+set -euo pipefail
+
+ACP_IMPLEMENTATION_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+ACP_INSTALL_HOME="$ACP_IMPLEMENTATION_DIR/home"
+export HOME="$ACP_INSTALL_HOME"
+export PATH="$ACP_INSTALL_HOME/.local/bin:$PATH"
+
+mkdir -p "$ACP_INSTALL_HOME/.local/bin"
+cd "$ACP_IMPLEMENTATION_DIR"
+
+${implementation.source.command}
+`;
+}
+
 export function resolveImplementationEnvironment({
   implementation,
   env,
 }: {
-  implementation: ACPNpmImplementation;
+  implementation: ACPImplementation;
   env: Readonly<Record<string, string | undefined>>;
 }): Record<string, string> {
   const forwardedEnvironment: Record<string, string> = {};
@@ -302,7 +338,7 @@ function validateForwardEnvironment({
 function getImplementationEnvironmentKeys({
   implementation,
 }: {
-  implementation: ACPNpmImplementation;
+  implementation: ACPImplementation;
 }): string[] {
   return [
     ...new Set([

package/src/v1/index.ts

@@ -2,6 +2,7 @@ export { createACPV1 } from './acp-v1-harness';
 export type {
   ACPCredentialBrokering,
   ACPAuthentication,
+  ACPInstallCommandSource,
   ACPInstructionMapping,
   ACPNpmLockedSource,
   ACPNpmSimpleSource,