web

Overview ¶

Answering a gated tool from a non-TUI client (E-12b).

A tool call awaiting approval blocks in the orchestrator's waitForApproval until a MsgApprovalResponse arrives on pane.<paneid>.approval.response. The `approval_response` ws command (server.go) is the only thing that publishes one on behalf of the desktop UI, the browser UI and the phone.

client → server: approval_response {pane_id,request_id,decision,reason}
server → client: approval_error    {pane_id,request_id,error}

The error direction exists because the phone has no console: an approval that is silently dropped looks exactly like one that is merely slow, while the tool blocks for five minutes and is then rejected.

The agents board's READ path for clients that are not the terminal UI (design 025 §6, design 028, design 027 wave 1).

WHY THIS FILE HAD TO EXIST. agents-board is a PaneType, and a pane of that type never starts a shell (domain.IsShelllessPaneType) — so nothing ever writes into its output buffer and there is nothing on the wire for a renderer to draw. The TUI does not notice, because it BUILDS the board itself: buildPanePanel dispatches the pane type to buildBoardPanel, which reads a board.Store the TUI subscribes to directly. Every other client got the pane's buffer, which for a shell-less pane holds whatever happened to be there — observed live in the desktop app as a board pane showing a stale `##pane list --meta` dump from a command that had errored against it, while four agents were posting to that board and their posts arrived fine.

That is the worst shape a monitoring view can fail in: not blank, not an error, but PLAUSIBLE CONTENT that has nothing to do with the board. The operator's report was "I cannot see that the agent board is working" while the board was in fact working end to end.

THE READER ASKS THE RECORDER. This does not subscribe, and it does not open the board's KV bucket — it puts a board.Query to ABLA over NATS, exactly as `rysh board tail` does. See msg.BoardQuerySubject for the two reasons (design 026 §5.4, and F-23, where a second call site derived the bucket name itself and read an empty board that looked healthy). A web server that grew its own subscription would be a third copy of the board in a process that is not the recorder, and would go stale exactly when the daemon is busiest.

PULL, NOT PUSH, and that is a deliberate limit rather than an oversight. The board has no per-board change notification the server could forward, and adding a subscription here to synthesise one would be the third copy above. The client polls (AgentsBoardView) and the cost is bounded by the client count, not by the post rate.

Package web provides an embedded web server that mirrors the rysh TUI in a browser. It connects to the same NATS bus as the TUI, polls workspace snapshots, and pushes them to WebSocket clients. Commands from the browser are published back to NATS so the actor hierarchy processes them identically.

Parity API surface (web_electron_roadmap Phase 3, tasks W7–W10).

The Electron desktop app gets a handful of conveniences from its main process (`window.electronAPI`): env/platform info, workspace reads, voice transcription and shell tab-completion. In web mode there is no Electron main process — but the daemon this server runs inside owns the same data and the same Go engines, so each capability is served here instead:

W9  GET  /api/env             → is_web flag + platform + session + capability map
W8  GET  /api/workspaces      → current workspace + on-disk session registry
W10 GET  /api/voice/config    → public voice config (never the API key)
W10 POST /api/voice/transcribe→ audio body → transcript (internal/voice)
W7  ws   completion_get       → completion_result (internal/tui engine),
                                replied ONLY to the requesting client

All /api/* routes sit behind the same access-token middleware as the rest of the server (auth.go); nothing here widens the surface. Everything is read-only except transcription, which only calls the configured provider.

Control-dashboard surface (WS5, design 005 — tasks DB1–DB4).

This file adds the browser control plane on top of the read-only viewer in server.go:

• DB1 channel operations → MsgHumanoidChannelStart/Stop on humanoid.{name}.inbox (same messages ##humanoid channel start/stop send)
• DB2 pairing operations → MsgChannelPairApprove / MsgChannelAllow / MsgChannelPairList on humanoid.{name}.pairing (same subject the terminal ##humanoid pair commands ride, WS3 / design 003 §4.4), plus a live relay of MsgChannelPairRequest/QR/Status/ListReply into the WS hub
• DB3 humanoid operations → MsgHumanoidActivate/Deactivate on the registry inbox and MsgHumanoidSetGovernance / MsgHumanoidSetReplyMode on humanoid.{name}.inbox
• DB4 control gating → every MUTATING endpoint/action requires control mode; read/list endpoints stay available. Control mode is enabled by the RYSH_WEB_CONTROL environment variable (1/true/yes/on) read in NewServer — chosen as the least-invasive wiring so the two existing WorkspaceActor NewServer call sites need no changes — or programmatically via SetControl (tests, future `rysh web --control`). When control is enabled the HTTP listener is forced onto 127.0.0.1.

Terminal and web drive the SAME typed messages on the SAME subjects, so the two fronts cannot diverge (design 003 §4.4 / 005 G5).

Server-side embedded web panes for browser mode (web_electron_roadmap W12).

In the Electron app a web pane is a native WebContentsView overlaid on the pane. A plain browser tab cannot embed arbitrary third-party pages (X-Frame-Options / CSP) nor attach a debugger — so in web mode the server drives a HEADLESS Chromium (internal/cdp, the same engine behind rysh's browser automation) and streams JPEG frames + url/title to the pane over the existing /ws protocol:

client → server: webpane_open {pane_id,url,profile} · webpane_navigate
                 {pane_id,url} · webpane_back/forward/reload/close {pane_id}
server → client: webpane_frame {pane_id,url,title,screenshot}   (~1 fps)
                 webpane_error {pane_id,error}                  (fail visible)

Availability is advertised in /api/env capabilities.web_pane (needs a workspace root for the profile dir and a Chromium binary). When it is false, the renderer keeps its explicit "requires the desktop app" note — the capability degrades visibly, never silently.

Profiles: each rysh web profile maps to its own persistent user-data-dir under <workspace>/.rysh/browser-instances/webpane/<profile> — deliberately NOT the interactive-login profile dir (Chromium locks user-data-dirs, and a headed login browser may hold that lock).

Coordinate input forwarding for server-side web panes (E7 T1 / E-16).

The client renders webpane_frame's JPEG scaled to whatever size the pane happens to be, so a pointer event arrives in DISPLAY space while the headless page only understands its own CSS-pixel SOURCE space. Forwarding a display coordinate unmapped is the entire bug class here: a 1280x900 page shown at 640x450 puts every click at half the intended point.

client → server: webpane_input {pane_id,kind,x,y,display_width,
                 display_height,button,key,modifiers,delta_x,delta_y}
server → client: webpane_error {pane_id,error}   (fail visible, never a
                 silent no-op — see TestWebPaneUnavailableIsVisible)

x/y are relative to the top-left of the rendered FRAME IMAGE (not the pane), and display_width/display_height are that image's rendered size. The client therefore never scales coordinates itself; it reports what it drew and the server does the mapping against the source dimensions it published on the frame.