Build first-class dreb web dashboard

[aebrer]

Closes #307

Sets up planning for a first-class dreb web dashboard: a first-party browser UI/server for projects, sessions, chat parity, subagents, settings, and safe localhost/Tailscale access.

Implementation plan posted as a comment below.

[aebrer]

Implementation Plan

Problem analysis

Issue 307 asks for a first-party dreb web dashboard, not a Pi dashboard fork. The dashboard needs to be a real alternate frontend for dreb: project/file browsing, cross-project session management, chat controls with practical TUI parity, live background subagent visibility, settings, responsive desktop/mobile UI, and a safe access model where same-machine localhost is frictionless but any other device is gated through Tailscale identity plus short-lived PIN pairing.

The current codebase already has the right core seams:

• AgentSession is the frontend-neutral runtime/event source.
• SessionManager owns JSONL session persistence, tree metadata, cross-project listAll, and session restore primitives.
• RPC mode exposes prompt/steer/follow-up/abort/state/session/model commands and streams AgentSessionEvent values.
• Telegram is the closest first-party non-TUI frontend precedent: a separate workspace package using @dreb/coding-agent/rpc rather than embedding TUI internals.

The largest new surface is not the agent runtime; it is the web server boundary: authentication, file APIs, browser state, session/runtime pooling, and safe remote access.

Deliverables

1. New first-party dashboard workspace

   • Add a new packages/dashboard workspace package with a dreb-dashboard bin.
   • Keep it separate from packages/coding-agent so browser/server dependencies do not bloat the core CLI package.
   • Use @dreb/coding-agent/rpc as the initial runtime boundary, matching the Telegram isolation pattern.
   • Add package build/test scripts, TypeScript config, asset copying, root build integration, Vitest workspace integration, and any required package-lock updates.

2. Dashboard server backend

   • Serve static browser assets and a small authenticated HTTP API.
   • Provide an event stream endpoint for live session events, likely SSE plus REST commands rather than WebSocket unless implementation proves SSE insufficient.
   • Manage a pool of active dreb runtimes keyed by project/session instead of hot-swapping unrelated projects inside one long-lived AgentSession.
   • Spawn child dreb RPC processes with --ui dashboard so system-prompt/frontend context is explicit.
   • Fail loudly on RPC child startup, process exit, invalid commands, unavailable projects, and settings validation errors.

3. Access control and pairing

   • Default bind should be localhost-only.
   • Same-machine loopback requests are allowed without pairing friction.
   • Non-loopback access must be explicitly enabled and must pass a Tailscale identity/device allowlist check before any dashboard control is granted.
   • Tailscale identity resolution should fail closed when Tailscale is unavailable, the source is not a Tailnet peer, or identity cannot be verified.
   • First browser/device login over non-loopback access requires a short-lived host-generated PIN shown in server logs or host UI output.
   • Persist paired browser/device grants separately from provider credentials, with expiration/revocation-ready metadata.
   • Do not trust arbitrary LAN reachability, public unauthenticated binding, or caller-supplied identity headers by default.

4. Project and file API

   • List configured browse roots and folder contents.
   • Open/select a folder as a project context.
   • Upload files to a selected folder.
   • Download files from the host.
   • Enforce path normalization, realpath checks, traversal rejection, symlink escape rejection where roots are constrained, upload size limits, and explicit errors.
   • Keep file browse/upload/download separate from model tools so human dashboard operations do not depend on agent tool execution.

5. Session API and runtime pool

   • List sessions across projects using SessionManager.listAll() for dashboard history.
   • List sessions for a selected project.
   • Create a new session in a selected project.
   • Open/resume a prior session by path, starting or reusing a runtime with the correct cwd.
   • Expose session metadata needed by the UI: cwd, model, thinking level, session id, session path, display name, timestamps, message count, status, and last activity when available.
   • Avoid pretending switch_session safely changes project context inside a runtime whose resources were loaded for a different cwd.

6. Chat and event model

   • Define dashboard DTOs/reducers for the event stream instead of reusing terminal rendering components.
   • Support prompt, steering, follow-up, abort, retry/compaction state, model/thinking controls where RPC already supports them.
   • Render user/assistant messages, streaming text, thinking/status, tool calls, tool results, bash results, errors, task lists, suggest-next events, and extension UI requests supported by RPC.
   • Load historical messages with get_messages/session context on open, then apply live events.
   • Preserve important TUI semantics such as queued steering/follow-up behavior and visible non-error status notifications.

7. Live subagent visibility

   • Track and display background_agent_start, background_agent_end, and parent_paused_for_background_agents events.
   • Show agent id, agent type, task summary, parent session, status, and completion/error state.
   • Make it clear when other background agents remain running.
   • Preserve the parent-session synthetic completion-message flow while adding dashboard-specific live visibility.

8. Settings tab

   • Expose model/provider/runtime settings that already exist in SettingsManager and RPC model APIs.
   • Include explicit validation and user-visible errors for invalid provider/model/thinking/settings values.
   • Start with settings that already have well-defined backend behavior: model selection, thinking level, steering/follow-up modes, auto-compaction, auto-retry, background-agent guardrail settings, and relevant dashboard auth/bind settings if those are stored locally.

9. Responsive browser UI

   • Implement a minimalist, dreb-native UI with project/session navigation, chat, subagents, and settings.
   • Use mobile-first layouts: collapsible sidebars/tabs, touch-friendly message controls, readable transcript, and clear active-session status.
   • Avoid Pi-specific protocols, Pi extension assumptions, and generic purple/orange AI-dashboard styling.

10. Documentation

• Add packages/dashboard/README.md and a dashboard doc under packages/coding-agent/docs/.
• Update root README.md package/interface sections.
• Update packages/coding-agent/README.md interfaces/programmatic usage sections.
• Document localhost-only use, Tailscale remote use, identity allowlisting, PIN pairing, file API risks, terminal-access non-goal for MVP, launch commands, and troubleshooting.

Files to create or modify

• packages/dashboard/package.json — new workspace package metadata, bin, scripts, dependencies, files.
• packages/dashboard/tsconfig.json and packages/dashboard/tsconfig.build.json — package TypeScript config.
• packages/dashboard/src/index.ts — CLI entrypoint for dreb-dashboard.
• packages/dashboard/src/server/* — HTTP server, routing, static assets, config loading, auth middleware, event stream handling.
• packages/dashboard/src/auth/* — loopback detection, Tailscale identity resolver, allowlist checks, PIN pairing, paired-client storage.
• packages/dashboard/src/agent/* — RPC client resolution, runtime/session pool, command forwarding, event fanout, lifecycle cleanup.
• packages/dashboard/src/files/* — browse/upload/download APIs with path safety checks.
• packages/dashboard/src/sessions/* — cross-project and per-project session listing/open/create helpers.
• packages/dashboard/src/settings/* — settings read/update/validation helpers.
• packages/dashboard/src/client/* — browser TypeScript, state reducers, API client, SSE client, UI views/components.
• packages/dashboard/src/client/styles.css or equivalent — minimalist responsive styling.
• packages/dashboard/test/* — dashboard backend, auth, file, session, event reducer, and UI state tests.
• package.json — include dashboard in root build/dev flow as appropriate.
• tsconfig.json — add @dreb/dashboard paths and remove/adjust stale web-ui exclusion if needed.
• vitest.workspace.ts — include the dashboard Vitest project.
• biome.json — replace stale web-ui includes with dashboard includes and ensure client/server TS is checked.
• package-lock.json — update only through intentional npm install if the new workspace or dependencies require it.
• packages/coding-agent/src/cli/args.ts / packages/coding-agent/src/main.ts — only if adding a convenience launch surface or explicit dashboard UI hint requires CLI support beyond passing --ui dashboard to RPC children.
• packages/coding-agent/src/core/sdk.ts / exports — only if the dashboard needs a small shared helper for resolving the dreb CLI path or shared event types.
• README.md, packages/coding-agent/README.md, packages/coding-agent/docs/dashboard.md, packages/dashboard/README.md — user-facing docs.

Testing approach

Test coverage is required for every new behavior.

1. Dashboard package tests

   • Server startup/shutdown, route registration, static asset serving, and explicit startup errors.
   • Localhost access bypass works only for loopback addresses.
   • Non-loopback access is denied when remote mode is disabled.
   • Non-loopback access is denied when Tailscale identity cannot be verified.
   • Allowed Tailscale identities/devices can reach pairing, denied identities/devices cannot.
   • PIN generation, expiry, wrong PIN rejection, successful pairing, replay behavior, and persisted paired-client lookup.
   • File browse rejects traversal, absolute-path escape, symlink escape outside allowed roots, invalid upload paths, and oversized uploads.
   • File browse/upload/download happy paths operate within allowed roots.
   • Session listing uses cross-project and per-project sources correctly and preserves cwd/session metadata.
   • Runtime pool starts one RPC child for the correct cwd/session, reuses safe matches, separates unrelated projects, forwards lifecycle errors, and cleans up.
   • Prompt, steer, follow-up, abort, model/thinking, and session commands map to RPC calls correctly.
   • SSE event fanout sends ordered events to connected clients and removes disconnected listeners.
   • Subagent events update live subagent state and retain parent-session linkage.
   • Settings updates validate allowed values and fail loudly on invalid input.
   • Client-side reducers render/update all required event categories: streaming assistant text, tool calls/results, errors, thinking/status, task lists, suggest-next, and subagent lifecycle.

2. Existing coding-agent tests to extend if touched

   • packages/coding-agent/test/args.test.ts if CLI launch or mode parsing changes.
   • packages/coding-agent/test/rpc.test.ts and packages/coding-agent/test/rpc-client-spawn.test.ts if RPC commands/types/client helpers change.
   • packages/coding-agent/test/sdk-session-manager.test.ts if shared SDK/session helpers change.
   • Relevant settings tests if dashboard-exposed settings require new SettingsManager validation helpers.

3. Validation commands

   • Run targeted Vitest suites during development.
   • Run npm run build after code changes before manual testing with built binaries.
   • Run npm test before handoff.
   • Run npm run check or at minimum tsgo --noEmit plus Biome on touched files before pushing final implementation.
   • Verify workspace links with npm run verify-workspace-links if dependencies or workspace wiring change.

Acceptance criteria

• A first-party dashboard package exists in the monorepo and builds with the workspace.
• The dashboard can be launched from source via the documented command and serves a browser UI locally.
• Same-machine localhost use works without Tailscale or PIN friction.
• Non-localhost access is unavailable by default and, when enabled, requires verified Tailscale identity/device allowlisting plus PIN pairing before dashboard control.
• The dashboard does not expose unauthenticated LAN control.
• Users can browse allowed host folders, open/select a project folder, upload files, and download files.
• Users can list sessions across projects, create a session in a selected project, open/resume prior sessions, and see session metadata.
• Users can interact with a session through chat controls for prompt, steering/follow-up, and abort.
• Core TUI event categories are visible in the browser: assistant/user messages, tool calls/results, errors, thinking/status, task updates, suggest-next, and background-agent lifecycle.
• Background subagents are visible as live work units with parent-session context and completion/error state.
• Model/runtime settings exposed by existing config/RPC systems are available with explicit validation errors.
• The UI is intentionally responsive on desktop and mobile.
• Documentation explains launch, local-only mode, Tailscale remote mode, PIN pairing, security implications, file-transfer risks, and supported workflows.

Risks and open questions

• Tailscale identity source: implementation needs to choose and test a reliable identity mechanism, likely local Tailscale API or CLI lookup, and must fail closed if unavailable.
• HTTP security boundary: file upload/download and agent control are powerful; defaults must prevent accidental LAN/public exposure.
• Session/project switching: current RPC switch_session is safe for same-cwd session switching, but cross-project dashboard control should use separate runtimes with correct cwd/resource loading.
• Fresh empty sessions: session files may not flush until assistant output exists, so the dashboard may need in-memory tracking for newly created empty sessions.
• Extension UI parity: RPC supports a subset of extension UI requests; full custom TUI components are not directly portable and should be documented as unsupported or mapped deliberately.
• Dependency/tooling scope: a browser UI can easily pull in large frameworks. Prefer the smallest maintainable stack for the MVP unless a dependency clearly reduces risk.
• MVP size: this is a large feature. Implement in vertical slices that keep the dashboard usable and tested at each step, but do not leave any issue acceptance category unaddressed.

---

Plan created by mach6

[github-actions]

Vitest coverage

Metric	Covered	Total	Coverage
Statements	18708	35141	53.23%
Branches	10219	21869	46.72%
Functions	3018	5596	53.93%
Lines	16383	31044	52.77%

View full coverage run

[aebrer]

Progress Update

Implemented the first-party dreb web dashboard MVP:

• Added new @dreb/dashboard workspace package and dreb-dashboard bin.
• Added Node built-in HTTP server with static assets, JSON APIs, and SSE event streaming.
• Added fail-closed dashboard auth: localhost bypass, opt-in remote mode, Tailscale identity/device allowlists, short-lived PIN pairing, and persisted pairing tokens.
• Added safe file APIs for roots, directory browsing, upload, and download with traversal/symlink escape checks and size limits.
• Added session listing and RPC runtime pool for per-project/session dreb runtimes using --ui dashboard.
• Added vanilla responsive browser UI for auth pairing, files, sessions, chat controls, runtime state/messages, live events, tasks, suggest-next, subagents, and model/thinking/mode settings.
• Added dashboard backend/client tests and documentation updates in root README, coding-agent README, dashboard docs, and package README.
• Integrated dashboard into root build/dev scripts, TypeScript paths, Vitest workspace, Biome config, and package lock.

Validation run:

• npm --prefix packages/dashboard test
• npm --prefix packages/dashboard run build
• npm run build
• npm test
• npm run check
• npm run verify-workspace-links

Commit: 2d68a8f

---

Progress tracked by mach6

[aebrer]

Closing this draft PR without merging.

The implementation jumped too far ahead. The dashboard work needs a dedicated UX/UI design pass first so the product shape, mobile layout, interaction model, and security-sensitive flows are clear before another implementation attempt.