Handsome-wzw 615256bf90
fix(*): show a machine's switched-off agent entries, and reconnect them from its sheet (#1019)
## 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>
2026-10-20 16:48:09 +08:00
..

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