Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
22.6 KB
Raw Blame
/**
 * 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';
}