@lyupro/codex-bridge 0.1.0

package/src/runner/schemas.mjs

@@ -0,0 +1,135 @@
+/**
+ * The shape each agent's answer must have, one JSON schema per agent.
+ *
+ * Handed to `codex exec --output-schema`, so a run that answers in the wrong shape is
+ * rejected by Codex itself rather than discovered later by write-meta.mjs. Keyed by agent
+ * next to INSTRUCTIONS in prompts.mjs: the two are the same choice made twice, and looking
+ * either of them up by agent name is what keeps the three agents from drifting apart.
+ */
+const SCOUT_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  additionalProperties: false,
+  required: ['answer', 'answers', 'findings', 'unknowns', 'report_markdown'],
+  properties: {
+    answer: { type: 'string', minLength: 1 },
+    // Required, not optional: a schema that only demanded a non-empty `answer` accepted a
+    // run that replied to six numbered questions with one table of coordinates. One object
+    // per question, each carrying its own prose — coordinates live in `evidence`.
+    answers: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['question_id', 'answer', 'evidence'],
+        properties: {
+          question_id: { type: 'string', pattern: '^Q\\d+$' },
+          answer: { type: 'string', minLength: 1 },
+          evidence: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['fact', 'where', 'confidence'],
+        properties: {
+          fact: { type: 'string', minLength: 1 },
+          where: { type: 'string' },
+          confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+        },
+      },
+    },
+    unknowns: { type: 'array', items: { type: 'string' } },
+    report_markdown: { type: 'string', minLength: 1 },
+  },
+};
+
+const BUILD_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  additionalProperties: false,
+  required: ['summary', 'changes', 'verify_command', 'verify_passed', 'leftovers', 'report_markdown'],
+  properties: {
+    summary: { type: 'string', minLength: 1 },
+    changes: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['file', 'what', 'why'],
+        properties: {
+          // One entry, one path. As a bare non-empty string this field legitimately
+          // collected `src/cost/{types,reader}.ts` and `a/*.test.ts; b/*.test.ts` — honest
+          // answers to "which files", and unmatchable against the worktree, so a run that
+          // really had done the work was failed for the way it described it (2026-07-31,
+          // run 120340). The pattern makes the folded forms impossible instead of merely
+          // discouraged: no `*`, `?`, braces, `;`, `,` or whitespace.
+          file: {
+            type: 'string',
+            minLength: 1,
+            pattern: '^[^*?{};,\\s]+$',
+            description:
+              'Exactly one repository-root-relative path, in the form printed by git ' +
+              '(for example packages/agent-sdk/src/cost/types.ts). Globs, brace expansion, ' +
+              'and lists are prohibited — use a separate entry for each file.',
+          },
+          what: { type: 'string' },
+          why: { type: 'string' },
+        },
+      },
+    },
+    verify_command: { type: ['string', 'null'] },
+    verify_passed: { type: ['boolean', 'null'] },
+    leftovers: { type: 'array', items: { type: 'string' } },
+    report_markdown: { type: 'string', minLength: 1 },
+  },
+};
+
+const REVIEW_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  additionalProperties: false,
+  required: ['verdict', 'summary', 'findings', 'next_steps'],
+  properties: {
+    verdict: { type: 'string', enum: ['approve', 'needs-attention'] },
+    summary: { type: 'string', minLength: 1 },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: [
+          'severity',
+          'title',
+          'body',
+          'file',
+          'line_start',
+          'line_end',
+          'confidence',
+          'recommendation',
+        ],
+        properties: {
+          severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
+          title: { type: 'string', minLength: 1 },
+          body: { type: 'string', minLength: 1 },
+          file: { type: 'string' },
+          line_start: { type: 'integer' },
+          line_end: { type: 'integer' },
+          confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+          recommendation: { type: 'string', minLength: 1 },
+        },
+      },
+    },
+    next_steps: { type: 'array', items: { type: 'string' } },
+  },
+};
+
+/** Same three keys as AGENTS in write-meta.mjs; parseArgs() has already refused anything else. */
+export const SCHEMAS = {
+  'codex-scout': SCOUT_SCHEMA,
+  'codex-build': BUILD_SCHEMA,
+  'codex-review': REVIEW_SCHEMA,
+};

package/src/runner/worker.mjs

@@ -0,0 +1,62 @@
+/**
+ * The half that outlives the caller: Codex itself, the "after" snapshots, the verdict.
+ *
+ * It takes its whole order from worker.json, written by launcher.mjs into the run folder —
+ * after the split that file is the only connection between the two halves. Read here:
+ * `repo`, `agent`, `args`, `is_git_repo`, `budget_minutes`. Written there: those five plus
+ * `slug` and `launcher_pid`, which nothing here needs but a run folder read back months later
+ * does. The launcher must write the selected mode's budget into worker.json before spawning
+ * this half, so the worker never re-reads run-config.json and one run cannot acquire two
+ * configurations.
+ * Neither side may change the shape alone.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { collect, exitCodeFor, AGENTS } from '../write-meta.mjs';
+import { setRun, emitReply } from './run-context.mjs';
+import { git, headSha, branchName, worktreeSnapshot, findFakeDone } from './git-state.mjs';
+import { runCodex } from './codex-cmd.mjs';
+
+/**
+ * Runs the order in runDir and answers into reply.txt, never to a console — nothing here
+ * may depend on anyone still being on the other end of a pipe.
+ */
+export async function worker(runDir) {
+  const cfg = JSON.parse(fs.readFileSync(path.join(runDir, 'worker.json'), 'utf8'));
+  const repoRoot = cfg.repo;
+  setRun(runDir, cfg.agent);
+
+  const exit = await runCodex(
+    cfg.args,
+    fs.readFileSync(path.join(runDir, 'task.md'), 'utf8'),
+    path.join(runDir, 'raw.log'),
+    cfg.budget_minutes,
+  );
+
+  if (cfg.agent === 'codex-build') {
+    fs.writeFileSync(path.join(runDir, 'head-after.txt'), `${cfg.is_git_repo ? headSha(repoRoot) : ''}\n`);
+    fs.writeFileSync(path.join(runDir, 'branch-after.txt'), `${cfg.is_git_repo ? branchName(repoRoot) : ''}\n`);
+    fs.writeFileSync(path.join(runDir, 'git-after.txt'), git(repoRoot, ['status', '--porcelain']).stdout || '');
+    fs.writeFileSync(path.join(runDir, 'state-after.txt'), `${worktreeSnapshot(repoRoot)}\n`);
+    fs.writeFileSync(path.join(runDir, 'diff.stat'), git(repoRoot, ['diff', '--stat']).stdout || '');
+    fs.writeFileSync(path.join(runDir, 'flags.txt'), findFakeDone(repoRoot));
+  }
+
+  // Human-readable report is carried inside the schema: a read-only scout cannot write
+  // files itself, so the runner unpacks it.
+  const resultPath = path.join(runDir, AGENTS[cfg.agent].result);
+  if (cfg.agent !== 'codex-review') {
+    try {
+      const result = JSON.parse(fs.readFileSync(resultPath, 'utf8'));
+      if (result.report_markdown) fs.writeFileSync(path.join(runDir, 'report.md'), `${result.report_markdown}\n`);
+    } catch {
+      // No parseable result — write-meta.mjs turns that into FAIL with the log reason.
+    }
+  }
+
+  // collect() writes meta.json and closes status.json; reply.txt comes last, so the launcher
+  // seeing a reply is proof the verdict behind it is already on disk.
+  const { meta, reply } = collect(runDir, cfg.agent, exit);
+  emitReply(reply);
+  process.exit(exitCodeFor(meta.status));
+}

package/src/write-meta.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * Turns one Codex run directory into accounting plus a verdict:
+ *   node write-meta.mjs <runDir> <agent> <exitCode>
+ *
+ * This is the only entry point that reads a run's artifacts. It writes meta.json — quota
+ * accounting that survives deletion of the gitignored raw.log — and derives the run
+ * status from what is actually on disk: exit code, log size, result file, git state.
+ * A dispatcher agent therefore cannot report an outcome its own run does not support.
+ *
+ * The reply lines printed here ARE the reply. Agents forward this stdout verbatim
+ * instead of composing prose, which is what keeps a delegated run at five lines.
+ *
+ * All three agents go through this file: accounting and verdict must not fork into
+ * three slightly different copies.
+ *
+ * The work itself lives in meta/, one concern per module: paths.mjs reads artifacts and
+ * makes two spellings of a path meet, chain.mjs finds the earlier passes of the same task,
+ * run-state.mjs keeps status.json honest, verdict.mjs decides OK/FAIL/LIMIT, reply.mjs
+ * renders the lines. Importers name this file and nothing below it.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { changedPaths, readJson, readText, size } from './meta/paths.mjs';
+import { splitRunChanges } from './meta/environment.mjs';
+import { writeStatus } from './meta/run-state.mjs';
+import { resolveStatus } from './meta/verdict.mjs';
+import { AGENTS, failReply, limitReply } from './meta/reply.mjs';
+
+export { expandDeclared, globToRegExp, readJson } from './meta/paths.mjs';
+export { chainBaseline, chainRuns, taskFingerprint } from './meta/chain.mjs';
+export { abandonedBranchDrift, activeRun, markAbandoned, writeFailure } from './meta/run-state.mjs';
+export { outOfScope, reportVersusWork } from './meta/verdict.mjs';
+export { AGENTS, writeStatus };
+
+/**
+ * Folder name a repository gets inside codex-runs. A repo whose own folder starts with a
+ * dot (~/.claude, ~/.omc) would otherwise produce a hidden run folder that plain `ls` does
+ * not show and that reads as a service directory rather than a project.
+ */
+export const projectFolder = (repoRoot) => path.basename(repoRoot).replace(/^\.+/, '') || 'repo';
+
+/**
+ * Reads the run directory, writes meta.json, returns {meta, reply}. `reply` is the
+ * exact text a dispatcher is allowed to return.
+ */
+export function collect(runDir, agent, exitCode) {
+  const cfg = AGENTS[agent];
+  if (!cfg) throw new Error(`unknown agent: ${agent} (expected one of ${Object.keys(AGENTS).join(', ')})`);
+
+  const logPath = path.join(runDir, 'raw.log');
+  const resultPath = path.join(runDir, cfg.result);
+  const log = readText(logPath);
+  const logBytes = size(logPath);
+  const result = readJson(resultPath);
+  const resultOk = Boolean(result) && cfg.filled(result);
+  const exit = exitCode === undefined || exitCode === null ? null : Number(exitCode);
+
+  // "tokens used" is followed by the count on the next line, with a non-breaking
+  // thousands separator — strip every non-digit rather than trusting the spacing.
+  const usage = [...log.matchAll(/tokens used[\r\n]+([^\r\n]+)/g)].pop();
+
+  // `codex exec review` reports no usage at all. Null, never 0: a zero would silently
+  // understate the total in /codex:usage.
+  const tokens = usage ? parseInt(usage[1].replace(/\D/g, ''), 10) || null : null;
+
+  const pick = (re) => (log.match(re) || [])[1] || null;
+  const { status, reason, carried } = resolveStatus({ log, logBytes, resultOk, exit, agent, result, runDir });
+
+  const meta = {
+    agent,
+    project: path.basename(path.dirname(runDir)),
+    run: path.basename(runDir),
+    finished_at: new Date().toISOString(),
+    exit,
+    status,
+    reason,
+    // An OK earned by an earlier pass of the same task reads differently from an OK earned
+    // here, and accounting must not blur the two: always present, so its absence in a reply
+    // is never mistaken for "false".
+    carried_from_earlier_run: Boolean(carried),
+    // What the tooling around the run wrote into the tree while it worked. Kept out of the
+    // verdict but never out of the record: this is the audit trail for every path a pattern
+    // excused, so a real edit cannot hide behind one.
+    environment_changes: splitRunChanges(
+      runDir,
+      changedPaths(readText(path.join(runDir, 'state-before.txt')), readText(path.join(runDir, 'state-after.txt'))),
+    ).environment,
+    result_ok: resultOk,
+    log_bytes: logBytes,
+    tokens,
+    tokens_reported: tokens !== null,
+    model: pick(/^model:\s*(\S+)/m),
+    sandbox: pick(/^sandbox:\s*(\S+)/m),
+    // Null for runs made before env.json existed: absence is not the same as "both off".
+    env: readJson(path.join(runDir, 'env.json')),
+    session_id: pick(/^session id:\s*(\S+)/m),
+  };
+
+  fs.writeFileSync(path.join(runDir, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`);
+  // meta.json first, status.json after it: status only ever claims a verdict that is
+  // already on disk.
+  writeStatus(runDir, { state: 'finished', status, finished_at: meta.finished_at });
+
+  const ctx = {
+    runDir,
+    agent,
+    result,
+    resultPath,
+    carried: meta.carried_from_earlier_run,
+    file: (name) => path.join(runDir, name),
+  };
+  const reply =
+    status === 'OK' ? cfg.reply(ctx) : status === 'LIMIT' ? limitReply(ctx, meta) : failReply(ctx, meta);
+
+  return { meta, reply: reply.join('\n') };
+}
+
+/** Exit code mirrors the status so an orchestrator can branch without parsing text. */
+export const exitCodeFor = (status) => (status === 'OK' ? 0 : status === 'LIMIT' ? 3 : 1);
+
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+if (invokedDirectly) {
+  const [runDir, agent, exitCode] = process.argv.slice(2);
+  if (!runDir || !agent) {
+    console.error('usage: node write-meta.mjs <runDir> <agent> <exitCode>');
+    process.exit(1);
+  }
+  const { meta, reply } = collect(runDir, agent, exitCode);
+  console.log(reply);
+  process.exit(exitCodeFor(meta.status));
+}