model-orchestrator 0.1.27 → 0.1.29

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [0.1.29] - 2026-09-21
+
+### Changed
+
+- **The seven principles state what to do, rather than what fails.** "A gate you cannot fail is not a gate" became "Every gate can come back wrong. A checkpoint earns its place by being answerable both ways"; "Exit 0 is not a deliverable" became "Check for the artifact. A deliverable is a file, a commit or a line you can point at"; "A write nobody can find again did not happen" became "A write stays findable". Same rules, same gates, stated forward. This finishes the copy pass 0.1.28 started, which left the principle list untouched.
+
+
+## [0.1.28] - 2026-09-21
+
+### Added
+
+- **A recording of the command doing its job, at the top of the README.** `docs/demo.gif` (60 KB) shows `npx model-orchestrator ... --dry` typed and run: the level, the AIs, both target folders, all 38 files it would write, and the closing line that nothing was written. `scripts/record-demo.sh` re-records it from the PUBLISHED package inside a temp folder, so the frames stay the program's own output rather than a staged screen, and anyone can reproduce them with `brew install asciinema agg`. The text plan stays in the README under the image, and the image carries alt text describing what it prints, so the page still reads with images off.
+- **`--summary` now answers the question the package exists for: how much work left the main session.** `work sent off the main session` counts covered turns whose route marker named any lane that is not an inline name, over covered turns. It is derived only from lane names the log already holds, with no price table and no token estimate, because the log holds neither. `--inline a,b` renames what counts as inline, since the lane vocabulary belongs to your own `ROUTING.md`. A log with no lane markers yet says so instead of printing a number.
+
+### Changed
+
+- **Every line of user-facing copy states what the package is and does.** The opening bullet was "What it is not: a proxy, a gateway or an API router", which told a new reader what to stop expecting before they knew what they were looking at. It now reads "Where it sits: above the request layer. Your agent reads the rules and picks the lane", and request-level routers are described as composing underneath rather than as the thing this is not. Same for the plugin section, the companion-tool intro and the gateway question in Common Questions. `test/copy.test.js` keeps the boundary it was written to protect: the OVERCLAIM guard is unchanged, and two positive phrases are now required in both README and `llms.txt`, so the claim cannot quietly widen and the copy cannot quietly lose it.
+
+
 ## [0.1.27] - 2026-09-21
 
 ### Changed
@@ -381,7 +400,9 @@ First release.
 - Tests: a case per fix, judges proven to go red, mutation checks; `npm test` prints the current count.
 - Adversarial audit: two Codex rounds plus a two-engine review (Codex, Antigravity); findings and fixes in `docs/audit-brief.md`. After the review: subagents go to the project root (`--project`), snippet paths computed from `--dir`, lane sections rendered from the selection, a primary agent required, level 3 asks for API keys separately from CLIs, images and CLI installs pinned, an activation summary at the end of every install.
 
-[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.27...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.29...HEAD
+[0.1.29]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.28...v0.1.29
+[0.1.28]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.27...v0.1.28
 [0.1.27]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.26...v0.1.27
 [0.1.26]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.25...v0.1.26
 [0.1.25]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.24...v0.1.25

package/README.md

@@ -8,7 +8,9 @@
 npx model-orchestrator
 ```
 
-Three questions, then 38 files. Here is a real `--dry` run, which prints the plan and writes nothing:
+<img src="docs/demo.gif" alt="A terminal running npx model-orchestrator with --dry: it prints the level, the AIs detected, both target folders and all 38 files it would write, then says nothing was written." width="100%" />
+
+Three questions, then 38 files. The same plan as text:
 
 ```text
 Plan
@@ -31,18 +33,20 @@ Plan
 --dry: nothing written.
 ```
 
-Reproduce it:
+Run it yourself, in any folder:
 
 ```bash
 npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code --dir ./ai-orchestrator --project . --dry
 ```
 
+The recording above comes from the published package under `asciinema`, rendered with `agg`: `bash scripts/record-demo.sh`.
+
 - **What it is:** routing rules, subagent definitions and a CLI lane runner (`cli-run`) for the AI tools you already pay for.
-- **What it is not:** a proxy, a gateway or an API router. It does not automatically compare prices or select models; your agent follows the rules and chooses.
+- **Where it sits:** above the request layer. Your agent reads the rules and picks the lane, so the decision stays somewhere you can read, version and edit. Request-level routers and gateways sit underneath it.
 - **Use it when:** you run more than one model or agent and want the expensive tier kept for planning and judgment.
 - **For agents:** [`llms.txt`](llms.txt) summarizes the package and links every doc; [`AGENTS.md`](AGENTS.md) has the headless commands.
 
-Built from a working system, not a diagram: the routing rules, the protocols and the lane runner here run in production, generalized so they transfer to any stack.
+Built from a working system: the routing rules, the protocols and the lane runner here run in production every day, generalized so they transfer to any stack.
 
 ## The three levels
 
@@ -78,7 +82,7 @@ node .claude/hooks/route-metrics.mjs --summary                        # since th
 node .claude/hooks/route-metrics.mjs --summary --since 2026-09-01     # since a date
 ```
 
-The report prints turns, **route-marker coverage** (the share of turns that carried a real lane, which answers "is the agent actually tagging its routing decisions?"), lanes by count, dispatches by `subagent_type`, dispatches with no matching start, and mean/max duration per agent type. It never logs prompt text, tool descriptions, or the "why" half of the marker. Fail-open by design: a miss is a missing log line, never a blocked turn.
+The report prints turns, **route-marker coverage** (the share of turns that carried a real lane, which answers "is the agent actually tagging its routing decisions?"), **work sent off the main session**, lanes by count, dispatches by `subagent_type`, and mean/max duration per agent type. The log holds exactly five things: a timestamp, the event, the session id, the lane name and the agent type. Every turn keeps running whatever the hook does, so the worst case is a quieter report.
 
 ## Claude Code plugin
 
@@ -89,11 +93,11 @@ The hooks and subagents also ship as a plugin, so they install and update throug
 /plugin install model-orchestrator@model-orchestrator
 ```
 
-It ships the three hooks and the eight subagents, each with an explicit tool list, and loads them namespaced as `model-orchestrator:builder`. It does not ship the routing rules, because a plugin runs no install step: `npx model-orchestrator` still writes those. `plugin/` is generated from `templates/` and `test/plugin.test.js` fails when the committed bundle drifts, when a hook gains a network call, a write or a subprocess, or when an agent loses its tool list. Details: [plugin/README.md](plugin/README.md).
+It ships the three hooks and the eight subagents, each with an explicit tool list, and loads them namespaced as `model-orchestrator:builder`. The routing rules come from `npx model-orchestrator`, which is the step that reads your setup and writes rules to match it. `plugin/` is generated from `templates/`, and `test/plugin.test.js` holds the bundle to that shape: committed output matches the generator, hooks stay read-only, every agent keeps its tool list. Details: [plugin/README.md](plugin/README.md).
 
 ## Companion tools (all optional)
 
-An orchestrator routes work. It does not make a model stop guessing numbers, give it a memory, or make it check a library's current docs before writing against it. Three tools close those gaps:
+An orchestrator routes work. Three companion tools cover the rest of what a working agent needs, exact numbers, a memory, and current library docs:
 
 | Tool | Closes | Default |
 |---|---|---|
@@ -101,17 +105,17 @@ An orchestrator routes work. It does not make a model stop guessing numbers, giv
 | [obsidian-tc](https://github.com/The-40-Thieves/obsidian-tc) | no durable memory: hybrid search, backlinks, compare-and-swap writes; local by default | no |
 | [Context7](https://github.com/upstash/context7) | stale library recall: current, version-specific docs pulled into the prompt | no |
 
-Selecting one writes a doc and config snippets; it installs nothing. What each needs first, and why Context7 pairs with codecalc rather than duplicating it: [docs/companions.md](docs/companions.md). Whether or not you select them, every level carries the three rules they serve: `protocols/numbers-and-logic.md`, `protocols/memory-and-record.md` and `protocols/docs-then-prove.md`.
+Selecting one writes a doc and the config snippets for your agents, so the install stays yours to run. What each needs first, and how Context7 and codecalc pair up (docs say what an API should do, a run proves what it does): [docs/companions.md](docs/companions.md). Every level carries the three rules they serve either way: `protocols/numbers-and-logic.md`, `protocols/memory-and-record.md` and `protocols/docs-then-prove.md`.
 
 ## Principles the whole thing rests on
 
-1. **Route by capability tier, not model name.** Default down, escalate on evidence.
-2. **A gate you cannot fail is not a gate.** Every checkpoint is a question that can come back wrong.
-3. **Exit 0 is not a deliverable.** Check for the artifact, not the status line. `cli-run` checks the response is structurally there; `--expect-file` checks the artifact.
-4. **Numbers are computed, never guessed.** A tool that calculates beats a model that feels finished.
-5. **A write nobody can find again did not happen.** Search first, keep the index true, one writer.
-6. **A delegate's brief carries this task's scope, whatever it already holds.** A Claude Code subagent loads the project's CLAUDE.md hierarchy at start, so it already has the standing rules; a second CLI or a fresh chat window may hold none of them. Either way, only the brief carries what this task needs. On claude-code, that changes who executes: see "Who builds" in `ROUTING.md`.
-7. **Only one process holds keys.** Names in the environment, values in a secrets manager, never in a file here.
+1. **Route by capability tier.** Start at the smallest tier that fits, and let evidence move it up.
+2. **Every gate can come back wrong.** A checkpoint earns its place by being answerable both ways.
+3. **Check for the artifact.** A deliverable is a file, a commit or a line you can point at. `cli-run` checks the response is structurally there; `--expect-file` checks the artifact.
+4. **Numbers are computed.** A tool that calculates beats a model that feels finished.
+5. **A write stays findable.** Search first, keep the index true, one writer.
+6. **A delegate's brief carries this task's scope, whatever it already holds.** A Claude Code subagent loads the project's CLAUDE.md hierarchy at start, so it already has the standing rules; a second CLI or a fresh chat window may hold none of them. Either way, the brief is what carries this task. On claude-code, that changes who executes: see "Who builds" in `ROUTING.md`.
+7. **Only one process holds keys.** Names in the environment, values in a secrets manager.
 
 ## Common questions
 
@@ -121,15 +125,15 @@ Install for the tools you have, then let the generated `ROUTING.md` decide the t
 
 ### How do I route tasks to cheaper models?
 
-The rules route by role, complexity and stakes (see [Routing by role, complexity and stakes](#routing-by-role-complexity-and-stakes)). Role picks the agent, complexity moves the effort, stakes move the tier. A task a cheap tier finishes correctly never gets a frontier token.
+The rules route by role, complexity and stakes (see [Routing by role, complexity and stakes](#routing-by-role-complexity-and-stakes)). Role picks the agent, complexity moves the effort, stakes move the tier. A task a cheap tier finishes correctly stays on the cheap tier, and the frontier tokens go to the work that earns them.
 
-### Is this an LLM router or an AI gateway?
+### Where does this sit next to an LLM router or an AI gateway?
 
-No. It routes at the task level, through instructions your agent follows and a runner for agent CLIs. If you want a service or proxy that picks or forwards the model on every API request, look at request-level routers and gateways such as RouteLLM, LiteLLM, OpenRouter or claude-code-router. They solve a different problem and can sit underneath this.
+One layer up, and they compose. This routes at the task level, through instructions your agent follows and a runner for agent CLIs. Request-level routers and gateways (RouteLLM, LiteLLM, OpenRouter, claude-code-router) forward the model on every API call, and they sit underneath this happily: pick the lane here, let the gateway carry the call.
 
 ### Can an agent install and run it without a person?
 
-Yes. `--yes` with `--level`, `--ais` and `--project` runs headless, `--dry-run` previews the plan, and `--list` prints every supported AI. Nothing is appended to a file you already have; activation snippets are written next to your files for you to merge.
+Yes. `--yes` with `--level`, `--ais` and `--project` runs headless, `--dry-run` previews the plan, and `--list` prints every supported AI. Your existing files stay as they are: activation snippets land beside them, ready to merge when you choose.
 
 
 ## Read next

package/llms.txt

@@ -1,6 +1,6 @@
 # model-orchestrator
 
-> Model orchestrator for AI coding agents and LLMs (Claude Code, Codex, Gemini, Grok, Qwen, Ollama). One installer writes routing rules, subagent definitions and a CLI lane runner for the AI tools you already have. The rules tell your agent which model, subagent or CLI to use for each task, so small work goes to cheap tiers and fewer tokens go to frontier models. It is not a proxy or gateway: it does not automatically compare prices or select models; your agent follows the rules and chooses.
+> Model orchestrator for AI coding agents and LLMs (Claude Code, Codex, Gemini, Grok, Qwen, Ollama). One installer writes routing rules, subagent definitions and a CLI lane runner for the AI tools you already have. The rules tell your agent which model, subagent or CLI to use for each task, so small work goes to cheap tiers and fewer tokens go to frontier models. It sits above the request layer: your agent reads the rules and picks the lane, so the decision stays readable, versioned and editable. Request-level routers and gateways compose underneath it.
 
 Install and run: `npx model-orchestrator` (interactive), or headless: `npx model-orchestrator --yes --level 2 --ais claude-code,codex --project . --dir ./ai-orchestrator`. Preview without writing: add `--dry-run`. List every supported AI: `npx model-orchestrator --list`. Node 18 or newer, zero runtime dependencies, MIT licence.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Model orchestrator for AI coding agents and LLMs: Claude Code, Codex, Gemini, Grok, Qwen, Ollama. Routing rules tell your agent which model, subagent or CLI to use for each task, so small work goes to cheap tiers and fewer tokens go to frontier models. One installer, plus a CLI runner that logs every route.",
   "type": "module",
   "bin": {

package/scripts/README.md

@@ -3,4 +3,5 @@
 | File | Job |
 |---|---|
 | `gen-catalog.js` | regenerates `docs/catalog.md` AND the vendor compatibility table in `README.md` (between the `vendor-table` markers) from `src/catalog.js`; `npm run gen:catalog`. `test/catalog.test.js` fails if either generated surface disagrees with the catalog. |
+| `record-demo.sh` | re-records `docs/demo.gif` by installing the published package into a temp folder and running it under `asciinema`, then rendering the cast with `agg`. Pass a version to pin one: `bash scripts/record-demo.sh 0.1.27`. Needs `brew install asciinema agg`. The frames are the installer's own output, so the GIF stays true to what the command prints. |
 | `gen-plugin.js` | regenerates the Claude Code plugin bundle in `plugin/` (agents, the two read-only hooks, `plugin.json`, `LICENSE`) from `templates/`, using the plan in `src/plugin.js`; `npm run gen:plugin`. `test/plugin.test.js` fails if the committed bundle disagrees. `plugin/README.md` and `plugin/hooks/hooks.json` are hand-owned. |

package/scripts/record-demo.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Re-records docs/demo.gif from the PUBLISHED package, so the frames are the
+# program's own output and anyone can reproduce them.
+#
+#   bash scripts/record-demo.sh            # records the current published version
+#   bash scripts/record-demo.sh 0.1.27     # pins a version
+#
+# Needs asciinema (the recorder) and agg (cast to GIF), both from the asciinema
+# project: brew install asciinema agg
+set -euo pipefail
+
+VERSION="${1:-latest}"
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT="$REPO_ROOT/docs/demo.gif"
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+for tool in asciinema agg npm; do
+  command -v "$tool" >/dev/null || { echo "missing: $tool (brew install asciinema agg)" >&2; exit 1; }
+done
+
+# Installed locally first, so the recorded npx call resolves from node_modules
+# and never stops on npx's own "Ok to proceed?" prompt mid-take.
+cd "$WORK"
+npm install --silent "model-orchestrator@$VERSION" >/dev/null
+
+cat > "$WORK/take.sh" <<'TAKE'
+#!/bin/bash
+cd "$(dirname "$0")"
+printf '~/my-app $ '
+sleep 0.8
+cmd='npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code --dry'
+for (( i=0; i<${#cmd}; i++ )); do printf '%s' "${cmd:$i:1}"; sleep 0.022; done
+sleep 0.6; printf '\n'
+npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code --dry
+printf '~/my-app $ '
+sleep 2.5
+TAKE
+chmod +x "$WORK/take.sh"
+
+asciinema rec --cols 108 --rows 34 --overwrite --command "$WORK/take.sh" "$WORK/demo.cast"
+agg --theme monokai --font-size 16 --speed 1.3 --idle-time-limit 1.2 --last-frame-duration 3 \
+  "$WORK/demo.cast" "$OUT"
+
+echo "wrote $OUT ($(wc -c < "$OUT") bytes)"

package/templates/agents/snippets/route-metrics.mjs

@@ -273,6 +273,10 @@ async function runHook() {
   process.exit(0); // fail-open, always: a miss here is a missing log line, never a blocked turn
 }
 
+// Lane names that mean "the main session did it itself". Defaults only: the lane
+// vocabulary belongs to the user's own ROUTING.md, and --inline overrides this.
+const INLINE_LANE_NAMES = ['inline', 'main', 'main inline'];
+
 // ---- --summary: a plain-text report, no stdin involved ----
 
 function parseLines(text) {
@@ -313,6 +317,22 @@ function runSummary(args) {
     for (const lane of Array.isArray(r.lane) ? r.lane : []) laneCounts.set(lane, (laneCounts.get(lane) || 0) + 1);
   }
 
+  // The one number that answers "did the routing actually move work off the main
+  // session?". Derived only from lane names the marker already carries: no price
+  // table, no token count, nothing this log does not hold. A covered turn counts as
+  // sent off when its marker names any lane that is not one of the inline names.
+  // The inline names are overridable because the lane vocabulary is the user's own
+  // ROUTING.md, not a list this package gets to fix.
+  const inlineIdx = args.indexOf('--inline');
+  const inlineNames = new Set(
+    (inlineIdx !== -1 && args[inlineIdx + 1] ? args[inlineIdx + 1].split(',') : INLINE_LANE_NAMES)
+      .map((n) => n.trim().toLowerCase())
+      .filter(Boolean)
+  );
+  const coveredRoutes = routes.filter((r) => Array.isArray(r.lane) && r.lane.some((l) => l !== 'missing'));
+  const sentOff = coveredRoutes.filter((r) => r.lane.some((l) => l !== 'missing' && !inlineNames.has(String(l).trim().toLowerCase()))).length;
+  const sentOffPct = coveredRoutes.length > 0 ? (sentOff / coveredRoutes.length) * 100 : null;
+
   const dispatches = records.filter((r) => r.event === 'dispatch');
   const dispatchCounts = new Map();
   for (const r of dispatches) dispatchCounts.set(r.subagent_type, (dispatchCounts.get(r.subagent_type) || 0) + 1);
@@ -331,6 +351,12 @@ function runSummary(args) {
   lines.push('route-metrics summary' + (Number.isNaN(since) ? '' : ' since ' + args[sinceIdx + 1]));
   lines.push('turns: ' + turns);
   lines.push('route-marker coverage: ' + (coveragePct === null ? 'no turns yet' : formatNumber(coveragePct) + '%') + ' (' + covered + '/' + turns + ')');
+  lines.push(
+    'work sent off the main session: ' +
+      (sentOffPct === null ? 'no covered turns yet' : formatNumber(sentOffPct) + '%') +
+      ' (' + sentOff + '/' + coveredRoutes.length + ' covered turns)'
+  );
+  lines.push('  inline names for this report: ' + [...inlineNames].join(', ') + ' (override with --inline a,b)');
   lines.push('lanes by count:');
   if (laneCounts.size === 0) lines.push('  (none)');
   for (const [lane, count] of [...laneCounts.entries()].sort((a, b) => b[1] - a[1])) lines.push('  ' + lane + ': ' + count);