feat(model-router): wave 3-A — first-use route confirmation, decision memory, project exceptions

routing.json (tracked, reached through the plugin directory) is now the
single source of the phase table and of every skill/agent row, plus the
decisions: confirmed rows/phases, changed rows (from/to) and projects
exceptions keyed by a normalized git remote (credentials never stored, no
machine paths). First use of a rowed typed skill, a rowed agent spawn or a
main-loop phase opens the engine's dialog (Later / Keep / two alternative
phases; Other = a phase name); a change asks Everywhere or This project
only. One dialog at a time, never in headless, never inside an agent,
never written by the model: only a dialog answer or /route ask writes,
serialized, size-capped, never creating the file. Layers: routing.json <
~/.claude/model-router.json; the project tree is never read. /route
pending, /route ask on|off. Census reads rows and phases from the file and
tolerates a user-changed row (WARN). Kit suite 86 → 190 tests.

Contract .claude/tasks/contracts/2026-10-10-model-router-w3a-confirm-1201.md,
plan r4: 3 lenses + 1 confirmation, feater + 4 rounds, GATE 0 MET,
verifier CONFORME then re-verify after security, security BLOCK(1) fixed
then PASS. Live: T2 dialogs answered by the user from the hot-loaded mod.
This commit is contained in:
bchanot committed 2026-10-11 11:48:25 +02:00
1 parent 45bb86ff1d
commit 22455c051f
5 files changed
+2298 -173

No files matched your search

+4
View File
@@ -48,6 +48,10 @@ Builtin `/effort` is NOT a lever inside a run: rows and routes outrank it.
typed marker (unverified live 2026-10-10). typed marker (unverified live 2026-10-10).
- Headless (`-p`, SDK) runs the hooks, so routing works there too. - Headless (`-p`, SDK) runs the hooks, so routing works there too.
- Mod off: typed agents fall back to their `model:`/`effort:` frontmatter. - Mod off: typed agents fall back to their `model:`/`effort:` frontmatter.
- First use of a row asks once (Keep, Later or another phase, then
Everywhere or this project only); the answer is kept in
`mods/model-router/routing.json`. `/route pending` lists what is still
unconfirmed, `/route ask off|on` toggles the dialog.
Measure the split any time: `python3 ~/.claude/lib/effort-audit.py` Measure the split any time: `python3 ~/.claude/lib/effort-audit.py`
(thinking/output/cache tokens per scope, model and effort). (thinking/output/cache tokens per scope, model and effort).
+117 -52
View File
@@ -1,12 +1,16 @@
#!/usr/bin/env bash #!/usr/bin/env bash
# lib/tests/effort-routing.test.sh — wave-2 census of the model-router rows. # lib/tests/effort-routing.test.sh — wave-2 census of the model-router rows.
# Drift lock: every tracked skill/agent row in mods/model-router/hooks/ # Drift lock: every tracked skill/agent row of mods/model-router/routing.json
# register.ts equals its frontmatter (the off-state floor), the D3 wiring # equals its frontmatter (the off-state floor), except a row the user changed
# markers sit in the orchestrators, no shifter citer survives. # through the first-use dialog (WARN floor drift: the floor may lag a
# confirmed decision); the D3 wiring markers sit in the orchestrators, no
# shifter citer survives.
# shellcheck disable=SC2015,SC2016 # A && ok || ko is deliberate (ok/ko never fail) # shellcheck disable=SC2015,SC2016 # A && ok || ko is deliberate (ok/ko never fail)
set -u set -u
R="$(cd "$(dirname "$0")/../.." && pwd)" R="$(cd "$(dirname "$0")/../.." && pwd)"
REG="$R/mods/model-router/hooks/register.ts" MOD="$R/mods/model-router"
RJ="$MOD/routing.json"
REG="$MOD/hooks/register.ts"
pass=0; fail=0 pass=0; fail=0
ok() { pass=$((pass+1)); } ok() { pass=$((pass+1)); }
ko() { fail=$((fail+1)); printf 'FAIL %s\n' "$1"; } ko() { fail=$((fail+1)); printf 'FAIL %s\n' "$1"; }
@@ -16,84 +20,145 @@ lacks() { if grep -qF "$2" "$R/$1"; then ko "$1 must NOT contain: $2"; else ok;
fm() { awk 'NR==1&&/^---$/{p=1;next} p&&/^---$/{exit} p' "$1"; } fm() { awk 'NR==1&&/^---$/{p=1;next} p&&/^---$/{exit} p' "$1"; }
fm_val() { fm "$1" | grep -E "^$2: [a-z]+$" | head -1 | cut -d' ' -f2; } fm_val() { fm "$1" | grep -E "^$2: [a-z]+$" | head -1 | cut -d' ' -f2; }
# ── register.ts parsers (awk/sed on the DEFAULT_CONFIG literal) ────────── # ── routing.json (rows, phases, decisions) and the tier heads ────────────
# rows <file> <agents|skills> -> "name phase" per row # dump <routing.json> -> "skills|agents <name> <phase>", "phases <p> <tier>
rows() { # <effort>", "changed <kind> <name> <from> <to>" lines
awk -v s="$2" '$0 ~ "^ "s": \\{"{f=1;next} f&&/^ \},?$/{f=0} f' "$1" \ dump() {
| grep -v '^ *//' | grep -oE "('[^']+'|[A-Za-z0-9_-]+): '[a-z]+'" \ python3 -I - "$1" <<'PY'
| sed -E "s/'//g; s/: / /" import json, sys
} d = json.load(open(sys.argv[1]))
# phase_effort <file> <phase> -> "<tier> <effort>" for kind in ("skills", "agents"):
phase_effort() { for k, v in d.get(kind, {}).items():
awk '/^ phases: \{/{f=1;next} f&&/^ \},?$/{f=0} f' "$1" \ print(kind, k, v)
| sed -nE "s/^ *$2: \{ tier: '([a-z]+)', effort: '([a-z]+)' \},?$/\1 \2/p" for k, v in d.get("phases", {}).items():
print("phases", k, v.get("tier", ""), v.get("effort", ""))
for kind in ("skills", "agents"):
for k, v in d.get("changed", {}).get(kind, {}).items():
print("changed", kind, k, v["from"], v["to"])
PY
} }
# lookups on a dump text: row_of D kind name · phase_effort D phase ·
# changed_of D kind name -> "from to"
row_of() { printf '%s\n' "$1" | awk -v k="$2" -v n="$3" '$1==k&&$2==n{print $3}'; }
phase_effort() { printf '%s\n' "$1" | awk -v p="$2" '$1=="phases"&&$2==p{print $3, $4}'; }
changed_of() { printf '%s\n' "$1" | awk -v k="$2" -v n="$3" '$1=="changed"&&$2==k&&$3==n{print $4, $5}'; }
# tier_head <file> <tier> -> first alias of the tier list # tier_head <file> <tier> -> first alias of the tier list
tier_head() { tier_head() {
awk '/^ tiers: \{/{f=1;next} f&&/^ \},?$/{f=0} f' "$1" \ awk '/^ tiers: \{/{f=1;next} f&&/^ \},?$/{f=0} f' "$1" \
| sed -nE "s/^ *$2: \['([a-z]+)'.*$/\1/p" | sed -nE "s/^ *$2: \['([a-z]+)'.*$/\1/p"
} }
row_of() { rows "$REG" "$1" | awk -v n="$2" '$1==n{print $2}'; } # the fallback copy of the phases inside the mod's code: "<tier> <effort>"
code_phase() {
awk '/^ phases: \{/{f=1;next} f&&/^ \},?$/{f=0} f' "$REG" \
| sed -nE "s/^ *$1: \{ tier: '([a-z]+)', effort: '([a-z]+)' \},?$/\1 \2/p"
}
# field_of <dump> <phase> <effort|model> -> that phase's frontmatter value
field_of() {
local pe tier
pe="$(phase_effort "$1" "$2")"
if [ "$3" = effort ]; then printf '%s\n' "${pe#* }"; return; fi
tier="${pe% *}"; tier_head "$REG" "$tier"
}
# verdict <dump> <kind> <name> <effort|model> <got> <phase>: ok when the
# frontmatter equals the row's phase; warn when the row was changed through
# the dialog (changed.from is the shipped phase, changed.to the row) and the
# frontmatter still holds the shipped value; fail otherwise (a Keep alone,
# an empty or unknown value, a hand edit after a change)
verdict() {
local D="$1" kind="$2" name="$3" field="$4" got="$5" phase="$6" ch from fromval
[ -n "$got" ] || { echo fail; return; }
[ "$got" = "$(field_of "$D" "$phase" "$field")" ] && { echo ok; return; }
ch="$(changed_of "$D" "$kind" "$name")"; from="${ch% *}"
[ -n "$ch" ] && [ "${ch#* }" = "$phase" ] || { echo fail; return; }
fromval="$(field_of "$D" "$from" "$field")"
[ -n "$fromval" ] && [ "$got" = "$fromval" ] && echo warn || echo fail
}
# floor_check <dump> <kind> <name> <effort|model> <got> <phase> <label>
floor_check() {
case "$(verdict "$1" "$2" "$3" "$4" "$5" "$6")" in
ok) ok;;
warn) printf 'WARN floor drift: %s %s vs row %s (%s)\n' "$7" "$5" "$6" "$4"; ok;;
*) ko "$7: $4 '$5' != row $6 ($(field_of "$1" "$6" "$4"))";;
esac
}
RD="$(dump "$RJ")"
# ── flip-test: the parsers read a fixture, reject a missing key ────────── # ── flip-test: the readers parse a fixture and reject the wrong verdicts ──
FIX="$(mktemp -d)"; trap 'rm -rf "$FIX"' EXIT FIX="$(mktemp -d)"; trap 'rm -rf "$FIX"' EXIT
cat > "$FIX/reg.ts" <<'FX' cat > "$FIX/reg.ts" <<'FX'
tiers: { tiers: {
big: ['opus', 'fable'], big: ['opus', 'fable'],
}, },
phases: {
judge: { tier: 'big', effort: 'xhigh' },
},
agents: {
// judge
Plan: 'judge', 'plan-challenger': 'judge',
},
skills: {
'ship-feature': 'plan', doc: 'apply',
},
FX FX
[ "$(rows "$FIX/reg.ts" agents | tr '\n' ,)" = "Plan judge,plan-challenger judge," ] \ cat > "$FIX/routing.json" <<'FX'
&& ok || ko "flip: agents rows misparsed" {
[ "$(rows "$FIX/reg.ts" skills | tr '\n' ,)" = "ship-feature plan,doc apply," ] \ "phases": {
&& ok || ko "flip: skills rows misparsed" "judge": { "tier": "big", "effort": "xhigh" },
[ "$(phase_effort "$FIX/reg.ts" judge)" = "big xhigh" ] && ok || ko "flip: phase" "reflect": { "tier": "best", "effort": "high" },
[ -z "$(phase_effort "$FIX/reg.ts" nothere)" ] && ok || ko "flip: ghost phase" "implement": { "tier": "work", "effort": "medium" }
},
"skills": { "feat": "implement", "doc": "reflect" },
"agents": { "Plan": "judge" },
"changed": { "skills": { "feat": { "from": "reflect", "to": "implement" } } },
"ask": true
}
FX
FD="$(dump "$FIX/routing.json")"
[ "$(row_of "$FD" agents Plan)" = judge ] && ok || ko "flip: agents row misread"
[ "$(row_of "$FD" skills feat)" = implement ] && ok || ko "flip: skills row misread"
[ -z "$(row_of "$FD" skills ghost)" ] && ok || ko "flip: ghost row"
[ "$(phase_effort "$FD" judge)" = "big xhigh" ] && ok || ko "flip: phase"
[ -z "$(phase_effort "$FD" nothere)" ] && ok || ko "flip: ghost phase"
[ "$(tier_head "$FIX/reg.ts" big)" = "opus" ] && ok || ko "flip: tier head" [ "$(tier_head "$FIX/reg.ts" big)" = "opus" ] && ok || ko "flip: tier head"
[ "$(rows "$REG" skills | wc -l)" -gt 40 ] && ok || ko "register.ts: skills rows not parsed" [ "$(changed_of "$FD" skills feat)" = "reflect implement" ] && ok || ko "flip: changed entry"
[ "$(rows "$REG" agents | wc -l)" -gt 15 ] && ok || ko "register.ts: agents rows not parsed" [ -z "$(changed_of "$FD" skills doc)" ] && ok || ko "flip: ghost changed entry"
# the drift verdicts (high = reflect's effort, medium = implement's)
[ "$(verdict "$FD" skills doc effort high reflect)" = ok ] && ok || ko "flip: equal must pass"
[ "$(verdict "$FD" skills doc effort medium reflect)" = fail ] && ok || ko "flip: a Keep-only drift must FAIL"
[ "$(verdict "$FD" skills feat effort high implement)" = warn ] && ok || ko "flip: changed.from drift must WARN"
[ "$(verdict "$FD" skills feat effort '' implement)" = fail ] && ok || ko "flip: an empty value must FAIL"
[ "$(verdict "$FD" skills feat effort banana implement)" = fail ] && ok || ko "flip: an unknown value must FAIL"
[ "$(verdict "$FD" skills feat effort low implement)" = fail ] && ok || ko "flip: a drift off the shipped value must FAIL"
[ "$(verdict "$FD" skills feat effort high reflect)" = ok ] && ok || ko "flip: row back to its shipped phase passes"
[ "$(verdict "$FD" skills feat effort high judge)" = fail ] && ok || ko "flip: a hand edit after a change must FAIL"
[ "$(echo "$RD" | grep -c '^skills ')" -gt 40 ] && ok || ko "routing.json: skills rows not read"
[ "$(echo "$RD" | grep -c '^agents ')" -gt 15 ] && ok || ko "routing.json: agents rows not read"
# ── the code's fallback phases equal routing.json's (never a stale route) ─
n_code="$(awk '/^ phases: \{/{f=1;next} f&&/^ \},?$/{f=0} f' "$REG" | grep -c "tier:")"
n_json="$(echo "$RD" | grep -c '^phases ')"
[ "$n_code" -eq "$n_json" ] && ok || ko "phases: $n_code in code vs $n_json in routing.json"
while read -r _ p tier effort; do
[ "$(code_phase "$p")" = "$tier $effort" ] && ok \
|| ko "phase $p: code '$(code_phase "$p")' != routing.json '$tier $effort'"
done < <(echo "$RD" | grep '^phases ')
# ── (b) tracked skills: row exists, frontmatter effort equals the row ──── # ── (b) tracked skills: row exists, frontmatter effort equals the row ────
NO_ROW_SKILLS=" find-docs graphify impeccable model-router " NO_ROW_SKILLS=" find-docs graphify impeccable model-router "
check_skill() { check_skill() {
local f="$1" name phase want got local f="$1" name phase
name="$(basename "$(dirname "$f")")" name="$(basename "$(dirname "$f")")"
case "$NO_ROW_SKILLS" in *" $name "*) return;; esac case "$NO_ROW_SKILLS" in *" $name "*) return;; esac
phase="$(row_of skills "$name")" phase="$(row_of "$RD" skills "$name")"
[ -n "$phase" ] || { ko "skills/$name: no row in register.ts"; return; } [ -n "$phase" ] || { ko "skills/$name: no row in routing.json"; return; }
want="$(phase_effort "$REG" "$phase" | cut -d' ' -f2)" [ -n "$(fm_val "$R/$f" effort)" ] || { ko "skills/$name: routed skill without effort:"; return; }
got="$(fm_val "$R/$f" effort)" floor_check "$RD" skills "$name" effort "$(fm_val "$R/$f" effort)" "$phase" "skills/$name"
[ -n "$got" ] || { ko "skills/$name: routed skill without effort:"; return; }
[ "$got" = "$want" ] && ok || ko "skills/$name: effort $got != row $phase ($want)"
} }
while IFS= read -r f; do check_skill "$f"; done < <( while IFS= read -r f; do check_skill "$f"; done < <(
cd "$R" && git ls-files 'skills/*/SKILL.md' 'skills-external/*/SKILL.md') cd "$R" && git ls-files 'skills/*/SKILL.md' 'skills-external/*/SKILL.md')
# ── (c) tracked agents with a row: tier head == model:, effort == effort: ─ # ── (c) tracked agents with a row: tier head == model:, effort == effort: ─
NO_ROW_AGENTS=" interviewer client-handover-writer " NO_ROW_AGENTS=" interviewer client-handover-writer "
tier_alias() { tier_head "$REG" "$(phase_effort "$REG" "$1" | cut -d' ' -f1)"; }
check_agent() { check_agent() {
local f="$1" name phase alias want got local f="$1" name phase
name="$(basename "$f" .md)" name="$(basename "$f" .md)"
case "$NO_ROW_AGENTS" in *" $name "*) return;; esac case "$NO_ROW_AGENTS" in *" $name "*) return;; esac
case "$name" in impeccable-*) return;; esac case "$name" in impeccable-*) return;; esac
phase="$(row_of agents "$name")" phase="$(row_of "$RD" agents "$name")"
[ -n "$phase" ] || { ko "agents/$name: no row in register.ts"; return; } [ -n "$phase" ] || { ko "agents/$name: no row in routing.json"; return; }
alias="$(tier_alias "$phase")"; got="$(fm_val "$R/$f" model)" floor_check "$RD" agents "$name" model "$(fm_val "$R/$f" model)" "$phase" "agents/$name"
[ "$got" = "$alias" ] && ok || ko "agents/$name: model $got != row $phase ($alias)" [ "$(field_of "$RD" "$phase" model)" = haiku ] && return
[ "$alias" = haiku ] && return floor_check "$RD" agents "$name" effort "$(fm_val "$R/$f" effort)" "$phase" "agents/$name"
want="$(phase_effort "$REG" "$phase" | cut -d' ' -f2)"
got="$(fm_val "$R/$f" effort)"
[ "$got" = "$want" ] && ok || ko "agents/$name: effort $got != row $phase ($want)"
} }
while IFS= read -r f; do check_agent "$f"; done < <( while IFS= read -r f; do check_agent "$f"; done < <(
cd "$R" && git ls-files 'agents/*.md' | grep -E '^agents/[^/]+\.md$' \ cd "$R" && git ls-files 'agents/*.md' | grep -E '^agents/[^/]+\.md$' \
File diff suppressed because it is too large. Load diff
+703 -104
View File
@@ -1,9 +1,10 @@
// model-router: routes each model request (main loop and sub-agents) to the // model-router: routes each model request (main loop and sub-agents) to the
// model and effort its phase deserves. Phases name a TIER (an ordered list of // model and effort its phase deserves. Phases name a TIER (an ordered list of
// aliases, the first available wins); a circuit breaker fed by the engine's // aliases, the first available wins); a circuit breaker fed by the engine's
// own failure events marks a model down for a while. Phases, agents, skills // own failure events marks a model down for a while. Phases, skill and agent
// and prompt rules come from DEFAULT_CONFIG, overridable by // rows come from routing.json (tracked next to this mod; the first use of a
// ~/.claude/model-router.json. // row asks the user once, see "first use" below), the rest from
// DEFAULT_CONFIG; ~/.claude/model-router.json overrides both per machine.
// One writer per concern: the Agent tool's own params are never rewritten, // One writer per concern: the Agent tool's own params are never rewritten,
// the spawn hook sets an agent's model once, turn.step sets efforts. // the spawn hook sets an agent's model once, turn.step sets efforts.
import type { EngineInterface, On, Register, TurnStepInput } from 'claude-code' import type { EngineInterface, On, Register, TurnStepInput } from 'claude-code'
@@ -77,6 +78,14 @@ type State = {
logged: Set<string> // session-once log lines logged: Set<string> // session-once log lines
turnLogged: Set<string> // turn-once log lines turnLogged: Set<string> // turn-once log lines
warned: Set<string> // hooks whose fail-open was already logged warned: Set<string> // hooks whose fail-open was already logged
mem: Memory // what routing.json says about decisions, as last read
override: Rec | undefined // the machine override's data, if it loaded
loaded: boolean // the layers were read once (else: lazily, on first use)
rebuildDue: boolean // /clear: re-read the layers at the next prompt
toggles: { switch?: boolean; verbose?: boolean } // session toggles
asking: string | null // key of the one first-use dialog in flight
asked: Set<string> // keys answered (or failed) this session
writes: Promise<unknown> // the serialized routing.json write chain
} }
type Log = (text: string) => void type Log = (text: string) => void
type StepIn = Readonly<TurnStepInput> type StepIn = Readonly<TurnStepInput>
@@ -91,6 +100,20 @@ type Picked = { phase: string; route: Route }
type Effort = StepIn['effort'] type Effort = StepIn['effort']
type EffortBy = 'floor' | 'sticky' | 'turn' | 'engine' type EffortBy = 'floor' | 'sticky' | 'turn' | 'engine'
type Decision = { effort: Effort; by: EffortBy } type Decision = { effort: Effort; by: EffortBy }
type Rec = Record<string, unknown>
type Table = Record<string, string>
type Row = 'skills' | 'agents' // a table of rows in routing.json
type Kind = Row | 'phases' // what a first-use decision is about
/** What routing.json says about decisions, as last read. */
type Memory = {
ok: boolean // the file was read: false = no dialog, no write
ask: boolean // dialogs on (the machine override wins over the file)
askLocal: boolean | undefined // the machine override's own `ask`
base: Record<Row, Table> // the file's rows, before any project layer
confirmed: Record<Kind, Table> // name -> the phase a Keep endorsed
local: Record<Row, Set<string>> // rows of projects[key] or the override
key: string | undefined // normalized repo key; undefined = no project layer
}
const LEVELS: readonly Level[] = ['low', 'medium', 'high', 'xhigh', 'max'] const LEVELS: readonly Level[] = ['low', 'medium', 'high', 'xhigh', 'max']
const MODEL_ID = /^claude-[a-z0-9.-]+$/ const MODEL_ID = /^claude-[a-z0-9.-]+$/
@@ -109,6 +132,23 @@ const USER_SWITCH: ReadonlySet<string> = new Set([
'command', 'picker', 'sdk', 'command', 'picker', 'sdk',
]) ])
const OVERRIDE = '.claude/model-router.json' const OVERRIDE = '.claude/model-router.json'
const ROUTING = 'routing.json' // next to plugin.json: the tracked source
// Key order of a written routing.json; other keys follow, untouched.
const ROUTING_ORDER: readonly string[] = [
'phases', 'skills', 'agents', 'projects', 'confirmed', 'changed', 'ask',
]
// First-use dialog: answers, and the phases offered as alternatives.
const LATER = 'Later'
const KEEP = 'Keep'
const EVERYWHERE = 'Everywhere'
const THIS_PROJECT = 'This project only'
const ALTS: Record<Kind, readonly string[]> = {
skills: ['plan', 'reflect', 'implement', 'apply'],
agents: ['judge', 'implement', 'verify', 'apply'],
phases: [],
}
const ROWS: readonly Row[] = ['skills', 'agents']
const KINDS: readonly Kind[] = ['skills', 'agents', 'phases']
const HAIKU = 'claude-haiku' const HAIKU = 'claude-haiku'
const MAX_PATTERN = 200 // chars of a prompt-rule pattern const MAX_PATTERN = 200 // chars of a prompt-rule pattern
const MAX_PROMPT_SCAN = 4096 // chars of a prompt a rule is run against const MAX_PROMPT_SCAN = 4096 // chars of a prompt a rule is run against
@@ -157,63 +197,10 @@ const DEFAULT_CONFIG: Config = {
apply: { tier: 'work', effort: 'low' }, apply: { tier: 'work', effort: 'low' },
mechanical: { tier: 'cheap', effort: 'low' }, mechanical: { tier: 'cheap', effort: 'low' },
}, },
// phase = role; one row per routed repo skill/agent (wave 2); a // Rows (skill/agent -> phase) live in routing.json, the tracked source;
// project-level agent of the same name shadows its row (see spawnRoute). // a project-level agent of the same name shadows its row (see spawnRoute).
agents: { agents: {},
// explore skills: {},
Explore: 'explore',
// judge
Plan: 'judge', 'plan-challenger': 'judge', 'plugin-advisor': 'judge',
'seo-analyzer': 'judge', 'geo-analyzer': 'judge', analyzer: 'judge',
// implement
feater: 'implement', bugfixer: 'implement', 'code-cleaner': 'implement',
scaffolder: 'implement', onboarder: 'implement',
// write
'commit-changer': 'write', 'doc-syncer': 'write',
'handover-doc-writer': 'write', refactorer: 'write',
// apply
hotfixer: 'apply', 'release-executor': 'apply', 'plugin-probe': 'apply',
'validator-analyzer': 'apply',
// verify
verifier: 'verify', 'security-auditor': 'verify',
// mechanical
'status-reporter': 'mechanical',
},
skills: {
// plan
'ship-feature': 'plan', 'init-project': 'plan', onboard: 'plan',
tour: 'plan', 'audit-delta': 'plan', analyze: 'plan',
'code-clean': 'plan', 'client-handover': 'plan', brainstorming: 'plan',
'writing-plans': 'plan', 'requesting-code-review': 'plan',
'21st-ui-review': 'plan',
// reflect
feat: 'reflect', hotfix: 'reflect', bugfix: 'reflect',
refactor: 'reflect', 'web-validate': 'reflect', harden: 'reflect',
seo: 'reflect', geo: 'reflect', 'site-motion': 'reflect',
'frontend-design': 'reflect', 'emil-design-eng': 'reflect',
'design-motion-principles': 'reflect', '21st-ui-build': 'reflect',
'scroll-world-storytelling': 'reflect',
'build-threejs-scroll-worlds': 'reflect',
'scroll-scrubbed-visual-sequence': 'reflect',
'scroll-scrubbed-word-reveal': 'reflect',
'scroll-progress-timeline': 'reflect',
'subagent-driven-development': 'reflect', 'writing-skills': 'reflect',
'deprecation-and-migration': 'reflect', '21st-ai': 'reflect',
'21st-ui-explore': 'reflect',
// implement
gitflow: 'implement', 'prune-memory': 'implement',
'pdf-translate': 'implement', 'ci-cd-and-automation': 'implement',
'observability-and-instrumentation': 'implement',
'test-driven-development': 'implement',
// apply
'commit-change': 'apply', 'release-candidate': 'apply', doc: 'apply',
capitalize: 'apply', close: 'apply', reconcile: 'apply', deploy: 'apply',
// mechanical
status: 'mechanical', profile: 'mechanical', 'plugin-check': 'mechanical',
'skills-perso': 'mechanical', 'using-git-worktrees': 'mechanical',
'21st-cli-use': 'mechanical', '21st-registry': 'mechanical',
'21st-design-sync': 'mechanical',
},
// `floor` rules set the turn's minimum effort; `default` rules set the // `floor` rules set the turn's minimum effort; `default` rules set the
// turn's route, which a route call or a skill overrides. Neither lowers. // turn's route, which a route call or a skill overrides. Neither lowers.
prompt: [ prompt: [
@@ -479,9 +466,13 @@ function mergeRows(
return rows return rows
} }
/** Defaults overlaid with the user's entries, each validated first. */ /** `seed` (the defaults) overlaid with the user's entries, each validated. */
function mergeConfig(user: unknown, log: Log): Config { function mergeConfig(
const base = structuredClone(DEFAULT_CONFIG) user: unknown,
log: Log,
seed: Config = DEFAULT_CONFIG,
): Config {
const base = structuredClone(seed)
if (!isRecord(user)) { if (!isRecord(user)) {
if (user !== undefined) log('model-router: config ignored: not an object') if (user !== undefined) log('model-router: config ignored: not an object')
return base return base
@@ -512,10 +503,10 @@ function mergeConfig(user: unknown, log: Log): Config {
async function readCapped( async function readCapped(
$: Api, $: Api,
path: string, path: string,
label: string,
log: Log, log: Log,
): Promise<string | undefined> { ): Promise<string | undefined> {
const tooBig = const tooBig = `model-router: ${label} over ${MAX_CONFIG_BYTES} bytes`
`model-router: ${OVERRIDE} over ${MAX_CONFIG_BYTES} bytes`
if ((await $.fs.stat(path)).size > MAX_CONFIG_BYTES) { if ((await $.fs.stat(path)).size > MAX_CONFIG_BYTES) {
log(tooBig) log(tooBig)
return undefined return undefined
@@ -526,38 +517,240 @@ async function readCapped(
return undefined return undefined
} }
type Override = { path: string; data: unknown } | 'absent' | 'failed' type Layer = { path: string; data: Rec } | 'absent' | 'failed'
/** 'absent': no file (defaults apply). 'failed': present but unusable. */ /** 'absent': no file (defaults apply). 'failed': present but unusable. */
async function readOverride($: Api, log: Log): Promise<Override> { async function readLayer(
$: Api,
path: string,
label: string,
log: Log,
): Promise<Layer> {
try { try {
const home = await $.env.get('HOME')
if (!home) return 'absent'
const path = `${home}/${OVERRIDE}`
if (!(await $.fs.exists(path))) return 'absent' if (!(await $.fs.exists(path))) return 'absent'
const text = await readCapped($, path, log) const text = await readCapped($, path, label, log)
if (text === undefined) return 'failed' if (text === undefined) return 'failed'
const data: unknown = JSON.parse(text) const data: unknown = JSON.parse(text)
if (isRecord(data)) return { path, data } if (isRecord(data)) return { path, data }
log(`model-router: ${OVERRIDE} is not an object`) log(`model-router: ${label} is not an object`)
return 'failed' return 'failed'
} catch (err) {
log(`model-router: ${label} unreadable (${String(err)})`)
return 'failed'
}
}
const readRouting = ($: Api, log: Log): Promise<Layer> =>
readLayer($, `${$.plugin.root}/${ROUTING}`, ROUTING, log)
async function readOverride($: Api, log: Log): Promise<Layer> {
try {
const home = await $.env.get('HOME')
if (!home) return 'absent'
return await readLayer($, `${home}/${OVERRIDE}`, OVERRIDE, log)
} catch (err) { } catch (err) {
log(`model-router: ${OVERRIDE} unreadable (${String(err)})`) log(`model-router: ${OVERRIDE} unreadable (${String(err)})`)
return 'failed' return 'failed'
} }
} }
/** Never throws; undefined when the override exists but cannot be used. */ // ---- routing.json: decision memory and project exceptions --------------
async function loadConfig(
$: Api, const strTable = (v: unknown): Table =>
log: Log, isRecord(v)
): Promise<{ cfg: Config; source: string } | undefined> { ? Object.fromEntries(Object.entries(v).filter(
const found = await readOverride($, log) (entry): entry is [string, string] => typeof entry[1] === 'string'))
if (found === 'failed') return undefined : {}
if (found === 'absent') {
return { cfg: mergeConfig(undefined, log), source: 'defaults' } const subRec = (v: unknown, key: string): Rec => {
const found = isRecord(v) && hasKey(v, key) ? v[key] : undefined
return isRecord(found) ? found : {}
}
/** The rows of `projects[key]`: this repo's exceptions. */
function projectRows(file: Rec, key: string | undefined): Record<Row, Table> {
const mine = key === undefined ? {} : subRec(file.projects, key)
return { skills: strTable(mine.skills), agents: strTable(mine.agents) }
}
function emptyMemory(): Memory {
return {
ok: false,
ask: true,
askLocal: undefined,
base: { skills: {}, agents: {} },
confirmed: { skills: {}, agents: {}, phases: {} },
local: { skills: new Set(), agents: new Set() },
key: undefined,
} }
return { cfg: mergeConfig(found.data, log), source: found.path } }
/** What the file and the machine override say about decisions. */
function buildMemory(
file: Rec,
key: string | undefined,
override: Rec | undefined,
): Memory {
const project = projectRows(file, key)
const flag = override?.ask
const askLocal = typeof flag === 'boolean' ? flag : undefined
const sure = subRec(file, 'confirmed')
const local = (row: Row): Set<string> => new Set([
...Object.keys(project[row]), ...Object.keys(strTable(override?.[row])),
])
return {
ok: true,
ask: askLocal ?? file.ask !== false,
askLocal,
base: { skills: strTable(file.skills), agents: strTable(file.agents) },
confirmed: {
skills: strTable(sure.skills),
agents: strTable(sure.agents),
phases: strTable(sure.phases),
},
local: { skills: local('skills'), agents: local('agents') },
key,
}
}
const SCP_REMOTE = /^[A-Za-z0-9._-]+@([A-Za-z0-9.-]+):([^:@]+)$/
const URL_REMOTE = /^[a-z][a-z0-9+.-]*:\/\//i
/** [host, path] of a remote, userinfo never read; undefined if unclear. */
function remoteParts(url: string): [string, string] | undefined {
const scp = SCP_REMOTE.exec(url)
if (scp) return [scp[1] as string, scp[2] as string]
if (!URL_REMOTE.test(url)) return undefined
// a second `@` in the authority hides a secret in the userinfo
const authority = url.replace(URL_REMOTE, '').split('/')[0] ?? ''
if (authority.split('@').length > 2) return undefined
try {
const u = new URL(url)
return [u.host, u.pathname]
} catch {
return undefined
}
}
/**
* A repo's identity across clones and machines: its origin remote reduced to
* `host/path` (scheme, userinfo, `.git` and trailing slash dropped, host
* lowercased). A remote that cannot be read with certainty, or that leaves
* an `@` or `:` in the host or an `@` in the path, gives undefined: no
* credential ever reaches the tracked file.
*/
function normalizeRemote(url: string): string | undefined {
const parts = remoteParts(url.trim())
if (parts === undefined) return undefined
const host = parts[0].toLowerCase()
const path = parts[1].replace(/^\/+/, '').replace(/\/+$/, '')
.replace(/\.git$/i, '')
if (host === '' || path === '' || path.includes('@')) return undefined
return /[@:]/.test(host.replace(/:\d+$/, '')) ? undefined : `${host}/${path}`
}
async function projectKey($: Api): Promise<string | undefined> {
try {
const repo = await $.session.repo()
return repo?.remote ? normalizeRemote(repo.remote) : undefined
} catch {
return undefined
}
}
/** routing.json's phases and rows as a user table, this repo's rows last. */
function routingTables(file: Rec, key: string | undefined): Rec {
const project = projectRows(file, key)
return {
phases: file.phases,
skills: { ...strTable(file.skills), ...project.skills },
agents: { ...strTable(file.agents), ...project.agents },
}
}
type Loaded = {
cfg: Config
source: string
mem: Memory
override: Rec | undefined
}
function sourceWord(file: Layer, over: Layer): string {
const fileWord = typeof file === 'string' ? undefined : ROUTING
const overWord = typeof over === 'string' ? undefined : over.path
if (fileWord && overWord) return `${fileWord} + ${overWord}`
return fileWord ?? overWord ?? 'defaults'
}
/** A phase routing.json lacks keeps the code default: one line names them. */
function logMissingPhases(phases: unknown, log: Log): void {
if (phases !== undefined && !isRecord(phases)) return // mergeTable says it
const missing = Object.keys(DEFAULT_CONFIG.phases)
.filter(name => !isRecord(phases) || !hasKey(phases, name))
if (missing.length === 0) return
log(`model-router: ${ROUTING} lacks phases ${missing.join(', ')}; ` +
'code defaults kept')
}
/**
* Defaults < routing.json < the machine override. The phases of both files
* merge first; every layer's rows then validate against that final table,
* so a routing.json row may name a phase only the override defines.
*/
function layerConfig(
tables: Rec | undefined,
override: Rec | undefined,
log: Log,
): Config {
const seeded = mergeConfig(tables && { phases: tables.phases }, log)
const cfg = mergeConfig(
override && { ...override, skills: undefined, agents: undefined },
log, seeded)
const ref = acceptPhaseRef(cfg.phases)
for (const row of ROWS) {
const base = mergeRows(cfg[row], tables?.[row], row, ref, log)
cfg[row] = mergeRows(base, override?.[row], row, ref, log)
}
return cfg
}
/** Defaults < routing.json (phases, rows, this repo's rows) < override. */
async function assemble(
$: Api,
file: Layer,
over: Layer,
log: Log,
): Promise<Loaded> {
const fileData = typeof file === 'string' ? undefined : file.data
const override = typeof over === 'string' ? undefined : over.data
if (file === 'absent') {
log(`model-router: ${ROUTING} missing; default phases, no rows, no asks`)
}
const key = fileData === undefined ? undefined : await projectKey($)
if (fileData !== undefined) logMissingPhases(fileData.phases, log)
const cfg = layerConfig(
fileData && routingTables(fileData, key), override, log)
const mem = fileData === undefined
? emptyMemory()
: buildMemory(fileData, key, override)
return { cfg, source: sourceWord(file, over), mem, override }
}
/**
* Reads the layers. At the first load a failed layer is skipped (logged); in
* every later read any failure, or a routing.json gone missing, returns
* undefined so the caller keeps the whole previous config.
*/
async function loadLayers(
$: Api,
first: boolean,
log: Log,
): Promise<Loaded | undefined> {
const file = await readRouting($, log)
const over = await readOverride($, log)
const broken = file === 'failed' || file === 'absent' || over === 'failed'
if (broken && !first) return undefined
return assemble($, file, over, log)
} }
/** Compiles the prompt rules; one that fails to compile is dropped, logged. */ /** Compiles the prompt rules; one that fails to compile is dropped, logged. */
@@ -605,13 +798,23 @@ function newState(cfg: Config, source: string): State {
logged: new Set(), logged: new Set(),
turnLogged: new Set(), turnLogged: new Set(),
warned: new Set(), warned: new Set(),
mem: emptyMemory(),
override: undefined,
loaded: false,
rebuildDue: false,
toggles: {},
asking: null,
asked: new Set(),
writes: Promise.resolve(),
} }
} }
/** /**
* /clear rebuilds the state but keeps what is account- or process-wide: * /clear rebuilds the state but keeps what is account- or process-wide:
* the breaker (a model's quota outlives the conversation), the model and * the breaker (a model's quota outlives the conversation), the model, the
* the agent definitions' sources (the listing is not offered again). * agent definitions' sources (the listing is not offered again), the config
* with its session toggles and the dialog in flight. The layers are read
* again at the next prompt; the config is swapped only if that read works.
*/ */
function resetSession(st: State): void { function resetSession(st: State): void {
const kept = { const kept = {
@@ -620,8 +823,15 @@ function resetSession(st: State): void {
agentModels: st.agentModels, agentModels: st.agentModels,
sessionModel: st.sessionModel, sessionModel: st.sessionModel,
offers: st.offers, offers: st.offers,
mem: st.mem,
override: st.override,
loaded: st.loaded,
toggles: st.toggles,
asking: st.asking,
writes: st.writes,
} }
Object.assign(st, newState(st.cfg, st.source), kept) Object.assign(st, newState(st.cfg, st.source), kept)
st.rebuildDue = st.loaded
} }
/** Logs a hook's fail-open once per session; never throws itself. */ /** Logs a hook's fail-open once per session; never throws itself. */
@@ -1179,8 +1389,9 @@ async function toggle(
arg: string | undefined, arg: string | undefined,
): Promise<string> { ): Promise<string> {
if (arg !== 'on' && arg !== 'off') return `usage: /route ${what} on|off` if (arg !== 'on' && arg !== 'off') return `usage: /route ${what} on|off`
if (what === 'switch') st.cfg.mainModelSwitch = arg === 'on' if (what === 'switch') st.toggles.switch = arg === 'on'
else st.cfg.verbose = arg === 'on' else st.toggles.verbose = arg === 'on'
applyToggles(st)
return show($, st) return show($, st)
} }
@@ -1192,22 +1403,49 @@ async function setUserRoute($: Api, st: State, args: string) {
return show($, st) return show($, st)
} }
/** /** Session toggles outlive any rebuild of the config. */
* (Re)loads the config into the state and re-registers the route tool. function applyToggles(st: State): void {
* An unusable override keeps the previous config: the kill switch fails const { switch: downgrade, verbose } = st.toggles
* closed, never back to the defaults. if (downgrade !== undefined) st.cfg.mainModelSwitch = downgrade
*/ if (verbose !== undefined) st.cfg.verbose = verbose
async function reloadConfig($: Api, st: State): Promise<void> { }
const loaded = await loadConfig($, text => $.ui.log(text))
if (loaded) { function applyLoaded(st: State, loaded: Loaded, log: Log): void {
st.cfg = loaded.cfg st.cfg = loaded.cfg
st.rules = compileRules(loaded.cfg, text => $.ui.log(text)) st.rules = compileRules(loaded.cfg, log)
st.source = loaded.source st.source = loaded.source
st.mem = loaded.mem
st.override = loaded.override
st.loaded = true
st.rebuildDue = false
applyToggles(st)
applyEnabled(st, loaded.cfg.enabled) applyEnabled(st, loaded.cfg.enabled)
} else { }
$.ui.log('model-router: override unreadable; keeping the previous config')
} /**
* (Re)loads the layers into the state and re-registers the route tool.
* After the first load an unusable layer keeps the whole previous config:
* the kill switch fails closed, never back to the defaults. True when the
* new config was swapped in.
*/
async function reloadConfig($: Api, st: State): Promise<boolean> {
const log = (text: string): void => $.ui.log(text)
const loaded = await loadLayers($, !st.loaded, log)
if (loaded) applyLoaded(st, loaded, log)
else log('model-router: config unreadable; keeping the previous config')
await registerTool($, st) await registerTool($, st)
return loaded !== undefined
}
/**
* The layers are read at session.start; a state that never saw it (a
* /reload-plugins re-runs register) loads on its first use. /clear leaves
* a re-read due, taken by the next prompt only (`atPrompt`).
*/
async function ensureConfig($: Api, st: State, atPrompt = false) {
if (st.loaded && !(atPrompt && st.rebuildDue)) return
st.rebuildDue = false
await reloadConfig($, st)
} }
/** The breaker is cleared first, whatever the config read then does. */ /** The breaker is cleared first, whatever the config read then does. */
@@ -1240,6 +1478,10 @@ async function handleCommand($: Api, st: State, args: string): Promise<string> {
return show($, st) return show($, st)
case 'reload': case 'reload':
return reloadCommand($, st) return reloadCommand($, st)
case 'pending':
return pendingText(st)
case 'ask':
return askCommand($, st, rest[0])
case 'switch': case 'switch':
case 'verbose': case 'verbose':
return toggle($, st, head, rest[0]) return toggle($, st, head, rest[0])
@@ -1248,6 +1490,328 @@ async function handleCommand($: Api, st: State, args: string): Promise<string> {
} }
} }
// ---- first use: one dialog per row, the answer kept in routing.json -----
// The first time a row routes (a typed skill, an agent spawn, a phase
// declared through the route tool) the user confirms it once, for every
// project; a change can be a project exception. Only a dialog answer or
// `/route ask` writes; nothing is asked on the step path or in an agent.
const HEADER = 'model-router'
const UPDATED = 'routing.json updated: commit it from the config repo ' +
'(chore branch)'
type Req = { kind: Kind; name: string; phase: string }
type RowReq = Req & { kind: Row }
type Answer =
| { act: 'later' }
| { act: 'keep' }
| { act: 'change'; phase: string }
type Scope = 'everywhere' | 'project' | 'later'
type Patch = (file: Rec) => void
const keyOf = (req: { kind: Kind; name: string }): string =>
`${req.kind}:${req.name}`
const isRowReq = (req: Req): req is RowReq => req.kind !== 'phases'
const own = (t: Table, name: string): string | undefined =>
hasKey(t, name) ? t[name] : undefined
/** Decided: a Keep or change confirmed the row, or a layer set it. */
function isDecided(mem: Memory, kind: Kind, name: string): boolean {
if (kind === 'phases') return own(mem.confirmed.phases, name) === name
if (mem.local[kind].has(name)) return true
const base = own(mem.base[kind], name)
return base !== undefined && own(mem.confirmed[kind], name) === base
}
const wantsAsk = (st: State, req: Req): boolean =>
!st.off && st.mem.ask && !st.asked.has(keyOf(req)) &&
!isDecided(st.mem, req.kind, req.name)
/** The file as it is now: another live session may have decided since. */
async function refreshMemory($: Api, st: State): Promise<boolean> {
const file = await readRouting($, text => $.ui.log(text))
if (typeof file === 'string') return false
st.mem = buildMemory(file.data, await projectKey($), st.override)
return true
}
async function askOr(
$: Api,
text: string,
options: readonly string[],
): Promise<string> {
try {
return await $.ui.ask(text, { options, header: HEADER })
} catch {
return LATER // dismissed, or no one to ask (-p run)
}
}
function optionsFor(st: State, req: Req): string[] {
const alts = ALTS[req.kind]
.filter(p => p !== req.phase && hasKey(st.cfg.phases, p))
return req.kind === 'phases'
? [LATER, KEEP]
: [LATER, KEEP, ...alts.slice(0, 2)]
}
/** Keep, a phase of the table (an alt or free text), else Later. */
function decide($: Api, st: State, req: Req, answer: string): Answer {
if (answer === KEEP) return { act: 'keep' }
if (answer === LATER || req.kind === 'phases') return { act: 'later' }
if (!hasKey(st.cfg.phases, answer)) {
const shown = answer.slice(0, 40).replace(/[\u0000-\u001f]/g, ' ')
$.ui.toast(`unknown phase "${shown}", default kept`)
return { act: 'later' }
}
return answer === req.phase
? { act: 'keep' }
: { act: 'change', phase: answer }
}
async function askScope(
$: Api,
st: State,
req: Req,
to: string,
): Promise<Scope> {
const key = st.mem.key
const text = `Use ${to} for ${req.name} everywhere, or only in this project?`
const answer = await askOr($, text,
[EVERYWHERE, key === undefined ? LATER : THIS_PROJECT])
if (answer === EVERYWHERE) return 'everywhere'
return answer === THIS_PROJECT && key !== undefined ? 'project' : 'later'
}
function table(parent: Rec, key: string): Rec {
const found = isRecord(parent[key]) ? parent[key] : undefined
if (found) return found
const fresh: Rec = {}
parent[key] = fresh
return fresh
}
function setKey(target: Rec, key: string, value: unknown): void {
if (key !== '__proto__') target[key] = value
}
const confirmIn = (file: Rec, kind: Kind, name: string, phase: string) =>
setKey(table(table(file, 'confirmed'), kind), name, phase)
/** A Keep endorses the row and its phase (no second ask at the route tool). */
function keepPatch(req: Req): Patch {
return file => {
if (isRowReq(req)) confirmIn(file, req.kind, req.name, req.phase)
confirmIn(file, 'phases', req.phase, req.phase)
}
}
/**
* Everywhere: the row moves, `changed` keeps the FIRST shipped phase for
* the census. This project only: the row stays, the exception goes under
* the repo key and the base row counts as confirmed (nobody else asks).
*/
function changePatch(req: RowReq, to: string, scope: Scope, key?: string) {
return (file: Rec): void => {
const rows = table(file, req.kind)
const was = typeof rows[req.name] === 'string' ? rows[req.name] : req.phase
if (scope === 'project' && key !== undefined) {
const mine = table(table(file, 'projects'), key)
setKey(table(mine, req.kind), req.name, to)
confirmIn(file, req.kind, req.name, String(was))
return
}
const changed = table(table(file, 'changed'), req.kind)
const first = subRec(changed, req.name).from ?? was
setKey(rows, req.name, to)
setKey(changed, req.name, { from: first, to })
confirmIn(file, req.kind, req.name, to)
}
}
function serializeRouting(file: Rec): string {
const known = ROUTING_ORDER.filter(k => hasKey(file, k))
const extra = Object.keys(file).filter(k => !ROUTING_ORDER.includes(k))
const ordered = Object.fromEntries(
[...known, ...extra].map(k => [k, file[k]]))
return JSON.stringify(ordered, null, 2) + '\n'
}
/**
* Read-modify-write of routing.json, one at a time (a chain). Refuses a
* missing or unparsable file and never creates it; rebuilds the config
* after, swapped only if the read works.
*/
async function writeNow($: Api, st: State, patch: Patch): Promise<boolean> {
const file = await readRouting($, text => $.ui.log(text))
if (typeof file === 'string') {
$.ui.toast(`${ROUTING} is missing or unreadable: nothing saved`)
return false
}
patch(file.data)
const out = serializeRouting(file.data)
if (out.length > MAX_CONFIG_BYTES) {
$.ui.toast(`${ROUTING} would exceed ${MAX_CONFIG_BYTES} bytes: ` +
'nothing saved')
return false
}
await $.fs.write(file.path, out)
const rebuilt = await reloadConfig($, st)
$.ui.toast(UPDATED)
if (!rebuilt) throw new Error('rebuild failed after the write')
return true
}
function writeRouting($: Api, st: State, patch: Patch): Promise<boolean> {
const run = st.writes.then(() => writeNow($, st, patch))
st.writes = run.catch(() => undefined)
return run
}
async function saveAnswer($: Api, st: State, req: Req, ans: Answer) {
if (ans.act === 'keep') return writeRouting($, st, keepPatch(req))
if (ans.act !== 'change' || !isRowReq(req)) return false
const scope = await askScope($, st, req, ans.phase)
if (scope === 'later') return false
const patch = changePatch(req, ans.phase, scope, st.mem.key)
return writeRouting($, st, patch)
}
/** The dialog and what follows; true when routing.json was rewritten. */
async function runDialog($: Api, st: State, req: Req, text: string) {
const answer = await askOr($, text, optionsFor(st, req))
st.asked.add(keyOf(req))
return saveAnswer($, st, req, decide($, st, req, answer))
}
function failOnce($: Api, st: State, err: unknown): void {
const text = `model-router: first-use dialog failed (${String(err)}); ` +
'default route kept'
if (st.logged.has(text)) return
st.logged.add(text)
$.ui.log(text)
}
/**
* Asks once whether `req.phase` is the right route for this row. At most
* one dialog is open per session: any other use finds `asking` set and
* routes unasked. The caller awaits it outside `safely` (it never throws).
* `say` builds the question from the real decision, only if one is asked.
* True when routing.json changed: the caller recomputes its route.
*/
async function confirmFirst(
$: Api,
st: State,
req: Req,
say: () => Promise<string>,
): Promise<boolean> {
if (st.asking !== null || !wantsAsk(st, req)) return false
st.asking = keyOf(req)
try {
if (!(await refreshMemory($, st)) || !wantsAsk(st, req)) return false
return await runDialog($, st, req, await say())
} catch (err) {
st.asked.delete(keyOf(req))
failOnce($, st, err)
return false
} finally {
st.asking = null
}
}
/** First-use question text: the id and level the next step really gets. */
async function mainQuestion($: Api, st: State, lead: string) {
const v = await snapshot($, st)
return `${lead} ${idWord(st, v.call.model)} at ${
effortWord(st, v)}. Keep it?`
}
function spawnQuestion(
$: Api,
st: State,
e: SpawnIn,
req: Req,
route: Route,
): string {
const id = spawnTarget($, st, e, route) ?? 'its own model'
const effort = st.explicitEffort.get(e.tool_use_id) ?? route.effort
return `First dispatch of ${req.name}: ${req.phase}, ${id} at ${
effort ?? 'its own effort'}. Keep it?`
}
/** Typed skill: a changed row re-routes the turn at once. */
async function confirmSkill($: Api, st: State, skill: string, row: Picked) {
const req: Req = { kind: 'skills', name: skill, phase: row.phase }
const lead = `First route for /${skill}: ${row.phase}, next step`
if (!(await confirmFirst($, st, req, () => mainQuestion($, st, lead)))) {
return
}
const after = skillRow(st, skill)
if (after === undefined) return
routeMainBySkill(st, after, true)
refresh($, st)
}
/** Rowed spawn: the route in force after the dialog (changed or not). */
async function routeSpawn($: Api, st: State, e: SpawnIn) {
const frozen = e.fork || e.workflow !== undefined
const route = spawnRoute(st, e, frozen)
const phase = hasKey(st.cfg.agents, e.subagentType)
? st.cfg.agents[e.subagentType]
: undefined
const inside = e.parentAgentId !== undefined || e.model !== undefined
if (!route || !phase || inside) return route
const req: Req = { kind: 'agents', name: e.subagentType, phase }
const say = async () => spawnQuestion($, st, e, req, route)
return (await confirmFirst($, st, req, say))
? spawnRoute(st, e, frozen)
: route
}
/** A phase declared through the route tool: confirm-only. */
async function confirmPhase($: Api, st: State, phase: string) {
const req: Req = { kind: 'phases', name: phase, phase }
const lead = `First use of ${phase} on the main loop:`
await confirmFirst($, st, req, () => mainQuestion($, st, lead))
}
// ---- first-use commands ----------------------------------------------
/** Rows and phases not confirmed yet, those asked this session first. */
function pendingText(st: State): string {
const m = st.mem
if (!m.ok) return `${ROUTING} missing or unreadable: nothing to confirm`
const names = (kind: Kind): string[] => Object.keys(
kind === 'phases' ? st.cfg.phases : m.base[kind])
.filter(name => !isDecided(m, kind, name))
const all = KINDS.flatMap(kind => names(kind).map(name => ({ kind, name })))
.map(keyOf)
const asked = all.filter(k => st.asked.has(k))
const rest = all.filter(k => !st.asked.has(k))
return [
`pending confirmation: ${all.length}` +
(m.ask ? '' : ' (asking is off: /route ask on)'),
`asked this session: ${asked.join(' ') || 'none'}`,
`not asked yet: ${rest.join(' ') || 'none'}`,
].join('\n')
}
async function askCommand($: Api, st: State, arg: string | undefined) {
if (arg !== 'on' && arg !== 'off') return 'usage: /route ask on|off'
const patch: Patch = file => { file.ask = arg === 'on' }
try {
if (!(await writeRouting($, st, patch))) {
return `${ROUTING} missing or unreadable: ask unchanged`
}
} catch (err) {
return `ask not applied (${String(err)})`
}
const local = st.mem.askLocal
const note = local === undefined ? '' : `; ~/${OVERRIDE} sets ask ${
local ? 'on' : 'off'} and wins here`
return `ask ${arg}${note}`
}
// ---- route tool ------------------------------------------------------ // ---- route tool ------------------------------------------------------
async function registerTool($: Api, st: State): Promise<void> { async function registerTool($: Api, st: State): Promise<void> {
@@ -1283,8 +1847,8 @@ async function registerCommand($: Api): Promise<void> {
name: 'route', name: 'route',
description: 'model-router: show or set the model and effort route', description: 'model-router: show or set the model and effort route',
argumentHint: argumentHint:
'[show|clear|off|on|reload|<phase>|model=<alias|id> effort=<level>' + '[show|clear|off|on|reload|pending|ask on|off|<phase>|' +
'|switch on|off|verbose on|off]', 'model=<alias|id> effort=<level>|switch on|off|verbose on|off]',
immediate: true, immediate: true,
}) })
} catch (err) { } catch (err) {
@@ -1372,6 +1936,9 @@ async function handleRouteTool($: Api, st: State, e: RouteInput) {
const picked = pickRoute(st.cfg, e.phase, e.effort) const picked = pickRoute(st.cfg, e.phase, e.effort)
if (typeof picked === 'string') return { deny: picked } if (typeof picked === 'string') return { deny: picked }
applyRoute(st, e.agentId, picked) applyRoute(st, e.agentId, picked)
if (e.agentId === undefined && typeof e.phase === 'string') {
await confirmPhase($, st, picked.phase)
}
return { result: await routedText($, st, e.agentId, picked) } return { result: await routedText($, st, e.agentId, picked) }
} }
@@ -1423,13 +1990,25 @@ function typedPath(st: State, skill: string): TypedPath | undefined {
return st.promptAllowed && idle ? 'typed-fallback' : undefined return st.promptAllowed && idle ? 'typed-fallback' : undefined
} }
function applyTypedSkill($: Api, st: State, skill: string): void { /** Routes main by the typed skill's row; the row, for the first-use ask. */
function armTypedSkill($: Api, st: State, skill: string) {
const row = skillRow(st, skill) const row = skillRow(st, skill)
const path = typedPath(st, skill) const path = typedPath(st, skill)
if (row === undefined || path === undefined) return if (row === undefined || path === undefined) return undefined
routeMainBySkill(st, row, true) routeMainBySkill(st, row, true)
refresh($, st) refresh($, st)
vlog($, st, `skill ${skill}: ${path} → ${row.phase}`) vlog($, st, `skill ${skill}: ${path} → ${row.phase}`)
return row
}
/** Bookkeeping that may fail without breaking the hook: fail-open. */
function armed($: Api, st: State, skill: string): Picked | undefined {
try {
return armTypedSkill($, st, skill)
} catch {
warnOnce(st, $, 'skill.prompt', 'bookkeeping')
return undefined
}
} }
// ---- agents ---------------------------------------------------------- // ---- agents ----------------------------------------------------------
@@ -1438,6 +2017,7 @@ type SpawnIn = {
tool_use_id: string tool_use_id: string
subagentType: string subagentType: string
model?: string model?: string
parentAgentId?: string // set when the spawn happens inside an agent
fork: boolean fork: boolean
workflow?: unknown workflow?: unknown
} }
@@ -1736,11 +2316,23 @@ function registerBreaker(on: On, st: State): void {
}) })
} }
function registerCwd(on: On, st: State): void {
on('classic.CwdChanged', async ($, e, next) => {
// the repo key follows the directory: rebuild the layers
if (st.loaded) await reloadConfig($, st)
return next(e)
}).catch(($, e, next) => {
warnOnce(st, $, 'CwdChanged', next.error.kind)
return next(e)
})
}
function registerCommandHook(on: On, st: State): void { function registerCommandHook(on: On, st: State): void {
on('command.run', { command: 'route' }, async ($, e) => { on('command.run', { command: 'route' }, async ($, e) => {
if (e.origin.kind !== 'composer') { if (e.origin.kind !== 'composer') {
return { text: 'route: user-only command' } return { text: 'route: user-only command' }
} }
await ensureConfig($, st)
return { text: await handleCommand($, st, e.args) } return { text: await handleCommand($, st, e.args) }
}).catch(($, e, next) => { }).catch(($, e, next) => {
warnOnce(st, $, 'command.run', next.error.kind) warnOnce(st, $, 'command.run', next.error.kind)
@@ -1750,6 +2342,7 @@ function registerCommandHook(on: On, st: State): void {
function registerRouteTool(on: On, st: State): void { function registerRouteTool(on: On, st: State): void {
on('tool.call', { tool: TOOL }, async ($, e) => { on('tool.call', { tool: TOOL }, async ($, e) => {
await ensureConfig($, st)
const out = await handleRouteTool($, st, e) const out = await handleRouteTool($, st, e)
refresh($, st) refresh($, st)
vlog($, st, `route ${e.agentId ?? 'main'}: ${JSON.stringify(out)}`) vlog($, st, `route ${e.agentId ?? 'main'}: ${JSON.stringify(out)}`)
@@ -1762,6 +2355,7 @@ function registerRouteTool(on: On, st: State): void {
function registerSkills(on: On, st: State): void { function registerSkills(on: On, st: State): void {
on('tool.call', { tool: 'Skill' }, async ($, e, next) => { on('tool.call', { tool: 'Skill' }, async ($, e, next) => {
await ensureConfig($, st)
const skill = typeof e.skill === 'string' ? e.skill : undefined const skill = typeof e.skill === 'string' ? e.skill : undefined
if (st.off || skill === undefined) return next(e) if (st.off || skill === undefined) return next(e)
st.skillCalls += 1 st.skillCalls += 1
@@ -1776,8 +2370,10 @@ function registerSkills(on: On, st: State): void {
return next(e) return next(e)
}) })
on('skill.prompt', async ($, e, next) => { on('skill.prompt', async ($, e, next) => {
await ensureConfig($, st)
if (st.off || st.skillCalls > 0) return next(e) if (st.off || st.skillCalls > 0) return next(e)
safely(st, $, 'skill.prompt', () => applyTypedSkill($, st, e.skill)) const row = armed($, st, e.skill)
if (row) await confirmSkill($, st, e.skill, row)
return next(e) return next(e)
}).catch(($, e, next) => { }).catch(($, e, next) => {
warnOnce(st, $, 'skill.prompt', next.error.kind) warnOnce(st, $, 'skill.prompt', next.error.kind)
@@ -1829,11 +2425,12 @@ function registerSpawn(on: On, st: State): void {
return next(e) return next(e)
}) })
on('agent.spawn', async ($, e, next) => { on('agent.spawn', async ($, e, next) => {
await ensureConfig($, st)
if (st.off) return next(e) if (st.off) return next(e)
st.spawning += 1 st.spawning += 1
try { try {
await prune($, st) await prune($, st)
const route = spawnRoute(st, e, e.fork || e.workflow !== undefined) const route = await routeSpawn($, st, e)
const wanted = spawnTarget($, st, e, route) const wanted = spawnTarget($, st, e, route)
const started = await next(wanted === undefined const started = await next(wanted === undefined
? e ? e
@@ -1942,6 +2539,7 @@ function noteTyped(st: State, kind: string, text: string, midTurn: boolean) {
function registerPrompt(on: On, st: State): void { function registerPrompt(on: On, st: State): void {
on('prompt.submit', async ($, e, next) => { on('prompt.submit', async ($, e, next) => {
await ensureConfig($, st, true)
if (st.off) return next(e) if (st.off) return next(e)
const midTurn = e.turnId !== undefined const midTurn = e.turnId !== undefined
noteTyped(st, e.origin.kind, e.text, midTurn) noteTyped(st, e.origin.kind, e.text, midTurn)
@@ -1966,6 +2564,7 @@ export const register: Register = on => {
const st = newState(mergeConfig(undefined, () => undefined), 'defaults') const st = newState(mergeConfig(undefined, () => undefined), 'defaults')
registerSession(on, st) registerSession(on, st)
registerBreaker(on, st) registerBreaker(on, st)
registerCwd(on, st)
registerCommandHook(on, st) registerCommandHook(on, st)
registerRouteTool(on, st) registerRouteTool(on, st)
registerSkills(on, st) registerSkills(on, st)
+144
View File
@@ -0,0 +1,144 @@
{
"phases": {
"plan": {
"tier": "best",
"effort": "xhigh"
},
"reflect": {
"tier": "best",
"effort": "high"
},
"orchestrate": {
"tier": "best",
"effort": "medium"
},
"escalate": {
"tier": "best",
"effort": "max"
},
"judge": {
"tier": "big",
"effort": "xhigh"
},
"implement": {
"tier": "work",
"effort": "medium"
},
"write": {
"tier": "work",
"effort": "high"
},
"verify": {
"tier": "work",
"effort": "xhigh"
},
"explore": {
"tier": "work",
"effort": "medium"
},
"apply": {
"tier": "work",
"effort": "low"
},
"mechanical": {
"tier": "cheap",
"effort": "low"
}
},
"skills": {
"ship-feature": "plan",
"init-project": "plan",
"onboard": "plan",
"tour": "plan",
"audit-delta": "plan",
"analyze": "plan",
"code-clean": "plan",
"client-handover": "plan",
"brainstorming": "plan",
"writing-plans": "plan",
"requesting-code-review": "plan",
"21st-ui-review": "plan",
"feat": "reflect",
"hotfix": "reflect",
"bugfix": "reflect",
"refactor": "reflect",
"web-validate": "reflect",
"harden": "reflect",
"seo": "reflect",
"geo": "reflect",
"site-motion": "reflect",
"frontend-design": "reflect",
"emil-design-eng": "reflect",
"design-motion-principles": "reflect",
"21st-ui-build": "reflect",
"scroll-world-storytelling": "reflect",
"build-threejs-scroll-worlds": "reflect",
"scroll-scrubbed-visual-sequence": "reflect",
"scroll-scrubbed-word-reveal": "reflect",
"scroll-progress-timeline": "reflect",
"subagent-driven-development": "reflect",
"writing-skills": "reflect",
"deprecation-and-migration": "reflect",
"21st-ai": "reflect",
"21st-ui-explore": "reflect",
"gitflow": "implement",
"prune-memory": "implement",
"pdf-translate": "implement",
"ci-cd-and-automation": "implement",
"observability-and-instrumentation": "implement",
"test-driven-development": "implement",
"commit-change": "apply",
"release-candidate": "apply",
"doc": "apply",
"capitalize": "apply",
"close": "apply",
"reconcile": "apply",
"deploy": "apply",
"status": "mechanical",
"profile": "mechanical",
"plugin-check": "mechanical",
"skills-perso": "mechanical",
"using-git-worktrees": "mechanical",
"21st-cli-use": "mechanical",
"21st-registry": "mechanical",
"21st-design-sync": "mechanical"
},
"agents": {
"Explore": "explore",
"Plan": "judge",
"plan-challenger": "judge",
"plugin-advisor": "judge",
"seo-analyzer": "judge",
"geo-analyzer": "judge",
"analyzer": "judge",
"feater": "implement",
"bugfixer": "implement",
"code-cleaner": "implement",
"scaffolder": "implement",
"onboarder": "implement",
"commit-changer": "write",
"doc-syncer": "write",
"handover-doc-writer": "write",
"refactorer": "write",
"hotfixer": "apply",
"release-executor": "apply",
"plugin-probe": "apply",
"validator-analyzer": "apply",
"verifier": "verify",
"security-auditor": "verify",
"status-reporter": "mechanical"
},
"projects": {},
"confirmed": {
"agents": {
"verifier": "verify",
"feater": "implement"
},
"phases": {
"verify": "verify",
"implement": "implement"
}
},
"changed": {},
"ask": true
}