## Summary The web composer initially displayed hardcoded `minimax-m3` until a full provider catalogue finished loading, even when another model was configured. Read the actual model/provider selection immediately after the gateway handshake, independently of catalogue building and provider probes when the gateway supports it. - Add optional `model.options.include_providers` with its existing full-catalogue behavior as the default. Advertise selection-only support through `system.hello.server_capabilities`; older strict gateways receive their original parameters and share one full catalogue request. - Show loading, empty and retry states. Permit sending once the selection arrives, and keep a known selection usable during background refreshes of the same view. First reads and navigation to another session or a new draft still wait for that view's selection. - Allow settings role pickers to use their available rows while the composer's provider catalogue refreshes. Keep New Task available during selection loading or failure, retain provider-setup redirects, and clear catalogue loading state if a gateway call throws synchronously. - Preserve session bindings, forced default providers and staged draft picks. Ignore responses superseded by navigation or a local pick, and prevent slow catalogues from overwriting the selection. - Update fixtures, generated web/TUI contracts, bilingual messages and user-facing documentation. Maintainer follow-up on top of the author's commits (no history rewritten): - Restored the design comment in `model_options` that explains why a catalogue read warms the rate catalogue (the picker's context windows come from it and nothing else on the page refreshes it), and said why a selection-only read skips it. The handler and module docstrings now describe `include_providers`. - Restored the comment in `loadProviders` that explains why a late catalogue answer is dropped, now also naming a later refresh of the same view. - Reverted the remote CLI test change (`tests/test_subagent_cli_remote.py`), which was unrelated to this fix. The final diff no longer touches that file. The race it addressed is real and still open on main (see Risk), so it should land as its own change; the original commit remains in this branch's history. - A draft promoted to a conversation keeps its known selection. The promotion takes no new view ticket, so the first same-view re-read of the new conversation (a settings-changing tool result, a provider or default-model write, a typed id) used to drop the chip to "Loading model..." and refuse sends until that read answered. The promotion now hands the draft's selection to the session it minted, but only when that selection was read under the ticket the promotion began on; a reader who opened another conversation or a new draft during the create keeps that view's own selection, and a draft whose selection never arrived or failed still waits. The README says so. - Named the provider list as `ui-web/CONTEXT.md` does: the two keys this change added are now `gui.model.provider_catalogue_loading` and `gui.model.provider_catalogue_failed` (texts unchanged, generated TUI catalogue regenerated), and the `ModelSource` comment, the README and this change's test titles say provider catalogue instead of the bare word, which the existing `gui.model.catalogue_*` keys use for a vendor's model list. ## Type - [x] Fix - [ ] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed Maintainer verification on Linux, Python 3.12 (`--all-extras`), Node 26, in isolated worktrees with their own virtualenv and `npm ci`. "Merged tree" means this branch merged into the latest main without committing; it merges cleanly. Branch head: - `uv run --frozen --python 3.12 --all-extras pytest tests/test_rpc_model.py tests/test_rpc_schema_match.py tests/test_rpc_system.py -q`: 772 passed (238 in `tests/test_rpc_model.py` after the wording change). - `npx vitest run --maxWorkers=6 --testTimeout=20000` in `ui-web` (with `NODE_OPTIONS=--localstorage-file=...`, which this Node version needs): 4004 passed, 0 failed. - The promotion regression, `src/state/session/runtime.promote.test.ts` "the model chip across a promotion": eight cases on the real registry, promotion, chip source and store with only the transport faked, each run with and without the selection-only capability. The first-re-read case fails on the previous head (status `loading`, send refused) and passes with the fix. Removing the hand-off call fails exactly those two cases (179 of 181 model and promotion tests still pass); removing its ticket guard fails exactly the two cases where the reader left during the create. - `npm run type-check`, `npm run gen:check`, `npm run lint` in `ui-web`: pass, lint 0 errors and 4 existing warnings in untouched files. `npm run lint:rpc` and `npm run lint:i18n` in `ui-tui`: pass. - `scripts/check_commit_messages.py`, `scripts/check_large_files.py`, `scripts/check_source_language.py` over the branch, and `commitlint --from origin/main`: pass. Merged tree, this head on the latest main (as of #985), merged without committing: - Full `ui-web` vitest run as above: 4158 passed, 0 failed. `type-check`, `gen:check` and `lint` pass; `python ui-web/build.py` passes both boot snapshots (365 and 364 nodes). - `tests/test_rpc_model.py`, `tests/test_rpc_schema_match.py`, `tests/test_rpc_system.py`: 788 passed. `ui-tui` `lint`, `lint:rpc`, `lint:i18n`, `type-check`: pass. `ruff check`, `ruff format --check`, `lint-imports` (10 contracts kept), `deptry raven`, `ty check`: pass. Earlier merged-tree runs, before this round's two follow-up fixes (which change only web code, the README, i18n keys, test titles and one Python comment): - Full Python suite on the merge with main as of #1002, `uv run --frozen --python 3.12 --all-extras pytest -q`: 33222 passed, 102 failed. Rerun on bare main on the same machine, exactly those 102 test ids fail there too (this machine's environment), so no failure is introduced by this branch. An earlier full run of the merge, against main before #1002, also errored in the remote CLI cancel test; that test file is identical to main's, and whole-file runs of it on bare main failed 1 of 5 with the same race (see Risk). Real page, before this round's fixes, isolated gateways (own RAVEN_HOME, loopback only), headless Chromium, configured model `deepseek/deepseek-chat` with a dummy key, recording the chip text and the page's own `model.options` frames: - Main's page on main's gateway: the chip reads `minimax-m3`, enabled, from 198 ms until the full catalogue answers at 986 ms. This is the reported bug. - This page on this gateway: "Loading model..." (disabled) until the selection-only read answers about 100 ms after the handshake; the chip shows `deepseek-chat` at 593 ms while the 55-row catalogue answers at 1817 ms. - This page on main's gateway (no capability): only the legacy `{}` read is sent, no validation error, and the chip goes from "Loading model..." to the configured model when that read answers (706 ms). Earlier verification by the author on Windows, before the follow-up commits: `tests/test_rpc_model.py` and `tests/test_rpc_schema_match.py` 665 passed; the hello/ping/version/dispatcher subset of `tests/test_rpc_system.py` 26 passed; `ui-web/build.py` boot snapshots matched; `ui-web` `npm test` 3,278 passed across 215 suites, `gen:check`, `type-check`, `build` and `lint` passed; `ui-tui` `lint:rpc` and `lint:i18n` matched. ## Risk - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes The new read mode is read-only and returns no provider credentials. Existing RPC callers (the TUI picker and the ACP config options) omit the field and keep full provider catalogue responses; web clients negotiate support before sending it. A failed selection read requires a retry, while a pending refresh of a known selection, including the first re-read after a draft becomes a conversation, allows sending. Settings role pickers and task navigation no longer inherit the composer's loading restriction. Known behavior, not changed here: - Every navigation, including the boot's own switch to the draft view, waits for that view's selection, by design and as tested. On the real page this shows "Loading model..." again for about 90 ms right after the first selection appears. Against an older gateway each such wait lasts as long as the full provider catalogue read. - With the remote CLI test change removed, `test_a_cli_run_left_on_the_machine_when_this_computer_stops_is_picked_up_by_the_next_start` and its cancel sibling keep main's race: they wait for the pid file, then read the run record that may not be written yet. A parallel local run of the three RPC files plus that test file on this branch hit it once. It is the same flake main has today. Roll back by reverting this change and rebuilding the served web page; no configuration migration is required. ## Related Issues Fixes #819 --------- Co-authored-by: Codex <noreply@openai.com> Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
11 KiB
ui-web
The page raven serve hosts: one HTML file with the stylesheet and the whole
script inlined, plus a directory of icons beside it. dist/index.html is what
the wheel ships and what nginx serves in a container; nothing on the page
fetches a second script.
The conventions a change here follows -- the layering, the shape of a domain,
the store, the naming, the gates -- are CONTRIBUTING.md. The vocabulary is
CONTEXT.md.
Layout
| Path | What it is |
|---|---|
src/page.html |
the document skeleton: <head>, the two pre-JavaScript shells, and the two markers build.py splices into |
src/main.tsx |
the entry, a straight line: the page root, the listeners, the island roots, the transport, the boot |
src/App.tsx |
the page root: every region at the body, in one portal, in document order |
src/app/ |
the page's lifecycle, called once from main.tsx: the boot's ordered list, the wiring, the connection, the update watch, the splash |
src/rpc/ |
the typed gateway seam: the generated method contract, the gateway slot, the three transports and the offline fixture library under rpc/fixtures/ |
src/state/ |
the stores and tables every region reads (store.ts is the one store shape, sources.ts the data seam, pages.ts the page table), plus lang/ and session/ |
src/chrome/ |
the page's own furniture -- rail, chat header, dock, sheet rack, tooltip, chips and their popovers -- plus behaviour/, the two it installs rather than renders |
src/features/<domain>/ |
one domain per directory: its types.ts, source.ts, store.ts, <Domain>App.tsx and manifest.ts, plus its own wire.ts, mount.tsx or styles.css where it needs them. features/manifests.ts assembles those declarations and features/hosts.ts holds the three detached nodes a tab re-attaches |
src/components/ |
the small components more than one region renders |
src/lib/ |
helpers with no store and no page of their own (lib/dom.ts is the page's $) |
src/i18n/ |
t.ts: the lookup into the shared catalogue at the repo root |
src/test/ |
helpers and suites about the assembled page, and the region goldens under src/test/__golden__/ |
src/styles/page.css |
the page's own stylesheet -- the frame and the --z ladder -- inlined at /*__STYLE__*/. A domain's own rules live in its styles.css |
src/assets/ |
icons served from dist/assets |
scripts/ |
the seven tools: the client generator, the three artifact checks, the boot snapshot, the test harness and the gates' fixture call table |
scripts/gates/ |
the gates vitest runs over the tree, the stylesheet and the contract |
Nothing is published on window, and nothing outside the bundle reaches in: a
module imports what it calls, and the direction those imports may run in is
scripts/gates/import-direction.test.mjs. Where the direction forbids the
import -- src/state/ calling into a domain -- the call goes through a callback
the state module declares and the domain fills (state/page.ts's onShow,
state/settings.ts's onEnter).
Adding a domain
Seven steps, and which gate reddens for each omission:
CONTRIBUTING.md section 10.
Build
Two steps, in this order:
npm ci
npm run build # Vite -> .modern/modern.iife.js and .modern/domains.css
python3 build.py # splice into src/page.html -> dist/index.html, copy assets
They are separate because build.py must run where npm may not be on PATH:
the installer adds npm inside a subshell, and the python step is what the
release wheel and make build-ui call. build.py is three substitutions and a
copy -- every line of JavaScript the page runs comes from the one bundle, and
the one <style> block is styles/page.css followed by the domains' own
sheets, which Vite collects into .modern/domains.css -- and it ends by booting
the artifact in happy-dom twice: once on its fixtures (?stub=1), once in live
mode with no gateway answering, comparing each DOM shape against its golden
under scripts/__golden__/, so a structural regression fails the build rather
than the browser.
Develop
raven serve # start the gateway first, in another terminal
npm run dev # http://127.0.0.1:5173/src/page.html
The dev server serves src/page.html with hot reload and proxies /rpc,
/health, /auth, /file, /files, /knowledge/file and /oauth/callback
to the gateway, whose port it reads from ~/.raven/serve.json (18792 if there
is no record). Same origin, so the session cookie works: sign in once through
the proxied /auth page. Dev never produces a dist/ -- the artifact only
ever comes from the two build steps above.
Without a gateway, ?stub=1 runs the page against its own fixtures. So does
opening dist/index.html from disk.
Model initialization
The composer's model chip shows "Loading model..." until the gateway reports
the configured default or the open conversation's model. Reading that
selection does not build the provider catalogue or probe provider endpoints.
Once the selection arrives, sending a message can proceed while the model
list continues loading in the background. Gateways announce this read mode as
model.options.selection_only in system.hello.server_capabilities. For older
gateways without that capability, the selection shares the full provider
catalogue request and becomes usable when that response arrives. Opening the
picker during that load shows a short loading notice. A refresh in the same
conversation keeps its known selection usable, and so does a draft that has just
become a conversation, since that is the same view; navigating to another
conversation or a new draft waits for that view's selection. Settings role
pickers can still open from their available lists while the composer's provider
catalogue is refreshing. Loading the selection does not prevent opening a new
task.
If the selection or model list cannot be loaded, click the model chip to retry. An empty selection shows "Choose a model"; a failed read never shows a made-up model. A late response cannot replace a model chosen locally or the model of a conversation opened since the request started.
Checks
npm test # vitest: every unit suite and every gate
npm run type-check # tsc
npm run lint # eslint: import order, unused imports and locals
npm run gen:check # src/rpc/generated.ts matches the schema
node scripts/check-page.mjs # the artifact: one style, two inline scripts, no markers
node scripts/check-css.mjs
node scripts/check-class-namespace.mjs
The page checks read dist/, so build before running them. The two boot
snapshots run on their own, from build.py. The last two also run as gates
under npm test, so the inner loop covers them.
make lint-ui at the repo root is gen:check, npm run lint and type-check
in that order, matching lint-tui; the ui job in .github/workflows/ci.yml
runs the same three and then npm test.
Gates
npm test is one run over both trees, so the 38 gate suites under scripts/gates/
go with the unit suites. Each one's header says what it pins and why; the
conventions they are written to are CONTRIBUTING.md section 8.
| Gate | What it pins |
|---|---|
import-direction |
which way an import may point; every upward and cross-domain edge, and every runtime cycle, as shrink-only lists |
domain-shape |
the files a domain has and the name its root component exports |
domain-registration |
every domain declared once, every page claimed by one domain, every seam key answered by one |
store-shape |
one store shape and one set of verbs; the listener set lives only in state/store.ts |
state-dom-touch |
how often each module in state/ and app/ may reach for an element -- counted per match, the page's own $ included -- how often the page frame -- chrome/, App.tsx, main.tsx -- may, zero for lib/ and components/, and how many text, class and markup writes each of those files still holds |
seam-assignment |
only app/install.ts puts a source on the data seam -- under any name a file bound to it, and through a destructuring target or defineProperty too -- plus the first frame's one pinned exception, held to exactly one assignment; setSources stays the test seam, named nowhere else |
island-lang |
every island's root subscribes to the language store |
i18n-keys |
every literal key exists in the catalogue, sits under a namespace, and the namespace belongs to one domain |
first-frame-literals |
the words the page shows without a t(key) behind them -- the served first frame and today's literals -- counted per file as unbroken CJK runs, escaped or not, and shrink-only |
file-names |
what a file may be called: PascalCase components, camelCase modules, <module>.test.ts, kebab-case gates |
rpc-names |
every method name is in the contract, and every call inside features/ is in that domain's source.ts |
fixture-shape |
every offline responder answers the shape the contract declares, plus the fields it never sends |
offline-coverage |
every method the page calls has an offline answer, or a reason it does not |
fixture-now |
the offline library has no clock of its own |
check-class-namespace |
a domain's class names carry the domain's prefix, the page frame's carry chrome- and a shared component's carry its own file name -- however the class is written: a className attribute, a class attribute inside a string of markup, a classList call, or a className={...} expression; every .tsx belongs to one of the three namespaces, the shared, unprefixed and borrowed debts may only shrink, and a class the stylesheets do not define is pinned by name |
check-css |
the stylesheet's own declaration-level invariants |
boot-order |
the page defers its first data-driven paint until every source is installed |
first-run-model-setup |
a page with no provider configured sends every task action to Models |
permission-chip |
the permission chip mirrors every settings load |
rail-nav-registry |
every rail button a page can light is one the rail writes to |
pipeline-coverage |
every turn event the contract declares has a stage, and no stage names one it does not |
notifications-contract |
the notification table is the server's roster plus exactly one name |
provider-mark-assets |
every logo the provider map names is in the bundle, and every file is named |
agent-mark-css |
which agent marks the dark theme filters, and with which filter |
agent-fold-css |
the roster's fold slot keeps its width on a head that cannot fold |
rail-row-css |
the session row's height contract |
rail-sig-css |
every state the session row's tail slot can hold has a visible mark |
desk-header-css |
the pane header's two controls sit on one line |
desk-layer-css |
the three layers a drag puts on the desk, in order |
desk-reserve-css |
the chat's right inset while the anchored desk is over it |
desk-page-gate |
the desk is bound to the chat, by a stylesheet rule |
instance-composer-css |
a sub-agent's composer is the page's composer, one size down |
agents-roster-live |
what the desk's agent list is a list of, on the shipped wiring |
direct-chat-media-live |
the instance composer's send carries its attachments |