feat(agent): bind the model to the conversation, not the process

[arelchan]

Summary

Stacked on #282 -- this branch contains that PR's commits plus one. Review #282 first; the diff here is the last commit, 6882916.

The model was two attributes on a process-wide AgentLoop, so there was one answer for everyone. Two sessions could not run different models, a switch in one moved all of them, and the "default" was whatever the last switch happened to write to agents.defaults. This makes the model a property of the conversation.

A ModelBinding is a model id and the credential that serves it, as one value -- the pairing that everything below depends on. ProviderPool is the single place that decides which credential a model id pairs with, cached per (vendor, model); constructing a binding from an already-resolved pair happens in several places. run_turn resolves the binding for the turn's session and holds it in a ContextVar for the whole turn tree; the loop's provider/model, the context engine's LLM-backed segments, the skill gate and rewriter, and the consolidator all read that instead of a reference of their own.

The rules, and what each cost

Rule	How it lands
Different sessions, different models	A dict of overrides, read once at turn entry
A switch moves only the session that asked	Nothing else reads that session's entry
A new session starts on the configured default	A session-scoped switch does not write agents.defaults, so nothing accumulates
A configured subsystem uses its own model+credentials; otherwise it follows the conversation	The factory resolves each pin through the pool, so a holder has either a complete pair or nothing
A switch mid-turn takes effect next turn	Free -- the turn holds the binding it entered on

The last one is worth spelling out: it needs no parking and no counter, and this branch deletes the ones #282 added -- _turns_in_flight, _pending_provider and the adopt-on-entry hook are gone, so #282's "In-flight work" rationale describes a mechanism that no longer exists once both land. The binding is captured before the turn's first read, so a switch landing mid-turn is simply not visible to that turn. The client-side refusal that used to pre-empt it (interrupt the current turn before trying to change models) is gone, and with it ModelSwitchInTurnError across the Python errors module, the TypeScript client, the OpenRPC schema and the code-table test -- nothing raises it, and leaving it would tell the next reader the server still can.

Detached work inherits the context copy asyncio makes at task creation, so a spawned subagent finishes on the model it was spawned under. spawn also passes the pair explicitly, because a subagent outlives its turn and that is worth being able to read in the code.

User-facing

config.set model takes a scope: session (what the picker sends) or default. /model <name> --default is the counterpart in the TUI, since a session-scoped switch alone would leave no way to change the persisted default at all. A session's choice is stored on its own record and restored on resume, so it outlives the process without becoming everyone's default. The picker and the session info bundle (session.create / session.resume) now report the session's own model -- reading agents.defaults there showed two different models for one conversation.

Config defaults

No subsystem ships a vendor default any more. context.curator_model, token_wise.tool_result_lifecycle.summary_model and skill_forge.detect_model all hardcoded the same Gemini id, and token_wise.smart_routing.tiers shipped six models across three vendors -- for users who may hold no key for any of them. All four are unset now, which is what "not configured" has to mean for the subsystem rule to be expressible. Only curator_model has readers today; the other three are dead config, emptied for consistency rather than for effect. The media tools keep their defaults, which live in the tool code rather than the schema: they are capability-bound, and no conversation model generates images or speech.

A subsystem pin is a pair too

context.curator_model and skill_forge.llm_gate_model took a model id and nothing else, so the pool had to guess which credential served it -- the same shape as the mis-pairing this whole line of work is about, one layer up. The guess is unanswerable once a gateway is configured: openrouter serving anthropic/claude-haiku-4-5 and anthropic serving claude-haiku-4-5 are both valid, name different credentials and different bills, and the id does not distinguish them. Guessing "the configured gateway serves everything" then handed the gateway an id it has no route for, and the 404 was swallowed by the subsystem's own fallback -- a pin that looked configured and never ran.

Each pin now takes a provider alongside the model (curator_provider, llm_gate_provider). Set, nothing is derived. Unset, the vendor is still derived from the id, which is what every existing config gets and what keeps them working. Either way a pin that cannot be paired is logged and dropped rather than silently borrowing the conversation's key. bind_pin's guard is also broadened from the credential exceptions to anything: it runs in the context-engine factory at construction and building a provider imports a vendor module, so a misconfigured pin could stop the agent from starting -- the opposite of what its docstring promised.

Release note. With context.curator_model unset, the Curator's slow path now runs on the conversation's model instead of failing on a Gemini id nobody had a key for and dropping to the deterministic plan. That is the rule working as asked, but on a long conversation it is up to 12 tool-calling requests per turn of context housekeeping that previously cost nothing. Set context.curator_model to a small model, and configure that vendor's key, to keep it cheap.

Type

• Feature

Verification

uv run pytest tests/ -q
5362 passed, 1 failed (tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare)

uv run ruff check raven/ tests/     # All checks passed
cd ui-tui && npm test               # 973 passed (85 files)
cd ui-tui && npx tsc --noEmit       # clean
cd ui-tui && npm run lint:rpc       # generated.ts in sync
cd ui-tui && npm run lint           # 0 errors (22 pre-existing warnings, untouched files)

tests/test_default_context_engine.py::TestTwoTrackConcurrency::test_skill_and_memory_run_concurrently also fails in some full-suite runs -- a load-dependent timing assertion that flakes on the unmodified branch too, and passes alone and with its own file. That one failure fails identically on an unmodified main at 53aeb0c when the whole file runs, and passes when the single test runs alone -- machine-dependent order pollution in that file, and CI is green on it. Same note as #282.

This change was reviewed by seven independent agents across two rounds, each in its own worktree, which is where most of its shape came from. The second round found the persistence half-built -- the write to the session record had no reader, so a switch died with the process while the code and the description both said otherwise -- and the provider pool handed a config snapshot at all three construction sites, so the freshness it documents never fired and a key added through the picker then selected in the same session failed where it used to work. It also found the picker overriding its selection for every session (session_model falls back to the default and so never answers None), the gateway pin escaping the factory's guard, a deleted session leaving its override behind, a fork dropping its parent's model, and -- on the TUI side -- two existing tests that would have gone red in CI on the new scope key, plus a default-scoped switch painting the new default into the status bar while the session kept its own model. All fixed here.

The first round found two features that existed on the server and were unreachable from the product: the client still refused a mid-turn switch, and a session-scoped /model had no counterpart for changing the persisted default.

A third round, run against the pushed branch, found three defects the earlier rounds had missed and three claims this description got wrong. The defects: config.set treated an explicit scope="session" carrying no session id as a request to change the default, so it wrote agents.defaults.model and moved every session that never switched -- reachable from the TUI, whose session_id is null until the first session.create resolves; the fork fix above re-pointed the live binding but never wrote the child's record, so a branched session kept its parent's model until the first restart and then silently dropped to the default; and /model <name> --default refused to repaint the status bar on the theory that a default-scoped switch cannot move the asking session, which is true only of sessions that already chose their own model -- for a fresh conversation, the common case for that command, the switch moved it and the bar then disagreed for the life of the session. The scope of a switch is now the server's answer (applies_to_session) rather than something the client infers.

The wrong claims were all in the mutation table, and the same class of error as the round-two finding above: three rows asserted a test that no longer discriminated. _set_model ignores scope and model.options loses its loop factory both left the suite green -- the conjunct that routes --default and the production registration that makes the picker session-aware were each exercised only by callers that could not tell the difference; both now have tests, verified red. The spawn row was true at #282's head and false at this one: asyncio.create_task copies the context, so moving the read out of spawn returns the same binding and no test can separate them. That row is dropped rather than reworded -- the explicit snapshot stays for readability, which is what the prose above already claimed for it. ProviderPool.default had no production caller at all: what a new session starts on is AgentLoop._default_binding, built in the constructor, so the method and the two table rows protecting it are deleted.

Mutation-tested rather than assumed. Each of these turns a test red:

Mutation
binding_for_session ignores the session dict	7 failed
set_session_binding -> pass	7 failed
run_turn drops use_binding	5 failed
run_turn keys on a hardcoded session	5 failed
run_turn drops the channel:chat_id key fallback	1 failed
set_default_binding stops fanning out	2 failed
use_binding never resets its token	7 failed
resolve ignores the pin	2 failed
spawn passes its fallback instead of the active binding	1 failed
_set_model ignores scope	2 failed
a session scope with no session id is widened to the default	1 failed
applies_to_session always claims the asking session moved	1 failed
ProviderPool.bind drops the cache	1 failed
bind_pin skips the credentials check	1 failed
bind_pin loses the gateway branch	1 failed
the pool holds a config snapshot	1 failed
the gate sends its raw pin out of turn	1 failed
the session info bundle drops the per-session model	1 failed
session.resume stops restoring the stored model	1 failed
_remember_session_model -> pass	1 failed
model.options ignores the session	1 failed
model.options loses its loop factory	1 failed
_build_binding never uses the pool	1 failed
scope validation removed	1 failed
the factory stops building the skill-gate pin	1 failed
bind_pin ignores the configured provider and guesses	4 failed
the factory drops the curator's configured provider	1 failed
the factory drops the gate's configured provider	1 failed
fork stops carrying the parent's model record	2 failed
session.branch stops handing the child the live binding	1 failed
session.delete stops releasing the binding	1 failed
the client guesses from the scope instead of asking the server (TS)	1 failed

• Relevant tests pass locally
• Relevant lint / type checks pass locally
• User-facing docs or screenshots are updated when needed

Risk

• Security impact considered
• Backward compatibility considered
• Rollback path is clear for risky changes

Existing config files load unchanged and still pin: a file containing curatorModel (or the snake_case spelling) keeps its value, and smartRouting.tiers round-trips verbatim. The new curatorProvider / llmGateProvider fields are additive and optional -- unset reproduces the previous derivation exactly. The scope key on config.set is additive and the response's new scope / session_id / applies_to_session keys are ignored by older clients. AgentLoop.provider / model became read-only properties, so anything assigning them must move to set_provider or a binding -- a deliberate break, since assigning one half of a pair is the bug this whole line of work started from. Rollback is a revert.

CONTEXT.md defines the new vocabulary (model binding, session binding, default binding, provider pool, subsystem pin) and ui-tui/CONTEXT.md defines model scope for the TUI, per AGENTS.md 6. config.set's params and result are declared in the OpenRPC schema and the Pydantic models -- both omitted session_id / provider before this, so the schema-match guardrail could not see the drift; generated.ts is regenerated.

Related Issues

N/A