6.3 KiB
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
spawnTargetpins a spawn tost.sessionModel(verbatim) ONLY when: no explicitmodel, no row, not a fork, no workflow,parentAgentIdundefined (main's own child),subagentTypein the allowlistINHERITING_AGENTS(general-purpose: built-in types with no frontmatter model) AND offered with sourcebuilt-in(st.offers; a shadowing repo/user agent of that name, or no offer record, is never pinned),turnModelset 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:wantedset, model causesession. Ashortcut:comment names the frontmatter blind spot.- Prompt-size estimate:
prompt.submit(any origin; text pluscontextentries) andskill.prompt(ONLY main's typed skill, never a sub-agent preload) ADDceil(codePoints / 3)to a pending estimate (sum; the FIRST entry's usage read is the baseline); adocumentattachment marks the estimate unknown. A mid-turn submit (turnIdset) is pending for the NEXT turn (baseline reset at promotion). A purewithEstimate(st, raw)returnsraw + estimatewhen the baseline is unknown or usage grew by less than half the estimate,undefinedwhen unknown, elseraw; it is applied in the shared reading path (readingFor, texts) AND inmainPlan(step), so both agree.noteServedrecords 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. - TTL:
State.cacheTtlMsinitialised toCACHE_TTL_MS(60 min), replaced on a PostModelSwitch event whosecache_ttlis one of the engine's two values ('5m'→ 5 min,'1h'→ 60 min; anything else ignored); events carryingagent_idchange neither the TTL norsessionModel.coldReadusesst.cacheTtlMs. The TTL survives/clearand is NOT reset by/route reload. /route showswitch word readson (downgrade, cap <N> tokens cold, ttl <M> min)when on;off (downgrade)unchanged; the existing show test is migrated.- 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)/clearkeeps 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 shadowedgeneral-purpose(sourceprojectSettings) is never pinned. Estimate tests run withclassify: false. Migrated existing tests, expectations re-derived, never weakened: the show text test (ttl suffix) andtoast: a downgrade held by the cap says so(its cold-read figure now includes the typed/featprompt's estimate, 6 tokens for 17 code points, plus any typed body counted). - 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
coldReadreadsst.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)