From 130711a377b24f11bbd11f61a5b459d295e16e51 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Sat, 7 Feb 2026 10:11:54 -0800 Subject: [PATCH] docs: update documentation for P7 web UI dashboard completion - README: add Web UI Dashboard section, update features list with all current capabilities (multi-channel, media pipeline, sandboxing, etc.), expand model providers table, update architecture diagram - CHANGELOG: add P7 entries (dashboard SPA, 4 new gateway handlers) - state.json: add P7 entry with all 6 phases and file lists, update overall_progress to reflect P0-P7 completion - web-ui-dashboard.md: mark as completed with detailed phase outcomes --- CHANGELOG.md | 16 +++- README.md | 63 +++++++++++---- docs/plans/2026-02-07-web-ui-dashboard.md | 94 ++++++++++++----------- docs/plans/state.json | 68 +++++++++++++++- 4 files changed, 183 insertions(+), 58 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d49a58..e349ab5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,18 @@ All notable changes to Flynn are documented in this file. ### Added +- **Web UI Dashboard (P7)** -- Full SPA control dashboard at the gateway web UI with + four pages: Dashboard (health stats, channels, auto-refresh), Chat (session selector, + streaming tool events, markdown rendering), Sessions (list, history viewer, delete), + and Settings (hook pattern editor, tool list, config viewer). No build step — vanilla + JS with ES modules, hash-based routing, and WebSocket JSON-RPC client with auto-reconnect. +- **Gateway: sessions.delete** -- New handler to clear a session's message history +- **Gateway: sessions.switch** -- New handler to switch a WebSocket connection to a + different session +- **Gateway: system.channels** -- New handler listing active channel adapters and their + connection status +- **Gateway: system.usage** -- New handler returning aggregated usage stats (uptime, + sessions, connections, tools) - **CLI Surface** -- Full command-line interface via `flynn` binary with 6 commands: `start`, `tui`, `send`, `sessions`, `doctor`, `config` - **Doctor Diagnostics** -- `flynn doctor` validates config, YAML parsing, schema, @@ -20,10 +32,12 @@ All notable changes to Flynn are documented in this file. ### Changed +- **Gateway Server** -- `GatewayServerConfig` now accepts `channelRegistry` for + channel status reporting; static file server supports `.mjs`, `.png`, `.ico`, `.woff2` - **Entry Points Refactored** -- `src/index.ts` and `src/tui.ts` now delegate to the CLI module (`src/cli/index.ts`) instead of directly starting the daemon/TUI - **Daemon Wiring** -- CronScheduler auto-registers in the channel registry when - `automation.cron` jobs are configured + `automation.cron` jobs are configured; channelRegistry passed to GatewayServer ## [0.1.0] - 2026-02-05 diff --git a/README.md b/README.md index 26feeba..269bfee 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,24 @@ Self-hosted personal AI assistant with Telegram and Terminal interfaces. ## Features -- **Multi-Frontend**: Telegram bot + Terminal UI (minimal & fullscreen modes) -- **Multi-Model**: Anthropic Claude, OpenAI, Ollama with intelligent routing +- **Multi-Frontend**: Telegram bot + Terminal UI (minimal & fullscreen modes) + Web UI dashboard +- **Multi-Model**: Anthropic Claude, OpenAI, GitHub Copilot, Gemini, Bedrock, Ollama, llama.cpp with intelligent routing +- **Multi-Channel**: Telegram, Discord, Slack, WhatsApp with unified adapter interface +- **Web Dashboard**: SPA control panel with health monitoring, chat, session browser, and settings editor - **Model Switching**: Switch between cloud/local models on demand - **Session Persistence**: SQLite-backed conversation history - **Fallback Chains**: Automatic failover when primary model fails - **Hook Engine**: Confirmation system for sensitive operations +- **Tool Framework**: Shell, file, web-fetch, web-search, browser control, image analysis, media send +- **Docker Sandboxing**: Per-session container isolation for tool execution +- **Multi-Agent Routing**: Config-driven agent selection per sender/channel with tool profiles +- **Media Pipeline**: Image analysis, outbound attachments, audio transcription across all channels - **Session Transfer**: Move conversations between frontends - **CLI**: Full command-line interface (`flynn start`, `send`, `doctor`, etc.) - **Cron Scheduling**: Automated messages on cron schedules with output routing - **Health Diagnostics**: `flynn doctor` validates config, connectivity, and system state +- **MCP Integration**: External tool servers via Model Context Protocol +- **Skills System**: Extensible capability packages (bundled, managed, workspace tiers) ## Quick Start @@ -96,7 +104,11 @@ hooks: |----------|--------| | Anthropic | `provider: anthropic`, `api_key` or `auth_token` | | OpenAI | `provider: openai`, `api_key`, optional `endpoint` | +| GitHub Copilot | `provider: github`, auto-login via OAuth device flow | +| Gemini | `provider: gemini`, `api_key` | +| Bedrock | `provider: bedrock`, AWS credentials | | Ollama | `provider: ollama`, `model`, optional `endpoint` | +| llama.cpp | `provider: llamacpp`, `endpoint` | ### Model Tiers @@ -121,6 +133,21 @@ models: | `/cloud` | Switch to cloud model | | `/model` | Show model info and options | +## Web UI Dashboard + +Flynn includes a built-in web control dashboard served by the WebSocket gateway. Access it at `http://localhost:18800` (or your configured gateway port). + +### Pages + +| Page | Description | +|------|-------------| +| **Dashboard** | System health cards, channel status, usage stats. Auto-refreshes every 10s | +| **Chat** | Session selector, streaming tool events, markdown rendering with syntax highlighting | +| **Sessions** | Browse all sessions, view message history, delete sessions | +| **Settings** | Edit hook patterns (confirm/log/silent), view tools, channels, and redacted config | + +The dashboard is a vanilla JS SPA with no build step — hash-based routing, ES modules, and the existing WebSocket JSON-RPC protocol. + ## Terminal UI ```bash @@ -278,22 +305,32 @@ Exit code is `1` if any check fails, `0` otherwise. Checks that depend on a vali ``` src/ +├── agents/ # Multi-agent routing +├── auth/ # OAuth flows (GitHub Copilot) +├── backends/native/ # Agent implementation + orchestrator +├── channels/ # Channel adapters (Telegram, Discord, Slack, WhatsApp, WebChat) ├── cli/ # CLI commands (commander) ├── config/ # YAML config + Zod validation -├── models/ # Model providers + router -├── backends/native/ # Agent implementation -├── session/ # SQLite persistence +├── context/ # Token estimation + compaction +├── daemon/ # Lifecycle management + routing +├── frontends/ +│ ├── telegram/ # Telegram bot +│ └── tui/ # Terminal UI (minimal + fullscreen) +├── gateway/ # WebSocket gateway + web UI dashboard +│ ├── handlers/ # JSON-RPC method handlers +│ └── ui/ # SPA dashboard (vanilla JS) +│ ├── pages/ # Dashboard, Chat, Sessions, Settings +│ └── lib/ # WebSocket RPC client ├── hooks/ # Confirmation engine -├── daemon/ # Lifecycle management -├── channels/ # Channel adapter abstraction -├── automation/ # Cron scheduler -├── gateway/ # WebSocket gateway + web UI ├── mcp/ # MCP tool server integration +├── memory/ # Persistent memory store +├── models/ # Model providers + router + media pipeline +├── prompt/ # System prompt templating +├── sandbox/ # Docker sandboxing +├── session/ # SQLite persistence ├── skills/ # Skill packages -├── tools/ # Builtin tools (shell, file, web) -└── frontends/ - ├── telegram/ # Telegram bot - └── tui/ # Terminal UI +├── tools/ # Builtin tools (shell, file, web, browser, process, media) +└── automation/ # Cron scheduler ``` ## Development diff --git a/docs/plans/2026-02-07-web-ui-dashboard.md b/docs/plans/2026-02-07-web-ui-dashboard.md index 729002d..7c1cda6 100644 --- a/docs/plans/2026-02-07-web-ui-dashboard.md +++ b/docs/plans/2026-02-07-web-ui-dashboard.md @@ -2,7 +2,7 @@ **Date:** 2026-02-07 **Priority:** P7 -**Status:** In Progress +**Status:** Completed ## Overview @@ -56,53 +56,61 @@ src/gateway/ui/ ## 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 1: Backend enhancements — DONE +- Added `sessions.delete` handler (clears session history) +- Added `sessions.switch` handler (switches WS connection to different session) +- Added `system.channels` handler (lists active channel adapters and status) +- Added `system.usage` handler (aggregated usage stats) +- Extended `static.ts` with `.mjs`, `.png`, `.ico`, `.woff2` content types +- Wired `channelRegistry` into `GatewayServerConfig` (duck-typed interface) +- Note: Streaming `content` events deferred — chat page works with `done` event containing full response -### 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 2: SPA shell + WebSocket client — DONE +- Rewrote `index.html` as SPA shell with sidebar nav and hash router +- Created `lib/ws-client.js` — promise-based JSON-RPC client with auto-reconnect, event streaming +- Created `app.js` — page router with lifecycle (render/teardown), connection status indicator +- Extended `style.css` with ~500 lines for SPA layout, sidebar, stats grid, chat, sessions, settings -### Phase 3: Dashboard page +### Phase 3: Dashboard page — DONE - Health cards (status, version, uptime, connections, sessions, tools) -- Channel status cards -- Usage summary (tokens, cost, calls) -- Auto-refresh on interval +- Channel status cards with colored dots +- Usage summary section +- Auto-refresh every 10 seconds -### 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 4: Chat page — DONE +- Session selector dropdown with new session button +- Load history button +- Streaming tool events (collapsible with spinner/checkmark) +- Markdown rendering with syntax highlighting (marked.js + highlight.js) +- Enter to send, Shift+Enter for newline, auto-resizing textarea +- Works with `done` event (full response), ready for future `content` streaming events -### 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 5: Sessions page — DONE +- Session list table with ID, message count, and actions +- Click to view full session history +- Delete button with confirmation dialog -### Phase 6: Settings page -- Read-only config view (with redacted secrets) -- Editable hook patterns (confirm/log/silent) -- Channel status overview -- Tool list with descriptions +### Phase 6: Settings page — DONE +- Editable hook patterns (confirm/log/silent) with save button via `config.patch` +- Tool list table with name and description +- Channel status grid +- Read-only redacted config JSON viewer -## Estimated Effort +## Files Created/Modified -- 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** +### New Files +- `src/gateway/ui/app.js` — SPA router +- `src/gateway/ui/lib/ws-client.js` — WebSocket RPC client +- `src/gateway/ui/pages/dashboard.js` — Dashboard page +- `src/gateway/ui/pages/chat.js` — Chat page +- `src/gateway/ui/pages/sessions.js` — Sessions page +- `src/gateway/ui/pages/settings.js` — Settings page + +### Modified Files +- `src/gateway/ui/index.html` — Rewritten as SPA shell +- `src/gateway/ui/style.css` — Extended with ~500 lines +- `src/gateway/static.ts` — Added content types +- `src/gateway/server.ts` — Added `channelRegistry` to config +- `src/gateway/handlers/system.ts` — Added `system.channels` and `system.usage` +- `src/gateway/handlers/sessions.ts` — Added `sessions.delete` and `sessions.switch` +- `src/daemon/index.ts` — Wired channelRegistry into gateway diff --git a/docs/plans/state.json b/docs/plans/state.json index 007aee4..d540c3d 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -537,6 +537,71 @@ } } }, + "p7-web-ui-dashboard": { + "file": "2026-02-07-web-ui-dashboard.md", + "status": "completed", + "date": "2026-02-07", + "summary": "Full SPA control dashboard: Dashboard (health, channels, auto-refresh), Chat (session selector, tool events, markdown), Sessions (list, history, delete), Settings (hook editor, tools, config viewer)", + "phases": { + "phase_1_backend_enhancements": { + "priority": "P7", + "status": "completed", + "description": "New gateway handlers (sessions.delete, sessions.switch, system.channels, system.usage), channelRegistry wiring, static file content types", + "files_modified": [ + "src/gateway/handlers/sessions.ts", + "src/gateway/handlers/system.ts", + "src/gateway/server.ts", + "src/gateway/static.ts", + "src/daemon/index.ts" + ] + }, + "phase_2_spa_shell": { + "priority": "P7", + "status": "completed", + "description": "SPA shell with hash-based router, sidebar nav, WebSocket RPC client with auto-reconnect, connection status indicator", + "files_created": [ + "src/gateway/ui/app.js", + "src/gateway/ui/lib/ws-client.js" + ], + "files_modified": [ + "src/gateway/ui/index.html", + "src/gateway/ui/style.css" + ] + }, + "phase_3_dashboard": { + "priority": "P7", + "status": "completed", + "description": "Dashboard page with health stats cards, channel status grid, usage summary, 10s auto-refresh", + "files_created": [ + "src/gateway/ui/pages/dashboard.js" + ] + }, + "phase_4_chat": { + "priority": "P7", + "status": "completed", + "description": "Chat page with session selector, new session, streaming tool events (collapsible), markdown rendering with syntax highlighting", + "files_created": [ + "src/gateway/ui/pages/chat.js" + ] + }, + "phase_5_sessions": { + "priority": "P7", + "status": "completed", + "description": "Sessions browser with list table, history viewer, delete with confirmation", + "files_created": [ + "src/gateway/ui/pages/sessions.js" + ] + }, + "phase_6_settings": { + "priority": "P7", + "status": "completed", + "description": "Settings page with hook pattern editor (save via config.patch), tool list, channel grid, redacted config viewer", + "files_created": [ + "src/gateway/ui/pages/settings.js" + ] + } + } + }, "earlier_plans": { "status": "completed", "summary": "Original design and implementation phases from 2026-02-02 to 2026-02-05", @@ -571,6 +636,7 @@ "p4_completion": "1/1 (100%) — multimodal media pipeline", "p5_completion": "1/1 (100%) — GitHub Copilot provider with auto-login", "p6_completion": "4/4 (100%) — enhanced media pipeline (image.analyze, outbound attachments, gateway attachments, audio transcription)", - "next_up": "All planned phases P0-P6 complete. Remaining gaps from feature analysis: Signal/iMessage/Teams channels, webhooks, onboard wizard, typing indicators for non-Telegram channels, session pruning, DM pairing" + "p7_completion": "6/6 (100%) — web UI dashboard SPA (dashboard, chat, sessions, settings)", + "next_up": "All planned phases P0-P7 complete. Remaining gaps from feature analysis: streaming content events for real-time chat, Signal/iMessage/Teams channels, webhooks, onboard wizard, typing indicators for non-Telegram channels, session pruning, DM pairing" } }