Build first-class dreb web dashboard

README.md

@@ -2,7 +2,7 @@
 
 dreb is a hackable, open-source terminal coding agent and agent runtime for people who want to own their AI development workflow. It gives you a practical coding assistant today — tools, sessions, memory, model switching, subagents, and a polished TUI — while keeping the core flexible enough to reshape with skills, extensions, packages, custom providers, and alternate frontends.
 
-Use dreb if you want a coding agent that can run against direct APIs, coding subscriptions, proxies, cloud providers, local models, or your own provider code; if you want workflows such as issue-to-merge automation and multi-agent review to be inspectable and replaceable; or if you want an agent runtime you can embed in a CLI, an RPC process, an SDK integration, or a Telegram bot.
+Use dreb if you want a coding agent that can run against direct APIs, coding subscriptions, proxies, cloud providers, local models, or your own provider code; if you want workflows such as issue-to-merge automation and multi-agent review to be inspectable and replaceable; or if you want an agent runtime you can embed in a CLI, a browser dashboard, an RPC process, an SDK integration, or a Telegram bot.
 
 ## Why choose dreb?
 
@@ -16,7 +16,7 @@ Use dreb if you want a coding agent that can run against direct APIs, coding sub
 - **Codebase and web understanding.** dreb includes file, grep/find/ls, bash, web search/fetch, task tracking, skill invocation, and semantic `search`. Semantic search uses AST-aware chunks, embeddings, POEM ranking, memory indexing, and also ships as [`@dreb/semantic-search`](packages/semantic-search/) with an MCP server for other harnesses. The semantic search package requires Node.js 22+.
 - **Detailed usage tracking and performance logging.** dreb records per-session token usage, cost, context-window utilization, and rolling tokens-per-second performance in a local JSONL log (`~/.dreb/agent/performance.jsonl`). This data stays on your machine and can be queried via the TUI footer, Telegram `/stats`, or RPC for personal analytics and model comparison.
 - **Safety and reliability primitives.** Recent dreb-specific hardening includes secret output scrubbing, sensitive-file guards, destructive-command guards, resource diagnostics surfaced in-session, warning propagation, rate-limited web search across parallel subagents, and JSON/RPC protocol hardening. Dropped provider streams are retried (discarding the partial), and responses truncated at the model's output-token limit are retried with a larger token budget — failing loudly rather than returning a silently empty or truncated result.
-- **Multiple interfaces.** Run dreb as an interactive TUI, print/headless CLI, JSON event stream, RPC process, embedded [SDK](packages/coding-agent/docs/sdk.md), or [Telegram bot](packages/telegram/).
+- **Multiple interfaces.** Run dreb as an interactive TUI, first-party [web dashboard](packages/coding-agent/docs/dashboard.md), print/headless CLI, JSON event stream, RPC process, embedded [SDK](packages/coding-agent/docs/sdk.md), or [Telegram bot](packages/telegram/).
 
 ## Quick Start
 
@@ -108,6 +108,7 @@ Project context files (`AGENTS.md`/`CLAUDE.md`) are loaded at startup by walking
 The same agent runtime powers multiple surfaces:
 
 - **Interactive TUI** — the default terminal coding workspace.
+- **Dashboard** — `@dreb/dashboard` serves a first-party browser UI for projects, sessions, chat, files, subagents, and settings with localhost/Tailscale access controls.
 - **Print/headless CLI** — `dreb -p` for one-shot prompts, including piped stdin.
 - **JSON mode** — event stream for scripts and automation.
 - **RPC mode** — strict [JSONL stdin/stdout protocol](packages/coding-agent/docs/rpc.md) for non-Node clients and custom UIs.
@@ -142,6 +143,7 @@ See [FORK.md](FORK.md) for details.
 | [`@dreb/agent-core`](packages/agent/) | General-purpose agent runtime: tool loop, state, streaming, hooks, steering/follow-up queue semantics |
 | [`@dreb/tui`](packages/tui/) | Terminal UI library with differential rendering, markdown/syntax rendering, editor/input components, overlays, keybindings |
 | [`@dreb/semantic-search`](packages/semantic-search/) | Semantic codebase search engine with AST chunking, embeddings, POEM ranking, library API, and MCP server |
+| [`@dreb/dashboard`](packages/dashboard/) | First-party browser dashboard for dreb over the native RPC protocol, with localhost/Tailscale access controls |
 | [`@dreb/telegram`](packages/telegram/) | Telegram bot frontend for dreb over the native RPC protocol |
 
 ## License

biome.json

@@ -28,8 +28,6 @@
 			"packages/*/src/**/*.ts",
 			"packages/*/test/**/*.ts",
 			"packages/coding-agent/examples/**/*.ts",
-			"packages/web-ui/src/**/*.ts",
-			"packages/web-ui/example/**/*.ts",
 			"!**/node_modules/**/*",
 			"!**/test-sessions.ts",
 			"!**/models.generated.ts",

package.json

@@ -12,8 +12,8 @@
 	"scripts": {
 		"clean": "npm run clean --workspaces",
 		"sync-version": "bash scripts/sync-version.sh",
-		"build": "cd packages/tui && npm run build && cd ../ai && npm run build && cd ../agent && npm run build && cd ../semantic-search && npm run build && cd ../coding-agent && npm run build && cd ../telegram && npm run build",
-		"dev": "concurrently --names \"ai,agent,coding-agent,tui\" --prefix-colors \"cyan,yellow,red,magenta\" \"cd packages/ai && npm run dev\" \"cd packages/agent && npm run dev\" \"cd packages/coding-agent && npm run dev\" \"cd packages/tui && npm run dev\"",
+		"build": "cd packages/tui && npm run build && cd ../ai && npm run build && cd ../agent && npm run build && cd ../semantic-search && npm run build && cd ../coding-agent && npm run build && cd ../telegram && npm run build && cd ../dashboard && npm run build",
+		"dev": "concurrently --names \"ai,agent,coding-agent,tui,dashboard\" --prefix-colors \"cyan,yellow,red,magenta,green\" \"cd packages/ai && npm run dev\" \"cd packages/agent && npm run dev\" \"cd packages/coding-agent && npm run dev\" \"cd packages/tui && npm run dev\" \"cd packages/dashboard && npm run dev\"",
 		"check": "npm run verify-git-hooks && npm run verify-engines && biome check --write --error-on-warnings . && tsgo --noEmit",
 		"verify-git-hooks": "node scripts/verify-git-hooks.js",
 		"verify-workspace-links": "node scripts/verify-workspace-links.js",

packages/coding-agent/README.md

@@ -81,7 +81,7 @@ Or use a custom provider (corporate proxy, Bedrock, etc.) — see [Custom provid
 
 Then just talk to dreb. All 11 built-in tools are enabled by default: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`, `web_search`, `web_fetch`, `subagent`, and `wait`. Use `--tools` to restrict to a subset (e.g., `--tools read,grep,find,ls` for read-only). Three additional tools — `search`, `skill`, and `tasks_update` — are always active regardless of `--tools`. `suggest_next` is active by default but excluded when `--tools` is specified. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [packages](#packages).
 
-**Also available:** [`@dreb/telegram`](https://www.npmjs.com/package/@dreb/telegram) — run dreb as a Telegram bot with live tool status and visible results for user-facing tools (`npm install -g @dreb/telegram`).
+**Also available:** [`@dreb/dashboard`](docs/dashboard.md) — run dreb in a browser with project/session browsing, chat, files, subagents, settings, and localhost/Tailscale access controls (`npm install -g @dreb/dashboard`); [`@dreb/telegram`](https://www.npmjs.com/package/@dreb/telegram) — run dreb as a Telegram bot with live tool status and visible results for user-facing tools (`npm install -g @dreb/telegram`).
 
 **Platform notes:** [Windows](docs/windows.md) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)
 
@@ -549,6 +549,19 @@ await session.prompt("What files are in the current directory?");
 
 See [docs/sdk.md](docs/sdk.md) and [examples/sdk/](examples/sdk/).
 
+### Dashboard
+
+For a browser interface, use the first-party dashboard package:
+
+```bash
+npm install -g @dreb/dashboard
+dreb-dashboard
+```
+
+The dashboard serves a local web UI for project/file browsing, session history, chat, live subagents, and runtime settings. Localhost access works without pairing; non-localhost access is opt-in and should go through Tailscale allowlisting plus PIN pairing.
+
+See [docs/dashboard.md](docs/dashboard.md) for launch and security details.
+
 ### RPC Mode
 
 For non-Node.js integrations, use RPC mode over stdin/stdout:

packages/coding-agent/docs/dashboard.md

@@ -0,0 +1,89 @@
+# Dashboard
+
+`@dreb/dashboard` is dreb's first-party browser dashboard. It provides a local web UI for browsing projects and files, opening sessions, chatting with dreb agents, watching live events/subagents, and adjusting runtime settings.
+
+The dashboard is a separate workspace package and talks to `@dreb/coding-agent` through the native RPC client. Each active project/session gets its own runtime entry so the dashboard does not silently switch a running agent across unrelated project contexts.
+
+## Install and launch
+
+From a source checkout:
+
+```bash
+npm install
+npm run build
+npm link -w packages/dashboard
+dreb-dashboard
+```
+
+By default the server binds to `127.0.0.1:3762`:
+
+```bash
+dreb-dashboard --host 127.0.0.1 --port 3762
+```
+
+Open the printed local URL in a browser on the host machine.
+
+## Localhost mode
+
+Same-machine loopback access is allowed without pairing friction. This is the default and safest mode:
+
+```bash
+dreb-dashboard
+```
+
+Do not bind to `0.0.0.0` unless remote mode is intentionally enabled and configured.
+
+## Tailscale remote mode
+
+Remote access is opt-in. Use Tailscale identities/devices and PIN pairing:
+
+```bash
+dreb-dashboard \
+  --host 0.0.0.0 \
+  --remote true \
+  --allowed-identity drew@example.com \
+  --allowed-device drews-phone
+```
+
+When remote mode starts, the server prints a short-lived pairing PIN. Open the dashboard from the allowed Tailnet device and enter the PIN. The paired browser receives an HTTP-only pairing cookie and future API calls are authorized until the pairing expires.
+
+Remote requests fail closed when:
+
+- remote mode is disabled
+- the request is not from a verified Tailscale peer
+- no Tailscale identity or device allowlist is configured
+- the peer does not match the allowlist
+- the browser has not completed PIN pairing
+
+The production resolver uses `tailscale status --json` and matches the socket remote address against Tailnet peer addresses. The dashboard does not trust caller-supplied identity headers.
+
+## Features
+
+- Browse configured roots (`cwd` and home by default)
+- Browse directories with path traversal and symlink escape checks
+- Upload files into the selected folder with size limits
+- Download files from allowed roots with size limits
+- List all sessions and sessions for the selected project
+- Open a new runtime or resume a project session
+- Send prompts, steering messages, follow-ups, and aborts
+- Load current runtime state and historical messages
+- Stream live agent events with SSE
+- Show tasks, suggest-next commands, event log entries, and background subagent lifecycle events
+- Change model, thinking level, steering mode, and follow-up mode through RPC-backed settings controls
+
+## Security notes
+
+The dashboard can control agents and move files on the host. Treat it as a powerful local control plane:
+
+- Keep the default localhost binding unless remote access is needed.
+- Use Tailscale for non-localhost access, including devices on the same LAN.
+- Configure specific allowed identities/devices; empty allowlists deny remote clients.
+- Pair each remote browser/device with the short-lived PIN shown on the host.
+- Avoid exposing the dashboard to a public network or unauthenticated reverse proxy.
+- File APIs are intentionally separate from model tools; human upload/download is authorized at the dashboard boundary.
+
+## MVP limitations
+
+- The embedded terminal pane is not part of the MVP.
+- Full custom TUI component rendering is not reused directly; the dashboard renders the core RPC event categories and supported extension UI events.
+- Remote TLS/origin hardening depends on the deployment path. Prefer Tailscale-local access rather than public exposure.

packages/coding-agent/package.json

@@ -25,6 +25,10 @@
 			"types": "./dist/modes/rpc/index.d.ts",
 			"import": "./dist/modes/rpc/index.js"
 		},
+		"./session-manager": {
+			"types": "./dist/core/session-manager.d.ts",
+			"import": "./dist/core/session-manager.js"
+		},
 		"./buddy": {
 			"types": "./dist/core/buddy/index.d.ts",
 			"import": "./dist/core/buddy/index.js"

packages/dashboard/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 2.34.4
+
+- Initial dashboard backend scaffold.

packages/dashboard/README.md

@@ -0,0 +1,42 @@
+# @dreb/dashboard
+
+First-party web dashboard for dreb. It serves a minimalist responsive browser UI for project/file browsing, session history, chat controls, live events/subagents, and runtime settings.
+
+## Launch
+
+```bash
+npm run build
+npm link -w packages/dashboard
+dreb-dashboard
+```
+
+Default: `http://127.0.0.1:3762`.
+
+Options:
+
+```bash
+dreb-dashboard [--host 127.0.0.1] [--port 3762] [--cwd /project] [--agentDir ~/.dreb/agent]
+```
+
+Remote access is opt-in and should go through Tailscale:
+
+```bash
+dreb-dashboard \
+  --host 0.0.0.0 \
+  --remote true \
+  --allowed-identity drew@example.com \
+  --allowed-device drews-phone
+```
+
+The server prints a short-lived PIN for remote browser pairing. Localhost access does not require pairing.
+
+## Security model
+
+- Local loopback clients are allowed by default.
+- Non-loopback clients are rejected unless remote mode is enabled.
+- Remote mode requires verified Tailscale peer identity/device allowlisting.
+- Empty remote allowlists deny access.
+- Remote browsers must complete PIN pairing before API control is granted.
+- Pairings are stored in `dashboard-pairings.json` under the dreb agent directory.
+
+See [`packages/coding-agent/docs/dashboard.md`](../coding-agent/docs/dashboard.md) for full usage and security notes.

packages/dashboard/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@dreb/dashboard",
+	"version": "2.34.4",
+	"description": "First-party web dashboard for dreb coding agent",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"bin": {
+		"dreb-dashboard": "./dist/index.js"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "tsgo -p tsconfig.build.json && tsgo -p tsconfig.client.json && shx chmod +x dist/index.js && npm run copy-assets",
+		"copy-assets": "shx mkdir -p dist/static && shx cp src/static/* dist/static/",
+		"dev": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
+		"test": "vitest --run",
+		"prepublishOnly": "npm run clean && npm run build"
+	},
+	"dependencies": {
+		"@dreb/agent-core": "*",
+		"@dreb/coding-agent": "*"
+	},
+	"devDependencies": {
+		"@types/node": "^24.3.0",
+		"shx": "^0.4.0",
+		"typescript": "^5.9.2",
+		"vitest": "^4.1.8"
+	},
+	"engines": {
+		"node": "22.x"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/aebrer/dreb.git",
+		"directory": "packages/dashboard"
+	}
+}