comfyui-mcp
Version:
Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no API key), free local models via Ollama (fully offline),
1,433 lines • 73.7 kB
JavaScript
// OpenAI Codex backend — the provider-specific adapter behind the AgentBackend
// port, driving Codex over the `codex app-server` JSON-RPC protocol (NOT
// `codex exec` string-scraping). This mirrors how our own `openai-codex` plugin
// drives the app-server (see the plugin's scripts/lib/app-server.mjs +
// codex.mjs); the protocol mapping is commented inline below.
//
// PanelAgent keeps all provider-agnostic orchestration (queue, turn-gate, bridge
// push, self-restart) and drives this backend via
// `for await (const ev of backend.run({...}))`. See
// docs/design/agent-backend-injection.md.
//
// PROTOCOL MAPPING (port → app-server):
// - session = a Codex THREAD (`thread/start` new | `thread/resume` by id)
// - run() loop turn = `turn/start` (one turn per neutral channel batch);
// images ride as `localImage` input items (file paths)
// - assistant_delta ← `item/agentMessage/delta` ({itemId, delta})
// - assistant_delta(th) ← `item/reasoning/{text,summaryText}Delta` (thinking)
// - assistant (commit) ← `item/completed` for an `agentMessage` item
// - result ← `turn/completed` ({threadId, turn:{status}})
// - error ← `error` notification ({error:{message}})
// - interrupt() → `turn/interrupt` ({threadId, turnId})
// - listModels() ← `config/read` (or a sensible static fallback)
//
// FULL PARITY with Claude: the Codex backend now drives the live ComfyUI canvas
// AND the headless comfyui MCP, with the panel system prompt — everything Claude
// can do. Two MCP servers are declared to the app-server at launch via `-c`
// overrides:
// - `comfyui` (stdio): the headless comfyui MCP (this build's dist/index.js),
// mirroring the env the Claude path passes (COMFYUI_URL / COMFYUI_PATH / …).
// - `panel` (http) : the orchestrator-hosted loopback HTTP MCP that exposes
// the SHARED panel_* live-graph tools, routed by tab id
// (http://127.0.0.1:<port>/<tabId>). See panel-mcp-http.ts + panel-tools.ts.
// The app-server can only host CONFIG-DECLARED MCP servers (not an in-process SDK
// server), which is exactly why panel_* is exposed over HTTP for this backend.
// The panel system prompt is prepended to the FIRST turn (the app-server's
// thread/start has no instructions field).
import { spawn, spawnSync } from "node:child_process";
import { createRequire } from "node:module";
import { promises as fsp } from "node:fs";
import os from "node:os";
import path from "node:path";
import readline from "node:readline";
import { logger } from "../utils/logger.js";
import { errorText, promptText } from "./error-text.js";
import { buildAgentSpawnEnv } from "../services/panel-secrets.js";
import { CODEX_CAPABILITIES, } from "./agent-backend.js";
function msgOf(err) {
return errorText(err);
}
const configuredInterruptTimeoutMs = Number(process.env.COMFYUI_MCP_CODEX_INTERRUPT_TIMEOUT_MS);
const CODEX_INTERRUPT_TIMEOUT_MS = Number.isFinite(configuredInterruptTimeoutMs) && configuredInterruptTimeoutMs > 0
? configuredInterruptTimeoutMs
: 1500;
const configuredCloseTimeoutMs = Number(process.env.COMFYUI_MCP_CODEX_CLOSE_TIMEOUT_MS);
const CODEX_CLOSE_TIMEOUT_MS = Number.isFinite(configuredCloseTimeoutMs) && configuredCloseTimeoutMs > 0
? configuredCloseTimeoutMs
: 2000;
const configuredForceKillGraceMs = Number(process.env.COMFYUI_MCP_CODEX_FORCE_KILL_GRACE_MS);
const CODEX_FORCE_KILL_GRACE_MS = Number.isFinite(configuredForceKillGraceMs) && configuredForceKillGraceMs > 0
? configuredForceKillGraceMs
: 500;
const CODEX_CLIENT_CLOSE_BUDGET_MS = CODEX_CLOSE_TIMEOUT_MS * 2 + CODEX_FORCE_KILL_GRACE_MS + 100;
async function settlesWithin(promise, timeoutMs) {
let timer;
try {
return await Promise.race([
promise.then(() => true, () => true),
new Promise((resolve) => {
timer = setTimeout(() => resolve(false), timeoutMs);
}),
]);
}
finally {
if (timer)
clearTimeout(timer);
}
}
/**
* Kill an entire process tree, not just the direct child. On the Windows
* PATH/shell fallback the direct child is a cmd.exe/shim whose grandchild is the
* real `codex` node process — killing only the shell leaves the tree alive. Use
* `taskkill /T /F` (mirrors the reference client's terminateProcessTree). On
* POSIX, signal the process group (negative pid) so a shell + its child both die,
* falling back to the single pid. Best-effort + swallows errors: it runs during
* teardown and must never throw into the host process.
*/
function killProcessTree(pid, force = false) {
if (!Number.isFinite(pid))
return false;
const p = pid;
if (process.platform === "win32") {
try {
const result = spawnSync("taskkill", ["/PID", String(p), "/T", "/F"], {
windowsHide: true,
timeout: CODEX_CLOSE_TIMEOUT_MS,
});
if (!result.error && result.status === 0)
return true;
}
catch {
// Fall through to the direct-pid kill below.
}
try {
process.kill(p, "SIGKILL");
return true;
}
catch {
return false; // already gone or inaccessible
}
}
const signal = force ? "SIGKILL" : "SIGTERM";
try {
process.kill(-p, signal); // process group (we spawn detached on POSIX)
return true;
}
catch {
try {
process.kill(p, signal);
return true;
}
catch {
return false; // already gone or inaccessible
}
}
}
class AppServerClient {
bin;
cwd;
env;
extraArgs;
proc = null;
rl = null;
pending = new Map();
nextId = 1;
closed = false;
closePromise = null;
exitResolved = false;
/** The error that ended the connection (null = clean exit). Readable so a turn
* can surface a meaningful message when the child dies mid-turn. */
exitError = null;
stderr = "";
notificationHandler = null;
resolveExit;
/** Resolves when the app-server process exits or errors (P0-2): runTurn() races
* its per-turn drain against this so a child that dies after turn/start resolved
* but before turn/completed doesn't deadlock the turn forever. */
exitPromise;
constructor(bin, cwd, env,
// Extra `-c key=value` config overrides appended after `app-server` (used to
// declare the comfyui + panel MCP servers — full Codex/Claude tool parity).
extraArgs = []) {
this.bin = bin;
this.cwd = cwd;
this.env = env;
this.extraArgs = extraArgs;
this.exitPromise = new Promise((resolve) => {
this.resolveExit = resolve;
});
}
/** Spawn `codex app-server`, perform the initialize handshake, and return. */
async initialize(clientInfo) {
// On Windows the bundled bin is a node launcher script; spawn it via the
// current node so we don't depend on a `codex` shim being on PATH. When `bin`
// is a plain "codex" (PATH fallback) we still spawn it directly.
const isJs = /\.(c|m)?js$/i.test(this.bin);
const cmd = isJs ? process.execPath : this.bin;
// `-c` overrides go AFTER the `app-server` subcommand (they're app-server
// flags). They declare the comfyui (stdio) + panel (http) MCP servers.
const baseArgs = isJs ? [this.bin, "app-server"] : ["app-server"];
const args = [...baseArgs, ...this.extraArgs];
// When falling back to a `codex` on PATH on Windows, the resolvable entry is a
// `.cmd`/`.ps1` shim — spawn without a shell can't find it (ENOENT). Use a
// shell in that case (mirrors the plugin's client). The bundled-dep lane runs
// the `.js` launcher via node directly, so it never needs a shell.
const useShell = !isJs && process.platform === "win32";
this.proc = spawn(cmd, args, {
cwd: this.cwd,
env: this.env,
stdio: ["pipe", "pipe", "pipe"],
windowsHide: true,
shell: useShell,
// On POSIX, put the child in its OWN process group so close() can kill the
// whole tree (shell + grandchild) with a single negative-pid signal. On
// Windows we use taskkill /T instead, so detached isn't needed there.
detached: process.platform !== "win32",
});
this.proc.stdout.setEncoding("utf8");
this.proc.stderr.setEncoding("utf8");
this.proc.stderr.on("data", (chunk) => {
this.stderr += chunk;
});
// Swallow stream errors on the child's pipes. When the app-server child dies
// mid-turn, the NEXT write to stdin (or a read on stdout) raises an async
// 'error' event (EPIPE on Windows) — with no listener Node treats it as an
// uncaughtException and the orchestrator's handler would exit the whole
// process. Route them through handleExit instead so the turn rejects cleanly
// (P0-2) and the host survives. (P0-2)
this.proc.stdin.on("error", (error) => this.handleExit(error));
this.proc.stdout.on("error", (error) => this.handleExit(error));
this.proc.on("error", (error) => this.handleExit(error));
this.proc.on("exit", (code, signal) => {
const detail = code === 0
? null
: new Error(`codex app-server exited unexpectedly (${signal ? `signal ${signal}` : `exit ${code}`}).${this.stderr ? ` ${this.stderr.trim().split(/\r?\n/).slice(-2).join(" ")}` : ""}`);
this.handleExit(detail);
});
this.rl = readline.createInterface({ input: this.proc.stdout });
this.rl.on("line", (line) => this.handleLine(line));
// JSON-RPC handshake: initialize (request) then initialized (notification).
// We opt IN to the delta notifications (by NOT opting out) so we can stream
// assistant + reasoning text token-by-token; the plugin opts them out because
// it only captures final messages.
await this.request("initialize", {
clientInfo,
capabilities: { experimentalApi: false, optOutNotificationMethods: [] },
});
this.notify("initialized", {});
}
request(method, params) {
if (this.closed)
return Promise.reject(new Error("codex app-server client is closed."));
const id = this.nextId++;
return new Promise((resolve, reject) => {
this.pending.set(id, { resolve: resolve, reject, method });
this.send({ id, method, params });
});
}
notify(method, params = {}) {
if (this.closed)
return;
// Fire-and-forget: a write failure (dead child) must not throw into the caller
// — handleExit already records it and rejects pending requests.
try {
this.send({ method, params });
}
catch {
// connection gone; pending requests already rejected via handleExit
}
}
send(message) {
const stdin = this.proc?.stdin;
// Stream gone / destroyed (child died) — surface as a connection exit so any
// pending request rejects, rather than throwing an unhandled error from a
// fire-and-forget notify() (P0-2).
if (!stdin || stdin.destroyed || stdin.writableEnded) {
this.handleExit(this.exitError ?? new Error("codex app-server stdin is not available."));
throw this.exitError ?? new Error("codex app-server stdin is not available.");
}
try {
stdin.write(`${JSON.stringify(message)}\n`);
}
catch (err) {
// Synchronous write failure (EPIPE) on a child that just died.
this.handleExit(err instanceof Error ? err : new Error(String(err)));
throw err;
}
}
/**
* The auto-approve RESULT for a server→client approval/permission/elicitation
* request, or null if the request isn't an approval we should auto-grant.
*
* Decision shapes differ per request method (from the app-server protocol):
* - execCommandApproval / applyPatchApproval → { decision: ReviewDecision }
* where ReviewDecision = "approved" | "denied" | …
* - item/commandExecution/requestApproval, item/fileChange/requestApproval,
* item/permissions/requestApproval → { decision: "accept" | … }
* - mcpServer/elicitation/request → an MCP elicitation result
* ({ action: "accept", content: {} }).
* We grant the affirmative for each so the headless background agent (same
* isolation posture as Claude's bypassPermissions) is never blocked.
*/
autoApproveDecision(method) {
switch (method) {
case "execCommandApproval":
case "applyPatchApproval":
return { decision: "approved" };
case "item/commandExecution/requestApproval":
case "item/fileChange/requestApproval":
case "item/permissions/requestApproval":
return { decision: "accept" };
case "mcpServer/elicitation/request":
return { action: "accept", content: {} };
default:
return null;
}
}
handleLine(line) {
if (!line.trim())
return;
let message;
try {
message = JSON.parse(line);
}
catch (error) {
this.handleExit(new Error(`Failed to parse codex app-server JSONL: ${msgOf(error)}`));
return;
}
// Server→client request. The app-server asks the client to approve commands,
// file edits, MCP tool elicitations, and permission requests. The panel agent
// is an ISOLATED background agent (same posture as the Claude path's
// bypassPermissions), so we AUTO-APPROVE these to keep the live-graph work
// flowing — otherwise a panel_* MCP tool call hangs on an approval prompt the
// headless orchestrator can't surface. Anything we don't recognize still gets
// a method-not-found so the protocol keeps moving.
if (message.id !== undefined && message.method) {
const decision = this.autoApproveDecision(message.method);
if (decision) {
logger.debug(`[codex-backend] auto-approving server request ${message.method}`);
this.send({ id: message.id, result: decision });
}
else {
logger.debug(`[codex-backend] unsupported server request ${message.method} — replying method-not-found`);
this.send({ id: message.id, error: { code: -32601, message: `Unsupported server request: ${message.method}` } });
}
return;
}
// Response to one of our requests.
if (message.id !== undefined) {
const p = this.pending.get(message.id);
if (!p)
return;
this.pending.delete(message.id);
if (message.error)
p.reject(new Error(message.error.message ?? `codex app-server ${p.method} failed.`));
else
p.resolve(message.result ?? {});
return;
}
// Notification.
if (message.method)
this.notificationHandler?.(message);
}
handleExit(error) {
if (this.exitResolved)
return;
this.exitResolved = true;
this.exitError = error;
for (const p of this.pending.values())
p.reject(error ?? new Error("codex app-server connection closed."));
this.pending.clear();
this.resolveExit();
}
async close() {
if (!this.closePromise) {
this.closePromise = (async () => {
this.closed = true;
// Drop the notification handler so a late notification can't re-enter a
// torn-down turn during shutdown.
this.notificationHandler = null;
this.rl?.close();
this.rl = null;
const proc = this.proc;
let softKillTimer;
if (proc && proc.exitCode === null) {
try {
proc.stdin.end();
}
catch {
// already gone
}
// Give a graceful stdin-EOF shutdown a beat, then kill the whole tree.
softKillTimer = setTimeout(() => {
if (proc.exitCode === null)
killProcessTree(proc.pid, false);
}, 50);
softKillTimer.unref?.();
}
let exited = await settlesWithin(this.exitPromise, CODEX_CLOSE_TIMEOUT_MS);
if (softKillTimer)
clearTimeout(softKillTimer);
if (!exited && proc && proc.exitCode === null) {
logger.warn(`[codex-backend] app-server did not exit within ${CODEX_CLOSE_TIMEOUT_MS}ms -- forcing process-tree termination`);
killProcessTree(proc.pid, true);
exited = await settlesWithin(this.exitPromise, CODEX_FORCE_KILL_GRACE_MS);
}
if (!exited) {
// Queue recovery must not depend on an OS exit event. Detach the pipes
// and resolve the logical connection even if both tree-kill attempts failed.
try {
proc?.stdin.destroy();
proc?.stdout.destroy();
proc?.stderr.destroy();
proc?.unref?.();
}
catch {
// best-effort final detach
}
this.handleExit(new Error("codex app-server teardown timed out after forced termination."));
}
this.proc = null;
})();
}
await this.closePromise;
}
}
// ---- reasoning-effort scale (advertised + applied) ----
// The authoritative Codex reasoning-effort scale (none < minimal < low < medium <
// high < xhigh — the app-server `turn/start` `effort` field). Defined ONCE here
// and reused by BOTH the model advertisement below (so every Codex ModelChoice
// tells the panel it has an effort control — the panel's normalizeModels reads
// `supportedEffortLevels`/`supportsEffort`, and hides the picker if neither is
// present) AND toCodexEffort() further down (the validity check), to avoid drift.
// The backend ALREADY applies effort to every turn via toCodexEffort regardless
// of model, so advertising it for all Codex models matches current behavior.
// GPT-5.6 extends the scale with `max` and `ultra` (verified live per model:
// sol/terra accept through ultra, luna through max — issue #241's catalog).
const CODEX_EFFORT_LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
// ---- model fallback ----
// config/read does not enumerate a model CATALOG (it reports the active provider
// + model), so when we can't derive a list we fall back to the current Codex
// model family. The panel picker degrades gracefully on an empty list. Each entry
// advertises the Codex effort scale so the panel enables the reasoning-effort
// dropdown for these models (the backend applies effort to every turn anyway).
// GPT-5.6 family ONLY (product decision 2026-07-20): older GPT-5.x are
// deprecated — the live catalog is filtered to the 5.6 family and these
// fallbacks match it. Per-variant effort ceilings from the live model/list.
const CODEX_FALLBACK_MODELS = [
{ id: "gpt-5.6-sol", label: "GPT-5.6 Sol", supportsEffort: true, supportedEffortLevels: ["low", "medium", "high", "xhigh", "max", "ultra"] },
{ id: "gpt-5.6-terra", label: "GPT-5.6 Terra", supportsEffort: true, supportedEffortLevels: ["low", "medium", "high", "xhigh", "max", "ultra"] },
{ id: "gpt-5.6-luna", label: "GPT-5.6 Luna", supportsEffort: true, supportedEffortLevels: ["low", "medium", "high", "xhigh", "max"] },
// This static list only surfaces when model/list is UNAVAILABLE — i.e. an
// older CLI resolved from PATH (bundled-install failure), which cannot run
// any 5.6 model. Keep one runnable pre-5.6 escape hatch there (codex
// review); accounts on the pinned bundled CLI never see this list.
{ id: "gpt-5.5", label: "GPT-5.5 (legacy CLI fallback)", supportsEffort: true, supportedEffortLevels: ["none", "minimal", "low", "medium", "high", "xhigh"] },
];
/** Does this id look like an OpenAI/Codex model (vs. a Claude panel model)? Used
* to ignore the Claude panel model PanelAgent unconditionally passes as
* opts.model, so the configured Codex model wins (P1-1). Anthropic ids start with
* "claude"/"anthropic"; Codex ids are gpt-, o-series, codex-, or chatgpt-. */
function isCodexModel(id) {
const m = id.toLowerCase();
if (m.startsWith("claude") || m.startsWith("anthropic"))
return false;
return /^(gpt-|o\d|codex|chatgpt)/.test(m) || m.includes("codex");
}
// ---- reasoning effort mapping ----
// Codex's reasoning-effort scale differs from Claude's: Codex accepts
// none|minimal|low|medium|high|xhigh (the app-server `turn/start` `effort` field;
// see the reference openai-codex plugin's codex.mjs), while the panel/Claude
// scale is low|medium|high|xhigh|max. The shared levels map 1:1; the only
// off-scale source value is Claude "max", which has no Codex equivalent and maps
// to the nearest valid level (xhigh). Unknown/empty → null (app-server default).
const CODEX_EFFORTS = CODEX_EFFORT_LEVELS; // single source of truth (advertised == accepted)
// Low→high rank for ceiling-snapping in toCodexEffort.
const EFFORT_RANK = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
function toCodexEffort(effort, allowed) {
if (!effort)
return null;
const e = effort.toLowerCase();
if (!CODEX_EFFORTS.includes(e)) {
return null; // unknown level → let the app-server pick its default
}
// Snap to the active model's supported list when we know it: "max"/"ultra"
// are native on GPT-5.6 but REJECTED by pre-5.6 models and older CLIs —
// the old blanket max→xhigh downmap was removed, so the ceiling must be
// enforced here (codex review). No list known → conservative xhigh cap.
if (allowed && allowed.length) {
if (allowed.includes(e))
return e;
for (let i = EFFORT_RANK.indexOf(e); i >= 0; i--) {
if (allowed.includes(EFFORT_RANK[i]))
return EFFORT_RANK[i];
}
return allowed[allowed.length - 1] ?? null;
}
if (e === "max" || e === "ultra")
return "xhigh";
return e;
}
/**
* Derive a display name for a Codex app-server `item` (from item/started and
* item/completed) when it represents a TOOL-like action — an MCP tool call, a
* shell command, a file change, a web search, etc. Returns null for non-tool
* items (agentMessage / reasoning), which the delta/commit paths already handle,
* so the caller skips emitting a tool_call for them. Best-effort + defensive: the
* exact item shape varies by app-server version, so we probe the common name
* fields and fall back to the item `type`.
*/
export function toolNameOf(item) {
if (!item || typeof item !== "object")
return null;
const type = typeof item.type === "string" ? item.type : undefined;
// These item types are text/reasoning, not tools — they're surfaced via the
// assistant_delta / assistant commit paths, so don't double-report them.
if (type === "agentMessage" || type === "reasoning")
return null;
// MCP tool calls carry a tool name (and often a server) — prefer the most
// specific identifier available, then fall back to the item type.
const pick = (...keys) => {
for (const k of keys) {
const v = item[k];
if (typeof v === "string" && v)
return v;
}
return undefined;
};
const server = pick("server", "serverName");
const tool = pick("tool", "toolName", "name", "command");
if (tool)
return server ? `${server}.${tool}` : tool;
// No explicit name field — use the item type as the label (commandExecution,
// fileChange, webSearch, …) so the panel at least shows that a tool ran.
return type ?? null;
}
/**
* Build the `-c key=value` CLI overrides that declare the given MCP servers to
* `codex app-server`. Values are TOML literals: strings are JSON-quoted, arrays
* are JSON arrays (valid TOML). Mirrors `codex mcp add` / the config.toml format.
*
* SECURITY LIMITATION (known, accepted — Codex lane only): the comfyui stdio
* server's `env` is emitted as `-c mcp_servers.comfyui.env.KEY="value"` argv, so
* any value here — including a panel-saved secret (CIVITAI_API_TOKEN, …) — lands
* in the spawned process's argv, visible to local process inspection (ps,
* /proc/<pid>/cmdline) and any external crash/telemetry tooling that captures
* argv. This is inherent to how the bundled `codex app-server` accepts MCP config:
* the ONLY out-of-band channel is `$CODEX_HOME/config.toml`, but CODEX_HOME also
* holds the user's Codex login/auth and real config, so pointing the app-server at
* a private temp CODEX_HOME to hide the secret would break the user's sign-in and
* settings — not a safe trade. We therefore accept the argv exposure for now and
* mitigate it by NEVER logging these args (they are passed straight to spawn() and
* to no logger; do not add any logging of the returned array or `extraArgs`).
* - The DEFAULT panel transport is the Claude Agent SDK (in-process MCP), which
* has no argv exposure; the Codex backend is opt-in (PANEL_AGENT_BACKEND=codex).
* - Follow-up: revisit if codex app-server gains an env/file/stdin channel for
* per-server MCP env that doesn't clobber CODEX_HOME.
*/
export function buildMcpConfigArgs(servers) {
const args = [];
const lit = (s) => JSON.stringify(s); // safe TOML string literal
for (const [name, spec] of Object.entries(servers)) {
if (spec.transport === "stdio") {
args.push("-c", `mcp_servers.${name}.command=${lit(spec.command)}`);
if (spec.args && spec.args.length) {
args.push("-c", `mcp_servers.${name}.args=${JSON.stringify(spec.args)}`);
}
for (const [k, v] of Object.entries(spec.env ?? {})) {
args.push("-c", `mcp_servers.${name}.env.${k}=${lit(v)}`);
}
}
else {
// Streamable HTTP MCP server — `url` is what `codex mcp add --url` sets.
args.push("-c", `mcp_servers.${name}.url=${lit(spec.url)}`);
}
}
return args;
}
// ---- sandbox / approval posture ----
// The Claude panel agent runs with bypassPermissions — full autonomy on the
// user's OWN machine. To MATCH that for the Codex lane (so Codex can actually run
// shell commands instead of hitting a read-only sandbox that "rejects multi-line
// scripts" and gives up), default the codex app-server to the most permissive
// sandbox (danger-full-access) with approvals disabled. Overridable via
// COMFYUI_MCP_CODEX_SANDBOX for a cautious user who wants to dial it down to
// "workspace-write" or "read-only". Anything else falls back to the default.
const CODEX_SANDBOX_MODES = new Set(["read-only", "workspace-write", "danger-full-access"]);
const CODEX_SANDBOX_DEFAULT = "danger-full-access";
export function resolveCodexSandbox() {
const raw = (process.env.COMFYUI_MCP_CODEX_SANDBOX ?? "").trim().toLowerCase();
return CODEX_SANDBOX_MODES.has(raw) ? raw : CODEX_SANDBOX_DEFAULT;
}
/**
* The Codex app-server adapter. One instance per PanelAgent; it holds the live
* app-server client + current thread/turn ids and re-opens on each `run()`.
*/
export class CodexBackend {
id = "codex";
capabilities = CODEX_CAPABILITIES;
deps;
client = null;
/** The client currently being spun up by an in-flight prepare(), tracked so a
* concurrent close() can tear it down even before it's published to
* this.client (P0-A: close() racing prepare() must never leak the child). */
preparingClient = null;
/** Detached clients whose bounded teardown is still in flight. */
closingClients = new Map();
/** Per-turn escape hatch used when the app-server ignores turn/interrupt. */
abortActiveTurn = null;
/** Set once close() runs — a hard tripwire so an in-flight prepare() that wakes
* up after close() disposes its local client instead of publishing it (P0-A). */
disposed = false;
/** Cached resolved path to the codex binary/launcher (set in prepare()). */
bin = null;
/** Account-aware model catalog from the app-server's model/list (set by
* listModels()); resolveTurnModel() clamps every thread's model to it. */
liveCatalog = null;
/** Sandbox posture for the app-server + every thread (COMFYUI_MCP_CODEX_SANDBOX,
* default danger-full-access — mirrors Claude's bypassPermissions). Read once at
* construction so it's stable for this backend instance. */
sandbox = resolveCodexSandbox();
/** The live thread + turn ids — used for `turn/interrupt`. */
threadId = null;
turnId = null;
/** The model requested for new turns (mutable for a future live setModel). */
model;
/** The Codex reasoning effort for new turns, already mapped to a valid Codex
* level (null = let the app-server choose). Captured from run(opts.effort). */
/** RAW panel effort for this session — snapped per-turn against the
* RESOLVED model's supported list (the catalog isn't loaded yet when run()
* captures it, and the active model can change via the clamp). */
effort = null;
/** True until the panel system prompt has been prepended to a turn. The
* app-server's thread/start has no instructions field, so the persona rides on
* the FIRST turn's input; reset whenever a NEW thread starts (run()). */
needsSystemPreamble = false;
/** Temp image files written for delivered turn images (the app-server's
* `localImage` input item takes a PATH, so /view bytes are spilled to disk).
* Tracked so each turn cleans up its own files, and close() sweeps any
* stragglers. */
tempImageFiles = new Set();
constructor(deps = {}) {
this.deps = deps;
this.model = deps.model;
}
beginClientClose(client, reason) {
const existing = this.closingClients.get(client);
if (existing)
return existing;
const closeOperation = Promise.resolve()
.then(() => client.close())
.catch((err) => {
logger.warn(`[codex-backend] ${reason}: ${msgOf(err)}`);
});
const closing = settlesWithin(closeOperation, CODEX_CLIENT_CLOSE_BUDGET_MS)
.then((settled) => {
if (!settled) {
logger.warn(`[codex-backend] ${reason}: close did not settle within ${CODEX_CLIENT_CLOSE_BUDGET_MS}ms; detaching`);
}
})
.finally(() => {
if (this.closingClients.get(client) === closing)
this.closingClients.delete(client);
});
this.closingClients.set(client, closing);
return closing;
}
/**
* Resolve the codex binary: prefer the bundled `@openai/codex` launcher (via
* require.resolve of its package bin) so no separate install is needed; fall
* back to a `codex` on PATH. Throws a clear message if neither is available.
*/
resolveBin() {
if (this.bin)
return this.bin;
try {
const require = createRequire(import.meta.url);
// The package exposes bin/codex.js; resolve its package.json then derive the
// bin path relative to the package dir (works regardless of OS separators).
const pkgPath = require.resolve("@openai/codex/package.json");
const pkg = require("@openai/codex/package.json");
const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.codex;
if (binRel) {
const sep = pkgPath.includes("\\") ? "\\" : "/";
const pkgDir = pkgPath.replace(/[\\/]package\.json$/, "");
this.bin = `${pkgDir}${sep}${binRel.replace(/^\.[\\/]/, "")}`;
}
}
catch {
// bundled package not installed — fall through to PATH.
}
if (!this.bin)
this.bin = "codex"; // PATH fallback (a `codex` on PATH)
return this.bin;
}
/**
* Fetch a ComfyUI image (/view) and spill the bytes to a temp file, returning
* its absolute path — or null on any failure (the text reference still names the
* image as a fallback). The app-server `turn/start` `localImage` input item takes
* a FILE PATH (mirrors the codex CLI `-i, --image <FILE>`), so unlike Claude
* (inline base64) we must write the bytes to disk. Mirrors
* ClaudeBackend.fetchImageBlock's source/size guards. Each written path is
* tracked in tempImageFiles for per-turn + close() cleanup.
*/
async fetchImageFile(ref) {
if (!this.deps.comfyuiUrl || !ref?.filename)
return null;
try {
const u = new URL("/view", this.deps.comfyuiUrl);
u.searchParams.set("filename", ref.filename);
u.searchParams.set("type", ref.type || "input");
if (ref.subfolder)
u.searchParams.set("subfolder", ref.subfolder);
const res = await fetch(u, { signal: AbortSignal.timeout(15000) });
if (!res.ok)
return null;
const mt = (res.headers.get("content-type") || "").split(";")[0].trim().toLowerCase();
const buf = Buffer.from(await res.arrayBuffer());
if (buf.length > 12 * 1024 * 1024)
return null; // keep context sane (parity with Claude)
// Preserve a recognizable extension so the model/app-server treat it as the
// right image type; default to .png (ComfyUI outputs are PNG by default).
const extFromMime = {
"image/png": ".png",
"image/jpeg": ".jpg",
"image/gif": ".gif",
"image/webp": ".webp",
};
// Recognized content-type → its extension; otherwise only trust the source
// filename extension if it's a known image type, else default to .png (don't
// preserve an arbitrary suffix — parity with Claude mapping unknowns to png).
const allowedExt = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
const fileExt = path.extname(ref.filename).toLowerCase();
const ext = extFromMime[mt] ?? (allowedExt.has(fileExt) ? fileExt : ".png");
const file = path.join(os.tmpdir(), `comfyui-codex-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}${ext}`);
await fsp.writeFile(file, buf);
this.tempImageFiles.add(file);
return file;
}
catch {
return null;
}
}
/** Delete the given temp image files (best-effort) and drop them from tracking. */
async cleanupTempImages(files) {
for (const f of files) {
this.tempImageFiles.delete(f);
try {
await fsp.unlink(f);
}
catch {
// already gone / never created — best-effort
}
}
}
/**
* Preflight: resolve + spawn `codex app-server`, perform the JSON-RPC
* handshake, and verify the account is logged in (ChatGPT login / CODEX_API_KEY
* — keyless, like the Claude OAuth lane). Fails fast with a clear reject so a
* missing binary or signed-out state surfaces immediately instead of being
* retried as a dropped session. Idempotent — reuses the live client.
*/
async prepare() {
if (this.disposed)
throw new Error("codex backend is closed.");
if (this.client)
return;
const bin = this.resolveBin();
const cwd = this.deps.cwd ?? process.cwd();
// Declare the comfyui + panel MCP servers as `-c` overrides so Codex has the
// same tool surface as Claude (full parity). Also set the sandbox + approval
// posture at the app-server CONFIG level (the per-turn thread/start `sandbox`
// param below is the effective lever, but pinning the config default keeps them
// consistent and covers any codex path that reads the config). Values are TOML
// string literals via JSON.stringify, matching buildMcpConfigArgs.
const extraArgs = [
...(this.deps.mcpServers ? buildMcpConfigArgs(this.deps.mcpServers) : []),
"-c",
`sandbox_mode=${JSON.stringify(this.sandbox)}`,
"-c",
`approval_policy=${JSON.stringify("never")}`,
// Isolate the embedded app-server from the user's GLOBAL Codex `notify`
// config (#277): an inherited legacy_notify hook can fail after a panel
// turn on Windows with `os error 206` (filename/extension too long),
// emitting a misleading warning alongside a failed turn. The panel owns
// its own UI notifications, so the embedded app-server needs no hook.
"-c",
"notify=[]",
];
// SECURITY: spawn with the agent env — process.env MINUS tool-only secrets
// (RunPod/HF/CivitAI… tokens). Those belong to the comfyui tool child
// (buildComfyuiMcpEnv), never to an LLM vendor's subprocess.
const client = new AppServerClient(bin, cwd, buildAgentSpawnEnv(), extraArgs);
// Publish the in-flight client BEFORE the startup awaits so a concurrent
// close() can find and kill it instead of seeing this.client === null and
// returning early — which would orphan the spawning app-server child (P0-A).
this.preparingClient = client;
// After EVERY await below, re-check disposed: close() may have run during the
// await and torn down our client out from under us. If so, dispose the local
// client and bail without publishing it.
const abortIfDisposed = async () => {
if (!this.disposed)
return;
if (this.preparingClient === client)
this.preparingClient = null;
await client.close().catch(() => { });
throw new Error("codex backend was closed during prepare().");
};
try {
try {
await client.initialize({ title: "comfyui-mcp panel", name: "comfyui-mcp", version: "0.16.0" });
}
catch (err) {
await client.close().catch(() => { });
throw new Error(`Could not start the Codex app-server (codex backend). Install the optional dependency with: npm i @openai/codex (or ensure \`codex\` is on PATH). Details: ${msgOf(err)}`);
}
await abortIfDisposed();
// Auth check: account/read tells us whether a ChatGPT login or API key is
// present. Mirror the plugin's app-server auth probe.
try {
const account = await client.request("account/read", { refreshToken: false });
const loggedIn = !!account?.account || account?.requiresOpenaiAuth === false;
if (!loggedIn) {
await client.close().catch(() => { });
throw new Error("Codex is not logged in. Run `codex login` (ChatGPT login) or set CODEX_API_KEY, then reconnect.");
}
}
catch (err) {
await client.close().catch(() => { });
throw err instanceof Error ? err : new Error(msgOf(err));
}
await abortIfDisposed();
this.client = client;
logger.info("[codex-backend] app-server ready (logged in)");
}
finally {
// Either we published it onto this.client, or an error/abort path already
// closed it — in all cases stop tracking it as in-flight.
if (this.preparingClient === client)
this.preparingClient = null;
}
}
/**
* Open/continue a Codex thread and yield canonical AgentEvents. The user
* channel (PanelAgent's gated queue) is consumed ONE turn at a time: each
* neutral batch becomes a `turn/start`, whose streamed notifications are
* normalized to AgentEvents, and only after the turn completes do we read the
* next batch (the channel async-iteration IS the turn-gate).
*/
async *run(opts) {
await this.prepare();
const client = this.client;
if (!client)
throw new Error("codex app-server not initialized");
const cwd = opts.cwd ?? this.deps.cwd ?? process.cwd();
// MODEL PRECEDENCE (P1-1): PanelAgent.start() always passes opts.model = the
// CLAUDE panel model (e.g. claude-opus-5), which is NOT a valid Codex model.
// The Codex model configured at construction (deps.model, from
// COMFYUI_MCP_CODEX_MODEL) must win. Only honor opts.model if it actually looks
// like a Codex model (so a future Codex-aware picker can still switch live);
// otherwise ignore it and keep the configured Codex model (or the account
// default when neither is set — model:null lets the app-server choose).
if (opts.model && isCodexModel(opts.model))
this.model = opts.model;
// Capture the RAW panel effort; each turn maps+snaps it against the model
// it actually runs (toCodexEffort with the model's supported list — the
// catalog isn't loaded yet here, and max/ultra are only valid on models
// that advertise them). The panel restarts run() on an effort change, so
// capturing once per session is enough.
this.effort = opts.effort ?? null;
// forkAtAnchor is false (CODEX_CAPABILITIES) → ignore opts.rewindAnchor; we
// only do whole-thread resume.
const resumeId = opts.resume ?? opts.sessionId ?? null;
// Make sure THIS instance knows the account's live model catalog before the
// thread opens — each tab's agent gets its own backend instance, so the
// catalog fetched by the connect-time advertisement lives elsewhere. Without
// this, resolveTurnModel() has nothing to clamp against and defers to the
// ~/.codex config default, which can be unrunnable (see resolveTurnModel).
if (!this.liveCatalog)
await this.listModels().catch(() => { });
let threadModel;
if (resumeId) {
// thread/resume continues an existing conversation by id.
const res = await client.request("thread/resume", {
threadId: resumeId,
cwd,
model: this.resolveTurnModel(),
approvalPolicy: "never",
sandbox: this.sandbox,
});
this.threadId = res.thread.id;
threadModel = res.model;
// A resumed thread already received the persona on its original first turn —
// don't repeat it.
this.needsSystemPreamble = false;
}
else {
// thread/start opens a fresh conversation.
const res = await client.request("thread/start", {
cwd,
model: this.resolveTurnModel(),
approvalPolicy: "never",
sandbox: this.sandbox,
ephemeral: false,
});
this.threadId = res.thread.id;
threadModel = res.model;
// Fresh thread → prepend the panel persona to the first turn's input.
this.needsSystemPreamble = !!this.deps.systemAppend;
}
// The thread id is our session id (PanelAgent persists it for resume).
yield {
type: "session",
sessionId: this.threadId,
...(threadModel ? { model: threadModel } : {}),
};
// Process the neutral channel one turn at a time. onActivity is the LIVENESS
// signal — every raw app-server notification for the active turn re-arms
// PanelAgent's idle watchdog so a long, quiet generation doesn't falsely trip.
for await (const turn of opts.channel) {
yield* this.runTurn(client, turn, opts.onActivity);
// A timed-out interrupt detaches this client. End the old run before it can
// consume another queued turn; PanelAgent will start a fresh app-server.
if (this.client !== client)
return;
}
}
/** Run ONE turn: turn/start + stream its notifications → AgentEvents, resolving
* when `turn/completed`/`error` for this thread+turn arrives, OR when the
* app-server child exits mid-turn (P0-2 — never deadlock). Notifications are
* buffered until the turnId is known and then filtered by belongsToTurn (P1-3)
* so a stale/interleaved same-thread notification can't complete the wrong turn. */
async *runTurn(client, turn, onActivity) {
const threadId = this.threadId;
// Event queue bridging the push-based notification handler to this pull-based
// async generator. The handler enqueues normalized AgentEvents; we drain.
const queue = [];
let wake = null;
let done = false;
const push = (ev) => {
queue.push(ev);
wake?.();
wake = null;
};
const finish = () => {
done = true;
wake?.();
wake = null;
};
// EVERY terminal path of a turn MUST emit exactly one `result` so PanelAgent's
// turn-gate advances (it only calls completeTurn() on a result event; a missing
// result parks its channel forever — panel-agent.ts ~438). This single
// idempotent helper guarantees that: it emits an `error` event + a single
// `{type:"result", ok:false}` and finishes, and is a no-op if a result was
// already emitted (so the error notification, the exit watcher, and the
// turn/start rejection can all call it without double-finishing) (P0-B).
let finishedResult = false;
const emitTerminalError = (message) => {
if (finishedResult)
return;
finishedResult = true;
closeStream();
push({ type: "error", message });
push({ type: "result", ok: false, subtype: "error" });
finish();
};
// ---- turn-id state machine (mirrors the reference captureTurn) ----
// The turnId isn't known until the turn/start response resolves, and some
// notifications can arrive BEFORE it. Buffer those, then replay only the ones
// that belong to this turn once we know the id. After that, filter live.
let activeTurnId = null;
let turnIdKnown = false;
const buffered = [];
const belongsToTurn = (msg) => {
const params = (msg.params ?? {});
const msgThreadId = params.threadId;
// Wrong thread → not ours.
if (msgThreadId && msgThreadId !== threadId)
return false;
const t = params.turn;
const msgTurnId = params.turnId ?? t?.id ?? null;
// No active turn id yet (shouldn't happen post-buffer) or the notification
// carries no turn id → accept; otherwise require an exact match.
return activeTurnId === null || msgTurnId === null || msgTurnId === activeTurnId;
};
// LIVENESS (watchdog re-arm): re-arm PanelAgent's idle watchdog ONLY for
// notifications that represent work or an outcome for THIS active turn. A
// long tool call streams item/* and turn/* notifications that carry no
// AgentEvent of their own — a multi-minute ComfyUI generation emits
// item/started, item/updated, … — so without this a healthy long run looks
// idle and the watchdog falsely trips. `error` counts too: a retrying
// provider error (willRetry) is Codex still owning the turn.
//
// It must NOT fire for the background traffic the app-server interleaves —
// account, model-catalog and token-usage notifications arrive while the
// active turn is silent — nor for notifications belonging to a stale or
// other thread/turn. Both kept the watchdog armed forever, so a genuinely
// wedged turn (nothing on its own item/turn stream while background chatter
// continued) never reached the stall deadline. Gating on belongsToTurn AND
// the active-turn method set is what makes the deadline reachable. (#307)
// item/* and turn/* are the streaming lifecycle; `error` is a (possibly
// retrying) turn error. The model/* trio are turn events the pinned
// app-server emits around provider routing/safety — they carry threadId +
// turnId, so they ARE active-turn progress and must re-arm the watchdog, but
// a bare item/turn prefix check misses them (#307 review, finding 2).
const MODEL_TURN_EVENTS = new Set([
"model/safetyBuffering/updated",
"model/rerouted",
"model/verification",
]);
const TURN_LIVENESS = (m) => m.startsWith("item/") || m.startsWith("turn/") || m === "error" || MODEL_TURN_EVENTS.has(m);
const bumpTurnActivity = (msg) => {
if (!belongsToTurn(msg) || !TURN_LIVENESS(msg.method ?? ""))
return;
try {
onActivity?.();
}
catch {
// a watchdog bump must never break the protocol reader
}
};
// Track the streamed item id so deltas + the final commit share one bubble id
// (the panel reconciles by id, like the Claude stream path). Reasoning and
// reply text each open/close their own stream (P2-1: reasoning was previously
// emitted without a stream_start, so the panel dropped early thinking deltas).
let streamOpen = false;
let streamKind = null;
let interrupted = false;
const openStream = (id, kind) => {
if (streamOpen && streamKind === kind)
return;
if (streamOpen)
push({ type: "stream_end" }); // switch kinds → close the old one
streamOpen = true;
streamKind = kind;
push({ type: "stream_start", id });
};
const closeStream = () => {
if (streamOpen) {
push({ type: "stream_end" });
streamOpen = false;
streamKind = null;
}
};
const abortActiveTurn = () => {
interrupted = true;
if (finishedResult)
return;
finishedResult = true;
closeStream();
// This is controlled recovery, not a provider failure. `ok: true` also
// prevents the watchdog path from painting a duplicate failure banner.
push({ type: "result", ok: true, subtype: "interrupted" });
finish();
};
this.abortActiveTurn = abortActiveTurn;
// Normalize ONE notification (already confirmed to belong to this turn) into
// canonical AgentEvents. Pulled out so it can be applied to both live and
// buffered (replayed) notifications.
const apply = (msg) => {
// Once ANY terminal result has fired (success turn/completed OR a terminal
// error via emitTerminalError), the turn is done — drop every later
// notification so a racing/buffered turn/completed can't push a SECOND result
// (double-completing PanelAgent's gate) or enqueue deltas into a closing
// iterator. This is the "exactly one result" invariant (P0-B).
if (finishedResult)
return;
const params = (msg.params ?? {});
switch (msg.method) {
case "turn/started": {
const t = params.turn;
if (t?.id) {
this.turnId = t.id;
if (!activeTurnId)
activeTurnId = t.id;
}
break;
}
case "item/agentMessage/delta": {
const delta = params.delta;
const itemId = params.itemId;
if (typeof delta === "string" && delta) {
openStream(itemId ?? null, "text");
push({ type: "assistant_delta", text: delta });
}
break;
}
case "item/reasoning/textDelta":
case "item/reasoning/summaryTextDelta": {
// Extended-thinking streaming (raw reasoning + the model's summary).
// Open a reasoning stream on the FIRST delta (P2-1) so PanelAgent — which
// drops assistant_delta when no stream is open — renders early thinking.
const delta = params.delta;
const itemId = params.itemId;
if (typeof delta === "string" && delta) {
openStream(itemId ?? null, "thinking");
push({ type: "assistant_delta", text: delta, thinking: true });
}
break;
}
case "item/started": {
// A non-message item began (a tool/command/MCP call or file change). Emit
// a tool_call(start) AgentEvent so the panel has TOOL VISIBILITY (the
// documented P2 gap — Codex previously surfaced no tool activity at all)
// and the watchdog re-arms on a translated event too. agentMessage /
// reasoning items aren't "tools" — they're handled by the delta/commit
// paths above — so skip them here.
const item = params.item;
const name = toolNameOf(item);
if (name)
push({ type: "tool_call", name, phase: "start", detail: item });
break;
}
case "item/completed": {
// The authoritative commit for a finished item. Close any open stream
// (reasoning OR reply) then emit the canonical event: `assistant` for an
// agentMessage, or tool_call(end) for a finished tool/command/MCP item.
const item = params.item;
const itemType = item?.type;
closeStream();
if (itemType === "agentMessage") {
const text = (item?.text ?? "").trim();
const id = item?.id;
push({
type: "assistant",
text,
...(id ? { id } : {}),
// No per-turn rewind anchor for Codex (forkAtAnchor=false) — omit uuid.
});
}
else {
const name = toolNameOf(item);
if (name)
push({ type: "tool_call", name, phase: "end", detail: item });
}
break;
}
case "error": {
// App-server uses the same notification for transient provider failures
// and terminal errors. `willRetry: true` means Codex is still owning the
// turn and will continue it after reconnecting; completing our iterator
// here would abort that recovery and make the panel report e.g.
// "Reconnecting... 2/5" as the final failure. `error` is in the turn
// liveness set, so this already re-armed the watchdog — keep waiting
// for either a later terminal error or turn/completed.
const e = (params.error ?? {});
if (params.willRetry === true)
break;
// A non-retrying `error` ends the turn: emit it AND finish, so a turn that
// errors out (no following turn/completed) doesn't hang (P0-2). Route it
// through the idempotent helper to avoid racing another terminal path.
emitTerminalError(e.message ?? "Codex error");
break;
}
case "turn/completed": {
closeStream();
const t = params.turn;
// Mark a result emitted so a racing terminal-error path stays a no-op.
finishedResult = true;
push({ type: "result", ok: t?.status === "completed", ...(t?.status ? { subtype: t.status } : {}) });
finish();
break;
}
default:
break;
}
};
const prev = client.notificationHandler;
client.notificationHandler = (msg) => {
// Until the turnId is known, buffer everything — we can't yet tell which
// turn a notification belongs to, so we can't yet decide whether it counts
// as liveness either. Replayed (and bumped) after turn/start resolves, so
// the watchdog rule lives in exactly one place: bumpTurnActivity.
if (!turnIdKnown) {
buffered.push(msg);
return;
}
bumpTurnActivity(msg);
if (!belongsToTurn(msg)) {
prev?.(msg); // stale / other-turn / other-thread → pass through
return;
}
apply(msg);
};
// Watch for the app-server child dying mid-turn: reject/finish the turn so the
// local drain below is woken instead of waiting forever (P0-2). Crucially this
// ALWAYS routes through emitTerminalError so even a child that dies while
// turn/start is still pending leaves the turn with a terminal `result` — the
// turn-start .catch() running first (rejecting the pending request) no longer
// lets this watcher finish() without a result and hang the gate (P0-B).
void client.exitPromise.then(() => {
if (done)
return;
// emitTerminalError is a no-op if a result already fired, so it's safe to
// call alongside the turn-start .catch() (which may run first when the child
// dies while turn/start is pending) — it guarantees the turn still ends with
// exactly one terminal result and never hangs the gate (P0-B).
emitTerminalError(client.exitError ? msgOf(client.exitError) : "codex app-server connection closed.");
});
// FIRST-TURN PERSONA: the app-server has no thread-level instructions field,
// so the panel system prompt is prepended to the first turn's input as a
// clearly-marked system/context preamble (later turns send plain text).
let turnText = promptText(turn.text);
if (this.needsSystemPreamble && this.deps.systemAppend) {
turnText =
`<system>\n${this.deps.systemAppend}\n</system>\n\n` +
`The user's first message follows.\n\n${turnText}`;
this.needsSystemPreamble = false;
}
// IMAGE DELIVERY (vision parity with Claude): fetch each ComfyUI image ref's
// bytes from /view, spill to a temp file, and add a `localImage` input item
// (which takes a FILE PATH — the app-server's path-based image variant, mirror
// of the codex CLI `-i, --image <FILE>`). The text item stays first so the
// prompt context is preserved; images follow. Falls back to text-only when
// there are no images (or none resolve). The files written for THIS turn are
// tracked locally so the finally block cleans them up after the turn ends.
const turnInput = [
{ type: "text", text: turnText, text_elements: [] },
];
const turnTempFiles = [];
for (const ref of turn.images ?? []) {
const file = await this.fetchImageFile(ref);
if (file) {
turnTempFiles.push(file);
turnInput.push({ type: "localImage", path: file });
}
}
try {
// turn/start delivers the user text plus any resolved image input items.
const turnModel = this.resolveTurnModel();
client
.request("turn/start", {
threadId,
input: turnInput,
// Same clamp as thread/start|resume — sending the raw pin here let
// a deprecated/unrunnable model bypass the thread-level clamp on
// every turn (codex review on this branch).
model: turnModel,
// Map+snap the session effort against the model THIS turn runs:
// known catalog → the model's own supported list caps it (5.6 keeps
// max/ultra; pre-5.6 snaps down); unknown catalog → xhigh cap.
effort: toCodexEffort(this.effort ?? undefined, this.liveCatalog?.find((m) => m.id === turnModel)?.supportedEffortLevels),
outputSchema: null,
})
.then((res) => {
// Set the active turn id, flush the buffer (replaying only this turn's
// notifications), then switch the handler to live filtering.
if (res.turn?.id) {
this.turnId = res.turn.id;
activeTurnId = res.turn.id;
}
turnIdKnown = true;
for (const msg of buffered) {
// Same watchdog rule as the live path: a buffered item/*, turn/* or
// error for this turn counts as liveness now that we can attribute it.
bumpTurnActivity(msg);
if (belongsToTurn(msg))
apply(msg);
else
prev?.(msg);
}
buffered.length = 0;
})
.catch((err) => {
// A failed turn/start (or an interrupt rejecting it) ends the turn. Also
// mark the id known so any post-failure notifications stop buffering.
turnIdKnown = true;
// CRITICAL (P0-B): when the child dies mid-turn, handleExit() rejects this
// pending request BEFORE resolving exitPromise — so this .catch() runs
// first. It MUST end the turn with a terminal `result` (not just an
// `error` + bare finish()), or the exit watcher then sees done===true and
// returns without one, hanging PanelAgent's gate forever. Route through
// the idempotent helper so it always emits exactly one result.
if (interrupted) {
// Deliberate teardown (interrupt restored/closed the turn): still end
// with a result so the gate advances, but no user-facing error.
abortActiveTurn();
}
else {
emitTerminalError(msgOf(err));
}
});
// Drain the bridged queue until the turn completes.
while (true) {
while (queue.length) {
yield queue.shift();
}
if (done)
break;
await new Promise((resolve) => {
wake = resolve;
});
}
// Flush any trailing events queued between the last drain and done.
while (queue.length)
yield queue.shift();
}
finally {
// Mark interrupted so a late turn/start rejection / exit doesn't surface as
// a spurious error after we've already torn the turn down.
interrupted = true;
if (this.abortActiveTurn === abortActiveTurn)
this.abortActiveTurn = null;
// Restore the prior handler ONLY if it's still ours (close() may have nulled
// it during shutdown — don't resurrect a stale handler onto a dead client).
if (client.notificationHandler && !client.exitError)
client.notificationHandler = prev ?? null;
this.turnId = null;
// Sweep this turn's temp image files now that the app-server has consumed
// them (the bytes were read at turn/start). Best-effort + non-blocking on the
// generator's teardown.
if (turnTempFiles.length)
void this.cleanupTempImages(turnTempFiles);
}
}
/** Stop the current turn without ending the thread → `turn/interrupt`. */
async interrupt() {
const client = this.client;
if (!client || !this.threadId || !this.turnId)
return;
let timer;
let timedOut = false;
try {
await Promise.race([
client.request("turn/interrupt", { threadId: this.threadId, turnId: this.turnId }),
new Promise((_, reject) => {
timer = setTimeout(() => {
timedOut = true;
reject(new Error(`turn/interrupt timed out after ${CODEX_INTERRUPT_TIMEOUT_MS}ms`));
}, CODEX_INTERRUPT_TIMEOUT_MS);
}),
]);
}
catch (err) {
if (timedOut) {
logger.warn(`[codex-backend] interrupt timed out after ${CODEX_INTERRUPT_TIMEOUT_MS}ms -- recycling app-server`);
if (this.client === client) {
this.client = null;
this.threadId = null;
this.turnId = null;
this.abortActiveTurn?.();
}
void this.beginClientClose(client, "interrupt recycle teardown failed");
return;
}
logger.debug(`[codex-backend] interrupt: ${msgOf(err)}`);
}
finally {
if (timer)
clearTimeout(timer);
}
}
/**
* Codex model enumeration — LIVE via the app-server's `model/list` (codex-cli
* ≥ ~0.14x), which is ACCOUNT-AWARE: a ChatGPT-plan login only sees models that
* plan can actually run. The old static list advertised ids the account
* couldn't use (e.g. "gpt-5.5-codex" on a ChatGPT account), so picking one
* 400'd every turn ("The 'gpt-5.5-codex' model is not supported when using
* Codex with a ChatGPT account" — Discord #help). Falls back to the static
* family only when the RPC is unavailable (older CLI) or errors.
*/
async listModels() {
try {
await this.prepare();
const client = this.client;
if (client) {
const res = await client.request("model/list", {});
const live = (res?.data ?? [])
.filter((m) => (m.id || m.model) && m.hidden !== true)
.map((m) => {
const efforts = (m.supportedReasoningEfforts ?? [])
.map((e) => e.reasoningEffort)
.filter((e) => typeof e === "string" && CODEX_EFFORT_LEVELS.includes(e));
return {
id: (m.id ?? m.model),
...(m.displayName ? { label: m.displayName } : {}),
// Every Codex ModelChoice MUST advertise effort support so the
// panel enables the reasoning dropdown (the backend applies
// effort to every turn regardless). Prefer the model's own list.
supportsEffort: true,
supportedEffortLevels: efforts.length ? efforts : [...CODEX_EFFORT_LEVELS],
};
});
if (live.length) {
// liveCatalog keeps the FULL account catalog: it answers "can this
// account run model X" for resolveTurnModel's clamp. The PICKER gets
// the deprecation-filtered view below — hiding a model from new
// picks must not force-switch an existing pin/resume that the
// account can still legally run (codex review on this branch).
this.liveCatalog = live;
// GPT-5.6-only policy: hide deprecated 5.x/codex ids from the picker
// when the account has the 5.6 family. Accounts WITHOUT any 5.6
// model keep their full catalog (never brick an older plan).
const fam = live.filter((m) => m.id.startsWith("gpt-5.6"));
if (fam.length && fam.length < live.length) {
logger.debug(`[codex-backend] hiding ${live.length - fam.length} deprecated pre-5.6 model(s) from the picker`);
}
return fam.length ? fam : live;
}
}
}
catch (err) {
logger.debug(`[codex-backend] model/list unavailable (older CLI?): ${msgOf(err)} — using static fallback`);
}
return CODEX_FALLBACK_MODELS;
}
/** The model to pass to thread/start|resume, CLAMPED to the live catalog.
* Passing null defers to the user's ~/.codex config default — which can name
* a model the RESOLVED binary or the account can't run (e.g. a newer CLI
* wrote `gpt-5.6-sol` into config, our optional-dep binary is older → every
* turn 400s "requires a newer version of Codex"). If we know the catalog and
* the requested/configured model isn't in it, use the catalog's first entry
* and say so in the log. Without a catalog, behave as before. */
resolveTurnModel() {
const cat = this.liveCatalog;
if (!cat || !cat.length)
return this.model ?? null;
const wanted = this.model;
if (wanted && cat.some((m) => m.id === wanted))
return wanted;
const fallback = cat[0].id;
logger.warn(`[codex-backend] model ${wanted ?? "(config default)"} is not in the account's live catalog — using ${fallback}`);
return fallback;
}
/** Permanently dispose of the backend (AgentBackend.close): kill the app-server
* process TREE (Windows shell-fallback grandchild included), remove listeners,
* null the client. Called by PanelAgent.stop() and every agent-replacement path
* (reset / effort restart / stopAll / shutdown). Idempotent + safe when never
* prepared (client is null). Without this the codex app-server child is orphaned
* because interrupt() is a no-op when the turn is idle (P0-1). */
async close() {
// Tripwire FIRST: an in-flight prepare() re-checks this after each await and
// disposes its local client rather than publishing it (P0-A).
this.disposed = true;
const client = this.client;
// Also tear down any client a concurrent prepare() is mid-spawn on but hasn't
// published yet — without this, close() would return while that child is still
// coming up and orphan it (P0-A).
const preparing = this.preparingClient;
const closing = [...this.closingClients.keys()];
const abortActiveTurn = this.abortActiveTurn;
this.client = null;
this.preparingClient = null;
this.threadId = null;
this.turnId = null;
abortActiveTurn?.();
if (this.abortActiveTurn === abortActiveTurn)
this.abortActiveTurn = null;
const clients = new Set();
for (const candidate of [...closing, client, preparing]) {
if (candidate)
clients.add(candidate);
}
for (const candidate of clients)
candidate.notificationHandler = null;
await Promise.all([...clients].map((candidate) => this.beginClientClose(candidate, "backend close teardown failed")));
// Sweep any temp image files a turn didn't get to clean up (e.g. close() raced
// an in-flight turn). Snapshot first — cleanupTempImages mutates the set.
if (this.tempImageFiles.size) {
await this.cleanupTempImages([...this.tempImageFiles]).catch(() => { });
}
}
}
//# sourceMappingURL=codex-backend.js.map