@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,177 lines (1,116 loc) • 49.4 kB
text/typescript
/**
* Reading the prompt text Codex actually assembles.
*
* The read-only dialog used to say Codex "does not expose" a layer's text. That
* was wrong: Codex is open source and ships `codex debug prompt-input`, which
* renders the model-visible input list as JSON. Reading it is the difference
* between describing a layer and showing it.
*
* What this does NOT cover, stated rather than implied:
*
* - `base-instructions` is absent from the probed output: Codex returns
* `prompt.input` and discards `base_instructions`, so the base prompt never
* appears there. It is read here from the configured sources instead - the
* `model_instructions_file` override when one is set, otherwise the selected
* model's catalog row - and reported separately as `base`.
* - World-state sections are DIFF-rendered (`add_section` registers state, it does
* not emit text). A section that renders nothing on a first turn is missing
* from this output even though its layer exists.
* - The output reflects the invoking directory and the current config, not a
* universal prompt.
*/
import { spawn } from "node:child_process";
import { closeSync, constants, existsSync, fstatSync, openSync, readSync, statSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { expandUserPath } from "../config";
import { clearableDeadline, type ClearableDeadline } from "../lib/abort";
import { parseCatalogJson, readCodexCatalogPathForHome, type RawCatalog, type RawEntry } from "./catalog/parsing";
import {
CodexExecTrustError,
validatedCodexExecInvocationAsync,
type CodexExecBoundaryAsyncDeps,
} from "./exec-boundary";
import type { SpawnInvocation } from "../lib/win-exec";
import { resolveCodexHomeDir } from "./home";
import {
CODEX_PROGRAM_NOT_FOUND_REASON,
displayCodexRuntimePath,
resolveCodexRuntime,
type CodexRuntimeSource,
type ResolveCodexRuntimeResult,
} from "./runtime";
/**
* Layer id -> the tag Codex actually renders it under.
*
* Every entry here was read off live `codex debug prompt-input` output across the
* feature flags that enable each section. None is inferred from the Rust section
* `ID` constants: those are identifiers for diffing, not wrapper tags, and an
* earlier guess from them mapped `permissions` to the wrong name while the real
* tag - `permissions instructions`, with a space - went unmatched.
*
* A layer absent from this map is reported as unsupported, never as silent.
*/
const LAYER_SECTION_TAGS: Record<string, string> = {
skills: "skills_instructions",
apps: "apps_instructions",
plugins: "plugins_instructions",
// Context-dependent: it is absent when the active collaboration mode adds no
// instructions, but Codex wraps it in this tag when it does render.
collaboration: "collaboration_mode",
environment: "environment_context",
permissions: "permissions instructions",
// Synthetic: the project doc carries no tag of its own (see extractSections).
"agents-md": "__agents_md",
};
/**
* Inventory ids with no confirmed tag in the rendered output. They are listed
* explicitly rather than left missing: an absent entry made the dialog report a
* successful probe as unavailable.
*/
const UNMAPPED_LAYER_IDS = [
"model-switch",
"context-window-guidance",
"environments-instructions",
"tools",
"multi-agent-mode",
// Confirmed absent from live output under their own feature flags, so the
// previous `personality` / `realtime` guesses reported these as silent when the
// truth is that this extractor has no verified tag for them.
"personality",
"realtime",
// The Rust source names a <git_attribution> marker pair, but a world-state section is
// DIFF-rendered: it emits nothing on a turn where its state has not changed. Live
// `codex debug prompt-input` (codex-cli 0.145.0, 32978 bytes) showed no such block and
// no attribution text. Listing the id here reports "unmapped" honestly instead of
// claiming a tag this extractor has never actually matched - the same mistake the
// header above records for permissions.
"git-attribution",
] as const;
export interface LayerText {
/** Rendered text, when this layer produced a section on the probed turn. */
text: string | null;
/** Why the text is absent, when it is. */
reason: "ok" | "empty-source" | "not-rendered" | "not-exposed" | "unmapped" | "unavailable";
bytes: number;
/**
* `expanded` is text Codex sends as written. `template` is a catalog
* `instructions_template`, which Codex expands before sending. Absent for every
* layer read out of the probed output, whose text is rendered by definition.
*/
representation?: "expanded" | "template";
/**
* For `empty-source`: the file that exists but has nothing in it. For
* `base-instructions`: the configured file the base prompt was read from, or
* the one that could not be read.
*/
sourcePath?: string;
}
/**
* Why the base prompt is or is not readable, at the granularity a reader can act
* on. `LayerText.reason` has six coarse values and cannot express any of this,
* which is why the detailed answer travels on its own record.
*/
export type BasePromptReason =
| "ok"
| "config-not-found"
| "config-unreadable"
| "config-too-large"
| "model-not-selected"
| "model-not-found"
| "catalog-not-found"
| "catalog-unreadable"
| "catalog-too-large"
| "not-published"
| "override-empty"
| "override-not-found"
| "override-too-large"
| "override-unreadable";
export interface BasePromptText {
/** The base prompt, when a configured source published one. */
text: string | null;
reason: BasePromptReason;
bytes: number;
/** The model selected in `config.toml`, when the config named one. */
model: string | null;
/** The file the answer came from, when a file was reached at all. */
sourcePath: string | null;
/**
* `expanded` is the text Codex sends. `template` is a catalog
* `instructions_template`: a template even when it currently carries no
* placeholder, so it is never presented as the text the model receives.
*/
representation: "expanded" | "template" | "unavailable";
}
/**
* Why a probe failed, as a stable token the caller can branch on. The prose
* `detail` string is kept for display, but matching on it was never a contract:
* a caller that needs "is Codex installed at all" versus "Codex rejected the
* command" cannot get that from a sentence.
*/
export type PromptProbeFailureKind =
| "program-not-found"
| "command-unsupported"
| "execution-failed"
| "output-invalid";
export interface PromptProbeFailure {
kind: PromptProbeFailureKind;
/** The command line that was attempted or resolved, for display. */
command: string;
/**
* A short fixed phrase plus the command - never captured process output.
* Codex stderr can carry the user's config path, model name, or environment
* details, and this response is served over the management API, so raw
* process output does not belong in it.
*/
detail: string;
}
export interface PromptTextProbe {
ok: boolean;
/** The Codex home the probe reported on. */
codexHome: string;
layers: Record<string, LayerText>;
/**
* The base prompt, read from configuration rather than from the probed output.
* Present on every outcome: it is computed before the subprocess, so it answers
* even when Codex cannot be resolved, the probe fails, or the caller cancels.
*/
base: BasePromptText;
/** The runtime the probe resolved and tried, when resolution produced one. */
runtime?: { command: string; source: CodexRuntimeSource };
/** Stable failure classification; `detail` remains the display string. */
failure?: PromptProbeFailure;
detail?: string;
}
/** 8 MiB is far above any real prompt and far below anything that hurts the server. */
const MAX_PROBE_OUTPUT_BYTES = 8 * 1024 * 1024;
/** stderr is captured only to classify the failure, never to echo back. */
const MAX_PROBE_STDERR_BYTES = 64 * 1024;
/** Read chunk for local prompt sources; the ceiling is MAX_PROBE_OUTPUT_BYTES. */
const PROMPT_SOURCE_CHUNK_BYTES = 64 * 1024;
function errorWithCode(message: string, code: string): NodeJS.ErrnoException {
const error = new Error(message) as NodeJS.ErrnoException;
error.code = code;
return error;
}
function errorCodeOf(error: unknown): string | undefined {
return (error as NodeJS.ErrnoException | null)?.code;
}
/**
* Read one configured prompt source, bounded, from a single descriptor.
*
* Three properties are load-bearing, and all three are about this running
* synchronously on the Bun request thread:
*
* - `O_NONBLOCK` is set BEFORE anything else. `openSync(path, "r")` on a FIFO with
* no writer blocks forever, and nothing can recover it: the probe timeout and
* request cancellation both need the event loop this call is holding. Windows
* has no such flag, so the constant is absent there and contributes nothing.
* - The regular-file check reads `fstatSync` on the OPENED descriptor. A path stat
* describes whatever the name pointed at a moment ago, not what got opened.
* - The ceiling is enforced while reading, not from a preflight size. A
* stat-then-read pair is a window in which the file can change, and it would let
* an unbounded body through into a management-API response.
*/
function readBoundedPromptSource(path: string): string {
// `O_NONBLOCK` is POSIX-only: Windows omits it from `fs.constants` even though the
// type declares it, so it is read defensively and contributes nothing there.
const nonBlocking = (constants as { O_NONBLOCK?: number }).O_NONBLOCK ?? 0;
const descriptor = openSync(path, constants.O_RDONLY | nonBlocking);
try {
if (!fstatSync(descriptor).isFile()) {
throw errorWithCode(`prompt source is not a regular file: ${path}`, "EFTYPE");
}
const parts: Buffer[] = [];
const view = Buffer.allocUnsafe(PROMPT_SOURCE_CHUNK_BYTES);
let total = 0;
for (;;) {
const read = readSync(descriptor, view, 0, view.length, total);
if (read === 0) break;
total += read;
// One byte past the ceiling is the whole answer: refuse before the content
// is retained, so an oversized source costs no more than a bounded read.
if (total > MAX_PROBE_OUTPUT_BYTES) {
throw errorWithCode(`prompt source exceeds ${MAX_PROBE_OUTPUT_BYTES} bytes: ${path}`, "EFBIG");
}
parts.push(Buffer.from(view.subarray(0, read)));
}
return Buffer.concat(parts).toString("utf8");
} finally {
try { closeSync(descriptor); } catch { /* the descriptor is already unusable */ }
}
}
function unavailableBase(
reason: BasePromptReason,
model: string | null = null,
sourcePath: string | null = null,
): BasePromptText {
return { text: null, reason, bytes: 0, model, sourcePath, representation: "unavailable" };
}
function readableBase(
text: string,
representation: "expanded" | "template",
model: string,
sourcePath: string,
): BasePromptText {
return { text, reason: "ok", bytes: Buffer.byteLength(text, "utf8"), model, sourcePath, representation };
}
function publishedString(entry: RawEntry, key: string): string | null {
const value = entry[key];
return typeof value === "string" && value.length > 0 ? value : null;
}
/**
* The base prompt for the configured model, read from the same files Codex reads.
*
* Precedence follows Codex: `model_instructions_file` replaces the base prompt
* outright, so an override that is set decides the answer whether or not it can be
* read. Without one, the selected catalog row's `base_instructions` is the
* published text, and `model_messages.instructions_template` is the fallback -
* reported as a template, because that is what it is.
*
* Every failure is a reason, never an exception: this feeds a GET that must
* degrade to "we could not read it" rather than to a 500.
*/
function readBasePrompt(codexHome: string): BasePromptText {
const configPath = join(codexHome, "config.toml");
let configText: string;
try {
configText = readBoundedPromptSource(configPath);
} catch (error) {
// ENOENT is "no config"; anything else is "the config we have could not be
// read". `existsSync` cannot separate those: it races the read, and it reports
// a permission failure as absence.
const code = errorCodeOf(error);
return unavailableBase(
code === "ENOENT" ? "config-not-found" : code === "EFBIG" ? "config-too-large" : "config-unreadable",
);
}
let root: Record<string, unknown>;
try {
const parsed = Bun.TOML.parse(configText);
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("config.toml is not a table");
root = parsed as Record<string, unknown>;
} catch {
// The WHOLE document has to parse before any key from it is trusted. Codex
// rejects a malformed config outright, so a model scraped out of the readable
// first lines would make this display a prompt that is never sent.
return unavailableBase("config-unreadable", null, configPath);
}
const configuredModel = typeof root.model === "string" ? root.model.trim() : "";
// A `model_instructions_file` with no model is out of scope here: the base
// prompt this reports on is the selected model's, and there is no selection.
if (!configuredModel) return unavailableBase("model-not-selected", null, configPath);
const model = configuredModel;
const override = typeof root.model_instructions_file === "string" ? root.model_instructions_file : null;
if (override !== null) {
// A blank value names no file. The key is still set, so Codex does not fall
// back to the catalog default and neither does this: reporting the catalog row
// would describe a base prompt this configuration never produces.
if (override.trim().length === 0) return unavailableBase("override-not-found", model);
// Relative to the config file's own directory, which is how the rest of this
// repository resolves the key.
const overridePath = resolve(dirname(configPath), expandUserPath(override));
let text: string;
try {
text = readBoundedPromptSource(overridePath);
} catch (error) {
const code = errorCodeOf(error);
return unavailableBase(
code === "ENOENT" ? "override-not-found" : code === "EFBIG" ? "override-too-large" : "override-unreadable",
model,
overridePath,
);
}
// Codex rejects this config with "model instructions file is empty", so
// reporting `ok` here would claim text that is never sent - and claim it for a
// configuration that does not start.
if (text.trim().length === 0) return unavailableBase("override-empty", model, overridePath);
return readableBase(text, "expanded", model, overridePath);
}
const catalogPath = readCodexCatalogPathForHome(codexHome, configText);
let catalog: RawCatalog | null;
try {
catalog = parseCatalogJson(readBoundedPromptSource(catalogPath));
} catch (error) {
const code = errorCodeOf(error);
return unavailableBase(
code === "ENOENT" ? "catalog-not-found" : code === "EFBIG" ? "catalog-too-large" : "catalog-unreadable",
model,
catalogPath,
);
}
if (!catalog) return unavailableBase("catalog-unreadable", model, catalogPath);
// Each candidate is guarded rather than trusted: `parseCatalogJson` validates
// only that `models` is an array, so a row of `null` would throw on property
// access and turn this read into a 500 on the management API.
const entry = catalog.models?.find(candidate => (
candidate !== null
&& typeof candidate === "object"
&& !Array.isArray(candidate)
&& (candidate.slug === model || candidate.id === model)
)) ?? null;
if (!entry) return unavailableBase("model-not-found", model, catalogPath);
const published = publishedString(entry, "base_instructions");
if (published) return readableBase(published, "expanded", model, catalogPath);
const messages = entry.model_messages;
const template = messages !== null && typeof messages === "object" && !Array.isArray(messages)
? publishedString(messages as RawEntry, "instructions_template")
: null;
if (template) return readableBase(template, "template", model, catalogPath);
return unavailableBase("not-published", model, catalogPath);
}
/**
* Project the base prompt onto the legacy `base-instructions` layer slot.
*
* The slot is lossy by construction - six coarse reasons, no renderer that reads
* `representation` - so it carries only what it can carry honestly: published text
* when the source is text Codex sends, and otherwise no text at all. A template is
* deliberately NOT `ok` here, because the dialog labels every `ok` layer "Text
* sent to the model" and an unexpanded template is not that. The detailed answer
* stays on `base`.
*/
function promptLayerForBase(base: BasePromptText): LayerText {
const source = base.sourcePath ? { sourcePath: base.sourcePath } : {};
if (base.reason === "ok" && base.text !== null && base.representation === "expanded") {
return { text: base.text, reason: "ok", bytes: base.bytes, representation: "expanded", ...source };
}
if (base.reason === "ok") return { text: null, reason: "not-exposed", bytes: 0, representation: "template", ...source };
return { text: null, reason: "unavailable", bytes: 0, ...source };
}
interface ProbeCommand {
binary: string;
args: string[];
cwd: string;
timeoutMs: number;
promptStateFingerprint: string | null;
}
interface PromptProbeFlight {
key: string;
controller: AbortController;
result: Promise<PromptProbeExecutionResult | null>;
closed: Promise<void>;
waiters: number;
joinable: boolean;
resultSettled: boolean;
settled: boolean;
}
interface PromptProbeExecution {
result: Promise<PromptProbeExecutionResult | null>;
closed: Promise<void>;
}
/**
* The process outcome travels with its classification so a shared flight hands
* every joined caller the same `failure`, not just the same null.
*/
interface PromptProbeExecutionResult {
raw: string | null;
failure: PromptProbeFailure | null;
}
type SharedPromptProbeOutcome =
| { kind: "output"; raw: string }
| { kind: "failed"; failure?: PromptProbeFailure }
| { kind: "busy" };
/**
* The fixed phrase that distinguishes a deadline expiry from every other
* termination. The shared flight's timer and a caller's own deadline both
* report it, so a waiter can tell "the budget ran out" from "the probe was
* stopped" without reading process output - which this response never carries.
*/
const PROMPT_PROBE_TIMEOUT_PHRASE = "codex prompt probe timed out";
let activePromptProbe: PromptProbeFlight | null = null;
let probeCommandForTests: { binary: string; args: string[] } | null = null;
let probeRuntimeForTests: { command: string; source: CodexRuntimeSource } | null | undefined;
let probeSpawnAttemptsForTests = 0;
let probeCloseBarrierForTests: Promise<void> | null = null;
let probeExecBoundaryDepsForTests: CodexExecBoundaryAsyncDeps | null = null;
let probeMetadataBarrierForTests: Promise<void> | null = null;
function commandKey(command: ProbeCommand): string {
return JSON.stringify([
command.binary,
command.args,
command.cwd,
command.timeoutMs,
command.promptStateFingerprint,
]);
}
function completedExecution(value: PromptProbeExecutionResult | null): PromptProbeExecution {
return { result: Promise.resolve(value), closed: Promise.resolve() };
}
/**
* The command line as it may be shown to a caller.
*
* Redacted, because this response is served over the management API and a
* resolved Codex path is a user path: the Windows Codex App lives under the
* profile directory, so echoing the raw command would put the account name in
* a diagnostic. `displayCodexRuntimePath` is the same helper the runtime log
* line and doctor output already use, so the probe reports a path in the form
* the rest of the product reports it.
*/
function commandDescription(command: ProbeCommand): string {
return [displayCodexRuntimePath(command.binary), ...command.args].join(" ");
}
function probeFailure(
command: ProbeCommand,
kind: PromptProbeFailureKind,
detail: string,
): PromptProbeFailure {
return { kind, command: commandDescription(command), detail };
}
/**
* A non-zero exit whose stderr reports an unknown subcommand means the resolved
* binary is a Codex too old (or too new) for `debug prompt-input` - a different
* remedy than "the process died". The stderr text itself is used only for this
* check; it never enters the response.
*/
function classifyProcessFailure(command: ProbeCommand, code: number | null, stderr: string): PromptProbeFailure {
const lower = stderr.toLowerCase();
const unsupported =
(/unrecognized|unknown|unexpected|invalid/.test(lower) && /subcommand|command|argument|option/.test(lower))
|| /usage:/.test(lower);
const kind: PromptProbeFailureKind = unsupported ? "command-unsupported" : "execution-failed";
const phrase = unsupported
? "codex does not support this probe command"
: `codex probe exited with code ${code ?? "unknown"}`;
return probeFailure(command, kind, `${phrase}: ${commandDescription(command)}`);
}
/**
* The resolver reports why each candidate lost. A candidate that is simply not
* there (issue 4458's repeated "path does not exist" on Windows) is a
* program-not-found; a candidate that exists but could not be probed is an
* execution problem on an installed program.
*/
function classifyRuntimeFailure(result: ResolveCodexRuntimeResult): PromptProbeFailure {
const isNotFound = (reason: string) =>
reason === CODEX_PROGRAM_NOT_FOUND_REASON || /does not exist|not found|ENOENT/i.test(reason);
const representative = result.failures.find(item => !isNotFound(item.reason))
?? result.failures[0];
const kind: PromptProbeFailureKind = !representative || isNotFound(representative.reason)
? "program-not-found"
: "execution-failed";
// Same redaction obligation as commandDescription: a rejected candidate is a
// real filesystem path, and every one of them is reported to the caller.
const command = displayCodexRuntimePath(representative?.command ?? result.runtime.command);
const phrase = kind === "program-not-found" ? "codex program not found" : "codex runtime could not be probed";
return { kind, command, detail: `${phrase}: ${command}` };
}
function runProbe(
command: ProbeCommand,
controller: AbortController,
onStopping: () => void,
): PromptProbeExecution {
const signal = controller.signal;
if (signal.aborted) return completedExecution({ raw: null, failure: null });
let resolveResult!: (value: PromptProbeExecutionResult | null) => void;
let resolveClosed!: () => void;
const result = new Promise<PromptProbeExecutionResult | null>(resolve => { resolveResult = resolve; });
const closed = new Promise<void>(resolve => { resolveClosed = resolve; });
let resultSettled = false;
let closeSettled = false;
const finishResult = (value: PromptProbeExecutionResult | null) => {
if (resultSettled) return;
resultSettled = true;
resolveResult(value);
};
const finishClosed = () => {
if (closeSettled) return;
closeSettled = true;
resolveClosed();
};
// One deadline covers trust verification AND the probe child. The timer
// aborts the flight controller rather than terminating directly, so the
// signal reaches an in-flight trust check (which must stop and reap its own
// helper) exactly like it reaches the probe child. The slot is never
// released while a verification promise is still unsettled.
let child: ReturnType<typeof spawn> | undefined;
let settled = false;
let stopping = false;
let stoppingFailure: PromptProbeFailure | null = null;
let timer: ReturnType<typeof setTimeout> | undefined;
const finish = (value: PromptProbeExecutionResult) => {
if (settled) return;
settled = true;
if (timer) clearTimeout(timer);
signal.removeEventListener("abort", onAbort);
finishResult(value);
finishClosed();
};
// Keep the flight admitted until `close`: kill() only requests termination
// and does not prove the exact child has released its process and stdio.
const terminate = (
failure = probeFailure(
command,
"execution-failed",
// The flight timer aborts with a TimeoutError; every other abort reason
// is a stop, not an expired budget. Callers match on the fixed phrase to
// report "timed out" instead of a generic termination.
signal.reason instanceof DOMException && signal.reason.name === "TimeoutError"
? `${PROMPT_PROBE_TIMEOUT_PHRASE}: ${commandDescription(command)}`
: `codex probe was terminated: ${commandDescription(command)}`,
),
) => {
if (settled || stopping) return;
stopping = true;
stoppingFailure = failure;
onStopping();
if (timer) clearTimeout(timer);
signal.removeEventListener("abort", onAbort);
child?.stdout?.destroy();
// The caller is bounded even if OS termination later fails. Admission is
// retained separately by `closed`, and later probes fail soft while this
// exact execution remains unproven terminal.
finishResult({ raw: null, failure });
if (!child || child.exitCode !== null || child.signalCode !== null) return;
try {
child.kill("SIGKILL");
} catch {
// Exact child state is ambiguous. Keep admission non-joinable until its
// own `close` proves terminal instead of targeting a reusable numeric PID.
}
};
const onAbort = () => terminate();
const start = async () => {
// The flight owns trust verification too: it runs under the shared
// deadline and the controller's abort, and a rejected target becomes this
// flight's shared failure instead of spawning beside the single slot.
let invocation: SpawnInvocation;
try {
invocation = await validatedCodexExecInvocationAsync(command.binary, command.args, {
env: process.env,
cwd: command.cwd,
signal,
...(probeExecBoundaryDepsForTests ?? {}),
});
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
finish({
raw: null,
failure: probeFailure(
command,
error instanceof CodexExecTrustError
? "execution-failed"
: /ENOENT|not found/i.test(message) ? "program-not-found" : "execution-failed",
`codex probe could not start: ${commandDescription(command)}`,
),
});
return;
}
if (stopping || settled) {
// Terminated while verification was in flight; its await has now settled
// and no probe child exists, so the slot can be released.
finishClosed();
return;
}
// A probe must never hang OR balloon the management API: it is bounded in
// time AND in bytes, and every failure degrades to "unavailable" rather
// than an error page.
try {
if (probeCommandForTests) probeSpawnAttemptsForTests += 1;
child = spawn(invocation.file, invocation.args, {
cwd: command.cwd,
stdio: ["ignore", "pipe", "pipe"],
windowsHide: true,
...invocation.options,
});
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
finish({
raw: null,
failure: probeFailure(
command,
/ENOENT|not found/i.test(message) ? "program-not-found" : "execution-failed",
`codex probe could not start: ${commandDescription(command)}`,
),
});
return;
}
const proc = child;
const chunks: Buffer[] = [];
const errorChunks: Buffer[] = [];
let size = 0;
let errorSize = 0;
proc.stdout?.on("data", (chunk: Buffer) => {
size += chunk.length;
if (size > MAX_PROBE_OUTPUT_BYTES) { terminate(); return; }
chunks.push(chunk);
});
proc.stderr?.on("data", (chunk: Buffer) => {
errorSize += chunk.length;
if (errorSize <= MAX_PROBE_STDERR_BYTES) errorChunks.push(chunk);
});
proc.on("error", error => {
// No PID means spawn itself failed, so there is no live child to drain.
if (proc.pid === undefined) {
const message = error instanceof Error ? error.message : String(error);
finish({
raw: null,
failure: probeFailure(
command,
/ENOENT|not found/i.test(message) ? "program-not-found" : "execution-failed",
`codex probe could not start: ${commandDescription(command)}`,
),
});
}
else terminate(probeFailure(
command,
"execution-failed",
`codex probe process error: ${commandDescription(command)}`,
));
});
proc.on("close", code => {
// Decode once, at the end: `String(chunk)` per chunk corrupts any UTF-8
// character that straddles a chunk boundary.
const recordClose = () => {
if (stopping) {
finish({
raw: null,
failure: stoppingFailure ?? probeFailure(
command,
"execution-failed",
`codex probe was terminated: ${commandDescription(command)}`,
),
});
} else if (code === 0) {
finish({ raw: Buffer.concat(chunks).toString("utf8"), failure: null });
} else {
finish({
raw: null,
failure: classifyProcessFailure(command, code, Buffer.concat(errorChunks).toString("utf8")),
});
}
};
const barrier = probeCloseBarrierForTests;
if (barrier) void barrier.then(recordClose, recordClose);
else recordClose();
});
// Close the race between the pre-spawn check and listener registration.
if (signal.aborted) terminate();
};
timer = setTimeout(() => {
// Abort rather than terminate directly so the signal also reaches a trust
// check that is still running: it must stop and reap its helper before the
// flight releases the slot.
controller.abort(new DOMException("prompt probe timed out", "TimeoutError"));
}, command.timeoutMs);
signal.addEventListener("abort", onAbort, { once: true });
void start().catch(() => {
finish({
raw: null,
failure: probeFailure(
command,
"execution-failed",
`codex probe failed: ${commandDescription(command)}`,
),
});
});
return { result, closed };
}
function startPromptProbeFlight(command: ProbeCommand): PromptProbeFlight {
const controller = new AbortController();
const flight: PromptProbeFlight = {
key: commandKey(command),
controller,
result: Promise.resolve(null),
closed: Promise.resolve(),
waiters: 0,
joinable: true,
resultSettled: false,
settled: false,
};
const execution = runProbe(command, controller, () => {
flight.joinable = false;
});
flight.result = execution.result
.catch(() => null)
.finally(() => {
flight.resultSettled = true;
});
flight.closed = execution.closed
.finally(() => {
flight.settled = true;
if (activePromptProbe === flight) activePromptProbe = null;
});
activePromptProbe = flight;
return flight;
}
async function runSharedPromptProbe(
command: ProbeCommand,
signal?: AbortSignal,
): Promise<SharedPromptProbeOutcome> {
const key = commandKey(command);
if (signal?.aborted) return { kind: "failed" };
const active = activePromptProbe;
if (!active) {
// The new flight claims the sole slot synchronously, before any await:
// trust verification runs inside it under the probe deadline, and a
// rejected target becomes the flight's shared failure for every joiner.
const result = await waitForPromptProbeFlight(startPromptProbeFlight(command), signal);
if (!result) return { kind: "failed" };
if (result.failure) return { kind: "failed", failure: result.failure };
return result.raw === null ? { kind: "failed" } : { kind: "output", raw: result.raw };
}
if (active.key === key && active.joinable && !active.controller.signal.aborted) {
const result = await waitForPromptProbeFlight(active, signal);
if (!result) return { kind: "failed" };
if (result.failure) return { kind: "failed", failure: result.failure };
return result.raw === null ? { kind: "failed" } : { kind: "output", raw: result.raw };
}
// A different or terminating flight still owns the sole process slot. Never
// wait unboundedly for an unproven close and never launch beside it.
return { kind: "busy" };
}
async function waitForPromptProbeFlight(
flight: PromptProbeFlight,
signal?: AbortSignal,
): Promise<PromptProbeExecutionResult | null> {
if (signal?.aborted) {
if (flight.waiters === 0 && !flight.settled) flight.controller.abort();
return null;
}
flight.waiters += 1;
let onAbort: (() => void) | undefined;
try {
if (!signal) return await flight.result;
const aborted = new Promise<PromptProbeExecutionResult | null>(resolve => {
onAbort = () => resolve(null);
signal.addEventListener("abort", onAbort, { once: true });
if (signal.aborted) onAbort();
});
return await Promise.race([flight.result, aborted]);
} finally {
if (onAbort) signal?.removeEventListener("abort", onAbort);
flight.waiters = Math.max(0, flight.waiters - 1);
if (flight.waiters === 0 && !flight.resultSettled) {
flight.controller.abort(new DOMException("All prompt probe callers cancelled", "AbortError"));
}
}
}
/** Pull every `<tag>...</tag>` section out of the rendered developer messages. */
function extractSections(raw: string): Map<string, string> {
const sections = new Map<string, string>();
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return sections;
}
if (!Array.isArray(parsed)) return sections;
for (const item of parsed) {
if (!item || typeof item !== "object" || Array.isArray(item)) continue;
const content = (item as { content?: unknown }).content;
if (!Array.isArray(content)) continue;
const text = content.map(part => {
if (!part || typeof part !== "object" || Array.isArray(part)) return "";
const value = (part as { text?: unknown }).text;
return typeof value === "string" ? value : "";
}).join("");
// Tag names are NOT all snake_case: Codex renders `<permissions instructions>`
// with a space. A `[a-z_]+` pattern silently skipped it, and the layer was
// reported as "sent nothing" while its text sat right there.
for (const match of text.matchAll(/<([a-zA-Z_][a-zA-Z0-9_ -]*)>([\s\S]*?)<\/\1>/g)) {
sections.set(match[1]!, match[2]!.trim());
}
// AGENTS.md is NOT tagged: it arrives as a `# AGENTS.md instructions`
// block among the tagged sections. Matching only on tags would report the
// layer as unrendered while its text sits in the same message.
//
// Bounded at both ends. Capturing to end-of-message swept up any unrelated
// untagged prose that happened to follow, and stripping tag-shaped blocks
// first also deleted XML-like text the user had written INSIDE their own
// AGENTS.md. Codex wraps the body in <INSTRUCTIONS>, so that is the boundary.
// No line anchor: the block is concatenated directly onto the previous
// section's closing tag, so requiring a newline before it never matched.
//
// The `for <path>` suffix is OPTIONAL. Upstream emits three shapes from
// `contextual_user_fragment().render()` (core/src/context.rs) and this has
// to read all three rather than the one that existed when the probe was
// written: the legacy single-root form `# AGENTS.md instructions for
// <dir>`, the no-directory form `# AGENTS.md instructions`, and the
// multi-environment form where each project's block is labeled `for \`<env>\`
// with root <cwd>` INSIDE the INSTRUCTIONS wrapper. The labels are part of
// what the model sees, so they stay in the captured body.
const projectDoc = /# AGENTS\.md instructions(?: for [^\n]*)?\n+<INSTRUCTIONS>\n?([\s\S]*?)\n?<\/INSTRUCTIONS>/.exec(text);
if (projectDoc) sections.set("__agents_md", projectDoc[1]!.trim());
else if (/# AGENTS\.md instructions/.test(text)) {
// The header rendered but in a shape this extractor does not recognize -
// a future upstream format, or prose truncated by the output cap. Claiming
// the layer "sent nothing" would be a lie about a block that is plainly
// present; the sentinel maps it to `unmapped`, the existing honest answer
// for "rendered in a form we cannot show".
sections.set("__agents_md_unmatched", "");
}
}
return sections;
}
/** Test seam: the extraction is the part worth pinning, not the spawn. */
export const extractSectionsForTests = extractSections;
function mapSectionsToLayers(sections: Map<string, string>): Record<string, LayerText> {
const layers: Record<string, LayerText> = {};
for (const [layerId, tag] of Object.entries(LAYER_SECTION_TAGS)) {
const text = sections.get(tag) ?? null;
layers[layerId] = text === null
// Registered but not rendered on this turn, which is an ordinary state for
// a diff-rendered section rather than an error.
? { text: null, reason: "not-rendered", bytes: 0 }
: { text, reason: "ok", bytes: Buffer.byteLength(text, "utf8") };
}
// `__agents_md_unmatched` is the sentinel for "the AGENTS.md header rendered in
// a shape the bounded extractor does not recognize". `unmapped` is the honest
// answer for it: the text exists but cannot be shown, which `not-rendered`
// would deny outright.
if (layers["agents-md"]?.reason === "not-rendered" && sections.has("__agents_md_unmatched")) {
layers["agents-md"] = { text: null, reason: "unmapped", bytes: 0 };
}
return layers;
}
/** Test seam: pin section-to-layer projection independently of the subprocess. */
export const mapSectionsToLayersForTests = mapSectionsToLayers;
/**
* Probe once and map every known layer to its rendered text.
*
* `cwd` matters: AGENTS.md and environment context are directory-dependent, so a
* probe from the wrong place would describe a prompt the user never sees.
*/
export async function probePromptText(
timeoutMs = 15_000,
signal?: AbortSignal,
promptStateFingerprint: string | null = null,
): Promise<PromptTextProbe> {
// Metadata time counts against the caller budget; synchronous reads cannot
// be interrupted, so expiry blocks admission after they return. Waiting and
// trust verification are cancellable. The flight keeps its fixed deadline:
// caller expiry ends only that wait, without extending the shared backstop.
// The child also stops on output overflow, process errors or last-waiter exit.
const deadlineAt = Date.now() + timeoutMs;
const deadline = clearableDeadline(timeoutMs, signal);
try {
const result = await probePromptTextWithinDeadline(timeoutMs, deadlineAt, deadline, promptStateFingerprint);
if (!deadline.didExpire()) return result;
const command = `${result.runtime?.command ?? "codex"} debug prompt-input`;
return {
...result,
ok: false,
detail: "prompt probe timed out",
failure: {
kind: "execution-failed",
command,
detail: `${PROMPT_PROBE_TIMEOUT_PHRASE}: ${command}`,
},
};
} finally {
deadline.clear();
}
}
async function probePromptTextWithinDeadline(
timeoutMs: number,
deadlineAt: number,
deadline: ClearableDeadline,
promptStateFingerprint: string | null,
): Promise<PromptTextProbe> {
const signal = deadline.signal;
// The probe runs in CODEX_HOME, never in a caller-supplied directory. A `cwd`
// parameter let an authenticated request read any readable folder's AGENTS.md,
// and it also described a prompt that depends on where Codex happened to run.
// The global home is the one context this page can honestly report on.
const codexHome = resolveCodexHomeDir();
// Read before anything is spawned. The base prompt comes from files this process
// reads itself, so binding it to the subprocess would lose the one layer the
// probed output never carries the moment Codex is missing, slow, or cancelled.
const base = readBasePrompt(codexHome);
const baseLayers = { "base-instructions": promptLayerForBase(base) };
if (signal?.aborted) {
return { ok: false, codexHome, layers: { ...baseLayers }, base, detail: "prompt probe cancelled" };
}
// Resolve through the shared runtime resolver, not a private path list: the
// old four-path POSIX check could never match the Codex App's Windows install
// under %LOCALAPPDATA%\OpenAI\Codex\bin\<version>, so the probe reported
// "not found" on machines where Codex was plainly installed (issue 4458).
//
// Both flags are deliberate. This runs on a request path: discoverAlternatives
// would walk the whole PATH just to fill a newerAvailable diagnostic the probe
// never shows, and probeVersion would pay a blocking `--version` exec per
// candidate. The probe needs a command it can spawn; the version is irrelevant.
const resolved = probeCommandForTests || probeRuntimeForTests !== undefined
? null
: resolveCodexRuntime({ discoverAlternatives: false, probeVersion: false });
const runtime: { command: string; source: CodexRuntimeSource } | undefined =
probeRuntimeForTests !== undefined
? probeRuntimeForTests ?? undefined
: resolved && resolved.runtime.source !== "fallback"
? { command: resolved.runtime.command, source: resolved.runtime.source }
: undefined;
// A `fallback` result is the resolver saying "nothing concrete was found" -
// its command is the bare word "codex", not a located binary. Reporting it as
// resolved would just relabel the same not-found as a spawn failure.
const binary = probeCommandForTests?.binary ?? runtime?.command ?? null;
// The response travels over the management API, so the reported runtime is
// redacted while `binary` keeps the real path the spawn needs. On Windows the
// Codex App install sits under the user's profile directory, so the raw
// command carries the account name.
const reportedRuntime = runtime
? { command: displayCodexRuntimePath(runtime.command), source: runtime.source }
: undefined;
if (!binary) {
const failure = resolved
? classifyRuntimeFailure(resolved)
: probeFailure(
{ binary: "codex", args: ["debug", "prompt-input"], cwd: codexHome, timeoutMs, promptStateFingerprint },
"program-not-found",
"codex program not found: codex debug prompt-input",
);
return {
ok: false,
codexHome,
layers: { ...baseLayers },
base,
...(reportedRuntime ? { runtime: reportedRuntime } : {}),
failure,
detail: "codex binary not found",
};
}
const command: ProbeCommand = {
binary,
args: probeCommandForTests?.args ?? ["debug", "prompt-input"],
cwd: codexHome,
timeoutMs,
promptStateFingerprint,
};
// The absolute check complements the abort signal: a synchronous metadata
// read that consumed the whole budget starves the timer callback, so the
// signal can still be quiet here after the absolute deadline passed. An
// expired caller must never start a flight.
const metadataBarrier = probeMetadataBarrierForTests;
if (metadataBarrier) await metadataBarrier;
if (signal.aborted && !deadline.didExpire()) {
return {
ok: false,
codexHome,
layers: { ...baseLayers },
base,
...(reportedRuntime ? { runtime: reportedRuntime } : {}),
detail: "prompt probe cancelled",
};
}
if (deadline.didExpire() || Date.now() >= deadlineAt) {
return {
ok: false,
codexHome,
layers: { ...baseLayers },
base,
...(reportedRuntime ? { runtime: reportedRuntime } : {}),
detail: "prompt probe timed out",
failure: probeFailure(
command,
"execution-failed",
`${PROMPT_PROBE_TIMEOUT_PHRASE}: ${commandDescription(command)}`,
),
};
}
const outcome = await runSharedPromptProbe(command, signal);
if (outcome.kind !== "output") {
return {
ok: false,
codexHome,
layers: { ...baseLayers },
base,
...(reportedRuntime ? { runtime: reportedRuntime } : {}),
...(outcome.kind === "failed" && outcome.failure ? { failure: outcome.failure } : {}),
detail: signal?.aborted
? "prompt probe cancelled"
: outcome.kind === "busy"
? "another prompt probe is still finishing; retry shortly"
: outcome.kind === "failed" && outcome.failure?.detail.startsWith(PROMPT_PROBE_TIMEOUT_PHRASE)
? "prompt probe timed out"
: "codex debug prompt-input failed",
};
}
const raw = outcome.raw;
const sections = extractSections(raw);
if (sections.size === 0) {
// Zero sections from a zero-exit probe means the output did not parse, which
// is a failed read - not fifteen layers that each chose to send nothing.
return {
ok: false,
codexHome,
layers: { ...baseLayers },
base,
...(reportedRuntime ? { runtime: reportedRuntime } : {}),
failure: probeFailure(
command,
"output-invalid",
`codex prompt output could not be parsed: ${commandDescription(command)}`,
),
detail: "prompt output could not be parsed",
};
}
const layers = mapSectionsToLayers(sections);
// A file that exists and is empty is not the same as a layer that chose to send
// nothing. Reporting "sent nothing" for an empty AGENTS.md tells the user their
// layer is idle when the real answer is that the file they wrote is blank.
const agentsMdPath = join(codexHome, "AGENTS.md");
if (layers["agents-md"]?.reason === "not-rendered" && existsSync(agentsMdPath)) {
try {
if (statSync(agentsMdPath).size === 0) {
layers["agents-md"] = { text: null, reason: "empty-source", bytes: 0, sourcePath: agentsMdPath };
}
} catch {
// An unreadable file stays "not-rendered": we cannot claim it is empty.
}
}
// Read from configuration above, not from this output: Codex discards
// `base_instructions` before rendering `prompt.input`.
Object.assign(layers, baseLayers);
// Layers whose rendered tag we have not confirmed against live output. Leaving
// them absent made the GUI fall through to "unavailable", which claims the probe
// failed when it succeeded. Keep this distinct from the base prompt's
// "not-exposed", which is confirmed to travel outside the printable message
// list - reusing it showed a base-prompt-specific explanation for unrelated
// layers.
for (const id of UNMAPPED_LAYER_IDS) {
layers[id] ??= { text: null, reason: "unmapped", bytes: 0 };
}
return { ok: true, codexHome, layers, base, ...(reportedRuntime ? { runtime: reportedRuntime } : {}) };
}
/** Test-only command seam; production always resolves the installed Codex binary. */
export function setPromptTextProbeCommandForTests(command: { binary: string; args: string[] } | null): void {
probeCommandForTests = command ? { binary: command.binary, args: [...command.args] } : null;
}
/** Test-only runtime seam: stands in for the shared resolver's answer. */
export function setPromptTextProbeRuntimeForTests(
runtime: { command: string; source: CodexRuntimeSource } | null | undefined,
): void {
probeRuntimeForTests = runtime;
}
/** Test-only process-start counter for proving admission without timing guesses. */
export function promptTextProbeSpawnAttemptsForTests(): number {
return probeSpawnAttemptsForTests;
}
/** Test-only close barrier for proving admission is not released at process exit. */
export function setPromptTextProbeCloseBarrierForTests(barrier: Promise<void> | null): void {
probeCloseBarrierForTests = barrier;
}
/** Test-only metadata-phase barrier; models elapsed work before flight admission. */
export function setPromptTextProbeMetadataBarrierForTests(barrier: Promise<void> | null): void {
probeMetadataBarrierForTests = barrier;
}
/** Test-only exec-boundary dep seam; production resolves the real environment. */
export function setPromptTextProbeExecBoundaryDepsForTests(deps: CodexExecBoundaryAsyncDeps | null): void {
probeExecBoundaryDepsForTests = deps;
}
/** Test-only fail-closed drain so one failed lifecycle case cannot poison another. */
export async function resetPromptTextProbeForTests(): Promise<void> {
const active = activePromptProbe;
if (active && !active.settled) {
active.controller.abort(new DOMException("Prompt probe test reset", "AbortError"));
const drained = await Promise.race([
active.closed.then(() => true),
Bun.sleep(2_000).then(() => false),
]);
if (!drained) throw new Error("prompt probe child did not close during test reset");
}
if (activePromptProbe === active) activePromptProbe = null;
probeCommandForTests = null;
probeRuntimeForTests = undefined;
probeSpawnAttemptsForTests = 0;
probeCloseBarrierForTests = null;
probeExecBoundaryDepsForTests = null;
probeMetadataBarrierForTests = null;
}