@lyupro/codex-bridge 0.1.0

package/src/runner/codex-cmd.mjs

@@ -0,0 +1,265 @@
+/**
+ * Everything about invoking the `codex` CLI: which flags a run gets, whether the CLI is
+ * there at all, and how its output reaches raw.log.
+ *
+ * The flag sets below are the ones the three agent files carried before, verbatim.
+ * Sandboxes especially must not drift: codex-scout is read-only through
+ * --ignore-user-config, codex-build needs workspace-write and must NOT get
+ * --ignore-user-config, codex-review needs an explicit --sandbox read-only before the
+ * `review` subcommand.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { writeFailure } from '../write-meta.mjs';
+import { MAX_LOG } from './git-state.mjs';
+import { CLEAN_ENV, RUN_ENV } from './run-env.mjs';
+
+/**
+ * An argument cmd.exe cannot be handed safely, or undefined. `%` is fatal because cmd
+ * expands variables even inside quotes. The launcher asks first, so the refusal costs
+ * nothing; the worker asks again on its own copy, because a process whose stderr goes
+ * nowhere must not be the one to discover this.
+ */
+export const unsafeForCmd = (args) =>
+  ['codex', ...args].find((a) => a.includes('%') || a.includes('"'));
+
+/**
+ * Stop the process that owns the Codex invocation. On Windows that process is cmd.exe, so
+ * child.kill() would reap only the shell and leave Codex spending quota as its grandchild —
+ * the exact orphan left by the killed caller on 2026-07-31. taskkill's tree flag is required;
+ * POSIX has no shell wrapper here, so killing the child itself is the honest boundary.
+ */
+export function stopCodex(child, onWindows = process.platform === 'win32') {
+  if (!onWindows) {
+    child.kill('SIGKILL');
+    return;
+  }
+  const killed = spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], {
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  if (killed.error || killed.status !== 0) child.kill();
+}
+
+/**
+ * Windows npm ships `codex` as codex.cmd, and Node refuses to spawn .cmd without a
+ * shell. One command line through cmd.exe keeps a single code path; every argument is
+ * quoted here, and unsafeForCmd() has already refused the ones that cannot be.
+ *
+ * The log is streamed, not collected: spawnSync kept every byte in memory and wrote the file
+ * only on return, so a worker killed at minute twelve left raw.log missing entirely and the
+ * run became unexplainable (2026-07-31, run 114736). Now whatever Codex has already said is
+ * on disk, and the task text is pushed into stdin by hand since there is no `input` option
+ * outside spawnSync. MAX_LOG stays the ceiling; past it the log is cut with a note rather
+ * than the run being killed — a huge log is a diagnosis, not a reason to lose the work.
+ */
+export function runCodex(args, taskText, logPath, budgetMinutes) {
+  const onWindows = process.platform === 'win32';
+  const deadlineMs =
+    typeof budgetMinutes === 'number' && Number.isFinite(budgetMinutes) && budgetMinutes > 0
+      ? budgetMinutes * 60 * 1000
+      : null;
+  const log = fs.createWriteStream(logPath, { flags: 'a' });
+  let written = 0;
+  let cut = false;
+  const append = (chunk) => {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8');
+    if (written >= MAX_LOG) {
+      if (!cut) {
+        cut = true;
+        log.write(`\nrun-codex: log truncated at ${MAX_LOG} bytes; further output is not saved\n`);
+      }
+      return;
+    }
+    const room = MAX_LOG - written;
+    const slice = buf.length > room ? buf.subarray(0, room) : buf;
+    written += slice.length;
+    log.write(slice);
+  };
+
+  let child;
+  if (onWindows) {
+    // Thrown rather than died: in the worker a bare exit would leave the run open, while a
+    // throw goes through the crash handler and closes it with meta.json like any failure.
+    const bad = unsafeForCmd(args);
+    if (bad) throw new Error(`argument unsafe for cmd.exe (contains % or "): ${bad}`);
+    const cmdline = ['codex', ...args].map((a) => (/[\s&|<>^]/.test(a) ? `"${a}"` : a)).join(' ');
+    child = spawn(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', `"${cmdline}"`], {
+      windowsVerbatimArguments: true,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } else {
+    child = spawn('codex', args, { stdio: ['pipe', 'pipe', 'pipe'] });
+  }
+
+  return new Promise((resolve) => {
+    let failed = false;
+    let deadlineTimer;
+    const startedAt = Date.now();
+    child.stdout.on('data', append);
+    child.stderr.on('data', append);
+    child.on('error', (err) => {
+      failed = true;
+      append(`\nrun-codex: ${err.message}\n`);
+    });
+    // Codex that dies before reading the order leaves an EPIPE here; the exit code and the
+    // log already say what happened, and an unhandled stream error would replace that with
+    // a crash of the runner.
+    child.stdin.on('error', () => {});
+    child.stdin.end(Buffer.from(taskText, 'utf8'));
+    if (deadlineMs !== null) {
+      deadlineTimer = setTimeout(() => {
+        const elapsed = Date.now() - startedAt;
+        log.write(
+          `\nrun-codex: run stopped on its deadline after ${elapsed} ms (budget ${deadlineMs} ms)\n`,
+        );
+        stopCodex(child, onWindows);
+      }, deadlineMs);
+    }
+    child.on('close', (code) => {
+      if (deadlineTimer) clearTimeout(deadlineTimer);
+      log.end(() => resolve(failed || code === null ? 1 : code));
+    });
+  });
+}
+
+/**
+ * Codex missing or not authorised is a deterministic FAIL, never a reason to improvise.
+ * Runs after the folder exists so this failure is recorded like any other.
+ */
+export function requireCodex(runDir, agent) {
+  const probe = spawnSync(
+    process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex',
+    process.platform === 'win32' ? ['/d', '/s', '/c', 'codex --version'] : ['--version'],
+    { encoding: 'utf8' },
+  );
+  if (probe.error || probe.status !== 0) {
+    const why = (probe.stderr || probe.error?.message || 'codex --version is not responding').trim();
+    const { reply } = writeFailure(runDir, agent, `Codex CLI unavailable: ${why}`, [
+      'Operator check: codex --version (and codex login if authorization is rejected)',
+    ]);
+    console.log(reply);
+    process.exit(1);
+  }
+}
+
+/**
+ * Which model runs a mode, and how deep it reasons.
+ *
+ * Three sources, in this order: what the dispatcher asked for this one task, the mode's
+ * configured profile, and finally a depth to fall back on. The order is the whole point —
+ * pinning a model without its depth leaves every run at the fallback, which is how a mode
+ * configured for maximum reasoning would quietly keep working at the shallowest setting.
+ */
+const FALLBACK_EFFORT = 'medium';
+
+/**
+ * A run is one worker, not a team it recruits for itself.
+ *
+ * Codex can spawn subagents when a prompt asks it to, and their edits land in the same
+ * worktree — so they arrive in the snapshot as the run's own work, outside the scope check
+ * that grades it, on quota nobody budgeted. The prompts say not to; this is why they cannot.
+ */
+const NO_SUBAGENTS = ['-c', 'agents.enabled=false'];
+
+/**
+ * Which configured mode an agent is. One table, because the launcher needs the same answer to
+ * pick a run's time budget: a second copy of this mapping is a second place to forget a mode.
+ */
+export const runMode = (agent) =>
+  ({
+    'codex-scout': 'scout',
+    'codex-build': 'build',
+    'codex-review': 'review',
+  })[agent];
+
+function runProfile(opts) {
+  const mode = runMode(opts.agent);
+  // opts.models is how tests state a configuration; a real run reads the one loaded for it.
+  const configured = (opts.models || RUN_ENV?.models || {})[mode] || {};
+  return {
+    model: configured.model || '',
+    effort: opts.effort || configured.effort || FALLBACK_EFFORT,
+  };
+}
+
+export function codexArgs(opts, runDir, isGitRepo) {
+  const schema = path.join(runDir, 'schema.json');
+  const profile = runProfile(opts);
+  const effort = `model_reasoning_effort=${profile.effort}`;
+  const modelArgs = profile.model ? ['-m', profile.model] : [];
+  if (opts.agent === 'codex-scout') {
+    return [
+      'exec',
+      ...CLEAN_ENV,
+      '--ignore-user-config',
+      '-c',
+      effort,
+      ...NO_SUBAGENTS,
+      ...modelArgs,
+      '--sandbox',
+      'read-only',
+      '--skip-git-repo-check',
+      '-C',
+      opts.repo,
+      '--output-schema',
+      schema,
+      '-o',
+      path.join(runDir, 'result.json'),
+      '-',
+    ];
+  }
+  if (opts.agent === 'codex-build') {
+    // --ignore-user-config is deliberately absent: with it Codex forces read-only and
+    // every edit is rejected ("writing is blocked by read-only sandbox").
+    return [
+      'exec',
+      ...CLEAN_ENV,
+      '-c',
+      effort,
+      ...NO_SUBAGENTS,
+      ...modelArgs,
+      '--sandbox',
+      'workspace-write',
+      '-C',
+      opts.repo,
+      ...(isGitRepo ? [] : ['--skip-git-repo-check']),
+      '--output-schema',
+      schema,
+      '-o',
+      path.join(runDir, 'result.json'),
+      '-',
+    ];
+  }
+  // codex-review deliberately does NOT use the `review` subcommand. Two of its traits
+  // break the contract this design rests on: it rejects a scope flag together with a
+  // prompt ("the argument '--uncommitted' cannot be used with '[PROMPT]'"), so task.md
+  // was silently discarded and the review rules never arrived; and it ignores
+  // --output-schema, writing prose into -o, so the old JSON parsing of review.json could
+  // only ever fail — which is what pushed a dispatcher into reviewing the diff itself.
+  //
+  // Plain `codex exec` honours the schema (proven by codex-scout), so the review comes
+  // back as machine-checkable JSON. Scope lives in the prompt as a file list plus the
+  // exact diff command computed by reviewScope(). Read-only through
+  // --ignore-user-config, same as scout: review never needs write access.
+  return [
+    'exec',
+    ...CLEAN_ENV,
+    '--ignore-user-config',
+    '-c',
+    effort,
+    ...NO_SUBAGENTS,
+    ...modelArgs,
+    '--sandbox',
+    'read-only',
+    '-C',
+    opts.repo,
+    '--output-schema',
+    schema,
+    '-o',
+    path.join(runDir, 'review.json'),
+    '-',
+  ];
+}

package/src/runner/git-state.mjs

@@ -0,0 +1,144 @@
+/**
+ * Reads the repository a run works in: what the tree looks like, what changed, what is
+ * under review.
+ *
+ * Everything here answers a question about the repository and nothing here decides anything
+ * about the run. The launcher takes the "before" answers, the worker takes the "after" ones,
+ * and write-meta.mjs compares them — which only works while both halves ask git in exactly
+ * the same words, so they ask it here.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { runsRoot } from './runs-root.mjs';
+
+export const MAX_LOG = 256 * 1024 * 1024;
+
+export const git = (repo, args) =>
+  spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', maxBuffer: MAX_LOG });
+
+/**
+ * Prefix of the run folders as seen from inside the repository, or null when they live
+ * outside it. ~/.claude hosts both the dispatchers and every run folder, so a run against
+ * ~/.claude sees the runner's own artifacts as work: one failed with “out-of-scope changes”
+ * listing its own git-after.txt. The snapshot has to skip them — they are the measuring
+ * instrument, not the measurement.
+ */
+export function runsPrefixInside(repo) {
+  const rel = path.relative(repo, runsRoot());
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return `${rel.split(path.sep).join('/')}/`;
+}
+
+/**
+ * State of the worktree in terms of actual content, not porcelain letters: line counts
+ * per tracked file plus sizes of untracked ones. A porcelain code stays ` M` when Codex
+ * edits an already-modified file, so comparing codes would report "0 files changed" for
+ * a run that did real work.
+ */
+export function worktreeSnapshot(repo) {
+  const skip = runsPrefixInside(repo);
+  // The path is the third tab-separated field in both git outputs used here.
+  const mine = (line) => Boolean(skip) && (line.split('\t')[2] || '').startsWith(skip);
+  const tracked = (git(repo, ['diff', 'HEAD', '--numstat']).stdout || '')
+    .split(/\r?\n/)
+    .filter((line) => line.trim() && !mine(line))
+    .join('\n')
+    .trim();
+  const untracked = (git(repo, ['ls-files', '-o', '--exclude-standard']).stdout || '')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .filter((file) => !(skip && `${file}/`.startsWith(skip)))
+    .map((file) => {
+      let bytes = 0;
+      try {
+        bytes = fs.statSync(path.join(repo, file)).size;
+      } catch {
+        // Vanished between listing and stat: size 0 still marks it as present.
+      }
+      return `U\t${bytes}\t${file}`;
+    });
+  return [tracked, untracked.join('\n')].filter(Boolean).join('\n');
+}
+
+/**
+ * The commit a run starts and ends on. A delegated run is forbidden to commit — the
+ * orchestrator has to see the edits uncommitted in order to accept them — and comparing
+ * HEAD either side is the only way to know whether that held. Empty for a repo without
+ * commits, which write-meta.mjs reads as "nothing to compare", not as a violation.
+ */
+export const headSha = (repo) => (git(repo, ['rev-parse', 'HEAD']).stdout || '').trim();
+
+/**
+ * The branch a run starts and ends on. Empty means detached HEAD, which is data to compare,
+ * not an error: a run may begin detached and stay that way, or leave the repository detached.
+ */
+export const branchName = (repo) =>
+  (git(repo, ['symbolic-ref', '--short', '-q', 'HEAD']).stdout || '').trim();
+
+const FAKE_DONE_RE =
+  /TODO|FIXME|test\.(skip|only)|it\.(skip|only)|describe\.(skip|only)|NotImplemented/;
+
+/**
+ * Traces of fake completion. `git diff` carries nothing for untracked files, so a brand
+ * new file full of TODOs would otherwise pass as "Flags: none" — the one case the check
+ * exists for.
+ */
+export function findFakeDone(repo) {
+  const skip = runsPrefixInside(repo);
+  const hits = (git(repo, ['diff', '-U0']).stdout || '')
+    .split(/\r?\n/)
+    .filter((l) => l.startsWith('+') && FAKE_DONE_RE.test(l));
+  for (const file of (git(repo, ['ls-files', '-o', '--exclude-standard']).stdout || '')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    // Same reason as in worktreeSnapshot: inside ~/.claude the run folder is part of the
+    // worktree, and task.md spells out the very words this scans for ("do not leave TODOs,
+    // test.skip"). A run flagged itself for quoting its own instructions.
+    .filter((file) => !(skip && `${file}/`.startsWith(skip)))) {
+    const full = path.join(repo, file);
+    try {
+      if (fs.statSync(full).size > 1024 * 1024) continue;
+      fs.readFileSync(full, 'utf8')
+        .split(/\r?\n/)
+        .forEach((l, i) => {
+          if (FAKE_DONE_RE.test(l)) hits.push(`${file}:${i + 1}: ${l.trim()}`);
+        });
+    } catch {
+      // Binary or unreadable: nothing to flag.
+    }
+  }
+  return hits.length ? `${hits.slice(0, 20).join('\n')}\n` : '';
+}
+
+/** What exactly is under review, resolved from git rather than from wording. */
+export function reviewScope(repo, mode) {
+  if (mode.startsWith('base:')) {
+    const base = mode.slice(5);
+    return {
+      label: `branch changes against base ${base}`,
+      diffCommand: `git diff ${base}...HEAD`,
+      files: (git(repo, ['diff', '--name-only', `${base}...HEAD`]).stdout || '')
+        .split(/\r?\n/)
+        .filter(Boolean),
+    };
+  }
+  if (mode.startsWith('commit:')) {
+    const sha = mode.slice(7);
+    return {
+      label: `commit ${sha}`,
+      diffCommand: `git show ${sha}`,
+      files: (git(repo, ['show', '--name-only', '--format=', sha]).stdout || '')
+        .split(/\r?\n/)
+        .filter(Boolean),
+    };
+  }
+  return {
+    label: 'uncommitted changes (staged, unstaged, untracked)',
+    diffCommand: 'git status --porcelain && git diff HEAD',
+    files: (git(repo, ['status', '--porcelain']).stdout || '')
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map((l) => l.slice(3).trim()),
+  };
+}