@koreanhole/opencodex 2.95.7 → 2.95.9

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

@@ -0,0 +1,1006 @@
+import { execFileSync, spawn as nodeSpawn } from "node:child_process";
+import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { Readable, Writable } from "node:stream";
+import * as acp from "@agentclientprotocol/sdk";
+import type { AdapterEvent } from "../../../types";
+import type { IncomingMeta } from "../../base";
+import { commandInvocation } from "../../../lib/win-exec";
+import { SendBudgetExhaustedError } from "../../../lib/upstream-retry";
+import type { SingleUseDispatchPermit } from "../../../lib/request-execution-budget";
+import { baseScopedEnv } from "../../coding-agent/turn";
+import { resolveClineBinary } from "./binary";
+import type { CliAgentStreamState, CliAgentTurnDeps } from "../types";
+import { createClineStreamState, ClineStreamProtocolError, mapClineToolIntent } from "./stream";
+
+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;
+
+const CLINE_ACP_ARGS = ["--acp"] as const;
+const OPENAI_CODEX_AUTH_IDS = new Set(["openai-codex", "openai-codex-oauth"]);
+const CLINE_AUTH_IDS = new Set(["cline", "cline-oauth"]);
+
+export interface ClineAcpModel {
+  modelId: string;
+  name?: string;
+  description?: string;
+}
+
+export interface ClineAcpConfigOptionValue {
+  value: string;
+  name?: string;
+  description?: string;
+}
+
+export interface ClineAcpConfigOption {
+  type: "select" | "boolean";
+  id: string;
+  name: string;
+  category?: string;
+  currentValue?: string | boolean;
+  options?: readonly ClineAcpConfigOptionValue[];
+}
+
+export interface ClineAcpSessionInfo {
+  sessionId: string;
+  currentModelId?: string;
+  availableModels: readonly ClineAcpModel[];
+  configOptions: readonly ClineAcpConfigOption[];
+  modelConfigOption?: ClineAcpConfigOption;
+}
+
+export interface ClineAcpAuthMethod {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+export interface ClineAcpInitialize {
+  protocolVersion: number;
+  authMethods: readonly ClineAcpAuthMethod[];
+  agentVersion?: string;
+}
+
+export class ClineAcpError 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 = "ClineAcpError";
+  }
+}
+
+export interface ClineAcpDeps extends CliAgentTurnDeps {
+  spawn?: typeof nodeSpawn;
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface ClineAcpHooks {
+  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;
+}
+
+function safeMessage(value: unknown): string {
+  const raw = value instanceof Error
+    ? value.message
+    : typeof value === "string"
+      ? value
+      : value === undefined
+        ? "Cline ACP failed."
+        : JSON.stringify(value) ?? String(value);
+  return raw
+    .replace(/\bsk-[A-Za-z0-9_-]{6,}\b/g, "[redacted]")
+    .replace(/(authorization\s*[:=]\s*)\S+/gi, "$1[redacted]")
+    .slice(0, 2_048);
+}
+
+function modelFrom(value: unknown): ClineAcpModel | 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): ClineAcpConfigOption | 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 Cline's session/new extension without requiring it in the stable ACP schema. */
+export function parseClineAcpSession(response: unknown): ClineAcpSessionInfo {
+  const result = asRecord(response);
+  const sessionId = nonEmpty(result?.sessionId, 1_024);
+  if (!sessionId) throw new ClineAcpError("Cline ACP returned a session without an id.", 502, "upstream_error", "acp_protocol_error", false, true);
+  const models = asRecord(result?.models);
+  const seen = new Set<string>();
+  const availableModels: ClineAcpModel[] = [];
+  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);
+  return {
+    sessionId,
+    ...(currentModelId ? { currentModelId } : {}),
+    availableModels,
+    configOptions,
+    ...(configOptions.find(option => option.type === "select" && option.category === "model")
+      ? { modelConfigOption: configOptions.find(option => option.type === "select" && option.category === "model") }
+      : {}),
+  };
+}
+
+export interface ClineModelSource {
+  ids: string[];
+  source: "models" | "configOptions" | "default";
+}
+
+/** Apply the specified discovery order and de-duplicate native ids. */
+export function clineModelSource(session: ClineAcpSessionInfo): ClineModelSource {
+  if (session.availableModels.length > 0) {
+    return { ids: session.availableModels.map(model => model.modelId), source: "models" };
+  }
+  const values = session.modelConfigOption?.options?.map(option => option.value) ?? [];
+  const ids = [...new Set(values.filter(value => value && value !== "default"))];
+  return ids.length > 0 ? { ids, source: "configOptions" } : { ids: ["default"], source: "default" };
+}
+
+export function parseClineAcpInitialize(value: unknown): ClineAcpInitialize {
+  const result = asRecord(value);
+  if (!result) throw new ClineAcpError("Cline ACP initialize returned an invalid response.", 502, "upstream_error", "acp_protocol_error", false, true);
+  const version = typeof result.protocolVersion === "number" && Number.isInteger(result.protocolVersion)
+    ? result.protocolVersion
+    : undefined;
+  if (version !== acp.PROTOCOL_VERSION) {
+    throw new ClineAcpError(
+      `Cline ACP negotiated protocol ${String(version ?? "unknown")}; only v${acp.PROTOCOL_VERSION} is supported.`,
+      502,
+      "upstream_error",
+      "acp_protocol_error",
+      false,
+      true,
+    );
+  }
+  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 } : {}) };
+}
+
+export interface ClineAcpMode {
+  acp: boolean;
+  autoApproveFlag?: boolean;
+}
+
+const MODE_CACHE = new Map<string, { mtimeMs: number; size: number; acp: boolean; autoApproveFlag: boolean }>();
+
+/** ACP is off by exact `0`; every other/missing value permits the capability probe. */
+export function clineAcpEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.OPENCODEX_CLINE_ACP?.trim() !== "0";
+}
+
+function acpHelp(text: string): { acp: boolean; autoApproveFlag: boolean } {
+  return {
+    acp: /(?:^|\s)--acp(?:\s|,|<|$)/.test(text),
+    autoApproveFlag: /(?:^|\s)--auto-approve(?:\s|,|<|$)/.test(text),
+  };
+}
+
+/** Probe `--acp` with a bounded help command and cache by binary path/fingerprint. */
+export async function probeClineAcpSupport(
+  binary: string,
+  env: Record<string, string>,
+  deps: ClineAcpDeps = {},
+): Promise<ClineAcpMode> {
+  if (!clineAcpEnabled(deps.env ?? process.env)) return { acp: false };
+  const key = resolve(binary);
+  let mtimeMs: number | undefined;
+  let size: number | undefined;
+  try {
+    const value = await stat(key);
+    mtimeMs = value.mtimeMs;
+    size = value.size;
+  } catch {
+    return { acp: false };
+  }
+  const cached = MODE_CACHE.get(key);
+  if (cached && cached.mtimeMs === mtimeMs && cached.size === size) {
+    return { acp: cached.acp, ...(cached.autoApproveFlag ? { autoApproveFlag: true } : {}) };
+  }
+  const result = await runClineHelp(binary, env, deps);
+  const capabilities = acpHelp(result);
+  MODE_CACHE.set(key, { mtimeMs, size, ...capabilities });
+  return { acp: capabilities.acp, ...(capabilities.autoApproveFlag ? { autoApproveFlag: true } : {}) };
+}
+
+async function runClineHelp(
+  binary: string,
+  env: Record<string, string>,
+  deps: ClineAcpDeps,
+): Promise<string> {
+  return await new Promise((resolvePromise, reject) => {
+    const invocation = commandInvocation(binary, ["--help"], deps.platform ?? process.platform, { env });
+    const spawnFn = deps.spawn ?? nodeSpawn;
+    const child = spawnFn(invocation.file, invocation.args, {
+      ...invocation.options,
+      cwd: homedir(),
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    const chunks: string[] = [];
+    let bytes = 0;
+    let settled = false;
+    const finish = (fn: () => void): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
+    const timer = setTimeout(() => {
+      try { child.kill("SIGKILL"); } catch { /* ignore */ }
+      finish(() => reject(new Error("Cline --help probe timed out.")));
+    }, deps.timeoutMs ?? 15_000);
+    const collect = (chunk: Buffer): void => {
+      if (bytes >= MAX_STDERR_BYTES) return;
+      const admitted = chunk.subarray(0, MAX_STDERR_BYTES - bytes);
+      chunks.push(admitted.toString("utf8"));
+      bytes += admitted.byteLength;
+    };
+    child.stdout?.on("data", collect);
+    child.stderr?.on("data", collect);
+    child.once("error", error => finish(() => reject(error)));
+    child.once("close", () => finish(() => resolvePromise(chunks.join(""))));
+  });
+}
+
+function isAuthError(error: unknown): boolean {
+  const message = safeMessage(error);
+  return /auth(?:entication)?\s*(?:required|failed)|not\s+(?:logged|signed)\s+in|sign[ -]?in|login required|unauthorized/i.test(message);
+}
+
+function acpError(error: unknown, fallbackAllowed: boolean): ClineAcpError {
+  const authRequired = isAuthError(error);
+  return new ClineAcpError(
+    safeMessage(error),
+    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 ClineAcpClientOptions {
+  binary: string;
+  env: Record<string, string>;
+  cwd: string;
+  args?: readonly string[];
+  hooks?: ClineAcpHooks;
+}
+
+/** One request-scoped ACP child. Cleanup is idempotent and always reaps the process. */
+export class ClineAcpClient {
+  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;
+  sessionId?: string;
+  initializeResult?: ClineAcpInitialize;
+
+  private constructor(
+    child: ReturnType<typeof nodeSpawn>,
+    connection: acp.ClientSideConnection,
+    processLifecycle: Promise<void>,
+    private readonly hooks: ClineAcpHooks,
+    private readonly deps: ClineAcpDeps,
+  ) {
+    this.child = child;
+    this.connection = connection;
+    this.processLifecycle = processLifecycle;
+    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 */ }
+      }
+      try { this.child.kill("SIGTERM"); } catch { /* already gone */ }
+      await Promise.race([
+        this.processLifecycle,
+        new Promise<void>(resolve => setTimeout(resolve, this.deps.killGraceMs ?? DEFAULT_KILL_GRACE_MS)),
+      ]);
+      if (this.child.exitCode === null) {
+        try { this.child.kill("SIGKILL"); } catch { /* already gone */ }
+        await Promise.race([
+          this.processLifecycle,
+          new Promise<void>(resolve => setTimeout(resolve, (this.deps.reapTimeoutMs ?? (this.deps.killGraceMs ?? DEFAULT_KILL_GRACE_MS) * 2 + 250))),
+        ]);
+      }
+    };
+  }
+
+  static async connect(
+    options: ClineAcpClientOptions,
+    deps: ClineAcpDeps = {},
+  ): Promise<ClineAcpClient> {
+    const hooks = options.hooks ?? {};
+    const spawnFn = deps.spawn ?? nodeSpawn;
+    const invocation = commandInvocation(options.binary, [...(options.args ?? CLINE_ACP_ARGS)], 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,
+      });
+    } catch (error) {
+      throw acpError(error, true);
+    }
+    if (!child.stdin || !child.stdout) {
+      try { child.kill("SIGKILL"); } catch { /* ignore */ }
+      throw new ClineAcpError("Cline ACP process did not expose stdio.", 500, "upstream_error", "acp_spawn_failed", false, true);
+    }
+    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: ClineAcpClient;
+    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 ClineAcpClient(child, connection, processLifecycle, hooks, deps);
+    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(),
+      );
+      instance.initializeResult = parseClineAcpInitialize(initialize);
+      return instance;
+    } catch (error) {
+      await instance.terminate();
+      if (error instanceof ClineAcpError) {
+        if (error.code === "timeout") {
+          throw new ClineAcpError(error.message, error.status, error.errorType, error.code, error.retryable, true);
+        }
+        throw error;
+      }
+      throw acpError(error, true);
+    }
+  }
+
+  stderrText(): string {
+    return this.stderrChunks.join("");
+  }
+
+  async newSession(params: {
+    cwd: string;
+    mcpServers: readonly Record<string, unknown>[];
+  }): Promise<ClineAcpSessionInfo> {
+    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(),
+      );
+      const session = parseClineAcpSession(response);
+      this.sessionId = session.sessionId;
+      return session;
+    } catch (error) {
+      if (error instanceof ClineAcpError) {
+        if (error.code === "timeout") {
+          throw new ClineAcpError(error.message, error.status, error.errorType, error.code, error.retryable, true);
+        }
+        throw error;
+      }
+      throw acpError(error, true);
+    }
+  }
+
+  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(),
+    ).catch(error => {
+      if (error instanceof ClineAcpError) throw error;
+      throw new ClineAcpError("Cline ACP rejected session/set_model.", 502, "upstream_error", "acp_transport_error", false, false);
+    });
+  }
+
+  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(),
+    ).catch(error => {
+      if (error instanceof ClineAcpError) throw error;
+      throw new ClineAcpError("Cline ACP rejected session/set_config_option.", 502, "upstream_error", "acp_transport_error", false, false);
+    });
+  }
+
+  async authenticate(methodId: string): Promise<void> {
+    await deadline(
+      this.connection.authenticate({ methodId }),
+      this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      () => this.terminate(),
+    ).catch(error => {
+      if (error instanceof ClineAcpError) throw error;
+      throw acpError(error, false);
+    });
+  }
+
+  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(),
+    );
+  }
+
+  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>): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      void onTimeout().catch(() => undefined);
+      reject(new ClineAcpError("Cline ACP request timed out.", 504, "upstream_error", "timeout", true, false));
+    }, ms);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export function selectClineAuthMethod(methods: readonly ClineAcpAuthMethod[]): ClineAcpAuthMethod | undefined {
+  const byId = new Map(methods.map(method => [method.id.toLowerCase(), method]));
+  for (const id of ["cline", "cline-oauth", "openai-codex", "openai-codex-oauth"]) {
+    const method = byId.get(id);
+    if (method) return method;
+  }
+  return methods.find(method => CLINE_AUTH_IDS.has(method.id.toLowerCase()) || OPENAI_CODEX_AUTH_IDS.has(method.id.toLowerCase()));
+}
+
+export interface ClineAcpLoginOptions {
+  binary?: string;
+  env?: NodeJS.ProcessEnv;
+  noWait?: boolean;
+  onInstruction?: (text: string) => void;
+  deps?: ClineAcpDeps;
+}
+
+export interface ClineAcpLoginResult {
+  methods: readonly ClineAcpAuthMethod[];
+  method: ClineAcpAuthMethod;
+  instructions: string;
+  complete: boolean;
+}
+
+/** Perform one human-initiated ACP login. Request paths must never call this function. */
+export async function loginClineAcp(options: ClineAcpLoginOptions = {}): Promise<ClineAcpLoginResult> {
+  const sourceEnv = options.env ?? process.env;
+  const binary = options.binary ?? resolveClineBinary(undefined, sourceEnv);
+  if (!binary) {
+    throw new ClineAcpError("Cline CLI not found on PATH. Install it with `npm install -g cline`.", 500, "upstream_error", "cli_not_found", false, false);
+  }
+  const env = buildClineAcpEnv(sourceEnv);
+  const mode = await probeClineAcpSupport(binary, env, { ...options.deps, env: sourceEnv });
+  if (!mode.acp) {
+    throw new ClineAcpError("The installed Cline CLI does not advertise --acp.", 400, "invalid_request_error", "cline_acp_unsupported", false, false);
+  }
+  const workspace = await stageClineAcpWorkspace();
+  let instructions = "";
+  let client: ClineAcpClient | undefined;
+  try {
+    client = await ClineAcpClient.connect({
+      binary,
+      env,
+      cwd: workspace.cwd,
+      args: mode.autoApproveFlag ? ["--acp", "--auto-approve", "false"] : ["--acp"],
+      hooks: {
+        onStderr: text => {
+          instructions = (instructions + text).slice(0, MAX_STDERR_BYTES);
+          options.onInstruction?.(text);
+        },
+      },
+    }, options.deps);
+    const methods = client.initializeResult?.authMethods ?? [];
+    const method = selectClineAuthMethod(methods);
+    if (!method) {
+      throw new ClineAcpError(
+        methods.length > 0
+          ? `No supported Cline ACP auth method. Advertised: ${methods.map(item => item.id).join(", ")}.`
+          : "Cline ACP did not advertise any authentication methods.",
+        400,
+        "invalid_request_error",
+        "cline_acp_auth_unavailable",
+        false,
+        false,
+      );
+    }
+    let authError: unknown;
+    const auth = client.authenticate(method.id).then(
+      () => true,
+      error => {
+        authError = error;
+        return false;
+      },
+    );
+    const completed = options.noWait
+      ? await Promise.race([
+        auth,
+        new Promise<boolean>(resolvePromise => setTimeout(() => resolvePromise(false), 2_000)),
+      ])
+      : await auth;
+    if (authError) throw authError;
+    return { methods, method, instructions, complete: completed };
+  } finally {
+    await client?.terminate();
+    await workspace.cleanup();
+  }
+}
+
+
+/** Build the Cline ACP child environment without staging auth away from the real home. */
+export function buildClineAcpEnv(sourceEnv: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const env = baseScopedEnv();
+  const realHome = nonEmpty(sourceEnv.HOME) ?? nonEmpty(sourceEnv.USERPROFILE) ?? homedir();
+  env.HOME = realHome;
+  env.USERPROFILE = realHome;
+  for (const key of ["XDG_CONFIG_HOME", "XDG_CACHE_HOME", "CLINE_DIR", "CLINE_DATA_DIR", "CLINE_PROVIDER_SETTINGS_PATH"]) {
+    const value = nonEmpty(sourceEnv[key]);
+    if (value) env[key] = value;
+  }
+  Object.assign(env, {
+    CLINE_NO_AUTO_UPDATE: "1",
+    CLINE_TELEMETRY_DISABLED: "1",
+    CLINE_DISABLE_CLINE_PASS_NOTICE: "1",
+    NO_UPDATE_NOTIFIER: "1",
+    NO_COLOR: "1",
+  });
+  return env;
+}
+
+export interface ClineAcpWorkspace {
+  cwd: string;
+  catalogPath?: string;
+  cleanup: () => Promise<void>;
+}
+
+export async function stageClineAcpWorkspace(
+  catalog: readonly Record<string, unknown>[] = [],
+): Promise<ClineAcpWorkspace> {
+  const cwd = await mkdtemp(join(tmpdir(), "ocx-cline-acp-"));
+  const catalogPath = join(cwd, "tool-catalog.json");
+  await writeFile(catalogPath, JSON.stringify(catalog), { encoding: "utf8", mode: 0o600, flag: "wx" });
+  return {
+    cwd,
+    ...(catalog.length > 0 ? { catalogPath } : {}),
+    cleanup: async () => { await rm(cwd, { recursive: true, force: true }).catch(() => undefined); },
+  };
+}
+
+export interface ClineAcpTurnInput {
+  binary: string;
+  env: Record<string, string>;
+  cwd: string;
+  modelId: string;
+  prompt: string;
+  toolNames: ReadonlyMap<string, string>;
+  mcpServers: readonly Record<string, unknown>[];
+  args?: readonly string[];
+  maxToolCalls: number;
+  requireToolCall: boolean;
+  incoming: IncomingMeta;
+  deps?: ClineAcpDeps;
+}
+
+function unsupportedModel(modelId: string): ClineAcpError {
+  return new ClineAcpError(
+    `Cline ACP cannot select model "${modelId}".`,
+    400,
+    "invalid_request_error",
+    "cline_model_unsupported",
+    false,
+    false,
+  );
+}
+
+export async function applyClineAcpModel(client: ClineAcpClient, session: ClineAcpSessionInfo, modelId: string): Promise<void> {
+  if (modelId === "default") return;
+  if (session.availableModels.length > 0) {
+    if (!session.availableModels.some(model => model.modelId === modelId)) throw unsupportedModel(modelId);
+    try {
+      await client.setModel(session.sessionId, modelId);
+      return;
+    } catch (error) {
+      if (error instanceof ClineAcpError && error.code === "timeout") throw error;
+      throw unsupportedModel(modelId);
+    }
+  }
+  const option = session.modelConfigOption;
+  if (option?.options?.some(value => value.value === modelId)) {
+    try {
+      await client.setConfigOption(session.sessionId, option.id, modelId);
+      return;
+    } catch (error) {
+      if (error instanceof ClineAcpError && error.code === "timeout") throw error;
+      throw unsupportedModel(modelId);
+    }
+  }
+  throw unsupportedModel(modelId);
+}
+
+/** Run one ACP prompt through the shared Codex event grammar. */
+export async function runClineAcpTurn(
+  input: ClineAcpTurnInput,
+  emit: (event: AdapterEvent) => void,
+): Promise<void> {
+  const deps = input.deps ?? {};
+  const state = createClineStreamState();
+  let client: ClineAcpClient | undefined;
+  let session: ClineAcpSessionInfo | undefined;
+  let terminalEmitted = false;
+  let sawOutput = false;
+  let safetyError: string | undefined;
+  let aborted = false;
+  let timedOut = false;
+  let terminateTimer: ReturnType<typeof setTimeout> | undefined;
+  let turnTimer: ReturnType<typeof setTimeout> | undefined;
+  let permit: SingleUseDispatchPermit | undefined;
+  let producer: { close(): void } | undefined;
+  const seenToolCalls = new Set<string>();
+
+  const deliver = (event: AdapterEvent): void => {
+    if (event.type === "text_delta" || event.type === "thinking_delta"
+      || event.type === "tool_call_start" || event.type === "tool_call_delta" || event.type === "tool_call_end") {
+      sawOutput = true;
+    }
+    if (event.type === "done" || event.type === "error" || event.type === "incomplete") {
+      if (terminalEmitted) return;
+      terminalEmitted = true;
+    }
+    emit(event);
+  };
+
+  const captureTool = (toolCall: Record<string, unknown>, sessionId: string): void => {
+    const id = nonEmpty(toolCall.toolCallId, 512);
+    if (id && seenToolCalls.has(id)) return;
+    if (id) seenToolCalls.add(id);
+    const name = nonEmpty(toolCall.name, 512);
+    if (!name) {
+      safetyError ??= "Cline ACP returned an undeclared tool call.";
+      void client?.cancel(sessionId).catch(() => undefined);
+      return;
+    }
+    try {
+      const events = mapClineToolIntent(name, id, toolCall.rawInput, state, {
+        toolNames: input.toolNames,
+        maxToolCalls: input.maxToolCalls,
+      });
+      for (const event of events) deliver(event);
+    } catch (error) {
+      safetyError ??= error instanceof ClineStreamProtocolError
+        ? error.message
+        : "Cline ACP returned an invalid tool call.";
+    }
+    void client?.cancel(sessionId).catch(() => undefined);
+  };
+
+  const hooks: ClineAcpHooks = {
+    onSessionUpdate: notification => {
+      const update = notification.update;
+      if (update.sessionUpdate === "agent_message_chunk" && update.content.type === "text" && update.content.text) {
+        deliver({ type: "text_delta", text: update.content.text });
+        return;
+      }
+      if (update.sessionUpdate === "agent_thought_chunk" && update.content.type === "text" && update.content.text) {
+        deliver({ type: "thinking_delta", thinking: update.content.text });
+        return;
+      }
+      if (update.sessionUpdate === "tool_call" || update.sessionUpdate === "tool_call_update") {
+        captureTool(update as unknown as Record<string, unknown>, notification.sessionId);
+      }
+    },
+    onPermission: params => {
+      captureTool(params.toolCall as unknown as Record<string, unknown>, params.sessionId);
+    },
+  };
+
+  const onAbort = (): void => {
+    aborted = true;
+    if (session) void client?.cancel(session.sessionId).catch(() => undefined);
+    terminateTimer ??= setTimeout(() => { void client?.terminate(); }, 750);
+  };
+
+  try {
+    client = await ClineAcpClient.connect({ binary: input.binary, env: input.env, cwd: input.cwd, hooks, ...(input.args ? { args: input.args } : {}) }, deps);
+    session = await client.newSession({ cwd: input.cwd, mcpServers: input.mcpServers });
+    await applyClineAcpModel(client, session, input.modelId);
+
+    if (input.incoming.abortSignal?.aborted) {
+      deliver({
+        type: "error",
+        message: "Cline ACP turn was aborted before the prompt.",
+        status: 499,
+        errorType: "invalid_request_error",
+        code: "client_cancelled",
+        retryable: false,
+      });
+      return;
+    }
+
+    producer = input.incoming.sendBudget?.beginSpendProducer?.();
+    const decision = input.incoming.sendBudget?.reserveDispatch({
+      sendClass: "initial",
+      targetKey: `cli-agent|Cline ACP|${input.binary}`,
+    });
+    if (decision && !decision.allowed) {
+      deliver({
+        type: "error",
+        message: "Cline ACP send budget exhausted before dispatch.",
+        status: 429,
+        errorType: "rate_limit_error",
+        code: "send_budget_exhausted",
+        retryable: false,
+      });
+      return;
+    }
+    permit = decision?.allowed ? decision.permit : undefined;
+    input.incoming.beforePhysicalSend?.();
+    if (permit && !permit.use()) throw new SendBudgetExhaustedError();
+    input.incoming.onPhysicalSend?.({ ordinal: 1 });
+
+    input.incoming.abortSignal?.addEventListener("abort", onAbort, { once: true });
+    turnTimer = setTimeout(() => {
+      timedOut = true;
+      onAbort();
+    }, deps.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+
+    const response = await client.prompt(session.sessionId, input.prompt, input.incoming.abortSignal);
+
+    if (timedOut) {
+      deliver({
+        type: "error",
+        message: "Cline ACP turn timed out.",
+        status: 504,
+        errorType: "upstream_error",
+        code: "timeout",
+        retryable: true,
+      });
+    } else if (aborted) {
+      deliver({
+        type: "error",
+        message: "Cline ACP turn was cancelled.",
+        status: 499,
+        errorType: "invalid_request_error",
+        code: "client_cancelled",
+        retryable: false,
+      });
+    } else if (safetyError) {
+      deliver({
+        type: "error",
+        message: safetyError,
+        status: 502,
+        errorType: "upstream_error",
+        code: "cli_protocol_error",
+        retryable: false,
+      });
+    } else if (state.toolCalls > 0) {
+      deliver({ type: "done", stopReason: "tool_use", ...(state.usage ? { usage: state.usage } : {}) });
+    } else if (input.requireToolCall) {
+      deliver({
+        type: "error",
+        message: "Cline ACP returned no tool call for a request that requires one.",
+        status: 502,
+        errorType: "upstream_error",
+        code: "tool_call_required",
+        retryable: false,
+      });
+    } else if (response.stopReason === "end_turn") {
+      deliver({ type: "done", stopReason: "stop", ...(state.usage ? { usage: state.usage } : {}) });
+    } else if (response.stopReason === "cancelled") {
+      deliver({
+        type: "error",
+        message: "Cline ACP cancelled the turn.",
+        status: 502,
+        errorType: "upstream_error",
+        code: "acp_cancelled",
+        retryable: false,
+      });
+    } else {
+      deliver({
+        type: "error",
+        message: `Cline ACP finished with ${response.stopReason}.`,
+        status: response.stopReason === "max_tokens" ? 400 : 502,
+        errorType: response.stopReason === "max_tokens" ? "invalid_request_error" : "upstream_error",
+        code: "cli_protocol_error",
+        retryable: false,
+      });
+    }
+  } catch (error) {
+    if (error instanceof ClineAcpError && error.fallbackAllowed && !sawOutput) throw error;
+    if (!terminalEmitted) {
+      const failure = timedOut
+        ? new ClineAcpError("Cline ACP turn timed out.", 504, "upstream_error", "timeout", true, false)
+        : aborted
+          ? new ClineAcpError("Cline ACP turn was cancelled.", 499, "invalid_request_error", "client_cancelled", false, false)
+          : error instanceof ClineAcpError
+        ? error
+        : error instanceof SendBudgetExhaustedError
+          ? new ClineAcpError("Cline ACP send budget exhausted before dispatch.", 429, "rate_limit_error", "send_budget_exhausted", false, false)
+          : new ClineAcpError(
+            safeMessage(error),
+            502,
+            "upstream_error",
+            "acp_transport_error",
+            false,
+            false,
+          );
+      deliver({
+        type: "error",
+        message: failure.message,
+        status: failure.status,
+        errorType: failure.errorType,
+        code: failure.code,
+        retryable: failure.retryable,
+      });
+    }
+  } finally {
+    if (turnTimer) clearTimeout(turnTimer);
+    if (terminateTimer) clearTimeout(terminateTimer);
+    input.incoming.abortSignal?.removeEventListener("abort", onAbort);
+    try { permit?.release?.(); } catch { /* ignore */ }
+    producer?.close();
+    await client?.terminate();
+  }
+}