feat: [routing] send altimate routing hint and register altimate-auto (Phase 0a client)

[anandgupta42]

Issue for this PR

Closes # (no issue; first slice of the gateway model-routing plan, docs/internal/2026-09-22-gateway-model-routing-research.md, Phase 0a)

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

The gateway cannot tell what kind of LLM call it is serving: every request from the CLI carries the same model id and no hint about whether it is a main agent turn, a subagent, a title, a compaction or a skill-selection call. That blocks any routing decision on the gateway side and it also blocks joining gateway traces to CLI outcomes. This PR adds the client half of the plumbing.

• Sends metadata.altimate = { task_kind, agent, tools, session_pos, message_id } in the request body for the altimate-free and altimate-backend providers only. It rides @ai-sdk/openai-compatible 2.0.41's providerOptions passthrough (verified in the SDK source: getArgs spreads providerOptions[providerId] into the body, filtering only four known keys). It is injected in LLM.stream rather than ProviderTransform.options because small: true calls (title, enhance, project-copy) use smallOptions and never reach options.
• Stamps task_kind at each call site: main / subagent / summary (shared processor call, branched on parentID and agent name), title, compaction, skill_select, enhance, review, project_copy; everything else is other. message_id is the assistant message id, the same id the generation telemetry event records, so gateway traces and CLI telemetry join on it; processor-less call sites omit it rather than send a throwaway id. tools is clamped to 512 and agent is validated before sending because the gateway drops invalid keys silently.
• Registers altimate-auto beside altimate-base under the free provider, behind ALTIMATE_AUTO_MODEL=1 (default off). The gateway on main still returns 403 for any model other than altimate-base, so the flag stays off until the gateway's Phase 0a alias lands. When the flag is off the model is not registered at all. Default model selection is unchanged. The three id.includes("altimate-base") checks in transform.ts become an exact-match isAltimateManagedModel helper.
• Skill selection now uses the session's model when that model is Altimate-managed instead of Provider.defaultModel(). Enhance-prompt and the review AI lane are unchanged because their call chains carry no session; documented in code.

Sending the hint before the gateway change is deployed is safe: today's gateway _strip_client_params removes client metadata without rejecting the request.

How did you verify your code works?

• New tests in test/session/llm.test.ts drive the real LLM.stream → ProviderTransform → @ai-sdk/openai-compatible → fetch path against a local Bun.serve server and assert the outgoing /chat/completions body: hint present with the right fields for the backend provider, the small: true free-provider path, other default, and no metadata key for a non-Altimate provider.
• test/session/processor-effect.test.ts: a real main turn asserts the hint's message_id equals the assistant message id used by the generation telemetry event.
• test/provider/provider.test.ts: altimate-auto absent by default and present with the flag (subprocess env test plus in-process registration test).
• test/altimate/skill-filtering.test.ts: Altimate session model bypasses defaultModel(); non-Altimate still falls back.
• From packages/opencode: bun run typecheck clean; bun test on the 17 touched/related files: 932 pass, 17 skip, 43 todo, 0 fail. bun run script/upstream/analyze.ts --markers --base origin/main --strict: all custom code in upstream-shared files properly marked.
• Not verified: no live run against the gateway (the gateway change is a separate PR in altimate-gateway); e2e suite not run. One pre-existing, order-dependent Effect fiber-cleanup flake in processor-effect.test.ts was observed once in a large combined run and reproduces on the unmodified test when isolated; it is not caused by this change.
• Reviewed by Codex (two passes); the second pass's blocker (Auto visible before the gateway accepts it), the telemetry join key and the marker gaps are fixed in the second commit.

Screenshots / recordings

Not a UI change. The model picker shows "Altimate Auto" only when ALTIMATE_AUTO_MODEL=1.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

🤖 Generated with Claude Code

---

Summary by cubic

Adds the client half of the Altimate gateway model-routing work: requests to altimate-free and altimate-backend now carry a metadata.altimate hint describing the call, and a new altimate-auto model becomes available behind a default-off flag.

What changed

• Sends metadata.altimate with task_kind, agent, tools, session_pos, and message_id (matching the generation telemetry event id) for Altimate-managed requests only; other providers are untouched.
• Tags each call site (main, subagent, title, summary, compaction, skill_select, enhance, review, project_copy), defaulting to other when unstamped.
• Registers altimate-auto as a pickable model under altimate-free only when ALTIMATE_AUTO_MODEL=1 (default off).
• Skill selection now reuses the session's Altimate-managed model instead of resolving Provider.defaultModel().

Rollout

• Sending the hint is safe against the current gateway, which strips client metadata without rejecting the request.
• Enable ALTIMATE_AUTO_MODEL only after the gateway’s Phase 0a alias change ships; until then, altimate-auto requests return 403.

^{Written for commit b041cd6. Summary will update on new commits.}

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

- - - - - - - - - - - - - - - - - - - - - - - - -
                    AIRECEIPTS                    
             1 session behind this PR             

claude-sonnet-5.........................≥ $35.0021
  session slice: turns 1–348 of 355
--------------------------------------------------
TOTAL priced............................≥ $35.0021
  standard API-equivalent floor; not an invoice
  counted: 1 session
  cache served >99% of input tokens

1 candidate session not attributed
(in repo + branch window, no branch commit)

1 session made git writes that could not be anchored
(see docs/trust.md)
  full receipts + session ids: section below
- - - - - - - - - - - - - - - - - - - - - - - - -
                npx aireceipts-cli                
         github.com/anandgupta42/receipts         
- - - - - - - - - - - - - - - - - - - - - - - - -

full receipts (1 session)

session	id	scope	turns	time	tokens in / out	cached
builder	fd8fad7c	turns 1–348 of 355	348	1h 05m	696 / 185k	>99%

builder · fd8fad7c

- - - - - - - - - - - - - - - - - - - - - - - - -
                    AIRECEIPTS                    
   Claude Code · Sep 22 2026 21:16 UTC · 1h 05m   
               claude-sonnet-5 100%               
        cache served >99% of input tokens         

pre-edit: 10% of priced floor (62/348 turns)
  (share before the first named edit tool)

Bash.......................≥ $24.8797  (253 calls)
Edit.........................≥ $5.2350  (48 calls)
Read.........................≥ $4.1190  (46 calls)
SendMessage...................≥ $0.2662  (2 calls)
(thinking/reply)..............≥ $0.2182  (2 turns)
Write..........................≥ $0.1835  (1 call)
ToolSearch.....................≥ $0.1002  (1 call)
--------------------------------------------------
TOTAL...................................≥ $35.0018
standard API-equivalent floor; not an invoice
same tokens on claude-haiku-4-5.........≥ $11.6673
  (67% lower observable floor)
  (arithmetic, not a prediction)
- - - - - - - - - - - - - - - - - - - - - - - - -
                npx aireceipts-cli                
         github.com/anandgupta42/receipts         
- - - - - - - - - - - - - - - - - - - - - - - - -

Generated by aireceipts

[github-actions]

👋 This PR was automatically closed by our quality checks.

Common reasons:

• New GitHub account with limited contribution history
• PR description doesn't meet our guidelines
• Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.