@lyupro/codex-bridge 0.1.1 → 0.1.3

package/src/required-inputs.mjs

@@ -0,0 +1,104 @@
+/**
+ * Defines the inputs the orchestrator must give each Codex dispatcher.
+ *
+ * This contract belongs beside the gate because the dispatcher prompt was the only place that
+ * named order id and scope, so the caller launched codex-build without either value and the
+ * runner refused the call before Codex could do any work. Pass 2 can render the same entries
+ * into agent instructions without creating a second list that can drift.
+ */
+
+const PLACEHOLDER_VALUES = new Set(['todo', 'tbd', 'label', 'none', 'order id', 'scope', 'xxx']);
+
+const freezeEntries = (entries) => Object.freeze(entries.map((entry) => Object.freeze(entry)));
+
+export const REQUIRED_INPUTS = Object.freeze({
+  'codex-scout': freezeEntries([
+    {
+      label: 'order id',
+      source: 'the orchestrator',
+      explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
+      example: 'plan-13-scout-20260804',
+    },
+  ]),
+  'codex-build': freezeEntries([
+    {
+      label: 'order id',
+      source: 'the orchestrator',
+      explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
+      example: 'plan-13-build-20260804',
+    },
+    {
+      label: 'scope',
+      source: 'the orchestrator',
+      explanation: 'Comma-separated globs relative to the repository root, listing every file the run may touch — including each caller of what changes, not only the file being edited. Anything outside the list fails the run.',
+      example: 'src/runner/**,tests/runner/**',
+    },
+  ]),
+  'codex-review': freezeEntries([
+    {
+      label: 'order id',
+      source: 'the orchestrator',
+      explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
+      example: 'plan-13-review-20260804',
+    },
+  ]),
+});
+
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function cleanValue(value) {
+  if (typeof value !== 'string') return '';
+  return value.trim().replace(/^([`'\"])(.*)\1$/, '$2').trim();
+}
+
+function isPlaceholder(value) {
+  const cleaned = cleanValue(value);
+  if (!cleaned) return true;
+  if (cleaned.startsWith('<') && cleaned.endsWith('>')) return true;
+  return PLACEHOLDER_VALUES.has(cleaned.replace(/[.,;:]+$/, '').trim().toLowerCase());
+}
+
+function extractValue(promptText, label) {
+  const labelPattern = escapeRegExp(label).replaceAll('\\ ', '\\s+');
+  const flag = `--${label.replaceAll(/\s+/g, '-')}`;
+  const direct = new RegExp(
+    `(?:^|\\r?\\n)\\s*(?:[-*]\\s*)?(?:[*_` + '`' + `]?${labelPattern}[*_` + '`' + `]?)\\s*(?::|=|—|-)\\s*([^\\r\\n]*)`,
+    'im',
+  );
+  const directMatch = promptText.match(direct);
+  if (directMatch) return cleanValue(directMatch[1]);
+
+  const flagPattern = new RegExp(
+    `${escapeRegExp(flag)}(?:=|\\s+)(?:"([^"]*)"|'([^']*)'|([^\\s\\r\\n]+))`,
+    'i',
+  );
+  const flagMatch = promptText.match(flagPattern);
+  if (!flagMatch) return null;
+  return cleanValue(flagMatch[1] ?? flagMatch[2] ?? flagMatch[3]);
+}
+
+/** Returns the immutable input entries for one dispatcher type. */
+export function requiredInputsFor(agentType) {
+  return REQUIRED_INPUTS[agentType] || [];
+}
+
+/** Returns required entries whose value is absent or is still an obvious template placeholder. */
+export function missingInputs(agentType, promptText) {
+  const prompt = typeof promptText === 'string' ? promptText : '';
+  return requiredInputsFor(agentType).filter((entry) => isPlaceholder(extractValue(prompt, entry.label)));
+}
+
+/** Renders the compact contract the orchestrator sees while choosing a dispatcher. */
+export function renderRequiredInputSummary(agentType) {
+  const entries = requiredInputsFor(agentType);
+  if (!entries.length) return '';
+  const labels = entries.map((entry) => `\`${entry.label}\``);
+  return `Requires ${entries[0].source}-provided ${labels.join(' and ')}.`;
+}
+
+/** Renders the same contract for pass 2 agent instructions. */
+export function renderRequiredInputs(agentType) {
+  return requiredInputsFor(agentType)
+    .map((entry) => `- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`)
+    .join('\n');
+}

package/src/runner/args.mjs

@@ -8,12 +8,17 @@
 import path from 'node:path';
 import { AGENTS } from '../write-meta.mjs';
 import { ALLOWED_EFFORTS } from '../run-config.mjs';
+import { requiredInputsFor } from '../required-inputs.mjs';
 
 export function die(message) {
   console.error(`run-codex: ${message}`);
   process.exit(2);
 }
 
+function requiredInput(agentType, label) {
+  return requiredInputsFor(agentType).find((entry) => entry.label === label);
+}
+
 // Flags that carry no value. A value is accepted only in its explicit yes/no spellings;
 // anything else stops the run. The permissive reading this replaces — "not 0/false/no means
 // yes" — turned the prompt's own placeholder text (`--continue "<only if the orchestrator provided
@@ -63,10 +68,12 @@ export function parseArgs(argv) {
   if (!AGENTS[opts.agent]) die(`unknown --agent ${opts.agent}`);
   opts.orderId = String(opts['order-id'] ?? '').trim();
   if (!opts.orderId) {
+    const orderInput = requiredInput(opts.agent, 'order id');
     die(
-      '--order-id is required: the orchestrator issues the order label and the runner will not invent one. ' +
+      `--order-id is required: ${orderInput.source} supplies the ${orderInput.label}; the runner will not invent one. ` +
         'A repeat of the same order should come back with --continue. If this appeared right after a package update, ' +
-        'the installed dispatcher prompts are stale and need npm run dev:install (local dev) or codex-bridge update.',
+        'the installed dispatcher prompts are stale and need npm run dev:install (local dev) or codex-bridge update. ' +
+        `Example: --order-id "${orderInput.example}". Action: get the value from ${orderInput.source}, pass it as --order-id, and retry.`,
     );
   }
   if (opts.agent === 'codex-scout') {
@@ -101,10 +108,11 @@ export function parseArgs(argv) {
     .map((p) => p.trim())
     .filter(Boolean);
   if (opts.agent === 'codex-build' && !opts.scopePatterns.length) {
+    const scopeInput = requiredInput(opts.agent, 'scope');
     die(
-      '--scope is required for codex-build: comma-separated globs relative to the repo root, ' +
-        'e.g. --scope "packages/event-calendar/**,apps/orchestrator/src/maestro/calendar-refresh.ts". ' +
-        'Anything outside the list is off limits and fails the run.',
+      `--scope is required for codex-build: ${scopeInput.source} supplies the ${scopeInput.label}. ` +
+        `${scopeInput.explanation} Example: --scope "${scopeInput.example}". ` +
+        `Action: get the value from ${scopeInput.source}, pass it as --scope, and retry.`,
     );
   }
   return opts;

package/src/runner/prompts.mjs

@@ -52,6 +52,15 @@ Working rules:
   cannot be done, do not pretend it is done; list it in leftovers.
 - After making changes, run verification: ${opts.verify || 'determine the command from the project'}.
   Put the command actually run in verify_command and whether it passed in verify_passed.
+- Declare the outcome in outcome: "done" if the work the task asked for was carried out,
+  "fail" if it was not — for any reason at all, including an impossible order, a file that
+  does not exist, a scope that forbids the only fix, or running out of time. "done" with an
+  empty changes[] is correct only when the task asked you to check something and nothing
+  needed changing; if you could not do what was asked, "fail" is the answer even when the
+  worktree is clean and verification is green. This is not a self-grade: work that was done
+  and merely leaves follow-ups is "done" with the follow-ups in leftovers, and partial work
+  that satisfies the definition of done is "done" too. On "fail" the first sentence of summary
+  states the reason — it is what the orchestrator is shown.
 - summary and changes describe only changes in this repository for this task. Do not include
   anything unrelated in them.
 - Each change is a separate changes[] entry, exactly one file per entry. The file field contains

package/src/runner/schemas.mjs

@@ -51,8 +51,30 @@ 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'],
+  required: [
+    'outcome',
+    'summary',
+    'changes',
+    'verify_command',
+    'verify_passed',
+    'leftovers',
+    'report_markdown',
+  ],
   properties: {
+    // The outcome is declared, never inferred. On 2026-08-04 a build asked to fix a function
+    // in a module that does not exist answered `OK — no code change was made`: every artifact
+    // was well-formed, the tree was legitimately clean, and the runner has no way to know
+    // whether the order required an edit. A string rather than a boolean because the set of
+    // outcomes will grow (`blocked` is a candidate) and an enum extends without breaking the
+    // contract. Presence of this field in the run's own schema.json is also the marker that
+    // says the run was contracted to declare an outcome — see meta/outcome.mjs.
+    outcome: {
+      type: 'string',
+      enum: ['done', 'fail'],
+      description:
+        'done — the work the task asked for was carried out. fail — it was not, for any ' +
+        'reason at all (impossible order, missing file, blocked by scope, out of time).',
+    },
     summary: { type: 'string', minLength: 1 },
     changes: {
       type: 'array',