@ai-sdk/harness-acp 1.0.0 → 1.0.2

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

@@ -1,4 +1,5 @@
 import type { HarnessV1PermissionMode } from '@ai-sdk/harness';
+import type { ACPToolCall } from '../acp-tool-call';
 
 export type ACPSerializablePrimitive = string | number | boolean | null;
 
@@ -26,33 +27,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;
@@ -86,8 +78,18 @@ export type ACPPermissionModeMapping = Readonly<
 export type ACPV1Settings = {
   readonly version?: 'v1';
   readonly harnessId: string;
+  readonly mcpServers?: Record<string, unknown>;
+  readonly isMcpToolCall?: (toolCall: ACPToolCall) => boolean;
   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;
@@ -95,4 +97,9 @@ export type ACPV1Settings = {
   readonly session?: {
     readonly meta?: Readonly<Record<string, ACPSerializableValue>>;
   };
+  /**
+   * Creates the authentication token used by the sandbox bridge. Defaults to
+   * a random 32-byte hexadecimal token.
+   */
+  readonly mintBridgeToken?: (sandboxId: string) => string;
 };

package/src/v1/acp-v1-turn-start-config.ts

@@ -20,6 +20,7 @@ export function createACPTurnStartConfig({
   builtinTools,
   permissionMode,
   permissionModeMapping,
+  mcpServers,
   debug,
   authenticationProfile,
   sessionMeta,
@@ -29,6 +30,7 @@ export function createACPTurnStartConfig({
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   permissionMode: NonNullable<StartMessage['permissionMode']>;
   permissionModeMapping: ACPPermissionModeMapping | undefined;
+  mcpServers: Record<string, unknown> | undefined;
   debug: HarnessV1DebugConfig | undefined;
   authenticationProfile: ACPAuthenticationProfileIdentity;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
@@ -42,6 +44,7 @@ export function createACPTurnStartConfig({
           sessionMeta: sessionMeta ?? null,
           builtinTools,
           permissionModeMapping: permissionModeMapping ?? null,
+          mcpServers: mcpServers ?? null,
         }),
       )
       .digest('hex'),

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/create-emit-stream-event.ts

@@ -6,17 +6,20 @@ import type {
   HarnessV1BridgeToolWire,
   HarnessV1StreamPart,
 } from '@ai-sdk/harness';
+import type { ACPToolCall } from '../../acp-tool-call';
 import type { ACPBuiltinToolMapping } from '../acp-v1-bridge-protocol';
 import { createACPStreamTranslator } from './stream-translator';
 import { createHostToolCorrelation } from './host-tool-correlation';
 
 export function createEmitStreamEvent({
   emit,
+  emitToolCallCandidate,
   builtinTools,
   hostToolServerName,
   hostTools,
 }: {
   emit: (event: HarnessV1StreamPart) => void;
+  emitToolCallCandidate: (options: { toolCall: ACPToolCall }) => void;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   hostToolServerName: string;
   hostTools: ReadonlyArray<HarnessV1BridgeToolWire>;
@@ -49,7 +52,11 @@ export function createEmitStreamEvent({
   }) => void;
   removeHostToolCorrelationInvocation: (options: { token: string }) => void;
 } {
-  const translator = createACPStreamTranslator({ emit, builtinTools });
+  const translator = createACPStreamTranslator({
+    emit,
+    emitToolCallCandidate,
+    builtinTools,
+  });
   const correlation = createHostToolCorrelation({
     emitSemanticUpdate: ({ message, rawUpdate }) => {
       translator.update({

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',
@@ -222,6 +230,12 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
   turn.emit({ type: 'stream-start' });
   const emitStreamEvent = createEmitStreamEvent({
     emit: event => turn.emit(event as BridgeEvent),
+    emitToolCallCandidate: ({ toolCall }) => {
+      turn.emit({
+        type: 'acp-tool-call-candidate',
+        toolCall,
+      });
+    },
     builtinTools: start.builtinTools,
     hostToolServerName: HOST_TOOL_MCP_SERVER_NAME,
     hostTools: start.tools ?? [],
@@ -260,6 +274,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() ?? []) {
@@ -313,6 +328,7 @@ async function ensureSession({
     sessionMeta: bridgeConfiguration.sessionMeta,
     permissionMode: start.permissionMode,
     permissionModeMapping: start.permissionModeMapping,
+    mcpServers: start.mcpServers,
   });
   if (session != null) {
     if (catalogRefreshError != null) throw catalogRefreshError;
@@ -361,7 +377,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<
@@ -419,6 +444,10 @@ async function ensureSession({
       authentication,
     });
   }
+  const externalMcpServers = createExternalMcpServers({
+    mcpServers: start.mcpServers,
+    initialization,
+  });
   const tools = start.tools ?? [];
   const catalogPath = `${bridgeStateDir}/host-tools.json`;
   await writeFile(catalogPath, JSON.stringify(tools), { mode: 0o600 });
@@ -428,6 +457,7 @@ async function ensureSession({
   });
 
   const mcpServers: acp.McpServer[] = [
+    ...externalMcpServers,
     {
       name: HOST_TOOL_MCP_SERVER_NAME,
       command: process.execPath,
@@ -539,6 +569,41 @@ async function ensureSession({
   sessionConfigurationFingerprint = fingerprint;
 }
 
+function createExternalMcpServers({
+  mcpServers,
+  initialization,
+}: {
+  mcpServers: Record<string, unknown> | undefined;
+  initialization: acp.InitializeResponse;
+}): acp.McpServer[] {
+  if (mcpServers == null) return [];
+  return Object.entries(mcpServers).map(([name, value]) => {
+    if (!isRecord(value)) {
+      throw new Error(
+        `ACP MCP server ${JSON.stringify(name)} must be configured with an object value.`,
+      );
+    }
+    if (value.type === 'acp') {
+      throw new HarnessBridgeCapabilityUnsupportedError({
+        harnessId: bridgeType,
+        message:
+          'ACP-transport MCP servers require client-side mcp/connect handling, which this harness does not provide.',
+      });
+    }
+    const mcpCapabilities = initialization.agentCapabilities?.mcpCapabilities;
+    if (
+      (value.type === 'http' && mcpCapabilities?.http !== true) ||
+      (value.type === 'sse' && mcpCapabilities?.sse !== true)
+    ) {
+      throw new HarnessBridgeCapabilityUnsupportedError({
+        harnessId: bridgeType,
+        message: `The ACP agent does not advertise support for ${value.type.toUpperCase()} MCP servers.`,
+      });
+    }
+    return { ...value, name } as acp.McpServer;
+  });
+}
+
 function unknownUsage() {
   return {
     inputTokens: {
@@ -631,39 +696,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,
 }: {

package/src/v1/bridge/stream-translator.ts

@@ -1,5 +1,10 @@
 import type { HarnessV1StreamPart } from '@ai-sdk/harness';
 import type { PromptResponse, SessionUpdate } from '@agentclientprotocol/sdk';
+import type {
+  ACPToolCall,
+  ACPToolCallStatus,
+  ACPToolKind,
+} from '../../acp-tool-call';
 import type { ACPBuiltinToolMapping } from '../acp-v1-bridge-protocol';
 
 type HarnessUsage = Extract<
@@ -20,7 +25,6 @@ type ToolState = {
   emittedResult: boolean;
   toolName?: string;
   nativeName?: string;
-  dynamic?: boolean;
 };
 
 export type ACPSessionUpdate = SessionUpdate;
@@ -28,9 +32,11 @@ export type ACPPromptResponse = PromptResponse;
 
 export function createACPStreamTranslator({
   emit,
+  emitToolCallCandidate,
   builtinTools = [],
 }: {
   emit: (event: HarnessV1StreamPart) => void;
+  emitToolCallCandidate?: (options: { toolCall: ACPToolCall }) => void;
   builtinTools?: ReadonlyArray<ACPBuiltinToolMapping>;
 }): {
   update: (
@@ -228,13 +234,12 @@ export function createACPStreamTranslator({
           builtin.nativeName != null && builtin.toolName !== builtin.nativeName
             ? builtin.nativeName
             : undefined;
-        state.dynamic = false;
       } else {
         state.toolName = createDynamicToolName({
           programmaticName,
           toolCallId: state.toolCallId,
         });
-        state.dynamic = true;
+        emitToolCallCandidate?.({ toolCall: createACPToolCall({ state }) });
       }
       emit({
         type: 'tool-call',
@@ -242,7 +247,6 @@ export function createACPStreamTranslator({
         toolName: state.toolName,
         input: stringifyToolInput({ input: state.values.rawInput }),
         providerExecuted: true,
-        ...(state.dynamic ? { dynamic: true } : {}),
         ...(state.nativeName == null ? {} : { nativeName: state.nativeName }),
       });
       state.emittedCall = true;
@@ -263,7 +267,6 @@ export function createACPStreamTranslator({
         toolName: state.toolName!,
         result: createToolResult({ state }),
         ...(state.values.status === 'failed' ? { isError: true } : {}),
-        ...(state.dynamic ? { dynamic: true } : {}),
       });
       state.emittedResult = true;
       pendingToolCallIds.delete(state.toolCallId);
@@ -697,6 +700,60 @@ function mergeToolUpdate({
   if (programmaticName != null) state.values.name = programmaticName;
 }
 
+function createACPToolCall({ state }: { state: ToolState }): ACPToolCall {
+  const title = getStringProperty({
+    value: state.values,
+    property: 'title',
+  });
+  const kind = state.values.kind;
+  const status = state.values.status;
+  return {
+    toolCallId: state.toolCallId,
+    title: title ?? state.toolName ?? `Tool ${state.toolCallId}`,
+    ...(isACPToolKind(kind) ? { kind } : {}),
+    ...(isACPToolCallStatus(status) ? { status } : {}),
+    ...(Array.isArray(state.values.content)
+      ? { content: state.values.content as ACPToolCall['content'] }
+      : {}),
+    ...(Array.isArray(state.values.locations)
+      ? { locations: state.values.locations as ACPToolCall['locations'] }
+      : {}),
+    ...(Object.prototype.hasOwnProperty.call(state.values, 'rawInput')
+      ? { rawInput: state.values.rawInput }
+      : {}),
+    ...(Object.prototype.hasOwnProperty.call(state.values, 'rawOutput')
+      ? { rawOutput: state.values.rawOutput }
+      : {}),
+    ...(state.values._meta === null || isRecord(state.values._meta)
+      ? { _meta: state.values._meta }
+      : {}),
+  };
+}
+
+function isACPToolKind(value: unknown): value is ACPToolKind {
+  return (
+    value === 'read' ||
+    value === 'edit' ||
+    value === 'delete' ||
+    value === 'move' ||
+    value === 'search' ||
+    value === 'execute' ||
+    value === 'think' ||
+    value === 'fetch' ||
+    value === 'switch_mode' ||
+    value === 'other'
+  );
+}
+
+function isACPToolCallStatus(value: unknown): value is ACPToolCallStatus {
+  return (
+    value === 'pending' ||
+    value === 'in_progress' ||
+    value === 'completed' ||
+    value === 'failed'
+  );
+}
+
 function emitFileChanges({
   state,
   emit,