@ai-sdk/harness-acp 0.0.0 → 1.0.0

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/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,
+  };
+}