d1f69bfd37
Some checks failed
ci/woodpecker/push/ci Pipeline failed
Ratification draft (Jason, 2026-07-09) extending NORTH_STAR.yaml with NS-10..NS-13 and workstreams J/K/W/P/Q/X. Written against origin/main's fleet suite (F4/F6 anchors, H2 profiles, native backlog per ASM-1). Homelab is the trial environment (D12); USC/web1 adopts post-trial. See proposals/mosaic-platform-prd/README.md for the full decision record D1-D12. Not yet merged into NORTH_STAR.yaml — landing and card decomposition are the homelab orchestrator's mission. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3.5 KiB
3.5 KiB
PRD — webUI Fleet Control · Workstream W (realizes F6)
Status: DRAFT for ratification · Goals: W1–W3 · Upstream anchor:
PRD-fleet-suite.mdPhase F6 ("webUI hooks — stable JSON contract + terminate/attach(butt-in) surface") Confirmed gap: zero xterm/pty/tmux code inapps/webon either the old snapshot ororigin/main.
Mission
The user can pop in on any agentic tmux session from the web, and get a full top-down view of the system — fleet roster, health, work in flight, spend — without touching a terminal. This is the product surface for "user has ability to pop in on any agent session; full top-down view available."
Requirements
Attach service (W1)
| ID | Requirement |
|---|---|
| W-R1 | A gateway service exposes per-agent session streams over WebSocket: watch (read-only pane view, cannot type) and butt-in (interactive takeover), mirroring the existing CLI verbs mosaic agent watch/attach. |
| W-R2 | Authz is workspace-scoped through the product auth stack (BetterAuth/Authentik); watch and butt-in are separate grants; butt-in may be requires_approval per workspace policy (workstream P). |
| W-R3 | Every attach (watch or butt-in) is audited: who, which agent, when, duration. |
| W-R4 | Butt-in visibly flags the session to the agent runtime and other viewers (no silent takeover). |
| W-R5 | Contract is stable JSON + streaming frames per F6's "stable JSON contract" requirement, so TUI/CLI and webUI share it. |
Web terminal (W2)
| ID | Requirement |
|---|---|
| W-R6 | xterm.js view in apps/web wired to W1: session list → click → live pane; toggle watch↔butt-in per grants. |
| W-R7 | Reconnect-safe (network blips resume the stream), mobile-usable read-only view. |
Top-down dashboard (W3)
| ID | Requirement |
|---|---|
| W-R8 | Fleet dashboard: roster with per-agent state (systemd + tmux + heartbeat join, as fleet ps provides), current card/task, last activity, drift/boot-enable warnings. |
| W-R9 | Work-in-flight view: backlog cards by state with depends_on DAG rendering; advisory spend per card (NS-2/NS-5). |
| W-R10 | Operator controls: PAUSE kill-switch (NS-8), per-agent terminate (killswitch service), queue pause/resume — each gated + audited; destructive controls confirm. |
| W-R11 | Existing widget framework (AgentStatusWidget, OrchestratorEventsWidget, SSE proxy routes) is the starting point, upgraded to the fleet contract rather than rebuilt. |
Acceptance criteria
- From a browser (desktop + phone), the user watches a live coder-agent pane read-only, then butt-ins with the right grant, types a message, detaches; agent session continues; audit log shows both.
- Dashboard reflects an agent crash within one heartbeat interval; PAUSE flip halts dispatch within one tick (AC-NS-5) from the UI.
- A user without butt-in grant can watch but cannot type (enforced server-side).
Non-goals
- Replacing tmux as the session substrate (tmux remains the transport; web is a view).
- Cross-host federation of the dashboard (rides the existing federation workstream later, per upstream note "Phase 5 rides federation").
Assumptions
- ASSUMPTION: pty bridging terminates at the gateway on the fleet host (web1), not in
apps/web; Next.js only speaks WebSocket to the gateway. - ASSUMPTION: the jarvis-brain dashboard's node-pty/xterm work (
dashboard/server/terminal.ts) serves as reference implementation only; code is not ported wholesale into the multi-tenant product without the authz layer above.