model-orchestrator 0.1.34 → 1.0.0

package/bin/README.md

@@ -1,10 +1,61 @@
-# bin/
+# Commands and lane runner
 
-Two executables. Both are plain Node, no dependencies.
+Plain Node executables with zero runtime dependencies.
 
-| File | What it is | Who runs it |
+| File | Command | What it gives you |
 |---|---|---|
-| `cli.js` | The installer. `npx model-orchestrator` lands here. Asks level + access, writes files, offers npm installs one at a time. | You, once per machine or project |
-| `cli-run.mjs` | The lane runner. Copied into your install at level 2 and above as `bin/cli-run.mjs`. Runs one agent CLI and exits non-zero unless it produced a deliverable. | Your orchestrator, every time it delegates to another CLI |
+| `cli.js` | `npx model-orchestrator` | Select a setup and write routing files; print third-party setup commands for you to run |
+| `aunx.js` | `aunx` | Run the installer, dispatch the lane runner, scaffold briefs and checks, summarize metrics or suggest a route |
+| `cli-run.mjs` | `aunx cli-run` | Call an agent CLI and return nonzero when it produces no accepted result |
 
-`cli-run.mjs` exports its judges (`judgeGrok`, `judgeCodex`, `judgeAgy`, `judgeHermes`, `judgeQwen`) so `test/` can prove each one goes red on the failure shapes it exists to catch, without spawning any CLI.
+## Lane runner (`aunx cli-run`)
+
+```bash
+aunx cli-run --doctor
+aunx cli-run codex --brief TASK_BRIEF.md --effort high
+# Direct equivalents from the installed rules folder:
+node bin/cli-run.mjs --doctor
+node bin/cli-run.mjs codex --brief TASK_BRIEF.md --effort high
+```
+
+`aunx` uses the packaged runner by default. Pass `--dir PATH` to use that project's own installed runner under `PATH/bin/`; `aunx` then prints the runner path it is using on stderr. When `--dir` names a folder with no runner, the packaged copy runs instead. Arguments and exit status pass through. `--doctor --run` performs live checks using your own vendor sign-ins and quota.
+
+| Exit | Meaning |
+|---|---|
+| 0 | Accepted result |
+| 2 | Invalid usage |
+| 10 | Empty result or unmet output contract |
+| 11 | No output |
+| 12 | Timeout |
+| 13 | Unavailable tool |
+| 14 | Authentication failure |
+| 15 | Quota exhausted |
+| 16 | Request rejected |
+| 17 | Required tool action refused |
+| 18 | Run cut short |
+| 130 / 143 | Interrupted by a signal on POSIX |
+
+The local log records requested model and effort, their source, fixed result classes and the vendor exit code. Its existing schema is preserved. It stores no prompt text or provider-supplied failure text.
+
+`cli-run.mjs` exports its output judges so `test/judges.test.js` can prove each rejects the failure shapes it exists to catch. Tests use fixture output and stub CLIs.
+
+## Acceptance-check runner (`aunx checks run`)
+
+Scaffold with `aunx checks ACCEPTANCE_CHECKS.json`, then fill each command and its expected property. `aunx checks run ACCEPTANCE_CHECKS.json` executes the commands and reports PASS or FAIL. Any failure exits 1. These are shell commands with your permissions: run only a reviewed check file. Gate a later action by running it only after exit 0.
+
+## Briefs, context and metrics
+
+`aunx brief` prints the template; `aunx brief new TASK_BRIEF.md` writes a new file. `aunx context CONTEXT.md` scaffolds shared facts. `aunx route-metrics --summary` reports local routing activity. `aunx route "design the auth system"` prints an explained keyword-based suggestion and launches no worker.
+
+## Operation and verification
+
+- **What and why:** one command exposes the installer and the tools an agent uses to prepare, route and verify work.
+- **Trigger:** a user or agent invokes a command explicitly. The wrapper registers no background service.
+- **Invocation chain:** npm bin link -> `bin/aunx.js` -> `src/aunx.js` -> the selected Node entry point or local scaffold/check handler.
+- **Dependencies:** Node as declared in `package.json`; a vendor CLI and its sign-in only when calling that vendor. Scaffolds and route suggestions work without companions.
+- **Reads:** package templates, an explicitly selected check file, the project's installed runner, and the existing metrics log for summaries.
+- **Writes:** scaffold files use exclusive creation. Check commands can write whatever their reviewed code requests. The delegated runner and metrics hook retain their documented local logs.
+- **Closed loop:** callers inspect the exit code and the check report. Nothing watches the wrapper as a service; the repository test workflow watches committed changes. Gate a later action on exit 0 when using acceptance checks.
+- **Failure modes:** invalid arguments or check format return 2, failed checks return 1, and dispatched Node commands retain their exit codes. An existing scaffold path is preserved. Without `--dir` the packaged runner always runs; with `--dir`, a missing project runner falls back to the packaged copy.
+- **Run and verify:** `node bin/aunx.js --help`, `node bin/aunx.js route "rename this file"`, and `node --test test/aunx.test.js`. For a real vendor, use the doctor command above with your own authorization and quota.
+- **Source of truth:** `src/aunx.js`, the templates it loads, and the dispatch and exit-code tests in `test/aunx.test.js`.

package/bin/aunx.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/aunx.js';
+
+main(process.argv.slice(2)).then(code => { process.exitCode = code; }).catch(error => {
+  console.error(`aunx: ${error.message}`);
+  process.exitCode = 2;
+});

package/bin/cli-run.mjs

@@ -31,12 +31,12 @@
 //   0   ok: structurally accepted non-empty response (and every --expect-* contract met)
 //   10  empty: ran and delivered nothing, or a contract was not met
 //   11  no_output: produced no output at all
-//   12  timeout: the lane AND its descendants are killed as a process group
+//   12  timeout: the lane, and its descendants, are killed as a process group
 //   13  unavailable: missing binary, disabled in lanes.json, or lanes.json malformed
 //   14  auth: the lane's own error says a credential is missing or not logged in
 //   15  quota: the lane's own error says usage limit, credits or rate limit
 //   16  rejected: the upstream rejected the request (bad model id, bad request)
-//   17  refused: no deliverable, and the lane reports tool calls a hook or deny rule blocked
+//   17  refused: no result, and the lane reports tool calls a hook or deny rule blocked
 //   18  cut_short: no trustworthy finish: a missing or non-success terminal event, a lane
 //       killed by a signal, output past the 16 MiB buffer, or a nonzero vendor exit
 //   130 / 143  cli-run itself received SIGINT / SIGTERM: the lane's process group was killed first
@@ -60,7 +60,7 @@
 // was REQUESTED plus where the request came from (flag, lanes.json, or nothing
 // at all). It does not log an "actual". One lane of five (grok) does report a
 // model id in its own output; the other four report none, and a field present
-// for one lane and absent for four is worse than no field. It would also be a
+// for one lane, and absent for four, is worse than no field. It would also be a
 // provider-supplied string, which this log deliberately never holds.
 
 import { spawn, spawnSync } from 'node:child_process';
@@ -821,7 +821,7 @@ export function classifyRun(lane, { rc = 0, out = '', err = '', reason = '', det
 // boundary; that is documented, not hidden.
 // Models often wrap JSON in one markdown fence. --expect-json accepts exactly that shape:
 // the whole trimmed response is one fenced block, optionally tagged json. Prose before or
-// after the fence still fails, because then the deliverable is not the JSON (#17).
+// after the fence still fails, because then the result is not the JSON (#17).
 export function unfence(text) {
   const t = String(text).trim();
   const m = /^```(?:json|JSON)?[ \t]*\r?\n([\s\S]*?)\r?\n?```$/.exec(t);
@@ -920,7 +920,7 @@ export function windowsSpawnPlan(argv, platform = process.platform, { allowCmdFa
   return { command: comspec, args: ['/d', '/s', '/c', buildCmdExeCommand(bin, args)], options: { windowsVerbatimArguments: true } };
 }
 
-// Kill a lane and everything it spawned. POSIX: the detached process group.
+// Kill a lane, and everything it spawned. POSIX: the detached process group.
 // Windows has no process groups a signal can reach, so taskkill walks the
 // tree (#18): whether the direct child is node (the resolved-shim path) or
 // cmd.exe (the fallback), taskkill /T reaches every descendant either way.
@@ -1154,23 +1154,27 @@ function installedPrimary(here = dirname(fileURLToPath(import.meta.url))) {
 }
 
 // --doctor: the first thing to run after install.
-export async function doctor(run) {
-  const cfg = laneConfig();
+export async function doctor(run, { here = dirname(fileURLToPath(import.meta.url)), compact = false, config = laneConfig(here), primary = installedPrimary(here) } = {}) {
+  const cfg = config;
   if (cfg === null) {
     console.error('doctor: lanes.json exists but is malformed; fix it first');
     return USAGE;
   }
   const { enabled, defaults } = cfg;
   let bad = 0;
-  console.log(`doctor: ${enabled.length} enabled lane(s): ${enabled.join(', ') || 'none'}`);
-  const primary = installedPrimary();
-  if (primary && !enabled.includes(primary)) console.log(`  note: ${primary} is the primary agent and is not an executable lane`);
+  if (!compact) console.log(`doctor: ${enabled.length} enabled lane(s): ${enabled.join(', ') || 'none'}`);
+  if (!compact && primary && !enabled.includes(primary)) console.log(`  note: ${primary} is the main agent and is not an executable lane`);
   if (!enabled.length) {
+    if (compact) {
+      console.log('doctor: no executable lanes enabled.');
+      return UNAVAILABLE;
+    }
     console.error('doctor: inactive: no executable lanes enabled. Use level 1 for a single-agent setup, or re-run the installer with a supported CLI selected.');
     return UNAVAILABLE;
   }
   for (const lane of LANES) {
     const on = enabled.includes(lane);
+    if (compact && !on) continue;
     const bin = which(lane);
     const d = defaults[lane] || {};
     // A disabled lane has no route worth reporting; saying "not pinned" there
@@ -1183,11 +1187,13 @@ export async function doctor(run) {
       line += rc === OK ? '  canary ok' : `  canary FAILED rc=${rc}`;
       if (rc !== OK) bad++;
     }
-    console.log(line);
+    console.log(compact ? `  ${lane}: ${bin ? 'present' : 'MISSING'}` : line);
   }
   console.log(bad ? `doctor: ${bad} problem(s)` : 'doctor: all enabled lanes ' + (run ? 'answered' : 'present'));
-  console.log('doctor checks presence and, with --run, a one-word canary. It does not check vendor versions.');
-  console.log('"route not pinned" means that lane runs on whatever its own config file says, which this tool cannot see. Pin it in lanes.json "defaults" if the route matters.');
+  if (!compact) {
+    console.log('doctor checks presence and, with --run, a one-word canary. It does not check vendor versions.');
+    console.log('"route not pinned" means that lane runs on whatever its own config file says, which this tool cannot see. Pin it in lanes.json "defaults" if the route matters.');
+  }
   return bad ? NO_DELIVERABLE : OK;
 }
 
@@ -1216,7 +1222,7 @@ export function checkContracts(opts, text, before) {
     if (!after.file || after.size === 0) return `--expect-file: ${p} is empty or not a regular file`;
     if (before && before.exists) {
       const changed = !before.file || after.sha !== before.sha || after.mtimeMs > before.mtimeMs;
-      if (!changed) return `--expect-file: ${p} existed before the run and was not changed by it (same content, same mtime); a pre-existing artifact is not this run's deliverable`;
+      if (!changed) return `--expect-file: ${p} existed before the run and was not changed by it (same content, same mtime); a pre-existing artifact is not this run's result`;
     }
   }
   if (opts.expectJson) {
@@ -1346,7 +1352,7 @@ export async function main(argv) {
       verdict = 'unavailable'; reason = 'unavailable'; detail = r.error.message; cls = 'unavailable';
     } else if (r.signal || r.status === null) {
       // A lane killed by a signal has no honest exit status. Whatever it printed
-      // before dying is not a deliverable; a null status must never become exit 0.
+      // before dying is not a result; a null status must never become exit 0.
       verdict = 'killed'; reason = 'killed'; detail = `lane killed by ${r.signal || 'unknown signal'}`; cls = 'cut_short';
     } else {
       const j = safeJudge(lane, r.status, out, err, outFile);