fix: reject unavailable explicit models
Issue for this PR
Closes #1800
Type of change
- Bug fix
- New feature
- Refactor / code improvement
- Documentation
What does this PR do?
Summary. An explicitly requested model the provider can't serve used to be silently replaced. That covers the run flag, project or agent config, a command, or a resumed session. Now the request fails, naming the model's source; config-file advice appears only when a config setting chose the model. Work that doesn't use that model keeps running: shell, direct MCP admin, a resumed session with a usable model, a command with its own model. Branded project config files load beside the legacy names, so a root altimate-code.json that main ignored now applies. This affects users with a stale or mistyped model; valid setups are unchanged. On first start the TUI moves TUI keys from branded root configs into the TUI config, with a backup.
Details.
- Only the effective model is validated. Order: command, command agent, request, agent, session history, config
model, automatic (documented in models.md). Command subtasks run on the model validated at dispatch. Helpers that only need a provider (prompt enhancement, copy naming) keep working when the configured model is stale. - Each guided error is published once. The async prompt route skips its second error only for errors already reported. An explicit subtask model, and a subagent's configured model, are reported with their own source.
- The sync prompt route returns 400 for an unavailable model and keeps 404 and busy-session statuses; other failures during a turn keep main's empty 200 plus the session error event.
- Shell and MCP rows record a display-only model. Session resolution, plan exit and ACP restore skip those rows and replies to them.
- The TUI reads
tui.jsonfrom.altimate-code/too; migration follows each loader's precedence (project, config dirs, global, managed). - TUI: a submit waits for the agent and command lists, each tracked per workspace and reloaded when the workspace changes. A failed command list shows an error and retries. Only model-backed submits wait for models. Rejected drafts stay editable, and edits cancel a deferred submit. Enhancement inserts pasted text literally. Picks and effort belong to their conversation, matching the server's selection order: with
--modelormodelconfigured, a new conversation starts on that model, where main carried a pick into new conversations during the same launch. As before, picks are not persisted across restarts (documented in models.md). An empty model value (often an unset${VAR}) is rejected with a hint to set the variable or remove the key. A new user with an unavailable configured model sees the error and the model picker, and keeps the draft.
Known follow-up (not in this PR): other prompt failures on the synchronous route still answer an empty 200 as on main; giving them real statuses needs run retry and TUI toast changes together.
How did you verify your code works?
- A local Claude review ran after each push. It found no P0 or P1, and its valid P2/P3 findings are fixed.
- CLI process suite (real server, loopback LLM): rejection from each source, command and subtask models, resume, shell and MCP admin with an unavailable default, and a single async error (fails without the fix). TUI prompt/sync/context and opencode config/provider/error suites, typecheck and markers pass.
- 11 local failures in untouched dialog tests; they pass in CI.
Cost side effects
None.
Screenshots / recordings
Unavailable configured model on submit (new home dir, a usable cloud provider, project model = missing-provider/missing-model). Before = 87e06a4, after = eda34f9. No message was sent to a model.
Before (recording):
https://github.com/user-attachments/assets/ef00ace2-baed-406b-acce-19c2632628a2
After (recording):
https://github.com/user-attachments/assets/72e1b0c0-3be2-4f9c-926a-25bf8afb7703
Checklist
- I have tested my changes locally
- I have not included unrelated changes in this PR
- I checked for cost side effects and described them
🤖 Generated with Claude Code
[!NOTE]
Medium Risk
Touches model resolution across server session entry points, CLI run, TUI submit, and ACP restore—behavior changes for stale or mistyped models but is heavily tested.
Overview
Explicit model selections now fail fast instead of silently falling back when the provider cannot serve them. Validation runs along a documented precedence chain (command → agent → CLI/request → session history → config model → automatic). Errors include where the model came from and config-file hints only when a config setting chose it; shell, /mcps, and similar paths can still run with display-only model metadata.
Config and session behavior is aligned with branded project files: altimate-code.json / .jsonc load with the same precedence rules as legacy opencode.*, including TUI key migration from .altimate-code/. ACP resume/fork, plan exit, and TUI prompt restore skip shell/MCP rows (and assistant replies tied to them) so they do not override the real chat model. run preflights fresh starts, preserves command-selected models for follow-ups and time-budget nudges, and surfaces guided ModelNotFoundError text. The sync prompt route returns 400 for unavailable models; async routes avoid duplicate session error events via ModelReport / ModelMetadata.
The TUI submit path waits for agents/commands, validates the effective model before sending, opens the model picker when the configured chat model is missing, and keeps the draft editable. defaultModel() and related helpers that only need a provider (e.g. prompt enhance, copy naming) degrade more gracefully when the configured model is stale.
Reviewed by Cursor Bugbot for commit 9deb719da5bc2fce243684957794fbd1f2fdeb26. Bugbot is set up for automated code reviews on this repo. Configure here.