# Flynn Web UI / Control Dashboard

**Date:** 2026-02-07
**Priority:** P7
**Status:** In Progress

## Overview

Upgrade the existing minimal web UI (`src/gateway/ui/`) into a proper control dashboard with:
1. **Dashboard** — system health, sessions, tools, channels, usage stats
2. **Chat** — real-time streaming chat with token-by-token content, session management
3. **Sessions** — browse/switch/delete sessions, view history
4. **Settings** — view/edit configuration, manage channels, view/edit hooks

## Architecture

### Tech Stack

- **No build step** — vanilla HTML/CSS/JS (consistent with existing UI)
- **SPA routing** — hash-based (`#/`, `#/chat`, `#/sessions`, `#/settings`)
- **WebSocket** — reuse existing JSON-RPC protocol for all data
- **CSS** — extend existing `style.css` design system (dark theme, design tokens)
- **Marked.js** — CDN for markdown rendering (already used)
- **Highlight.js** — CDN for syntax highlighting in code blocks

### File Structure

```
src/gateway/ui/
├── index.html          # SPA shell (nav + router)
├── style.css           # Extended design system
├── app.js              # SPA router + WebSocket client
├── pages/
│   ├── dashboard.js    # Dashboard page
│   ├── chat.js         # Chat page
│   ├── sessions.js     # Sessions browser
│   └── settings.js     # Settings page
└── lib/
    └── ws-client.js    # WebSocket RPC client (shared)
```

### Backend Changes

1. **`content` streaming events** — `agent.send` should emit `content` events with text chunks as the model generates them. Currently only emits `tool_start`, `tool_end`, `done`. Requires wiring the model client's streaming iterator through the agent.

2. **New gateway methods**:
   - `sessions.delete` — clear a session's history
   - `sessions.switch` — switch the connection's active session
   - `system.channels` — list active channel adapters and their status
   - `system.usage` — aggregated usage stats (tokens, cost)
   - `config.channels` — channel-specific configuration view

3. **Static file serving** — extend `static.ts` to serve `.js` files from subdirectories (already supports `.js`, but need to handle nested paths under `pages/` and `lib/`)

4. **Content-type additions** — add `.png`, `.ico`, `.woff2` to `CONTENT_TYPES` in `static.ts` (for future assets).

## Implementation Phases

### Phase 1: Backend enhancements
- Add `sessions.delete` handler
- Add `sessions.switch` handler  
- Add `system.channels` handler
- Add `system.usage` handler
- Add streaming `content` events to `agent.send`
- Extend `static.ts` for nested paths
- Tests for all new handlers

### Phase 2: SPA shell + WebSocket client
- Rewrite `index.html` as SPA shell with hash router and nav
- Create `lib/ws-client.js` — promise-based RPC client with reconnect
- Create `app.js` — page router, WebSocket lifecycle

### Phase 3: Dashboard page
- Health cards (status, version, uptime, connections, sessions, tools)
- Channel status cards
- Usage summary (tokens, cost, calls)
- Auto-refresh on interval

### Phase 4: Chat page  
- Session selector dropdown
- New session button
- Real-time streaming text (token by token via `content` events)
- Tool events display (collapsible)
- Markdown rendering with syntax highlighting
- Session history loading on page entry
- Input area with send/cancel

### Phase 5: Sessions page
- Session list with message count, last activity
- Click to view session history
- Delete session button
- Session detail view with full message history

### Phase 6: Settings page
- Read-only config view (with redacted secrets)
- Editable hook patterns (confirm/log/silent)
- Channel status overview
- Tool list with descriptions

## Estimated Effort

- Phase 1: Backend — 1 hour
- Phase 2: SPA shell — 30 min
- Phase 3: Dashboard — 30 min
- Phase 4: Chat — 1 hour
- Phase 5: Sessions — 30 min
- Phase 6: Settings — 30 min
- **Total: ~4 hours**