very-happy-cli 0.2.159 → 0.2.161

package/dist/codexAppServerClient-ZzhUTWPo.cjs

@@ -0,0 +1,1090 @@
+'use strict';
+
+var node_child_process = require('node:child_process');
+var spawn = require('cross-spawn');
+var node_readline = require('node:readline');
+var logger = require('./logger-Bc8-u1w0.cjs');
+var contentLogMetadata = require('./contentLogMetadata-ZSFk_NjQ.cjs');
+var manager = require('./manager-Cly8xVIR.cjs');
+var _package = require('./package-Cl5BEP5x.cjs');
+
+function isAppServerAvailable() {
+  try {
+    const version = node_child_process.execSync("codex --version", { encoding: "utf8", windowsHide: true }).trim();
+    const match = version.match(/codex-cli\s+(\d+\.\d+\.\d+)/);
+    if (!match) return false;
+    const [, ver] = match;
+    const [major, minor] = ver.split(".").map(Number);
+    return major > 0 || minor >= 100;
+  } catch {
+    return false;
+  }
+}
+function normalizeRawFileChangeList(changes) {
+  if (!Array.isArray(changes)) {
+    return void 0;
+  }
+  const normalized = {};
+  for (const change of changes) {
+    if (!change || typeof change !== "object" || Array.isArray(change)) {
+      continue;
+    }
+    const path = typeof change.path === "string" ? change.path : null;
+    if (!path) {
+      continue;
+    }
+    const entry = {};
+    const changeRecord = change;
+    const kind = changeRecord.kind && typeof changeRecord.kind === "object" && !Array.isArray(changeRecord.kind) ? changeRecord.kind : null;
+    const type = typeof changeRecord.type === "string" ? changeRecord.type : typeof kind?.type === "string" ? kind.type : null;
+    const movePath = changeRecord.move_path ?? kind?.move_path ?? null;
+    if (kind) {
+      entry.kind = kind;
+    } else if (type) {
+      entry.kind = { type, move_path: movePath };
+    }
+    const diff = typeof changeRecord.diff === "string" ? changeRecord.diff : typeof changeRecord.unified_diff === "string" ? changeRecord.unified_diff : null;
+    if (diff !== null) {
+      entry.diff = diff;
+    }
+    if (changeRecord.add && typeof changeRecord.add === "object" && !Array.isArray(changeRecord.add)) {
+      entry.add = changeRecord.add;
+    }
+    if (changeRecord.modify && typeof changeRecord.modify === "object" && !Array.isArray(changeRecord.modify)) {
+      entry.modify = changeRecord.modify;
+    }
+    if (changeRecord.delete && typeof changeRecord.delete === "object" && !Array.isArray(changeRecord.delete)) {
+      entry.delete = changeRecord.delete;
+    }
+    const content = typeof changeRecord.content === "string" ? changeRecord.content : null;
+    if (type === "add" && content !== null) {
+      entry.add = { content };
+    }
+    if (type === "delete" && content !== null) {
+      entry.delete = { content };
+    }
+    const oldContent = typeof changeRecord.oldContent === "string" ? changeRecord.oldContent : typeof changeRecord.old_content === "string" ? changeRecord.old_content : null;
+    const newContent = typeof changeRecord.newContent === "string" ? changeRecord.newContent : typeof changeRecord.new_content === "string" ? changeRecord.new_content : null;
+    if ((oldContent !== null || newContent !== null) && type !== "add" && type !== "delete") {
+      entry.modify = {
+        old_content: oldContent ?? "",
+        new_content: newContent ?? ""
+      };
+    }
+    normalized[path] = entry;
+  }
+  return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+class CodexAppServerClient {
+  process = null;
+  readline = null;
+  nextId = 1;
+  pending = /* @__PURE__ */ new Map();
+  processEpoch = 0;
+  connected = false;
+  sandboxConfig;
+  sandboxCleanup = null;
+  sandboxEnabled = false;
+  // Session state
+  _threadId = null;
+  _turnId = null;
+  threadDefaults = null;
+  // Turn completion tracking for the currently active sendTurnAndWait call.
+  // A completion event only resolves once we have seen task_started for this turn.
+  pendingTurnCompletion = null;
+  // Tracks in-flight interruptTurn() RPCs so sendTurnAndWait can wait for them
+  // before starting a new turn (prevents stale turn/interrupt from aborting the next turn).
+  pendingInterrupt = null;
+  // In-flight idle release (B-461); ensureConnected() waits for it so a message
+  // arriving mid-release cannot spawn a second app-server against a dying one.
+  idleRelease = null;
+  notificationProtocol = "unknown";
+  completedTurnIds = /* @__PURE__ */ new Set();
+  rawFileChangesByItemId = /* @__PURE__ */ new Map();
+  // Handlers set by the consumer (runCodex.ts)
+  eventHandler = null;
+  approvalHandler = null;
+  constructor(sandboxConfig) {
+    this.sandboxConfig = sandboxConfig;
+  }
+  get threadId() {
+    return this._threadId;
+  }
+  get turnId() {
+    return this._turnId;
+  }
+  setEventHandler(handler) {
+    this.eventHandler = handler;
+  }
+  setApprovalHandler(handler) {
+    this.approvalHandler = handler;
+  }
+  extractTurnId(params) {
+    const turnId = params?.turn?.id ?? params?.turnId ?? params?.turn_id ?? null;
+    return typeof turnId === "string" && turnId.length > 0 ? turnId : null;
+  }
+  extractTurnStatus(params) {
+    const status = params?.turn?.status ?? params?.status ?? null;
+    return typeof status === "string" && status.length > 0 ? status : null;
+  }
+  shouldHandleRawNotification(method) {
+    const isRawNotification = method === "thread/started" || method === "turn/started" || method === "turn/completed" || method === "thread/status/changed" || method === "thread/tokenUsage/updated" || method.startsWith("item/");
+    if (!isRawNotification) {
+      return false;
+    }
+    if (this.notificationProtocol === "legacy") {
+      return false;
+    }
+    if (this.notificationProtocol === "unknown") {
+      this.notificationProtocol = "raw";
+    }
+    return true;
+  }
+  emitRawTurnCompletion(turnId, status, error, source) {
+    const aborted = status === "cancelled" || status === "canceled" || status === "aborted" || status === "interrupted";
+    this.tryResolvePendingTurn(aborted, turnId, source);
+    this._turnId = null;
+    if (turnId && this.completedTurnIds.has(turnId)) {
+      return;
+    }
+    if (turnId) {
+      this.completedTurnIds.add(turnId);
+    }
+    if (aborted) {
+      this.eventHandler?.({
+        type: "turn_aborted",
+        ...turnId ? { turn_id: turnId } : {},
+        ...status ? { status } : {},
+        ...error !== void 0 && error !== null ? { error } : {}
+      });
+      return;
+    }
+    this.eventHandler?.({
+      type: "task_complete",
+      ...turnId ? { turn_id: turnId } : {},
+      ...status ? { status } : {},
+      ...error !== void 0 && error !== null ? { error } : {}
+    });
+  }
+  handleRawNotification(method, params) {
+    if (!this.shouldHandleRawNotification(method)) {
+      return false;
+    }
+    if (method === "turn/started") {
+      const turnId = this.extractTurnId(params);
+      if (turnId) {
+        this._turnId = turnId;
+      }
+      this.markPendingTurnStarted(turnId);
+      this.eventHandler?.({
+        type: "task_started",
+        ...turnId ? { turn_id: turnId } : {}
+      });
+      return true;
+    }
+    if (method === "turn/completed") {
+      this.emitRawTurnCompletion(
+        this.extractTurnId(params),
+        this.extractTurnStatus(params),
+        params?.turn?.error ?? params?.error,
+        method
+      );
+      return true;
+    }
+    if (method === "thread/status/changed") {
+      const statusType = params?.status?.type;
+      if (statusType === "idle" && this.pendingTurnCompletion) {
+        this.emitRawTurnCompletion(this._turnId, "completed", null, method);
+      }
+      return true;
+    }
+    if (method === "thread/tokenUsage/updated") {
+      const tokenUsage = params?.tokenUsage;
+      if (tokenUsage && typeof tokenUsage === "object") {
+        this.eventHandler?.({
+          type: "token_count",
+          ...tokenUsage
+        });
+      }
+      return true;
+    }
+    const item = params?.item;
+    if (!item || typeof item !== "object") {
+      return method.startsWith("item/");
+    }
+    if ((method === "item/started" || method === "item/completed") && (item.type === "collabAgentToolCall" || item.type === "subAgentActivity")) {
+      this.eventHandler?.({ type: "collab_agent_item", item });
+      return true;
+    }
+    if (method === "item/started" && item.type === "commandExecution") {
+      const callId = typeof item.id === "string" ? item.id : "";
+      this.eventHandler?.({
+        type: "exec_command_begin",
+        call_id: callId,
+        callId,
+        command: item.command,
+        cwd: item.cwd,
+        description: item.command
+      });
+      return true;
+    }
+    if (method === "item/completed" && item.type === "commandExecution") {
+      const callId = typeof item.id === "string" ? item.id : "";
+      this.eventHandler?.({
+        type: "exec_command_end",
+        call_id: callId,
+        callId,
+        output: item.aggregatedOutput ?? "",
+        exit_code: item.exitCode ?? null,
+        duration_ms: item.durationMs ?? null,
+        status: item.status,
+        cwd: item.cwd,
+        command: item.command
+      });
+      return true;
+    }
+    if (item.type === "fileChange") {
+      const callId = typeof item.id === "string" ? item.id : "";
+      const changes = normalizeRawFileChangeList(item.changes);
+      if (callId && changes) {
+        this.rawFileChangesByItemId.set(callId, changes);
+      }
+      if (method === "item/started") {
+        this.eventHandler?.({
+          type: "patch_apply_begin",
+          call_id: callId,
+          callId,
+          changes: changes ?? {}
+        });
+        return true;
+      }
+      if (method === "item/completed") {
+        this.eventHandler?.({
+          type: "patch_apply_end",
+          call_id: callId,
+          callId,
+          status: item.status
+        });
+        if (callId && (item.status === "completed" || item.status === "failed" || item.status === "declined")) {
+          this.rawFileChangesByItemId.delete(callId);
+        }
+        return true;
+      }
+    }
+    if (method === "item/completed" && item.type === "agentMessage") {
+      const text = typeof item.text === "string" ? item.text : "";
+      if (text.length > 0) {
+        this.eventHandler?.({
+          type: "agent_message",
+          message: text,
+          item_id: item.id,
+          phase: item.phase
+        });
+      }
+      if (item.phase === "final_answer" && this.pendingTurnCompletion) {
+        this.emitRawTurnCompletion(
+          this.extractTurnId(params),
+          "completed",
+          null,
+          `${method}:final_answer`
+        );
+      }
+      return true;
+    }
+    return method.startsWith("item/");
+  }
+  // ─── Lifecycle ──────────────────────────────────────────────
+  async connect() {
+    if (this.connected) return;
+    if (!isAppServerAvailable()) {
+      throw new Error(
+        "Codex CLI is not installed\n\nPlease install Codex CLI using one of these methods:\n\nOption 1 - npm (recommended):\n  npm install -g @openai/codex\n\nOption 2 - Homebrew (macOS):\n  brew install --cask codex\n\nAlternatively, use Claude Code:\n  very-happy claude"
+      );
+    }
+    let command = "codex";
+    let args = ["app-server", "--listen", "stdio://"];
+    this.sandboxEnabled = false;
+    if (this.sandboxConfig?.enabled && process.platform !== "win32") {
+      try {
+        this.sandboxCleanup = await manager.initializeSandbox(this.sandboxConfig, process.cwd());
+        const wrapped = await manager.wrapForMcpTransport("codex", ["app-server", "--listen", "stdio://"]);
+        command = wrapped.command;
+        args = wrapped.args;
+        this.sandboxEnabled = true;
+        logger.logger.info(`[CodexAppServer] Sandbox enabled`);
+      } catch (error) {
+        logger.logger.warn("[CodexAppServer] Failed to initialize sandbox; continuing without.", error);
+        this.sandboxCleanup = null;
+      }
+    }
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (typeof value === "string") env[key] = value;
+    }
+    const filter = "codex_core::rollout::list=off";
+    if (!env.RUST_LOG) {
+      env.RUST_LOG = filter;
+    } else if (!env.RUST_LOG.includes("codex_core::rollout::list=")) {
+      env.RUST_LOG += `,${filter}`;
+    }
+    if (this.sandboxEnabled) {
+      env.CODEX_SANDBOX = "seatbelt";
+    }
+    logger.logger.debug(`[CodexAppServer] Spawning: ${command} ${args.join(" ")}`);
+    const epoch = ++this.processEpoch;
+    const proc = spawn.spawn(command, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env,
+      windowsHide: true
+    });
+    this.process = proc;
+    proc.on("error", (err) => {
+      logger.logger.debug("[CodexAppServer] Process error:", err);
+    });
+    proc.on("exit", (code, signal) => {
+      logger.logger.debug(`[CodexAppServer] Process exited: code=${code} signal=${signal}`);
+      if (this.process !== proc || this.processEpoch !== epoch) {
+        logger.logger.debug("[CodexAppServer] Ignoring stale process exit");
+        return;
+      }
+      this.connected = false;
+      for (const [id, req] of this.pending) {
+        if (req.epoch !== epoch) continue;
+        req.reject(new Error(`Codex process exited (code=${code}) while waiting for ${req.method}`));
+        this.pending.delete(id);
+      }
+      this.resolvePendingTurn(true);
+    });
+    proc.stderr?.on("data", (chunk) => {
+      if (this.process !== proc || this.processEpoch !== epoch) return;
+      const text = chunk.toString().trim();
+      if (text) logger.logger.debug("[CodexAppServer:stderr]", contentLogMetadata.contentLogMetadata(text));
+    });
+    this.readline = node_readline.createInterface({ input: proc.stdout });
+    this.readline.on("line", (line) => {
+      if (this.process !== proc || this.processEpoch !== epoch) return;
+      this.handleLine(line, epoch);
+    });
+    const initParams = {
+      clientInfo: {
+        name: "happy-codex",
+        title: "Happy Codex Client",
+        version: _package.packageJson.version
+      },
+      capabilities: {
+        experimentalApi: true
+      }
+    };
+    await this.request("initialize", initParams);
+    this.notify("initialized");
+    this.connected = true;
+    logger.logger.debug("[CodexAppServer] Connected and initialized");
+  }
+  async disconnectInternal(opts) {
+    if (!this.connected && !this.process) return;
+    const proc = this.process;
+    const pid = proc?.pid;
+    const epoch = this.processEpoch;
+    logger.logger.debug(`[CodexAppServer] Disconnecting; pid=${pid ?? "none"}`);
+    this.readline?.close();
+    this.readline = null;
+    try {
+      proc?.stdin?.end();
+      proc?.kill("SIGTERM");
+    } catch {
+    }
+    if (pid) {
+      const killTimer = setTimeout(() => {
+        try {
+          process.kill(pid, 0);
+          process.kill(pid, "SIGKILL");
+        } catch {
+        }
+      }, 2e3);
+      killTimer.unref();
+    }
+    this.process = null;
+    this.connected = false;
+    this._turnId = null;
+    this.notificationProtocol = "unknown";
+    this.completedTurnIds.clear();
+    if (!opts?.preserveThreadState) {
+      this._threadId = null;
+      this.threadDefaults = null;
+    }
+    for (const [id, req] of this.pending) {
+      if (req.epoch !== epoch) continue;
+      req.reject(new Error(`Codex process disconnected while waiting for ${req.method}`));
+      this.pending.delete(id);
+    }
+    this.resolvePendingTurn(true);
+    if (this.sandboxCleanup) {
+      try {
+        await this.sandboxCleanup();
+      } catch {
+      }
+      this.sandboxCleanup = null;
+    }
+    this.sandboxEnabled = false;
+    logger.logger.debug("[CodexAppServer] Disconnected");
+  }
+  async disconnect() {
+    await this.disconnectInternal();
+  }
+  /** True while an app-server child process is owned by this client. */
+  get hasProcess() {
+    return this.process !== null;
+  }
+  /**
+   * Drop the app-server process while the session is idle, keeping the thread
+   * id and defaults so the next turn can `thread/resume` it (B-461). Refuses —
+   * returning false — whenever anything is still in flight: an active turn, a
+   * pending interrupt, or any outstanding RPC. See codexIdleRelease.ts.
+   */
+  async releaseIdleProcess() {
+    if (this.idleRelease) return this.idleRelease;
+    if (!this.connected && !this.process) return false;
+    if (this.pendingTurnCompletion || this.pendingInterrupt || this.pending.size > 0) {
+      logger.logger.debug("[CodexAppServer] Idle release skipped: work still in flight");
+      return false;
+    }
+    const run = (async () => {
+      const threadId = this._threadId;
+      logger.logger.debug(`[CodexAppServer] Releasing idle app-server; thread=${threadId ?? "none"} kept for resume`);
+      await this.disconnectInternal({ preserveThreadState: !!threadId });
+      return true;
+    })();
+    this.idleRelease = run;
+    try {
+      return await run;
+    } finally {
+      if (this.idleRelease === run) this.idleRelease = null;
+    }
+  }
+  /**
+   * Make sure an app-server is running and, if a thread is remembered, resumed
+   * in it. Cheap no-op while connected. Covers both the idle release above and
+   * an app-server that exited on its own between turns.
+   */
+  async ensureConnected() {
+    if (this.idleRelease) await this.idleRelease;
+    if (this.connected) return;
+    const threadId = this._threadId;
+    if (this.process) {
+      await this.disconnectInternal({ preserveThreadState: !!threadId });
+    }
+    await this.connect();
+    if (threadId) {
+      await this.resumeThread({ threadId });
+    }
+  }
+  buildThreadConfig(mcpServers) {
+    return mcpServers ? { mcp_servers: mcpServers } : null;
+  }
+  rememberThreadDefaults(opts) {
+    this.threadDefaults = {
+      model: opts.model,
+      cwd: opts.cwd,
+      approvalPolicy: opts.approvalPolicy,
+      sandbox: opts.sandbox,
+      mcpServers: opts.mcpServers
+    };
+  }
+  // ─── Thread management ──────────────────────────────────────
+  async startThread(opts) {
+    await this.ensureConnected();
+    const params = {
+      model: opts.model ?? null,
+      modelProvider: null,
+      profile: null,
+      cwd: opts.cwd ?? process.cwd(),
+      approvalPolicy: opts.approvalPolicy ?? null,
+      sandbox: opts.sandbox ?? null,
+      config: this.buildThreadConfig(opts.mcpServers),
+      baseInstructions: null,
+      developerInstructions: null,
+      compactPrompt: null,
+      includeApplyPatchTool: null,
+      experimentalRawEvents: false,
+      persistExtendedHistory: true
+    };
+    const result = await this.request("thread/start", params);
+    this._threadId = result.thread.id;
+    this._turnId = null;
+    this.rememberThreadDefaults(opts);
+    logger.logger.debug("[CodexAppServer] Thread started:", this._threadId);
+    return { threadId: result.thread.id, model: result.model };
+  }
+  async resumeThread(opts) {
+    const threadId = opts?.threadId ?? this._threadId;
+    if (!threadId) {
+      throw new Error("No thread available to resume.");
+    }
+    await this.ensureConnected();
+    const defaults = this.threadDefaults ?? {};
+    const params = {
+      threadId,
+      model: opts?.model ?? defaults.model ?? null,
+      modelProvider: null,
+      cwd: opts?.cwd ?? defaults.cwd ?? process.cwd(),
+      approvalPolicy: opts?.approvalPolicy ?? defaults.approvalPolicy ?? null,
+      sandbox: opts?.sandbox ?? defaults.sandbox ?? null,
+      config: this.buildThreadConfig(opts?.mcpServers ?? defaults.mcpServers),
+      baseInstructions: null,
+      developerInstructions: null,
+      persistExtendedHistory: true
+    };
+    const result = await this.request("thread/resume", params);
+    this._threadId = result.thread.id;
+    this._turnId = null;
+    this.rememberThreadDefaults({
+      model: opts?.model ?? defaults.model,
+      cwd: opts?.cwd ?? defaults.cwd,
+      approvalPolicy: opts?.approvalPolicy ?? defaults.approvalPolicy,
+      sandbox: opts?.sandbox ?? defaults.sandbox,
+      mcpServers: opts?.mcpServers ?? defaults.mcpServers
+    });
+    logger.logger.debug("[CodexAppServer] Thread resumed:", this._threadId);
+    return { threadId: result.thread.id, model: result.model };
+  }
+  async forkThread(opts) {
+    await this.ensureConnected();
+    const defaults = this.threadDefaults ?? {};
+    const params = {
+      threadId: opts.threadId,
+      model: opts.model ?? defaults.model ?? null,
+      modelProvider: null,
+      cwd: opts.cwd ?? defaults.cwd ?? process.cwd(),
+      approvalPolicy: opts.approvalPolicy ?? defaults.approvalPolicy ?? null,
+      sandbox: opts.sandbox ?? defaults.sandbox ?? null,
+      config: this.buildThreadConfig(opts.mcpServers ?? defaults.mcpServers),
+      baseInstructions: null,
+      developerInstructions: null,
+      ephemeral: false,
+      threadSource: null
+    };
+    const result = await this.request("thread/fork", params);
+    this._threadId = result.thread.id;
+    this._turnId = null;
+    this.rememberThreadDefaults({
+      model: opts.model ?? defaults.model,
+      cwd: opts.cwd ?? defaults.cwd,
+      approvalPolicy: opts.approvalPolicy ?? defaults.approvalPolicy,
+      sandbox: opts.sandbox ?? defaults.sandbox,
+      mcpServers: opts.mcpServers ?? defaults.mcpServers
+    });
+    logger.logger.debug("[CodexAppServer] Thread forked:", opts.threadId, "->", this._threadId);
+    return { threadId: result.thread.id, model: result.model, thread: result.thread };
+  }
+  async readThread(opts) {
+    await this.ensureConnected();
+    const params = {
+      threadId: opts.threadId,
+      includeTurns: opts.includeTurns ?? true
+    };
+    return await this.request("thread/read", params);
+  }
+  async rollbackThread(opts) {
+    await this.ensureConnected();
+    const params = {
+      threadId: opts.threadId,
+      numTurns: opts.numTurns
+    };
+    return await this.request("thread/rollback", params);
+  }
+  async injectItems(opts) {
+    await this.ensureConnected();
+    const params = {
+      threadId: opts.threadId,
+      items: opts.items
+    };
+    return await this.request("thread/inject_items", params);
+  }
+  async reconnectAndResumeThread() {
+    const threadId = this._threadId;
+    await this.disconnectInternal({ preserveThreadState: !!threadId });
+    await this.connect();
+    if (!threadId) {
+      return false;
+    }
+    try {
+      await this.resumeThread({ threadId });
+      return true;
+    } catch (error) {
+      logger.logger.warn("[CodexAppServer] Failed to resume thread after reconnect", error);
+      this._threadId = null;
+      this.threadDefaults = null;
+      return false;
+    }
+  }
+  // ─── Turn management ────────────────────────────────────────
+  /** Default grace period after interrupt before forcing a restart (ms). */
+  static ABORT_GRACE_MS = 3e3;
+  hasPendingTurnCompletion() {
+    return this.pendingTurnCompletion !== null;
+  }
+  resolvePendingTurn(aborted) {
+    if (!this.pendingTurnCompletion) return;
+    this.pendingTurnCompletion.resolve(aborted);
+    this.pendingTurnCompletion = null;
+  }
+  markPendingTurnStarted(turnId) {
+    if (!this.pendingTurnCompletion) return;
+    if (turnId) {
+      this.pendingTurnCompletion.turnId = turnId;
+    }
+  }
+  tryResolvePendingTurn(aborted, turnId, source) {
+    const pending = this.pendingTurnCompletion;
+    if (!pending) return;
+    if (pending.turnId && turnId && pending.turnId !== turnId) {
+      logger.logger.debug(
+        `[CodexAppServer] Ignoring ${source} for turn ${turnId}; awaiting ${pending.turnId}`
+      );
+      return;
+    }
+    this.resolvePendingTurn(aborted);
+  }
+  async waitForTurnCompletion(timeoutMs) {
+    if (!this.hasPendingTurnCompletion()) {
+      return true;
+    }
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    while (this.hasPendingTurnCompletion()) {
+      if (Date.now() >= deadline) {
+        return false;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    return true;
+  }
+  /**
+   * Request turn interruption and optionally force-restart the app-server if
+   * the turn does not settle within a short grace period.
+   */
+  async abortTurnWithFallback(opts) {
+    const hadActiveTurn = this.hasPendingTurnCompletion();
+    if (!hadActiveTurn) {
+      return { hadActiveTurn: false, aborted: false, forcedRestart: false, resumedThread: false };
+    }
+    await this.interruptTurn();
+    const gracePeriodMs = opts?.gracePeriodMs ?? CodexAppServerClient.ABORT_GRACE_MS;
+    const settled = await this.waitForTurnCompletion(gracePeriodMs);
+    if (settled) {
+      return { hadActiveTurn: true, aborted: true, forcedRestart: false, resumedThread: false };
+    }
+    const shouldForceRestart = opts?.forceRestartOnTimeout ?? true;
+    if (!shouldForceRestart) {
+      return { hadActiveTurn: true, aborted: false, forcedRestart: false, resumedThread: false };
+    }
+    logger.logger.warn(`[CodexAppServer] interrupt did not settle turn in ${gracePeriodMs}ms; force-restarting app-server`);
+    const pendingTurnId = this.pendingTurnCompletion?.turnId ?? this._turnId;
+    if (this.pendingTurnCompletion) {
+      this.eventHandler?.({
+        type: "turn_aborted",
+        reason: "interrupted",
+        ...pendingTurnId ? { turn_id: pendingTurnId } : {},
+        forced_restart: true
+      });
+    }
+    const resumedThread = await this.reconnectAndResumeThread();
+    return { hadActiveTurn: true, aborted: true, forcedRestart: true, resumedThread };
+  }
+  /**
+   * Send a user turn and wait for it to complete.
+   * Returns when task_complete or turn_aborted is received.
+   */
+  async sendTurn(prompt, opts) {
+    if (!this._threadId) {
+      throw new Error("No active thread. Call startThread first.");
+    }
+    await this.ensureConnected();
+    const input = [
+      { type: "text", text: prompt },
+      ...(opts?.images ?? []).map((path) => ({ type: "localImage", path }))
+    ];
+    const params = {
+      threadId: this._threadId,
+      input
+    };
+    if (opts?.cwd) params.cwd = opts.cwd;
+    if (opts?.approvalPolicy) params.approvalPolicy = opts.approvalPolicy;
+    if (opts?.model) params.model = opts.model;
+    if (opts?.effort) params.effort = opts.effort;
+    if (opts?.sandbox) {
+      switch (opts.sandbox) {
+        case "workspace-write":
+          params.sandboxPolicy = { type: "workspaceWrite" };
+          break;
+        case "danger-full-access":
+          params.sandboxPolicy = { type: "dangerFullAccess" };
+          break;
+        case "read-only":
+          params.sandboxPolicy = { type: "readOnly" };
+          break;
+      }
+    }
+    const result = await this.request("turn/start", params);
+    const turnId = result?.turn?.id;
+    if (typeof turnId === "string" && turnId.length > 0) {
+      this._turnId = turnId;
+      if (this.pendingTurnCompletion) {
+        this.pendingTurnCompletion.turnId = turnId;
+      }
+    }
+  }
+  /** Default timeout for waiting on turn completion (ms). 10 minutes. */
+  static TURN_TIMEOUT_MS = 10 * 60 * 1e3;
+  /**
+   * Send a user turn and wait for it to complete (task_complete or turn_aborted).
+   * Returns { aborted: true } if the turn was aborted (user cancel, permission reject, etc.).
+   */
+  async sendTurnAndWait(prompt, opts) {
+    if (this.pendingInterrupt) {
+      await this.pendingInterrupt;
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    await this.ensureConnected();
+    const timeoutMs = opts?.turnTimeoutMs ?? CodexAppServerClient.TURN_TIMEOUT_MS;
+    let timer = null;
+    const completion = new Promise((resolve) => {
+      this.pendingTurnCompletion = {
+        resolve,
+        turnId: null
+      };
+      timer = setTimeout(() => {
+        if (this.pendingTurnCompletion) {
+          logger.logger.warn(`[CodexAppServer] Turn timed out after ${timeoutMs}ms \u2014 treating as abort`);
+          this.resolvePendingTurn(true);
+        }
+      }, timeoutMs);
+    });
+    try {
+      await this.sendTurn(prompt, opts);
+    } catch (err) {
+      if (timer) clearTimeout(timer);
+      this.pendingTurnCompletion = null;
+      throw err;
+    }
+    const aborted = await completion;
+    if (timer) clearTimeout(timer);
+    return { aborted };
+  }
+  async interruptTurn() {
+    if (!this._threadId) return;
+    if (!this._turnId) {
+      logger.logger.debug("[CodexAppServer] interruptTurn: no active turnId, skipping");
+      return;
+    }
+    const params = {
+      threadId: this._threadId,
+      turnId: this._turnId
+    };
+    const doInterrupt = async () => {
+      try {
+        await this.request("turn/interrupt", params);
+      } catch (err) {
+        logger.logger.debug("[CodexAppServer] interruptTurn error (may be expected):", err);
+      } finally {
+        this.pendingInterrupt = null;
+      }
+    };
+    this.pendingInterrupt = doInterrupt();
+    return this.pendingInterrupt;
+  }
+  // ─── State queries ──────────────────────────────────────────
+  hasActiveThread() {
+    return this._threadId !== null;
+  }
+  clearThreadState() {
+    logger.logger.debug(
+      `[CodexAppServer] Clearing thread state: thread=${this._threadId ?? "none"} turn=${this._turnId ?? "none"}`
+    );
+    this.resolvePendingTurn(true);
+    this._threadId = null;
+    this._turnId = null;
+    this.threadDefaults = null;
+    this.completedTurnIds.clear();
+    this.rawFileChangesByItemId.clear();
+  }
+  // ─── JSON-RPC transport ─────────────────────────────────────
+  /** Default timeout for RPC requests (ms). */
+  static REQUEST_TIMEOUT_MS = 3e4;
+  async listModels() {
+    const models = [];
+    let cursor = null;
+    const seenCursors = /* @__PURE__ */ new Set();
+    do {
+      const response = await this.request("model/list", { limit: 100, cursor, includeHidden: false });
+      models.push(...response.data.filter((model) => !model.hidden));
+      cursor = response.nextCursor ?? null;
+      if (cursor && seenCursors.has(cursor)) throw new Error("Repeated model/list cursor");
+      if (cursor) seenCursors.add(cursor);
+    } while (cursor);
+    return models;
+  }
+  request(method, params, timeoutMs) {
+    const timeout = timeoutMs ?? CodexAppServerClient.REQUEST_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+      if (!this.process?.stdin?.writable) {
+        reject(new Error(`Cannot send ${method}: stdin not writable`));
+        return;
+      }
+      const id = this.nextId++;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${method} timed out after ${timeout}ms (id=${id})`));
+      }, timeout);
+      this.pending.set(id, {
+        resolve: (result) => {
+          clearTimeout(timer);
+          resolve(result);
+        },
+        reject: (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+        method,
+        epoch: this.processEpoch
+      });
+      const msg = { jsonrpc: "2.0", id, method, params };
+      const line = JSON.stringify(msg) + "\n";
+      logger.logger.debug(`[CodexAppServer] \u2192 ${method} (id=${id})`);
+      this.process.stdin.write(line);
+    });
+  }
+  notify(method, params) {
+    if (!this.process?.stdin?.writable) return;
+    const msg = { jsonrpc: "2.0", method, params };
+    this.process.stdin.write(JSON.stringify(msg) + "\n");
+    logger.logger.debug(`[CodexAppServer] \u2192 ${method} (notification)`);
+  }
+  respond(id, result) {
+    if (!this.process?.stdin?.writable) return;
+    const msg = { jsonrpc: "2.0", id, result };
+    this.process.stdin.write(JSON.stringify(msg) + "\n");
+    logger.logger.debug(`[CodexAppServer] \u2192 response (id=${id})`);
+  }
+  handleLine(line, sourceEpoch = this.processEpoch) {
+    if (sourceEpoch !== this.processEpoch) {
+      return;
+    }
+    if (!line.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      logger.logger.debug("[CodexAppServer] Non-JSON line received:", contentLogMetadata.contentLogMetadata(line));
+      return;
+    }
+    if (msg.id != null && (msg.result !== void 0 || msg.error !== void 0)) {
+      const pending = this.pending.get(msg.id);
+      if (pending) {
+        if (pending.epoch !== sourceEpoch) {
+          logger.logger.debug(`[CodexAppServer] Ignoring response from stale epoch for id=${msg.id}`);
+          return;
+        }
+        this.pending.delete(msg.id);
+        if (msg.error) {
+          pending.reject(new Error(`${pending.method}: ${msg.error.message} (code=${msg.error.code})`));
+        } else {
+          pending.resolve(msg.result);
+        }
+      }
+      return;
+    }
+    if (msg.id != null && msg.method) {
+      this.handleServerRequest(msg.id, msg.method, msg.params).catch((err) => {
+        logger.logger.debug("[CodexAppServer] Error handling server request:", contentLogMetadata.errorLogMetadata(err));
+      });
+      return;
+    }
+    if (msg.method) {
+      this.handleNotification(msg.method, msg.params);
+      return;
+    }
+    logger.logger.debug("[CodexAppServer] Unhandled message:", contentLogMetadata.contentLogMetadata(msg));
+  }
+  /**
+   * Map our internal ReviewDecision to the wire format the server expects.
+   * Server uses: accept, acceptForSession, decline, cancel
+   * Our handler uses: approved, approved_for_session, denied, abort
+   */
+  /**
+   * Map our internal ReviewDecision to the wire format codex expects.
+   * v2 methods (item/*) use: accept/acceptForSession/decline/cancel
+   * Legacy methods (execCommandApproval/applyPatchApproval) use: approved/approved_for_session/denied/abort
+   */
+  mapDecisionToWire(decision, legacy) {
+    if (typeof decision === "string") {
+      if (legacy) {
+        return decision;
+      }
+      switch (decision) {
+        case "approved":
+          return "accept";
+        case "approved_for_session":
+          return "acceptForSession";
+        case "denied":
+          return "decline";
+        case "abort":
+          return "cancel";
+        default:
+          return "decline";
+      }
+    }
+    if ("approved_execpolicy_amendment" in decision) {
+      return decision;
+    }
+    return legacy ? "denied" : "decline";
+  }
+  parseToolNameFromElicitationMessage(message) {
+    if (typeof message !== "string") {
+      return null;
+    }
+    const match = message.match(/tool "([^"]+)"/i);
+    return match?.[1] ?? null;
+  }
+  mapDecisionToMcpElicitationResponse(decision, params) {
+    if (typeof decision === "string") {
+      switch (decision) {
+        case "approved":
+        case "approved_for_session":
+          return {
+            action: "accept",
+            content: params?.mode === "form" ? {} : null,
+            _meta: null
+          };
+        case "abort":
+          return {
+            action: "cancel",
+            content: null,
+            _meta: null
+          };
+        case "denied":
+        default:
+          return {
+            action: "decline",
+            content: null,
+            _meta: null
+          };
+      }
+    }
+    return {
+      action: "decline",
+      content: null,
+      _meta: null
+    };
+  }
+  async handleServerRequest(id, method, params) {
+    if (method === "mcpServer/elicitation/request") {
+      const toolName = this.parseToolNameFromElicitationMessage(params?.message) ?? params?.serverName ?? "McpTool";
+      const decision = await this.handleApproval({
+        type: "mcp",
+        callId: `${params?.serverName ?? "mcp"}:${id}`,
+        toolName,
+        input: params?._meta?.tool_params ?? {},
+        serverName: params?.serverName,
+        message: params?.message
+      });
+      this.respond(id, this.mapDecisionToMcpElicitationResponse(decision, params));
+      return;
+    }
+    if (method === "item/commandExecution/requestApproval" || method === "execCommandApproval") {
+      const legacy = method === "execCommandApproval";
+      const callId = params.itemId ?? params.callId ?? String(id);
+      const decision = await this.handleApproval({
+        type: "exec",
+        callId,
+        command: params.command != null ? [params.command] : [],
+        cwd: params.cwd,
+        reason: params.reason
+      });
+      this.respond(id, { decision: this.mapDecisionToWire(decision, legacy) });
+      return;
+    }
+    if (method === "item/fileChange/requestApproval" || method === "applyPatchApproval") {
+      const legacy = method === "applyPatchApproval";
+      const callId = params.itemId ?? params.callId ?? String(id);
+      const decision = await this.handleApproval({
+        type: "patch",
+        callId,
+        fileChanges: params.fileChanges ?? (typeof callId === "string" ? this.rawFileChangesByItemId.get(callId) : void 0),
+        reason: params.reason
+      });
+      this.respond(id, { decision: this.mapDecisionToWire(decision, legacy) });
+      return;
+    }
+    logger.logger.debug(`[CodexAppServer] Unknown server request: ${method}`);
+    this.respond(id, {});
+  }
+  async handleApproval(params) {
+    if (this.approvalHandler) {
+      try {
+        return await this.approvalHandler(params);
+      } catch (err) {
+        logger.logger.debug("[CodexAppServer] Approval handler error:", err);
+        return "denied";
+      }
+    }
+    return "denied";
+  }
+  handleNotification(method, params) {
+    if (method === "codex/event" || method.startsWith("codex/event/")) {
+      this.notificationProtocol = "legacy";
+      const msg = params?.msg;
+      if (msg) {
+        if (msg.type === "task_started" && msg.turn_id) {
+          this._turnId = msg.turn_id;
+        }
+        if (msg.type === "task_started") {
+          this.markPendingTurnStarted(msg.turn_id ?? msg.turnId ?? null);
+        }
+        this.eventHandler?.(msg);
+        if (msg.type === "task_complete" || msg.type === "turn_aborted") {
+          const turnId = msg.turn_id ?? msg.turnId ?? null;
+          if (turnId) {
+            this.completedTurnIds.add(turnId);
+          }
+          this.tryResolvePendingTurn(
+            msg.type === "turn_aborted",
+            turnId,
+            `codex/event/${msg.type}`
+          );
+          this._turnId = null;
+        }
+      }
+      return;
+    }
+    if (this.handleRawNotification(method, params)) {
+      logger.logger.debug(`[CodexAppServer] Raw notification: ${method}`);
+      return;
+    }
+    if (method === "thread/started" || method === "turn/started" || method === "turn/completed" || method === "thread/status/changed") {
+      logger.logger.debug(`[CodexAppServer] Lifecycle notification: ${method}`);
+      if (method === "turn/started") {
+        const turnId = this.extractTurnId(params);
+        if (turnId) {
+          this._turnId = turnId;
+        }
+        this.markPendingTurnStarted(turnId);
+      }
+      if (method === "turn/completed") {
+        this.emitRawTurnCompletion(
+          this.extractTurnId(params),
+          this.extractTurnStatus(params),
+          params?.turn?.error ?? params?.error,
+          method
+        );
+      }
+      return;
+    }
+    if (method === "mcpServer/startupStatus/updated") {
+      logger.logger.debug(`[CodexAppServer] mcpServer startup status:`, params);
+      return;
+    }
+    logger.logger.debug(`[CodexAppServer] Notification: ${method}`);
+  }
+}
+
+exports.CodexAppServerClient = CodexAppServerClient;