diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 1f6cff2..ffdf923 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -1422,6 +1422,10 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **Gates**: plan r1 → r3 (simplicity CONCERNS(4), robustness FATAL(6) BLOCKER unbounded await, correctness CONCERNS(4); confirmation robustness CONCERNS(4)); feater DONE (423) + 1 round (trim, argumentHint, repeated undefined: 428, each mutation-proven); GATE 0 MET; verifier ECARTS(2) coverage → CONFORME on #2; security PASS (0 findings; LOW accepted: pasted text can steer one turn's effort up, README says so). Abort paths judged by reading (`[gated]` clarification). Residual: `smallModelBusy` checks `cfg.models.haiku` while classify uses the engine's default small model (mismatch only when the two differ). Live AC9 open. - **Refs**: contract `.claude/tasks/contracts/2026-10-11-model-router-w4b-classifier-1858.md`, plan r3 same slug. Links [[EVAL-045]], [[LRN-210]]. +- **Amendment (2026-10-13, feature/router-downgrade-cap, commit 2ce203a, user decision)**: W4-B "EFFORT ONLY" clause superseded. Classifier writes full phase route; main may move DOWN on a guess, never above session model (`wantedModel` ranks vs `sessionModel`, not `cur`: breaker fallback sonnet→opus, never haiku); `ultrathink` floor model beats guess. `mainModelSwitch` default **true**, fail-closed picker (non-boolean → off + log). Caps measure COLD READ (LRN-216): `coldRead(M) = tokens − served[M].tokens` within `CACHE_TTL_MS` 1 h, else whole context; `downgradeMaxTokens` 120000 (user delegated value), `upgradeMaxTokens` 200000 same measure; served record written EVERY main step, dropped by `/clear` + `/route reload`, stale (context < record) = cold. No return bypass (warm return cheap by construction). Model-loaded helper skill inside best-tier run → effort only (`belowRun`). Window outgrown (haiku 200k) → back to session model. `/effort` typed between turns drops guess for that turn only (`engineBase` per turn). Rejected: user `/model` suspends classifier (baseline moves, guess follows; `/route classify off` pins) — trade-off accepted; raw context-size cap (r1: refused cheap re-down to warm sonnet, forced cold fable read); engine-model return bypass (premise false after N sonnet turns). Residuals TODO 2026-10-13: unrowed agent `parentModel` inheritance on demoted turn, `session.usage` lag vs new prompt, TTL const. Gates: 3 lenses CONCERNS (10 MAJOR) → r2; confirmation FATAL(7) BLOCKER → r3; feater DONE 450 tests; verifier CONFORME 10/10 first pass; security PASS. Links [[LRN-216]], [[EVAL-047]], [[LRN-204]]. + +- **Amendment 2 (2026-10-13, same branch, commit 1be57a3, user "fix les residus")**: three residuals closed. (1) Spawn pin NARROW: built-in `general-purpose` only (`INHERITING_AGENTS` + `offers.source === 'built-in'`), no explicit model, no row, no fork/workflow, main's own child, main BELOW session model (`ranksAbove(session, turnModel)`), session model ranked + up → sent `sessionModel` verbatim, cause `session`. Rejected: "no model + no row = inherits" (r1 BLOCKER ×2: frontmatter `model:` invisible to the hook, would override plugin/project agents; LRN-217); any `turnModel` (upgrade would drag agents down). (2) Prompt estimate: `ceil(codePoints/3)` of text + `context` + main's TYPED skill body, summed, first baseline kept; pure `withEstimate` in shared `readingFor` + `mainPlan` (texts = step); `noteServed` RAW (inflated record would trip compaction path); consumed at first main step of its turn; mid-turn → `pendingEstimate` next turn; `document` attachment → unknown → blocked. (3) TTL: `cacheTtlMs` from engine enum `'5m'|'1h'` on main's PostModelSwitch (`agent_id` events ignored), kept across `/clear`, show prints `ttl N min`. Residuals left (TODO): TTL before first switch event = 60 min assumption; hooks-below context / dropped prompt = conservative; `onAutoSwitch` targets main's `lastPlan` for sub-agent fallbacks (pre-existing); LIVE CHECK whether `parentModel` follows the rewrite. Gates: 3 lenses (FATAL ×2, CONCERNS) → r2, confirmation CONCERNS(3) → r3, feater DONE 472 tests, verifier CONFORME 7/7, security PASS. Links [[LRN-217]], [[LRN-216]]. + ## BDR-117 — shared gstack helpers live in lib/gstack-removed.sh, not in a new lib [accepted] (2026-10-12) - **Decision**: C5 /refactor 2026-10-12. profile.sh + toggle-external.sh duplicated gstack_skills + park/unpark moves. Host gstack_skills/gstack_parked_names/gstack_park/gstack_unpark in lib/gstack-removed.sh; each takes dirs as args, no caller globals; plain-statement call only (errexit, [[LRN-215]]). - **Why**: only sourced file 5 fixture suites copy next to both scripts; new lib = every fixture breaks. diff --git a/.claude/memory/evals.md b/.claude/memory/evals.md index 30f038a..a81be58 100644 --- a/.claude/memory/evals.md +++ b/.claude/memory/evals.md @@ -425,3 +425,8 @@ Dogfood: 3 blind lenses attacked the v1 plan for the plan-challenge feature itse - **Method**: correctness FATAL(6), robustness FATAL(5), simplicity CONCERNS(5), confirmation CONCERNS(2). Independent re-check of the executor: `make test` 47 green, shellcheck 0, hook `$pattern` sha256 identical old/new, old vs new google_seo.py no-arg run byte-identical (stdout, stderr, rc). - **Anomaly**: r1 wrong on 5 points (directive placement, logic-line counter ignored the error-handling exclusion → 1 false positive + 3 reclassified, B18 half false: 2 of 4 sites already `local`, C1 move would silently void T19, `|| return $?` rule inverted). Executor denied once (`rm -rf` on a variable path), used a fresh dir, reported it. Scope file's BUG TO LOG block came out empty (regex cut at the heading) — executor fell back to the plan. Two golden gaps left open by executor (gstack-absent warning, pack_hints with stubbed CLI). - **Action**: keep the confirmation pass after a material rewrite (it caught 2 MAJOR the first round missed). Scope writer: assert every section non-empty before dispatch. Links [[LRN-213]], [[LRN-214]], [[LRN-215]]. + +## EVAL-047 — model-router downgrade cap: 3 lenses CONCERNS, confirmation pass FATAL(7); the 4th blind read found the BLOCKER the author + 3 lenses missed +- **Method**: /feat. r1 (author): context-size cap + engine-model return bypass + classifier full route. 3 blind lenses on r1: simplicity CONCERNS(3), correctness CONCERNS(4), robustness CONCERNS(3), 10 MAJOR, 0 BLOCKER, convergent (cold-read measure, classifier upgrade leak, bypass useless, test list incomplete, helper-skill demotion, haiku window). r2 written. ONE confirmation challenger on r2: FATAL(7) — BLOCKER served record only on routed steps (session model's cache invisible), + 6 MAJOR (test (d) `turnModel` survives `/route clear`, guess vs `cur` + breaker → haiku, floor hidden by guess tier, `pickSwitch` fails OPEN, compaction floor-at-0, `engineBase` process-wide kill). r3 → feater DONE first pass, 450 tests, verifier CONFORME 10/10 first pass, security PASS. +- **Anomalies**: author's r2 introduced 1 BLOCKER + 6 MAJOR while fixing r1 — a material rewrite is a NEW plan, the confirmation pass is not optional. `pickSwitch` "fail closed" was wrong by name: falls back to seeded default (now true). Verifier noticed 2 stale texts outside criteria (label comment, route tool description) — fixed by hand pre-commit (minor, justified). Doc-sync SIGNIFICANT: 13 patches, 3 docs stated the old default as a promise. +- **Action**: keep the single confirmation pass mandatory after any r2 that changes the mechanism (not just wording); when a plan says "fail closed", name the picker and its fallback value in the plan; TODO residuals (parentModel inheritance, usage lag, TTL const) carried, not dropped. Links [[BDR-116]], [[LRN-216]], [[EVAL-045]]. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 26eccc2..06abff1 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -607,3 +607,7 @@ rules: - /code-clean whole repo on chore/code-clean (gitflow start, pushed). Plan r1→r3: 3 lenses + confirmation, C1 (gitflow-test.sh move) deferred ×2 lenses, B18 half false, C3 needed stderr oracle, errexit rule inverted. User approved all 14 non-deferred items. code-cleaner DONE: A1 import, B1-B4 lint/hook regex (sha identical), B5/B7/B9/B11 splits, B18-B20, C2 suite wired, C3 hoist. make test 47 green, shellcheck 0, verified independently. 1 bug logged (usage() 3-26 truncation). No commit. LRN-213/214/215, EVAL-046. Next (user: "capitalize all then correct bugs with what has been skipped"): usage() fix inline, C4/C5 via /refactor; C1 + B13-B17 left (blocked / no-change by design). - Follow-up (same branch, no commit): usage() bug fixed inline (`sed -n '3,/^# ====/p' | sed '$d'`, --help 36 lines, 14 tools). /refactor → refactorer: C4 `tool_kind`/`tool_source` single roster (exact-match loop, not the `*" $x "*` idiom: multi-word arg stayed unknown), `disable_*` split mirrors `enable_*`; C5 shared `gstack_skills/parked_names/park/unpark` in lib/gstack-removed.sh (already copied by all 5 fixtures; new sourced lib would break them). 496-run golden capture identical except `${name:?}` diagnostic line ref for an empty `gstack__` dir. Verified: make test 47 green, shellcheck 0. Left: C1 (T19 lock), B13-B17 (no change), `name` leak in enable_pack. Commit split suggested: cleanup / usage fix / C4-C5. - Rust default-language rule (user ask). `rules/default-language.md` always-on (no `paths:`), CLAUDE.global.md at 317/320 → BDR-085 exception path. Hooks: interviewer FAILURE MODES row, init-project BDR table, project CLAUDE.md exception list. Branch chore/rust-default, doctrine-citers green. BDR-118 pending user approval. + +## 2026-10-13 +- model-router /feat `downgradeMaxTokens` (user: switch on by default, classifier may switch model early, back up to fable on reflection). Plan r1 context-size cap → challenge: cap must measure COLD READ (LRN-204), bypass dropped, classifier down-only vs session model; confirmation pass FATAL(7), BLOCKER served-record-on-routed-steps-only → r3. feater DONE 450 tests, verifier CONFORME 10/10, security PASS, commit 2ce203a on feature/router-downgrade-cap. Doc-sync + BDR/LRN/EVAL pending. +- Residuals /feat (user "fix les residus"): plan r1 → 3 lenses FATAL×2 (BLOCKER: `e.model===undefined && route===undefined` ≠ "inherits", frontmatter model invisible to the hook) → allowlist `INHERITING_AGENTS` + built-in source + below-session guard; estimate via shared `withEstimate`, raw served record; TTL enum lookup. Confirmation CONCERNS(3) → r3. feater DONE 472 tests, verifier CONFORME 7/7, security PASS, commit 1be57a3. Doc-sync + capitalize pending. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 92b8c1a..fe19c2f 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -1801,3 +1801,11 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s ## LRN-215 — helper extracted from a `set -e` function must be called as a plain statement; `helper || …` / `if helper` switches errexit OFF inside it - **Context**: code-clean B5/B7/B9 split enable_tool / enable_skill / cmd_show out of `set -euo pipefail` scripts. r2 executor rule said `|| return $?`; confirmation lens: that form disables errexit inside the helper, so a failed `mv` (toggle-external.sh:273) would print `ok …` rc 0 instead of aborting — a path no golden capture sees. Plain call keeps `return 1` → errexit in caller → exit 1 as today. - **Apply**: split rule for -e scripts: plain calls only, never `||`, `&&`, `if`, `!` around an extracted helper. Golden capture (stdout + stderr + rc + fixture tree) before/after for every moved arm when the suite discards output. Links [[LRN-214]], [[EVAL-046]]. + +## LRN-216 — Capping a main-loop model switch = cap the COLD READ (context − target's warm prefix), never the context size; the warm record must be written on EVERY main step +- **Context**: model-router downgrade cap 2026-10-13. r1 compared context size to cap → after N coding turns sonnet warm, fable cold; context crosses cap → next coding turn starts on fable (cold) and cheap re-down refused = worst outcome. r2 fixed measure, but wrote `served` only on routed steps → unrouted steps on session model invisible → return to fable refused above 200k (confirmation pass BLOCKER). Per-model prefix cache (LRN-204): cost of switch INTO M = tokens − tokens at M's last step if within TTL, else all; context smaller than record = history rewritten (compaction) = cold. +- **Apply**: any "switch model when cheap" logic: (1) keep `{at, tokens}` per model id, written at every step of the loop whatever the routing; (2) cost = delta vs that record within TTL, whole context otherwise or when record > current; (3) unknown size = blocked; (4) no special-case "return to session model" bypass, the measure covers it. A guess-sourced route ranks vs the SESSION model, not the current one, or a breaker fallback walks down to the cheapest tier. Links [[BDR-116]], [[LRN-204]], [[EVAL-047]]. + +## LRN-217 — In an `agent.spawn` hook, "no explicit `model` and no routing row" does NOT mean "inherits the parent": the agent's frontmatter `model:` is invisible to the hook; only an allowlist of types known to inherit is safe, and `agent.offer.source` tells a built-in from a shadowing definition +- **Context**: model-router residuals 2026-10-13, plan r1 pinned every unrowed, model-less spawn to the session model during a demoted turn. Two lenses BLOCKER: engine 2.1.296 builds the spawn input as `model: e.model` (Agent tool param only); frontmatter model never reaches `agent.spawn` nor `agent.offer`; `route === undefined` also covers frozen forks/workflows (hook model ignored) and project-source skips; nested spawns carry the SUB-AGENT's `parentModel`; `turnModel` is set on upgrades too. A repo/user `general-purpose.md` can shadow the built-in with its own `model:` → `offers.get(type) === 'built-in'` is the discriminator. +- **Apply**: before rewriting a spawn's model, prove the agent would inherit: allowlist of built-in types with no frontmatter (`general-purpose`), source `built-in`, not fork/workflow, `parentAgentId` undefined, and the parent really sits below the baseline. Record what the hook cannot see as a `shortcut:` at the allowlist. Links [[BDR-116]], [[BDR-115]], [[LRN-203]]. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 3277004..01dd11f 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -1,5 +1,13 @@ # TODO +## 2026-10-13 — model-router: cold-read cap, switch on by default, classifier routes down (feature/router-downgrade-cap) +Contract `.claude/tasks/contracts/2026-10-13-router-downgrade-cap-0013.md`, plan r3 `.claude/tasks/plans/2026-10-13-router-downgrade-cap-0013.md`. +- [x] /feat run: 3 lenses (10 MAJOR) → r2; confirmation pass FATAL(7) (BLOCKER: served record only on routed steps) → r3; feater DONE (19 tests + 3 extra, 450 pass), GATE 0 MET 4/4, verifier CONFORME 10/10 first pass, security PASS. Commit 2ce203a. +- [x] Residuals (1)-(3) closed 2026-10-13, commit 1be57a3 (contract `.claude/tasks/contracts/2026-10-13-router-cap-residuals-1902.md`, plan r3): session pin for built-in `general-purpose` spawned by main below the session model; prompt-size estimate (text + context + typed skill body, code points / 3) added to the cap's size at the first main step unless usage grew by half; `document` attachment = unknown = blocked; engine `cache_ttl` ('5m'|'1h') adopted from main's PostModelSwitch. 3 lenses (2 BLOCKER same finding: frontmatter model invisible to the hook) → r2; confirmation CONCERNS(3) → r3; feater DONE 472 tests; verifier CONFORME 7/7; security PASS. Residual (4) "model unknown to the table" not reproduced since (later route answers named claude-fable-5-1): closed as transient. +- [ ] Residuals left (accepted): TTL known only after the first PostModelSwitch of the process (no API exposes the account TTL; 60 min default before); hooks-below `context` and a dropped prompt leave the estimate conservative/stale; `onAutoSwitch` targets main's `lastPlan` even for a sub-agent's auto fallback (pre-existing); `agent_id: null` on a main switch (if the engine ever sends null) would freeze sessionModel/TTL updates. +- [ ] LIVE CHECK: does `parentModel` follow the turn.step rewrite or the session model? Read general-purpose's step-0 `message.model` in a transcript during a demoted turn (if it is already the session model, the pin is a harmless no-op). +- [ ] Live check (next sessions): a coding prompt on fable → spinner `sonnet-5-5/medium`; a reflect turn after → fable; above 120k cold read the skip line once; `/route show` cap text. + ## 2026-10-12 — code-clean whole repo (chore/code-clean) - [x] audit r1→r3 (3 lenses + confirmation), user approved all 14 non-deferred items, code-cleaner DONE, make test 47 green — plan `.claude/tasks/plans/2026-10-12-code-clean-0103.md`, scope `.claude/audits/CODE-CLEAN-SCOPE.md` - [x] fix BUGS-FOUND: toggle-external.sh usage() prints header 3-26, list ends at 32 diff --git a/.claude/tasks/contracts/2026-10-13-router-cap-residuals-1902.md b/.claude/tasks/contracts/2026-10-13-router-cap-residuals-1902.md new file mode 100644 index 0000000..cac1ba5 --- /dev/null +++ b/.claude/tasks/contracts/2026-10-13-router-cap-residuals-1902.md @@ -0,0 +1,37 @@ +# CONTRACT — router-cap-residuals +- date: 2026-10-13 | flow: feat | branch: feature/router-downgrade-cap (working branch, commit in place) +- status: active + +## REQUEST (verbatim — IMMUTABLE) +User: "tres bien, fix les residus" +(the residuals = the three accepted residuals of the downgrade-cap run, TODO.md 2026-10-13 entry, items (1)-(3); item (4) "model unknown to the table" was a one-off observation, not a residual to code) + +/feat arguments: model-router: close the three residuals of the downgrade-cap run (TODO 2026-10-13). (1) An unrowed sub-agent with no explicit model spawned while main is demoted (turnModel set) must not inherit the demoted parentModel: spawn it on the session model. (2) The cap reads `session.usage().context.tokens`, which may not include the prompt just submitted: estimate the submitted prompt's size at prompt.submit and add it to the tokens of that turn's first main step before the cap check. (3) `CACHE_TTL_MS` is a 60 min constant: adopt the engine's `cache_ttl` carried by PostModelSwitch events when present (parse `5m`/`1h` forms), fall back to the constant. Same branch feature/router-downgrade-cap. + +## CLARIFICATIONS +Q: prompt-size estimate unit / A: delegated — code points / 3, rounded up (conservative: French and code tokenize denser than English) +Q: add the estimate blindly, or detect whether usage already counts the prompt? / A: delegated — detect: usage read at prompt.submit vs at the turn's first main step; the estimate is added only when the growth is under half the estimate (the prompt was not counted) +Q: hand-off log word for a spawn pinned to the session model / A: delegated — `session` (model cause), verbose line only +Q: `/route show` shows the TTL? / A: delegated — yes, inside the switch word: `on (downgrade, cap 120000 tokens cold, ttl 60 min)` +Q: which spawns may be pinned? / A: [r2, challenge BLOCKER] only built-in types with no frontmatter model (`general-purpose`), main's own non-fork non-workflow children, when main sits BELOW the session model; the hook cannot see a frontmatter `model:`, so any wider rule would override agents' own pins +Q: estimate consumption / A: [r2] first main step after the submit; carried across a turn end when unconsumed; texts read the same adjusted size (pure peek); the served record stays raw + +## ACCEPTANCE CRITERIA +1. `spawnTarget` pins a spawn to `st.sessionModel` (verbatim) ONLY when: no explicit `model`, no row, not a fork, no workflow, `parentAgentId` undefined (main's own child), `subagentType` in the allowlist `INHERITING_AGENTS` (`general-purpose`: built-in types with no frontmatter model) AND offered with source `built-in` (`st.offers`; a shadowing repo/user agent of that name, or no offer record, is never pinned), `turnModel` set AND ranking BELOW the session model (demotion or breaker fallback, never an upgrade), session model ranked and not down. Everything else is untouched. Hand-off bookkeeping: `wanted` set, model cause `session`. A `shortcut:` comment names the frontmatter blind spot. +2. Prompt-size estimate: `prompt.submit` (any origin; text plus `context` entries) and `skill.prompt` (ONLY main's typed skill, never a sub-agent preload) ADD `ceil(codePoints / 3)` to a pending estimate (sum; the FIRST entry's usage read is the baseline); a `document` attachment marks the estimate unknown. A mid-turn submit (`turnId` set) is pending for the NEXT turn (baseline reset at promotion). A pure `withEstimate(st, raw)` returns `raw + estimate` when the baseline is unknown or usage grew by less than half the estimate, `undefined` when unknown, else `raw`; it is applied in the shared reading path (`readingFor`, texts) AND in `mainPlan` (step), so both agree. `noteServed` records the RAW size. The estimate is consumed by the first main step of its turn; an unconsumed one is carried across the turn end with its baseline reset (added at the next step), never dropped. +3. TTL: `State.cacheTtlMs` initialised to `CACHE_TTL_MS` (60 min), replaced on a PostModelSwitch event whose `cache_ttl` is one of the engine's two values (`'5m'` → 5 min, `'1h'` → 60 min; anything else ignored); events carrying `agent_id` change neither the TTL nor `sessionModel`. `coldRead` uses `st.cacheTtlMs`. The TTL survives `/clear` and is NOT reset by `/route reload`. +4. `/route show` switch word reads `on (downgrade, cap tokens cold, ttl min)` when on; `off (downgrade)` unchanged; the existing show test is migrated. +5. Tests in `hooks/register.test.ts`: (a) general-purpose during a demoted turn → session model; (b) no route → untouched; (b2) rowed feater → row wins; (b3) fork → untouched; (b4) nested spawn → untouched; (b5) non-allowlisted unrowed type → untouched; (b6) upgraded main (haiku session → fable) → untouched; (d) pasted prompt counted before the first step (cap 110000, raw 100000, estimate 20000 → refused); (e) growth = half → not added → allowed, growth < half → added → refused; (f) consumed by the first step, carried across turn end when unconsumed; (g) `'5m'` → 6 min old record cold, `'1h'` → 59 min old warm; (h) sub-agent switch event leaves TTL and sessionModel; (i) `/clear` keeps the TTL; (j) show ttl text default and after `'5m'`; (k) document attachment blocks the first step's switch; (l) typed skill body counted, (l2) a preload during an in-flight spawn adds nothing; (b7) a shadowed `general-purpose` (source `projectSettings`) is never pinned. Estimate tests run with `classify: false`. Migrated existing tests, expectations re-derived, never weakened: the show text test (ttl suffix) and `toast: a downgrade held by the cap says so` (its cold-read figure now includes the typed `/feat` prompt's estimate, 6 tokens for 17 code points, plus any typed body counted). +6. Whole mod suite green. + CHECK: make test suite=lib/tests/mods.test.sh 2>&1 | tail -1 + EXPECT: all suites green + EVIDENCE: MET exit=0 marker-found :: all suites green +7. `coldRead` reads `st.cacheTtlMs`, not the constant; the allowlist exists. + CHECK: cd mods/model-router && ! grep -n "CACHE_TTL_MS" hooks/register.ts | grep -q "now - hit.at" && grep -q "cacheTtlMs" hooks/register.ts && grep -q "INHERITING_AGENTS" hooks/register.ts && echo CRIT7-OK + EXPECT: CRIT7-OK + EVIDENCE: MET exit=0 marker-found :: CRIT7-OK + +## FILE SCOPE +- mods/model-router/hooks/register.ts +- mods/model-router/hooks/register.test.ts +(README/USAGE/CHANGELOG via STEP 6 doc-sync) diff --git a/.claude/tasks/contracts/2026-10-13-router-downgrade-cap-0013.md b/.claude/tasks/contracts/2026-10-13-router-downgrade-cap-0013.md new file mode 100644 index 0000000..885de40 --- /dev/null +++ b/.claude/tasks/contracts/2026-10-13-router-downgrade-cap-0013.md @@ -0,0 +1,49 @@ +# CONTRACT — router-downgrade-cap +- date: 2026-10-13 | flow: feat | branch: feature/router-downgrade-cap (to start off develop) +- status: active + +## REQUEST (verbatim — IMMUTABLE) +User (2026-10-13, after the explanation of why `mainModelSwitch` is off): +"on va partir sur 2 on va fiare un feat maintenant comme ca c'est bon. JE te laisse juger le seuil de token a metre en place, sachant que capourrait switcher plusieurs fois dnas la meme conversation. Dison que si je suis sur fable et que l'interprete du prompt estime que c'est un autre model il switch de model tot. Et si il y a de nouveau de la reflexion alors on switch plus haut genre fable sans forcemnt re down si on ateint la limite de token. bref je te laisse faire ca" + +Option 2 as proposed by Claude: "Un `/feat` qui ajoute `downgradeMaxTokens` au mod et passe le switch à on par défaut sous ce plafond." + +/feat arguments: model-router: downgrade cap. Add `downgradeMaxTokens` to the mod (symmetric to `upgradeMaxTokens`): a main-loop downgrade is allowed only while the context is under the cap; above it main keeps its model (no re-down once the limit is reached, upgrades to best still allowed). Flip `mainModelSwitch` default to on under that cap. User also wants the prompt classifier to be allowed to move the main model down (today effort-only by design, W4-B), with the cap as the guard. Threshold value left to Claude's judgment (several switches per conversation expected). + +## CLARIFICATIONS +Q: default value of `downgradeMaxTokens` / A: delegated — 120000 tokens of COLD READ (LRN-204; r2: measured against the target model's warm prefix, not the context size); per-machine override in `~/.claude/model-router.json` +Q: does a return to the engine's own model obey the upgrade cap? / A: delegated — r1 said "bypass"; r2 (challenge, correctness #1): no bypass, both caps measure the COLD READ of the target (LRN-204), so a warm return passes by itself and a cold one is capped like any switch +Q: does the classifier also move main UP (design/analysis → best tier)? / A: delegated — no, downgrades only; prompt rules keep upgrading as today [r2, correctness #2] +Q: does a user `/model` suspend the classifier's model axis? / A: delegated — no; the baseline moves and the guess routes from it; `/route classify off` or `/route off` pins [r2, correctness #3, trade-off to the BDR] +Q: when a user `/effort` beats the classifier's effort guess (`userMovedEffort`), does the model guess still apply? / A: delegated — no: the whole classifier route yields for that step, both axes +Q: status line display once the switch defaults to on / A: [gated 2026-10-13] show ` · switch off` only when the switch is off; the ` · switch on` fragment is dropped (on is the norm) + +## ACCEPTANCE CRITERIA +1. `Config` carries `downgradeMaxTokens` (positive number, default 120000), merged like `upgradeMaxTokens` (`pickPositive`, user override wins, invalid value logged and ignored). + CHECK: cd mods/model-router && grep -q "downgradeMaxTokens: 120000" hooks/register.ts && grep -q "user.downgradeMaxTokens, base.downgradeMaxTokens, 'downgradeMaxTokens'" hooks/register.ts && echo CRIT1-OK + EXPECT: CRIT1-OK + EVIDENCE: MET exit=0 marker-found :: CRIT1-OK +2. `mainModelSwitch` defaults to `true` in `DEFAULT_CONFIG` and is merged FAIL-CLOSED (a non-boolean override is logged and reads as `false`; it never enables anything). + CHECK: cd mods/model-router && grep -q "mainModelSwitch: true," hooks/register.ts && grep -q 'config "mainModelSwitch" is not a boolean' hooks/register.ts && echo CRIT2-OK + EXPECT: CRIT2-OK + EVIDENCE: MET exit=0 marker-found :: CRIT2-OK +3. Both caps measure the COLD READ of the target model (context tokens minus the tokens at that model's last main step when it served within `CACHE_TTL_MS` = 1 h; the whole context when never served, expired, or when the context is SMALLER than the record (compaction: entry dropped); unknown size = blocked): `upgradeCall` and `leaveDown` against `upgradeMaxTokens`, `downgradeCall` against `downgradeMaxTokens`, through ONE helper (`coldBlock`). The served record is written on EVERY main step (routed or not), kept across turn ends, NOT kept across `/clear`, reset by `/route reload`. A downgrade refusal keeps `switch off` first, then logs `downgrade skipped: cold read N tokens over M` / `downgrade skipped: context size unknown` once per cap crossing (until a downgrade next succeeds). No "return bypass" exists. +4. In `decideMain`, main routed onto a model whose known window (`windows`) the context has outgrown returns to the session model (once-log) when the size is known and the session model is a known, ranked, not-down, non-haiku id; otherwise the normal decision runs. `moveTo` carries `[1m]` when `cur` OR the session model has it (haiku excepted). +5. The prompt classifier writes the full phase route (`tier` + `effort`); the model name comes from the first slot carrying one, and when that slot is the classifier's: a floor with a model wins over it, and a wanted that ranks above the SESSION model is dropped (a guess never moves main above the user's baseline; a breaker fallback from a guessed sonnet reaches opus, never haiku). So `coding`/`bookkeeping` move main down under the switch and the cold-read cap while `design`/`analysis` only set effort; `chat`/unknown route nothing. `userMovedEffort` compares this turn's first engine effort with the previous turn's; when true, `mainPlan` drops a classifier route for THIS turn only (both axes, `turnModel` untouched, texts agree); the next classified turn routes again. A user `/model` is NOT a guard (baseline moves). In-file comments at the classifier (~l.3438-3441, 3535, 3546) state the new rule. +6. A model-loaded (not typed) skill row whose resolved model ranks below the run slot's resolved model moves effort only while `runMain` is set; typed skills and best-tier rows unchanged. +7. `/route show` prints `switch: on (downgrade, cap 120000 tokens cold)` / `switch: off (downgrade)`; the status line shows ` · switch off` only when the switch is off [gated 2026-10-13]; the toast hint names a cap hold (`, held: `) as well as the switch. +8. Tests in `hooks/register.test.ts`: (a) downgrade under the cold-read cap by default; (b) above the cap keeps main, one log; (c) unknown usage blocks; (d) warm model cheap to return to, with a control (cold opus blocked at the same size); (e) classifier coding → sonnet/medium; (f) classifier coding above the cap → fable/medium; (g) `switch off` restores today's behavior; (h) user `/effort` drops the model guess, `/route show` agrees; (i) design guess never moves a sonnet session up; (j) model-loaded helper skill in a run moves effort only; (k) haiku outgrown returns to the session model; (l) quoted "false" switch reads as off with a warning; (m) cap hold toast hint; (n) TTL expiry; (o) reload forgets the record + skip line once per cap crossing across turns; (p) smaller context than the record is cold; (q) mid-turn ultrathink floor beats a guess; (r) guessed sonnet rate-limited falls to opus never haiku; (s) a user /effort drops the guess for one turn only. The tests the default flip invalidates (plan § Tests list, incl. l.305-315, 605-614, 747, 754, 951-958, 1665-1672, 2934-2943, 4576, 4783-4799, status-line `switch on` assertions) are re-expressed with an explicit `switch off`, never weakened or deleted; a mutable-usage rig uses ONE bottom `session.usage` hook. +9. The whole mod test suite passes. + CHECK: make test suite=lib/tests/mods.test.sh 2>&1 | tail -1 + EXPECT: all suites green + EVIDENCE: MET exit=0 marker-found :: all suites green +10. `lib/effort-shift.md` Limits bullet about the classifier says the guess may move the model DOWN under `mainModelSwitch` and `downgradeMaxTokens`, never up, and that a user `/model` moves the baseline; no longer "effort only". + CHECK: ! grep -q "classifier (effort only;" lib/effort-shift.md && grep -q "downgradeMaxTokens" lib/effort-shift.md && echo CRIT10-OK + EXPECT: CRIT10-OK + EVIDENCE: MET exit=0 marker-found :: CRIT10-OK + +## FILE SCOPE +- mods/model-router/hooks/register.ts +- mods/model-router/hooks/register.test.ts +- lib/effort-shift.md +(README.md l.144/146 and USAGE.md l.190 handled by STEP 6 doc-sync, out of the executor's scope) diff --git a/.claude/tasks/plans/2026-10-13-router-cap-residuals-1902.md b/.claude/tasks/plans/2026-10-13-router-cap-residuals-1902.md new file mode 100644 index 0000000..9139d6b --- /dev/null +++ b/.claude/tasks/plans/2026-10-13-router-cap-residuals-1902.md @@ -0,0 +1,164 @@ +# PLAN — router-cap-residuals (feat, r3: r2 + confirmation CONCERNS(3) closed below) +Contract: .claude/tasks/contracts/2026-10-13-router-cap-residuals-1902.md + +## Files +1. mods/model-router/hooks/register.ts +2. mods/model-router/hooks/register.test.ts + +## Approach +- (1) Demoted-turn spawn pin, NARROW (`spawnTarget` ~l.2890, `spawnModelCause`, + `handoffOf` ~l.3160) [BLOCKER: the hook cannot see an agent's frontmatter `model:`; + `e.model === undefined && route === undefined` is NOT "inherits"]. New const + `INHERITING_AGENTS: ReadonlySet = new Set(['general-purpose'])` next to + `PROJECT_SOURCES` (~l.155), comment: "built-in types with no frontmatter model: an + undefined `model` makes them inherit the spawning loop's model". `spawnTarget` + rewrites to `st.sessionModel` (verbatim, keeps `[1m]`) ONLY when ALL hold: + `e.model === undefined && route === undefined`, `!e.fork && e.workflow === undefined` + (frozen: engine ignores a hook model), `e.parentAgentId === undefined` (main's child: + `parentModel` IS main's model), `INHERITING_AGENTS.has(e.subagentType)`, `st.offers.get(e.subagentType) === 'built-in'` + [r3 #1: a repo or user `general-purpose.md` shadowing the built-in may carry a + frontmatter model; no offer record = deny], `st.turnModel !== undefined` and `ranksAbove(st, canonical(sessionModel), + canonical(turnModel))` (main sits BELOW the session model: demotion or breaker + fallback, never an upgrade), session model ranked and not in `st.down`. Else + `undefined` (today's path). `handoffOf`: the "has a hand-off" condition adds + `sp.wanted !== undefined`; `spawnModelCause` returns `'session'` when `route === + undefined && e.model === undefined && sp.wanted !== undefined`. `shortcut:` comment at + the allowlist: "the frontmatter model of other types is invisible to the hook; widen + the set when the engine exposes it on agent.offer". +- (2) Prompt estimate (State, `prompt.submit` ~l.3560, `skill.prompt` ~l.3462, + `readingFor` ~l.1387, `mainPlan` ~l.3240, `endMainTurn` ~l.3282): + `State.promptEstimate: { tokens: number; usage: number | undefined; unknown: boolean } + | null`. `addEstimate(st, text, usage)`: estimate = `Math.ceil(Array.from(text).length + / 3)`; a pending entry SUMS the tokens and KEEPS the first baseline (`usage`); a fresh + one takes `usage` = `await readTokens($)` at that moment. `prompt.submit` (any + origin, mid-turn too): `addEstimate` with `e.text`; if the input carries a + `document` attachment (check the kit type for the attachments field; if absent in the + input type, skip this clause and say so in the report) set `unknown = true`. + `skill.prompt`: `addEstimate` with `e.text` ONLY when the prompt is main's TYPED skill + (the `typedPath` verdict, exposed from `armTypedSkill` for rowed and unrowed names + alike; a preload inside an in-flight spawn — `spawning > 0` — adds nothing) [r3 #2], + called BEFORE `confirmSkill` so the dialog and toast see the body. + `prompt.submit` also counts the code points of `e.context ?? []` entries (hooks above + attached them; hooks-below context arrives after `next`, residual) [r3 #6]. + `withEstimate(st, raw): number | undefined` PURE (no mutation): `raw` when + `raw === undefined || st.promptEstimate === null`; `undefined` (blocked) when + `est.unknown`; `raw + est.tokens` when `est.usage === undefined || raw − est.usage < + est.tokens / 2`; else `raw`. Used by BOTH `readingFor` (texts: snapshot, + mainQuestion, toastChange) and `mainPlan` → step and texts agree. + `mainPlan`: `const raw = await readTokens($)`; `read = { tokens: withEstimate(st, + raw), now }` for `decideFor`; `noteServed(st, plan, { tokens: raw, now })` records the + RAW size (an over-estimate in the record would trip the compaction path); then + `st.promptEstimate = null` (consumed by the first main step of the turn the prompt + belongs to). Mid-turn submits (`e.turnId !== undefined`) go to + `st.pendingEstimate` instead, promoted by `endMainTurn` into `promptEstimate` with the + baseline reset to `undefined` (the codebase convention for mid-turn input: + `pendingPrompt`/`pendingSlash`) [r3 #4: whether the engine injects a mid-turn prompt + into the running turn is unverified; next-turn is the conservative reading]. An + unconsumed `promptEstimate` at turn end is likewise carried (baseline reset), never + dropped. +- (3) TTL (`CACHE_TTL_MS` ~l.224, `coldRead` ~l.1188, `SwitchIn` ~l.3325, + `onModelSwitch`, `resetSession`): `State.cacheTtlMs` initialised to `CACHE_TTL_MS`, + listed in `resetSession`'s `kept`, untouched by `reloadCommand`. `SwitchIn` gains + `cache_ttl?: unknown` and `agent_id?: unknown`. `const CACHE_TTLS: Readonly> = { '5m': 300000, '1h': 3600000 }` (the engine's closed enum); + `ttlOf(v: unknown)` = `typeof v === 'string' && hasKey(CACHE_TTLS, v) ? CACHE_TTLS[v] + : undefined`. `onModelSwitch`: when `e.agent_id !== undefined` (a sub-agent's switch) + do NOT write `sessionModel` nor the TTL (breaker handling unchanged); else `const ttl + = ttlOf(e.cache_ttl); if (ttl !== undefined) st.cacheTtlMs = ttl` before the + `st.off` return. `coldRead` compares against `st.cacheTtlMs`. Const comment: "1 h + default; replaced by the engine's `cache_ttl` at the first model-switch event". +- (4) `switchWord(st)` → `on (downgrade, cap ${st.cfg.downgradeMaxTokens} tokens cold, + ttl ${Math.round(st.cacheTtlMs / 60000)} min)`; `off (downgrade)` unchanged. + +## Edge cases +- Session model unknown (''), unranked or down → no pin, engine decides. +- Upgraded main (haiku session lifted to fable by a plan route) → no pin: the agent + inherits fable as today. +- Fork / workflow / nested / project-source / non-allowlisted type → untouched. +- Estimate: `readTokens` failing at submit → baseline undefined → added (conservative); + `tokens` unknown at the step → stays unknown → blocked. Two queued pastes → summed. + `document` attachment → unknown → every switch blocked that turn. +- Mid-turn submit: consumed by the first main step after it; none follows → carried to + the next turn, baseline reset. +- A prompt dropped by a later hook leaves a stale estimate for the next step (accepted: + conservative; residual). +- TTL takes effect only after the first PostModelSwitch event of the process; before it + the 60 min default holds (residual, named in TODO: no API exposes the account TTL). +- Sub-agent PostModelSwitch events never move `sessionModel` or the TTL. + +## Tests (register.test.ts) — contract letters +- Helpers: `typed($, text)` (l.878) / `queued` for prompts, `clearSession` (l.4507) for + /clear, `usageVar`, `switchTo(from, to, source, cache_ttl = '5m')` (add the optional + 4th param typed `'5m' | '1h'`); `home: { classify: false }` for the estimate tests + (bootRig has no classify bottom hook). +- Migration: `text: show names the switch and its cap` (~l.5188) expects `switch: on + (downgrade, cap 120000 tokens cold, ttl 60 min)`. `toast: a downgrade held by the cap + says so` (~l.5202): `typeFeat` submits `/feat add a thing` (17 code points → estimate + 6) on usage 300000, so the toast now reads `cold read 300006 tokens over 120000` + (plus the skill body's estimate if `typeFeat` also runs skill.prompt with a body: the + executor derives the exact figure and states it in the report) [r3 #3]. +- `switchTo(from, to, source, cache_ttl = '5m', agent_id?)`; (i) registers a bottom + `on('session.end', …)` before boot (bootRig has none); (f) uses `queued($, + 'composer', …)` for the mid-turn case and a FRESH rig for the carried case [r3 #7]. +- (a) `spawn: general-purpose during a demoted turn starts on the session model` + (fable rig, route mechanical, step → haiku, spawn general-purpose with `parentModel: + HAIKU` → bottom gets `model: FABLE`). +- (a) fires `offerOf($, 'general-purpose', 'built-in')` before the spawn [r3 #1]. +- (b7) `general-purpose` offered from `projectSettings` (shadowed) → untouched [r3 #1]. +- (b) same spawn, no route in force → untouched. (b2) `feater` (rowed) during a demoted + turn → SONNET (row wins). (b3) `general-purpose` with `fork: true` → untouched. (b4) + nested: `parentAgentId: 'a1'` → untouched. (b5) a non-allowlisted unrowed type + (`code-explorer`) → untouched. (b6) haiku session upgraded to fable by a plan route, + spawn general-purpose → untouched (inherits fable). +- (c) = (b2). +- (d) `cap: a pasted prompt counts before the first step`: `home: { classify: false, + downgradeMaxTokens: 110000 }`, usageVar 100000, `typed` 60000-code-point text + (estimate 20000), route implement → refused, log `cold read 120000 tokens over + 110000`. +- (e) `set(110000)` before the step (growth 10000 = half) → nothing added → 110000 ≤ + 110000 → SONNET; sibling `set(109999)` (growth 9999 < half) → added → 129999 → + refused. +- (f) consumed: after (d)'s first step, a second step same turn sees raw (route implement + at raw 100000 → SONNET); carried: `typed` mid-turn (with `turnId`) then `endTurn`, next + turn's first step adds it (refused at the 110000 cap with raw 100000). +- (g) `switchTo(FABLE, FABLE, 'command', '5m')`, record 6 min old → cold (refused above + cap); `switchTo(..., '1h')`, record 59 min old → warm (allowed). +- (h) sub-agent switch event (`agent_id: 'a1'`, `'5m'`) → TTL and `sessionModel` + unchanged (`/route show` ttl still 60 min). +- (i) `clearSession` keeps a 5 min TTL. +- (j) show: `ttl 60 min` default; `ttl 5 min` after a `'5m'` event. +- (k) `cap: a document attachment blocks the FIRST step's switch` (`attachments: [{ + type: 'document' }]` exists on PromptSubmitInput, d.ts ~7198) — first step blocked, + second step raw [r3 #7]. +- (l) `cap: a typed skill's body counts` (`SkillPromptInput.text`), and (l2) `a preload + during an in-flight spawn adds nothing` [r3 #2]. +- Run: `make test suite=lib/tests/mods.test.sh`. + +## Disposition (STEP 0.6) +- honors BDR-116 amendment 2026-10-13 / LRN-216: the record stays RAW and on every main + step; the cap alone reads the adjusted size; the TTL is one state value `coldRead` + reads. +- honors BDR-115 (spawn hook sets a model once; explicit `model` wins; an agent moves UP + from its frontmatter, never below): the pin covers only types with no frontmatter + model, and only lifts them back to the session model. +- honors LRN-206 (kit: one bottom hook per event): `usageVar`/`switchTo` reuse. + +## CHALLENGE SUMMARY (r1 → r2) +- BLOCKER (correctness #1 = robustness #1): frontmatter invisible → allowlist + `INHERITING_AGENTS` + fork/workflow/nested/project-source guards + tests (b3-b5). +- MAJOR: upgrade sets `turnModel` (c#2, r#3) → `ranksAbove(session, turnModel)` + (b6); + texts vs step (s#1, c#5, r#10) → pure `withEstimate` in `readingFor`; test (e) values + (s#5, c#3) → boundary 110000/109999; TTL enum (s#3, c#4, r#8) → two-value lookup, (h) + rewritten as the sub-agent case; mid-turn estimate dropped at turn end (r#4) → carried + with baseline reset; served inflation (r#5, c#6) → RAW record; overwrite (r#6) → sum; + attachments/skill body (r#7, c#9) → unknown flag + skill.prompt estimate; sub-agent + switch events (r#9) → ignored for sessionModel/TTL; rig names (s#4, c#8) → `typed`, + `clearSession`, show test migration; `switchWord(st)` (s#6). +- Residuals kept (TODO): TTL known only after the first switch event; a dropped prompt + leaves a conservative stale estimate; hooks-below `context` not counted; sub-agent auto + fallback marks main's model down (pre-existing, `onAutoSwitch` targets `lastPlan`); + LIVE CHECK: does `parentModel` follow the turn.step rewrite or the session model? read + general-purpose's step-0 `message.model` in a transcript during a demoted turn (if it + is already the session model, the pin is a no-op) [r3 #5]. +- Confirmation pass r2: CONCERNS(3), closed by the [r3 #n] changes above. +- Deferred BLOCKERs: none. diff --git a/.claude/tasks/plans/2026-10-13-router-downgrade-cap-0013.md b/.claude/tasks/plans/2026-10-13-router-downgrade-cap-0013.md new file mode 100644 index 0000000..ffa607e --- /dev/null +++ b/.claude/tasks/plans/2026-10-13-router-downgrade-cap-0013.md @@ -0,0 +1,235 @@ +# PLAN — router-downgrade-cap (feat, r3: r2 + confirmation pass FATAL(7) → 1 BLOCKER + 6 MAJOR closed by the named changes below) +Contract: .claude/tasks/contracts/2026-10-13-router-downgrade-cap-0013.md + +## Files +1. mods/model-router/hooks/register.ts +2. mods/model-router/hooks/register.test.ts +3. lib/effort-shift.md + +## Core change of r2 — the cap bounds the COLD READ, not the context size +LRN-204: a switch INTO a model costs the tokens that model's prompt cache does not +hold; within the 1 h TTL its cache holds the prefix up to its last main step. So the +cost of moving main to model M at a context of T tokens is +`coldRead(M) = T − servedTokens(M)` when M served main within the TTL, else `T`. +r1 compared T itself to the cap, which (correctness #1) refused the cheap re-down to a +warm Sonnet and forced a cold read on Fable instead. r2 compares `coldRead`. + +## Approach +- Config (`register.ts` Config type ~l.30-37, DEFAULT_CONFIG ~l.217-275, mergeRouting + ~l.512-537): `downgradeMaxTokens: number` next to `upgradeMaxTokens` in `Config`, + `Routing` and `mergeRouting` (`pickPositive(user.downgradeMaxTokens, + base.downgradeMaxTokens, 'downgradeMaxTokens', log)`); default `120000`, comment + "max cold read a downgrade may cost (LRN-204)". `upgradeMaxTokens` comment becomes + "max cold read an upgrade may cost". `mainModelSwitch: true`, merged FAIL-CLOSED like `pickEnabled` (~l.505-510): a + non-boolean override logs `model-router: config "mainModelSwitch" is not a boolean; + switch off` and reads as `false` [r3 #5: `pickSwitch` falls back to the seeded + default, which is now `true`]. +- Served record (State ~l.80-100, `mainPlan` ~l.3052) [r3, BLOCKER #1 / #6 / #12]: + `served: Map` keyed by the canonical id main + was sent (`plan.model`). `mainPlan` reads `tokens` (`readTokens`) and `now` + (`$.clock.now()`) on EVERY main step, routed or not, and records + `served.set(canonical(plan.model), { at: now, tokens })` after the decision, whatever + the routing — an unrouted step on the session model is exactly the one that keeps + that model warm. Texts (`snapshot`, `toastChange`) keep the lazy read. `served` is + NOT in `resetSession`'s kept list (`/clear` starts cold) and is cleared by `/route + reload` next to the breaker marks (~l.1099-1108). Const `CACHE_TTL_MS = 60 * 60000` + next to `CLASSIFY_*`, comment: "the account's prompt-cache TTL (1 h here; an + engine-reported `cache_ttl` would supersede it — TODO)". `decideFor($, st, cur, + tokens?, now?)` takes the values when the caller has them and reads them itself + otherwise; it returns `{ call, wanted }` as today. `capSaid` is set/cleared in + `mainPlan` from the returned call (a text run never mutates it). + Compaction / history rewrite [#6]: in `coldRead`, when `tokens < entry.tokens` the + entry is stale → drop it and return `tokens` (cold). +- One cap helper replaces `capBlock` (~l.1143-1147): `coldBlock(st, id, tokens, max, + now)` → `undefined` when `tokens !== undefined && coldRead ≤ max`; else the reason + `'context size unknown'` or `` `cold read ${cold} tokens over ${max}` ``. + `coldRead(st, id, tokens, now)` = `tokens − entry.tokens` when `served.get(canonical + id)` exists and `now − entry.at ≤ CACHE_TTL_MS` (floored at 0), else `tokens`. + `decideFor` receives `tokens`/`now` from `mainPlan` (texts read them lazily, as today). +- `upgradeCall` (~l.1177-1192): `coldBlock(…, st.cfg.upgradeMaxTokens)` in place of + `capBlock`; same `keep(cur, why, 'model-router: upgrade skipped: …')`, `logKey + 'upgrade-skipped'`. `leaveDown` (~l.1160-1175) uses the same helper for `upOk`. + NO return bypass (simplicity #1, correctness #1/#5, robustness #4-#6): a return to a + warm model has a small cold read and passes by itself; turn end restores `e.model`. +- `downgradeCall` (~l.1196-1205): `switch off` refusal first (text unchanged), then + `coldBlock(…, st.cfg.downgradeMaxTokens)` → `skipped(cur, 'downgrade', block)` with + `logKey 'downgrade-skipped'`, then `fits`, then `moveTo`. One shared `skipped(cur, + kind, block)` builds both skip calls (upgrade too). +- Log spam (robustness #8): `downgrade-skipped` is said once per session until a + downgrade next succeeds: `st.capSaid: boolean`, set in `mainPlan` when the returned + call is a downgrade skip (log suppressed while set), cleared in `mainPlan` when the + returned call is `why === 'downgrade'`; the per-turn `turnLogged` dedupe stays for + the upgrade. +- `[1m]` carry (robustness #6): `moveTo` keeps `[1m]` from `cur`; after a haiku hop + `cur` has none. Change `moveTo(cur, target, why, session)` to carry `[1m]` when + EITHER `cur` or `st.sessionModel` has it (and the target is not haiku); all callers + pass `st.sessionModel`. +- Window re-check (robustness #2) [r3 #10]: in `decideMain`, after the `unknownCall` + check: when `st.turnModel !== undefined`, `tokens !== undefined`, `!fits(st, id, + tokens)`, and the session model is a known ranked id, not down and not haiku → `moveTo + (cur, canonical(st.sessionModel), 'window', st.sessionModel)` with a once-log + `model-router: context outgrew : back to `; any guard failing → + fall through to the normal decision. Only `windows` entries (haiku) can trigger it. +- Classifier model axis, DOWNGRADES ONLY under the switch (correctness #2, simplicity + #3, robustness #3) [r3 #3 / #4 / #9]: `routeFromLabel` (~l.3531-3541) writes `route: + { ...phaseRoute(st.cfg, phase) }` (tier + effort). `mainModel` becomes + `mainModelSlot(st): Routed | null` = the FIRST slot (userMain, turnMain, runMain, + turnFloor) whose route carries a model name; `decideFor` resolves the name from it. + Two rules on that slot when `slot.source === 'classifier'`: (i) a floor with a model + name wins over it (`turnFloor` route name used instead: `ultrathink` mid-turn still + reaches fable/max); (ii) the resolved `wanted` is dropped (`undefined`) when it + `ranksAbove` the SESSION model (`canonical(st.sessionModel)`), never compared to + `cur` — so a guess never moves main above the user's baseline, while a breaker + fallback from a guessed sonnet to opus (below fable) still works and never falls to + haiku. Texts and step agree (both go through `decideFor`). Existing test l.4568 + (sonnet session, design guess → sonnet) holds; rename it `…never moves UP`. +- Classifier vs a user `/effort` (simplicity #2, correctness #6/#7, robustness #9) [r3 + #7]: `engineBase` becomes per turn: `noteEngineBase` records the engine effort of + THIS turn's first main step, compared against the previous turn's value + (`st.engineBase` holds the last turn's, `st.turnEngine` this turn's; at turn end + `engineBase = turnEngine`). `userMovedEffort` = this turn's engine effort differs + from the previous turn's: a `/effort` typed between turns. In `mainPlan`, before + `mainEffort`: `if (userMovedEffort(st, e)) st.turnMain = null` when `turnMain.source + === 'classifier'` — the guess is dropped on both axes for THIS turn only; `turnModel` + is NOT touched (no return without a cold-read check; turn end restores `e.model`). + The `skipTurn` parameter of `mainEffort` (~l.1302) goes away. The next classified + turn routes again from the new baseline effort. +- User `/model` (correctness #3, robustness #3): NO suspension. A user `/model` sets + the new baseline (`sessionModel`) and the classifier keeps routing from it; `/route + classify off` or `/route off` pins the model. The r1 disposition claim is struck; the + trade-off goes into the BDR amendment and the doctrine line. +- Helper skills inside a run (robustness #1): `routeMainBySkill(st, skill, row, + typed)`: when `!typed && st.runMain !== null` and the row's tier ranks below the + run's (rank through `resolveRoute` → `modelRank`, so a phase naming a model is ranked + too [r3 #15]), write + `route: { effort: row.route.effort }` only — a model-loaded helper (e.g. + `using-git-worktrees` inside `/feat`) moves effort, never the orchestrator's model. + Typed skills and best-tier rows unchanged. Test l.1130 keeps `skill mechanical` in + the status and gains `expect((await stepOn(…)).model).toBe(FABLE)`. +- Toast hint (correctness #6) [r3 #11]: `skipped(cur, kind, block)` sets `call.why = + `${kind} skipped: ${block}`` (the bare block text is never the `why`) and `call.log = + 'model-router: ' + why`; `downgradeHeld` matches `why === 'switch off'` OR + `why.startsWith('downgrade skipped')`; hint: switch → unchanged text; cap → `, held: + `. Test (m) covers the cap hint. +- Texts (`show` ~l.1463, `statusLine` ~l.1475): `switch: on (downgrade, cap 120000 + tokens cold)` / `switch: off (downgrade)`; status line [gated 2026-10-13]: ` · switch + off` only when off, the ` · switch on` fragment is dropped. +- In-file comments (correctness #9): rewrite l.3438-3441 ("never a model move"), + l.3535 and l.3546 to the new rule (effort + a downward tier under the switch and the + cold-read cap). +- Doctrine (`lib/effort-shift.md` Limits bullet): "A plain typed prompt with no route + in force is classified by a small model: the guessed phase sets the turn's effort + and, under `mainModelSwitch` and `downgradeMaxTokens` (max cold read, default + 120000), may move main DOWN, never up; a user `/model` only moves the baseline the + guess starts from (`/route classify off` to stop guessing; never `-p`)." + +## Edge cases +- Context size unknown: both caps block, logged once (upgrade per turn, downgrade per + cap crossing); the window re-check does not fire on an unknown size. +- Compaction (`tokens` below a served entry): that entry is stale, the move is cold. +- TTL (60 min const) is an assumption of this account's cache; residual in TODO. +- Target down (breaker): `resolveName` yields the first available alias; a guessed route + ranks against the session model, so its fallback stays between sonnet and fable. +- Main already down, context grows past the downgrade cap mid-turn: `wanted` unchanged + → keep; a best route later moves up (cold read of Fable = delta since its last step, + usually under 200k); no re-down unless Sonnet's cold read fits — which it does while + Sonnet is warm. Turn end resets `turnModel`; next turn starts on `e.model`. +- Haiku on main and the context passes 200k: window re-check returns main to the + session model. +- `/route switch off`: identical to today (refusal text `switch off`). +- Classifier `chat`/unknown: nothing written. +- Non-best session (`/model opus`): coding guess → sonnet (downgrade); design guess → + stays opus (never up by a guess); prompt RULES still upgrade as today. +- Unrowed sub-agent with no explicit model spawned during a demoted turn may inherit + the demoted `parentModel` (robustness #10): accepted residual, all repo agents are + rowed and built-ins carry `model=`; logged in TODO. +- `session.usage().context.tokens` may lag the new prompt (robustness #11): accepted, + the cap is an economic guard, not a hard limit; logged in TODO. + +## Tests (register.test.ts) — contract letters +- Rig: add `usageVar(on, initial)` returning `{ set(n) }` over ONE bottom + `session.usage` hook with a mutable count (never a second `on('session.usage')`); + `bootRig` gains an optional `usage` handle or a sibling `bootRigVar`. +- Re-expressed (default flip), never weakened: l.305-315 (`/route model: alias + resolved…` → `switch off` first), l.605-614 and l.1665-1672 (toggle survival → + `switch off` / `switch: off`), l.747 (`switch off` first), l.754 (drop the `switch on` + line: default proves it), l.951-958 (`show reflects /model opus` → `switch off` + first), l.2934-2943 (toast: `switch off` first, hint text unchanged), l.4576 (`route + carries no tier` → `carries the tier`), l.4783-4799 (`classify guard: a route landing + during the call wins` → `switch off` first [r3 #8]), every status-line assertion on + ` · switch on` (grep) → asserts the fragment is ABSENT by default and present as + ` · switch off` after `switch off`. `bootCls` gains a `tokens` option (ClsOpts) for (f) + [r3 #13]. +- (a) `cap: a downgrade under the cold-read cap moves main` (fable, 1000 tokens, route + mechanical → haiku, no `switch on`). +- (b) `cap: a downgrade above the cold-read cap keeps main` (fable, 300000, route + mechanical → `{ model: FABLE, effort: 'low' }`, log contains `downgrade skipped: cold + read 300000 tokens over 120000`); second step same turn: no second log line. +- (c) `cap: unknown usage blocks the downgrade` (tokens null). +- (d) `cap: a warm model is cheap to return to, a cold one is capped` [r3 #2] — rig + with `usageVar` at 100000: route implement, step → SONNET (served sonnet@100000); + `endTurn`; step on FABLE unrouted → FABLE (served fable@100000, the unrouted write); + `endTurn`; `set(210000)`; route implement, step → SONNET (moved from FABLE: cold read + 110000 ≤ 120000 although the context is 210000); `endTurn`; CONTROL: route judge + (opus, never served, ranks below fable), step → FABLE kept, log contains `downgrade + skipped: cold read 210000 tokens over 120000`. +- (e) `classify: coding moves main to sonnet medium under the cap` (fable, 1000). +- (f) `classify: coding above the cap keeps fable at medium` (fable, 300000). +- (g) `downgrade: switch off keeps today's behavior` (= l.747 re-expressed). +- (h) `classify: a user /effort drops the model guess too` (step effort ≠ engine base → + FABLE at the step's effort, `/route show` agrees: `session defaults`). +- (i) `classify: a design guess never moves a sonnet session up` (= l.4568 renamed). +- (j) `run slot: a model-loaded helper skill moves effort only` (= l.1130 extended). +- (k) `window: haiku outgrown returns main to the session model` (route mechanical on + fable at 1000 → haiku; `set(250000)`; next step → FABLE, log once). +- (l) `config: a quoted "false" mainModelSwitch reads as off with a warning` (`/route + show` contains `switch: off`) [r3 #5]. +- (m) `toast: a downgrade held by the cap says so` (`, held: downgrade skipped: cold + read …`) [r3 #11]. +- (n) `cap: the served record expires after the TTL` (clock advanced 61 min: cold = + whole context, downgrade above cap refused) [r3 #13]. +- (o) `cap: /route reload forgets the served record`; `cap: the skip line is said once + until a downgrade succeeds` (two turns above cap → one line; a downgrade under cap on + a later turn; above cap again → one new line) [r3 #13]. +- (p) `cap: a smaller context than the record is cold` (set(50000) after served@100000 + → downgrade to a never-served model refused only if 50000 > cap; use cap override + `downgradeMaxTokens: 40000` in `home` → refused, entry dropped) [r3 #6]. +- (q) `classify: a mid-turn ultrathink floor still reaches fable max` (classifier coding + → sonnet; mid-turn prompt `ultrathink` → next step FABLE/max) [r3 #4]. +- (r) `classify: a guessed sonnet rate-limited falls to opus, never haiku` (coding → + sonnet; `failWith('rate_limit')` → next step OPUS) [r3 #3]. +- (s) `classify: a user /effort drops the guess for one turn only` (turn 1 engine effort + high = base; turn 2 engine effort low (user /effort) → guess dropped, FABLE; turn 3 + engine effort low → coding guess routes again → SONNET) [r3 #7]. +- Run: `make test suite=lib/tests/mods.test.sh`. + +## Disposition (STEP 0.6) +- honors BDR-115 (one writer per axis, full ids): cap and served record live in + `decideMain`'s path, the only writer of main's model; full ids only. +- honors LRN-204 (cold read per switch INTO a model, warm return): the cap measures + exactly that quantity; no bypass needed. +- supersedes one clause of BDR-116 amendment W4-B ("EFFORT ONLY: main model never + moves on a guess") by user decision 2026-10-13, DOWN only, under the switch and the + cold-read cap; the `/effort` guard stays (route dropped on both axes); the `/model` + guard is NOT kept (baseline moves, guess follows) — stated trade-off for the BDR. +- honors BDR-107 effort rungs: no effort value changes. + +## CHALLENGE SUMMARY (r1 → r2 → r3) +- correctness #1 / simplicity #1 / robustness #4-#6 → cold-read cap + served record, + bypass dropped. correctness #2 / simplicity #3 / robustness #3 → downgrades only. + correctness #3 → claim struck, trade-off surfaced. correctness #4 / simplicity #6 → + full test list, letters aligned. simplicity #2 / correctness #6-#7 / robustness #9 → + drop the guessed route on both axes in `mainPlan`. simplicity #4 → one `coldBlock`. + simplicity #5 → moot. robustness #1 → helper-skill effort-only inside a run. + robustness #2 → window re-check. robustness #7 → pickSwitch. robustness #8 → once per + cap crossing. robustness #10/#11 → accepted residuals (TODO). correctness #9 → + comments + USAGE.md/README to STEP 6. +- Confirmation pass (r2, FATAL(7)): BLOCKER #1 → served written on EVERY main step + (tokens + clock read per step). #2 → test (d) with `endTurn` between legs. #3 → guess + ranked against the session model. #4 → floor model wins over a guess. #5 → fail-closed + switch picker. #6 → stale entry = cold, `served` not kept across /clear. #7 → + per-turn `engineBase`, no `turnModel` reset. #8/#13 → tests added. #9 → slot-sourced + predicate. #10 → window re-check guards. #11 → `why` pinned through `skipped()`. #12 → + `capSaid` in `mainPlan`. #14 → TTL const + TODO. #15 → rank via `resolveRoute`. +- Deferred BLOCKERs: none. Re-challenge budget consumed (1 extra pass); verifier and + security gates follow. diff --git a/CHANGELOG.md b/CHANGELOG.md index 292515e..79c38a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,11 +7,12 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project ## [Unreleased] ### Added -- **model-router mod**: `mods/model-router/`, a Claude Code mod (function-hooks plugin), routes every repo skill and agent from phase rows (`plan`, `reflect`, `orchestrate`, `escalate`, `judge`, `implement`, `write`, `verify`, `explore`, `apply`, `mechanical`; built-ins Explore on sonnet/medium, Plan on opus/xhigh). A typed skill routes the main loop to its row, and a best-tier row holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. Agents get their row's model at spawn (within the tier, upward only) and its effort on every step; explicit Agent params win. Orchestrators declare their phases through the `mcp__model-router__route` tool. `ultrathink` in a prompt sets the turn's minimum effort and `/route effort=max` holds until `/route clear`; the built-in `/effort` is not a lever inside a run. `/route show` names the run slot (`main: run `), and a `null` row in the override drops a default row. The model gets a `route` tool and the user a `/route` command (`show|clear|off|on|reload|pending|ask on|off|forget ||model= effort=|switch on|off|verbose on|off`). Optional per-machine config `~/.claude/model-router.json`, where `"enabled": false` turns it off on that machine. The spinner suffix and the status line show the route in force. It loads in every session through the tracked symlink `skills/model-router` (`model-router@skills-dir`). `make doctor` gains a Mods section; suite `make test suite=lib/tests/mods.test.sh`. Known limits: the main loop switches model only with `mainModelSwitch` on (default off, one cold-cache step per switch into another model), and the hooks send full model ids, so the `models` table has to follow new versions. +- **model-router mod**: `mods/model-router/`, a Claude Code mod (function-hooks plugin), routes every repo skill and agent from phase rows (`plan`, `reflect`, `orchestrate`, `escalate`, `judge`, `implement`, `write`, `verify`, `explore`, `apply`, `mechanical`; built-ins Explore on sonnet/medium, Plan on opus/xhigh). A typed skill routes the main loop to its row, and a best-tier row holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. Agents get their row's model at spawn (within the tier, upward only) and its effort on every step; explicit Agent params win. Orchestrators declare their phases through the `mcp__model-router__route` tool. `ultrathink` in a prompt sets the turn's minimum effort and `/route effort=max` holds until `/route clear`; the built-in `/effort` is not a lever inside a run. `/route show` names the run slot (`main: run `), and a `null` row in the override drops a default row. The model gets a `route` tool and the user a `/route` command (`show|clear|off|on|reload|pending|ask on|off|forget ||model= effort=|switch on|off|verbose on|off`). Optional per-machine config `~/.claude/model-router.json`, where `"enabled": false` turns it off on that machine. The spinner suffix and the status line show the route in force. It loads in every session through the tracked symlink `skills/model-router` (`model-router@skills-dir`). `make doctor` gains a Mods section; suite `make test suite=lib/tests/mods.test.sh`. Known limits: a main-loop switch runs only while the cold read it costs (the context minus what the target model's prompt cache holds) fits `upgradeMaxTokens` (200000) or `downgradeMaxTokens` (120000), and a downgrade also needs `mainModelSwitch` (on by default, off on any non-boolean value); the hooks send full model ids, so the `models` table has to follow new versions. - **model-router first-use confirmation**: `mods/model-router/routing.json` (tracked) is the single source of the phase table and of every skill and agent row, and keeps the decisions: `confirmed`, `changed` (`from`/`to`), `projects` exceptions keyed by the origin remote reduced to `host/path` (credentials and local paths never stored), and `ask`. The first use of a rowed typed skill, a rowed agent spawn or a main-loop phase declared through the `route` tool opens a dialog with context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line (a new field on each of the 11 phases) and the model id and effort the next step really runs on. A row offers Later, Keep or Change; a main-loop phase Later or Keep. Change asks the model (fable, opus, sonnet, haiku with their tier), then the effort among those the phases of that model use (skipped when there is only one), then Everywhere or This project only; the pair maps to an existing phase (rows stay phase names, the same phase counts as Keep, a pair no phase offers is added by hand as a new phase). A skill-row change toasts the model and effort it now runs on, with the `/route switch on` hint when the main loop holds back a downgrade; a free-text answer counts as Later. One dialog at a time, never in headless (`-p`) runs or inside a sub-agent. Only a dialog answer, `/route ask on|off` or `/route forget` (which takes decisions back; a changed row returns to its shipped phase, the frontmatter floors stay yours to realign) writes the file (serialized, 64 KiB cap, never created when absent); each write asks you to commit it from the config repo. `/route pending` lists unconfirmed rows and phases. Layers: routing.json < `~/.claude/model-router.json` (its `ask` wins); a project's `.claude/model-router.json` is never read. Tests: `mods/model-router/hooks/register.test.ts`. - **Manual-push mode**: `git config gitflow.autopush false` (human-set) now stops every push the gitflow lib makes, not only the post-commit / post-merge hooks. `gitflow start` and `finish` branch, commit and merge locally and push nothing; `gitflow delete` leaves the `origin/` copy in place and prints `git push origin --delete
` for the user to run. `hooks/unpushed-guard.sh` stays silent at turn end in this mode and opens each session with one `ℹ manual push mode:` line counting the commits no remote holds across every local branch; an unparseable or unreadable `gitflow.autopush` value is treated as manual push mode too, and that line names it. `hooks/push-guard.sh` (PreToolUse, `Bash|Monitor`) refuses any `git push` Claude types while `gitflow.autopush` reads false in the session cwd or in a literal `-C`/`cd` directory the command names (global config counts outside a repo); the refusal tells the user to run it with `! git push`. It reads the mode through the same lib verb as every other reader and fails closed: an unparseable or unreadable value reads as manual, and an internal error, a missing `lib/gitflow.sh`, more than 20 distinct directory tokens in one command (capped before any token is classified), a `cd`/`-C` directory token mixing quoted and unquoted parts, or a payload jq cannot parse whose raw text looks like a push refuse the push (these pathological cases fire in auto mode too). Directory tokens are read as whole shell words, adjacent quoted segments and backslash escapes included. Once the text looks like a push, the command is split into simple commands (quotes, escapes, separators, heredoc bodies dropped) and a push must be git's own subcommand in one of them: `grep "git push"`, `git log -S "git push"`, `git config --get push.default`, `git stash push`, a heredoc quoting a push or a commit message naming one are allowed; `bash -c` scripts are re-checked, wrappers (`sudo`, `env`, `eval`, `xargs`, `timeout`, `git subtree`...) and assignments keep the text verdict. The misses listed in its header fall to a new `autoMode.soft_deny` rule that no request in the turn clears. The session banner adds `🔒 push : manual (autopush=false) — ! git push` when the key reads false, and `🔒 push : manual (autopush bad) — ! git push` when the value is invalid. Skills read the mode through a new lib verb, `bash ~/.claude/lib/gitflow.sh push-mode`: it prints `auto`, `manual` or `invalid` (rc 0) and names an invalid value on stderr (printable characters only, 64 at most). It is the one reader a skill may call, since the `git config` read of the key is denied to Claude. Skills push nothing on their own, except the `/release-candidate` tag in auto-push mode on an explicit go. Every "on origin" or "not pushed" line they print comes from `git rev-list --count origin/
..
` read after the fact, with the complete `! git …` command when something is left for the user to push. An invalid value (anything but unset, true or false, or a read that fails) is manual push mode for every reader and is named where it is read (see Fixed). Tests: `lib/gitflow-test.sh` T11b (push-mode verb), T18m and T18q blocks, `lib/tests/unpushed-guard.test.sh` T10-T16, `lib/tests/push-guard.test.sh` (98 checks). -- **model-router prompt classifier**: a plain prompt typed in the composer (12 characters or more, not a slash command, not mid-turn, never under `-p` or in a sub-agent) that no keyword rule, skill, run slot, `/route` or floor covers is labelled by one call to the engine's small model (`design`, `analysis`, `coding`, `bookkeeping`, `chat`), bounded to 3 s. The label maps to plan, reflect, implement or apply and that phase's effort becomes the turn's default: effort only, no model move, no dialog, no file write, gone at the end of the turn, replaced by any route call or typed skill, and beaten by a `/effort` you set yourself. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). `"classify": false` in `~/.claude/model-router.json` and `/route classify on|off` turn it off; `/route show` prints `classify:`. The status line reads `route: classifier ` and `/route verbose on` adds `(: classifier)`. +- **model-router prompt classifier**: a plain prompt typed in the composer (12 characters or more, not a slash command, not mid-turn, never under `-p` or in a sub-agent) that no keyword rule, skill, run slot, `/route` or floor covers is labelled by one call to the engine's small model (`design`, `analysis`, `coding`, `bookkeeping`, `chat`), bounded to 3 s. The label maps to plan, reflect, implement or apply and the turn takes that phase's route: its effort, and its model under the switch and the downgrade cap, never above the session model (an `ultrathink` floor keeps its model); no dialog, no file write, gone at the end of the turn, replaced by any route call or typed skill, and dropped for that turn by a `/effort` typed between turns. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). `"classify": false` in `~/.claude/model-router.json` and `/route classify on|off` turn it off; `/route show` prints `classify:`. The status line reads `route: classifier ` and `/route verbose on` adds `(: classifier)`. +- **model-router cold-read caps**: both main-loop caps measure the cold read a switch costs, from a per-model record of main's last step, warm within the engine's prompt-cache TTL (`cache_ttl` 5m or 1h from main's model-switch events, 1 h before the first, kept across `/clear`; records cleared by `/clear` and `/route reload`), plus the submitted prompt the engine's usage may not count yet (code points / 3 of its text, context entries and a typed skill's body, added at the turn's first main step unless usage already grew by half of it; a `document` attachment blocks the switch for that step); `downgradeMaxTokens` (default 120000) joins `upgradeMaxTokens` (200000). A model-loaded helper skill inside a best-tier run moves effort only; main routed onto a model whose window the context outgrew returns to the session model. `/route show` prints `switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`, the status line shows ` · switch off` only when the switch is off, the skip line is logged once per cap crossing and the change toast names a cap hold. A built-in `general-purpose` agent that main spawns with no model while main sits below the session model starts on the session model instead of inheriting the lower one. ### Changed - model-router `verbose: true` logs transitions only: one line when main changes model or effort (`model-router: main: fable/high → fable/xhigh (plan: route tool)`), one hand-off line per dispatch and one per later effort move of an agent, each with its cause; the per-step, "answered by", spawn, route-tool and skill-path lines are gone. An agent answering on a model other than the planned one is said once. A non-boolean `verbose` falls back to `false`, said once. diff --git a/README.md b/README.md index 2f5d0cd..a7944b4 100644 --- a/README.md +++ b/README.md @@ -132,18 +132,18 @@ effort, never version. Transcript audit `python3 lib/effort-audit.py`. `mods/model-router/` is a Claude Code mod (a function-hooks plugin) that applies this table per request. It loads in every session through the tracked symlink `skills/model-router`, as `model-router@skills-dir`. -- Main loop: every request gets the route in force. A typed skill with a row routes the main loop to it; a best-tier row (`plan`, `reflect`, `orchestrate`, `escalate`) holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. A skill without a row leaves the route as it is. -- Sub-agents: a routed agent gets its row's model at spawn, within its tier and only upward from its frontmatter model, and the row's effort on every step. Explicit `model` / `effort` params on the Agent call win; a project-defined agent of the same name keeps its own definition. Built-ins: Explore runs on sonnet/medium, Plan on opus/xhigh. +- Main loop: every request gets the route in force. A typed skill with a row routes the main loop to it; a best-tier row (`plan`, `reflect`, `orchestrate`, `escalate`) holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. A skill without a row leaves the route as it is. A rowed skill the model loads inside a best-tier run moves effort only when its row ranks below the run's model. Main routed onto a model whose context window the conversation outgrew returns to the session model. +- Sub-agents: a routed agent gets its row's model at spawn, within its tier and only upward from its frontmatter model, and the row's effort on every step. Explicit `model` / `effort` params on the Agent call win; a project-defined agent of the same name keeps its own definition. Built-ins: Explore runs on sonnet/medium, Plan on opus/xhigh. A built-in `general-purpose` agent that main spawns with no `model` param, while main runs below the session model (a downgrade or a breaker fallback), starts on the session model instead of inheriting the lower one; it is not pinned when the session model is marked down, for a fork, a workflow or a nested spawn, or when a project or user definition shadows the built-in. Other agent types are never pinned this way: the hook cannot see their frontmatter model. - Levers inside a run: `ultrathink` in a prompt sets the turn's minimum effort; `/route effort=max` holds until `/route clear`. The built-in `/effort` is not a lever inside a run, rows and routes outrank it. -- Prompt classifier: a plain prompt typed in the composer (12 characters or more, not a slash command) that no keyword rule, skill, run slot, `/route` or floor covers is sent to the engine's small fast model, one call, bounded to 3 seconds (the prompt waits for it, typically under a second). The label (`design`, `analysis`, `coding`, `bookkeeping`, `chat`) maps to plan, reflect, implement or apply (`chat` routes nothing), and that phase's effort becomes the turn's default. Effort only: the main model never moves because of a guess, no dialog opens and no file is written. The route is gone at the end of the turn, a later route call or typed skill replaces it, and a `/effort` you set yourself beats it. A typed best-tier skill holds its run slot across turns, so nothing is classified there until `/route clear`. Long prompts are sampled (first 500 and last 1500 code points), so pasted text at the end can steer one turn's effort. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). Never in a sub-agent, mid-turn or under `-p`. Off per session with `/route classify off`, per machine with `"classify": false`. The status line reads `route: classifier `; `/route verbose on` adds the transition line. -- `/route` (user command) shows or sets the route: `show`, `clear`, `off`, `on`, `reload`, `pending` (rows and phases not confirmed yet), `ask on|off` (first-use dialog on or off), `forget ` (takes decisions back: a changed row returns to its shipped phase; `all` and `projects` ask first), a phase name, `model= effort=`, `switch on|off`, `classify on|off` (the prompt classifier, below), `verbose on|off` (logs transitions only: each change of model or effort, with a few words of cause). `/route show` names the run slot when one holds (`main: run `). The model sets routes through a `route` tool. -- First use: the first time a rowed skill is typed, a rowed agent is spawned or a phase is declared on the main loop through the `route` tool, the mod asks once whether the route is right. The question gives context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line, and the model id and effort the next step really runs on; a declared phase also says what uses it (rows, prompt rules). A row offers Later, Keep or Change; a declared phase offers Later or Keep. Change asks the model (fable, opus, sonnet, haiku, each shown with the tier it heads), then the effort among those the phases on that model use (shipped table: fable medium, high, xhigh or max; sonnet low, medium, high or xhigh; opus and haiku have one level each, so no question), then Everywhere or This project only. Rows stay phase names, so the pair maps to an existing phase: the row's current phase wins a tie and the same phase counts as Keep; a pair no phase offers needs a new phase added by hand in routing.json. Everywhere moves the row and records the shipped phase under `changed`; This project only stores an exception under `projects`, keyed by the origin remote reduced to `host/path` (no credentials, no local paths; a remote that cannot be read that way offers no project choice). Keep lands under `confirmed`; Later, a dismissed dialog or a free-text answer asks again next session. After a skill row changes, a toast names the model and effort that skill now runs on, plus the `/route switch on` hint when the main loop holds back a downgrade. One dialog at a time, never in a headless (`-p`) run, never inside a sub-agent. +- Prompt classifier: a plain prompt typed in the composer (12 characters or more, not a slash command) that no keyword rule, skill, run slot, `/route` or floor covers is sent to the engine's small fast model, one call, bounded to 3 seconds (the prompt waits for it, typically under a second). The label (`design`, `analysis`, `coding`, `bookkeeping`, `chat`) maps to plan, reflect, implement or apply (`chat` routes nothing), and the turn takes that phase's route: its effort becomes the turn's default, and its model may move the main loop, never above the session model. A `coding` or `bookkeeping` guess moves main down only when `mainModelSwitch` is on and the cold read fits `downgradeMaxTokens`; an `ultrathink` floor in the same turn keeps its own model. No dialog opens and no file is written. The route is gone at the end of the turn, a later route call or typed skill replaces it, and a `/effort` you type between turns drops the guess for that turn only. A typed best-tier skill holds its run slot across turns, so nothing is classified there until `/route clear`. Long prompts are sampled (first 500 and last 1500 code points), so pasted text at the end can steer one turn's route. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). Never in a sub-agent, mid-turn or under `-p`. Off per session with `/route classify off`, per machine with `"classify": false`. The status line reads `route: classifier `; `/route verbose on` adds the transition line. +- `/route` (user command) shows or sets the route: `show`, `clear`, `off`, `on`, `reload`, `pending` (rows and phases not confirmed yet), `ask on|off` (first-use dialog on or off), `forget ` (takes decisions back: a changed row returns to its shipped phase; `all` and `projects` ask first), a phase name, `model= effort=`, `switch on|off`, `classify on|off` (the prompt classifier, below), `verbose on|off` (logs transitions only: each change of model or effort, with a few words of cause). `/route show` names the run slot when one holds (`main: run `) and prints the switch with its cap and the prompt-cache TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). The model sets routes through a `route` tool. +- First use: the first time a rowed skill is typed, a rowed agent is spawned or a phase is declared on the main loop through the `route` tool, the mod asks once whether the route is right. The question gives context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line, and the model id and effort the next step really runs on; a declared phase also says what uses it (rows, prompt rules). A row offers Later, Keep or Change; a declared phase offers Later or Keep. Change asks the model (fable, opus, sonnet, haiku, each shown with the tier it heads), then the effort among those the phases on that model use (shipped table: fable medium, high, xhigh or max; sonnet low, medium, high or xhigh; opus and haiku have one level each, so no question), then Everywhere or This project only. Rows stay phase names, so the pair maps to an existing phase: the row's current phase wins a tie and the same phase counts as Keep; a pair no phase offers needs a new phase added by hand in routing.json. Everywhere moves the row and records the shipped phase under `changed`; This project only stores an exception under `projects`, keyed by the origin remote reduced to `host/path` (no credentials, no local paths; a remote that cannot be read that way offers no project choice). Keep lands under `confirmed`; Later, a dismissed dialog or a free-text answer asks again next session. After a skill row changes, a toast names the model and effort that skill now runs on, plus a hint when the main loop holds back a downgrade: `/route switch on` when the switch is off, the cap hold (`held: downgrade skipped: cold read tokens over `) when the cold read is over `downgradeMaxTokens`. One dialog at a time, never in a headless (`-p`) run, never inside a sub-agent. - Only a dialog answer, `/route ask on|off` or `/route forget` writes `routing.json`, never the model. Writes are serialized, capped at 64 KiB, and refused when the file is missing (it is never created). Each write leaves the config repo dirty; a toast reminds you to commit it from there. -- The spinner suffix and the status line under the prompt show the route in force. +- The spinner suffix and the status line under the prompt show the route in force; the status line adds ` · switch off` when the downgrade switch is off. -Config layers: `mods/model-router/routing.json` (tracked: phases with their tier, effort and `about` line, rows, decisions, `ask`), then the optional per-machine `~/.claude/model-router.json`, which wins. A `.claude/model-router.json` inside a project is never read. Machine keys: `models` (alias → full id), `windows` (context window per full id), `tiers` (ordered alias lists per tier: `best` fable>opus>sonnet, `big` opus>fable>sonnet, `work` sonnet>opus, `cheap` haiku>sonnet; the first alias not down is used), `fallback` (the rank order of the aliases, best first, used by the breaker), `cooldownMinutes` (how long a model stays marked down after an availability error, 15 by default, doubling per episode up to 300), `mainUpgrade` (default `true`: the main loop may move up to a phase's tier), `upgradeMaxTokens` (default 200000: no main-loop upgrade above this context size, since an upgrade re-reads the whole context cold), `phases`, `agents`, `skills`, `prompt` (rules), `mainModelSwitch` (default `false`), `classify` (default `true`; `false` stops the prompt classifier on that machine), `verbose` (default `false`; `true` logs transitions only, a non-boolean value falls back to `false`), `spinner` (default `true`), `enabled` (default `true`; `false` turns the mod off on that machine), `ask` (overrides routing.json's `ask` on that machine). A `null` value in `agents` or `skills` drops a row. Edit phases and rows by hand in routing.json (a phase's `about`, 120 characters at most, is read from there only and shown in the dialog; a model and effort pair no phase offers needs a new phase there); without it the mod runs the code's default phases, with no rows and no dialog. `/route reload` re-reads both files. +Config layers: `mods/model-router/routing.json` (tracked: phases with their tier, effort and `about` line, rows, decisions, `ask`), then the optional per-machine `~/.claude/model-router.json`, which wins. A `.claude/model-router.json` inside a project is never read. Machine keys: `models` (alias → full id), `windows` (context window per full id), `tiers` (ordered alias lists per tier: `best` fable>opus>sonnet, `big` opus>fable>sonnet, `work` sonnet>opus, `cheap` haiku>sonnet; the first alias not down is used), `fallback` (the rank order of the aliases, best first, used by the breaker), `cooldownMinutes` (how long a model stays marked down after an availability error, 15 by default, doubling per episode up to 300), `mainUpgrade` (default `true`: the main loop may move up to a phase's tier), `upgradeMaxTokens` (default 200000: the largest cold read a main-loop upgrade may cost), `downgradeMaxTokens` (default 120000: the same cap for a downgrade; the cold read is the context minus what the target model's prompt cache already holds, taken from main's last step on that model within the prompt-cache TTL, forgotten by `/clear` and `/route reload`. The TTL follows the engine's `cache_ttl` (5 or 60 minutes) carried by main's model-switch events, is 60 minutes until the first one and survives `/clear`. The context also counts the prompt just submitted, which the engine's usage may not include yet: code points / 3 of its text, its context entries and a typed skill's body, summed and added at the turn's first main step unless usage already grew by half of it. A `document` attachment makes the size unknown, and an unknown context size blocks the switch; the step, `/route show`, the first-use dialog and the toast read the same adjusted size), `phases`, `agents`, `skills`, `prompt` (rules), `mainModelSwitch` (default `true`: the main loop may move down to a cheaper model; a value that is not a boolean turns it off and says so), `classify` (default `true`; `false` stops the prompt classifier on that machine), `verbose` (default `false`; `true` logs transitions only, a non-boolean value falls back to `false`), `spinner` (default `true`), `enabled` (default `true`; `false` turns the mod off on that machine), `ask` (overrides routing.json's `ask` on that machine). A `null` value in `agents` or `skills` drops a row. Edit phases and rows by hand in routing.json (a phase's `about`, 120 characters at most, is read from there only and shown in the dialog; a model and effort pair no phase offers needs a new phase there); without it the mod runs the code's default phases, with no rows and no dialog. `/route reload` re-reads both files. -Limits: the main loop changes model only with `mainModelSwitch` on, and each switch into another model costs one cold-cache step. The hooks send full model ids, so the `models` table has to follow new model versions. +Limits: a main-loop switch re-reads cold the part of the context the target model's cache does not hold; a switch whose cold read is over its cap (`upgradeMaxTokens` up, `downgradeMaxTokens` down) is skipped and main keeps its model, and a downgrade also needs `mainModelSwitch`. The prompt estimate is conservative (3 code points per token), so a long pasted prompt can hold back a switch that would have fit. The hooks send full model ids, so the `models` table has to follow new model versions. --- diff --git a/USAGE.md b/USAGE.md index 8a92314..553fb0c 100644 --- a/USAGE.md +++ b/USAGE.md @@ -187,7 +187,7 @@ l'outil `mcp__model-router__route` (`lib/effort-shift.md`). Les skills externes vendorés (pile design, superpowers, agent-skills, skills scroll MengTo, 21st) ont aussi leur ligne. -Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou un skill d'un autre tier tapé. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : son niveau d'effort devient celui du tour, sans jamais changer de modèle ; `/route classify off` ou `"classify": false` dans la config machine le coupe, et ton propre `/effort` passe devant. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. `/route show` affiche la route en cours, slot de run compris (`main: run `). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (fable, opus, sonnet, haiku, chacun avec son tier), puis le niveau parmi ceux des phases de ce modèle (fable : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; opus et haiku n'en ont qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand la boucle principale refuse de descendre. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget ` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). +Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou un skill d'un autre tier tapé. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. Un agent intégré `general-purpose` lancé par la boucle principale sans `model`, pendant que celle-ci tourne sous le modèle de la session (descente, ou repli quand un modèle est en panne), part sur le modèle de la session au lieu d'hériter du modèle inférieur ; les autres types d'agents ne sont jamais épinglés ainsi. `/route show` affiche la route en cours, slot de run compris (`main: run `), et le switch avec son plafond et ce TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (fable, opus, sonnet, haiku, chacun avec son tier), puis le niveau parmi ceux des phases de ce modèle (fable : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; opus et haiku n'en ont qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand le switch est coupé, ou nomme le plafond quand la relecture à froid bloque la descente. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget ` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). La config par machine, optionnelle, vit dans `~/.claude/model-router.json` et passe devant `routing.json` ; `"enabled": false` y coupe le mod sur cette machine, `"ask": false` y coupe le dialogue, une ligne à `null` y retire une ligne. Un `.claude/model-router.json` dans un projet n'est jamais lu. Les phases et les lignes se modifient à la main dans `routing.json` ; `/route reload` relit les deux fichiers. diff --git a/lib/effort-shift.md b/lib/effort-shift.md index 8d22876..cd953d0 100644 --- a/lib/effort-shift.md +++ b/lib/effort-shift.md @@ -47,8 +47,12 @@ Builtin `/effort` is NOT a lever inside a run: rows and routes outrank it. - A skill typed while a background agent is live routes only through the typed marker (unverified live 2026-10-10). - Headless (`-p`, SDK) runs the hooks, so routing works there too. -- A plain typed prompt with no route in force gets its turn effort from a - small-model classifier (effort only; `/route classify off`; never `-p`). +- A plain typed prompt with no route in force is classified by a small + model: the guessed phase sets the turn's effort and, under + `mainModelSwitch` and `downgradeMaxTokens` (max cold read, default + 120000), may move main DOWN, never up. A user `/model` only moves the + baseline the guess starts from (`/route classify off` to stop guessing; + never `-p`). - Mod off: typed agents fall back to their `model:`/`effort:` frontmatter. - First use of a row asks once, with context (Later, Keep or Change: model, then effort, then Everywhere or this project only); the answer is kept in diff --git a/mods/model-router/hooks/register.test.ts b/mods/model-router/hooks/register.test.ts index b84a276..288b664 100644 --- a/mods/model-router/hooks/register.test.ts +++ b/mods/model-router/hooks/register.test.ts @@ -307,6 +307,7 @@ test('ultrathink in a prompt sets a max floor on main', async ($, on) => { test('/route model: alias resolved, id passed, typo refused', async ( $, on) => { await boot($, on) + await route($, 'switch off') const alias = await route($, 'model=sonnet') expect(mainLine(alias)).toContain('asked claude-sonnet-5-5, keeps ') const id = await route($, 'model=claude-x-9') @@ -606,11 +607,11 @@ test('reload with an unreadable override keeps the previous config', async ( $, on) => { const world = newWorld({ home: {} }) await boot($, on, FABLE, 1000, world) - await route($, 'switch on') + await route($, 'switch off') world.files.set(HOME_FILE, '{nope') const out = await route($, 'reload') - expect(out).toContain('switch: on') - expect(await route($, 'show')).toContain('switch: on') + expect(out).toContain('switch: off') + expect(await route($, 'show')).toContain('switch: off') }) // ---- tiers, breaker, derived phases ------------------------------------- @@ -666,6 +667,8 @@ const switchTo = ( from: string, to: string, source: 'command' | 'auto', + cache_ttl: '5m' | '1h' = '5m', + agent_id?: string, ) => $.classic.PostModelSwitch({ from_model: from, to_model: to, @@ -673,7 +676,8 @@ const switchTo = ( source, context_tokens: 0, prompt_cache_warm: false, - cache_ttl: '5m', + cache_ttl, + ...(agent_id === undefined ? {} : { agent_id }), estimated_cache_write_usd: 0, pricing: 'catalog', }) @@ -681,8 +685,9 @@ const switchTo = ( const planRoute = ($: Engine) => $.tool.call({ tool: ROUTE_TOOL, phase: 'plan' }) -/** A bottom `session.usage` answering a context of `tokens`. */ -function usageOf(on: On, tokens: number): void { +/** One bottom `session.usage` over a count `set` changes (never a second). */ +function usageVar(on: On, initial: number): { set: (n: number) => void } { + let tokens = initial on('session.usage', () => ({ value: { startedAt: 0, @@ -690,6 +695,24 @@ function usageOf(on: On, tokens: number): void { rateLimits: [], }, })) + return { set: n => { tokens = n } } +} + +/** A bottom `session.usage` answering a context of `tokens`. */ +function usageOf(on: On, tokens: number): void { + usageVar(on, tokens) +} + +/** bootRig with a context size the test changes through `usage.set`. */ +async function bootRigVar( + $: Engine, + on: On, + model: string = FABLE, + tokens = 1000, + world: World = newWorld(), +) { + const usage = usageVar(on, tokens) + return { rig: await bootRig($, on, model, null, world), usage } } test('tier: a plan route upgrades a haiku session to fable xhigh', async ( @@ -747,14 +770,14 @@ test('breaker: model_not_found on a non-table id marks nothing', async ( test('downgrade: mechanical on fable keeps the model, switch off', async ( $, on) => { const rig = await bootRig($, on) + await route($, 'switch off') await $.tool.call({ tool: ROUTE_TOOL, phase: 'mechanical' }) expect(await stepOn($, rig, FABLE)).toEqual({ model: FABLE, effort: 'low' }) }) -test('downgrade: the switch on moves main to the cheap tier', async ( +test('cap: a downgrade under the cold-read cap moves main', async ( $, on) => { const rig = await bootRig($, on) - await route($, 'switch on') await $.tool.call({ tool: ROUTE_TOOL, phase: 'mechanical' }) const sent = await stepOn($, rig, FABLE) expect(sent.model).toBe(HAIKU) @@ -954,6 +977,7 @@ test('text: show names the session model after the turn ended', async ( test('text: show reflects a /model command to opus', async ($, on) => { const rig = await bootRig($, on) + await route($, 'switch off') await stepOn($, rig, FABLE) await switchTo($, FABLE, OPUS, 'command') await route($, 'mechanical') @@ -999,11 +1023,12 @@ async function bootRun( on: On, model: string = FABLE, world: World = newWorld(), + tokens: number | null = 1000, ) { on('tool.call', { tool: 'Skill' }, () => ({ result: { success: true, commandName: 'bottom' }, })) - return bootRig($, on, model, 1000, world) + return bootRig($, on, model, tokens, world) } const spawnOf = (agent: string, extra: object = {}) => @@ -1127,11 +1152,13 @@ test('run slot: survives route calls and the turn end', async ($, on) => { expect(mainLine(await route($, 'show'))).toContain('run reflect') }) -test('run slot: a model-loaded helper skill keeps it', async ($, on) => { - await bootRun($, on) +test('run slot: a model-loaded helper skill moves effort only', async ( + $, on) => { + const rig = await bootRun($, on) await loadSkill($, 'feat') await loadSkill($, 'using-git-worktrees') expect(mainLine(await route($, 'show'))).toContain('skill mechanical') + expect(await stepOn($, rig, FABLE)).toEqual({ model: FABLE, effort: 'low' }) await endTurn($) expect(mainLine(await route($, 'show'))).toContain('run reflect') }) @@ -1664,10 +1691,10 @@ test('layers: routing.json missing at start logs once, no rows', async ( test('layers: session toggles survive a rebuild', async ($, on) => { await bootRun($, on) - await route($, 'switch on') + await route($, 'switch off') await route($, 'verbose on') const out = await route($, 'reload') - expect(out).toContain('switch: on') + expect(out).toContain('switch: off') expect(out).toContain('verbose: on') }) @@ -2936,6 +2963,7 @@ test('change: a downgrade names the real route and the switch', async ( const toasts = recordToasts(on) const w = asks([...TO_IMPLEMENT, 'Everywhere']) await bootRun($, on, FABLE, w) + await route($, 'switch off') await typeFeat($) expect((routingOf(w).skills as Rec).feat).toBe('implement') expect(toasts).toContain('/feat now runs claude-fable-5-1 at medium, ' + @@ -3692,7 +3720,6 @@ test('logs: an upgrade rides on the same line', async ($, on) => { test('logs: a downgrade is a switch', async ($, on) => { const { logs } = await bootLogged($, on) - await route($, 'switch on') await route($, 'mechanical') await runStep($, highStep()) expect(logs).toEqual([ @@ -4431,6 +4458,7 @@ type ClsOpts = { model?: string world?: World verbose?: boolean + tokens?: number // context size the usage hook answers (default 1000) } const PLAIN = 'refactor the billing module please' @@ -4473,7 +4501,7 @@ async function bootCls($: Engine, on: On, o: ClsOpts = {}): Promise { return { value: await (o.reply ?? (() => 'coding'))(asks.length) } }) const world = o.world ?? newWorld() - const clock = await boot($, on, o.model ?? FABLE, 1000, world) + const clock = await boot($, on, o.model ?? FABLE, o.tokens ?? 1000, world) if (o.verbose) await route($, 'verbose on') logs.splice(0) return { asks, seen, clock, logs, toasts, status, world } @@ -4565,7 +4593,7 @@ test('classify: an unknown label neither warns nor counts', async ($, on) => { expect(c.logs).toEqual([]) }) -test('classify: the main model never moves for a design guess', async ( +test('classify: a design guess never moves a sonnet session up', async ( $, on) => { const c = await bootCls($, on, { model: SONNET, reply: () => 'design' }) await typed($, PLAIN) @@ -4573,12 +4601,12 @@ test('classify: the main model never moves for a design guess', async ( expect(c.seen[c.seen.length - 1]).toEqual({ model: SONNET, effort: 'xhigh' }) }) -test('classify: the route carries no tier', async ($, on) => { +test('classify: the route carries the tier', async ($, on) => { const c = await bootCls($, on, { reply: () => 'design' }) await typed($, PLAIN) const line = mainLine(await route($, 'show')) expect(line).toContain('classifier plan') - expect(line).not.toContain('[tier') + expect(line).toContain('[tier best]') expect(c.asks).toHaveLength(1) }) @@ -4609,6 +4637,7 @@ test('classify: a user /effort change beats the guessed effort', async ( $, on) => { const c = await bootCls($, on, { reply: () => 'design' }) await runStep($, highStep()) + await endTurn($) await typed($, PLAIN) await runStep($, { ...highStep(), effort: 'low' as const }) expect(c.seen[c.seen.length - 1]?.effort).toBe('low') @@ -4617,6 +4646,7 @@ test('classify: a user /effort change beats the guessed effort', async ( test('classify: the baseline survives /clear', async ($, on) => { const c = await bootCls($, on, { reply: () => 'design' }) await runStep($, highStep()) + await endTurn($) await clearSession($) await typed($, PLAIN) await runStep($, { ...highStep(), effort: 'low' as const }) @@ -4789,6 +4819,7 @@ test('classify guard: a route landing during the call wins', async ( const c = await bootCls($, on, { reply: async () => { await gate; return 'design' }, }) + await route($, 'switch off') const pending = typed($, PLAIN) await c.clock.settle() await $.tool.call({ tool: ROUTE_TOOL, phase: 'mechanical' }) @@ -5031,3 +5062,430 @@ test('classify: /route advertises classify on|off in its hint', async ( await bootCls($, on) expect(hints.join('\n')).toContain('classify on|off') }) + +// ---- downgrade cap: the cold read ------------------------------------------- + +const logsWith = (logs: string[], text: string): number => + logs.filter(l => l.includes(text)).length + +const SKIP = 'downgrade skipped' + +test('cap: a downgrade above the cold-read cap keeps main', async ($, on) => { + const logs = recordLogs(on) + const rig = await bootRig($, on, FABLE, 300000) + await $.tool.call({ tool: ROUTE_TOOL, phase: 'mechanical' }) + expect(await stepOn($, rig, FABLE)).toEqual({ model: FABLE, effort: 'low' }) + await stepOn($, rig, FABLE) + expect(logsWith(logs, `${SKIP}: cold read 300000 tokens over 120000`)) + .toBe(1) +}) + +test('cap: unknown usage blocks the downgrade', async ($, on) => { + const logs = recordLogs(on) + const rig = await bootRig($, on, FABLE, null) + await $.tool.call({ tool: ROUTE_TOOL, phase: 'mechanical' }) + expect((await stepOn($, rig, FABLE)).model).toBe(FABLE) + expect(logsWith(logs, `${SKIP}: context size unknown`)).toBe(1) +}) + +test('cap: a user downgradeMaxTokens overrides the default', async ( + $, on) => { + const world = newWorld({ home: { downgradeMaxTokens: 500 } }) + const rig = await bootRig($, on, FABLE, 1000, world) + await $.tool.call({ tool: ROUTE_TOOL, phase: 'mechanical' }) + expect((await stepOn($, rig, FABLE)).model).toBe(FABLE) +}) + +/** Routes `phase` and steps once on FABLE; the model that was sent. */ +async function routedStep($: Engine, rig: Rig, phase: string) { + await $.tool.call({ tool: ROUTE_TOOL, phase }) + return (await stepOn($, rig, FABLE)).model +} + +test('cap: a warm model is cheap to return to, a cold one is capped', async ( + $, on) => { + const logs = recordLogs(on) + const { rig, usage } = await bootRigVar($, on, FABLE, 100000) + expect(await routedStep($, rig, 'implement')).toBe(SONNET) + await endTurn($) + expect((await stepOn($, rig, FABLE)).model).toBe(FABLE) + await endTurn($) + usage.set(210000) + expect(await routedStep($, rig, 'implement')).toBe(SONNET) + await endTurn($) + // control: opus never served, the same context is a cold read of 210000 + expect(await routedStep($, rig, 'judge')).toBe(FABLE) + expect(logsWith(logs, `${SKIP}: cold read 210000 tokens over 120000`)) + .toBe(1) +}) + +test('cap: the served record expires after the TTL', async ($, on) => { + const { rig, usage } = await bootRigVar($, on, FABLE, 100000) + await routedStep($, rig, 'implement') + await endTurn($) + await stepOn($, rig, FABLE) + await endTurn($) + usage.set(210000) + await rig.clock.advance(61 * 60000) + expect(await routedStep($, rig, 'implement')).toBe(FABLE) +}) + +test('cap: /route reload forgets the served record', async ($, on) => { + const { rig, usage } = await bootRigVar($, on, FABLE, 100000) + await routedStep($, rig, 'implement') + await endTurn($) + await stepOn($, rig, FABLE) + await endTurn($) + usage.set(210000) + await route($, 'reload') + expect(await routedStep($, rig, 'implement')).toBe(FABLE) +}) + +test('cap: the skip line is said once until a downgrade succeeds', async ( + $, on) => { + const logs = recordLogs(on) + const { rig, usage } = await bootRigVar($, on, FABLE, 300000) + for (let turn = 0; turn < 2; turn++) { + await routedStep($, rig, 'mechanical') + await endTurn($) + } + expect(logsWith(logs, SKIP)).toBe(1) + usage.set(1000) + expect(await routedStep($, rig, 'mechanical')).toBe(HAIKU) + await endTurn($) + usage.set(300000) + expect(await routedStep($, rig, 'mechanical')).toBe(FABLE) + expect(logsWith(logs, SKIP)).toBe(2) +}) + +test('cap: a smaller context than the record is cold', async ($, on) => { + const world = newWorld({ home: { downgradeMaxTokens: 40000 } }) + const { rig, usage } = await bootRigVar($, on, SONNET, 100000, world) + await stepOn($, rig, SONNET) + await endTurn($) + await switchTo($, SONNET, FABLE, 'command') + usage.set(50000) + expect(await routedStep($, rig, 'implement')).toBe(FABLE) +}) + +test('window: haiku outgrown returns main to the session model', async ( + $, on) => { + const logs = recordLogs(on) + const { rig, usage } = await bootRigVar($, on, FABLE, 1000) + expect(await routedStep($, rig, 'mechanical')).toBe(HAIKU) + usage.set(250000) + expect((await stepOn($, rig, FABLE)).model).toBe(FABLE) + await stepOn($, rig, FABLE) + expect(logsWith(logs, 'context outgrew')).toBe(1) +}) + +test('config: a quoted "false" mainModelSwitch reads as off with a warning', + async ($, on) => { + const logs = recordLogs(on) + const world = newWorld({ home: { mainModelSwitch: 'false' } }) + await boot($, on, FABLE, 1000, world) + expect(await route($, 'show')).toContain('switch: off (downgrade)') + expect(logsWith(logs, 'mainModelSwitch" is not a boolean')).toBe(1) + }) + +test('text: show names the switch and its cap', async ($, on) => { + await boot($, on) + expect(await route($, 'show')).toContain( + 'switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)') +}) + +test('status: the switch shows only when off', async ($, on) => { + const c = await bootCls($, on) + await route($, 'classify off') + expect(c.status[c.status.length - 1]).not.toContain('switch') + await route($, 'switch off') + expect(c.status[c.status.length - 1]).toContain(' · switch off') +}) + +test('toast: a downgrade held by the cap says so', async ($, on) => { + const toasts = recordToasts(on) + const w = asks([...TO_IMPLEMENT, 'Everywhere']) + await bootRun($, on, FABLE, w, 300000) + await typeFeat($) + expect(toasts).toContain('/feat now runs claude-fable-5-1 at medium, ' + + `held: ${SKIP}: cold read 300007 tokens over 120000`) +}) + +// ---- downgrade cap: the classifier's model axis --------------------------- + +const lastSeen = (c: Cls): Seen | undefined => c.seen[c.seen.length - 1] + +test('classify: coding moves main to sonnet medium under the cap', async ( + $, on) => { + const c = await bootCls($, on) + await typed($, PLAIN) + await runStep($, highStep()) + expect(lastSeen(c)).toEqual({ model: SONNET, effort: 'medium' }) +}) + +test('classify: coding above the cap keeps fable at medium', async ( + $, on) => { + const c = await bootCls($, on, { tokens: 300000 }) + await typed($, PLAIN) + await runStep($, highStep()) + expect(lastSeen(c)).toEqual({ model: FABLE, effort: 'medium' }) +}) + +test('classify: a user /effort drops the model guess too', async ($, on) => { + const c = await bootCls($, on) + await runStep($, highStep()) + await endTurn($) + await typed($, PLAIN) + await runStep($, { ...highStep(), effort: 'low' as const }) + expect(lastSeen(c)).toEqual({ model: FABLE, effort: 'low' }) + expect(mainLine(await route($, 'show'))).toContain('session defaults') +}) + +test('classify: a user /effort drops the guess for one turn only', async ( + $, on) => { + const c = await bootCls($, on) + await runStep($, highStep()) + await endTurn($) + const low = { ...highStep(), effort: 'low' as const } + await typed($, PLAIN) + await runStep($, low) + expect(lastSeen(c)).toEqual({ model: FABLE, effort: 'low' }) + await endTurn($) + await typed($, PLAIN) + await runStep($, low) + expect(lastSeen(c)).toEqual({ model: SONNET, effort: 'medium' }) +}) + +test('classify: a mid-turn ultrathink floor still reaches fable max', async ( + $, on) => { + const c = await bootCls($, on) + await typed($, PLAIN) + await runStep($, highStep()) + expect(lastSeen(c)?.model).toBe(SONNET) + await queued($, 'composer', 'ultrathink please') + await runStep($, highStep()) + expect(lastSeen(c)).toEqual({ model: FABLE, effort: 'max' }) +}) + +test('classify: a guessed sonnet rate-limited falls to opus, not haiku', async ( + $, on) => { + const c = await bootCls($, on) + await typed($, PLAIN) + await runStep($, highStep()) + expect(lastSeen(c)?.model).toBe(SONNET) + await failWith($, 'rate_limit') + await runStep($, highStep()) + expect(lastSeen(c)?.model).toBe(OPUS) +}) + +// ---- cap residuals: session pin, prompt estimate, engine TTL --------------- + +const GP = 'general-purpose' + +/** A demoted main (fable session, mechanical route on haiku) + spawn rig. */ +async function demotedRig($: Engine, on: On, source = 'built-in') { + const { rig } = await bootRigVar($, on, FABLE, 1000) + await offerOf($, GP, source) + expect(await routedStep($, rig, 'mechanical')).toBe(HAIKU) + return rig +} + +test('spawn: general-purpose during a demoted turn starts on the session model', + async ($, on) => { + const logs = recordLogs(on) + const rig = await demotedRig($, on) + await route($, 'verbose on') + await $.agent.spawn(spawnOf(GP, { parentModel: HAIKU })) + expect(rig.specs).toEqual([FABLE]) + expect(logsWith(logs, `agent ${GP}`)).toBe(1) + expect(logsWith(logs, '(session, engine)')).toBe(1) + }) + +test('spawn: no route in force leaves general-purpose untouched', async ( + $, on) => { + const { rig } = await bootRigVar($, on, FABLE, 1000) + await offerOf($, GP, 'built-in') + await $.agent.spawn(spawnOf(GP, { parentModel: FABLE })) + expect(rig.specs).toEqual([undefined]) +}) + +test('spawn: a rowed agent keeps its row during a demoted turn', async ( + $, on) => { + const rig = await demotedRig($, on) + await $.agent.spawn(spawnOf('feater', { parentModel: HAIKU })) + expect(rig.specs).toEqual([SONNET]) +}) + +test('spawn: a fork during a demoted turn is untouched', async ($, on) => { + const rig = await demotedRig($, on) + await $.agent.spawn(spawnOf(GP, { parentModel: HAIKU, fork: true })) + expect(rig.specs).toEqual([undefined]) +}) + +test('spawn: a nested spawn during a demoted turn is untouched', async ( + $, on) => { + const rig = await demotedRig($, on) + await $.agent.spawn(spawnOf(GP, { parentModel: HAIKU, parentAgentId: 'a1' })) + expect(rig.specs).toEqual([undefined]) +}) + +test('spawn: a type outside the allowlist is untouched', async ($, on) => { + const rig = await demotedRig($, on) + await offerOf($, 'code-explorer', 'built-in') + await $.agent.spawn(spawnOf('code-explorer', { parentModel: HAIKU })) + expect(rig.specs).toEqual([undefined]) +}) + +test('spawn: an upgraded main never pins general-purpose', async ($, on) => { + const { rig } = await bootRigVar($, on, HAIKU, 1000) + await offerOf($, GP, 'built-in') + await planRoute($) + expect((await stepOn($, rig, HAIKU)).model).toBe(FABLE) + await $.agent.spawn(spawnOf(GP, { parentModel: FABLE })) + expect(rig.specs).toEqual([undefined]) +}) + +test('spawn: a shadowed general-purpose is never pinned', async ($, on) => { + const rig = await demotedRig($, on, 'projectSettings') + await $.agent.spawn(spawnOf(GP, { parentModel: HAIKU })) + expect(rig.specs).toEqual([undefined]) +}) + +const longText = (points: number) => 'x'.repeat(points) + +/** Cap 110000, classifier off, a context of `tokens`; estimates need both. */ +function estimateRig($: Engine, on: On, tokens: number) { + const home = { classify: false, downgradeMaxTokens: 110000 } + return bootRigVar($, on, FABLE, tokens, newWorld({ home })) +} + +test('cap: a pasted prompt counts before the first step', async ($, on) => { + const logs = recordLogs(on) + const { rig } = await estimateRig($, on, 100000) + await typed($, longText(60000)) + expect(await routedStep($, rig, 'implement')).toBe(FABLE) + expect(logsWith(logs, `${SKIP}: cold read 120000 tokens over 110000`)) + .toBe(1) +}) + +test('cap: the estimate is skipped once usage counted the prompt', async ( + $, on) => { + const first = await estimateRig($, on, 100000) + await typed($, longText(60000)) + first.usage.set(110000) + expect(await routedStep($, first.rig, 'implement')).toBe(SONNET) +}) + +test('cap: usage growth under half the estimate still adds it', async ( + $, on) => { + const logs = recordLogs(on) + const { rig, usage } = await estimateRig($, on, 100000) + await typed($, longText(60000)) + usage.set(109999) + expect(await routedStep($, rig, 'implement')).toBe(FABLE) + expect(logsWith(logs, 'cold read 129999 tokens over 110000')).toBe(1) +}) + +test('cap: the first main step consumes the estimate', async ($, on) => { + const { rig } = await estimateRig($, on, 100000) + await typed($, longText(60000)) + expect(await routedStep($, rig, 'implement')).toBe(FABLE) + expect((await stepOn($, rig, FABLE)).model).toBe(SONNET) +}) + +test('cap: a mid-turn prompt is counted at the next turn first step', async ( + $, on) => { + const { rig } = await estimateRig($, on, 100000) + await queued($, 'composer', longText(60000)) + await endTurn($) + expect(await routedStep($, rig, 'implement')).toBe(FABLE) +}) + +test('cap: an estimate no step consumed is carried over the turn end', async ( + $, on) => { + const { rig } = await estimateRig($, on, 100000) + await typed($, longText(60000)) + await endTurn($) + expect(await routedStep($, rig, 'implement')).toBe(FABLE) +}) + +test('cap: a document attachment blocks the first step switch', async ( + $, on) => { + const logs = recordLogs(on) + const { rig } = await estimateRig($, on, 1000) + await $.prompt.submit({ + text: 'see the file', + wait: false, + origin: { kind: 'composer' }, + attachments: [{ type: 'document' }], + }) + expect(await routedStep($, rig, 'implement')).toBe(FABLE) + expect(logsWith(logs, `${SKIP}: context size unknown`)).toBe(1) + expect((await stepOn($, rig, FABLE)).model).toBe(SONNET) +}) + +test('cap: a typed skill body counts', async ($, on) => { + const { rig } = await estimateRig($, on, 100000) + await typed($, '/analyze') + await $.skill.prompt({ skill: 'analyze', text: longText(60000) }) + expect(await routedStep($, rig, 'implement')).toBe(FABLE) +}) + +test('cap: a preload during a live spawn adds nothing', async ($, on) => { + const { rig } = await estimateRig($, on, 100000) + await typed($, 'hello') + await $.agent.spawn(spawnOf('feater')) + await $.skill.prompt({ skill: 'analyze', text: longText(60000) }) + expect(await routedStep($, rig, 'implement')).toBe(SONNET) +}) + +/** A sonnet record of 100000 tokens, then `age` min later a 210000 context. */ +async function ttlCase($: Engine, on: On, ttl: '5m' | '1h', age: number) { + const { rig, usage } = await bootRigVar($, on, FABLE, 100000) + await switchTo($, FABLE, FABLE, 'command', ttl) + await routedStep($, rig, 'implement') + await endTurn($) + await stepOn($, rig, FABLE) + await endTurn($) + usage.set(210000) + await rig.clock.advance(age * 60000) + return routedStep($, rig, 'implement') +} + +test('ttl: the engine 5m makes a 6 min old record cold', async ($, on) => { + expect(await ttlCase($, on, '5m', 6)).toBe(FABLE) +}) + +test('ttl: the engine 1h keeps a 59 min old record warm', async ($, on) => { + expect(await ttlCase($, on, '1h', 59)).toBe(SONNET) +}) + +test('ttl: a sub-agent switch event moves neither TTL nor session', async ( + $, on) => { + const rig = await bootRig($, on) + await route($, 'switch off') + await stepOn($, rig, FABLE) + await switchTo($, FABLE, OPUS, 'command', '5m', 'a1') + const text = await route($, 'show') + await route($, 'mechanical') + const line = mainLine(await route($, 'show')) + expect(line).toContain(FABLE) + expect(line).not.toContain(OPUS) + expect(text).not.toContain('ttl 5 min') +}) + +test('ttl: /clear keeps the engine TTL', async ($, on) => { + on('session.end', ($, e) => ({ sessionId: e.sessionId })) + await bootRig($, on) + await switchTo($, FABLE, FABLE, 'command', '5m') + await clearSession($) + expect(await route($, 'show')).toContain('ttl 5 min') +}) + +test('ttl: show says 60 min by default and 5 min after a 5m event', async ( + $, on) => { + await boot($, on) + expect(await route($, 'show')).toContain('ttl 60 min)') + await switchTo($, FABLE, FABLE, 'command', '5m') + expect(await route($, 'show')).toContain('ttl 5 min)') +}) diff --git a/mods/model-router/hooks/register.ts b/mods/model-router/hooks/register.ts index 8289ab0..b2a72f8 100644 --- a/mods/model-router/hooks/register.ts +++ b/mods/model-router/hooks/register.ts @@ -29,7 +29,8 @@ type Config = { fallback: string[] // alias order, best first: the rank and the fallback chain cooldownMinutes: number // breaker hold at the first strike mainUpgrade: boolean // main may move UP to a phase's tier by itself - upgradeMaxTokens: number // above this context an upgrade is skipped + upgradeMaxTokens: number // max cold read an upgrade may cost (LRN-204) + downgradeMaxTokens: number // max cold read a downgrade may cost (LRN-204) mainModelSwitch: boolean // gates DOWNGRADES only verbose: boolean classify: boolean // a small-model guess of the typed prompt's phase @@ -45,6 +46,7 @@ type Routed = { source: Source label?: string // the skill a skill route came from, for the logs } +type Served = { at: number; tokens: number } // ms, context tokens type Hold = { until: number; reason: string } // until: ms, Infinity = reload type Pushed = { prev: Routed | null; spawnIds: Set } type Loop = { @@ -54,6 +56,12 @@ type Loop = { last?: Plan // the plan this loop last ran, once it was told cause?: string // who set the effort in force, for the log lines } +/** A submitted prompt's size where `session.usage` may not count it yet. */ +type Estimate = { + tokens: number + usage: number | undefined // context size read when the first entry came + unknown: boolean // carries a non-text item: the size cannot be guessed +} type State = { cfg: Config rules: Rule[] @@ -94,7 +102,14 @@ type State = { loaded: boolean // the layers were read once (else: lazily, on first use) rebuildDue: boolean // /clear: re-read the layers at the next prompt toggles: Partial> // session toggles - engineBase: NonNullable | null // engine effort of main's first step + engineBase: NonNullable | null // engine effort of the last turn's + // first main step + turnEngine: NonNullable | null // same, for this turn + served: Map // canonical id -> main's last step on it + capSaid: boolean // the downgrade skip was logged for this cap crossing + cacheTtlMs: number // the prompt-cache TTL a cold read is measured against + promptEstimate: Estimate | null // the submitted prompt, not in usage yet + pendingEstimate: Estimate | null // same, typed mid-turn: next turn's classifyFails: number // classifier failures in a row classifyUntil: number // classifier paused until (ms); 0 = running asking: string | null // key of the one first-use dialog in flight @@ -105,6 +120,8 @@ type Log = (text: string) => void type StepIn = Readonly type PromptIn = { text: string + attachments?: readonly { type: string }[] + context?: readonly string[] turnId?: string origin: { kind: string } } @@ -149,6 +166,11 @@ const TYPED_ORIGINS: ReadonlySet = new Set([ const PROJECT_SOURCES: ReadonlySet = new Set([ 'projectSettings', 'localSettings', ]) +// Built-in agent types with no frontmatter model: an undefined `model` makes +// them inherit the spawning loop's model. +// shortcut: the frontmatter model of other types is invisible to the hook; +// widen the set when the engine exposes it on agent.offer. +const INHERITING_AGENTS: ReadonlySet = new Set(['general-purpose']) // PostModelSwitch sources a person chose (auto and resume are not). const USER_SWITCH: ReadonlySet = new Set([ 'command', 'picker', 'sdk', @@ -196,8 +218,9 @@ const BAD_KEYS: ReadonlySet = new Set([ // A quantified group holding a quantifier, the shape behind catastrophic // backtracking ((a+)+$): rejected before compiling. const NESTED_QUANT = /\((?:[^()\\]|\\.)*[+*}](?:[^()\\]|\\.)*\)[+*{]/ -// Prompt classifier: label -> the phase whose effort the turn takes. `chat` -// (and any label not here) routes nothing. +// Prompt classifier: label -> the phase whose route the turn takes (effort, +// and a model below the session's under the switch and the cold-read cap). +// `chat` (and any label not here) routes nothing. const CLASSIFY_LABELS: readonly string[] = ['design', 'analysis', 'coding', 'bookkeeping', 'chat'] const LABEL_PHASE: Readonly> = { @@ -212,6 +235,16 @@ const CLASSIFY_MAX = 2000 // code points sent whole; longer: head + tail const CLASSIFY_HEAD = 500 const CLASSIFY_TAIL = 1500 const CLASSIFY_FAILS = 3 // failures in a row that pause the classifier +// The account's prompt-cache TTL: a model that served main within it is +// warm. 1 h default; replaced by the engine's `cache_ttl` at the first +// model-switch event. +const CACHE_TTL_MS = 60 * 60000 +// The engine's two `cache_ttl` values (a closed enum), in ms. +const CACHE_TTLS: Readonly> = { + '5m': 5 * 60000, + '1h': 60 * 60000, +} +const ESTIMATE_DIVISOR = 3 // code points per token, conservative const TIMEOUT: unique symbol = Symbol('classify timeout') const DEFAULT_CONFIG: Config = { @@ -232,7 +265,8 @@ const DEFAULT_CONFIG: Config = { fallback: ['fable', 'opus', 'sonnet', 'haiku'], // rank = index, best first cooldownMinutes: 15, mainUpgrade: true, - upgradeMaxTokens: 200000, // an upgrade re-reads the whole context cold + upgradeMaxTokens: 200000, // max cold read an upgrade may cost + downgradeMaxTokens: 120000, // max cold read a downgrade may cost (LRN-204) phases: { plan: { tier: 'best', effort: 'xhigh' }, reflect: { tier: 'best', effort: 'high' }, @@ -267,7 +301,7 @@ const DEFAULT_CONFIG: Config = { mode: 'default', }, ], - mainModelSwitch: false, + mainModelSwitch: true, verbose: false, classify: true, spinner: true, @@ -509,8 +543,17 @@ function pickEnabled(v: unknown, fallback: boolean, log: Log): boolean { return false } +/** The model switch fails closed: a non-boolean override reads off. */ +function pickModelSwitch(v: unknown, fallback: boolean, log: Log): boolean { + if (v === undefined) return fallback + if (typeof v === 'boolean') return v + log('model-router: config "mainModelSwitch" is not a boolean; ' + + 'switch off') + return false +} + type Routing = Pick + 'mainUpgrade' | 'upgradeMaxTokens' | 'downgradeMaxTokens'> /** Tiers, fallback chain and breaker knobs, validated against `models`. */ function mergeRouting( @@ -534,6 +577,9 @@ function mergeRouting( mainUpgrade: pickBool(user.mainUpgrade, base.mainUpgrade), upgradeMaxTokens: pickPositive( user.upgradeMaxTokens, base.upgradeMaxTokens, 'upgradeMaxTokens', log), + downgradeMaxTokens: pickPositive( + user.downgradeMaxTokens, base.downgradeMaxTokens, 'downgradeMaxTokens', + log), } } @@ -582,7 +628,8 @@ function mergeConfig( agents: mergeRows(base.agents, user.agents, 'agents', ref, log), skills: mergeRows(base.skills, user.skills, 'skills', ref, log), prompt: mergePrompt(base.prompt, user.prompt, phases, log), - mainModelSwitch: pickBool(user.mainModelSwitch, base.mainModelSwitch), + mainModelSwitch: pickModelSwitch( + user.mainModelSwitch, base.mainModelSwitch, log), verbose: pickSwitch( 'config "verbose" is not a boolean; ignored', user.verbose, base.verbose, log), classify: pickSwitch( @@ -932,6 +979,12 @@ function newState(cfg: Config, source: string): State { rebuildDue: false, toggles: {}, engineBase: null, + turnEngine: null, + served: new Map(), + capSaid: false, + cacheTtlMs: CACHE_TTL_MS, + promptEstimate: null, + pendingEstimate: null, classifyFails: 0, classifyUntil: 0, asking: null, @@ -961,6 +1014,7 @@ function resetSession(st: State): void { loaded: st.loaded, toggles: st.toggles, engineBase: st.engineBase, + cacheTtlMs: st.cacheTtlMs, classifyFails: st.classifyFails, classifyUntil: st.classifyUntil, asking: st.asking, @@ -1120,9 +1174,15 @@ type Call = { const keep = (cur: string, why = 'unchanged', log?: string): Call => ({ model: cur, why, moved: false, ...(log === undefined ? {} : { log }) }) -/** The replacement keeps the session's `[1m]` tier, haiku has none. */ -function moveTo(cur: string, target: string, why: string): Call { - const carried = ONE_M.test(cur) && !target.startsWith(HAIKU) +/** The move keeps the `[1m]` tier of `cur` or the session; haiku has none. */ +function moveTo( + cur: string, + target: string, + why: string, + session: string, +): Call { + const long = ONE_M.test(cur) || ONE_M.test(session) + const carried = long && !target.startsWith(HAIKU) const model = carried ? `${target}[1m]` : target const once = carried ? `model-router: ${why} to ${model}: the [1m] variant is carried over` @@ -1139,11 +1199,38 @@ function fits(st: State, id: string, tokens: number | undefined): boolean { const noFit = (id: string): string => `model-router: no switch to ${id}: context not known to fit` -/** Why the upgrade cap blocks a move, or undefined. Unknown size = blocked. */ -function capBlock(st: State, tokens: number | undefined): string | undefined { +/** + * Tokens a switch INTO `id` re-reads cold (LRN-204): the context minus what + * `id`'s cache holds, i.e. its last main step within the TTL. A context + * smaller than that step (compaction) drops the stale record. + */ +function coldRead( + st: State, + id: string, + tokens: number, + now: number, +): number { + const key = canonical(st.cfg, id) + const hit = st.served.get(key) + if (hit === undefined || now - hit.at > st.cacheTtlMs) return tokens + if (tokens < hit.tokens) { + st.served.delete(key) + return tokens + } + return tokens - hit.tokens +} + +/** Why a cap blocks a move onto `id`, or undefined. Unknown size = blocked. */ +function coldBlock( + st: State, + id: string, + tokens: number | undefined, + max: number, + now: number, +): string | undefined { if (tokens === undefined) return 'context size unknown' - const max = st.cfg.upgradeMaxTokens - return tokens > max ? `context ${tokens} tokens over ${max}` : undefined + const cold = coldRead(st, id, tokens, now) + return cold > max ? `cold read ${cold} tokens over ${max}` : undefined } /** True when `wanted` ranks above `id` in the fallback chain. */ @@ -1153,6 +1240,16 @@ function ranksAbove(st: State, wanted: string, id: string): boolean { return rw !== undefined && rc !== undefined && rw < rc } +/** Main keeps its model: a cap said no, once per turn under its own key. */ +function skipped(cur: string, kind: string, block: string): Call { + const why = `${kind} skipped: ${block}` + const call = keep(cur, why, `model-router: ${why}`) + return { ...call, logKey: `${kind}-skipped` } +} + +/** The state a decision reads besides the model: context size and clock. */ +type Reading = { tokens: number | undefined; now: number } + /** * `cur` is down: `wanted`, else the next model of the chain that fits. A * better `wanted` is an upgrade and passes the same switch and cap. @@ -1161,15 +1258,21 @@ function leaveDown( st: State, cur: string, wanted: string | undefined, - tokens: number | undefined, + read: Reading, ): Call { const id = canonical(st.cfg, cur) - const upOk = st.cfg.mainUpgrade && capBlock(st, tokens) === undefined + const max = st.cfg.upgradeMaxTokens + const upOk = (o: string): boolean => st.cfg.mainUpgrade && + coldBlock(st, o, read.tokens, max, read.now) === undefined for (const option of [wanted, nextAvailable(st, id)]) { if (option === undefined || st.down.has(option)) continue if (aliasOf(st.cfg, option) === undefined) continue - if (option === wanted && !upOk && ranksAbove(st, option, id)) continue - if (fits(st, option, tokens)) return moveTo(cur, option, 'fallback') + if (option === wanted && ranksAbove(st, option, id) && !upOk(option)) { + continue + } + if (fits(st, option, read.tokens)) { + return moveTo(cur, option, 'fallback', st.sessionModel) + } } return keep(cur, 'fallback unavailable') } @@ -1179,29 +1282,33 @@ function upgradeCall( st: State, cur: string, wanted: string, - tokens: number | undefined, + read: Reading, ): Call { if (!st.cfg.mainUpgrade) return keep(cur, 'switch off') - const block = capBlock(st, tokens) - if (block !== undefined) { - const why = `upgrade skipped: ${block}` - const call = keep(cur, why, `model-router: ${why}`) - return { ...call, logKey: 'upgrade-skipped' } + const block = coldBlock( + st, wanted, read.tokens, st.cfg.upgradeMaxTokens, read.now) + if (block !== undefined) return skipped(cur, 'upgrade', block) + if (!fits(st, wanted, read.tokens)) { + return keep(cur, 'no fit', noFit(wanted)) } - if (!fits(st, wanted, tokens)) return keep(cur, 'no fit', noFit(wanted)) - return moveTo(cur, wanted, 'upgrade') + return moveTo(cur, wanted, 'upgrade', st.sessionModel) } -/** `wanted` is cheaper (or unranked): only with the downgrade switch on. */ +/** `wanted` is cheaper (or unranked): the switch and the cold-read cap. */ function downgradeCall( st: State, cur: string, wanted: string, - tokens: number | undefined, + read: Reading, ): Call { if (!st.cfg.mainModelSwitch) return keep(cur, 'switch off') - if (!fits(st, wanted, tokens)) return keep(cur, 'no fit', noFit(wanted)) - return moveTo(cur, wanted, 'downgrade') + const block = coldBlock( + st, wanted, read.tokens, st.cfg.downgradeMaxTokens, read.now) + if (block !== undefined) return skipped(cur, 'downgrade', block) + if (!fits(st, wanted, read.tokens)) { + return keep(cur, 'no fit', noFit(wanted)) + } + return moveTo(cur, wanted, 'downgrade', st.sessionModel) } /** A model the table does not rank is never switched; said once. */ @@ -1212,9 +1319,33 @@ function unknownCall(cur: string, id: string): Call { return { ...call, once } } +/** + * Main sits on a model the router moved it to and whose known window the + * context outgrew (haiku): back to the session model, when that is a known, + * ranked, available, non-haiku model. Otherwise undefined: the normal + * decision runs. + */ +function windowReturn( + st: State, + cur: string, + tokens: number | undefined, +): Call | undefined { + const id = canonical(st.cfg, cur) + const home = canonical(st.cfg, st.sessionModel) + if (st.turnModel === undefined || tokens === undefined) return undefined + if (fits(st, id, tokens)) return undefined + const usable = modelRank(st.cfg, home) !== undefined && + !st.down.has(home) && !isHaiku(st.cfg, home) + if (!usable) return undefined + const call = moveTo(cur, home, 'window', st.sessionModel) + const once = `model-router: context outgrew ${id}: back to ${home}` + return { ...call, once } +} + /** * The one decision of the main loop's model, in this order: router off, a - * model the table does not rank (never touched), `cur` down (leave it, + * model the table does not rank (never touched), a model whose window the + * context outgrew (back to the session model), `cur` down (leave it, * always), no or same wanted model, a better one (upgrade), a cheaper one * (downgrade). Used by the step AND by every text, so they agree. */ @@ -1222,25 +1353,37 @@ function decideMain( st: State, cur: string, wanted: string | undefined, - tokens: number | undefined, + read: Reading, ): Call { const id = canonical(st.cfg, cur) if (st.off) return keep(cur) if (modelRank(st.cfg, id) === undefined) return unknownCall(cur, id) - if (st.down.has(id)) return leaveDown(st, cur, wanted, tokens) + const back = windowReturn(st, cur, read.tokens) + if (back !== undefined) return back + if (st.down.has(id)) return leaveDown(st, cur, wanted, read) if (wanted === undefined) return keep(cur) if (aliasOf(st.cfg, wanted) === aliasOf(st.cfg, id)) return keep(cur) return ranksAbove(st, wanted, id) - ? upgradeCall(st, cur, wanted, tokens) - : downgradeCall(st, cur, wanted, tokens) + ? upgradeCall(st, cur, wanted, read) + : downgradeCall(st, cur, wanted, read) +} + +/** + * The slot that names main's model: sticky, turn route, run slot, then the + * floor's own model. A floor with a model beats a classifier's guess. + */ +function mainModelSlot(st: State): Routed | null { + const slots = [st.userMain, st.turnMain, st.runMain, st.turnFloor] + const slot = slots.find(s => routeName(s?.route) !== undefined) ?? null + const floor = st.turnFloor + if (slot?.source === 'classifier' && routeName(floor?.route) !== undefined) { + return floor + } + return slot } -/** Model axis: sticky, turn route, run slot, then the floor's own model. */ const mainModel = (st: State): string | undefined => - routeName(st.userMain?.route) ?? - routeName(st.turnMain?.route) ?? - routeName(st.runMain?.route) ?? - routeName(st.turnFloor?.route) + routeName(mainModelSlot(st)?.route) async function readTokens($: Api): Promise { try { @@ -1250,17 +1393,103 @@ async function readTokens($: Api): Promise { } } +/** + * The context size a cap reads: `raw` plus the pending prompt's estimate, + * unless usage already grew by half of it (the prompt was counted). Pure: + * the step and every text read the same figure. Unknown = blocked. + */ +function withEstimate(st: State, raw: number | undefined) { + const est = st.promptEstimate + if (raw === undefined || est === null) return raw + if (est.unknown) return undefined + const counted = est.usage !== undefined && + raw - est.usage >= est.tokens / 2 + return counted ? raw : raw + est.tokens +} + +/** Sums an entry into a pending estimate; the first baseline is kept. */ +function sumEstimate( + cur: Estimate | null, + tokens: number, + usage: number | undefined, + unknown: boolean, +): Estimate { + return { + tokens: (cur?.tokens ?? 0) + tokens, + usage: cur === null ? usage : cur.usage, + unknown: (cur?.unknown ?? false) || unknown, + } +} + +/** + * Adds a submitted text (and a flag for a non-text item) to the pending + * estimate. A mid-turn entry waits for the next turn, where its baseline is + * reset; the first entry of a turn reads the usage as its baseline. + */ +async function addEstimate( + $: Api, + st: State, + size: { points: number; unknown: boolean }, + midTurn: boolean, +): Promise { + const tokens = Math.ceil(size.points / ESTIMATE_DIVISOR) + if (midTurn) { + st.pendingEstimate = sumEstimate( + st.pendingEstimate, tokens, undefined, size.unknown) + return + } + const usage = st.promptEstimate === null ? await readTokens($) : undefined + st.promptEstimate = sumEstimate( + st.promptEstimate, tokens, usage, size.unknown) +} + +/** Code points of a text, as the estimate counts them. */ +const pointsOf = (texts: readonly string[]): number => + texts.reduce((n, t) => n + Array.from(t).length, 0) + type Verdict = { call: Call; wanted: string | undefined } -/** What the main loop would run on from `cur`: wanted model + decision. */ -async function decideFor($: Api, st: State, cur: string): Promise { - const name = mainModel(st) - const wanted = name === undefined - ? undefined - : resolveName(st, name, canonical(st.cfg, cur)) - const needsTokens = wanted !== undefined || st.down.size > 0 - const tokens = needsTokens ? await readTokens($) : undefined - return { call: decideMain(st, cur, wanted, tokens), wanted } +/** + * The model main is asked to run on from `cur`. A classifier's guess never + * ranks above the session model: it moves main down, never above the + * user's baseline. + */ +function wantedModel(st: State, cur: string): string | undefined { + const slot = mainModelSlot(st) + const name = routeName(slot?.route) + if (name === undefined) return undefined + const wanted = resolveName(st, name, canonical(st.cfg, cur)) + const above = wanted !== undefined && slot?.source === 'classifier' && + ranksAbove(st, wanted, canonical(st.cfg, st.sessionModel)) + return above ? undefined : wanted +} + +/** Reads the usage and the clock when a decision may need them. */ +async function readingFor( + $: Api, + st: State, + wanted: string | undefined, +): Promise { + const needs = wanted !== undefined || st.down.size > 0 || + st.turnModel !== undefined + if (!needs) return { tokens: undefined, now: 0 } + const raw = await readTokens($) + return { tokens: withEstimate(st, raw), now: await $.clock.now() } +} + +/** + * What the main loop would run on from `cur`: wanted model + decision. The + * step passes the `known` reading it took; a text reads for itself. + */ +async function decideFor( + $: Api, + st: State, + cur: string, + known?: Reading, +): Promise { + const wanted = wantedModel(st, cur) + const read = known ?? await readingFor($, st, wanted) + return { call: decideMain(st, cur, wanted, read), wanted } } function logCall($: Api, st: State, call: Call): void { @@ -1297,11 +1526,10 @@ function higherFloor(cur: Routed | null, next: Routed): Routed { * The one decision of the main loop's effort. The user's floor is the turn's * default (no sticky or turn route names an effort) and its minimum. * `by` names who set the value: the floor when it raised or supplied it. - * `skipTurn`: the turn route yields (a classified effort under a user /effort). */ -function mainEffort(st: State, engine: Effort, skipTurn = false): Decision { +function mainEffort(st: State, engine: Effort): Decision { const sticky = st.userMain?.route.effort - const turn = skipTurn ? undefined : st.turnMain?.route.effort + const turn = st.turnMain?.route.effort const named = sticky ?? turn ?? st.runMain?.route.effort const floor = st.turnFloor?.route.effort const base = named ?? floor ?? engine @@ -1455,14 +1683,20 @@ async function snapshot($: Api, st: State) { return { now, ...(await decideFor($, st, cur)) } } +/** The downgrade switch and, when on, the cold read it is capped at. */ +const switchWord = (st: State): string => st.cfg.mainModelSwitch + ? `on (downgrade, cap ${st.cfg.downgradeMaxTokens} tokens cold, ttl ${ + Math.round(st.cacheTtlMs / 60000)} min)` + : 'off (downgrade)' + async function show($: Api, st: State): Promise { const c = st.cfg const flag = (b: boolean) => (b ? 'on' : 'off') const s = await snapshot($, st) return [ mainText(st, s), - `router: ${routerWord(st)} · switch: ${flag(c.mainModelSwitch)} ` + - `(downgrade) · upgrade: ${flag(c.mainUpgrade)} · verbose: ${ + `router: ${routerWord(st)} · switch: ${switchWord(st)} · upgrade: ${ + flag(c.mainUpgrade)} · verbose: ${ flag(c.verbose)} · classify: ${flag(c.classify)} · spinner: ${ flag(c.spinner)}`, downText(st, s.now), @@ -1480,7 +1714,7 @@ function statusLine(st: State): string { const floor = liveFloor(st) const paused = st.cfg.classify && st.classifyUntil !== 0 return `route: ${now}${floor ? ` · floor ${floor.level}` : ''}${ - st.cfg.mainModelSwitch ? ' · switch on' : ''}${ + st.cfg.mainModelSwitch ? '' : ' · switch off'}${ paused ? ' · classifier: paused' : ''}` } @@ -1534,6 +1768,7 @@ async function toggle( if (arg !== 'on' && arg !== 'off') return `usage: /route ${what} on|off` st.toggles[what] = arg === 'on' applyToggles(st) + refresh($, st) return show($, st) } @@ -1594,6 +1829,8 @@ async function ensureConfig($: Api, st: State, atPrompt = false) { /** The breaker is cleared first, whatever the config read then does. */ async function reloadCommand($: Api, st: State): Promise { clearBreaker(st) + st.served.clear() + st.capSaid = false st.classifyFails = 0 st.classifyUntil = 0 const swapped = await reloadConfig($, st) @@ -2120,19 +2357,22 @@ async function skillQuestion($: Api, st: State, skill: string, phase: string) { return mainQuestion($, st, `${head}. ${routedTo(st, phase)}`) } -/** A downgrade the switch holds back: main keeps its model, said. */ -function downgradeHeld(st: State, v: Verdict, cur: string): boolean { - return v.wanted !== undefined && v.call.why === 'switch off' && - !ranksAbove(st, v.wanted, canonical(st.cfg, cur)) +/** A downgrade the switch or the cold-read cap holds back, said. */ +function downgradeHint(st: State, v: Verdict, cur: string): string { + const { wanted, call } = v + if (wanted === undefined) return '' + if (ranksAbove(st, wanted, canonical(st.cfg, cur))) return '' + if (call.why === 'switch off') { + return ', main moves up only: /route switch on allows a downgrade' + } + return call.why.startsWith('downgrade skipped') ? `, held: ${call.why}` : '' } /** After a Change: what main will really run, and the switch hint. */ async function toastChange($: Api, st: State, skill: string) { const cur = st.turnModel ?? st.sessionModel const v = await decideFor($, st, cur) - const hint = downgradeHeld(st, v, cur) - ? ', main moves up only: /route switch on allows a downgrade' - : '' + const hint = downgradeHint(st, v, cur) $.ui.toast(`/${skill} now runs ${idWord(st, v.call.model)} at ${ effortWord(st, v)}${hint}`) } @@ -2495,9 +2735,9 @@ async function registerTool($: Api, st: State): Promise { 'Declare the phase of the work ahead so the next requests of THIS ' + 'loop run at the right effort and model. Call it before a span of ' + 'work changes nature (planning, orchestrating, mechanical work). ' + - 'The main loop moves up to a phase\'s tier by itself (below the ' + - 'context cap), down only with the switch on; a sub-agent\'s model ' + - 'is fixed at spawn. ' + + 'The main loop moves up or down to a phase\'s tier while the cold ' + + 'read it costs fits the cap (down also needs the switch on); a ' + + 'sub-agent\'s model is fixed at spawn. ' + `Phases: ${Object.keys(st.cfg.phases).join(', ')}.`, inputSchema: { type: 'object', @@ -2626,6 +2866,13 @@ function skillRow(st: State, skill: string): Picked | undefined { return phase !== undefined && route ? { phase, route } : undefined } +/** The run slot's model outranks the route's: a helper moves effort only. */ +function belowRun(st: State, route: Route): boolean { + const mine = resolveRoute(st, route) + const run = resolveRoute(st, st.runMain?.route) + return mine !== undefined && run !== undefined && ranksAbove(st, run, mine) +} + /** * A rowed skill on main sets the turn route; a best-tier row also holds the * run slot. A typed non-best row drops the run; one the model loads (a @@ -2637,7 +2884,10 @@ function routeMainBySkill( row: Picked, typed: boolean, ): void { - const turn: Routed = { phase: row.phase, route: { ...row.route }, + const route = !typed && belowRun(st, row.route) + ? { effort: row.route.effort } + : { ...row.route } + const turn: Routed = { phase: row.phase, route, source: 'skill', label: clean(skill, NAME_CAP) } st.turnMain = turn if (row.route.tier === BEST) st.runMain = { ...turn, source: 'run' } @@ -2670,23 +2920,28 @@ function typedPath(st: State, skill: string): TypedPath | undefined { return st.promptAllowed && idle ? 'typed-fallback' : undefined } -/** Routes main by the typed skill's row; the row, for the first-use ask. */ -function armTypedSkill($: Api, st: State, skill: string) { +type Armed = { row: Picked | undefined; typed: boolean } + +/** + * Routes main by the typed skill's row; the row, for the first-use ask, and + * whether the user typed the skill (rowed or not: its body is theirs). + */ +function armTypedSkill($: Api, st: State, skill: string): Armed { const row = skillRow(st, skill) - const path = typedPath(st, skill) - if (row === undefined || path === undefined) return undefined + const typed = typedPath(st, skill) !== undefined + if (row === undefined || !typed) return { row: undefined, typed } routeMainBySkill(st, skill, row, true) refresh($, st) - return row + return { row, typed } } /** Bookkeeping that may fail without breaking the hook: fail-open. */ -function armed($: Api, st: State, skill: string): Picked | undefined { +function armed($: Api, st: State, skill: string): Armed { try { return armTypedSkill($, st, skill) } catch { warnOnce(st, $, 'skill.prompt', 'bookkeeping') - return undefined + return { row: undefined, typed: false } } } @@ -2746,9 +3001,31 @@ function inTier($: Api, st: State, agent: string, tier: string) { return undefined } +/** + * A built-in inheriting type spawned by main while main sits below the + * session model (a demotion or a breaker fallback) would inherit that lower + * model: it starts on the session model instead. Forks and workflows are + * frozen, a nested spawn inherits an agent's model, never main's, and a + * shadowing project or user definition may carry its own frontmatter model. + */ +function sessionPin(st: State, e: SpawnIn): string | undefined { + const turn = st.turnModel + const inherits = INHERITING_AGENTS.has(e.subagentType) && + st.offers.get(e.subagentType) === 'built-in' + const main = !e.fork && e.workflow === undefined && + e.parentAgentId === undefined + if (turn === undefined || st.sessionModel === '' || !inherits || !main) { + return undefined + } + const session = canonical(st.cfg, st.sessionModel) + const demoted = ranksAbove(st, session, canonical(st.cfg, turn)) + return demoted && !st.down.has(session) ? st.sessionModel : undefined +} + /** The model a spawn is rewritten to; an explicit `model` param wins. */ function spawnTarget($: Api, st: State, e: SpawnIn, route: Route | undefined) { - if (e.model !== undefined || route === undefined) return undefined + if (e.model !== undefined) return undefined + if (route === undefined) return sessionPin(st, e) if (route.tier === undefined) return resolveRoute(st, route) return inTier($, st, e.subagentType, route.tier) } @@ -2909,6 +3186,7 @@ function modelCause(st: State, why: Why): string | undefined { if (!call.moved) return undefined if (call.why === 'upgrade') return 'upgrade' if (call.why === 'downgrade') return 'switch' + if (call.why === 'window') return 'window' return `fallback: ${nameOf(st.cfg, cur)} down` } @@ -2977,6 +3255,7 @@ type Handoff = { to: Plan; modelCause: string; effortCause: string } function spawnModelCause(st: State, sp: Spawned): string { const { e, route, wanted } = sp if (e.model !== undefined) return 'explicit' + if (route === undefined && wanted !== undefined) return 'session' if (route === undefined || wanted === undefined) return 'frontmatter' const head = headAlias(st.cfg, route) const lead = head === undefined ? undefined : st.cfg.models[head] @@ -2993,7 +3272,9 @@ function handoffOf( given: Level | undefined, ): Handoff | undefined { const { e, route, started } = sp - if (route === undefined && e.model === undefined && given === undefined) { + const pinned = sp.wanted !== undefined + if (route === undefined && e.model === undefined && given === undefined && + !pinned) { return undefined } const effort = isHaiku(st.cfg, started.model) @@ -3031,32 +3312,64 @@ function agentPlan(st: State, e: StepIn): Plan { type Why = { by: EffortBy; call: Call; cur: string } type Step = { plan: Plan; why?: Why } -/** The engine effort of main's first step: what the user left as default. */ +/** The engine effort of this turn's first main step: the user's default. */ function noteEngineBase(st: State, e: StepIn): void { - if (st.engineBase === null && e.effort !== undefined) { - st.engineBase = e.effort + if (st.turnEngine === null && e.effort !== undefined) { + st.turnEngine = e.effort } } -/** A user /effort beats a guessed phase: the engine effort left its base. */ -function userMovedEffort(st: State, e: StepIn): boolean { - return st.turnMain?.source === 'classifier' && e.effort !== undefined && - st.engineBase !== null && e.effort !== st.engineBase +/** + * A user /effort beats a guessed phase: this turn's engine effort differs + * from the previous turn's, typed between the two. + */ +function userMovedEffort(st: State): boolean { + return st.turnMain?.source === 'classifier' && st.turnEngine !== null && + st.engineBase !== null && st.turnEngine !== st.engineBase +} + +/** Main ran `plan` at `read`: that model's cache holds this context now. */ +function noteServed(st: State, plan: Plan, read: Reading): void { + const id = canonical(st.cfg, plan.model) + if (read.tokens === undefined || aliasOf(st.cfg, id) === undefined) return + st.served.set(id, { at: read.now, tokens: read.tokens }) +} + +/** + * The downgrade skip is said once per cap crossing: it stays quiet until a + * downgrade succeeds. Returns the call the log line is taken from. + */ +function capLogged(st: State, call: Call): Call { + if (call.why === 'downgrade') st.capSaid = false + if (!call.why.startsWith('downgrade skipped')) return call + const said = st.capSaid + st.capSaid = true + if (!said) return call + const { log: _log, logKey: _key, ...quiet } = call + return quiet } /** * The main loop's plan: effort from the floor/sticky/turn decision, model * from `decideMain`. `cur` is the model the router moved this turn, else - * the engine's own (verbatim: an engine fallback is respected). + * the engine's own (verbatim: an engine fallback is respected). Every step + * reads the context and the clock and records the model it ran on. */ async function mainPlan($: Api, st: State, e: StepIn): Promise { noteEngineBase(st, e) - const { effort, by } = mainEffort(st, e.effort, userMovedEffort(st, e)) + if (userMovedEffort(st)) st.turnMain = null + const { effort, by } = mainEffort(st, e.effort) await prune($, st) const cur = st.turnModel ?? e.model - const { call } = await decideFor($, st, cur) - logCall($, st, call) + const raw = await readTokens($) + const now = await $.clock.now() + const { call } = await decideFor( + $, st, cur, { tokens: withEstimate(st, raw), now }) + logCall($, st, capLogged(st, call)) if (call.moved) st.turnModel = call.model + // the record stays raw: an estimate in it would trip the compaction path + noteServed(st, { model: call.model, effort }, { tokens: raw, now }) + st.promptEstimate = null // consumed by the turn's first main step return { plan: { model: call.model, effort }, why: { by, call, cur } } } @@ -3082,7 +3395,21 @@ function noteMain($: Api, st: State, plan: Plan): void { safely(st, $, 'turn.step status', () => refresh($, st)) } +/** + * An estimate no step consumed, and one typed mid-turn, carry to the next + * turn with their baseline reset: added at its first step, never dropped. + */ +function carryEstimate(st: State): void { + const left = [st.promptEstimate, st.pendingEstimate] + .filter((x): x is Estimate => x !== null) + const sum = left.reduce( + (acc, x) => sumEstimate(acc, x.tokens, undefined, x.unknown), null) + st.promptEstimate = sum + st.pendingEstimate = null +} + function endMainTurn($: Api, st: State): void { + carryEstimate(st) st.turnFloor = st.pendingPrompt st.pendingPrompt = null st.turnMain = null @@ -3095,6 +3422,8 @@ function endMainTurn($: Api, st: State): void { st.explicitEffort.clear() st.spinner = '' st.turnLogged.clear() + if (st.turnEngine !== null) st.engineBase = st.turnEngine + st.turnEngine = null refresh($, st) } @@ -3129,8 +3458,14 @@ type SwitchIn = { to_model: string requested_model: string | null source: string + cache_ttl?: unknown + agent_id?: unknown // set when a sub-agent's model switched } +/** The engine's `cache_ttl` in ms, or undefined for any other value. */ +const ttlOf = (v: unknown): number | undefined => + typeof v === 'string' && hasKey(CACHE_TTLS, v) ? CACHE_TTLS[v] : undefined + /** * The engine switched the model by itself. The model it left is marked, one * strike, unless it landed where the router already was; the mark targets @@ -3149,9 +3484,15 @@ async function onAutoSwitch($: Api, st: State, e: SwitchIn): Promise { markDown($, st, target, 'engine fallback', await $.clock.now()) } -/** Any model change: keeps `sessionModel`; a user choice clears its mark. */ +/** + * Any model change: keeps `sessionModel` and the cache TTL (main's own + * switches only); a user choice clears its mark. + */ async function onModelSwitch($: Api, st: State, e: SwitchIn): Promise { - st.sessionModel = e.to_model + if (e.agent_id === undefined) { + st.sessionModel = e.to_model + st.cacheTtlMs = ttlOf(e.cache_ttl) ?? st.cacheTtlMs + } if (USER_SWITCH.has(e.source)) st.runMain = null if (st.off || e.source === 'resume') return if (e.source === 'auto') await onAutoSwitch($, st, e) @@ -3264,7 +3605,11 @@ function registerSkills(on: On, st: State): void { on('skill.prompt', async ($, e, next) => { await ensureConfig($, st) if (st.off || st.skillCalls > 0) return next(e) - const row = armed($, st, e.skill) + const { row, typed } = armed($, st, e.skill) + if (typed) { + const size = { points: pointsOf([e.text]), unknown: false } + await addEstimate($, st, size, false) + } if (row) await confirmSkill($, st, e.skill, row) return next(e) }).catch(($, e, next) => { @@ -3436,9 +3781,11 @@ function noteTyped(st: State, kind: string, text: string, midTurn: boolean) { // ---- prompt classifier ----------------------------------------------- // A typed prompt no rule, skill, route or floor covers is guessed by one -// small-model call: the phase's EFFORT becomes the turn's default (never a -// model move, never a dialog, never a file write). The call is bounded and -// every failure leaves the prompt as it was. +// small-model call: the phase's effort becomes the turn's default and its +// tier a model move DOWN only (under `mainModelSwitch` and the cold-read cap +// `downgradeMaxTokens`; never above the session model; never a dialog or a +// file write). The call is bounded and every failure leaves the prompt as +// it was. /** The whole text up to CLASSIFY_MAX code points, else its head and tail. */ function sampleOf(text: string): string { @@ -3532,18 +3879,16 @@ async function askClassifier( return label } -/** The turn route of a label: its phase's effort only; false = nothing. */ +/** The turn route of a label: its phase's tier and effort; false = none. */ function routeFromLabel(st: State, label: string): boolean { const phase = hasKey(LABEL_PHASE, label) ? LABEL_PHASE[label] : undefined - const effort = phase === undefined - ? undefined - : phaseRoute(st.cfg, phase)?.effort - if (phase === undefined || effort === undefined) return false - st.turnMain = { phase, route: { effort }, source: 'classifier' } + const route = phase === undefined ? undefined : phaseRoute(st.cfg, phase) + if (phase === undefined || route?.effort === undefined) return false + st.turnMain = { phase, route: { ...route }, source: 'classifier' } return true } -/** Fills an empty route with the guessed phase's effort; never throws on it. */ +/** Fills an empty route with the guessed phase's route; never throws on it. */ async function classifyPrompt( $: Api, st: State, @@ -3557,12 +3902,21 @@ async function classifyPrompt( if (routeFromLabel(st, label)) refresh($, st) } +/** What a prompt adds to the context: its text, context blocks, items. */ +function promptSize(e: PromptIn): { points: number; unknown: boolean } { + return { + points: pointsOf([e.text, ...(e.context ?? [])]), + unknown: (e.attachments ?? []).some(a => a.type === 'document'), + } +} + function registerPrompt(on: On, st: State): void { on('prompt.submit', async ($, e, next) => { await ensureConfig($, st, true) if (st.off) return next(e) const midTurn = e.turnId !== undefined noteTyped(st, e.origin.kind, e.text, midTurn) + await addEstimate($, st, promptSize(e), midTurn) if (e.origin.kind === 'composer') routeFromPrompt(st, e.text, midTurn) refresh($, st) await classifyPrompt($, st, e, next.signal)