@ai-sdk/harness-acp 0.0.0 → 1.0.0

package/src/v1/bridge/profile-values.ts

@@ -0,0 +1,97 @@
+import type { ACPProfileValue, ACPSerializableValue } from '../acp-v1-settings';
+
+export type ACPGatewayValues = {
+  readonly apiKey: string;
+  readonly baseUrl: string;
+  readonly clientAppName: string;
+  readonly clientAppVersion: string;
+};
+
+export function resolveACPProfileValue({
+  value,
+  gateway,
+}: {
+  value: ACPProfileValue;
+  gateway: ACPGatewayValues;
+}): ACPSerializableValue {
+  if (Array.isArray(value)) {
+    return value.map(item => resolveACPProfileValue({ value: item, gateway }));
+  }
+  if (value !== null && typeof value === 'object') {
+    if (isValueSource(value)) {
+      const sourceValue = resolveSource({ source: value.$source, gateway });
+      const resolved = `${value.prefix ?? ''}${sourceValue}`;
+      return value.ensureSuffix == null
+        ? `${resolved}${value.suffix ?? ''}`
+        : ensureSuffix({
+            value: resolved,
+            suffix: value.ensureSuffix,
+          });
+    }
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        resolveACPProfileValue({ value: item, gateway }),
+      ]),
+    );
+  }
+  return value;
+}
+
+function isValueSource(value: object): value is {
+  readonly $source:
+    | 'gateway-api-key'
+    | 'gateway-base-url'
+    | 'gateway-authorization'
+    | 'client-app'
+    | 'client-app-name'
+    | 'client-app-version';
+  readonly prefix?: string;
+  readonly suffix?: string;
+  readonly ensureSuffix?: string;
+} {
+  return (
+    '$source' in value &&
+    typeof (value as { $source?: unknown }).$source === 'string'
+  );
+}
+
+function ensureSuffix({
+  value,
+  suffix,
+}: {
+  value: string;
+  suffix: string;
+}): string {
+  const normalized = value.replace(/\/+$/, '');
+  return normalized.endsWith(suffix) ? normalized : `${normalized}${suffix}`;
+}
+
+function resolveSource({
+  source,
+  gateway,
+}: {
+  source:
+    | 'gateway-api-key'
+    | 'gateway-base-url'
+    | 'gateway-authorization'
+    | 'client-app'
+    | 'client-app-name'
+    | 'client-app-version';
+  gateway: ACPGatewayValues;
+}): string {
+  switch (source) {
+    case 'gateway-api-key':
+      return gateway.apiKey;
+    case 'gateway-base-url':
+      return gateway.baseUrl;
+    case 'gateway-authorization':
+      return `Bearer ${gateway.apiKey}`;
+    case 'client-app':
+      return `${gateway.clientAppName}/${gateway.clientAppVersion}`;
+    case 'client-app-name':
+      return gateway.clientAppName;
+    case 'client-app-version':
+      return gateway.clientAppVersion;
+  }
+}

package/src/v1/bridge/protocol-configuration.ts

@@ -0,0 +1,146 @@
+import type { ACPResolvedProviderAuthentication } from './acp-v1-bridge-environment';
+import type { ACPClientApp } from '../../acp-auth';
+import type { ACPAuthentication } from '../acp-v1-settings';
+import {
+  resolveACPProfileValue,
+  type ACPGatewayValues,
+} from './profile-values';
+
+export type ACPInitializeResult = {
+  readonly protocolVersion: number;
+  readonly authMethods?: ReadonlyArray<{ readonly id: string }> | null;
+  readonly agentCapabilities?: Readonly<Record<string, unknown>> | null;
+};
+
+export function createACPInitializeRequest({
+  protocolVersion,
+  clientApp,
+  authentication,
+  supportsBooleanSessionConfigOptions = false,
+}: {
+  protocolVersion: number;
+  clientApp: ACPClientApp;
+  authentication: ACPAuthentication | undefined;
+  supportsBooleanSessionConfigOptions?: boolean;
+}): {
+  readonly protocolVersion: number;
+  readonly clientInfo: {
+    readonly name: string;
+    readonly version: string;
+  };
+  readonly clientCapabilities: Readonly<Record<string, unknown>>;
+} {
+  let clientCapabilities: Readonly<Record<string, unknown>> =
+    authentication?.clientCapabilities ?? {};
+  if (supportsBooleanSessionConfigOptions) {
+    clientCapabilities = mergeRecords({
+      left: clientCapabilities,
+      right: {
+        session: {
+          configOptions: {
+            boolean: {},
+          },
+        },
+      },
+    });
+  }
+  return {
+    protocolVersion,
+    clientInfo: clientApp,
+    clientCapabilities,
+  };
+}
+
+export function resolveACPLaunchEnvironment({
+  providerAuthentication,
+  gateway,
+}: {
+  providerAuthentication: ACPResolvedProviderAuthentication | undefined;
+  gateway: ACPGatewayValues | undefined;
+}): Record<string, string> {
+  if (providerAuthentication?.type !== 'ai-gateway') {
+    return {};
+  }
+  const resolved = asRecord(
+    resolveACPProfileValue({
+      value: providerAuthentication.env,
+      gateway: requireGateway({ gateway }),
+    }),
+  );
+  return Object.fromEntries(
+    Object.entries(resolved).map(([key, value]) => [
+      key,
+      typeof value === 'string' ? value : JSON.stringify(value),
+    ]),
+  );
+}
+
+export function validateACPProtocolVersion({
+  requested,
+  initialization,
+}: {
+  requested: number;
+  initialization: ACPInitializeResult;
+}): void {
+  if (initialization.protocolVersion !== requested) {
+    throw new Error(
+      `ACP protocol negotiation failed: requested v${requested}, agent selected v${initialization.protocolVersion}.`,
+    );
+  }
+}
+
+export function assertACPAuthenticationMethod({
+  initialization,
+  methodId,
+}: {
+  initialization: ACPInitializeResult;
+  methodId: string;
+}): void {
+  if (!initialization.authMethods?.some(method => method.id === methodId)) {
+    const advertised =
+      initialization.authMethods?.map(method => method.id).join(', ') || 'none';
+    throw new Error(
+      `ACP authentication method ${JSON.stringify(methodId)} is not advertised by the agent. Advertised methods: ${advertised}.`,
+    );
+  }
+}
+
+function mergeRecords({
+  left,
+  right,
+}: {
+  left: Readonly<Record<string, unknown>>;
+  right: Readonly<Record<string, unknown>>;
+}): Readonly<Record<string, unknown>> {
+  const result: Record<string, unknown> = { ...left };
+  for (const [key, value] of Object.entries(right)) {
+    const previous = result[key];
+    result[key] =
+      isRecord(previous) && isRecord(value)
+        ? mergeRecords({ left: previous, right: value })
+        : value;
+  }
+  return result;
+}
+
+function requireGateway({
+  gateway,
+}: {
+  gateway: ACPGatewayValues | undefined;
+}): ACPGatewayValues {
+  if (gateway == null) {
+    throw new Error('ACP Gateway profile values are unavailable.');
+  }
+  return gateway;
+}
+
+function asRecord(value: unknown): Readonly<Record<string, unknown>> {
+  if (!isRecord(value)) {
+    throw new Error('ACP profile data must resolve to an object.');
+  }
+  return value;
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/v1/bridge/recovered-session.ts

@@ -0,0 +1,145 @@
+import { HarnessBridgeCapabilityUnsupportedError } from '@ai-sdk/harness/bridge';
+import * as acp from '@agentclientprotocol/sdk';
+import type { ACPInitializeResult } from './protocol-configuration';
+
+export type ACPActiveSession = {
+  readonly sessionId: string;
+  readonly newSessionResponse: acp.NewSessionResponse;
+  prompt(prompt: Array<acp.ContentBlock>): Promise<acp.PromptResponse>;
+  nextUpdate(): Promise<acp.ActiveSessionMessage>;
+  dispose(): void;
+};
+
+export function assertACPResumeCapability({
+  initialization,
+  harnessId,
+}: {
+  initialization: ACPInitializeResult;
+  harnessId: string;
+}): void {
+  const sessionCapabilities = initialization.agentCapabilities
+    ?.sessionCapabilities as Readonly<Record<string, unknown>> | undefined;
+  if (
+    sessionCapabilities?.resume == null ||
+    sessionCapabilities.resume === false
+  ) {
+    throw new HarnessBridgeCapabilityUnsupportedError({
+      harnessId,
+      message:
+        'ACP process-loss rerun requires the agent to advertise sessionCapabilities.resume; a fresh unrelated ACP session will not be created.',
+    });
+  }
+}
+
+export function createACPRecoveredSession({
+  agent,
+  sessionId,
+  restorationResponse,
+  updates,
+}: {
+  agent: acp.ClientContext;
+  sessionId: string;
+  restorationResponse: acp.ResumeSessionResponse | acp.LoadSessionResponse;
+  updates: ReturnType<typeof createACPRecoveredSessionUpdates>;
+}): ACPActiveSession {
+  let disposed = false;
+  return {
+    sessionId,
+    newSessionResponse: {
+      sessionId,
+      ...restorationResponse,
+    },
+    prompt: async prompt => {
+      if (disposed) {
+        throw new Error('Recovered ACP session is disposed.');
+      }
+      updates.clearErrors();
+      const response = agent.request<acp.PromptResponse, acp.PromptRequest>(
+        acp.methods.agent.session.prompt,
+        { sessionId, prompt },
+      );
+      void response.then(
+        value => {
+          updates.enqueue({
+            kind: 'stop',
+            response: value,
+            stopReason: value.stopReason,
+          });
+        },
+        error => updates.reject(error),
+      );
+      return response;
+    },
+    nextUpdate: () => updates.next(),
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      updates.fail(new Error('Recovered ACP session disposed.'));
+    },
+  };
+}
+
+export function createACPRecoveredSessionUpdates(): {
+  enqueue(value: acp.ActiveSessionMessage): void;
+  reject(error: unknown): void;
+  clearErrors(): void;
+  fail(error: unknown): void;
+  next(): Promise<acp.ActiveSessionMessage>;
+} {
+  type Entry =
+    | { readonly type: 'value'; readonly value: acp.ActiveSessionMessage }
+    | { readonly type: 'error'; readonly error: unknown };
+  const values: Entry[] = [];
+  const waiters: Array<{
+    resolve(value: acp.ActiveSessionMessage): void;
+    reject(error: unknown): void;
+  }> = [];
+  let failure: unknown;
+  let failed = false;
+  return {
+    enqueue(value) {
+      if (failed) return;
+      const waiter = waiters.shift();
+      if (waiter == null) values.push({ type: 'value', value });
+      else waiter.resolve(value);
+    },
+    reject(error) {
+      if (failed) return;
+      const waiter = waiters.shift();
+      if (waiter == null) values.push({ type: 'error', error });
+      else waiter.reject(error);
+    },
+    clearErrors() {
+      for (let index = values.length - 1; index >= 0; index--) {
+        if (values[index]?.type === 'error') values.splice(index, 1);
+      }
+    },
+    fail(error) {
+      if (failed) return;
+      failed = true;
+      failure = error;
+      for (const waiter of waiters.splice(0)) waiter.reject(error);
+    },
+    next() {
+      const entry = values.shift();
+      if (entry?.type === 'value') return Promise.resolve(entry.value);
+      if (entry?.type === 'error') {
+        return Promise.reject(
+          entry.error instanceof Error
+            ? entry.error
+            : new Error('Recovered ACP session update failed.'),
+        );
+      }
+      if (failed) {
+        return Promise.reject(
+          failure instanceof Error
+            ? failure
+            : new Error('Recovered ACP session update stream failed.'),
+        );
+      }
+      return new Promise((resolve, reject) => {
+        waiters.push({ resolve, reject });
+      });
+    },
+  };
+}

package/src/v1/bridge/refresh-host-tool-catalog.ts

@@ -0,0 +1,33 @@
+import type { HarnessV1BridgeToolWire } from '@ai-sdk/harness';
+import { HarnessBridgeCapabilityUnsupportedError } from '@ai-sdk/harness/bridge';
+import type { HostToolRelay } from './host-tool-relay';
+
+export async function refreshHostToolCatalog({
+  relay,
+  tools,
+  harnessId,
+  timeoutMs,
+}: {
+  relay: Pick<HostToolRelay, 'updateCatalog' | 'waitForCatalogRefresh'>;
+  tools: ReadonlyArray<HarnessV1BridgeToolWire>;
+  harnessId: string;
+  timeoutMs: number;
+}): Promise<void> {
+  const catalog = relay.updateCatalog({ tools });
+  if (!catalog.changed && tools.length === 0) return;
+  if (
+    await relay.waitForCatalogRefresh({
+      revision: catalog.revision,
+      timeoutMs,
+    })
+  ) {
+    return;
+  }
+  throw new HarnessBridgeCapabilityUnsupportedError({
+    harnessId,
+    message:
+      'The ACP implementation did not load the active harness-owned MCP ' +
+      `tool catalog to revision ${catalog.revision} before the next ` +
+      'prompt, so host tools cannot be exposed safely.',
+  });
+}

package/src/v1/bridge/session-lifecycle.ts

@@ -0,0 +1,83 @@
+import { HarnessBridgeCapabilityUnsupportedError } from '@ai-sdk/harness/bridge';
+import * as acp from '@agentclientprotocol/sdk';
+import type { ACPInitializeResult } from './protocol-configuration';
+
+export type ACPSessionRestorationMethod = 'resume' | 'load';
+
+export function resolveACPSessionRestorationMethod({
+  initialization,
+  harnessId,
+}: {
+  initialization: ACPInitializeResult;
+  harnessId: string;
+}): ACPSessionRestorationMethod {
+  const sessionCapabilities = initialization.agentCapabilities
+    ?.sessionCapabilities as Readonly<Record<string, unknown>> | undefined;
+  if (
+    sessionCapabilities?.resume != null &&
+    sessionCapabilities.resume !== false
+  ) {
+    return 'resume';
+  }
+  if (initialization.agentCapabilities?.loadSession === true) {
+    return 'load';
+  }
+  throw new HarnessBridgeCapabilityUnsupportedError({
+    harnessId,
+    message:
+      'Cold ACP session restoration requires the agent to advertise sessionCapabilities.resume or loadSession; a fresh unrelated ACP session will not be created.',
+  });
+}
+
+export async function restoreACPBridgeSession({
+  agent,
+  initialization,
+  sessionId,
+  cwd,
+  mcpServers,
+  meta,
+  harnessId,
+  setHistoricalUpdatesSuppressed,
+  discardCapturedHistory,
+}: {
+  agent: acp.ClientContext;
+  initialization: ACPInitializeResult;
+  sessionId: string;
+  cwd: string;
+  mcpServers: ReadonlyArray<acp.McpServer>;
+  meta: Readonly<Record<string, unknown>> | undefined;
+  harnessId: string;
+  setHistoricalUpdatesSuppressed(options: { suppressed: boolean }): void;
+  discardCapturedHistory(): void;
+}): Promise<{
+  method: ACPSessionRestorationMethod;
+  response: acp.ResumeSessionResponse | acp.LoadSessionResponse;
+}> {
+  const method = resolveACPSessionRestorationMethod({
+    initialization,
+    harnessId,
+  });
+  setHistoricalUpdatesSuppressed({ suppressed: true });
+  try {
+    const request = {
+      sessionId,
+      cwd,
+      mcpServers: [...mcpServers],
+      ...(meta == null ? {} : { _meta: meta }),
+    };
+    const response =
+      method === 'resume'
+        ? await agent.request<
+            acp.ResumeSessionResponse,
+            acp.ResumeSessionRequest
+          >(acp.methods.agent.session.resume, request)
+        : await agent.request<acp.LoadSessionResponse, acp.LoadSessionRequest>(
+            acp.methods.agent.session.load,
+            request,
+          );
+    discardCapturedHistory();
+    return { method, response };
+  } finally {
+    setHistoricalUpdatesSuppressed({ suppressed: false });
+  }
+}