@koreanhole/opencodex 3.0.0 → 3.2.0

package/src/adapters/cli-agent/gemini/headless.ts

@@ -0,0 +1,654 @@
+import { spawn as nodeSpawn, type ChildProcess } from "node:child_process";
+import { link, lstat, mkdir, mkdtemp, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import type { AdapterEvent, IncomingMeta, OcxUsage } from "../../../types";
+import { redactSecretString } from "../../../lib/redact";
+import { commandInvocation } from "../../../lib/win-exec";
+import { baseScopedEnv } from "../env";
+import { readJsonLines } from "../protocol";
+import type { CliAgentTurnDeps } from "../types";
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_KILL_GRACE_MS = 2_000;
+const HELP_TIMEOUT_MS = 15_000;
+const MAX_HELP_BYTES = 256 * 1024;
+const MAX_STDERR_BYTES = 8 * 1024;
+const MAX_ERROR_CHARS = 2_048;
+
+const GEMINI_SYSTEM_SETTINGS = JSON.stringify({
+  hooksConfig: { enabled: false },
+  skills: { enabled: false },
+  mcp: { excluded: ["*"] },
+  admin: {
+    secureModeEnabled: true,
+    extensions: { enabled: false },
+    skills: { enabled: false },
+  },
+}, null, 2) + "\n";
+
+const FORWARDED_ENV_KEYS = [
+  "XDG_CONFIG_HOME",
+  "XDG_CACHE_HOME",
+  "APPDATA",
+  "LOCALAPPDATA",
+  "GEMINI_API_KEY",
+  "GOOGLE_API_KEY",
+  "GOOGLE_GENAI_USE_VERTEXAI",
+  "GOOGLE_GENAI_USE_GCA",
+  "GOOGLE_CLOUD_PROJECT",
+  "GOOGLE_CLOUD_LOCATION",
+  "GOOGLE_APPLICATION_CREDENTIALS",
+  "GOOGLE_GEMINI_BASE_URL",
+  "GEMINI_API_KEY_AUTH_MECHANISM",
+  "GOOGLE_GENAI_API_VERSION",
+  "GEMINI_SYSTEM_MD",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+] as const;
+
+const AUTH_FILE_NAMES = ["oauth_creds.json", "google_accounts.json", ".env"] as const;
+
+export interface GeminiHeadlessDeps extends CliAgentTurnDeps {
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface GeminiHeadlessMode {
+  headless: boolean;
+  detail?: string;
+}
+
+interface ModeCacheEntry {
+  mtimeMs: number;
+  size: number;
+  mode: GeminiHeadlessMode;
+}
+
+const MODE_CACHE = new Map<string, ModeCacheEntry>();
+
+function nonEmpty(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function safeMessage(value: unknown, fallback: string): string {
+  const raw = typeof value === "string"
+    ? value
+    : value instanceof Error
+      ? value.message
+      : value === undefined
+        ? fallback
+        : JSON.stringify(value) ?? fallback;
+  return redactSecretString(raw).slice(0, MAX_ERROR_CHARS);
+}
+
+function optionPresent(text: string, option: string): boolean {
+  const escaped = option.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp("(?:^|\\s)" + escaped + "(?:\\s|,|=|\\[|<|$)").test(text);
+}
+
+export function resetGeminiHeadlessCacheForTests(): void {
+  MODE_CACHE.clear();
+}
+
+export function geminiHeadlessEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.OPENCODEX_GEMINI_ACP?.trim() !== "0";
+}
+
+export function buildGeminiHeadlessEnv(
+  sourceEnv: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): Record<string, string> {
+  const env = baseScopedEnv(sourceEnv);
+  const realHome = nonEmpty(sourceEnv.HOME) ?? nonEmpty(sourceEnv.USERPROFILE) ?? homedir();
+  env.HOME = realHome;
+  env.USERPROFILE = realHome;
+  for (const key of FORWARDED_ENV_KEYS) {
+    const value = nonEmpty(sourceEnv[key]);
+    if (value) env[key] = value;
+  }
+  Object.assign(env, {
+    GEMINI_CLI_TRUST_WORKSPACE: "true",
+    GEMINI_CLI_NO_RELAUNCH: "1",
+    GEMINI_TELEMETRY_ENABLED: "false",
+    NO_UPDATE_NOTIFIER: "1",
+    NO_COLOR: "1",
+  });
+  if (platform === "win32") env.NODE_USE_SYSTEM_CA = "1";
+  return env;
+}
+
+export async function probeGeminiHeadlessSupport(
+  binary: string,
+  env: Record<string, string>,
+  deps: GeminiHeadlessDeps = {},
+): Promise<GeminiHeadlessMode> {
+  if (!geminiHeadlessEnabled(deps.env ?? process.env)) {
+    return { headless: false, detail: "Gemini provider is disabled by OPENCODEX_GEMINI_ACP=0." };
+  }
+  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 { headless: false, detail: "Gemini CLI binary was not found." };
+  }
+  const cached = MODE_CACHE.get(key);
+  if (cached && cached.mtimeMs === mtimeMs && cached.size === size) return cached.mode;
+  const help = await runGeminiHelp(binary, env, deps);
+  const supported = optionPresent(help, "--prompt")
+    && optionPresent(help, "--output-format")
+    && optionPresent(help, "--skip-trust")
+    && optionPresent(help, "--approval-mode");
+  const mode: GeminiHeadlessMode = supported
+    ? { headless: true }
+    : { headless: false, detail: "Gemini --help does not advertise -p/--prompt, --output-format, --skip-trust, and --approval-mode." };
+  MODE_CACHE.set(key, { mtimeMs: mtimeMs!, size: size!, mode });
+  return mode;
+}
+
+async function runGeminiHelp(
+  binary: string,
+  env: Record<string, string>,
+  deps: CliAgentTurnDeps,
+): Promise<string> {
+  return await new Promise((resolvePromise, reject) => {
+    const invocation = commandInvocation(binary, ["--help"], deps.platform ?? process.platform, { env });
+    const spawnFn = deps.spawn ?? (nodeSpawn as unknown as NonNullable<CliAgentTurnDeps["spawn"]>);
+    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("Gemini --help probe timed out.")));
+    }, deps.timeoutMs ?? HELP_TIMEOUT_MS);
+    const collect = (chunk: Buffer): void => {
+      if (bytes >= MAX_HELP_BYTES) return;
+      const admitted = chunk.subarray(0, MAX_HELP_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(""))));
+  });
+}
+
+export interface GeminiHeadlessWorkspace {
+  root: string;
+  geminiHome: string;
+  settingsPath: string;
+  cleanup: () => Promise<void>;
+}
+
+export interface GeminiReasoningSelection {
+  modelId: string;
+  thinkingConfig: {
+    thinkingLevel?: string;
+    thinkingBudget?: number;
+    includeThoughts?: boolean;
+  };
+}
+
+function geminiSystemSettings(reasoning?: GeminiReasoningSelection): string {
+  const settings = JSON.parse(GEMINI_SYSTEM_SETTINGS) as Record<string, unknown>;
+  if (reasoning) {
+    settings.modelConfigs = {
+      customOverrides: [{
+        match: { model: reasoning.modelId },
+        modelConfig: {
+          generateContentConfig: {
+            thinkingConfig: reasoning.thinkingConfig,
+          },
+        },
+      }],
+    };
+  }
+  return `${JSON.stringify(settings, null, 2)}\n`;
+}
+
+export async function stageGeminiHeadlessWorkspace(
+  reasoning?: GeminiReasoningSelection,
+  options: {
+    root?: string;
+    sourceEnv?: NodeJS.ProcessEnv;
+  } = {},
+): Promise<GeminiHeadlessWorkspace> {
+  const root = options.root ?? await mkdtemp(join(tmpdir(), "ocx-gemini-headless-"));
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const geminiHome = join(root, "gemini-home");
+  const settingsPath = join(root, "settings.json");
+  const geminiConfigDir = join(geminiHome, ".gemini");
+  const exclusive = options.root === undefined;
+  const writeOptions = { encoding: "utf8" as const, mode: 0o600, ...(exclusive ? { flag: "wx" as const } : {}) };
+  await Promise.all([
+    mkdir(geminiConfigDir, { recursive: true, mode: 0o700 }),
+    writeFile(settingsPath, geminiSystemSettings(reasoning), writeOptions),
+  ]);
+  await linkGeminiAuth(geminiConfigDir, options.sourceEnv ?? process.env);
+  return {
+    root,
+    geminiHome,
+    settingsPath,
+    cleanup: async () => { await rm(root, { recursive: true, force: true }).catch(() => undefined); },
+  };
+}
+
+async function linkGeminiAuth(targetDir: string, sourceEnv: NodeJS.ProcessEnv): Promise<void> {
+  const realHome = nonEmpty(sourceEnv.HOME) ?? nonEmpty(sourceEnv.USERPROFILE) ?? homedir();
+  const realGemini = join(realHome, ".gemini");
+  await Promise.all(AUTH_FILE_NAMES.map(async name => {
+    const target = join(realGemini, name);
+    try {
+      await lstat(target);
+    } catch {
+      return;
+    }
+    const path = join(targetDir, name);
+    try {
+      await symlink(resolve(target), path);
+    } catch {
+      try {
+        await link(resolve(target), path);
+      } catch {
+        // Best-effort; environment-provided auth remains the primary contract.
+      }
+    }
+  }));
+}
+
+export interface GeminiHeadlessArgsInput {
+  modelId?: string;
+  resumeSessionId?: string;
+}
+
+export function geminiHeadlessArgs(input: GeminiHeadlessArgsInput = {}): string[] {
+  const args = [
+    "-p", "",
+    "--output-format", "stream-json",
+    "--skip-trust",
+    "--approval-mode", "auto_edit",
+    "-e", "none",
+  ];
+  if (input.modelId && input.modelId !== "default") args.push("--model", input.modelId);
+  if (input.resumeSessionId) args.push("--resume", input.resumeSessionId);
+  return args;
+}
+
+export interface GeminiHeadlessTurnInput {
+  binary: string;
+  env: Record<string, string>;
+  cwd: string;
+  args: readonly string[];
+  modelId: string;
+  prompt: string;
+  deltaPrompt?: string;
+  resumeSessionId?: string;
+  sessionKeySource?: string;
+  hadPreviousResponseId?: boolean;
+  incoming: IncomingMeta;
+  onVendorSession?: (sessionId: string) => void;
+  onResumeFailed?: () => void;
+  deps?: CliAgentTurnDeps;
+}
+
+interface AttemptResult {
+  terminal: Extract<AdapterEvent, { type: "done" | "error" | "incomplete" }>;
+  sessionId?: string;
+  sawText: boolean;
+  resumeFailed: boolean;
+}
+
+function usageFromStats(value: unknown, modelId?: string): OcxUsage | undefined {
+  const stats = asRecord(value);
+  if (!stats) return undefined;
+  const count = (input: unknown): number =>
+    typeof input === "number" && Number.isFinite(input) && input >= 0 ? Math.floor(input) : 0;
+  const inputTokens = count(stats.input_tokens ?? stats.inputTokens);
+  const outputTokens = count(stats.output_tokens ?? stats.outputTokens);
+  const cached = count(stats.cached ?? stats.cached_tokens ?? stats.cachedTokens);
+  const totalTokens = count(stats.total_tokens ?? stats.totalTokens) || inputTokens + outputTokens;
+  if (inputTokens === 0 && outputTokens === 0 && cached === 0) return undefined;
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    ...(modelId ? { modelId } : {}),
+    ...(cached > 0 ? { cachedInputTokens: cached, cacheReadInputTokens: cached } : {}),
+  };
+}
+
+function classifyError(message: string): { status: number; errorType: string; code: string; retryable: boolean } {
+  if (/session.*(?:not found|unknown|invalid|expired)|resume.*(?:not found|failed|invalid)/i.test(message)) {
+    return { status: 502, errorType: "upstream_error", code: "gemini_session_resume_failed", retryable: false };
+  }
+  if (/not logged in|please (?:run )?\/?login|sign in|authentication (?:failed|required)|unauthorized|invalid (?:api )?key/i.test(message)) {
+    return { status: 401, errorType: "authentication_error", code: "gemini_cli_not_logged_in", retryable: false };
+  }
+  if (/rate limit|too many requests|quota|credit|usage limit|daily limit/i.test(message)) {
+    return { status: 429, errorType: "rate_limit_error", code: "rate_limit_exceeded", retryable: true };
+  }
+  if (/model (?:is )?(?:not found|unavailable|unsupported)|invalid model/i.test(message)) {
+    return { status: 400, errorType: "invalid_request_error", code: "model_not_found", retryable: false };
+  }
+  return { status: 502, errorType: "upstream_error", code: "cli_protocol_error", retryable: false };
+}
+
+function errorEvent(error: unknown): Extract<AdapterEvent, { type: "error" }> {
+  const message = safeMessage(error, "Gemini headless turn failed.");
+  return { type: "error", message, ...classifyError(message) };
+}
+
+function classifyFailure(exitCode: number, stderr: string): Extract<AdapterEvent, { type: "error" }> {
+  const message = safeMessage(stderr.trim() || `Gemini headless exited with code ${exitCode}.`, "Gemini headless turn failed.");
+  return { type: "error", message, ...classifyError(message) };
+}
+
+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 });
+}
+
+async function runAttempt(
+  input: GeminiHeadlessTurnInput,
+  emit: (event: AdapterEvent) => void,
+  deps: CliAgentTurnDeps,
+  resumeSessionId: string | undefined,
+): Promise<AttemptResult> {
+  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 promptText = resumeSessionId && input.deltaPrompt ? input.deltaPrompt : input.prompt;
+  const stderr: string[] = [];
+  let stderrBytes = 0;
+  let child: ChildProcess | undefined;
+  let terminal: AttemptResult["terminal"] | undefined;
+  let sawText = false;
+  let aborted = false;
+  let timedOut = false;
+  let spawnError: Error | undefined;
+  let exitCode: number | null = null;
+  let sessionId: string | undefined;
+  let observedModel: string | undefined;
+  let usage: OcxUsage | undefined;
+  let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+  let killTimer: ReturnType<typeof setTimeout> | undefined;
+  let lifecycle: Promise<void> | undefined;
+
+  const finish = (event: AttemptResult["terminal"]): void => {
+    if (!terminal) terminal = event;
+  };
+
+  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) {
+    return {
+      terminal: {
+        type: "error",
+        message: "Gemini headless turn was cancelled.",
+        status: 499,
+        errorType: "invalid_request_error",
+        code: "client_cancelled",
+        retryable: false,
+      },
+      sawText: false,
+      resumeFailed: false,
+    };
+  }
+
+  const onAbort = (): void => {
+    if (terminal) return;
+    aborted = true;
+    kill();
+    stopStdout();
+    finish({
+      type: "error",
+      message: "Gemini headless turn was cancelled.",
+      status: 499,
+      errorType: "invalid_request_error",
+      code: "client_cancelled",
+      retryable: false,
+    });
+  };
+
+  try {
+    const args = [...input.args];
+    if (resumeSessionId) args.push("--resume", resumeSessionId);
+    const invocation = commandInvocation(input.binary, args, platform, { env: input.env });
+    child = spawnFn(invocation.file, invocation.args, {
+      ...invocation.options,
+      cwd: input.cwd,
+      env: input.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    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 (terminal) return;
+      timedOut = true;
+      kill();
+      stopStdout();
+      finish({
+        type: "error",
+        message: "Gemini headless 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.stdin) throw new Error("Gemini headless process produced no stdin stream.");
+    if (!child.stdout) throw new Error("Gemini headless process produced no stdout stream.");
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(promptText);
+
+    for await (const message of readJsonLines(child.stdout, {}, "Gemini headless")) {
+      if (terminal) break;
+      const type = asString(message.type);
+      if (type === "init") {
+        sessionId = nonEmpty(message.session_id);
+        observedModel = nonEmpty(message.model);
+        if (sessionId) input.onVendorSession?.(sessionId);
+        continue;
+      }
+      if (type === "message") {
+        if (message.role !== "assistant") continue;
+        const content = asString(message.content);
+        if (!content) continue;
+        sawText = true;
+        emit({ type: "text_delta", text: content });
+        continue;
+      }
+      if (type === "error") {
+        if (message.severity === "warning") continue;
+        const messageText = safeMessage(message.message, "Gemini headless turn failed.");
+        finish({ type: "error", message: messageText, ...classifyError(messageText) });
+        continue;
+      }
+      if (type === "result") {
+        usage = usageFromStats(message.stats, observedModel ?? (input.modelId === "default" ? undefined : input.modelId)) ?? usage;
+        if (message.status === "success") {
+          finish({ type: "done", stopReason: "stop", ...(usage ? { usage } : {}) });
+        } else {
+          const error = asRecord(message.error);
+          const messageText = safeMessage(error?.message ?? "Gemini headless turn failed.", "Gemini headless turn failed.");
+          finish({ type: "error", message: messageText, ...classifyError(messageText) });
+        }
+        continue;
+      }
+      // tool_use/tool_result are Gemini's internal native-tool records.
+    }
+
+    if (!terminal) {
+      await Promise.race([
+        lifecycle ?? Promise.resolve(),
+        new Promise<void>(resolvePromise => setTimeout(resolvePromise, reapTimeoutMs)),
+      ]);
+      if (aborted) {
+        finish({
+          type: "error",
+          message: "Gemini headless turn was cancelled.",
+          status: 499,
+          errorType: "invalid_request_error",
+          code: "client_cancelled",
+          retryable: false,
+        });
+      } else if (timedOut) {
+        finish({
+          type: "error",
+          message: "Gemini headless turn timed out.",
+          status: 504,
+          errorType: "upstream_error",
+          code: "timeout",
+          retryable: true,
+        });
+      } else if (spawnError) {
+        finish({
+          type: "error",
+          message: safeMessage(spawnError.message, "Gemini headless process failed to start."),
+          status: 500,
+          errorType: "upstream_error",
+          code: "cli_spawn_failed",
+          retryable: false,
+        });
+      } else if (exitCode !== null && exitCode !== 0) {
+        finish(classifyFailure(exitCode, stderr.join("")));
+      } else if (sawText) {
+        finish({ type: "done", stopReason: "stop", ...(usage ? { usage } : {}) });
+      } else {
+        finish({
+          type: "error",
+          message: "Gemini headless ended without a terminal result.",
+          status: 502,
+          errorType: "upstream_error",
+          code: "cli_protocol_error",
+          retryable: false,
+        });
+      }
+    }
+  } catch (error) {
+    if (!terminal) finish(errorEvent(error));
+  } finally {
+    if (timeoutTimer) clearTimeout(timeoutTimer);
+    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);
+  }
+
+  const result = terminal ?? {
+    type: "error" as const,
+    message: "Gemini headless ended without a terminal result.",
+    status: 502,
+    errorType: "upstream_error",
+    code: "cli_protocol_error",
+    retryable: false,
+  };
+  return {
+    terminal: result,
+    ...(sessionId ? { sessionId } : {}),
+    sawText,
+    resumeFailed: Boolean(resumeSessionId) && !sawText && result.type === "error" && result.code === "gemini_session_resume_failed",
+  };
+}
+
+/** Run one headless Gemini turn, retrying a stale resume as a fresh session. */
+export async function runGeminiHeadlessTurn(
+  input: GeminiHeadlessTurnInput,
+  emit: (event: AdapterEvent) => void,
+  deps?: CliAgentTurnDeps,
+): Promise<void> {
+  const effectiveDeps = deps ?? input.deps ?? {};
+  const first = await runAttempt(input, emit, effectiveDeps, input.resumeSessionId);
+  if (first.resumeFailed && input.resumeSessionId) {
+    input.onResumeFailed?.();
+    const second = await runAttempt(input, emit, effectiveDeps, undefined);
+    emit(second.terminal);
+    return;
+  }
+  emit(first.terminal);
+}