## Summary Reported by the owner on 2026-10-20, on the first day with #1007 on their site: the Ravenx card said "No agent connected here yet" while the machine's connect form greyed Claude Code as "already connected on this machine". Both were telling the truth by different rules. The card counted connected entries only (`agents_on_machine(only_enabled=True)`); the form, and `subagents.add`'s duplicate rule, counted every entry of the preset on the machine, switched off or not -- and the owner had just switched `Claude Code@ravenx` off. So a switched-off entry was counted nowhere on the card, blocked the form, and had no way back from the machine's side. What changes: - `machines.list` rows carry `agents_off_here`, the entries on the machine that are switched off (the connected ones stay in `agents_here`; both empty when the agents section or the config file cannot be read). The card line and the sheet field show them marked *switched off*. - `subagents.presets` now means by `on_machines` the machines a *connected* entry runs on, and adds `off_on_machines` (machine + entry name) for the switched-off ones. Both additive. - The connect form keeps greying a preset the machine has connected, but offers one it has switched off back under its own entry -- each switched-off entry as a choice of its own, by name, since a machine may hold several explicitly named ones: the option says *switched off*, the working-directory field is left out (the entry keeps the one it had), and the button reads **Reconnect**, which runs the agents page's own `subagents.toggle enabled=true` on that entry -- same proof ping, no second entry. The add is offered only while the machine holds nothing of the preset (the server refuses it otherwise). The Reconnect goes through the agents page's own `act`, so the row is marked joining for the length of the ping: that page draws it pending and cannot press its own Connect meanwhile, and the form, reading `joining` too, greys the entry the other way round -- one ping whichever side pressed. The card line and the sheet field read *N on this machine* / *Agents on this machine*, since they list switched-off entries as well. The write is guarded like the add (opening generation, drawer still current) and marked pending so a form reopened meanwhile does not offer it twice; a refusal stays on the form in the agent's words. - Docs: machines guide (en + zh), CHANGELOG, CONTEXT. ## Type - [x] Fix - [ ] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification - `pytest tests/test_rpc_machines.py tests/test_rpc_schema_match.py tests/test_rpc_registration.py -n 4`: 580 passed; `pytest tests/test_rpc_subagents.py tests/test_ops_connection_add.py tests/test_raven_config_tool.py -n 4`: 365 passed. The two extended cases (`agents_off_here` listed apart; `off_on_machines` carries the entry name while `on_machines` leaves it out) fail with the two handler changes stashed. - `ruff check` / `ruff format --check` on the changed Python files: clean. - ui-web: `vitest run src/features/extAgents scripts/gates`: 483 passed (5 new page cases: the third for two switched-off entries of one preset on one machine, each reconnectable in turn; the fourth and fifth for a toggle in flight from either side -- the agents page offers no Connect while the machine's Reconnect runs, and the form greys the entry and says why while the agents page's Connect runs -- both fail with the previous store/form; the switched-off preset is pickable and labelled, no directory field, Reconnect toggles the existing entry and lands back on the sheet with the lists re-read; a refused Reconnect stays on the form in the agent's words -- both fail with `MachineCards.tsx`/`store.ts` stashed; the card/sheet case extended with a switched-off entry). `tsc --noEmit`, `eslint` on the changed files, `gen:check` clean; `ui-tui` `lint:rpc` / `lint:i18n` clean. - `pytest tests/test_docs_site.py`: 16 passed; `mkdocs build --strict`: clean. - Full suite: see the comment on this PR. - Real page: see the comment on this PR. ## Risk - [x] Security impact considered: the new fields carry entry names already shown on the agents page; Reconnect is the existing toggle, with its proof ping and refusals. - [x] Backward compatibility considered: `agents_off_here` and `off_on_machines` are new fields (the page maps both defensively); `on_machines` narrows to connected entries, which only this page reads. - [x] Rollback path is clear for risky changes: revert the commit; nothing stored changes shape. ## Related Issues N/A (follow-up to #1007, from the owner's report on 2026-10-20) --------- Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
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 |