@koreanhole/opencodex 2.95.10 → 2.97.0

package/src/adapters/cli-agent/acp-client.ts

@@ -0,0 +1,545 @@
+import { execFileSync, spawn as nodeSpawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import * as acp from "@agentclientprotocol/sdk";
+import { commandInvocation } from "../../lib/win-exec";
+import { redactSecretString } from "../../lib/redact";
+import type { CliAgentTurnDeps } from "./types";
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_KILL_GRACE_MS = 2_000;
+const MAX_STDERR_BYTES = 8 * 1024;
+const MAX_MODEL_ID_CHARS = 512;
+const MAX_ACP_MODELS = 512;
+const MAX_ACP_CONFIG_OPTIONS = 128;
+const MAX_ACP_OPTION_VALUES = 512;
+const MAX_MCP_SERVERS = 32;
+
+export interface AcpModel {
+  modelId: string;
+  name?: string;
+  description?: string;
+}
+
+export interface AcpConfigOptionValue {
+  value: string;
+  name?: string;
+  description?: string;
+}
+
+export interface AcpConfigOption {
+  type: "select" | "boolean";
+  id: string;
+  name: string;
+  category?: string;
+  currentValue?: string | boolean;
+  options?: readonly AcpConfigOptionValue[];
+}
+
+export interface AcpSessionInfo {
+  sessionId: string;
+  currentModelId?: string;
+  availableModels: readonly AcpModel[];
+  configOptions: readonly AcpConfigOption[];
+  modelConfigOption?: AcpConfigOption;
+}
+
+export interface AcpAuthMethod {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+export interface AcpInitialize {
+  protocolVersion: number;
+  authMethods: readonly AcpAuthMethod[];
+  agentVersion?: string;
+}
+
+export class AcpError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly errorType: string,
+    readonly code: string,
+    readonly retryable: boolean,
+    readonly fallbackAllowed: boolean,
+    readonly authRequired = false,
+  ) {
+    super(message);
+    this.name = "AcpError";
+  }
+}
+
+export interface AcpDeps extends CliAgentTurnDeps {
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface AcpHooks {
+  onSessionUpdate?: (notification: acp.SessionNotification) => void;
+  onPermission?: (params: acp.RequestPermissionRequest) => void;
+  onStderr?: (text: string) => void;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function nonEmpty(value: unknown, max = MAX_MODEL_ID_CHARS): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed && trimmed.length <= max ? trimmed : undefined;
+}
+
+export function safeAcpMessage(value: unknown, fallback = "ACP failed."): string {
+  const raw = value instanceof Error
+    ? value.message
+    : typeof value === "string"
+      ? value
+      : value === undefined
+        ? fallback
+        : JSON.stringify(value) ?? String(value);
+  return redactSecretString(raw).slice(0, 2_048);
+}
+
+export function isAcpAuthError(error: unknown): boolean {
+  return /auth(?:entication)?\s*(?:required|failed|missing)|not\s+(?:logged|signed)\s+in|sign[ -]?in|login required|unauthorized|api key (?:is )?missing|invalid (?:api )?key/i.test(safeAcpMessage(error));
+}
+
+function modelFrom(value: unknown): AcpModel | undefined {
+  const record = asRecord(value);
+  const modelId = nonEmpty(record?.modelId);
+  if (!modelId) return undefined;
+  const name = nonEmpty(record?.name, 512);
+  const description = nonEmpty(record?.description, 2_048);
+  return {
+    modelId,
+    ...(name ? { name } : {}),
+    ...(description ? { description } : {}),
+  };
+}
+
+function configOptionFrom(value: unknown): AcpConfigOption | undefined {
+  const record = asRecord(value);
+  if (!record) return undefined;
+  const id = nonEmpty(record.id, 512);
+  const name = nonEmpty(record.name, 512);
+  if (!id || !name) return undefined;
+  const type = record.type === "boolean" ? "boolean" : record.type === "select" ? "select" : undefined;
+  if (!type) return undefined;
+  const category = typeof record.category === "string" ? record.category : undefined;
+  const currentValue = typeof record.currentValue === "string" || typeof record.currentValue === "boolean"
+    ? record.currentValue
+    : undefined;
+  const options = Array.isArray(record.options)
+    ? record.options.slice(0, MAX_ACP_OPTION_VALUES).flatMap(item => {
+      const option = asRecord(item);
+      const optionValue = nonEmpty(option?.value, 512);
+      if (!optionValue) return [];
+      const optionName = nonEmpty(option?.name, 512);
+      const optionDescription = nonEmpty(option?.description, 2_048);
+      return [{
+        value: optionValue,
+        ...(optionName ? { name: optionName } : {}),
+        ...(optionDescription ? { description: optionDescription } : {}),
+      }];
+    })
+    : undefined;
+  return {
+    type,
+    id,
+    name,
+    ...(category ? { category } : {}),
+    ...(currentValue !== undefined ? { currentValue } : {}),
+    ...(options ? { options } : {}),
+  };
+}
+
+/** Parse the ACP session extension without requiring provider-specific fields. */
+export function parseAcpSession(
+  response: unknown,
+  label = "ACP",
+  fallbackAllowed = true,
+): AcpSessionInfo {
+  const result = asRecord(response);
+  const sessionId = nonEmpty(result?.sessionId, 1_024);
+  if (!sessionId) throw new AcpError(`${label} returned a session without an id.`, 502, "upstream_error", "acp_protocol_error", false, fallbackAllowed);
+  const models = asRecord(result?.models);
+  const seen = new Set<string>();
+  const availableModels: AcpModel[] = [];
+  if (Array.isArray(models?.availableModels)) {
+    for (const item of models.availableModels.slice(0, MAX_ACP_MODELS)) {
+      const model = modelFrom(item);
+      if (!model || seen.has(model.modelId)) continue;
+      seen.add(model.modelId);
+      availableModels.push(model);
+    }
+  }
+  const configOptions = Array.isArray(result?.configOptions)
+    ? result.configOptions.slice(0, MAX_ACP_CONFIG_OPTIONS).flatMap(item => {
+      const option = configOptionFrom(item);
+      return option ? [option] : [];
+    })
+    : [];
+  const currentModelId = nonEmpty(models?.currentModelId);
+  const modelConfigOption = configOptions.find(option => option.type === "select" && option.category === "model");
+  return {
+    sessionId,
+    ...(currentModelId ? { currentModelId } : {}),
+    availableModels,
+    configOptions,
+    ...(modelConfigOption ? { modelConfigOption } : {}),
+  };
+}
+
+export function parseAcpInitialize(
+  value: unknown,
+  label = "ACP",
+  fallbackAllowed = true,
+): AcpInitialize {
+  const result = asRecord(value);
+  if (!result) throw new AcpError(`${label} initialize returned an invalid response.`, 502, "upstream_error", "acp_protocol_error", false, fallbackAllowed);
+  const version = typeof result.protocolVersion === "number" && Number.isInteger(result.protocolVersion)
+    ? result.protocolVersion
+    : undefined;
+  if (version !== acp.PROTOCOL_VERSION) {
+    throw new AcpError(
+      `${label} negotiated protocol ${String(version ?? "unknown")}; only v${acp.PROTOCOL_VERSION} is supported.`,
+      502,
+      "upstream_error",
+      "acp_protocol_error",
+      false,
+      fallbackAllowed,
+    );
+  }
+  const authMethods = Array.isArray(result.authMethods)
+    ? result.authMethods.flatMap(item => {
+      const record = asRecord(item);
+      const id = nonEmpty(record?.id, 256);
+      const name = nonEmpty(record?.name, 512);
+      const description = nonEmpty(record?.description, 2_048);
+      return id && name ? [{ id, name, ...(description ? { description } : {}) }] : [];
+    })
+    : [];
+  const agentInfo = asRecord(result.agentInfo);
+  const agentVersion = nonEmpty(agentInfo?.version, 256);
+  return { protocolVersion: version, authMethods, ...(agentVersion ? { agentVersion } : {}) };
+}
+
+function acpError(error: unknown, fallbackAllowed: boolean, label: string): AcpError {
+  const authRequired = isAcpAuthError(error);
+  return new AcpError(
+    safeAcpMessage(error, `${label} failed.`),
+    authRequired ? 401 : 502,
+    authRequired ? "authentication_error" : "upstream_error",
+    authRequired ? "acp_auth_required" : "acp_transport_error",
+    false,
+    fallbackAllowed,
+    authRequired,
+  );
+}
+
+function killWindowsProcessTree(pid: number): void {
+  const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
+  execFileSync(taskkill, ["/PID", String(pid), "/T", "/F"], { stdio: "pipe", windowsHide: true });
+}
+
+export interface AcpClientOptions {
+  binary: string;
+  env: Record<string, string>;
+  cwd: string;
+  args?: readonly string[];
+  hooks?: AcpHooks;
+  label?: string;
+  fallbackAllowed?: boolean;
+}
+
+/** One request-scoped ACP child. Cleanup is idempotent and always reaps the process. */
+export class AcpClient {
+  private readonly child: ReturnType<typeof nodeSpawn>;
+  private readonly connection: acp.ClientSideConnection;
+  private readonly processLifecycle: Promise<void>;
+  private readonly stderrChunks: string[] = [];
+  private stderrBytes = 0;
+  private readonly terminateOnce: () => Promise<void>;
+  private terminated = false;
+  private exited = false;
+  private readonly label: string;
+  private readonly fallbackAllowed: boolean;
+  sessionId?: string;
+  initializeResult?: AcpInitialize;
+
+  private constructor(
+    child: ReturnType<typeof nodeSpawn>,
+    connection: acp.ClientSideConnection,
+    processLifecycle: Promise<void>,
+    private readonly hooks: AcpHooks,
+    private readonly deps: AcpDeps,
+    label: string,
+    fallbackAllowed: boolean,
+  ) {
+    this.child = child;
+    this.connection = connection;
+    this.processLifecycle = processLifecycle;
+    this.label = label;
+    this.fallbackAllowed = fallbackAllowed;
+    this.terminateOnce = async () => {
+      if (this.terminated) return;
+      this.terminated = true;
+      try { this.child.stdin?.end(); } catch { /* already closed */ }
+      if (this.deps.platform === "win32" && this.child.pid !== undefined) {
+        try { (this.deps.killWindowsProcessTree ?? killWindowsProcessTree)(this.child.pid); } catch { /* direct fallback */ }
+      }
+      this.signalTree("SIGTERM");
+      await Promise.race([
+        this.processLifecycle,
+        new Promise<void>(resolve => setTimeout(resolve, this.deps.killGraceMs ?? DEFAULT_KILL_GRACE_MS)),
+      ]);
+      if (this.child.exitCode === null || this.treeAlive()) {
+        this.signalTree("SIGKILL");
+        await Promise.race([
+          this.processLifecycle,
+          new Promise<void>(resolve => setTimeout(resolve, (this.deps.reapTimeoutMs ?? (this.deps.killGraceMs ?? DEFAULT_KILL_GRACE_MS) * 2 + 250))),
+        ]);
+      }
+    };
+  }
+
+  private signalTree(signal: NodeJS.Signals): void {
+    const pid = this.child.pid;
+    if ((this.deps.platform ?? process.platform) !== "win32" && pid !== undefined) {
+      try {
+        process.kill(-pid, signal);
+        return;
+      } catch {
+        // Fall through when the child did not establish a process group.
+      }
+    }
+    try { this.child.kill(signal); } catch { /* already gone */ }
+  }
+
+  private treeAlive(): boolean {
+    const pid = this.child.pid;
+    if ((this.deps.platform ?? process.platform) === "win32" || pid === undefined) return false;
+    try {
+      process.kill(-pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  static async connect(
+    options: AcpClientOptions,
+    deps: AcpDeps = {},
+  ): Promise<AcpClient> {
+    const hooks = options.hooks ?? {};
+    const label = options.label ?? "ACP";
+    const fallbackAllowed = options.fallbackAllowed ?? true;
+    const spawnFn = deps.spawn ?? (nodeSpawn as unknown as NonNullable<CliAgentTurnDeps["spawn"]>);
+    const invocation = commandInvocation(options.binary, [...(options.args ?? ["--acp"])], deps.platform ?? process.platform, { env: options.env });
+    let child: ReturnType<typeof nodeSpawn>;
+    try {
+      child = spawnFn(invocation.file, invocation.args, {
+        ...invocation.options,
+        cwd: options.cwd,
+        env: options.env,
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+        detached: (deps.platform ?? process.platform) !== "win32",
+      });
+    } catch (error) {
+      throw acpError(error, fallbackAllowed, label);
+    }
+    if (!child.stdin || !child.stdout) {
+      try { child.kill("SIGKILL"); } catch { /* ignore */ }
+      throw new AcpError(`${label} process did not expose stdio.`, 500, "upstream_error", "acp_spawn_failed", false, fallbackAllowed);
+    }
+    const processLifecycle = new Promise<void>(resolvePromise => {
+      let settled = false;
+      const settle = (): void => {
+        if (settled) return;
+        settled = true;
+        resolvePromise();
+      };
+      child.once("error", settle);
+      child.once("close", settle);
+      if (child.exitCode !== null) settle();
+    });
+    let instance: AcpClient;
+    const client: acp.Client = {
+      requestPermission: async params => {
+        hooks.onPermission?.(params);
+        if (instance?.sessionId) void instance.cancel(instance.sessionId).catch(() => undefined);
+        return { outcome: { outcome: "cancelled" } };
+      },
+      sessionUpdate: async notification => {
+        if (notification.sessionId === instance?.sessionId) hooks.onSessionUpdate?.(notification);
+      },
+    };
+    const stream = acp.ndJsonStream(
+      Writable.toWeb(child.stdin) as WritableStream<Uint8Array>,
+      Readable.toWeb(child.stdout) as unknown as ReadableStream<Uint8Array>,
+    );
+    const connection = new acp.ClientSideConnection(() => client, stream);
+    instance = new AcpClient(child, connection, processLifecycle, hooks, deps, label, fallbackAllowed);
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk: string) => {
+      if (instance.stderrBytes >= MAX_STDERR_BYTES) return;
+      const remaining = MAX_STDERR_BYTES - instance.stderrBytes;
+      const admitted = chunk.slice(0, remaining);
+      instance.stderrChunks.push(admitted);
+      instance.stderrBytes += admitted.length;
+      hooks.onStderr?.(admitted);
+    });
+    child.once("close", () => { instance.exited = true; });
+    try {
+      const initialize = await deadline(
+        connection.initialize({
+          protocolVersion: acp.PROTOCOL_VERSION,
+          clientCapabilities: {},
+          clientInfo: { name: "opencodex", version: "1.0.0" },
+        }),
+        deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        () => instance.terminate(),
+        label,
+        fallbackAllowed,
+      );
+      instance.initializeResult = parseAcpInitialize(initialize, label, fallbackAllowed);
+      return instance;
+    } catch (error) {
+      await instance.terminate();
+      if (error instanceof AcpError) throw error;
+      throw acpError(error, fallbackAllowed, label);
+    }
+  }
+
+  stderrText(): string {
+    return this.stderrChunks.join("");
+  }
+
+  async newSession(params: {
+    cwd: string;
+    mcpServers: readonly Record<string, unknown>[];
+  }): Promise<AcpSessionInfo> {
+    try {
+      const response = await deadline(
+        this.connection.request<unknown>(acp.AGENT_METHODS.session_new, {
+          cwd: params.cwd,
+          mcpServers: params.mcpServers.slice(0, MAX_MCP_SERVERS),
+        }),
+        this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        () => this.terminate(),
+        this.label,
+        this.fallbackAllowed,
+      );
+      const session = parseAcpSession(response, this.label, this.fallbackAllowed);
+      this.sessionId = session.sessionId;
+      return session;
+    } catch (error) {
+      if (error instanceof AcpError) throw error;
+      throw acpError(error, this.fallbackAllowed, this.label);
+    }
+  }
+
+  async setModel(sessionId: string, modelId: string): Promise<void> {
+    await deadline(
+      this.connection.request("session/set_model", { sessionId, modelId }),
+      this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      () => this.terminate(),
+      this.label,
+      this.fallbackAllowed,
+    ).catch(error => {
+      if (error instanceof AcpError) throw error;
+      throw new AcpError(`${this.label} rejected session/set_model.`, 502, "upstream_error", "acp_transport_error", false, this.fallbackAllowed);
+    });
+  }
+
+  async setConfigOption(sessionId: string, configId: string, value: string): Promise<void> {
+    await deadline(
+      this.connection.request(acp.AGENT_METHODS.session_set_config_option, {
+        sessionId,
+        configId,
+        value,
+      }),
+      this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      () => this.terminate(),
+      this.label,
+      this.fallbackAllowed,
+    ).catch(error => {
+      if (error instanceof AcpError) throw error;
+      throw new AcpError(`${this.label} rejected session/set_config_option.`, 502, "upstream_error", "acp_transport_error", false, this.fallbackAllowed);
+    });
+  }
+
+  async setMode(sessionId: string, modeId: string): Promise<void> {
+    await deadline(
+      this.connection.request(acp.AGENT_METHODS.session_set_mode, { sessionId, modeId }),
+      this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      () => this.terminate(),
+      this.label,
+      this.fallbackAllowed,
+    ).catch(error => {
+      if (error instanceof AcpError) throw error;
+      throw new AcpError(`${this.label} rejected session/set_mode.`, 502, "upstream_error", "acp_transport_error", false, this.fallbackAllowed);
+    });
+  }
+
+  async authenticate(methodId: string): Promise<void> {
+    await deadline(
+      this.connection.authenticate({ methodId }),
+      this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      () => this.terminate(),
+      this.label,
+      this.fallbackAllowed,
+    ).catch(error => {
+      if (error instanceof AcpError) throw error;
+      throw acpError(error, this.fallbackAllowed, this.label);
+    });
+  }
+
+  async prompt(sessionId: string, text: string, cancellationSignal?: AbortSignal): Promise<acp.PromptResponse> {
+    return await deadline(
+      this.connection.request(
+        acp.AGENT_METHODS.session_prompt,
+        { sessionId, prompt: [{ type: "text" as const, text }] },
+        { ...(cancellationSignal ? { cancellationSignal } : {}) },
+      ),
+      this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      () => this.terminate(),
+      this.label,
+      this.fallbackAllowed,
+    );
+  }
+
+  async cancel(sessionId: string): Promise<void> {
+    if (this.exited) return;
+    await this.connection.cancel({ sessionId });
+  }
+
+  async terminate(): Promise<void> {
+    await this.terminateOnce();
+  }
+}
+
+async function deadline<T>(
+  promise: Promise<T>,
+  ms: number,
+  onTimeout: () => Promise<void>,
+  label: string,
+  fallbackAllowed: boolean,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      void onTimeout().catch(() => undefined);
+      reject(new AcpError(`${label} request timed out.`, 504, "upstream_error", "timeout", true, fallbackAllowed));
+    }, ms);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}