@ai-sdk/harness-acp 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -27,8 +27,8 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@ai-sdk/harness": "1.0.63",
-    "@ai-sdk/provider-utils": "5.0.24"
+    "@ai-sdk/harness": "1.0.64",
+    "@ai-sdk/provider-utils": "5.0.25"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

package/src/acp-harness.ts

@@ -1,19 +1,11 @@
 import type { HarnessV1 } from '@ai-sdk/harness';
 import type { ToolSet } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
-import {
-  createACPAuthenticationProfileIdentity,
-  resolveACPProviderAuthenticationCompatibility,
-  type ACPAuthenticationProfileIdentity,
-  type ACPClientApp,
-} from './acp-auth';
+import type { ACPClientApp } from './acp-auth';
 import { createACPV1, type ACPV1Settings } from './v1';
-import { createImplementationIdentity } from './v1/implementation';
 import {
   acpColdSessionStateSchema,
   acpTurnStartConfigSchema,
-  type ACPColdSessionState,
-  type ACPTurnStartConfig,
 } from './v1/acp-v1-bridge-protocol';
 import { VERSION } from './version';
 
@@ -30,7 +22,11 @@ export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly version?: ACPV1Settings['version'];
   readonly harnessId: ACPV1Settings['harnessId'];
   readonly auth?: ACPV1Settings['auth'];
-  readonly implementation: ACPV1Settings['implementation'];
+  readonly source: ACPV1Settings['source'];
+  readonly executable: ACPV1Settings['executable'];
+  readonly args?: ACPV1Settings['args'];
+  readonly forwardEnv?: ACPV1Settings['forwardEnv'];
+  readonly env?: ACPV1Settings['env'];
   readonly authentication?: ACPV1Settings['authentication'];
   readonly providerAuthentication?: ACPV1Settings['providerAuthentication'];
   readonly modelId?: ACPV1Settings['modelId'];
@@ -86,8 +82,6 @@ const acpResumeStateSchema = z.object({
   skillsFingerprint: z.string().optional(),
 });
 
-type ACPBridgeCoords = z.infer<typeof acpBridgeCoordsSchema>;
-
 export function createACP<TBuiltinTools extends ToolSet = {}>(
   settings: ACPHarnessSettings<TBuiltinTools>,
 ): HarnessV1<TBuiltinTools> {
@@ -95,50 +89,6 @@ export function createACP<TBuiltinTools extends ToolSet = {}>(
   switch (version) {
     case 'v1': {
       const clientApp = settings.clientApp ?? ACP_CLIENT_APP;
-      const providerAuthenticationCompatibility =
-        resolveACPProviderAuthenticationCompatibility({
-          auth: settings.auth,
-          providerAuthentication: settings.providerAuthentication,
-          env: process.env,
-        });
-      const implementationIdentity = createImplementationIdentity({
-        harnessId: settings.harnessId,
-        acpVersion: version,
-        implementation: settings.implementation,
-        clientApp,
-        providerAuthentication: providerAuthenticationCompatibility,
-        permissionModeMapping: settings.permissionModeMapping,
-      });
-      const authenticationProfile = createACPAuthenticationProfileIdentity({
-        authentication: settings.authentication,
-        providerAuthenticationCompatibility,
-      });
-      const lifecycleStateSchema: z.ZodType<{
-        readonly implementationIdentity: string;
-        readonly authenticationProfile?: ACPAuthenticationProfileIdentity;
-        readonly acpSessionId?: string;
-        readonly bridge?: ACPBridgeCoords;
-        readonly coldSession?: ACPColdSessionState;
-        readonly turnStartConfig?: ACPTurnStartConfig;
-        readonly recovery?: {
-          readonly mode: 'disk-replay' | 'lossy-rerun';
-          readonly reason: string;
-        };
-        readonly restoration?: {
-          readonly method: 'resume' | 'load';
-        };
-        readonly initialGuidanceApplied?: boolean;
-        readonly skillsMaterialized?: boolean;
-        readonly skillsFingerprint?: string;
-      }> = acpResumeStateSchema.extend({
-        implementationIdentity: z.literal(implementationIdentity),
-        authenticationProfile: acpResumeStateSchema.shape.authenticationProfile
-          .unwrap()
-          .extend({
-            digest: z.literal(authenticationProfile.digest),
-          })
-          .optional(),
-      });
       return createACPV1({
         settings,
         builtinTools:
@@ -146,10 +96,7 @@ export function createACP<TBuiltinTools extends ToolSet = {}>(
         port: settings.port,
         startupTimeoutMs: settings.startupTimeoutMs,
         clientApp,
-        implementationIdentity,
-        authenticationProfile,
-        providerAuthenticationCompatibility,
-        lifecycleStateSchema,
+        lifecycleStateSchema: acpResumeStateSchema,
       });
     }
     default:

package/src/index.ts

@@ -3,8 +3,8 @@ export type { ACPAuthOptions, ACPClientApp } from './acp-auth';
 export type { ACPHarnessSettings } from './acp-harness';
 export type {
   ACPAuthentication,
-  ACPLockedNpmImplementation,
-  ACPNpmImplementation,
+  ACPNpmLockedSource,
+  ACPNpmSimpleSource,
   ACPPermissionModeMapping,
   ACPPermissionModeTarget,
   ACPProfileValue,
@@ -12,7 +12,7 @@ export type {
   ACPProviderAuthenticationMode,
   ACPSerializablePrimitive,
   ACPSerializableValue,
-  ACPSimpleNpmImplementation,
+  ACPSource,
   ACPV1Settings,
   ACPValueSource,
 } from './v1';

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

@@ -34,13 +34,16 @@ import {
 } from '@ai-sdk/provider-utils';
 import { WebSocket } from 'ws';
 import {
+  createACPAuthenticationProfileIdentity,
   resolveACPProviderAuthentication,
+  resolveACPProviderAuthenticationCompatibility,
   type ACPAuthenticationProfileIdentity,
   type ACPClientApp,
-  type ACPProviderAuthenticationCompatibility,
 } from '../acp-auth';
 import {
+  createACPV1Implementation,
   createImplementationDescriptor,
+  createImplementationIdentity,
   createImplementationInstallCommand,
   createImplementationManifest,
   getImplementationLockfile,
@@ -112,9 +115,6 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
   port: portOverride,
   startupTimeoutMs,
   clientApp,
-  implementationIdentity,
-  authenticationProfile,
-  providerAuthenticationCompatibility,
   lifecycleStateSchema,
 }: {
   settings: ACPV1Settings;
@@ -122,11 +122,6 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
   port?: number;
   startupTimeoutMs?: number;
   clientApp: ACPClientApp;
-  implementationIdentity: string;
-  authenticationProfile: ACPAuthenticationProfileIdentity;
-  providerAuthenticationCompatibility:
-    | ACPProviderAuthenticationCompatibility
-    | undefined;
   lifecycleStateSchema: NonNullable<
     HarnessV1<TBuiltinTools>['lifecycleStateSchema']
   >;
@@ -136,7 +131,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       `ACP harnessId must be a stable kebab-case identifier; received ${JSON.stringify(settings.harnessId)}.`,
     );
   }
-  validateACPV1Implementation(settings.implementation);
+  const implementation = createACPV1Implementation({ settings });
+  validateACPV1Implementation(implementation);
 
   const BOOTSTRAP_DIR = `.harness-bootstrap/${settings.harnessId}`;
 
@@ -164,7 +160,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           readBridgeAsset({ name: 'host-tool-mcp.mjs' }),
         ]);
       const implementationLock = getImplementationLockfile({
-        implementation: settings.implementation,
+        implementation,
       });
       cachedBootstrap = {
         harnessId: settings.harnessId,
@@ -186,14 +182,13 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           {
             path: `${BOOTSTRAP_DIR}/implementation/package.json`,
             content: createImplementationManifest({
-              implementation: settings.implementation,
+              implementation,
             }),
           },
           {
             path: `${BOOTSTRAP_DIR}/implementation/implementation.json`,
             content: createImplementationDescriptor({
-              implementation: settings.implementation,
-              implementationIdentity,
+              implementation,
             }),
           },
           ...(implementationLock == null
@@ -213,7 +208,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
             command: createImplementationInstallCommand({
               implementationDir: 'implementation',
               storeDir: '../.pnpm-store',
-              implementation: settings.implementation,
+              implementation,
             }),
           },
         ],
@@ -229,6 +224,25 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         });
       }
       const permissionMode = startOptions.permissionMode ?? 'allow-all';
+      const env = { ...process.env };
+      const providerAuthenticationCompatibility =
+        resolveACPProviderAuthenticationCompatibility({
+          auth: settings.auth,
+          providerAuthentication: settings.providerAuthentication,
+          env,
+        });
+      const implementationIdentity = createImplementationIdentity({
+        harnessId: settings.harnessId,
+        acpVersion: 'v1',
+        implementation,
+        clientApp,
+        providerAuthentication: providerAuthenticationCompatibility,
+        permissionModeMapping: settings.permissionModeMapping,
+      });
+      const authenticationProfile = createACPAuthenticationProfileIdentity({
+        authentication: settings.authentication,
+        providerAuthenticationCompatibility,
+      });
 
       const resolvedProviderAuthentication = resolveACPProviderAuthentication({
         auth: {
@@ -236,7 +250,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           providerAuthentication: settings.providerAuthentication,
           clientApp,
         },
-        env: process.env,
+        env,
         compatibility: providerAuthenticationCompatibility,
       });
       const sandboxSession = startOptions.sandboxSession;
@@ -472,8 +486,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           ` --bridge-type ${shellQuote(settings.harnessId)}`,
         env: {
           ...resolveImplementationEnvironment({
-            implementation: settings.implementation,
-            env: process.env,
+            implementation,
+            env,
           }),
           ...createACPBridgeEnvironment({
             authentication: settings.authentication,

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

@@ -26,33 +26,24 @@ export type ACPProfileValue =
   | ReadonlyArray<ACPProfileValue>
   | { readonly [key: string]: ACPProfileValue };
 
-type ACPNpmLaunchSettings = {
-  readonly type: 'npm';
-  readonly executable: string;
-  readonly args?: ReadonlyArray<string>;
-  readonly forwardEnv?: ReadonlyArray<string>;
+export type ACPNpmSimpleSource = {
+  readonly type: 'npm-simple';
+  readonly packageName: string;
   /**
-   * Runtime environment values that are safe to persist in bootstrap and
-   * lifecycle compatibility identity.
+   * Exact version to install. When omitted, the package's `latest` dist-tag is
+   * installed and no version takes part in the implementation identity, so a
+   * new upstream release does not invalidate existing lifecycle state.
    */
-  readonly env?: Readonly<Record<string, string>>;
-};
-
-export type ACPSimpleNpmImplementation = ACPNpmLaunchSettings & {
-  readonly mode: 'simple';
-  readonly packageName: string;
-  readonly version: string;
+  readonly packageVersion?: string;
 };
 
-export type ACPLockedNpmImplementation = ACPNpmLaunchSettings & {
-  readonly mode: 'locked';
+export type ACPNpmLockedSource = {
+  readonly type: 'npm-locked';
   readonly packageJson: string;
   readonly pnpmLockYaml: string;
 };
 
-export type ACPNpmImplementation =
-  | ACPSimpleNpmImplementation
-  | ACPLockedNpmImplementation;
+export type ACPSource = ACPNpmSimpleSource | ACPNpmLockedSource;
 
 export type ACPAuthentication = {
   readonly methodId: string;
@@ -87,7 +78,15 @@ export type ACPV1Settings = {
   readonly version?: 'v1';
   readonly harnessId: string;
   readonly auth?: ACPProviderAuthenticationMode;
-  readonly implementation: ACPNpmImplementation;
+  readonly source: ACPSource;
+  readonly executable: string;
+  readonly args?: ReadonlyArray<string>;
+  readonly forwardEnv?: ReadonlyArray<string>;
+  /**
+   * Runtime environment values that are safe to persist in bootstrap and
+   * lifecycle compatibility identity.
+   */
+  readonly env?: Readonly<Record<string, string>>;
   readonly authentication?: ACPAuthentication;
   readonly providerAuthentication?: ACPProviderAuthentication;
   readonly modelId?: string;

package/src/v1/bridge/acp-diagnostics.ts

@@ -39,11 +39,37 @@ export function createACPBridgeError({
     | 'prompt update stream';
   cause: unknown;
 }): Error {
-  const error = new Error(`ACP ${stage} failed.`);
+  const causeMessage = getErrorMessage({ error: cause });
+  const error = new Error(
+    causeMessage == null
+      ? `ACP ${stage} failed.`
+      : `ACP ${stage} failed: ${causeMessage}`,
+  );
   (error as Error & { cause?: unknown }).cause = cause;
   return error;
 }
 
+function getErrorMessage({ error }: { error: unknown }): string | undefined {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  if (
+    error != null &&
+    typeof error === 'object' &&
+    'message' in error &&
+    typeof error.message === 'string'
+  ) {
+    return error.message;
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  return undefined;
+}
+
 function stripMetadata({ value }: { value: unknown }): unknown {
   if (Array.isArray(value)) {
     return value.map(item => stripMetadata({ value: item }));

package/src/v1/bridge/agent-stderr-monitor.ts

@@ -0,0 +1,52 @@
+import type { Readable } from 'node:stream';
+import { stripVTControlCharacters } from 'node:util';
+
+export function monitorACPAgentStderr({
+  stderr,
+  onStderrLine,
+}: {
+  stderr: Readable;
+  onStderrLine: (line: string) => void;
+}): Promise<never> {
+  let rejectFailure!: (error: unknown) => void;
+  const failure = new Promise<never>((_, reject) => {
+    rejectFailure = reject;
+  });
+  void failure.catch(() => {});
+
+  void (async () => {
+    stderr.setEncoding('utf8');
+    let pending = '';
+    for await (const chunk of stderr) {
+      pending += chunk;
+      const lines = pending.split('\n');
+      pending = lines.pop() ?? '';
+      for (const line of lines) handleStderrLine({ line });
+    }
+    if (pending.length > 0) handleStderrLine({ line: pending });
+  })().catch(error => rejectFailure(error));
+
+  return failure;
+
+  function handleStderrLine({ line }: { line: string }): void {
+    if (line.length === 0) return;
+    onStderrLine(line);
+    const normalizedLine = stripVTControlCharacters(line);
+
+    /*
+     * An ACP agent can log a response-stream decoding failure without rejecting
+     * its pending JSON-RPC prompt. Once the provider stream cannot be decoded,
+     * no valid prompt completion can reach the ACP client, so the bridge must
+     * fail the turn instead of waiting indefinitely.
+     */
+    if (
+      normalizedLine
+        .toLowerCase()
+        .includes('failed to deserialize responsestreamevent from stream')
+    ) {
+      rejectFailure(
+        new Error('ACP agent failed to deserialize a streamed response.'),
+      );
+    }
+  }
+}

package/src/v1/bridge/index.ts

@@ -30,6 +30,7 @@ import {
   createACPBridgeError,
   createACPInitializationDiagnostic,
 } from './acp-diagnostics';
+import { monitorACPAgentStderr } from './agent-stderr-monitor';
 import { createEmitStreamEvent } from './create-emit-stream-event';
 import {
   startHostToolRelay,
@@ -79,6 +80,7 @@ const implementation = await readImplementationDescriptor({
 const bridgeConfiguration = await readACPBridgeEnvironment({ env: processEnv });
 
 let child: ChildProcessWithoutNullStreams | undefined;
+let agentResponseStreamFailure: Promise<never> | undefined;
 let connection: acp.ClientConnection | undefined;
 let session: ACPActiveSession | undefined;
 let recoveredSessionUpdates:
@@ -139,6 +141,12 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
   if (activeSession == null) {
     throw new Error('ACP session initialization did not produce a session.');
   }
+  const activeAgentResponseStreamFailure = agentResponseStreamFailure;
+  if (activeAgentResponseStreamFailure == null) {
+    throw new Error(
+      'ACP session initialization did not start stderr monitoring.',
+    );
+  }
   if (start.recoveryMode?.type === 'lossy-rerun') {
     const marker = {
       type: 'acp-recovery',
@@ -260,6 +268,7 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
         message = await Promise.race([
           activeSession.nextUpdate(),
           cancellationFailure,
+          activeAgentResponseStreamFailure,
         ]);
       } catch (error) {
         for (const rawValue of streamCapture?.drainRawValues() ?? []) {
@@ -361,7 +370,16 @@ async function ensureSession({
       stdio: ['pipe', 'pipe', 'pipe'],
     },
   );
-  forwardAgentStderr({ child, turn });
+  agentResponseStreamFailure = monitorACPAgentStderr({
+    stderr: child.stderr,
+    onStderrLine: line => {
+      turn.bridgeLog({
+        level: 'warn',
+        subsystem: 'acp.agent.stderr',
+        message: line,
+      });
+    },
+  });
 
   const input = Writable.toWeb(child.stdin);
   const output = Readable.toWeb(child.stdout) as ReadableStream<
@@ -631,39 +649,6 @@ function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
   return value != null && typeof value === 'object' && !Array.isArray(value);
 }
 
-function forwardAgentStderr({
-  child,
-  turn,
-}: {
-  child: ChildProcessWithoutNullStreams;
-  turn: BridgeTurn;
-}): void {
-  void (async () => {
-    child.stderr.setEncoding('utf8');
-    let pending = '';
-    for await (const chunk of child.stderr) {
-      pending += chunk;
-      const lines = pending.split('\n');
-      pending = lines.pop() ?? '';
-      for (const line of lines) {
-        if (line.length === 0) continue;
-        turn.bridgeLog({
-          level: 'warn',
-          subsystem: 'acp.agent.stderr',
-          message: line,
-        });
-      }
-    }
-    if (pending.length > 0) {
-      turn.bridgeLog({
-        level: 'warn',
-        subsystem: 'acp.agent.stderr',
-        message: pending,
-      });
-    }
-  })();
-}
-
 async function readImplementationDescriptor({
   path,
 }: {