@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,673 lines • 80.4 kB
text/typescript
/**
* features.ts — codex feature-flag view for $CODEX_HOME/config.toml.
*
* Scope boundary: this module mirrors only the flags opencodex has to READ
* directly from config.toml:
* - `multi_agent_v2`, because opencodex migrates its concurrency value across
* the v1/v2 boundary and exposes the multi-agent config surface;
* - `default_mode_request_user_input` (Codex Auth page toggle), because the
* management API needs a live reader for the flag it manages.
* Every other upstream feature flag is delegated to the native `codex features`
* command (see src/cli/v2.ts) and must not be hardcoded here.
*
* Upstream reshapes flags freely: in the 1f0566d3f..5a1097ed2 range alone,
* `code_mode_host` changed from a boolean to a table (it is Stage::Stable and
* default-enabled upstream), `enable_fanout` and `item_ids` were retired to
* Stage::Removed ("useless but kept for backward compatibility"), and several
* under-development flags were added. Delegation is what keeps opencodex out of
* that churn.
*
* Used by the catalog v2-gated-ultra policy (devlog/260709_v2_gated_ultra) and the
* `ocx v2` toggle surface. The FLAG itself is never written here — toggling goes
* through the official `codex features enable|disable` CLI (format-preserving).
* The writes this module owns are the scoped scalars —
* `features.multi_agent_v2.max_concurrent_threads_per_session` and the
* `[agents]`/`[features]` fields the management API exposes: the codex CLI has
* no persisted setter for nested feature config (`-c` is per-invocation only),
* so ocx does scoped, EOL-preserving line edits — each one a read → edit →
* rename under the shared config write lock (see config-write-lock.ts).
*
* CODEX_HOME is resolved at CALL time (activeCodexConfigPath pattern, mirrors
* catalog.ts:40-54) so tests can point fixtures via env or the explicit
* `configPath` parameter without fighting the module-load-time const in paths.ts.
*/
import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
import { delimiter, dirname, join, resolve } from "node:path";
import { createRequire } from "node:module";
import { realpathSync } from "node:fs";
import { homedir } from "node:os";
import { AtomicWriteResidualTempError, AtomicWriteSecretResidualError, atomicWriteFile, getConfigDir } from "../config";
import { ConfigWriteDestinationChanged, assertNativeConfigWriteDestination, runConfigWriteChild, withConfigWriteRecovery, publishConfigWrite, configWriteLockFailureMessage, withConfigWriteLock, withConfigWriteLockHeld, type LockHandle } from "./config-write-lock";
import { codexHomeIsAbsent } from "./codex-home-owner";
import { forgetEphemeralSecretPath } from "../lib/windows-secret-acl";
import { resolveCodexHomeDir } from "./home";
import { resolveAndPersistCodexRuntime } from "./runtime";
import { decodeOverlayState } from "./shim-state-file";
import { canonicalizeOpenCodexModeHint } from "./multi-agent-mode-policy";
import { rootAssignmentKey, sourceText, splitSourceLines } from "./toml-source-lines";
const AGENTS_THREAD_LIMIT_KEY = "max_concurrent_threads_per_session";
const LEGACY_AGENTS_THREAD_LIMIT_KEY = "max_threads";
/** Upstream codex-rs feature key: allow `request_user_input` in Default mode. */
export const DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY = "default_mode_request_user_input";
// EOL preservation, local copies of inject.ts dominantEol/applyEol: importing
// inject here would close a module cycle (features -> inject -> catalog -> features).
function dominantEol(content: string): "\r\n" | "\n" {
const crlf = (content.match(/\r\n/g) ?? []).length;
if (crlf === 0) return "\n";
const bareLf = (content.match(/\n/g) ?? []).length - crlf;
return crlf >= bareLf ? "\r\n" : "\n";
}
function applyEol(content: string, eol: "\r\n" | "\n"): string {
const normalized = content.replace(/\r\n/g, "\n");
return eol === "\n" ? normalized : normalized.replace(/\n/g, "\r\n");
}
function mergeTrailingComments(existing?: string, migrated?: string): string {
if (!existing) return migrated ?? "";
if (!migrated || existing.trim() === migrated.trim()) return existing;
const migratedText = migrated.replace(/^\s*#\s*/, "");
if (existing.replace(/^\s*#\s*/, "").split(";").map(part => part.trim()).includes(migratedText.trim())) return existing;
return `${existing}; ${migratedText}`;
}
export function activeCodexConfigPath(): string {
// Keep home aliases observable by the held destination validator.
const home = resolveCodexHomeDir();
if (!process.env.CODEX_HOME?.trim()) {
const alias = join(homedir(), ".codex");
try { if (realpathSync.native(alias) === home) return join(alias, "config.toml"); }
catch { /* An absent local home can select the WSL Windows-home fallback. */ }
}
return join(home, "config.toml");
}
function readConfigText(configPath?: string): string | null {
const path = configPath ?? activeCodexConfigPath();
try {
if (!existsSync(path)) return null;
return readFileSync(path, "utf8");
} catch {
return null;
}
}
/**
* One edit's answer: either the replacement content or a refusal. `next` equal
* to the input is a no-change result — the helper compares before writing, so
* an edit never has to spell "unchanged" differently.
*/
type TomlEditOutcome = { next: string } | { error: string };
/**
* One read → edit → write pass over config.toml under the shared write lock.
*
* The edit callback sees bytes re-read INSIDE the lock, so it is always
* computed against what is actually on disk and no cooperating writer can land
* while the section runs. Previously every writer in this file read outside
* any lock and renamed over the whole file — a foreign rewrite landing between
* read and rename was silently discarded (a prompt-layer projection, another
* scalar edit, an injection's routing keys).
*
* A busy lock maps to the shared locked message: the sections under it are
* millisecond-scale, so refusing fast and letting the caller retry beats
* queuing behind whatever holds it.
*/
function editCodexConfigToml(
path: string,
edit: (content: string) => TomlEditOutcome,
heldConfigWriteLock?: LockHandle,
): ConfigEditResult {
if (codexHomeIsAbsent(dirname(path))) return { ok: false, error: `config.toml not readable at ${path}` };
const locked = withConfigWriteLockHeld(path, heldConfigWriteLock, (held): ConfigEditResult => {
const content = readConfigText(path);
if (content === null) return { ok: false, error: `config.toml not readable at ${path}` };
const outcome = edit(content);
if ("error" in outcome) return { ok: false, error: outcome.error };
if (outcome.next === content) return { ok: true, changed: false };
publishConfigWrite(path, held, (destination, hooks) => atomicWriteFile(destination, outcome.next, undefined, hooks));
return { ok: true, changed: true };
});
if (!locked.ok) return { ok: false, error: configWriteLockFailureMessage(locked), ...(locked.error === "unsafe" ? { retryable: false } : {}) };
return locked.value;
}
/**
* Body lines of a TOML table `[header]` up to (not including) the next table header.
*
* The implementation body is deliberately unchanged by #1295 — only this comment
* is new. The scanner is line-based and string-unaware, so it ends the table at
* the first line matching `/^\s*\[/` even inside a multi-line value. Twenty call
* sites in this file consume its output, most of them by matching a regex
* against the returned text, so widening that text changes what they match. An
* earlier attempt at #1295 made this scanner string-aware and thereby gave
* `getAgentsEnabled`, `getAgentsMaxDepth`, and `getMaxConcurrentThreads` three
* new wrong answers.
*
* The readers that matter for #1295 use a real TOML parse instead (see
* `parsedTomlTable`). This stays as the fallback for documents that do not
* parse, and as the reader for the remaining call sites until they are migrated
* the same way.
*/
function tomlTableBody(content: string, header: string): string | null {
const lines = content.split("\n");
const escaped = header.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
const start = lines.findIndex(l => new RegExp(`^\\s*\\[${escaped}\\]\\s*(?:#.*)?$`).test(l));
if (start === -1) return null;
const rest = lines.slice(start + 1);
const end = rest.findIndex(l => /^\s*\[/.test(l));
return (end === -1 ? rest : rest.slice(0, end)).join("\n");
}
function tomlBoolInBody(body: string, key: string): boolean | null {
const m = body.match(new RegExp(`^\\s*${key}\\s*=\\s*(true|false)\\s*(?:#.*)?$`, "m"));
return m ? m[1] === "true" : null;
}
/**
* TRUE when the codex `multi_agent_v2` feature is enabled in config.toml.
* Recognizes both shipped forms (codex-rs features/src/tests.rs):
* [features.multi_agent_v2] [features]
* enabled = true multi_agent_v2 = true
* plus the inline-table form `multi_agent_v2 = { enabled = true, ... }`.
* Missing file/key -> false (upstream default_enabled = false).
*/
export function isMultiAgentV2Enabled(configPath?: string): boolean {
const content = readConfigText(configPath);
return multiAgentV2EnabledFromConfigText(content);
}
/** Parse `multi_agent_v2` from caller-owned config.toml text without consulting disk. */
export function multiAgentV2EnabledFromConfigText(content: string | null): boolean {
if (content === null) return false;
// Prefer a real parse. The hand-written table scanner below cannot distinguish
// an assignment from prose that looks like one — a `"""` value containing the
// line `enabled = true` reads as the key itself — and TOML has enough value
// shapes (multi-line arrays opening on the next line, escapes, comments) that
// each near-miss costs another special case (#1295).
//
// The scanner remains only for a document `Bun.TOML.parse` rejects. That is a
// statement about Bun's parser, not about Codex's — the two are separate
// implementations and no compatibility evidence is claimed here, so a document
// Bun rejects may still be one Codex loads. The fallback is therefore
// best-effort and inherits the ambiguity above. It exists because reporting a
// feature as disabled on account of an unreadable file presents a failure as
// a state.
const parsed = parsedTomlTable(content, "features");
if (parsed !== null) {
const table = plainTomlRecord(parsed.multi_agent_v2);
if (table !== null) return table.enabled === true;
if (typeof parsed.multi_agent_v2 === "boolean") return parsed.multi_agent_v2;
return false;
}
// Bun 1.4 enforces TOML's "value must begin on the assignment line" rule that
// 1.3.14 did not, so `hint =` followed by `[` on the next line now fails the
// real parse and reaches the line-based fallback below — which reads that `[`
// as a table header and truncates the table before `enabled`. Codex's own
// parser accepts the document, so answering "disabled" would report a parser
// disagreement as a feature state (#1295, #1691).
//
// Joining a dangling `=` to the line that follows is the smallest repair that
// keeps the scanner untouched: widening `tomlTableBody` to be string-aware is
// what previously broke `getAgentsEnabled`, `getAgentsMaxDepth`, and
// `getMaxConcurrentThreads` (see its comment). If the joined document parses,
// that answer is authoritative; if it does not, nothing is lost.
const joined = joinDanglingTomlAssignments(content);
if (joined !== content) {
const reparsed = parsedTomlTable(joined, "features");
if (reparsed !== null) {
const table = plainTomlRecord(reparsed.multi_agent_v2);
if (table !== null) return table.enabled === true;
if (typeof reparsed.multi_agent_v2 === "boolean") return reparsed.multi_agent_v2;
return false;
}
}
const table = tomlTableBody(content, "features.multi_agent_v2");
if (table !== null) {
const enabled = tomlBoolInBody(table, "enabled");
if (enabled !== null) return enabled;
// A bare [features.multi_agent_v2] table without `enabled` counts as on
// (FeatureToml::Config with enabled: None materializes as enabled upstream
// only when set; be conservative and require the boolean).
return false;
}
const features = tomlTableBody(content, "features");
if (features !== null) {
const bool = tomlBoolInBody(features, "multi_agent_v2");
if (bool !== null) return bool;
const inline = features.match(/^\s*multi_agent_v2\s*=\s*\{([^}]*)\}/m);
if (inline) {
const enabled = inline[1].match(/enabled\s*=\s*(true|false)/);
if (enabled) return enabled[1] === "true";
}
}
return false;
}
function plainTomlRecord(value: unknown): Record<string, unknown> | null {
return value !== null && typeof value === "object" && !Array.isArray(value)
? value as Record<string, unknown>
: null;
}
/**
* Join `key =` to the following line when the value was written on the next
* line, so a parser enforcing TOML's same-line rule can read the document.
*
* Bun 1.3.14 accepted this shape; Bun 1.4 rejects it, correctly — TOML requires
* the value to begin on the assignment line. Codex's parser still accepts it, so
* this exists to keep the two readers agreeing rather than to endorse the shape.
*
* Deliberately narrow: it only acts on a line whose LAST non-comment character
* is `=`, which cannot occur in a valid assignment. Lines inside multi-line
* strings are left alone — a `"""` body line ending in `=` would be rewritten,
* but the result is only used when it PARSES, and the unmodified document is
* always tried first, so a wrong join cannot displace a correct read.
*/
function joinDanglingTomlAssignments(content: string): string {
const lines = content.split("\n");
const out: string[] = [];
for (let i = 0; i < lines.length; i++) {
const line = lines[i]!;
// A dangling assignment: trailing `=` with nothing after it on this line.
if (/^[^#]*[^=!<>]=\s*$/.test(line) && i + 1 < lines.length) {
let j = i + 1;
// Skip blank and comment-only lines between the `=` and its value.
while (j < lines.length && /^\s*(?:#.*)?$/.test(lines[j]!)) j++;
if (j < lines.length) {
out.push(`${line.replace(/\s*$/, "")} ${lines[j]!.replace(/^\s*/, "")}`);
i = j;
continue;
}
}
out.push(line);
}
return out.join("\n");
}
/**
* A top-level table from a full TOML parse, or null when the document does not
* parse. A parsed document with no such table yields `{}` rather than null: that
* is a real answer ("no keys"), while null means "could not read, fall back".
*/
function parsedTomlTable(content: string, name: string): Record<string, unknown> | null {
const toml = (globalThis as { Bun?: { TOML?: { parse(input: string): unknown } } }).Bun?.TOML;
if (!toml) return null;
try {
const root = plainTomlRecord(toml.parse(content));
if (root === null) return null;
return plainTomlRecord(root[name]) ?? {};
} catch {
return null;
}
}
/**
* TRUE when the codex `default_mode_request_user_input` feature is enabled in
* config.toml — lets a Default-mode session pause and ask the user questions
* through `request_user_input` (upstream FeatureSpec: under development,
* default_enabled = false). Recognizes the shipped boolean form
* `[features] default_mode_request_user_input = true`.
* Missing file/key -> false.
*/
export function isDefaultModeRequestUserInputEnabled(configPath?: string): boolean {
const content = readConfigText(configPath);
if (content === null) return false;
// Same reason as the v2 reader: a `"""` value whose prose contains
// `default_mode_request_user_input = true` is not an assignment, and a raw
// regex over the table body cannot tell the difference (#1295).
const parsed = parsedTomlTable(content, "features");
if (parsed !== null) return parsed[DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY] === true;
const features = tomlTableBody(content, "features");
if (features === null) return false;
return tomlBoolInBody(features, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY) === true;
}
/**
* Whether either spelling of the [agents] limit is present, including invalid
* values. Keep the exported compatibility name; migrations must remove both.
*/
export function hasAgentsMaxThreads(configPath?: string): boolean {
const content = readConfigText(configPath);
if (content === null) return false;
const parsed = parsedTomlTable(content, "agents");
if (parsed !== null) return Object.hasOwn(parsed, AGENTS_THREAD_LIMIT_KEY) || Object.hasOwn(parsed, LEGACY_AGENTS_THREAD_LIMIT_KEY);
return agentsThreadLimitEntries(content).entries.length > 0;
}
/** Canonical [agents] limit, falling back to max_threads only when absent. */
export function getAgentsMaxThreads(configPath?: string): number | null {
const content = readConfigText(configPath);
if (content === null) return null;
const parsed = parsedTomlTable(content, "agents");
if (parsed !== null) {
const value = Object.hasOwn(parsed, AGENTS_THREAD_LIMIT_KEY) ? parsed[AGENTS_THREAD_LIMIT_KEY] : parsed[LEGACY_AGENTS_THREAD_LIMIT_KEY];
return typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : null;
}
// Unrelated valid 64-bit integers can make Bun reject the whole document.
// Decode the same isolated structural assignment the editor uses, including
// quoted keys and non-decimal integers, rather than treating unreadable as unset.
const entries = agentsThreadLimitEntries(content).entries;
return (entries.find(entry => entry.key === AGENTS_THREAD_LIMIT_KEY) ?? entries[0])?.value ?? null;
}
/**
* Current `[agents] enabled`. Upstream defaults this to true and lets an enabled
* `features.multi_agent_v2` override it entirely (codex-rs core/src/config/mod.rs
* multi_agent_version_override returns V2 first at :1521-1523; `enabled = false`
* only takes effect with V2 off), so `null` means "unset, upstream default applies"
* and is NOT the same as `true`.
*/
export function getAgentsEnabled(configPath?: string): boolean | null {
const content = readConfigText(configPath);
if (content === null) return null;
const agents = tomlTableBody(content, "agents");
if (agents === null) return null;
const m = agents.match(/^\s*enabled\s*=\s*(true|false)\s*(?:#.*)?$/m);
return m ? m[1] === "true" : null;
}
/**
* Current `[agents] max_depth`. Upstream applies this to V1 agent threads only and
* ignores it under V2 (config_toml.rs: "Maximum nesting depth for V1 agent threads.
* Ignored by V2."). The upstream type is `Option<i32>` with no minimum, so a
* negative value is valid config that effectively disables V1 child spawning —
* do not "correct" it, and do not present this as an effective V2 limit.
*/
export function getAgentsMaxDepth(configPath?: string): number | null {
const content = readConfigText(configPath);
if (content === null) return null;
const agents = tomlTableBody(content, "agents");
if (agents === null) return null;
const m = agents.match(/^\s*max_depth\s*=\s*(-?\d+)\s*(?:#.*)?$/m);
if (!m) return null;
const value = Number(m[1]);
return Number.isInteger(value) && value >= -2_147_483_648 && value <= 2_147_483_647 ? value : null;
}
/**
* Current `features.multi_agent_v2.max_concurrent_threads_per_session`, from
* either the dedicated or inline-table form; null means the Codex default.
*/
export function getMaxConcurrentThreads(configPath?: string): number | null {
const content = readConfigText(configPath);
if (content === null) return null;
const table = tomlTableBody(content, "features.multi_agent_v2");
const features = tomlTableBody(content, "features");
const inline = features?.match(/^\s*multi_agent_v2\s*=\s*\{([^}]*)\}/m);
const m = table?.match(/^\s*max_concurrent_threads_per_session\s*=\s*(\d+)\s*(?:#.*)?$/m)
?? inline?.[1].match(/(?:^|,)\s*max_concurrent_threads_per_session\s*=\s*(\d+)\s*(?:,|$)/);
if (!m) return null;
const value = Number(m[1]);
return Number.isFinite(value) && value >= 1 ? value : null;
}
/** Largest V1 child limit we translate. Well below Number.MAX_SAFE_INTEGER and far
* above any real concurrency setting; upstream's usize saturates, ours would silently
* lose precision. */
const MAX_TRANSLATABLE_V1_CHILD_LIMIT = 1_000_000;
/** The V2 side is one larger by construction: it counts the root agent's own slot, so
* the image of the maximum V1 value must itself be translatable back. */
const MAX_TRANSLATABLE_V2_TOTAL_LIMIT = MAX_TRANSLATABLE_V1_CHILD_LIMIT + 1;
export function isTranslatableV1ChildLimit(limit: number): boolean {
return Number.isInteger(limit) && limit >= 1 && limit <= MAX_TRANSLATABLE_V1_CHILD_LIMIT;
}
export function isTranslatableV2TotalLimit(limit: number): boolean {
return Number.isInteger(limit) && limit >= 1 && limit <= MAX_TRANSLATABLE_V2_TOTAL_LIMIT;
}
/**
* Upstream counts the root agent inside the V2 thread limit but not inside the legacy
* `[agents]` limit (codex-rs core/src/config/mod.rs resolve_multi_agent_v2_config applies
* saturating_add(1) to the [agents] value; the inverse saturating_sub(1) appears at
* mod.rs:1555). These helpers keep our migrations on the same side of that boundary.
*/
export function v1ChildLimitToV2TotalLimit(childLimit: number): number {
if (!isTranslatableV1ChildLimit(childLimit)) {
throw new RangeError(`v1 child limit out of translatable range: ${childLimit}`);
}
return childLimit + 1;
}
/**
* Inverse of `v1ChildLimitToV2TotalLimit`. A V2 total of 1 means "root only, no
* children", which has no representable legacy child count >= 1, so it clamps to 1
* rather than writing 0 and tripping upstream's `>= 1` validation.
*/
export function v2TotalLimitToV1ChildLimit(totalLimit: number): number {
if (!isTranslatableV2TotalLimit(totalLimit)) {
throw new RangeError(`v2 total limit out of translatable range: ${totalLimit}`);
}
return Math.max(1, totalLimit - 1);
}
/**
* The content-level half of `setMaxConcurrentThreads`, reused by
* `ensureDisabledV2Config` so a nested edit never re-takes the write lock on
* the file its caller already holds.
*/
function maxConcurrentThreadsEdit(
content: string,
value: number,
migratedComment?: string,
): TomlEditOutcome {
const eol = dominantEol(content);
const lines = content.split(/\r?\n/);
const headerRe = /^\s*\[features\.multi_agent_v2\]\s*(?:#.*)?$/;
const headerIdx = lines.findIndex(l => headerRe.test(l));
if (headerIdx === -1) {
const featuresHeader = lines.findIndex(l => /^\s*\[features\]\s*(?:#.*)?$/.test(l));
if (featuresHeader === -1) return { error: "multi_agent_v2 feature config not found — enable v2 first (ocx v2 on)" };
let featuresEnd = lines.length;
for (let i = featuresHeader + 1; i < lines.length; i++) {
if (/^\s*\[/.test(lines[i])) { featuresEnd = i; break; }
}
const boolRe = /^(\s*)multi_agent_v2\s*=\s*(true|false)(\s*#.*)?$/;
const inlineRe = /^(\s*)multi_agent_v2\s*=\s*\{([^}]*)\}(\s*#.*)?$/;
for (let i = featuresHeader + 1; i < featuresEnd; i++) {
const bool = lines[i].match(boolRe);
if (bool) {
lines[i] = `${bool[1]}multi_agent_v2 = { enabled = ${bool[2]}, max_concurrent_threads_per_session = ${value} }${mergeTrailingComments(bool[3], migratedComment)}`;
return { next: applyEol(lines.join("\n"), eol) };
}
const inline = lines[i].match(inlineRe);
if (!inline) continue;
const existing = inline[2].match(/(?:^|,)\s*max_concurrent_threads_per_session\s*=\s*(\d+)\s*(?=,|$)/);
if (existing && Number(existing[1]) === value && (!migratedComment || migratedComment === inline[3])) return { next: content };
const body = existing
? inline[2].replace(/(^|,)\s*max_concurrent_threads_per_session\s*=\s*\d+\s*(?=,|$)/, `$1 max_concurrent_threads_per_session = ${value}`)
: `${inline[2].trim()}${inline[2].trim() ? ", " : ""}max_concurrent_threads_per_session = ${value}`;
lines[i] = `${inline[1]}multi_agent_v2 = { ${body.trim()} }${mergeTrailingComments(inline[3], migratedComment)}`;
return { next: applyEol(lines.join("\n"), eol) };
}
return { error: "multi_agent_v2 feature config not found — enable v2 first (ocx v2 on)" };
}
let end = lines.length;
for (let i = headerIdx + 1; i < lines.length; i++) {
if (/^\s*\[/.test(lines[i])) { end = i; break; }
}
const keyRe = /^(\s*)max_concurrent_threads_per_session\s*=\s*(\d+)(\s*#.*)?$/;
for (let i = headerIdx + 1; i < end; i++) {
const m = lines[i].match(keyRe);
if (!m) continue;
if (Number(m[2]) === value && (!migratedComment || migratedComment === m[3])) return { next: content };
lines[i] = `${m[1]}max_concurrent_threads_per_session = ${value}${mergeTrailingComments(m[3], migratedComment)}`;
return { next: applyEol(lines.join("\n"), eol) };
}
lines.splice(headerIdx + 1, 0, `max_concurrent_threads_per_session = ${value}${migratedComment ?? ""}`);
return { next: applyEol(lines.join("\n"), eol) };
}
/**
* Persist `features.multi_agent_v2.max_concurrent_threads_per_session = value`.
* Scoped edit in either the dedicated table or `[features]` boolean/inline form.
* Boolean form is upgraded to an inline config so the numeric value remains
* attached to the feature without a TOML key conflict. Idempotent on equal value.
*/
export function setMaxConcurrentThreads(value: number, configPath?: string, migratedComment?: string): { ok: true; changed: boolean } | { ok: false; error: string } {
if (!Number.isInteger(value) || value < 1) {
return { ok: false, error: "max_concurrent_threads_per_session must be an integer >= 1" };
}
const path = configPath ?? activeCodexConfigPath();
return editCodexConfigToml(path, content => maxConcurrentThreadsEdit(content, value, migratedComment));
}
type ConfigEditResult = { ok: true; changed: boolean } | { ok: false; error: string; retryable?: boolean };
/**
* Encode a string as a TOML single-line basic string.
*
* Character-by-character on purpose. A chained-replace implementation
* (`.replace(/\\/g, "\\\\").replace(/\t/g, "\\t")`) corrupts input: the backslash
* pass runs first, then later passes insert NEW backslashes the first pass can no
* longer protect. Single-line basic strings handle every case including embedded
* `"""`, which a multi-line `"""..."""` form cannot.
*/
function encodeTomlBasicString(value: string): string {
let out = '"';
for (const ch of value) {
switch (ch) {
case "\\": out += "\\\\"; break;
case '"': out += '\\"'; break;
case "\n": out += "\\n"; break;
case "\r": out += "\\r"; break;
case "\t": out += "\\t"; break;
case "\b": out += "\\b"; break;
case "\f": out += "\\f"; break;
default: {
const code = ch.codePointAt(0)!;
out += code < 0x20 || code === 0x7f
? `\\u${code.toString(16).padStart(4, "0")}`
: ch;
}
}
}
return out + '"';
}
/**
* Decode one TOML string token INCLUDING its quotes. Basic strings (`"..."`)
* unescape; literal strings (`'...'`) are verbatim — a backslash is not special
* there. Returns null for anything that is not a string token.
*/
function decodeTomlStringToken(token: string): string | null {
if (token.length < 2) return null;
// Multi-line literal string: `'''...'''` verbatim (backslashes not special).
if (token.startsWith("'''")) {
return token.endsWith("'''") && token.length >= 6
? normalizeTomlMultilineBody(token.slice(3, -3))
: null;
}
// Multi-line basic string: `"""..."""` with escapes.
if (token.startsWith('"""')) {
if (!token.endsWith('"""') || token.length < 6) return null;
return decodeBasicStringBody(normalizeTomlMultilineBody(token.slice(3, -3)), true);
}
if (token.startsWith("'")) {
return token.endsWith("'") ? token.slice(1, -1) : null;
}
if (!token.startsWith('"') || !token.endsWith('"')) return null;
return decodeBasicStringBody(token.slice(1, -1));
}
/** Apply TOML's multi-line newline rules before string-body decoding. */
function normalizeTomlMultilineBody(body: string): string {
const normalized = body.replace(/\r\n/g, "\n");
return normalized.startsWith("\n") ? normalized.slice(1) : normalized;
}
/** Unescape the body of a TOML basic string (single- or multi-line). */
function decodeBasicStringBody(body: string, multiline = false): string | null {
let out = "";
for (let i = 0; i < body.length; i++) {
const ch = body[i];
if (ch !== "\\") { out += ch; continue; }
const esc = body[++i];
if (multiline) {
let newline = i;
while (body[newline] === " " || body[newline] === "\t") newline++;
if (body[newline] === "\n") {
i = newline;
while (body[i + 1] === " " || body[i + 1] === "\t" || body[i + 1] === "\n") i++;
continue;
}
}
switch (esc) {
case "\\": out += "\\"; break;
case '"': out += '"'; break;
case "n": out += "\n"; break;
case "r": out += "\r"; break;
case "t": out += "\t"; break;
case "b": out += "\b"; break;
case "f": out += "\f"; break;
case "u": {
const code = parseInt(body.slice(i + 1, i + 5), 16);
if (Number.isNaN(code)) return null;
out += String.fromCodePoint(code);
i += 4;
break;
}
case "U": {
const code = parseInt(body.slice(i + 1, i + 9), 16);
if (Number.isNaN(code)) return null;
out += String.fromCodePoint(code);
i += 8;
break;
}
default: return null;
}
}
return out;
}
/**
* End index (exclusive) of the TOML value starting at or after `start` in `text`.
* String-aware: basic strings honor backslash escapes, literal strings do not.
* Inline tables and arrays nest and are scanned with the same awareness.
*/
function scanTomlValueEnd(text: string, start: number): number {
let i = start;
while (i < text.length && (text[i] === " " || text[i] === "\t")) i++;
const first = text[i];
if (first === '"') {
// Multi-line basic string: `"""..."""`. The closing delimiter is a triple
// quote; a single or double quote inside the body does not end the token.
if (text[i + 1] === '"' && text[i + 2] === '"') {
i += 3;
while (i < text.length) {
if (text[i] === "\\") { i += 2; continue; }
if (text[i] === '"' && text[i + 1] === '"' && text[i + 2] === '"') {
// TOML permits up to two quotes immediately inside the closing
// delimiter, so a 4- or 5-quote run means the extra one or two
// quotes are part of the value. Consume the full valid run and
// keep the surplus quotes in the body.
let end = i + 3;
if (text[end] === '"') {
end++;
if (text[end] === '"') end++;
}
return end;
}
i++;
}
return text.length;
}
i++;
while (i < text.length) {
if (text[i] === "\\") { i += 2; continue; }
if (text[i] === '"') return i + 1;
i++;
}
return text.length;
}
if (first === "'") {
// Multi-line literal string: `'''...'''`.
if (text[i + 1] === "'" && text[i + 2] === "'") {
i += 3;
while (i < text.length) {
if (text[i] === "'" && text[i + 1] === "'" && text[i + 2] === "'") {
// Same as multi-line basic: up to two surplus single quotes can
// precede the closing delimiter and remain part of the value.
let end = i + 3;
if (text[end] === "'") {
end++;
if (text[end] === "'") end++;
}
return end;
}
i++;
}
return text.length;
}
const close = text.indexOf("'", i + 1);
return close === -1 ? text.length : close + 1;
}
if (first === "{") {
const close = findInlineTableEnd(text, i);
return close === -1 ? text.length : close + 1;
}
if (first === "[") {
let depth = 0;
while (i < text.length) {
const c = text[i];
if (c === '"' || c === "'") { i = scanTomlValueEnd(text, i); continue; }
if (c === "[") depth++;
else if (c === "]") { depth--; if (depth === 0) return i + 1; }
i++;
}
return text.length;
}
while (i < text.length && !/[\s,}\]#]/.test(text[i])) i++;
return i;
}
/** Index of the `}` matching the `{` at `openIdx`, string-aware, or -1. */
function findInlineTableEnd(text: string, openIdx: number): number {
let depth = 0;
let i = openIdx;
while (i < text.length) {
const c = text[i];
if (c === '"' || c === "'") { i = scanTomlValueEnd(text, i); continue; }
if (c === "{") depth++;
else if (c === "}") { depth--; if (depth === 0) return i; }
i++;
}
return -1;
}
interface InlineEntry { keyStart: number; valueStart: number; valueEnd: number }
/** Locate a top-level assignment while skipping complete (possibly multiline) values. */
function findTomlAssignment(text: string, key: string): InlineEntry | null {
let lineStart = 0;
while (lineStart < text.length) {
let i = lineStart;
while (text[i] === " " || text[i] === "\t") i++;
const keyStart = i;
let keyText = "";
if (text[i] === '"' || text[i] === "'") {
const keyEnd = scanTomlValueEnd(text, i);
keyText = decodeTomlStringToken(text.slice(i, keyEnd)) ?? "";
i = keyEnd;
} else {
const match = /^[A-Za-z0-9_-]+/.exec(text.slice(i));
if (match) {
keyText = match[0];
i += match[0].length;
}
}
while (text[i] === " " || text[i] === "\t") i++;
if (keyText && text[i] === "=") {
const valueStart = i + 1;
const valueEnd = scanTomlValueEnd(text, valueStart);
if (keyText === key) return { keyStart, valueStart, valueEnd };
const nextLine = text.indexOf("\n", valueEnd);
lineStart = nextLine === -1 ? text.length : nextLine + 1;
continue;
}
const nextLine = text.indexOf("\n", lineStart);
lineStart = nextLine === -1 ? text.length : nextLine + 1;
}
return null;
}
/**
* Locate `key = value` inside the inline-table body spanning [bodyStart, bodyEnd)
* (exclusive of the braces), string-aware on both keys and values, or null.
*/
function findInlineEntry(text: string, bodyStart: number, bodyEnd: number, key: string): InlineEntry | null {
let i = bodyStart;
while (i < bodyEnd) {
while (i < bodyEnd && /[\s,]/.test(text[i])) i++;
if (i >= bodyEnd) break;
const entryStart = i;
let keyText: string;
if (text[i] === '"' || text[i] === "'") {
const keyEnd = scanTomlValueEnd(text, i);
keyText = decodeTomlStringToken(text.slice(i, keyEnd)) ?? "";
i = keyEnd;
} else {
const m = /^[A-Za-z0-9_-]+/.exec(text.slice(i, bodyEnd));
if (!m) break;
keyText = m[0];
i += m[0].length;
}
while (i < bodyEnd && /\s/.test(text[i])) i++;
if (text[i] !== "=") { i = entryStart + 1; continue; }
i++;
while (i < bodyEnd && /\s/.test(text[i])) i++;
const valueStart = i;
const valueEnd = Math.min(scanTomlValueEnd(text, valueStart), bodyEnd);
if (keyText === key) return { keyStart: entryStart, valueStart, valueEnd };
i = valueEnd;
}
return null;
}
/** Whether a TOML assignment's value starts with a triple-quoted string. */
function isMultilineTomlString(text: string, valueStart: number): boolean {
let start = valueStart;
while (text[start] === " " || text[start] === "\t") start++;
return text.startsWith('"""', start) || text.startsWith("'''", start);
}
/** Whether one field in a supported inline `multi_agent_v2` table is triple-quoted. */
function hasInlineMultilineTomlString(text: string, assignment: InlineEntry, key: string): boolean {
let openIdx = assignment.valueStart;
while (text[openIdx] === " " || text[openIdx] === "\t") openIdx++;
if (text[openIdx] !== "{") return false;
const closeIdx = findInlineTableEnd(text, openIdx);
if (closeIdx === -1) return false;
const entry = findInlineEntry(text, openIdx + 1, closeIdx, key);
return entry !== null && isMultilineTomlString(text, entry.valueStart);
}
/**
* Set or remove one scalar key inside a top-level TOML table, preserving every
* other line byte-for-byte — including the existing value's trailing comment,
* which is kept verbatim. `encoded` is the already-serialized RHS
* (`encodeTomlBasicString` for strings, `String(n)` for numbers, `"true"`/`"false"`
* for booleans); null removes the key. Creates the table when absent. Returns the
* new content; returning the input unchanged means no-op.
*/
function editScalarInTable(content: string, table: string, key: string, encoded: string | null): string {
const eol = dominantEol(content);
const lines = content.split(/\r?\n/);
const headerRe = new RegExp(`^\\s*\\[${table.replace(/\./g, "\\.")}\\]\\s*(?:#.*)?$`);
const headerIdx = lines.findIndex(l => headerRe.test(l));
if (headerIdx === -1) {
if (encoded === null) return content;
const separator = lines.length > 0 && lines[lines.length - 1] !== "" ? [""] : [];
lines.push(...separator, `[${table}]`, `${key} = ${encoded}`);
return applyEol(lines.join("\n"), eol);
}
let end = lines.length;
for (let i = headerIdx + 1; i < lines.length; i++) {
if (/^\s*\[/.test(lines[i])) { end = i; break; }
}
for (let i = headerIdx + 1; i < end; i++) {
const entry = findTomlAssignment(lines[i], key);
if (!entry) continue;
// The existing value may itself contain '#', so scan the value token
// string-aware instead of splitting on '#'.
const line = lines[i];
const trailing = line.slice(entry.valueEnd);
if (encoded === null) {
lines.splice(i, 1);
return applyEol(lines.join("\n"), eol);
}
if (line.slice(entry.valueStart, entry.valueEnd).trim() === encoded) return content;
lines[i] = `${line.slice(0, entry.keyStart)}${key} = ${encoded}${trailing}`;
return applyEol(lines.join("\n"), eol);
}
if (encoded === null) return content;
lines.splice(headerIdx + 1, 0, `${key} = ${encoded}`);
return applyEol(lines.join("\n"), eol);
}
/** Persist `[agents] enabled = value`, or remove the key when `value` is null. */
export function setAgentsEnabled(value: boolean | null, configPath?: string, heldConfigWriteLock?: LockHandle): ConfigEditResult {
const path = configPath ?? activeCodexConfigPath();
return editCodexConfigToml(path, content => ({
next: editScalarInTable(content, "agents", "enabled", value === null ? null : String(value)),
}), heldConfigWriteLock);
}
/**
* Persist `[agents] max_depth = value`, or remove the key when `value` is null.
* Validation is exactly the upstream contract: `Option<i32>` with no minimum, so
* any integer in signed-i32 range is accepted — writing anything wider would
* produce a config upstream cannot deserialize, a hard parse failure for the
* user's Codex.
*/
export function setAgentsMaxDepth(value: number | null, configPath?: string, heldConfigWriteLock?: LockHandle): ConfigEditResult {
if (value !== null && (!Number.isInteger(value) || value < -2_147_483_648 || value > 2_147_483_647)) {
return { ok: false, error: "max_depth must be an integer within signed i32 range" };
}
const path = configPath ?? activeCodexConfigPath();
return editCodexConfigToml(path, content => ({
next: editScalarInTable(content, "agents", "max_depth", value === null ? null : String(value)),
}), heldConfigWriteLock);
}
/**
* Current `features.multi_agent_v2.subagent_developer_instructions`.
*
* Upstream tri-state (codex-rs core/src/config/mod.rs resolve_multi_agent_v2_config):
* unset -> the child inherits the parent's developer instructions
* non-empty -> replaces the inherited parent fragment
* empty string -> clears the inherited fragment
*
* So `null` and `""` are DIFFERENT values and both must round-trip. Upstream
* `.trim()`s the configured text, so whitespace-only values are effectively `""`.
* Reads both the dedicated-table and inline forms; dedicated wins, mirroring
* `getMaxConcurrentThreads` precedence.
*/
/**
* Read a string-valued `features.multi_agent_v2` scalar (dedicated table or inline
* form; dedicated wins, mirroring `getMaxConcurrentThreads` precedence). Returns
* `null` when the key is absent or the config is unreadable. A present empty string
* round-trips faithfully — some upstream keys treat `""` and `null` differently.
*/
function getV2StringField(key: string, configPath?: string): string | null {
const content = readConfigText(configPath);
if (content === null) return null;
const table = tomlTableBodyForStringFields(content, "features.multi_agent_v2");
if (table !== null) {
const entry = findTomlAssignment(table, key);
if (entry) {
const token = table.slice(entry.valueStart, entry.valueEnd).trim();
return decodeTomlStringToken(token);
}
return null;
}
const features = tomlTableBodyForStringFields(content, "features");
if (features === null) return null;
const v2Entry = findTomlAssignment(features, "multi_agent_v2");
if (!v2Entry) return null;
let openIdx = v2Entry.valueStart;
while (features[openIdx] === " " || features[openIdx] === "\t") openIdx++;
if (features[openIdx] !== "{") return null;
const closeIdx = findInlineTableEnd(features, openIdx);
if (closeIdx === -1) return null;
const entry = findInlineEntry(features, openIdx + 1, closeIdx, key);
if (!entry) return null;
return decodeTomlStringToken(features.slice(entry.valueStart, entry.valueEnd).trim());
}
/**
* A table body scanner that skips complete TOML values before recognizing the
* next header. Unlike the legacy line scanner, bracket-shaped prose inside a
* multi-line string cannot truncate the table.
*/
function tomlTableBodyForStringFields(content: string, header: string): string | null {
const escaped = escapeRegExp(header);
const match = new RegExp(`^\\s*\\[${escaped}\\]\\s*(?:#.*)?$`, "m").exec(content);
if (!match) return null;
const newline = content.indexOf("\n", match.index + match[0].length);
if (newline === -1) return "";
const bodyStart = newline + 1;
let lineStart = bodyStart;
while (lineStart < content.length) {
let cursor = lineStart;
while (content[cursor] === " " || content[cursor] === "\t") cursor++;
if (content[cursor] === "[") return content.slice(bodyStart, lineStart);
const lineEnd = content.indexOf("\n", cursor);
const boundedEnd = lineEnd === -1 ? content.length : lineEnd;
let keyEnd = cursor;
if (content[keyEnd] === '"' || content[keyEnd] === "'") {
keyEnd = scanTomlValueEnd(content, keyEnd);
} else {
const keyMatch = /^[A-Za-z0-9_.-]+/.exec(content.slice(keyEnd, boundedEnd));
if (keyMatch) keyEnd += keyMatch[0].length;
}
while (content[keyEnd] === " " || content[keyEnd] === "\t") keyEnd++;
if (content[keyEnd] === "=" && keyEnd < boundedEnd) {
const valueEnd = scanTomlValueEnd(content, keyEnd + 1);
const nextLine = content.indexOf("\n", valueEnd);
lineStart = nextLine === -1 ? content.length : nextLine + 1;
} else {
lineStart = lineEnd === -1 ? content.length : lineEnd + 1;
}
}
return content.slice(bodyStart);
}
function escapeRegExp(value: string): string {
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}
/** Bare and quoted TOML forms of one known-safe key. */
function tomlKeyPattern(key: string): string {
const escaped = escapeRegExp(key);
return `(?:${escaped}|"${escaped}"|'${escaped}')`;
}
export function getSubagentDeveloperInstructions(configPath?: string): string | null {
return getV2StringField("subagent_developer_instructions", configPath);
}
/** Current `features.multi_agent_v2.multi_agent_mode_hint_text`, or null when unset. */
export function getMultiAgentModeHintText(configPath?: string): string | null {
return getV2StringField("multi_agent_mode_hint_text", configPath);
}
/**
* Persist `features.multi_agent_v2.subagent_developer_instructions`, or remove the
* key when `value` is null. Handles all three existing encodings: the dedicated
* table (scalar edit), the inline table (string-aware edit inside the braces — a
* regex over `[^}]*` would corrupt any value containing `}`), and the bare boolean
* form (upgraded in place to an inline table, mirroring `setMaxConcurrentThreads`).
* With no existing v2 config, creates the dedicated table carrying only this key.
* The key name must match upstream character-for-character: the upstream struct
* carries `#[serde(deny_unknown_fields)]`, so a misspelling is not ignored — it is
* a hard config-parse failure for the user's Codex.
*/
function setV2StringField(key: string, value: string | null, configPath?: string, heldConfigWriteLock?: LockHandle): ConfigEditResult {
const path = configPath ?? activeCodexConfigPath();
const encoded = value === null ? null : encodeTomlBasicString(value);
return editCodexConfigToml(path, (content): TomlEditOutcome => {
// A parsed V2 object without one of the supported source forms came from
// dotted/quoted path segments. Appending a dedicated table would redefine it
// and make Codex reject the file, so fail closed without changing any bytes.
const parsedFeatures = parsedTomlTable(content, "features");
const parsedV2 = parsedFeatures === null ? null : plainTomlRecord(parsedFeatures.multi_agent_v2);
const dedicatedV2 = tomlTableBodyForStringFields(content, "features.multi_agent_v2") !== null;
const featuresBody = tomlTableBodyForStringFields(content, "features");
const featuresV2Entry = featuresBody === null ? null : findTomlAssignment(featuresBody, "multi_agent_v2");
const supportedFeaturesEntry = featuresV2Entry !== null;
if (parsedV2 !== null && !dedicatedV2 && !supportedFeaturesEntry) {
return { error: "dotted or quoted multi_agent_v2 config is not supported for managed string fields" };
}
const dedicatedStringBody = tomlTableBodyForStringFields(content, "features.multi_agent_v2");
if (dedicatedStringBody !== null) {
// Multiline TOML strings ("""...""" / '''...''') span multiple lines and the
// single-line table editor cannot rewrite or remove them without corrupting
// the document. Scope this guard to the target V2 table so an unrelated
// table carrying the same key does not block an otherwise safe edit.
const dedicatedEntry = findTomlAssignment(dedicatedStringBody, key);
if (dedicatedEntry !== null && isMultilineTomlString(dedicatedStringBody, dedicatedEntry.valueStart)) {
return { error: `multi-line TOML string for ${key} is not editable; convert it to a single-line string first` };
}
const legacyDedicatedBody = tomlTableBody(content, "features.multi_agent_v2") ?? "";
if (dedicatedEntry !== null && findTomlAssignment(legacyDedicatedBody, key) === null) {
return { error: `cannot edit ${key} after a header-shaped multiline value safely` };
}
return { next: editScalarInTable(content, "features.multi_agent_v2", key, encoded) };
}
if (featuresBody !== null && featuresV2Entry !== null && hasInlineMultilineTomlString(featuresBody, featuresV2Entry, key)) {
return { error: `multi-line TOML string for ${key} is not editable; convert it to a single-line string first` };
}
const eol = dominantEol(content);
const lines = content.split(/\r?\n/);
const featuresHeader = lines.findIndex(l => /^\s*\[features\]\s*(?:#.*)?$/.test(l));
if (featuresHeader !== -1) {
let featuresEnd = lines.length;
for (let i = featuresHeader + 1; i < lines.length; i++) {
if (/^\s*\[/.test(lines[i])) { featuresEnd = i; break; }
}
for (let i = featuresHeader + 1; i < featuresEnd; i++) {
const line = lines[i];
const inlineMatch = line.match(/^(\s*)multi_agent_v2\s*=\s*\{/);
if (inlineMatch) {
const openIdx = inlineMatch[0].length - 1;
const closeIdx = findInlineTableEnd(line, openIdx);
if (closeIdx === -1) return { error: "malformed multi_agent_v2 inline table" };
const entry = findInlineEntry(line, openIdx + 1, closeIdx, key);
if (encoded === null) {
if (!entry) return { next: content };
let start = entry.keyStart;
let stop = entry.valueEnd;
let j = stop;
while (j < closeIdx && line[j] === " ") j++;
if (line[j] === ",") {
stop = j + 1;
while (stop < closeIdx && line[stop] === " ") stop++;
} else {
let k = start;
while (k > openIdx + 1 && line[k - 1] === " ") k--;
if (line[k - 1] === ",") start = k - 1;
}
lines[i] = line.slice(0, start) + line.slice(stop);
return { next: applyEol(lines.join("\n"), eol) };
}
if (entry) {
if (line.slice(entry.valueStart, entry.valueEnd).trim() === encoded) return { next: content };
lines[i] = line.slice(0, entry.valueStart) + encoded + line.slice(entry.valueEnd);
} else {
let insertPos = closeIdx;
while (insertPos > openIdx + 1 && line[insertPos - 1] === " ") insertPos--;
const hasEntries = line.slice(openIdx + 1, insertPos).trim().length > 0;
const insertion = hasEntries
? `, ${key} = ${encoded} `
: ` ${key} = ${encoded} `;
lines[i] = line.slice(0, insertPos) + insertion + line.slice(closeIdx);
}
return { next: applyEol(lines.join("\n"), eol) };
}
const boolMatch = line.match(/^(\s*)multi_agent_v2\s*=\s*(true|false)(\s*(?:#.*)?)$/);
if (boolMatch) {
if (encoded === null) return { next: content };
lines[i] = `${boolMatch[1]}multi_agent_v2 = { enabled = ${boolMatch[2]}, ${key} = ${encoded} }${boolMatch[3]}`;
return { next: applyEol(lines.join("\n"), eol) };
}
}
if (featuresV2Entry !== null) {
return { error: "multi_agent_v2 inside a multiline [features] table is not editable safely" };
}
}
if (encoded === null) return { next: content };
const suffix = content.endsWith("\n") || content.length === 0 ? "" : eol;
const separator = content.length > 0 && !content.endsWith(`${eol}${eol}`) ? eol : "";
const tableText = `[features.multi_agent_v2]${eol}${key} = ${encoded}${eol}`;
return { next: `${content}${suffix}${separator}${tableText}` };
}, heldConfigWriteLock);
}
export function setSubagentDeveloperInstructions(value: string | null, configPath?: string, heldConfigWriteLock?: LockHandle): ConfigEditResult {
return setV2StringField("subagent_developer_instructions", value, configPath, heldConfigWriteLock);
}
export const MODE_HINT_UNSUPPORTED_ERROR =
"installed Codex does not support multi_agent_mode_hint_text; update Codex first";
/**
* Persist `features.multi_agent_v2.multi_agent_mode_hint_text`, or remove the key
* when `value` is null. Same encoding coverage and upstream-name discipline as
* `setSubagentDeveloperInstructions`; the upstream struct rejects unknown fields,
* so the key spelling must match codex-rs exactly.
*/
export function setMultiAgentModeHintText(value: string | null, configPath?: string, heldConfigWriteLock?: LockHandle): ConfigEditResult {
// The upstream `multi_agent_mode_hint_text` key is newer than the v2 config
// surface opencodex already manages; an older Codex build rejects the unknown
// member (`#[serde(deny_unknown_fields)]`) and fails to start. Probe the
// installed runtime binary for the key string and refuse the write when the
// binary provably lacks it. A probe that cannot run (missing binary,
// unreadable file) does not block: that is the test/hermetic path and the
// headless runtime fallback.
if (value !== null) {
const probe = probeCodexSupportsModeHint();
if (probe === false) {
return {
ok: false,
error: MODE_HINT_UNSUPPORTED_ERROR,
};
}
}
const canonicalValue = value === null ? null : canonicalizeOpenCodexModeHint(value);
return setV2StringField("multi_agent_mode_hint_text", canonicalValue, configPath, heldConfigWriteLock);
}
export const MODE_HINT_CAPABILITY_CACHE_MAX_ENTRIES = 8;
export const modeHintCapabilityCache = new Map<string, boolean | null>();
export function rememberModeHintCapability(cacheKey: string, capability: boolean | null): void {
modeHintCapabilityCache.delete(cacheKey);
modeHintCapabilityCache.set(cacheKey, capability);
while (modeHintCapabilityCache.size > MODE_HINT_CAPABILITY_CACHE_MAX_ENTRIES) {
const oldest = modeHintCapabilityCache.keys().next().value;
if (oldest === undefined) break;
modeHintCapabilityCache.delete(oldest);
}
}
/**
* True when the installed Codex runtime binary contains the
* `multi_agent_mode_hint_text` config key, false when it provably does not, and
* null when the probe could not run (missing binary, unreadable file).
*/
export function probeCodexSupportsModeHint(): boolean | null {
try {
const runtime = resolveAndPersistCodexRuntime({ env: process.env }).runtime;
const selectedPath = resolveSelectedCommandPath(runtime.command);
let selectedIdentity = selectedPath ?? "";
try { if (selectedPath) selectedIdentity = realpathSync.native(selectedPath); } catch { /* keep lexical path */ }
const candidates = codexNativeBinaryCandidates(runtime.command);
const binaryStatFingerprint = candidates.map(candidate => {
try {
const stat = statSync(candidate);
return `${candidate}\0${stat.dev}\0${stat.ino}\0${stat.size}\0${stat.mtimeMs}\0${stat.ctimeMs}`;
} catch {
return `${candidate}\0missing`;
}
}).join("\0");
const cacheKey = `${runtime.command}\0${runtime.version ?? ""}\0${selectedIdentity}\0${binaryStatFingerprint}`;
const cached = modeHintCapabilityCache.get(cacheKey);
if (cached !== undefined) return cached;
let sawBinary = false;
for (const candidate of candidates) {
try {
if (!existsSync(candidate)) continue;
const buf = readFileSync(candidate);
if (!isNativeExecutable(buf)) continue;
sawBinary = true;
if (buf.includes(Buffer.from("multi_agent_mode_hint_text", "utf8"))) {
rememberModeHintCapability(cacheKey, true);
return true;
}
} catch {
continue;
}
}
// At least one real binary was inspected and none contained the key.
const result = sawBinary ? false : null;
rememberModeHintCapability(cacheKey, result);
return result;
} catch {
return null;
}
}
const CODEX_PLATFORM_PACKAGES = [
["codex-darwin-arm64", "aarch64-apple-darwin", "codex"],
["codex-darwin-x64", "x86_64-apple-darwin", "codex"],
["codex-linux-x64", "x86_64-unknown-linux-musl", "codex"],
["codex-linux-arm64", "aarch64-unknown-linux-musl", "codex"],
["codex-win32-x64", "x86_64-pc-windows-msvc", "codex.exe"],
["codex-win32-arm64", "aarch64-pc-windows-msvc", "codex.exe"],
] as const;
function isNativeExecutable(buf: Buffer): boolean {
if (buf.length < 4) return false;
if (buf[0] === 0x4d && buf[1] === 0x5a) return true; // PE/COFF
const magic = buf.readUInt32BE(0);
return magic === 0x7f454c46 // ELF
|| magic === 0xfeedface || magic === 0xfeedfacf
|| magic === 0xcefaedfe || magic === 0xcffaedfe
|| magic === 0xcafebabe || magic === 0xbebafeca; // Mach-O/fat Mach-O
}
/**
* Candidate native codex binaries to probe. The resolved `command` may be the
* opencodex shim or the npm JS wrapper (`codex.opencodex-real`), neither of
* which embeds the Rust config schema. The real binary ships under the
* platform package's `vendor/<triple>/bin/codex`; also try adjacent wrappers.
*/
function codexNativeBinaryCandidates(command: string): string[] {
const out = new Set<string>();
const resolverBases = new Set<string>();
const selectedPath = resolveSelectedCommandPath(command);
const addSelectedTarget = (target: string) => {
try {
const real = realpathSync.native(target);
out.add(target);
out.add(real);
if (/[\\/]@openai[\\/]codex[\\/]bin[\\/]/.test(real)) resolverBases.add(real);
} catch {
// Missing backing paths cannot establish capability either way.
}
};
// Follow the resolved command to its real location. The opencodex shim and
// the npm JS wrapper resolve to `@openai/codex/bin/codex.js`; the native
// binary lives in the sibling platform package's vendor directory.
if (selectedPath) {
addSelectedTarget(selectedPath);
for (const target of selectedShimBackingPaths(selectedPath)) addSelectedTarget(target);
}
// npm's Windows wrappers are ordinary scripts. Resolve from both the global
// prefix layout and a project-local node_modules/.bin layout; createRequire
// then follows the selected installation's own dependency tree (including
// pnpm/nested optional dependencies) without consulting unrelated PATH bins.
const wrapperPath = selectedPath ?? command;
if (/\.(?:cmd|ps1)$/i.test(wrapperPath)) {
resolverBases.add(resolve(dirname(wrapperPath), "node_modules", "@openai", "codex", "bin", "codex.js"));
resolverBases.add(resolve(dirname(wrapperPath), "..", "@openai", "codex", "bin", "codex.js"));
}
for (const base of resolverBases) {
const requireFromSelected = createRequire(base);
for (const [pkg, triple, exe] of CODEX_PLATFORM_PACKAGES) {
try {
const manifest = requireFromSelected.resolve(`@openai/${pkg}/package.json`);
out.add(join(dirname(manifest), "vendor", triple, "bin", exe));
} catch {
// Optional platform packages for other targets are normally absent.
}
}
}
return [...out];
}
/** Backing paths tied to this exact OCX shim entry in codex-shim.json. */
function selectedShimBackingPaths(commandPath: string): string[] {
try {
const configDir = getConfigDir();
const state = JSON.parse(readFileSync(join(configDir, "codex-shim.json"), "utf8")) as {
schema?: unknown;
mode?: unknown;
wrapperPath?: unknown;
originalPath?: unknown;
backupPath?: unknown;
realPath?: unknown;
wrappers?: Array<Record<string, unknown>>;
};
const overlay = decodeOverlayState(state, configDir);
if (overlay) return resolve(overlay.wrapperPath) === resolve(commandPath) ? [overlay.launcherPath] : [];
if (state.schema !== undefined || state.mode !== undefined) return [];
const entries = Array.isArray(state.wrappers) && state.wrappers.length > 0 ? state.wrappers : [state];
const selected = resolve(commandPath);
for (const entry of entries) {
if (typeof entry.wrapperPath !== "string" || resolve(entry.wrapperPath) !== selected) continue;
return [entry.backupPath, entry.realPath, entry.originalPath]
.filter((value): value is string => typeof value === "string" && value.length > 0 && resolve(value) !== selected);
}
} catch {
// Not an OCX-owned shim, or no readable state.
}
return [];
}
/** Resolve only the selected bare command against PATH; never enumerate peers. */
function resolveSelectedCommandPath(command: string): string | null {
if (command.includes("/") || command.includes("\\")) return existsSync(command) ? resolve(command) : null;
for (const dir of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
const candidate = join(dir, command);
if (existsSync(candidate)) return candidate;
}
return null;
}
function editAgentsMaxThreads(value: number | null, configPath?: string, migratedComment?: string): ConfigEditResult {
const path = configPath ?? activeCodexConfigPath();
return editCodexConfigToml(path, (content): TomlEditOutcome => {
const eol = dominantEol(content);
const { lines, headerIdx, entries } = agentsThreadLimitEntries(content);
if (headerIdx === -1) {
if (value === null) return { next: content };
const separator = content.length > 0 && !content.endsWith("\n") ? eol : "";
return { next: `${content}${separator}${eol}[agents]${eol}${AGENTS_THREAD_LIMIT_KEY} = ${value}${migratedComment ?? ""}${eol}` };
}
const selected = entries.find(entry => entry.key === AGENTS_THREAD_LIMIT_KEY) ?? entries[0];
if (entries.length === 1 && selected?.key === AGENTS_THREAD_LIMIT_KEY && selected.value === value
&& value !== null && mergeTrailingComments(selected.comment, migratedComment) === (selected.comment ?? "")) return { next: content };
let comment = selected?.comment;
for (const entry of entries) comment = mergeTrailingComments(comment, entry.comment);
comment = mergeTrailingComments(comment, migratedComment);
for (const entry of [...entries].reverse()) {
if (value !== null && entry === selected) {
const line = lines[entry.index]!;
line.text = `${line.text.match(/^\s*/)?.[0] ?? ""}${AGENTS_THREAD_LIMIT_KEY} = ${value}${comment}`;
} else lines.splice(entry.index, 1);
}
if (value !== null && !selected) {
if (!lines[headerIdx]!.eol) lines[headerIdx]!.eol = eol;
lines.splice(headerIdx + 1, 0, { text: `${AGENTS_THREAD_LIMIT_KEY} = ${value}${comment}`, eol, structural: true });
}
return { next: sourceText(lines) };
});
}
/** Only structural assignments in the supported agents table are editable. */
function agentsThreadLimitEntries(content: string) {
const lines = splitSourceLines(content);
const headerIdx = lines.findIndex(line => line.structural && /^\s*\[agents\]\s*(?:#.*)?$/.test(line.text));
const entries: Array<{ index: number; key: string; value: number | null; comment?: string; editable: boolean }> = [];
if (headerIdx !== -1) {
for (let index = headerIdx + 1; index < lines.length; index++) {
const line = lines[index]!;
if (!line.structural) continue;
if (/^\s*\[/.test(line.text)) break;
const key = rootAssignmentKey(line.text);
if (key !== AGENTS_THREAD_LIMIT_KEY && key !== LEGACY_AGENTS_THREAD_LIMIT_KEY) continue;
const assignment = findTomlAssignment(line.text, key);
const editable = assignment !== null && (index + 1 === lines.length || lines[index + 1]!.structural);
let value: unknown;
try { value = (Bun.TOML.parse(line.text) as Record<string, unknown>)[key]; } catch {
// Match the reader's large-integer fallback without widening edit syntax.
const integer = assignment && /^\d+$/.exec(line.text.slice(assignment.valueStart, assignment.valueEnd).trim());
if (integer) value = Number(integer[0]);
}
entries.push({ index, key, editable, value: typeof value === "number" && Number.isInteger(value) && value >= 1 ? value : null,
comment: assignment ? line.text.slice(assignment.valueEnd).match(/\s*#.*$/)?.[0] : undefined });
}
}
return { lines, headerIdx, entries };
}
function removeMaxConcurrentThreads(configPath?: string): ConfigEditResult {
const path = configPath ?? activeCodexConfigPath();
return editCodexConfigToml(path, (content): TomlEditOutcome => {
const eol = dominantEol(content);
const lines = content.split(/\r?\n/);
const headerIdx = lines.findIndex(l => /^\s*\[features\.multi_agent_v2\]\s*(?:#.*)?$/.test(l));
if (headerIdx !== -1) {
let end = lines.length;
for (let i = headerIdx + 1; i < lines.length; i++) {
if (/^\s*\[/.test(lines[i])) { end = i; break; }
}
const keyIdx = lines.findIndex((line, i) => i > headerIdx && i < end && /^\s*max_concurrent_threads_per_session\s*=/.test(line));
if (keyIdx !== -1) {
lines.splice(keyIdx, 1);
return { next: applyEol(lines.join("\n"), eol) };
}
}
const featuresHeader = lines.findIndex(l => /^\s*\[features\]\s*(?:#.*)?$/.test(l));
if (featuresHeader === -1) return { next: content };
let featuresEnd = lines.length;
for (let i = featuresHeader + 1; i < lines.length; i++) {
if (/^\s*\[/.test(lines[i])) { featuresEnd = i; break; }
}
const inlineRe = /^(\s*)multi_agent_v2\s*=\s*\{([^}]*)\}(\s*#.*)?$/;
for (let i = featuresHeader + 1; i < featuresEnd; i++) {
const inline = lines[i].match(inlineRe);
if (!inline || !/(?:^|,)\s*max_concurrent_threads_per_session\s*=/.test(inline[2])) continue;
const body = inline[2]
.replace(/^\s*max_concurrent_threads_per_session\s*=\s*\d+\s*,?\s*/, "")
.replace(/,\s*max_concurrent_threads_per_session\s*=\s*\d+\s*(?=,|$)/, "")
.trim();
lines[i] = `${inline[1]}multi_agent_v2 = { ${body} }${inline[3] ?? ""}`;
return { next: applyEol(lines.join("\n"), eol) };
}
return { next: content };
});
}
function ensureDisabledV2Config(value: number | null, configPath?: string, migratedComment?: string): ConfigEditResult {
const path = configPath ?? activeCodexConfigPath();
return editCodexConfigToml(path, (content): TomlEditOutcome => {
if (tomlTableBody(content, "features.multi_agent_v2") !== null || tomlTableBody(content, "features")?.match(/^\s*multi_agent_v2\s*=/m)) {
if (value === null) return { next: content };
// The content-level edit, not the exported writer: this section already
// holds `path`'s write lock and a nested acquire would refuse itself.
return maxConcurrentThreadsEdit(content, value, migratedComment);
}
const eol = dominantEol(content);
const suffix = content.endsWith("\n") || content.length === 0 ? "" : eol;
const table = `[features.multi_agent_v2]${eol}enabled = false${value === null ? "" : `${eol}max_concurrent_threads_per_session = ${value}${migratedComment ?? ""}`}${eol}`;
return { next: `${content}${suffix}${content.length > 0 && !content.endsWith(`${eol}${eol}`) ? eol : ""}${table}` };
});
}
/**
* The effective concurrency limit expressed in the units of the currently ACTIVE
* backend: under V2 the total-thread limit upstream enforces, under V1 the child
* limit. The active backend's own key wins; the other backend's key is translated
* across the root-agent slot. Display path only — never throws: a stored value
* outside the translatable range is returned raw (at that magnitude the ±1 root
* slot is already below float precision, and crashing `ocx v2 status` or
* `GET /api/v2` is not a price worth paying for a translation that means nothing).
* Migration code uses `discoverStoredThreadLimit` instead, which keeps provenance.
*/
export function getLogicalMaxThreads(configPath?: string): number | null {
if (isMultiAgentV2Enabled(configPath)) {
const v2 = getMaxConcurrentThreads(configPath);
if (v2 !== null) return v2;
const legacy = getAgentsMaxThreads(configPath);
if (legacy === null) return null;
return isTranslatableV1ChildLimit(legacy) ? v1ChildLimitToV2TotalLimit(legacy) : legacy;
}
const legacy = getAgentsMaxThreads(configPath);
if (legacy !== null) return legacy;
const v2 = getMaxConcurrentThreads(configPath);
if (v2 === null) return null;
return isTranslatableV2TotalLimit(v2) ? v2TotalLimitToV1ChildLimit(v2) : v2;
}
type ThreadLimitUnits = "v1-child" | "v2-total";
/**
* Which storage the active limit lives in, in that storage's native units. The
* active backend's own key wins; the other backend's key is the fallback and keeps
* ITS units. Never translates and never throws. This is the migration-side sibling
* of `getLogicalMaxThreads`: a migration needs to know exactly which storage the
* value came from, and a display function's raw fallback would lose that.
*/
function discoverStoredThreadLimit(configPath?: string): { value: number; units: ThreadLimitUnits } | null {
if (isMultiAgentV2Enabled(configPath)) {
const v2 = getMaxConcurrentThreads(configPath);
if (v2 !== null) return { value: v2, units: "v2-total" };
const legacy = getAgentsMaxThreads(configPath);
return legacy === null ? null : { value: legacy, units: "v1-child" };
}
const legacy = getAgentsMaxThreads(configPath);
if (legacy !== null) return { value: legacy, units: "v1-child" };
const v2 = getMaxConcurrentThreads(configPath);
return v2 === null ? null : { value: v2, units: "v2-total" };
}
function activeThreadComment(content: string, v2Enabled: boolean): string | undefined {
const entries = agentsThreadLimitEntries(content).entries;
let legacy = (entries.find(entry => entry.key === AGENTS_THREAD_LIMIT_KEY) ?? entries[0])?.comment;
for (const entry of entries) legacy = mergeTrailingComments(legacy, entry.comment) || undefined;
const dedicated = tomlTableBody(content, "features.multi_agent_v2")
?.match(/^\s*max_concurrent_threads_per_session\s*=\s*\d+([ \t]*#.*)$/m)?.[1];
const features = tomlTableBody(content, "features");
const inlineLine = features?.match(/^\s*multi_agent_v2\s*=\s*\{([^}]*)\}([ \t]*#.*)$/m);
const inline = inlineLine && /(?:^|,)\s*max_concurrent_threads_per_session\s*=\s*\d+\s*(?:,|$)/.test(inlineLine[1])
? inlineLine[2]
: undefined;
return v2Enabled ? dedicated ?? inline ?? legacy : legacy ?? dedicated ?? inline;
}
let migrationEditSeq = 0;
/** Both residual classes gate the memo release: a plain residual and a
* secret-bearing one alike keep their destination memo while the file
* remains on disk. Exported for the regression seam. */
export function isAtomicResidualError(error: unknown): boolean {
return error instanceof AtomicWriteResidualTempError || error instanceof AtomicWriteSecretResidualError;
}
/**
* Stage the temp-copy edits then swap `path` in one pass.
*
* Caller must already hold `path`'s config write lock —
* `transitionMultiAgentV2` is that caller, and it holds the lock across the
* whole migration so a foreign write cannot land between its stages or be
* discarded by the byte-restore rollback. The per-call edits inside run on the
* temp path, which takes its own lock harmlessly.
*/
function applyConfigEditsAtomically(path: string, held: LockHandle, edit: (tempPath: string) => ConfigEditResult): ConfigEditResult {
const content = readConfigText(path);
if (content === null) return { ok: false, error: `config.toml not readable at ${path}` };
const tempPath = `${path}.ocx-migration.${process.pid}.${++migrationEditSeq}`;
// An inner residual temp (AtomicWriteResidualTempError) keeps its
// destination-keyed memo: fail-closed while the residual exists.
let innerResidual = false;
try {
atomicWriteFile(tempPath, content);
const result = edit(tempPath);
if (!result.ok) return result;
const edited = readConfigText(tempPath);
if (edited === null) return { ok: false, error: "temporary config migration output is unreadable" };
if (edited === content) return { ok: true, changed: false };
publishConfigWrite(path, held, (destination, hooks) => atomicWriteFile(destination, edited, undefined, hooks));
return { ok: true, changed: true };
} catch (error) {
if (isAtomicResidualError(error)) innerResidual = true;
throw error;
} finally {
try {
unlinkSync(tempPath);
if (!innerResidual) forgetEphemeralSecretPath(tempPath);
} catch (error) {
// Already absent is also proven-absent; other failures keep the memo.
if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") {
if (!innerResidual) forgetEphemeralSecretPath(tempPath);
}
}
}
}
export type MultiAgentV2TransitionResult =
| { ok: true; changed: boolean; threadLimit: number | null }
| { ok: false; error: string; retryable?: boolean };
function transitionConfigError(content: string, explicitThreadLimit: boolean): string | null {
if (/^\s*(?:features\.multi_agent_v2(?:\.[A-Za-z0-9_]+)?|agents\.(?:max_threads|max_concurrent_threads_per_session))\s*=/m.test(content)) {
return "dotted multi-agent config keys are not supported for automatic migration";
}
const dedicatedTables = content.match(/^\s*\[features\.multi_agent_v2\]\s*(?:#.*)?$/gm) ?? [];
const featuresTables = content.match(/^\s*\[features\]\s*(?:#.*)?$/gm) ?? [];
const agentsTables = content.match(/^\s*\[agents\]\s*(?:#.*)?$/gm) ?? [];
if (dedicatedTables.length > 1 || featuresTables.length > 1 || agentsTables.length > 1) {
return "duplicate multi-agent TOML tables cannot be migrated safely";
}
const features = tomlTableBody(content, "features");
const featureDefs = features?.match(/^\s*multi_agent_v2\s*=/gm) ?? [];
if (featureDefs.length > 1 || (dedicatedTables.length === 1 && featureDefs.length === 1)) {
return "duplicate multi_agent_v2 definitions cannot be migrated safely";
}
if (features && /^\s*multi_agent_v2\.(?:enabled|max_concurrent_threads_per_session)\s*=/m.test(features)) {
return "dotted multi_agent_v2 fields are not supported for automatic migration";
}
const entries = agentsThreadLimitEntries(content).entries;
const parsedAgents = parsedTomlTable(content, "agents");
for (const key of [AGENTS_THREAD_LIMIT_KEY, LEGACY_AGENTS_THREAD_LIMIT_KEY]) {
const matches = entries.filter(entry => entry.key === key);
if (matches.length > 1) return `duplicate agents.${key} definitions cannot be migrated safely`;
if (parsedAgents && Object.hasOwn(parsedAgents, key) && matches.length === 0) {
return "unsupported agents thread-limit storage cannot be migrated safely";
}
}
if (entries.some(entry => !entry.editable)) return "unsupported agents thread-limit value cannot be migrated safely";
if (!explicitThreadLimit && (entries.some(entry => entry.value === null) || (entries.length === 2 && entries[0]!.value !== entries[1]!.value))) {
return "conflicting or invalid agents thread-limit aliases require an explicit thread limit";
}
const dedicated = tomlTableBody(content, "features.multi_agent_v2");
if ((dedicated?.match(/^\s*max_concurrent_threads_per_session\s*=/gm) ?? []).length > 1) {
return "duplicate v2 thread-limit definitions cannot be migrated safely";
}
return null;
}
/**
* Toggle native multi_agent_v2 while moving the active thread limit to the key
* valid for the destination version. Any failed command/postcondition restores
* the exact original config bytes; alias drift restores only the locked canonical target.
*/
export function transitionMultiAgentV2(
enabled: boolean,
toggleFeature: (enabled: boolean, env: NodeJS.ProcessEnv, validateBeforeSpawn: () => void) => void,
options: { configPath?: string; threadLimit?: number; heldConfigWriteLock?: LockHandle } = {},
): MultiAgentV2TransitionResult {
if (options.threadLimit !== undefined && (!Number.isSafeInteger(options.threadLimit) || options.threadLimit < 1)) {
return { ok: false, error: "thread limit must be a safe integer >= 1" };
}
const path = options.configPath ?? activeCodexConfigPath();
if (codexHomeIsAbsent(dirname(path))) return { ok: false, error: `config.toml not readable at ${path}` };
const runTransition = (held: LockHandle): MultiAgentV2TransitionResult => {
const original = readConfigText(path);
if (original === null) return { ok: false, error: `config.toml not readable at ${path}` };
const preflightError = transitionConfigError(original, options.threadLimit !== undefined);
if (preflightError) return { ok: false, error: preflightError };
const beforeEnabled = isMultiAgentV2Enabled(path);
// A caller-supplied limit is already in the DESTINATION backend's units and is
// never translated. A discovered limit carries the units of the storage it was
// read from and crosses the root-slot boundary only when those units differ
// from the destination's — which covers both backend flips and same-state
// storage migrations (legacy-only under V2, V2-only under V1). The range
// check runs only when a translation is actually needed, and before the try
// block so an out-of-range stored value is a normal error result rather than
// a RangeError escaping the rollback contract.
const discovered = discoverStoredThreadLimit(path);
const destinationUnits: ThreadLimitUnits = enabled ? "v2-total" : "v1-child";
let threadLimit = options.threadLimit ?? discovered?.value ?? null;
if (options.threadLimit === undefined && discovered !== null && discovered.units !== destinationUnits) {
const translatable = discovered.units === "v1-child" ? isTranslatableV1ChildLimit : isTranslatableV2TotalLimit;
if (!translatable(discovered.value)) {
return { ok: false, error: `stored thread limit out of translatable range: ${discovered.value}` };
}
threadLimit = discovered.units === "v1-child"
? v1ChildLimitToV2TotalLimit(discovered.value)
: v2TotalLimitToV1ChildLimit(discovered.value);
}
if (threadLimit !== null && !Number.isSafeInteger(threadLimit)) {
return { ok: false, error: "stored thread limit cannot be written safely; supply an explicit safe integer limit" };
}
const migratedComment = activeThreadComment(original, beforeEnabled);
try {
return withConfigWriteRecovery(path, held, () => {
if (beforeEnabled !== enabled) assertNativeConfigWriteDestination(path, held);
if (enabled) {
if (!beforeEnabled) {
const staged = applyConfigEditsAtomically(path, held, tempPath => {
const v2 = ensureDisabledV2Config(threadLimit, tempPath, migratedComment);
if (!v2.ok) return v2;
return editAgentsMaxThreads(null, tempPath);
});
if (!staged.ok) throw new Error(staged.error);
runConfigWriteChild(path, held, (env, validate) => toggleFeature(true, env, validate));
}
if (!isMultiAgentV2Enabled(path)) throw new Error("codex feature command did not enable multi_agent_v2");
const target = applyConfigEditsAtomically(path, held, tempPath => {
const v2 = threadLimit === null
? removeMaxConcurrentThreads(tempPath)
: setMaxConcurrentThreads(threadLimit, tempPath, migratedComment);
if (!v2.ok) return v2;
return editAgentsMaxThreads(null, tempPath);
});
if (!target.ok) throw new Error(target.error);
if (hasAgentsMaxThreads(path) || getMaxConcurrentThreads(path) !== threadLimit) throw new Error("v2 thread-limit migration postcondition failed");
} else {
if (beforeEnabled) runConfigWriteChild(path, held, (env, validate) => toggleFeature(false, env, validate));
if (isMultiAgentV2Enabled(path)) throw new Error("codex feature command did not disable multi_agent_v2");
const target = applyConfigEditsAtomically(path, held, tempPath => {
const v2 = removeMaxConcurrentThreads(tempPath);
if (!v2.ok) return v2;
return editAgentsMaxThreads(threadLimit, tempPath, migratedComment);
});
if (!target.ok) throw new Error(target.error);
const agents = parsedTomlTable(readConfigText(path) ?? "", "agents");
if (getMaxConcurrentThreads(path) !== null || getAgentsMaxThreads(path) !== threadLimit || (agents && Object.hasOwn(agents, LEGACY_AGENTS_THREAD_LIMIT_KEY))) throw new Error("v1 thread-limit migration postcondition failed");
}
return { ok: true, changed: readConfigText(path) !== original, threadLimit };
});
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (err instanceof ConfigWriteDestinationChanged) return { ok: false, error: message, retryable: false };
return { ok: false, error: message };
}
};
/*
* The whole migration — staged edits, the codex-features subprocess, the
* postcondition checks, and a possible byte-restore rollback — runs under
* `path`'s write lock. A foreign write that could once land between stages
* is now refused instead of silently surviving into the rolled-back bytes.
*
* A caller that already holds the lock (the injector, whose wider section
* must also cover the artifact commit) passes its handle: re-acquiring the
* same lock file would refuse itself.
*/
const locked = withConfigWriteLockHeld(path, options.heldConfigWriteLock, runTransition);
if (!locked.ok) return { ok: false, error: configWriteLockFailureMessage(locked), ...(locked.error === "unsafe" ? { retryable: false } : {}) };
return locked.value;
}