Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* codex-toml.ts — managed marker-block writer for Codex's config.toml
* (#4043, the fired CX2-17 revisit; see TARGETS['codex-2026-08'] in
* host-specs.ts for the verified format assumptions).
*
* Why a direct writer exists at all: `codex mcp add` cannot express an
* inline credential (only `--bearer-token-env-var`, which reintroduces
* the shell-profile dependency framework-spawned codex lacks), so the
* harness lane owns exactly one `[mcp_servers.<name>]` table between two
* full-line comment markers. Everything outside the markers survives
* byte-for-byte. The credential is emitted as
* `http_headers = { Authorization = "Bearer <token>" }` — codex-cli >=0.149
* rejects an inline `bearer_token` for streamable_http AT CONFIG LOAD
* (bricking every codex session, #4574), while the http_headers inline-table
* shape loads on 0.147.x AND 0.149.x (reporter probe in #4574).
*
* Safety invariants [C10 + adversarial-verify corrections]:
* - Foreign-server detection parses the file (Bun.TOML.parse) with our block
* stripped — a header-only regex false-negatives inline tables, dotted
* keys, and quoted headers, and a duplicate table definition is a HARD
* TOML parse error that bricks codex outright.
* - Rewrites REMOVE the old block and RE-ANCHOR at EOF (refusing on trailing
* content would let any later legitimate codex write permanently block
* update/removal; at EOF our table can never absorb someone else's keys).
* - The rendered output is parse-validated BEFORE rename, and our table's
* keys are asserted to be exactly what we wrote; on any failure the
* original file is kept.
* - Exactly one begin/end pair, in order, full-line match — anything else is
* a hand-edit; refuse rather than guess.
* - Secrets hygiene: tmp file created 0600 with a random suffix, the target
* is chmod'd 0600 (it carries a bearer token), and the .bak is chmod'd
* 0600 (on re-runs it carries the PREVIOUS token).
* - CRLF configs are scanned with `\r` stripped and re-emitted with their
* dominant EOL; a missing trailing newline is repaired before append so a
* marker can never glue onto the last line (the run-2 duplicate-append
* brick).
*/
import { chmodSync, copyFileSync, existsSync, readFileSync, statSync } from 'node:fs';
import { atomicWriteTextFile } from './atomic-write.ts';
import { CODEX_TOML_BLOCK_BEGIN, CODEX_TOML_BLOCK_END } from './host-specs.ts';
export interface CodexHttpServerBlock {
/** MCP server name — bare-key charset only (goes into a table header). */
name: string;
/** Streamable-HTTP MCP endpoint url (normalized upstream). */
url: string;
/** Bearer token written inline as `http_headers.Authorization` (the whole
* point of the direct writer; codex-cli >=0.149 rejects `bearer_token`). */
bearerToken: string;
}
export interface WriteCodexBlockResult {
configPath: string;
/** True when a prior managed block was replaced (idempotent re-run). */
replacedPrior: boolean;
backupPath: string | null;
notes: string[];
}
export interface RemoveCodexBlockResult {
configPath: string;
removed: boolean;
backupPath: string | null;
notes: string[];
}
/** Escape a value for a TOML basic string. */
export function tomlString(value: string): string {
if (/[\n\r\0\t]/.test(value)) {
throw new Error('control characters are not allowed in codex config values');
}
return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
}
function assertBareKeyName(name: string): void {
if (!/^[A-Za-z0-9_-]+$/.test(name)) {
throw new Error(
`MCP server name "${name}" is not a bare TOML key ([A-Za-z0-9_-]+) — pick a simpler --name`,
);
}
}
interface BlockSpan {
/** Line index of the begin marker, or -1 when absent. */
begin: number;
/** Line index of the end marker, or -1 when absent. */
end: number;
}
/**
* Locate the managed block in \n-normalized lines. Throws on marker
* anomalies (duplicates, out of order, one without the other) — those are
* hand-edits we must not guess through.
*/
function findBlock(lines: string[]): BlockSpan {
const begins: number[] = [];
const ends: number[] = [];
lines.forEach((line, i) => {
if (line === CODEX_TOML_BLOCK_BEGIN) begins.push(i);
if (line === CODEX_TOML_BLOCK_END) ends.push(i);
});
if (begins.length === 0 && ends.length === 0) return { begin: -1, end: -1 };
if (begins.length !== 1 || ends.length !== 1 || begins[0] > ends[0]) {
throw new Error(
`the gbrain-managed block markers in this config.toml are damaged ` +
`(${begins.length} begin / ${ends.length} end${begins.length === 1 && ends.length === 1 ? ', out of order' : ''}) — ` +
`the file was hand-edited inside the managed region. Fix the markers (or delete the whole block) and re-run.`,
);
}
return { begin: begins[0], end: ends[0] };
}
function stripBlock(lines: string[]): { remainder: string[]; hadBlock: boolean } {
const span = findBlock(lines);
if (span.begin === -1) return { remainder: lines, hadBlock: false };
const remainder = [...lines.slice(0, span.begin), ...lines.slice(span.end + 1)];
return { remainder, hadBlock: true };
}
function parseToml(text: string): Record<string, unknown> {
// Bun.TOML is available in this runtime (no dependency added).
const parsed = (Bun as unknown as { TOML: { parse(t: string): unknown } }).TOML.parse(text);
if (typeof parsed !== 'object' || parsed === null) {
throw new Error('config.toml did not parse to a table');
}
return parsed as Record<string, unknown>;
}
/**
* True when `[mcp_servers.<name>]` is defined OUTSIDE our managed block, in
* ANY toml spelling (header, inline table, dotted key, quoted header,
* array-of-tables). Throws when the surrounding config does not parse —
* appending to a broken file could only deepen the damage.
*/
export function detectForeignCodexServer(configText: string, name: string): boolean {
const server = outsideServer(configText, name);
return server !== undefined && !isToolsOnly(server);
}
/** `mcp_servers.<name>` as defined outside our managed block, or undefined. */
function outsideServer(configText: string, name: string): unknown {
const { remainder } = stripBlock(configText.replace(/\r\n/g, '\n').split('\n'));
const servers = parseToml(remainder.join('\n')).mcp_servers;
return isTable(servers) ? servers[name] : undefined;
}
/**
* Codex's per-tool settings for a server (`[mcp_servers.<name>.tools.<tool>]`,
* e.g. `approval_mode = "approve"` from "always allow", #6799): tool name to
* scalar settings. Null for any other shape, which stays a foreign edit.
*/
export type CodexToolPolicy = Record<string, Record<string, string | number | boolean>>;
const isTable = (value: unknown): value is Record<string, unknown> =>
typeof value === 'object' && value !== null && !Array.isArray(value);
export function codexToolPolicy(value: unknown): CodexToolPolicy | null {
if (!isTable(value)) return null;
for (const settings of Object.values(value)) {
if (!isTable(settings) || Object.values(settings).some(v => !['string', 'number', 'boolean'].includes(typeof v))) return null;
}
return value as CodexToolPolicy;
}
/** A server table holding nothing but a valid tool policy: Codex's approvals, not a server definition. */
function isToolsOnly(server: unknown): boolean {
return isTable(server) && Object.keys(server).join(',') === 'tools' && codexToolPolicy(server.tools) !== null;
}
/** Tools whose Codex settings sit outside our managed block (removing the block would orphan them). */
export function codexToolsOutsideBlock(configText: string, name: string): string[] {
const server = outsideServer(configText, name);
return isToolsOnly(server) ? Object.keys((server as { tools: CodexToolPolicy }).tools) : [];
}
function renderBlock(block: CodexHttpServerBlock, tools: CodexToolPolicy = {}): string[] {
// http_headers inline table, NOT `bearer_token`: codex-cli >=0.149 rejects
// bearer_token for streamable_http at config load (#4574); this shape loads
// on 0.147.x and 0.149.x.
return [
CODEX_TOML_BLOCK_BEGIN,
`[mcp_servers.${block.name}]`,
`url = ${tomlString(block.url)}`,
`http_headers = { Authorization = ${tomlString(`Bearer ${block.bearerToken}`)} }`,
...Object.entries(tools).flatMap(([tool, settings]) => [
`[mcp_servers.${block.name}.tools.${tomlKey(tool)}]`,
...Object.entries(settings).map(([k, v]) => `${tomlKey(k)} = ${typeof v === 'string' ? tomlString(v) : String(v)}`),
]),
CODEX_TOML_BLOCK_END,
];
}
/** Post-render assertion shared by the writer and the snippet renderer: our
* table's keys are EXACTLY [http_headers, url] (plus a `tools` table of
* Codex's own per-tool settings, #6799), and the http_headers inline
* table carries EXACTLY the Authorization header we wrote. Returns an error
* string (caller prefixes its own context) or null when valid. */
function validateOurKeys(ours: unknown): string | null {
const ourKeys = typeof ours === 'object' && ours !== null ? Object.keys(ours as object).sort() : [];
const withTools = ourKeys.join(',') === 'http_headers,tools,url' && codexToolPolicy((ours as Record<string, unknown>).tools) !== null;
if (ourKeys.join(',') !== 'http_headers,url' && !withTools) {
return `keys are [${ourKeys.join(', ')}], expected exactly [http_headers, url] (plus Codex tool settings)`;
}
const headers = (ours as Record<string, unknown>).http_headers;
const headerKeys = typeof headers === 'object' && headers !== null ? Object.keys(headers as object) : [];
if (headerKeys.join(',') !== 'Authorization') {
return `http_headers keys are [${headerKeys.join(', ')}], expected exactly [Authorization]`;
}
return null;
}
/**
* Render the `[mcp_servers.<name>]` table as a paste-ready snippet WITHOUT
* the CODEX_TOML_BLOCK_BEGIN/END lines. The managed markers are SINGLETON —
* findBlock refuses duplicate marker pairs and writeCodexHttpServerBlock
* strips any prior managed block on rewrite — so a printed snippet carrying
* markers would later be stripped or rejected by the writer. A marker-free
* snippet stays ordinary user content: a later managed write sees it as a
* FOREIGN table and refuses to double-define rather than silently absorbing
* it.
*
* Validation mirrors the writer: the bare-key name assertion up front, then
* the rendered text is parsed back and our table's keys are asserted to be
* exactly [http_headers, url] (the same key-set check the writer's
* post-render validation performs).
*/
export function renderCodexHttpServerBlock(block: CodexHttpServerBlock): string {
assertBareKeyName(block.name);
const lines = renderBlock(block).filter(
(line) => line !== CODEX_TOML_BLOCK_BEGIN && line !== CODEX_TOML_BLOCK_END,
);
const text = lines.join('\n');
const parsed = parseToml(text);
const servers = parsed.mcp_servers as Record<string, unknown> | undefined;
const problem = validateOurKeys(servers?.[block.name]);
if (problem !== null) {
throw new Error(`render validation failed: [mcp_servers.${block.name}] ${problem}.`);
}
return text;
}
/** Atomic 0600 write preserving symlinks and the file's dominant EOL
* (forceMode: the file carries a bearer token regardless of prior mode). */
function atomicWriteToml(configPath: string, unixText: string, crlf: boolean): void {
const out = crlf ? unixText.replace(/\n/g, '\r\n') : unixText;
atomicWriteTextFile(configPath, out, { forceMode: 0o600 });
}
/**
* Idempotently write the managed `[mcp_servers.<name>]` block: strip any
* prior managed block, re-anchor the fresh one at EOF, validate the render,
* then swap atomically. The token lands inline, so the file is forced 0600.
*/
export function writeCodexHttpServerBlock(
configPath: string,
block: CodexHttpServerBlock,
): WriteCodexBlockResult {
assertBareKeyName(block.name);
const notes: string[] = [];
let rawText = '';
let existed = false;
if (existsSync(configPath)) {
existed = true;
rawText = readFileSync(configPath, 'utf8');
}
const crlf = rawText.includes('\r\n');
const lines = rawText.replace(/\r\n/g, '\n').split('\n');
const { remainder, hadBlock } = stripBlock(lines);
// #6799: Codex's tool approvals written inside our block are carried into the new one.
const span = findBlock(lines);
const priorServers = span.begin === -1 ? undefined : parseToml(lines.slice(span.begin, span.end + 1).join('\n')).mcp_servers;
const prior = isTable(priorServers) ? priorServers[block.name] : undefined;
const carried: CodexToolPolicy = (isTable(prior) && codexToolPolicy(prior.tools)) || {};
// Foreign ownership guard — a duplicate table definition is a hard TOML
// parse error that would brick codex entirely. A table holding only Codex's
// tool settings is not a server definition (#6799).
const remainderText = remainder.join('\n');
let parsedRemainder: Record<string, unknown>;
try {
parsedRemainder = parseToml(remainderText);
} catch (e) {
throw new Error(
`${configPath} does not parse as TOML outside the gbrain-managed block ` +
`(${(e as Error).message}) — fix the config (codex itself cannot read it either) and re-run.`,
);
}
const servers = parsedRemainder.mcp_servers;
if (isTable(servers) && servers[block.name] !== undefined && !isToolsOnly(servers[block.name])) {
throw new Error(
`[mcp_servers.${block.name}] is already defined in ${configPath} outside the gbrain-managed block — ` +
`refusing to double-define it (that is a hard TOML parse error). ` +
`Remove the existing entry (codex mcp remove ${block.name}) or pick another name (--name).`,
);
}
// Assemble: remainder (trailing newline repaired, trailing blank run
// collapsed to one separator line) + block at EOF.
const trimmed = [...remainder];
while (trimmed.length > 0 && trimmed[trimmed.length - 1].trim() === '') trimmed.pop();
const body = trimmed.length > 0 ? [...trimmed, ''] : [];
const nextLines = [...body, ...renderBlock(block, carried), ''];
const nextText = nextLines.join('\n');
// Post-render validation: parse + assert OUR table's keys are exactly ours.
const rendered = parseToml(nextText);
const renderedServers = rendered.mcp_servers as Record<string, unknown> | undefined;
const ours = renderedServers?.[block.name] as Record<string, unknown> | undefined;
const lost = Object.keys(carried).find(tool => canonicalJson((ours?.tools as CodexToolPolicy | undefined)?.[tool]) !== canonicalJson(carried[tool]));
const problem = validateOurKeys(ours) ?? (lost === undefined ? null : `Codex settings for tool ${lost} did not round-trip`);
if (problem !== null) {
throw new Error(
`post-render validation failed: [mcp_servers.${block.name}] ${problem} — original file left untouched.`,
);
}
let backupPath: string | null = null;
if (existed) {
backupPath = `${configPath}.bak`;
copyFileSync(configPath, backupPath);
chmodSync(backupPath, 0o600); // on re-runs the .bak carries the previous token
const mode = statSync(configPath).mode & 0o777;
if ((mode & 0o077) !== 0) {
notes.push(
`${configPath} was group/other-readable (mode ${mode.toString(8)}); tightened to 0600 — it now carries a bearer token.`,
);
}
}
atomicWriteToml(configPath, nextText, crlf);
return { configPath, replacedPrior: hadBlock, backupPath, notes };
}
/**
* Remove the managed block (marker-keyed; content outside survives
* byte-for-byte). Absent file / absent block are calm no-ops. Damaged
* markers refuse via findBlock — removal never guesses.
*/
export function removeCodexHttpServerBlock(
configPath: string,
name: string,
): RemoveCodexBlockResult {
assertBareKeyName(name);
const notes: string[] = [];
if (!existsSync(configPath)) {
return { configPath, removed: false, backupPath: null, notes: ['no config.toml — nothing to remove'] };
}
const rawText = readFileSync(configPath, 'utf8');
const crlf = rawText.includes('\r\n');
const lines = rawText.replace(/\r\n/g, '\n').split('\n');
const { remainder, hadBlock } = stripBlock(lines);
if (!hadBlock) {
return { configPath, removed: false, backupPath: null, notes: ['no gbrain-managed block — nothing to remove'] };
}
// Validate what we are about to write back — never leave codex unreadable.
const trimmed = [...remainder];
while (trimmed.length > 0 && trimmed[trimmed.length - 1].trim() === '') trimmed.pop();
const nextText = trimmed.length > 0 ? `${trimmed.join('\n')}\n` : '';
if (nextText !== '') parseToml(nextText);
const backupPath = `${configPath}.bak`;
copyFileSync(configPath, backupPath);
chmodSync(backupPath, 0o600);
atomicWriteToml(configPath, nextText, crlf);
return { configPath, removed: true, backupPath, notes };
}
// ── Hash-owned single tables (`gbrain setup codex`) ─────────────────────────
//
// Setup owns individual tables (`[mcp_servers.<name>]`, each
// `[hooks.state."<key>"]`) by the fingerprint of their parsed value, not by
// markers: codex itself may rewrite config.toml and drop comments. A table is
// appended at EOF and removed by its header line through the next header;
// both edits are verified by parsing: everything else in the file must parse
// to exactly what it parsed to before, or the file is left as it was.
export type CodexTomlValue = string | string[] | Record<string, string>;
const tomlKey = (k: string): string => (/^[A-Za-z0-9_-]+$/.test(k) ? k : tomlString(k));
export function codexTomlHeader(path: string[]): string {
return `[${path.map(tomlKey).join('.')}]`;
}
function renderTomlValue(v: CodexTomlValue): string {
if (typeof v === 'string') return tomlString(v);
if (Array.isArray(v)) return `[${v.map(tomlString).join(', ')}]`;
return `{ ${Object.entries(v).map(([k, val]) => `${tomlKey(k)} = ${tomlString(val)}`).join(', ')} }`;
}
/** The parsed value at `path`, or undefined. Throws when the file does not parse. */
export function readCodexTomlTable(configPath: string, path: string[]): unknown {
if (!existsSync(configPath)) return undefined;
let node: unknown = parseToml(readFileSync(configPath, 'utf8'));
for (const seg of path) node = node && typeof node === 'object' && !Array.isArray(node) ? (node as Record<string, unknown>)[seg] : undefined;
return node;
}
const canonicalJson = (v: unknown): string => JSON.stringify(v, (_k, val) =>
val && typeof val === 'object' && !Array.isArray(val) ? Object.fromEntries(Object.keys(val).sort().map((k) => [k, (val as Record<string, unknown>)[k]])) : val);
/** Delete `path` from a parsed document, then drop the ancestors that deletion emptied. */
function withoutPath(doc: Record<string, unknown>, path: string[]): Record<string, unknown> {
const copy = JSON.parse(JSON.stringify(doc)) as Record<string, unknown>;
const chain: Array<Record<string, unknown>> = [copy];
for (const seg of path.slice(0, -1)) {
const next = chain[chain.length - 1]![seg];
if (!next || typeof next !== 'object' || Array.isArray(next)) return copy;
chain.push(next as Record<string, unknown>);
}
delete chain[chain.length - 1]![path[path.length - 1]!];
for (let i = chain.length - 1; i > 0; i--) {
if (Object.keys(chain[i]!).length > 0) break;
delete chain[i - 1]![path[i - 1]!];
}
return copy;
}
/**
* Append `[path]` with `value` at EOF (after an optional comment line). Refuses
* when the table already exists anywhere in the file (a duplicate table is a
* hard parse error that bricks codex) or when the result would not parse to
* the old document plus exactly this table.
*/
export function appendCodexTomlTable(configPath: string, path: string[], value: Record<string, CodexTomlValue>, comment?: string): void {
const raw = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
const crlf = raw.includes('\r\n');
const text = raw.replace(/\r\n/g, '\n');
const before = parseToml(text);
if (readCodexTomlTable(configPath, path) !== undefined) throw new Error(`${configPath} already defines ${codexTomlHeader(path)}; setup never defines a table twice.`);
const block = [...(comment ? [`# ${comment}`] : []), codexTomlHeader(path), ...Object.entries(value).map(([k, v]) => `${tomlKey(k)} = ${renderTomlValue(v)}`)];
const body = text.replace(/\n*$/, '');
const next = `${body ? `${body}\n\n` : ''}${block.join('\n')}\n`;
const after = parseToml(next);
if (canonicalJson(withoutPath(after, path)) !== canonicalJson(before)) throw new Error(`appending ${codexTomlHeader(path)} to ${configPath} would change other settings; the file is left as it was.`);
let node: unknown = after;
for (const seg of path) node = (node as Record<string, unknown> | undefined)?.[seg];
if (canonicalJson(node) !== canonicalJson(value)) throw new Error(`${codexTomlHeader(path)} in ${configPath} did not parse back to what setup wrote; the file is left as it was.`);
atomicWriteTextFile(configPath, crlf ? next.replace(/\n/g, '\r\n') : next, { freshMode: 0o600 });
}
/**
* Remove `[path]`: its header line through the line before the next header
* (plus a directly preceding `# gbrain setup` comment and one separating blank
* line). `unlocatable` when no such header line exists or the edit would change
* anything but this table (it was split, re-rendered or extended); the file is
* then left as it was. The caller checks the table's fingerprint first.
*/
export function removeCodexTomlTable(configPath: string, path: string[], opts: { dryRun?: boolean } = {}): 'removed' | 'absent' | 'unlocatable' {
if (!existsSync(configPath)) return 'absent';
const raw = readFileSync(configPath, 'utf8');
const crlf = raw.includes('\r\n');
const lines = raw.replace(/\r\n/g, '\n').split('\n');
const before = parseToml(lines.join('\n'));
if (readCodexTomlTable(configPath, path) === undefined) return 'absent';
const header = codexTomlHeader(path);
const quoted = `[${path.map((seg) => tomlString(seg)).join('.')}]`;
const start = lines.findIndex((l) => l.trim() === header || l.trim() === quoted);
if (start < 0) return 'unlocatable';
let end = lines.findIndex((l, i) => i > start && /^\s*\[/.test(l));
if (end < 0) end = lines.length;
while (end > start + 1 && /^\s*(#.*)?$/.test(lines[end - 1]!)) end--;
let from = start;
if (from > 0 && lines[from - 1]!.startsWith('# gbrain setup')) from--;
if (from > 0 && lines[from - 1]!.trim() === '') from--;
const kept = [...lines.slice(0, from), ...lines.slice(end)];
while (kept.length > 0 && kept[kept.length - 1]!.trim() === '') kept.pop();
const next = kept.length > 0 ? `${kept.join('\n')}\n` : '';
let after: Record<string, unknown>;
try { after = parseToml(next); } catch { return 'unlocatable'; }
if (canonicalJson(after) !== canonicalJson(withoutPath(before, path))) return 'unlocatable';
if (!opts.dryRun) atomicWriteTextFile(configPath, crlf ? next.replace(/\n/g, '\r\n') : next, { freshMode: 0o600 });
return 'removed';
}