Raven-1/ui-web/README.md
knqiufan ba3a3f8c54
fix: initialize the web composer with its configured model (#840)
## 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>
2026-10-19 21:50:30 +08:00

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