@koreanhole/opencodex 3.0.0 → 3.1.0

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

@@ -0,0 +1,652 @@
+import { spawn as nodeSpawn, type ChildProcess } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import type { AdapterEvent, IncomingMeta } from "../../../types";
+import { redactSecretString } from "../../../lib/redact";
+import { commandInvocation } from "../../../lib/win-exec";
+import { CodingAgentProtocolError, readJsonLines } from "../protocol";
+import type { CliAgentTurnDeps } from "../types";
+import { buildClineAcpEnv } from "./acp";
+import type { ClineSelection } from "./settings";
+import {
+  classifyClineFailure,
+  ClineStreamProtocolError,
+  createClineStreamState,
+  mapClineMessage,
+} from "./stream";
+
+const HELP_TIMEOUT_MS = 15_000;
+const PREFLIGHT_TIMEOUT_MS = 15_000;
+const MAX_HELP_BYTES = 256 * 1024;
+const MAX_PREFLIGHT_STDOUT_BYTES = 2 * 1024 * 1024;
+const MAX_STDERR_BYTES = 8 * 1024;
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_KILL_GRACE_MS = 2_000;
+const DEFAULT_TOOL_BATCH_IDLE_MS = 250;
+const MAX_TOOL_CALLS = 16;
+
+export class ClineJsonError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly errorType: string,
+    readonly code: string,
+    readonly retryable = false,
+  ) {
+    super(message);
+    this.name = "ClineJsonError";
+  }
+}
+
+export interface ClineJsonCapabilities {
+  json: boolean;
+  toolCatalogJson: boolean;
+  providerFlag?: "--provider";
+  modelFlag?: "--model" | "--modelid";
+  systemFlag?: "--system";
+}
+
+export interface ClineJsonTurnInput {
+  binary: string;
+  args: readonly string[];
+  env: Record<string, string>;
+  cwd: string;
+  promptFile: string;
+  toolNames: ReadonlyMap<string, string>;
+  maxToolCalls: number;
+  requireToolCall: boolean;
+  incoming: IncomingMeta;
+}
+
+export interface ClineEnabledTool {
+  id: string;
+  kind: "builtin";
+}
+
+export interface ClineToolPreflightResult {
+  ok: boolean;
+  detail?: string;
+  enabledTools?: readonly ClineEnabledTool[];
+}
+
+interface ProbeResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+interface CapabilityCacheEntry {
+  mtimeMs: number;
+  size: number;
+  capabilities: ClineJsonCapabilities;
+}
+
+const CAPABILITY_CACHE = new Map<string, CapabilityCacheEntry>();
+
+export function resetClineJsonCapabilityCacheForTests(): void {
+  CAPABILITY_CACHE.clear();
+}
+
+function optionPresent(text: string, option: string): boolean {
+  const escaped = option.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp("(?:^|\\s)" + escaped + "(?:\\s|,|=|\\[|<|$)").test(text);
+}
+
+export function parseClineJsonHelp(
+  text: string,
+  scope: "turn" | "toolCatalog" = "turn",
+): ClineJsonCapabilities {
+  const json = optionPresent(text, "--json");
+  if (scope === "toolCatalog") {
+    return { json: true, toolCatalogJson: json };
+  }
+  const providerFlag = optionPresent(text, "--provider") ? "--provider" as const : undefined;
+  const modelFlag = optionPresent(text, "--model")
+    ? "--model" as const
+    : optionPresent(text, "--modelid")
+      ? "--modelid" as const
+      : undefined;
+  const systemFlag = optionPresent(text, "--system") ? "--system" as const : undefined;
+  return {
+    json,
+    toolCatalogJson: false,
+    ...(providerFlag ? { providerFlag } : {}),
+    ...(modelFlag ? { modelFlag } : {}),
+    ...(systemFlag ? { systemFlag } : {}),
+  };
+}
+
+function redactProbeDetail(value: string): string {
+  return redactSecretString(value.trim()).slice(0, MAX_STDERR_BYTES);
+}
+
+function runProbeProcess(
+  binary: string,
+  args: readonly string[],
+  env: Record<string, string>,
+  cwd: string,
+  deps: CliAgentTurnDeps,
+  timeoutMs: number,
+  maxStdoutBytes: number,
+): Promise<ProbeResult> {
+  return new Promise((resolvePromise, reject) => {
+    const invocation = commandInvocation(binary, args, deps.platform ?? process.platform, { env });
+    const spawnFn = deps.spawn ?? (nodeSpawn as unknown as NonNullable<CliAgentTurnDeps["spawn"]>);
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let settled = false;
+    let child: ChildProcess;
+    const finish = (fn: () => void): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
+    try {
+      child = spawnFn(invocation.file, invocation.args, {
+        ...invocation.options,
+        cwd,
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    const timer = setTimeout(() => {
+      try { child.kill("SIGKILL"); } catch { /* already stopped */ }
+      finish(() => reject(new Error("Cline help probe timed out.")));
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk: Buffer) => {
+      if (stdoutBytes >= maxStdoutBytes) return;
+      const admitted = chunk.subarray(0, maxStdoutBytes - stdoutBytes);
+      stdout.push(admitted);
+      stdoutBytes += admitted.byteLength;
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      if (stderrBytes >= MAX_STDERR_BYTES) return;
+      const admitted = chunk.subarray(0, MAX_STDERR_BYTES - stderrBytes);
+      stderr.push(admitted);
+      stderrBytes += admitted.byteLength;
+    });
+    child.once("error", error => finish(() => reject(error)));
+    child.once("close", code => finish(() => resolvePromise({
+      exitCode: code ?? 1,
+      stdout: Buffer.concat(stdout).toString("utf8"),
+      stderr: Buffer.concat(stderr).toString("utf8"),
+    })));
+  });
+}
+
+function probeFailure(code: string, detail: string): ClineJsonError {
+  return new ClineJsonError(
+    "Cline capability probe failed: " + (redactProbeDetail(detail) || "no diagnostic output"),
+    502,
+    "upstream_error",
+    code,
+    false,
+  );
+}
+
+export async function probeClineJsonCapabilities(
+  binary: string,
+  env: Record<string, string> = buildClineAcpEnv(),
+  deps: CliAgentTurnDeps = {},
+): Promise<ClineJsonCapabilities> {
+  const path = resolve(binary);
+  let fingerprint: { mtimeMs: number; size: number } | undefined;
+  try {
+    const value = await stat(path);
+    fingerprint = { mtimeMs: value.mtimeMs, size: value.size };
+  } catch {
+    fingerprint = undefined;
+  }
+  if (fingerprint) {
+    const cached = CAPABILITY_CACHE.get(path);
+    if (cached && cached.mtimeMs === fingerprint.mtimeMs && cached.size === fingerprint.size) {
+      return { ...cached.capabilities };
+    }
+  }
+
+  const timeoutMs = Math.min(deps.timeoutMs ?? HELP_TIMEOUT_MS, HELP_TIMEOUT_MS);
+  let top: ProbeResult;
+  try {
+    top = await runProbeProcess(binary, ["--help"], env, homedir(), deps, timeoutMs, MAX_HELP_BYTES);
+  } catch (error) {
+    throw probeFailure("cline_help_probe_failed", error instanceof Error ? error.message : String(error));
+  }
+  if (top.exitCode !== 0) throw probeFailure("cline_help_probe_failed", top.stderr || top.stdout);
+  const turn = parseClineJsonHelp(top.stdout + "\n" + top.stderr);
+  if (!turn.json) {
+    throw new ClineJsonError(
+      "The installed Cline CLI does not advertise --json. Upgrade Cline or set CLINE_BIN_PATH to a compatible binary.",
+      400,
+      "invalid_request_error",
+      "cline_json_unsupported",
+      false,
+    );
+  }
+
+  let tools: ProbeResult;
+  try {
+    tools = await runProbeProcess(binary, ["config", "tools", "--help"], env, homedir(), deps, timeoutMs, MAX_HELP_BYTES);
+  } catch (error) {
+    throw probeFailure("cline_tool_catalog_probe_failed", error instanceof Error ? error.message : String(error));
+  }
+  if (tools.exitCode !== 0) throw probeFailure("cline_tool_catalog_probe_failed", tools.stderr || tools.stdout);
+  const toolCatalog = parseClineJsonHelp(tools.stdout + "\n" + tools.stderr, "toolCatalog");
+  if (!toolCatalog.toolCatalogJson) {
+    throw new ClineJsonError(
+      "The installed Cline CLI does not advertise config tools --json; the tool preflight cannot run safely.",
+      400,
+      "invalid_request_error",
+      "cline_tool_catalog_unsupported",
+      false,
+    );
+  }
+
+  const capabilities: ClineJsonCapabilities = {
+    ...turn,
+    toolCatalogJson: true,
+  };
+  if (fingerprint) CAPABILITY_CACHE.set(path, { ...fingerprint, capabilities: { ...capabilities } });
+  return capabilities;
+}
+
+export function buildClineJsonArgs(input: {
+  capabilities: ClineJsonCapabilities;
+  modelId: string;
+  selection?: ClineSelection;
+  systemPrompt?: string;
+  prompt: string;
+}): string[] {
+  if (!input.capabilities.json) {
+    throw new ClineJsonError("The installed Cline CLI does not advertise --json.", 400, "invalid_request_error", "cline_json_unsupported", false);
+  }
+  const args = ["--json"];
+  if (input.capabilities.providerFlag && input.selection?.providerId) {
+    args.push(input.capabilities.providerFlag, input.selection.providerId);
+  }
+  if (input.modelId !== "default") {
+    if (!input.capabilities.modelFlag) {
+      throw new ClineJsonError(
+        'The installed Cline CLI has no advertised model selector for "' + input.modelId + '".',
+        400,
+        "invalid_request_error",
+        "cline_model_flag_unsupported",
+        false,
+      );
+    }
+    args.push(input.capabilities.modelFlag, input.modelId);
+  }
+  if (input.capabilities.systemFlag && input.systemPrompt) {
+    args.push(input.capabilities.systemFlag, input.systemPrompt);
+  }
+  args.push(input.prompt);
+  return args;
+}
+
+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): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function validateClineToolCatalog(parsed: unknown): ClineToolPreflightResult {
+  if (!Array.isArray(parsed)) return { ok: false, detail: "Cline tool preflight returned a non-array catalog." };
+  const enabledTools: ClineEnabledTool[] = [];
+  let pluginDetail: string | undefined;
+  for (const item of parsed) {
+    const record = asRecord(item);
+    if (!record) continue;
+    if (record.type === "plugin") {
+      if (record.enabled === true) {
+        pluginDetail ??= "Cline enabled plugin tool " + String(record.name ?? "unknown") + ".";
+      }
+      continue;
+    }
+    if (record.defaultEnabled !== true) continue;
+    const id = nonEmpty(record.id);
+    if (!id) return { ok: false, detail: "Cline enabled a built-in tool without an id." };
+    enabledTools.push({ id, kind: "builtin" });
+  }
+  if (pluginDetail) return { ok: false, detail: pluginDetail };
+  if (enabledTools.length > 0) {
+    return {
+      ok: false,
+      detail: "Cline enabled built-in tool " + enabledTools[0]!.id + ".",
+      enabledTools,
+    };
+  }
+  return { ok: true };
+}
+
+export async function preflightClineTools(input: {
+  binary: string;
+  env: Record<string, string>;
+  cwd: string;
+  capabilities: ClineJsonCapabilities;
+  deps?: CliAgentTurnDeps;
+  timeoutMs?: number;
+}): Promise<ClineToolPreflightResult> {
+  if (!input.capabilities.toolCatalogJson) {
+    return { ok: false, detail: "The installed Cline CLI does not advertise config tools --json." };
+  }
+  let result: ProbeResult;
+  try {
+    result = await runProbeProcess(
+      input.binary,
+      ["config", "tools", "--json"],
+      input.env,
+      input.cwd,
+      input.deps ?? {},
+      input.timeoutMs ?? PREFLIGHT_TIMEOUT_MS,
+      MAX_PREFLIGHT_STDOUT_BYTES,
+    );
+  } catch (error) {
+    return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+  }
+  if (result.exitCode !== 0) {
+    return { ok: false, detail: redactProbeDetail(result.stderr) || "Cline tool preflight exited with code " + result.exitCode + "." };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    return { ok: false, detail: "Cline tool preflight returned non-JSON output." };
+  }
+  return validateClineToolCatalog(parsed);
+}
+
+function errorEvent(error: unknown): Extract<AdapterEvent, { type: "error" }> {
+  if (error instanceof ClineJsonError) {
+    return {
+      type: "error",
+      message: error.message,
+      status: error.status,
+      errorType: error.errorType,
+      code: error.code,
+      retryable: error.retryable,
+    };
+  }
+  return {
+    type: "error",
+    message: redactSecretString(error instanceof Error ? error.message : String(error)),
+    status: 502,
+    errorType: "upstream_error",
+    code: "cli_protocol_error",
+    retryable: false,
+  };
+}
+
+function killWindowsProcessTree(pid: number): void {
+  const taskkill = (process.env.SystemRoot ?? "C:\\Windows") + "\\System32\\taskkill.exe";
+  nodeSpawn(taskkill, ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+}
+
+export async function runClineJsonTurn(
+  input: ClineJsonTurnInput,
+  emit: (event: AdapterEvent) => void,
+  deps: CliAgentTurnDeps = {},
+): Promise<void> {
+  const spawnFn = deps.spawn ?? (nodeSpawn as unknown as NonNullable<CliAgentTurnDeps["spawn"]>);
+  const platform = deps.platform ?? process.platform;
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const killGraceMs = deps.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+  const reapTimeoutMs = deps.reapTimeoutMs ?? killGraceMs * 2 + 250;
+  const toolBatchIdleMs = deps.toolBatchIdleMs ?? DEFAULT_TOOL_BATCH_IDLE_MS;
+  const state = createClineStreamState();
+  const maxToolCalls = Math.min(input.maxToolCalls, MAX_TOOL_CALLS);
+  const stderr: string[] = [];
+  let stderrBytes = 0;
+  let child: ChildProcess | undefined;
+  let terminalEmitted = false;
+  let aborted = false;
+  let timedOut = false;
+  let toolBatchStopped = false;
+  let spawnError: Error | undefined;
+  let exitCode: number | null = null;
+  let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+  let killTimer: ReturnType<typeof setTimeout> | undefined;
+  let toolIdleTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const deliver = (event: AdapterEvent): void => {
+    const terminal = event.type === "done" && input.requireToolCall && state.toolCalls === 0
+      ? {
+          type: "error" as const,
+          message: "Cline returned no tool call for a request that requires one.",
+          status: 502,
+          errorType: "upstream_error",
+          code: "tool_call_required",
+          retryable: false,
+        }
+      : event;
+    if (terminal.type === "done" || terminal.type === "error" || terminal.type === "incomplete") {
+      if (terminalEmitted) return;
+      terminalEmitted = true;
+    }
+    emit(terminal);
+  };
+
+  const stopStdout = (): void => {
+    try { child?.stdout?.destroy(); } catch { /* already closed */ }
+  };
+
+  const kill = (): void => {
+    if (!child || child.killed) return;
+    if (platform === "win32" && child.pid !== undefined) {
+      try {
+        (deps.killWindowsProcessTree ?? killWindowsProcessTree)(child.pid);
+        return;
+      } catch {
+        // Fall through to the direct termination ladder.
+      }
+    }
+    try { child.kill("SIGTERM"); } catch { /* already stopped */ }
+    killTimer = setTimeout(() => {
+      try { child?.kill("SIGKILL"); } catch { /* already stopped */ }
+    }, killGraceMs);
+  };
+
+  if (input.incoming.abortSignal?.aborted) {
+    deliver({
+      type: "error",
+      message: "Cline JSON turn was cancelled.",
+      status: 499,
+      errorType: "invalid_request_error",
+      code: "client_cancelled",
+      retryable: false,
+    });
+    return;
+  }
+
+  const onAbort = (): void => {
+    if (terminalEmitted) return;
+    aborted = true;
+    kill();
+    stopStdout();
+    deliver({
+      type: "error",
+      message: "Cline JSON turn was cancelled.",
+      status: 499,
+      errorType: "invalid_request_error",
+      code: "client_cancelled",
+      retryable: false,
+    });
+  };
+
+  const armToolIdle = (): void => {
+    if (terminalEmitted || toolBatchStopped || state.toolCalls === 0) return;
+    if (toolIdleTimer) clearTimeout(toolIdleTimer);
+    toolIdleTimer = setTimeout(() => {
+      toolBatchStopped = true;
+      kill();
+    }, toolBatchIdleMs);
+  };
+
+  let lifecycle: Promise<void> | undefined;
+  try {
+    const invocation = commandInvocation(input.binary, input.args, platform, { env: input.env });
+    let stdinDescriptor: number;
+    try {
+      stdinDescriptor = openSync(input.promptFile, "r");
+    } catch {
+      deliver({
+        type: "error",
+        message: "Cline prompt could not be staged securely.",
+        status: 500,
+        errorType: "upstream_error",
+        code: "cli_prompt_staging_failed",
+        retryable: false,
+      });
+      return;
+    }
+    try {
+      child = spawnFn(invocation.file, invocation.args, {
+        ...invocation.options,
+        cwd: input.cwd,
+        env: input.env,
+        stdio: [stdinDescriptor, "pipe", "pipe"],
+        windowsHide: true,
+      });
+    } finally {
+      closeSync(stdinDescriptor);
+    }
+    lifecycle = new Promise<void>(resolvePromise => {
+      let settled = false;
+      const settle = (): void => {
+        if (settled) return;
+        settled = true;
+        resolvePromise();
+      };
+      child?.once("error", error => {
+        spawnError = error;
+        if (child?.pid === undefined) settle();
+      });
+      child?.once("close", code => {
+        exitCode = code;
+        settle();
+      });
+    });
+
+    input.incoming.abortSignal?.addEventListener("abort", onAbort, { once: true });
+    timeoutTimer = setTimeout(() => {
+      if (terminalEmitted) return;
+      timedOut = true;
+      kill();
+      stopStdout();
+      deliver({
+        type: "error",
+        message: "Cline JSON turn timed out.",
+        status: 504,
+        errorType: "upstream_error",
+        code: "timeout",
+        retryable: true,
+      });
+    }, timeoutMs);
+
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk: string) => {
+      if (stderrBytes >= MAX_STDERR_BYTES) return;
+      const remaining = MAX_STDERR_BYTES - stderrBytes;
+      const admitted = chunk.slice(0, remaining);
+      stderr.push(admitted);
+      stderrBytes += Buffer.byteLength(admitted);
+    });
+
+    if (!child.stdout) throw new Error("Cline JSON process produced no stdout stream.");
+    for await (const message of readJsonLines(child.stdout)) {
+      if (terminalEmitted) break;
+      let events: AdapterEvent[];
+      try {
+        events = mapClineMessage(message, state, {
+          toolNames: input.toolNames,
+          maxToolCalls,
+        });
+      } catch (error) {
+        if (error instanceof ClineStreamProtocolError || error instanceof CodingAgentProtocolError) {
+          deliver({
+            type: "error",
+            message: error.message,
+            status: error.status,
+            errorType: "upstream_error",
+            code: "cli_protocol_error",
+            retryable: false,
+          });
+          break;
+        }
+        throw error;
+      }
+      for (const event of events) deliver(event);
+      if (terminalEmitted) break;
+      armToolIdle();
+    }
+
+    if (!terminalEmitted && !aborted && !timedOut) {
+      await Promise.race([
+        lifecycle ?? Promise.resolve(),
+        new Promise<void>(resolvePromise => setTimeout(resolvePromise, reapTimeoutMs)),
+      ]);
+      if (state.toolCalls > 0) {
+        if (toolBatchStopped || exitCode === 0) {
+          deliver({ type: "done", stopReason: "tool_use", ...(state.usage ? { usage: state.usage } : {}) });
+        } else {
+          deliver(classifyClineFailure(exitCode ?? 1, stderr.join("")));
+        }
+      } else if (input.requireToolCall) {
+        deliver({
+          type: "error",
+          message: "Cline returned no tool call for a request that requires one.",
+          status: 502,
+          errorType: "upstream_error",
+          code: "tool_call_required",
+          retryable: false,
+        });
+      } else if (spawnError) {
+        deliver({
+          type: "error",
+          message: "Cline JSON process failed to start: " + spawnError.message,
+          status: 500,
+          errorType: "upstream_error",
+          code: "cli_spawn_failed",
+          retryable: false,
+        });
+      } else if (exitCode !== null && exitCode !== 0) {
+        deliver(classifyClineFailure(exitCode, stderr.join("")));
+      } else {
+        deliver({
+          type: "error",
+          message: "Cline JSON ended without a terminal result.",
+          status: 502,
+          errorType: "upstream_error",
+          code: "cli_protocol_error",
+          retryable: false,
+        });
+      }
+    }
+  } catch (error) {
+    if (!terminalEmitted) deliver(errorEvent(error));
+  } finally {
+    if (timeoutTimer) clearTimeout(timeoutTimer);
+    if (toolIdleTimer) clearTimeout(toolIdleTimer);
+    input.incoming.abortSignal?.removeEventListener("abort", onAbort);
+    try { child?.stdin?.destroy(); } catch { /* already closed */ }
+    if (child && child.exitCode === null && !child.killed) kill();
+    if (child && child.exitCode === null) {
+      await Promise.race([
+        lifecycle ?? new Promise<void>(resolvePromise => child?.once("close", () => resolvePromise())),
+        new Promise<void>(resolvePromise => setTimeout(resolvePromise, reapTimeoutMs)),
+      ]);
+    }
+    if (killTimer) clearTimeout(killTimer);
+  }
+}