The reasoning pill stops guessing — it speaks the contract

🛰️ Satellite — why a stub enum on a wire-facing control is a time bomb

The stakes: the reasoning pill is the single user-facing knob over "how hard the agent thinks," and that knob has to route a turn to a model via the broker. The level word the UI shows is the same word the broker resolves (RFC-APB-004). If the UI carries its own private copy of the level set, the day the contract renames a level — extra_high → max, which is exactly what RFC-APB-004 did — the pill keeps rendering a word the broker no longer accepts, and the turn fails closed. A duplicated enum on a trust boundary is a drift waiting for a deploy.

The naive fix — "just keep the union in sync by hand" — detonates on the first rename: nothing fails the build, the stub still compiles, the tests still pass against the stub, and the break only shows up as a runtime 422 in staging. The real fix makes the generated enum the single source of the type (HR-22) so a rename upstream is a compile error here, and adds a totality guard so an added level the pill forgot to render also fails the build. The contract can't drift away from the UI silently anymore — the type system welds them.

✈️ Airplane — type from src/gen, default from the descriptor, level onto the turn

One analogy: the pill is a gear lever. Before, the lever had its own painted list of gears that someone had to repaint whenever the gearbox changed. Now the lever reads its gears off the gearbox itself — and when you shift, the chosen gear travels down the linkage to the box, which decides what's actually safe to engage (the floor).

🔬 Microscopic — the pieces, and why each is shaped the way it is

The level type — sourced, then proven total

agent-descriptor.ts drops the hand-typed union for export type ReasoningLevel = ThinkingLevel (imported from @/gen). The UI-facing name is kept so no call site churns, but the type is now contract-owned. The render-order array uses as const satisfies readonly ReasoningLevel[] — a rename upstream makes a literal stop satisfying the type, failing the build. That only catches renames, so a one-line totality guard (Exclude<ReasoningLevel, (typeof REASONING_LEVELS)[number]> must be never) catches an added level the array forgot — the pill can never silently drop a level the contract gained.

The default — declared by the agent, not the control

atlas-descriptor.ts sets defaultReasoningLevel: "medium" (RFC §E: ~90% of turns never touch the pill and ride the agent's default, so the default is the product; the pill is the escape hatch). The dock already read the default from the descriptor — the fix is that the value is now the agent's declared one, not the "High" that was baked in.

The turn request — the level rides as rail posture

src/lib/agents/turn-request.ts is a pure, transport-free shaper. The AgentSessionTurnRequest envelope is strict (extra="forbid"), but its context is the open, versioned provider bag. The posture rides as one named provider — providers.posture.thinking_level — mirroring the agent_invoke.v1 posture. The broker resolves the level to {model, reasoning_effort} LAST and floors it: a per-op floor can raise the level, never silently drop a user's explicit choice below the floor (RFC §B / ADR-129 D3). A unit test parses the built request through the generated agentSessionTurnRequestSchema to prove the strict envelope accepts it.

The wiring — the dock builds the request every send

agent-dock-mount.tsx already tracked the chosen level in state. Its send() now builds the turn request from that level via the shaper and emits it through a new onSubmitTurn seam. The live socket that POSTs the request is a separate child (T12), so until it wires onSubmitTurn the composer still appends the counsel's message locally (proving thread continuity) while the request shape — carrying the chosen thinking_level — is built on every send. The seam is named, not hidden.

The cost hint — legible, never a price

RFC §F asks the expensive tiers to be legible so counsel chooses deliberately. The Max and Ultra Max tier hints now carry a qualitative cost step ("higher cost", "Frontier · highest cost") in both en and hi. This is a tier hint, not a model name, provider, or live price — the exact model/cost stays in audit provenance, off this surface (ADR-129 D2).

Verified

pnpm lint clean, pnpm build (TypeScript) green — including the totality guard that proves the array covers the whole generated enum — and pnpm test all 687 passing, with five new tests on the turn-request shaper (including the generated-schema parse). The existing reasoning-pill and composer Storybook stories continue to render the levels and tier hints with no model/price copy. Per the Story Process, the Project #2 board was not touched.

What shipped

• src/components/agents/agent-descriptor.ts — ReasoningLevel now aliases the generated ThinkingLevel; REASONING_LEVELS gains a compile-time totality guard.
• src/components/agents/atlas-descriptor.ts — default reasoning level high → medium (the agent's declared default, RFC §E).
• src/lib/agents/turn-request.ts — new pure shaper putting the chosen level at context.providers.posture.thinking_level.
• src/components/agents/agent-dock-mount.tsx — send() builds the turn request and emits it through the onSubmitTurn transport seam (T12).
• src/lib/agents/__tests__/turn-request.test.ts — five tests, incl. parsing the built envelope through the generated contract schema.
• messages/en.json + messages/hi.json — quiet cost-tier hints on Max / Ultra Max (both locales).

Files changed

7 file(s), +194 / -13 lines