feat(dashboard): rename vis → dashboard and add agent-tracing dashboard (#137)

* feat(dashboard): add the agent-tracing dashboard (web UI, CLI, API, packaging)

Introduce `pythinker dashboard` — a local web UI for inspecting agent
sessions: wire events, context messages, state, sub-agents, a dual view,
tool statistics, and usage over time. Served by a FastAPI backend
(`pythinker_code.dashboard`) under `/api/dashboard`, with the React/Vite
frontend bundled at build time (`make build-dashboard`, wired into the
wheel, PyInstaller binaries, and the Linux/Windows installers). Reachable
from the interactive shell via `/reports` (alias `/dashboard`).

Also fixes correctness issues found in review: attach the session auth
header to the import and delete calls; log previously-swallowed
exceptions in the session/statistics APIs and the build script; group
sub-agent events by a stable key; and gate the number-key tab shortcuts
to the in-session view.

* docs(dashboard): document the agent-tracing dashboard

Add the dashboard reference page, wire up navigation and cross-links,
refresh the architecture and configuration docs, and add a CHANGELOG
entry introducing `pythinker dashboard`.

* fix(dashboard): sync lockfile and address review findings

- Regenerate dashboard/package-lock.json to restore the nested @emnapi
  deps so the onefile build's `npm ci` succeeds (was failing on every
  platform in PR #137 CI).
- Open the browser at localhost for `::` binds, not just `0.0.0.0`, so the
  URL stays within the allowed origins (loopback_browser_host helper + test).
- use-theme: fall back to the legacy "vis-theme" key for upgraders.
- Help overlay: move the session-gated 1-5 tab shortcuts out of "Global"
  into a "Session Views" group.
- AGENTS.md: drop stale "visualization" wording for the dashboard targets.
- Assert the dashboard missing-assets 503 names the expected static path.

* fix(dashboard): center the Daily Usage chart instead of full-width

The Daily Usage line chart stretched to the full 1400px content width,
leaving the sparse 30-day series looking over-extended. Cap the card at
max-w-3xl and center it (matching loading skeleton) so it stays centered
and readable on wide screens.

* fix(dashboard): resolve CodeRabbit findings and fix lockfile @emnapi sync

- Add -> None return type to SwitchToDashboard.__init__ (ANN204)
- Rename unused args to _args in reports() slash command (ARG001)
- Add IPv6 :: host to allowed_origins in dashboard app
- Add @emnapi/core@1.11.1 and @emnapi/runtime@1.11.1 to dashboard lockfile

The build was failing on all platforms because npm ci could not find
@emnapi/core@1.11.1 and @emnapi/runtime@1.11.1 in the lockfile. These
are needed by @tailwindcss/oxide-wasm32-wasi which pins ^1.10.0 (now
resolved to 1.11.1 on the registry). Added the missing top-level entries.

Author: elkaix

.github/dependabot.yml

@@ -36,7 +36,7 @@ updates:
   - package-ecosystem: "npm"
     directories:
       - "/web"
-      - "/vis"
+      - "/dashboard"
       - "/docs"
       - "/packages/install-counter-worker"
       - "/examples/feedback-worker"
@@ -54,7 +54,7 @@ updates:
           - "patch"
     ignore:
       # TypeScript 6.x is a major bump: it deprecates the tsconfig `baseUrl`
-      # option (TS5101) and breaks the vis/ and web/ builds. Adopting it is a
+      # option (TS5101) and breaks the dashboard/ and web/ builds. Adopting it is a
       # coordinated monorepo migration, not four split bot PRs. Hold the major
       # until that lands; minor/patch within the current line still flow.
       - dependency-name: "typescript"

.github/workflows/linux-installer.yml

@@ -62,7 +62,7 @@ jobs:
           cache: "npm"
           cache-dependency-path: web/package-lock.json
 
-      # The web/vis frontends are gitignored build artifacts; without these
+      # The web/dashboard frontends are gitignored build artifacts; without these
       # steps PyInstaller froze a binary whose web UI 404'd on "/". The
       # bundles are arch-independent, so they are built once on the host —
       # the QEMU container build picks them up from the mounted checkout.
@@ -73,8 +73,8 @@ jobs:
           PYTHINKER_WEB_EXPECT_VERSION: ${{ steps.ver.outputs.version }}
         run: python3 scripts/build_web.py
 
-      - name: Build vis UI bundle
-        run: python3 scripts/build_vis.py
+      - name: Build dashboard UI bundle
+        run: python3 scripts/build_dashboard.py
 
       - name: Set up QEMU (aarch64 only)
         if: matrix.qemu

.github/workflows/windows-installer.yml

@@ -61,7 +61,7 @@ jobs:
           cache: "npm"
           cache-dependency-path: web/package-lock.json
 
-      # The web/vis frontends are gitignored build artifacts; without these
+      # The web/dashboard frontends are gitignored build artifacts; without these
       # steps PyInstaller froze a binary whose web UI 404'd on "/". The spec
       # file now also refuses to freeze when the bundles are missing.
       - name: Build web UI bundle
@@ -70,8 +70,8 @@ jobs:
           PYTHINKER_WEB_EXPECT_VERSION: ${{ steps.ver.outputs.version }}
         run: python scripts/build_web.py
 
-      - name: Build vis UI bundle
-        run: python scripts/build_vis.py
+      - name: Build dashboard UI bundle
+        run: python scripts/build_dashboard.py
 
       - name: Install PyInstaller
         run: uv pip install pyinstaller

.gitignore

@@ -28,8 +28,8 @@ src/pythinker_code/deps/tmp
 # Web build artifacts
 src/pythinker_code/web/static/assets/
 
-# Vis build artifacts
-src/pythinker_code/vis/static/
+# Dashboard build artifacts
+src/pythinker_code/dashboard/static/
 
 # Generated reports
 .firecrawl/

AGENTS.md

@@ -144,8 +144,8 @@ Development servers:
 ```bash
 make web-back     # FastAPI web backend on port 5494
 make web-front    # web frontend dev server
-make vis-back     # visualization backend on port 5495
-make vis-front    # visualization frontend dev server
+make dashboard-back     # dashboard backend on port 5495
+make dashboard-front    # dashboard frontend dev server
 ```
 
 Targeted package commands:
@@ -173,7 +173,7 @@ Pick the smallest reliable gate for the change, then run broader gates before re
 | `packages/pythinker-host` | `make check-pythinker-host && make test-pythinker-host` |
 | `packages/pythinker-review` | `make check-pythinker-review && make test-pythinker-review` |
 | `sdks/pythinker-sdk` | `make check-pythinker-sdk && make test-pythinker-sdk` |
-| Web / vis frontends | `make check-web`; build affected frontend when packaging assets changed |
+| Web / dashboard frontends | `make check-web`; build affected frontend when packaging assets changed |
 | Release / packaging / PyInstaller | `make build` or `make build-bin` as appropriate |
 
 If a gate cannot run because of missing system tools (for example `npm`), report that explicitly
@@ -221,7 +221,7 @@ see `docs/en/customization/architecture.md`. This list is a quick orientation on
 - `src/pythinker_code/auth/`: OAuth/API-key provider integrations.
 - `src/pythinker_code/background/`: background task worker/runtime support.
 - `src/pythinker_code/cli/`: Typer command tree (lazy-loaded subcommands `mcp`, `plugin`,
-  `skill`, `web`, `vis`, `info`, `export`, `review`, `secscan`, `security-scan`, `debug`,
+  `skill`, `web`, `dashboard`, `info`, `export`, `review`, `secscan`, `security-scan`, `debug`,
   `update`, plus eager `login`, `logout`, `term`, `acp`).
 - `src/pythinker_code/hooks/`: hook definitions and execution engine.
 - `src/pythinker_code/plugin/`: plugin discovery and installation support.
@@ -239,8 +239,8 @@ see `docs/en/customization/architecture.md`. This list is a quick orientation on
 - `src/pythinker_code/tools/`: built-in tools (`agent`, `ask_user`, `background`, `dmail`, `file`,
   `plan`, `shell`, `think`, `todo`, `web`, etc.).
 - `src/pythinker_code/ui/`: shell, print, and ACP frontends.
-- `src/pythinker_code/web/`, `src/pythinker_code/vis/`: backend integrations for web/visualization.
-- `web/`, `vis/`: frontend apps bundled into the CLI package.
+- `src/pythinker_code/web/`, `src/pythinker_code/dashboard/`: backend integrations for web/visualization.
+- `web/`, `dashboard/`: frontend apps bundled into the CLI package.
 - `packages/pythinker-core/`: LLM abstraction layer for messages, providers, streaming, and tools.
 - `packages/pythinker-host/`: host abstraction for local/remote file and shell operations.
 - `packages/pythinker-review/`: review/debug/security engine, code-reviewr-derived PR

CHANGELOG.md

@@ -15,6 +15,8 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+- **Agent-tracing dashboard.** Added `pythinker dashboard` — a local web UI for inspecting sessions, wire events, context messages, tool statistics, and usage over time. It is also reachable from the interactive shell via the `/reports` slash command (aliased `/dashboard`).
+
 ## 0.44.0 (2026-06-13)
 
 - **Toggle auto-update from the CLI.** Running `/update` now opens a menu — *Check for updates now* (the default, so a bare `/update` + Enter still checks immediately) or *Auto-update on startup* with its current state — so the toggle is discoverable without knowing a subcommand. `/update auto on|off` still sets it directly, and `/update auto` with no value opens an interactive On/Off picker (cursor defaulted to the current setting). The same toggle appears in the interactive `/settings` panel, and `pythinker info` reports the auto-update status. All surfaces show the *effective* state — an external override (`PYTHINKER_CLI_NO_AUTO_UPDATE` or a source checkout) is surfaced as the reason, renders the `/settings` row read-only, and makes `/update auto` report the read-only state rather than popping a no-op picker, so the toggle is never a silent no-op.

Makefile

@@ -29,12 +29,12 @@ web-back: ## Start web backend with uvicorn (reload enabled).
 web-front: ## Start web frontend (vite dev server).
 	@npm --prefix web run dev
 
-# for pythinker vis development
-.PHONY: vis-back vis-front
-vis-back: ## Start vis backend with uvicorn (reload enabled).
-	@LOG_LEVEL=DEBUG uv run uvicorn pythinker_code.vis.app:create_app --factory --reload --port 5495
-vis-front: ## Start vis frontend (vite dev server).
-	@npm --prefix vis run dev
+# for pythinker dashboard development
+.PHONY: dashboard-back dashboard-front
+dashboard-back: ## Start dashboard backend with uvicorn (reload enabled).
+	@LOG_LEVEL=DEBUG uv run uvicorn pythinker_code.dashboard.app:create_app --factory --reload --port 5495
+dashboard-front: ## Start dashboard frontend (vite dev server).
+	@npm --prefix dashboard run dev
 
 .PHONY: format format-pythinker-code format-pythinker-core format-pythinker-host format-pythinker-review format-pythinker-sdk format-web
 format: format-pythinker-code format-pythinker-core format-pythinker-host format-pythinker-review format-pythinker-sdk format-web ## Auto-format all workspace packages.
@@ -145,8 +145,8 @@ cov-pythinker-sdk: ## Run Pythinker SDK tests with coverage.
 		--cov --cov-report=xml:coverage.xml -vv
 
 .PHONY: build build-pythinker-code build-pythinker-core build-pythinker-host build-pythinker-review build-pythinker-sdk build-bin build-bin-onedir
-build: build-web build-vis build-pythinker-code build-pythinker-core build-pythinker-host build-pythinker-review build-pythinker-sdk ## Build Python packages for release.
-build-pythinker-code: build-web build-vis ## Build the pythinker-code sdist and wheel.
+build: build-web build-dashboard build-pythinker-code build-pythinker-core build-pythinker-host build-pythinker-review build-pythinker-sdk ## Build Python packages for release.
+build-pythinker-code: build-web build-dashboard ## Build the pythinker-code sdist and wheel.
 	@echo "==> Building pythinker-code distributions"
 	@uv build --package pythinker-code --no-sources --out-dir dist
 build-pythinker-core: ## Build the pythinker-core sdist and wheel.
@@ -164,15 +164,15 @@ build-pythinker-sdk: ## Build the pythinker-sdk sdist and wheel.
 build-web: ## Build web UI and sync into pythinker-code package.
 	@echo "==> Building web UI"
 	@uv run scripts/build_web.py
-build-vis: ## Build vis UI and sync into pythinker-code package.
-	@echo "==> Building vis UI"
-	@uv run scripts/build_vis.py
-build-bin: build-web build-vis ## Build the standalone executable with PyInstaller (one-file mode).
+build-dashboard: ## Build dashboard UI and sync into pythinker-code package.
+	@echo "==> Building dashboard UI"
+	@uv run scripts/build_dashboard.py
+build-bin: build-web build-dashboard ## Build the standalone executable with PyInstaller (one-file mode).
 	@echo "==> Building PyInstaller binary (one-file)"
 	@uv run pyinstaller pythinker.spec
 	@mkdir -p dist/onefile
 	@if [ -f dist/pythinker.exe ]; then mv dist/pythinker.exe dist/onefile/; elif [ -f dist/pythinker ]; then mv dist/pythinker dist/onefile/; fi
-build-bin-onedir: build-web build-vis ## Build the standalone executable with PyInstaller (one-dir mode).
+build-bin-onedir: build-web build-dashboard ## Build the standalone executable with PyInstaller (one-dir mode).
 	@echo "==> Building PyInstaller binary (one-dir)"
 	@rm -rf dist/onedir dist/pythinker
 	@PYINSTALLER_ONEDIR=1 uv run pyinstaller pythinker.spec

README.md

@@ -744,8 +744,8 @@ make test-pythinker-sdk   # SDK only
 ```sh
 make web-back             # web backend
 make web-front            # web frontend
-make vis-back             # vis backend
-make vis-front            # vis frontend
+make dashboard-back       # dashboard backend
+make dashboard-front      # dashboard frontend
 ```
 
 </td>
@@ -770,7 +770,7 @@ make help                 # all targets
 
 ```
 pythinker-code/
-├── 📦 src/pythinker_code/         CLI runtime · tools · UIs · ACP · MCP · hooks · plugins · skills · web · vis backends
+├── 📦 src/pythinker_code/         CLI runtime · tools · UIs · ACP · MCP · hooks · plugins · skills · web · dashboard backends
 ├── 🧱 packages/
 │   ├── pythinker-core/           Provider-agnostic message, tool, and chat-provider abstractions
 │   ├── pythinker-host/           Local/remote host filesystem and command execution

vis/AGENTS.md dashboard/AGENTS.mdvis/AGENTS.md renamed to dashboard/AGENTS.md

@@ -1,25 +1,25 @@
-# Pythinker Vis UI (vis/)
+# Pythinker Dashboard UI (dashboard/)
 
 React 19 + Vite + TypeScript session-tracing visualizer, bundled into the `pythinker-code`
 package. It is a read-only viewer of Wire events, context messages, agent state, and subagent
 activity. Run all `npm` commands from this directory.
 
 ## Critical invariants
 
-- **`vis/src/lib/api.ts` is hand-written, not generated** (unlike `web/`, which has a generated
+- **`dashboard/src/lib/api.ts` is hand-written, not generated** (unlike `web/`, which has a generated
   client). Keep its types (`WireEvent`, `ContextMessage`, `SessionInfo`, `SubagentInfo`) in
-  sync by hand with the vis backend (`src/pythinker_code/vis/`) and the Wire protocol
+  sync by hand with the dashboard backend (`src/pythinker_code/dashboard/`) and the Wire protocol
   (`src/pythinker_code/wire/`) whenever either changes. There is no codegen step here.
-- **Do not hand-copy build output.** `scripts/build_vis.py` builds and syncs `vis/dist` →
-  `src/pythinker_code/vis/static`. No ad-hoc copy/rsync scripts.
-- **Read-only data plane.** It consumes `/api/vis/*` from the vis backend (port 5495) with a
+- **Do not hand-copy build output.** `scripts/build_dashboard.py` builds and syncs `dashboard/dist` →
+  `src/pythinker_code/dashboard/static`. No ad-hoc copy/rsync scripts.
+- **Read-only data plane.** It consumes `/api/dashboard/*` from the dashboard backend (port 5495) with a
   Bearer token taken from a URL query param; `cache.ts` dedupes in-flight requests. Do not add
   write/mutation calls here — mutations belong to the web UI / backend, not the visualizer.
 
 ## Stack and conventions
 
-- Build: `tsc -b && vite build`; dev: `npm run dev` (or `make vis-front`). Backend:
-  `make vis-back` (port 5495).
+- Build: `tsc -b && vite build`; dev: `npm run dev` (or `make dashboard-front`). Backend:
+  `make dashboard-back` (port 5495).
 - Styling: Tailwind + Radix UI / shadcn; `react-virtuoso` for efficient large-session lists.
 - Feature panels live under `src/features/` (`wire-viewer`, `context-viewer`, `agents-panel`,
   `state-viewer`, `sessions-explorer`).