@ai-sdk/harness-acp 0.0.0 → 1.0.1

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

@@ -0,0 +1,83 @@
+import type { InitializeResponse } from '@agentclientprotocol/sdk';
+
+export function createACPInitializationDiagnostic({
+  initialization,
+  sessionId,
+}: {
+  initialization: InitializeResponse;
+  sessionId: string;
+}): Record<string, unknown> {
+  const agentInfo = initialization.agentInfo;
+  return {
+    protocolVersion: initialization.protocolVersion,
+    sessionId,
+    agent:
+      agentInfo == null
+        ? null
+        : {
+            name: agentInfo.name,
+            version: agentInfo.version,
+            ...(agentInfo.title == null ? {} : { title: agentInfo.title }),
+          },
+    capabilities: stripMetadata({
+      value: initialization.agentCapabilities ?? {},
+    }),
+    authMethods: (initialization.authMethods ?? []).map(method => ({
+      id: method.id,
+      type: 'type' in method ? method.type : 'agent',
+    })),
+  };
+}
+
+export function createACPBridgeError({
+  stage,
+  cause,
+}: {
+  stage:
+    | 'session initialization'
+    | 'session cancellation'
+    | 'prompt update stream';
+  cause: unknown;
+}): Error {
+  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 }));
+  }
+  if (value == null || typeof value !== 'object') return value;
+  const result: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (key !== '_meta') result[key] = stripMetadata({ value: item });
+  }
+  return result;
+}

package/src/v1/bridge/acp-stream-capture.ts

@@ -0,0 +1,152 @@
+import type {
+  AnyMessage,
+  SessionUpdate,
+  Stream as ACPStream,
+} from '@agentclientprotocol/sdk';
+
+const KNOWN_SESSION_UPDATES = new Set([
+  'user_message_chunk',
+  'agent_message_chunk',
+  'agent_thought_chunk',
+  'tool_call',
+  'tool_call_update',
+  'plan',
+  'plan_update',
+  'plan_removed',
+  'available_commands_update',
+  'current_mode_update',
+  'config_option_update',
+  'session_info_update',
+  'usage_update',
+]);
+
+type CapturedSessionUpdate = {
+  readonly rawUpdate: unknown;
+  readonly forwarded: boolean;
+};
+
+export type ACPStreamCapture = {
+  takeForUpdate(options: { update: SessionUpdate }): {
+    readonly precedingRawValues: ReadonlyArray<unknown>;
+    readonly rawUpdate: unknown;
+  };
+  drainRawValues(): ReadonlyArray<unknown>;
+};
+
+export function captureACPStream({ stream }: { stream: ACPStream }): {
+  stream: ACPStream;
+  capture: ACPStreamCapture;
+} {
+  const updates: CapturedSessionUpdate[] = [];
+  const readable = stream.readable.pipeThrough(
+    new TransformStream<AnyMessage, AnyMessage>({
+      transform(message, controller) {
+        const rawUpdate = getRawSessionUpdate({ message });
+        if (!rawUpdate.isSessionUpdate) {
+          controller.enqueue(message);
+          return;
+        }
+
+        const sessionUpdate = getStringProperty({
+          value: rawUpdate.value,
+          property: 'sessionUpdate',
+        });
+        const forwarded =
+          !rawUpdate.canFilterUnknown ||
+          sessionUpdate == null ||
+          KNOWN_SESSION_UPDATES.has(sessionUpdate);
+        updates.push({ rawUpdate: rawUpdate.value, forwarded });
+        if (forwarded) controller.enqueue(message);
+      },
+    }),
+  );
+
+  return {
+    stream: { ...stream, readable },
+    capture: {
+      takeForUpdate: ({ update }) => {
+        const index = updates.findIndex(
+          candidate =>
+            candidate.forwarded &&
+            sessionUpdatesMatch({
+              rawUpdate: candidate.rawUpdate,
+              update,
+            }),
+        );
+        if (index === -1) {
+          return { precedingRawValues: [], rawUpdate: update };
+        }
+        const consumed = updates.splice(0, index + 1);
+        return {
+          precedingRawValues: consumed
+            .slice(0, -1)
+            .map(candidate => candidate.rawUpdate),
+          rawUpdate: consumed.at(-1)!.rawUpdate,
+        };
+      },
+      drainRawValues: () =>
+        updates.splice(0).map(candidate => candidate.rawUpdate),
+    },
+  };
+}
+
+function getRawSessionUpdate({ message }: { message: AnyMessage }):
+  | { readonly isSessionUpdate: false }
+  | {
+      readonly isSessionUpdate: true;
+      readonly value: unknown;
+      readonly canFilterUnknown: boolean;
+    } {
+  const record = message as unknown as Record<string, unknown>;
+  if (record.method !== 'session/update' || !isRecord(record.params)) {
+    return { isSessionUpdate: false };
+  }
+  const params = record.params;
+  return {
+    isSessionUpdate: true,
+    value: params.update,
+    canFilterUnknown:
+      typeof params.sessionId === 'string' && isRecord(params.update),
+  };
+}
+
+function sessionUpdatesMatch({
+  rawUpdate,
+  update,
+}: {
+  rawUpdate: unknown;
+  update: SessionUpdate;
+}): boolean {
+  if (!isRecord(rawUpdate)) return false;
+  if (rawUpdate.sessionUpdate !== update.sessionUpdate) return false;
+  if (
+    update.sessionUpdate === 'tool_call' ||
+    update.sessionUpdate === 'tool_call_update'
+  ) {
+    return rawUpdate.toolCallId === update.toolCallId;
+  }
+  if (
+    update.sessionUpdate === 'user_message_chunk' ||
+    update.sessionUpdate === 'agent_message_chunk' ||
+    update.sessionUpdate === 'agent_thought_chunk'
+  ) {
+    return rawUpdate.messageId === update.messageId;
+  }
+  return true;
+}
+
+function getStringProperty({
+  value,
+  property,
+}: {
+  value: unknown;
+  property: string;
+}): string | undefined {
+  if (!isRecord(value)) return undefined;
+  const propertyValue = value[property];
+  return typeof propertyValue === 'string' ? propertyValue : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -0,0 +1,95 @@
+import { z } from 'zod/v4';
+import type {
+  ACPAuthentication,
+  ACPProfileValue,
+  ACPSerializableValue,
+} from '../acp-v1-settings';
+
+export const ACP_BRIDGE_CONFIGURATION_ENV = 'AI_SDK_ACP_BRIDGE_CONFIGURATION';
+
+const serializableValueSchema: z.ZodType<ACPSerializableValue> = z.json();
+
+const profileValueSchema: z.ZodType<ACPProfileValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.object({
+      $source: z.enum([
+        'gateway-api-key',
+        'gateway-base-url',
+        'gateway-authorization',
+        'client-app',
+        'client-app-name',
+        'client-app-version',
+      ]),
+      prefix: z.string().optional(),
+      suffix: z.string().optional(),
+      ensureSuffix: z.string().optional(),
+    }),
+    z.array(profileValueSchema),
+    z.record(z.string(), profileValueSchema),
+  ]),
+);
+
+const serializableRecordSchema = z.record(z.string(), serializableValueSchema);
+const profileRecordSchema = z.record(z.string(), profileValueSchema);
+
+const authenticationSchema: z.ZodType<ACPAuthentication> = z.object({
+  methodId: z.string(),
+  meta: serializableRecordSchema.optional(),
+  clientCapabilities: serializableRecordSchema.optional(),
+});
+
+const providerAuthenticationSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('direct') }),
+  z.object({
+    type: z.literal('ai-gateway'),
+    env: profileRecordSchema,
+  }),
+]);
+
+export type ACPResolvedProviderAuthentication = z.infer<
+  typeof providerAuthenticationSchema
+>;
+
+export type ACPBridgeConfiguration = {
+  readonly authentication?: ACPAuthentication;
+  readonly providerAuthentication?: ACPResolvedProviderAuthentication;
+  readonly sessionMeta?: Readonly<Record<string, ACPSerializableValue>>;
+};
+
+const bridgeConfigurationSchema: z.ZodType<ACPBridgeConfiguration> = z.object({
+  authentication: authenticationSchema.optional(),
+  providerAuthentication: providerAuthenticationSchema.optional(),
+  sessionMeta: serializableRecordSchema.optional(),
+});
+
+export function createACPBridgeEnvironment({
+  authentication,
+  providerAuthentication,
+  sessionMeta,
+}: ACPBridgeConfiguration): Record<string, string> {
+  return {
+    [ACP_BRIDGE_CONFIGURATION_ENV]: JSON.stringify({
+      ...(authentication == null ? {} : { authentication }),
+      ...(providerAuthentication == null ? {} : { providerAuthentication }),
+      ...(sessionMeta == null ? {} : { sessionMeta }),
+    }),
+  };
+}
+
+export async function readACPBridgeEnvironment({
+  env,
+}: {
+  env: Readonly<Record<string, string | undefined>>;
+}): Promise<ACPBridgeConfiguration> {
+  const serialized = env[ACP_BRIDGE_CONFIGURATION_ENV];
+  if (serialized == null) return {};
+  try {
+    const result = bridgeConfigurationSchema.safeParse(JSON.parse(serialized));
+    if (result.success) return result.data;
+  } catch {}
+  throw new Error('ACP bridge configuration environment is invalid.');
+}

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

@@ -0,0 +1,97 @@
+import type {
+  ActiveSessionMessage,
+  ToolCallUpdate,
+} from '@agentclientprotocol/sdk';
+import type {
+  HarnessV1BridgeToolWire,
+  HarnessV1StreamPart,
+} from '@ai-sdk/harness';
+import type { ACPBuiltinToolMapping } from '../acp-v1-bridge-protocol';
+import { createACPStreamTranslator } from './stream-translator';
+import { createHostToolCorrelation } from './host-tool-correlation';
+
+export function createEmitStreamEvent({
+  emit,
+  builtinTools,
+  hostToolServerName,
+  hostTools,
+}: {
+  emit: (event: HarnessV1StreamPart) => void;
+  builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
+  hostToolServerName: string;
+  hostTools: ReadonlyArray<HarnessV1BridgeToolWire>;
+}): {
+  message: (options: {
+    message: ActiveSessionMessage;
+    rawUpdate?: unknown;
+  }) => boolean;
+  raw: (options: { rawValue: unknown }) => void;
+  close: () => void;
+  permissionToolCall: (options: { toolCall: ToolCallUpdate }) => void;
+  claimHostToolPermission: (options: { toolCall: ToolCallUpdate }) => boolean;
+  hostToolCall: (options: {
+    toolCallId: string;
+    toolName: string;
+    input: Readonly<Record<string, unknown>>;
+  }) => void;
+  hostToolResult: (options: {
+    toolCallId: string;
+    toolName: string;
+    output: unknown;
+    isError?: boolean;
+  }) => void;
+  registerHostToolCorrelationInvocation: (options: {
+    token: string;
+    serverName: string;
+    toolName: string;
+    input: Readonly<Record<string, unknown>>;
+    order: number;
+  }) => void;
+  removeHostToolCorrelationInvocation: (options: { token: string }) => void;
+} {
+  const translator = createACPStreamTranslator({ emit, builtinTools });
+  const correlation = createHostToolCorrelation({
+    emitSemanticUpdate: ({ message, rawUpdate }) => {
+      translator.update({
+        update: message.update,
+        rawUpdate,
+        preserveRaw: false,
+      });
+    },
+    emitRawUpdate: ({ rawUpdate }) => {
+      translator.raw({ rawValue: rawUpdate });
+    },
+    hostToolServerName,
+    hostTools,
+  });
+
+  return {
+    message: ({ message, rawUpdate }) => {
+      if (message.kind === 'stop') {
+        correlation.close();
+        translator.finish(message.response);
+        return true;
+      }
+      correlation.update({ message, rawUpdate });
+      return false;
+    },
+    raw: translator.raw,
+    close: () => {
+      correlation.close();
+      translator.close();
+    },
+    permissionToolCall: ({ toolCall }) => {
+      translator.permissionToolCall({
+        toolCall: {
+          sessionUpdate: 'tool_call_update',
+          ...toolCall,
+        },
+      });
+    },
+    claimHostToolPermission: correlation.claimHostToolPermission,
+    hostToolCall: translator.hostToolCall,
+    hostToolResult: translator.hostToolResult,
+    registerHostToolCorrelationInvocation: correlation.registerInvocation,
+    removeHostToolCorrelationInvocation: correlation.removeInvocation,
+  };
+}