Compare commits
47 Commits
f6946d72f4
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 nntrivi2001
|
2c29504c75 | ||
|
nntrivi2001
|
39572aa04c | ||
|
nntrivi2001
|
3ae0d00b0c | ||
|
nntrivi2001
|
a2b5fa4669 | ||
|
nntrivi2001
|
bab19e2f36 | ||
|
nntrivi2001
|
6f22aed47c | ||
|
nntrivi2001
|
d542fbbf4b | ||
|
nntrivi2001
|
764dc6a7b5 | ||
|
nntrivi2001
|
06817b7901 | ||
|
nntrivi2001
|
14f116bf00 | ||
|
nntrivi2001
|
6dda604362 | ||
|
nntrivi2001
|
22ce61bcfe | ||
|
nntrivi2001
|
8a61a2b359 | ||
|
nntrivi2001
|
b1d43bf098 | ||
|
nntrivi2001
|
11b779479d | ||
|
nntrivi2001
|
18a1ecb6f9 | ||
|
nntrivi2001
|
fa416b5e6b | ||
|
nntrivi2001
|
0f15800b23 | ||
|
nntrivi2001
|
43f29ee904 | ||
|
nntrivi2001
|
18a42873b2 | ||
|
nntrivi2001
|
b0bfc66d65 | ||
|
nntrivi2001
|
78fb82b257 | ||
|
nntrivi2001
|
7e2bb6225f | ||
|
nntrivi2001
|
774ee48f19 | ||
|
nntrivi2001
|
bcd1259ed2 | ||
|
nntrivi2001
|
251a18dc39 | ||
|
nntrivi2001
|
d581705eb0 | ||
|
nntrivi2001
|
cb8800fa31 | ||
|
nntrivi2001
|
9c3331c843 | ||
|
nntrivi2001
|
31af7aefbf | ||
|
nntrivi2001
|
6709f9a192 | ||
|
nntrivi2001
|
b951f64321 | ||
|
nntrivi2001
|
2f39f4ec98 | ||
|
nntrivi2001
|
f1e7d4245a | ||
|
nntrivi2001
|
82bf803c2e | ||
|
nntrivi2001
|
24f13911fe | ||
|
nntrivi2001
|
9b8d9bbe39 | ||
|
nntrivi2001
|
872c698132 | ||
|
nntrivi2001
|
1bc237198c | ||
|
nntrivi2001
|
56744b360d | ||
|
nntrivi2001
|
1dd18fe98c | ||
|
nntrivi2001
|
d96d552428 | ||
|
nntrivi2001
|
00f6338d4c | ||
|
nntrivi2001
|
dfea1a99d6 | ||
|
nntrivi2001
|
f4dc6a0730 | ||
|
nntrivi2001
|
7357070fb9 | ||
|
nntrivi2001
|
f0ae876472 |
@@ -13,6 +13,7 @@ You are running the autonomous feature pipeline for **one CCAM lane**. The human
|
||||
LANE_DIR="$(pwd)" # the lane clone IS your cwd — CCAM resolves the lane from this, never a hardcoded path
|
||||
```
|
||||
- CCAM resolves your lane from `cwd` automatically (longest path-boundary prefix match) — there is no marker file to check and no separate assign step. If `ccam stage` or `ccam feature activate` ever fails with "no lane found", you are not inside a lane's working directory; stop and tell the human.
|
||||
- **Pipeline template is this skill's contract, not whatever the lane started on.** Before your first `ccam stage` call, run `ccam lanes pipeline ship-feature` (no id needed — resolves from `cwd` like `ccam stage`; idempotent, a no-op if already set) so every stage below resolves against the 16-node `ship-feature` map. The human is never expected to pick this in Add Lane or anywhere else — you force it to match the skill actually running.
|
||||
- All stage updates go through `ccam stage <stage> [--status <s>] [--evidence "..."]` — **call it at the start of every stage** (this is also the heartbeat, visible on the dashboard).
|
||||
- **Integration toggles: check, don't assume.** `ccam lanes integration tracker`, `ccam lanes integration dev_qc`, `ccam lanes integration ci_wait` each exit 0 (on) or 1 (off), reading the profile's `integrations.env`. No agent exists yet to actually FILE a ticket or run dev-QC even when a toggle reads on (`ticketer`/`dev-qc` are a later task) — so regardless of the check's result, Stage 9 (ticket) stays skipped, Stage 13's dev-QC and dev-CI-wait halves stay skipped, and Stage 10's CI watch keeps using the plain `gh pr checks` path (`ccam ci` doesn't exist yet). Check the toggle where noted below anyway, so the evidence you record is honest about whether the PROFILE wants the integration on, distinct from whether CCAM can act on it yet.
|
||||
- **Heartbeat during long stages.** Implementing (Stage 1), CI waits (Stage 10), and the watch/post-merge polls (Stages 12–13) can run many minutes between stage transitions — bump the heartbeat with `ccam stage <same-stage>` after each commit and on each poll iteration, so the dashboard doesn't false-flag a working lane as stalled.
|
||||
|
||||
@@ -19,6 +19,13 @@ Each phase below starts with `ccam stage <node>`, which is what puts the phase
|
||||
on the lane's pipeline map. The nodes are the `default` template's:
|
||||
`intake → plan → implement → tests → review → gate → ship → done`.
|
||||
|
||||
Set the template yourself, don't rely on how the lane was created: before your
|
||||
first `ccam stage` call, run `ccam lanes pipeline default` (no id needed —
|
||||
resolves from `cwd`; a no-op if the lane is already on it). This is what makes
|
||||
the choice invisible to the human — whichever of `ship-feature` or
|
||||
`ship-feature-lane` actually runs is what decides the template, not a picker
|
||||
they have to get right in advance.
|
||||
|
||||
`ccam stage` needs a lane owning the current directory. If it reports no lane,
|
||||
this repo was never adopted (`ccam lanes add --cwd $(pwd)` fixes it) — carry on
|
||||
with the workflow and skip the stage calls; they are reporting, not control
|
||||
|
||||
@@ -52,10 +52,10 @@ i18n architecture: **Supported languages** list, `supportedLngs`, the 15 namespa
|
||||
## Tier 3 — situational
|
||||
|
||||
- `.env.example` — every env var belongs here with a sane default + comment.
|
||||
- `INSTALL.md`, `SETUP.md`, `DEPLOYMENT.md`, `docs/DEPLOYMENT.md` — install/run/deploy commands.
|
||||
- `INSTALL.md`, `SETUP.md` — install/run commands.
|
||||
- `CLAUDE.md`, `AGENTS.md` — agent working guides; update when commands, file locations, or workflows change.
|
||||
- `docs/README.md` — docs index; add a link when a new `docs/*.md` is created.
|
||||
- `desktop/README.md`, `vscode-extension/README.md`, `statusline/README.md` — surface-specific; update only when that surface changes.
|
||||
- `vscode-extension/README.md`, `statusline/README.md` — surface-specific; update only when that surface changes.
|
||||
|
||||
## Consistency invariants
|
||||
|
||||
|
||||
+7
-395
@@ -35,35 +35,13 @@ Architectural overview and technical reference for the Agent Dashboard system, c
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -87,7 +65,6 @@ Architectural overview and technical reference for the Agent Dashboard system, c
|
||||
- [Update Notifier Subsystem](#update-notifier-subsystem)
|
||||
- [Tabby Companion Subsystem](#tabby-companion-subsystem)
|
||||
- [VS Code Extension Architecture](#vs-code-extension-architecture)
|
||||
- [Desktop App Architecture (macOS & Windows / Electron)](#desktop-app-architecture-macos--windows--electron)
|
||||
- [Security Considerations](#security-considerations)
|
||||
- [Performance Characteristics](#performance-characteristics)
|
||||
- [Deployment Modes](#deployment-modes)
|
||||
@@ -348,8 +325,7 @@ graph TD
|
||||
| `routes/agents.js` | CRUD with status/session_id filtering. PATCH broadcasts `agent_updated`. Agent-list responses (`GET /api/agents`, `GET /api/sessions/:id/agents`) attach a per-agent `cost` via `pricing.attachAgentCosts` — each subagent's OWN cost, computed from its `metadata.tokens` at current rates (main agents get 0; their cost is the session total), so a subagent card shows only what that subagent spent rather than the session total |
|
||||
| `routes/events.js` | Read-only event listing with session_id filter and pagination |
|
||||
| `routes/stats.js` | Single aggregate query returning total/active counts + status distributions |
|
||||
| `routes/metrics.js` | Prometheus / OpenMetrics text-exposition endpoint (`GET /api/metrics`) — re-exposes the dashboard's live counters (sessions/agents by status, event + token totals, connected WebSocket clients, configured remote sources, process uptime/RSS, build version) in the v0.0.4 text format for scraping into Prometheus / Grafana. Read-only; reads the same `db.js` prepared statements the REST API uses, so numbers match the UI. Status series are enumerated so a gauge never drops out at zero. Mounted under `/api`, so it sits behind the Host-header (DNS-rebinding) guard and the optional `DASHBOARD_TOKEN` guard — a non-loopback scraper needs `DASHBOARD_ALLOWED_HOSTS` (+ token if set). A turnkey Prometheus + Grafana stack with four auto-provisioned dashboards lives in `monitoring/` (`npm run monitoring:up` or `npm run docker:full:up`) |
|
||||
| `monitoring/` | Optional npm-managed or Docker Compose Prometheus + Grafana stack that scrapes `GET /api/metrics`. Ships four Grafana dashboards (`ccam-overview`, `ccam-sessions-agents`, `ccam-tokens-events`, `ccam-platform`), recording rules (`prometheus/ccam-rules.yml`), a Prometheus 3.x-compatible static HTML console (`prometheus/consoles/index.html`), and lifecycle scripts (`monitoring:install`, `monitoring:up`, `monitoring:verify`). See [`monitoring/README.md`](./monitoring/README.md) |
|
||||
| `routes/metrics.js` | Prometheus / OpenMetrics text-exposition endpoint (`GET /api/metrics`) — re-exposes the dashboard's live counters (sessions/agents by status, event + token totals, connected WebSocket clients, configured remote sources, process uptime/RSS, build version) in the v0.0.4 text format for scraping into Prometheus / Grafana. Read-only; reads the same `db.js` prepared statements the REST API uses, so numbers match the UI. Status series are enumerated so a gauge never drops out at zero. Mounted under `/api`, so it sits behind the Host-header (DNS-rebinding) guard and the optional `DASHBOARD_TOKEN` guard — a non-loopback scraper needs `DASHBOARD_ALLOWED_HOSTS` (+ token if set) |
|
||||
| `routes/analytics.js` | Extended analytics — token totals, tool usage counts, daily event/session trends, agent type distribution. The client-side analytics heatmap grid is aligned to a Sunday start for correct day-of-week positioning |
|
||||
| `routes/pricing.js` | Model pricing CRUD (list/upsert/delete) and per-session / global cost calculation with pattern-based model matching. `PUT /api/pricing` upserts a rule and accepts optional time-limited **introductory** rates (`intro_*_per_mtok` + `intro_until`): usage on/before the cutoff date prices at the intro rate, after it at the standard rate — the calculator picks the effective rate per usage day (`ratesForBucket`), so a promo like Sonnet 5's launch discount is correct before AND after the cutoff, retroactively. Intro columns are written only when the caller sends them (a standard-rate edit never disturbs a promo). Cost is computed per token bucket — keyed by (model, speed, inference_geo, service_tier) — applying fast-mode premium, US data-residency (1.1x), and Batch (0.5x) modifiers, the 5m/1h cache-write split, plus server-tool surcharges (web search $10/1k; code execution estimated by container-time with the monthly free-hours allowance; web fetch free). `attachAgentCosts`/`agentOwnCost` reuse the same calculator to price each agent's `metadata.tokens` for the per-agent `cost` on agent-list responses. Feature rates + modifier math live in `lib/pricing-constants.js`; usage normalization in `lib/token-usage.js` |
|
||||
| `routes/settings.js` | System info (DB size, hook status, server uptime, transcript cache stats), data export as one versioned JSON bundle and matching import/restore (`POST /api/settings/import` via `server/lib/data-transfer.js` — idempotent, session-atomic, non-destructive; consolidates machines), session cleanup (abandon stale, purge old), clear all data (including the fired-alert feed and webhook delivery log; alert *rules* and webhook *targets* are preserved as user configuration), reset pricing, reinstall hooks |
|
||||
@@ -374,9 +350,10 @@ graph TD
|
||||
| `lib/cc-mutate.js` | Create / overwrite / delete for the **low-risk text-file surfaces only** (skills, subagents, slash commands, output styles, memory — including the per-project file-based auto-memory store, mutated via `scope: "auto-memory"`, `type: "auto-memory"`, `project`, `name`, with its backups landing in `<memory-dir>/.cc-config-backups/auto-memory/`), plus `writeKeybindings()` for the structured `keybindings.json` editor (read-modify-write that preserves top-level metadata, rejects duplicate contexts/keys, and backs up to `<CLAUDE_HOME>/cc-config-backups/keybindings/`). Plugins, MCP, hooks-in-settings, and `settings.json` files are NEVER written from here — they have concurrent-write races with the live Claude Code CLI. Every mutation creates a timestamped backup at `<root>/cc-config-backups/<type>/<base>.<ISO>.bak[.dir]` BEFORE the change — backups land outside the directories Claude Code scans, so a deleted skill cannot resurface as a backup-named one. Writes are atomic: temp file in same dir → fsync → `renameSync`. Tmp removed on every failure path. Skill dirs are backed up whole (preserving bundled assets) before recursive removal. Strict `name` regex (`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`), 256 KB content cap, double-checked path containment via `isUnder()` |
|
||||
| `routes/cc-config.js` | HTTP surface for the Claude Config Explorer. Read endpoints for every surface (skills, agents, commands, output-styles, plugins, marketplaces, mcp, hooks, hook-scripts, keybindings, statusline, settings, memory, file, overview), plus mutation endpoints (`PUT /file`, `DELETE /file`, and a structured `PUT /keybindings`) that delegate to `cc-mutate.js`, plus a `GET /backups` listing for the recovery modal. After every successful PUT/DELETE the route broadcasts `cc_config_changed` over the WebSocket so any open `/cc-config` tab refetches without polling. All errors return structured `{error: {code, message}}` shapes mapped to 400/404/413/500 statuses |
|
||||
| `lib/cc-watcher.js` | Best-effort `fs.watch` over `~/.claude/` (recursive where the platform / Node version honors it — macOS / Windows always; Linux from Node 20) plus `~/.claude.json`. Coalesces bursts at 500 ms and broadcasts `cc_config_changed` with `{ source: "fs", paths: [...] }` so the Config Explorer picks up changes from external tools (CLI installs a plugin, manual `settings.json` edits, dropping a new skill) without a manual refresh. Started from `server/index.js` after the HTTP server boots; failures are caught and logged so a flaky watcher can't take the server down |
|
||||
| `lib/stream-json-parser.js` | Newline-delimited JSON line buffer for parsing `claude --output-format stream-json` output. Reassembles arbitrarily chunked stdout into discrete envelopes. Robust: malformed lines are reported via an `onError` callback but never throw |
|
||||
| `lib/run-spawner.js` | Spawns and supervises `claude` subprocesses for the Run page. Two modes: **headless** (`-p "<prompt>"` in argv, stdin closed, exits after one turn) and **conversation** (`--input-format stream-json`, prompt + follow-ups piped over stdin, multi-turn). Conversation mode also supports `resumeSessionId` → `--resume <id>`; an empty `prompt` is permitted in this case (the spawner skips the initial stdin write so `claude` idles on the resumed transcript until the user POSTs a follow-up via `/run/:id/message`). The argv builder also passes through an optional `effort` (`low`/`medium`/`high`) → `--effort`. Output is always `--output-format stream-json --verbose --include-partial-messages` so the parser yields character-level deltas (`stream_event` envelopes) the UI can render token-by-token; each envelope is broadcast as `run_stream` over the existing WebSocket. Status transitions broadcast as `run_status`. A failed spawn records an actual-exit timestamp too: no child started, so lane teardown can safely proceed instead of waiting for a nonexistent `exit` event. SIGTERM escalation checks that timestamp rather than Node's delivery-acknowledgement `child.killed`, so a child that ignores SIGTERM still receives SIGKILL after five seconds. Concurrency is effectively uncapped (default ceiling 10000 — matches the terminal TUI which has no cap; the cap is sanity-only to prevent fork-bomb footguns from a buggy client; override with `RUN_MAX_CONCURRENT`, NaN-safe). Per-handle bounded envelope log (cap 500) lets late-attaching clients replay history via `?envelopes=1`. The Run page additionally reconciles this in-memory log against the session's on-disk JSONL transcript on every attach (incl. clicking Resume / View on a row) — when the transcript has more user/assistant messages than the spawner saw (e.g., a resumed run whose prior history never traversed stdout), it supersedes; otherwise the spawner's log wins (it has stream_event deltas the transcript doesn't carry until each turn finalizes). This is what makes leaving a resumed run and coming back show the same chat the user saw initially. Completed handles reaped after 5 min; full transcripts persist via the normal hook ingestion pipeline because every spawned `claude` fires hooks like any other CLI session |
|
||||
| `routes/run.js` | HTTP surface for the Run feature. **Same-origin guard** on every route — browser requests must come from a localhost-ish Origin (`localhost`, `127.0.0.1`, `::1`, `0.0.0.0`); missing-Origin (curl/CLI) requests pass. When `DASHBOARD_TOKEN` is configured it is **also** required on these routes (same as the rest of `/api/*`). cwd sanitization: must be absolute and exist as a directory. `GET /` lists handles + concurrency state. `GET /binary` probes whether `claude` is on `PATH`. `GET /cwds` suggests cwds (dashboard + home + recent from sessions table). `GET /files?cwd=&q=` powers the Run page's `@`-file autocomplete: scoped fuzzy search inside `cwd` skipping `node_modules`, `.git`, `dist`, `build`, `.next`, `.cache`, `coverage`, `vendor`, etc., capped result count, ranked by basename match. `POST /` spawns (accepts `effort` in body). `POST /:id/message` sends a follow-up turn. `GET /:id` returns the handle; `?envelopes=1` includes the in-memory envelope log for re-attach. `DELETE /:id` SIGTERMs (escalates to SIGKILL after 5 s) |
|
||||
| `lib/tmux.js` | Wrapper around tmux CLI for session management. `createSession(sessionName, cwd)` creates a new tmux session in the specified working directory. `sendCommand(sessionName, command)` sends a command into the session. `killSession(sessionName)` terminates the session. `listSessions()` returns all active sessions. Session management is the foundation for the PTY transport layer |
|
||||
| `lib/pty-run.js` | PTY lifecycle for tmux-backed runs. Manages one tmux session per lane, named `ccam-lane-<lane.id>`. Exports `startRun()` to create/attach a session and return a `runId` opaque handle; internally uses tmux to manage the pseudoterminal. Spawned `claude` processes run inside the session and fire the dashboard's hooks like any other CLI session, so they show up in `/api/sessions`, the analytics, the Kanban board, and the Workflows page automatically. The PTY frames (terminal input/output deltas) are streamed to the client over `/ws-pty/:runId` (see `server/websocket.js`) at binary frame granularity rather than as JSON envelopes; the client's xterm.js terminal widget renders these raw PTY updates live |
|
||||
| `lib/pty-attach.js` | Client-side PTY attachment via WebSocket. Establishes a `/ws-pty/:runId` connection, receives binary PTY frames, and feeds them to an xterm.js terminal instance. Handles reconnection, resize events (sending `TIOCSWINSZ` ioctl to the tmux pane), and cleanup on disconnect. A single tmux session can have many simultaneous PTY clients (browser Workspace, `ccam lanes shell` CLI, etc.), all synced live |
|
||||
| `routes/run.js` | HTTP surface for the tmux+PTY Run feature. **Same-origin guard** on every route — browser requests must come from a localhost-ish Origin (`localhost`, `127.0.0.1`, `::1`, `0.0.0.0`); missing-Origin (curl/CLI) requests pass. When `DASHBOARD_TOKEN` is configured it is **also** required on these routes (same as the rest of `/api/*`). `GET /api/run` lists all live runs (computed fresh from tmux state via `tmux list-sessions`). `GET /api/run/tmux` reports whether `tmux` is installed and on PATH (required for the feature to work). `GET /api/run/binary` probes whether `claude` is on `PATH`. `GET /api/run/cwds` suggests cwds (dashboard + home + recent from sessions table). `GET /api/run/history?laneId=...` returns persisted run history, optionally scoped to one lane. `GET /api/run/files?cwd=&q=` powers the Workspace page's `@`-file autocomplete: scoped fuzzy search inside `cwd` skipping `node_modules`, `.git`, `dist`, `build`, `.next`, `.cache`, `coverage`, `vendor`, etc., capped result count, ranked by basename match. `POST /api/run` requires `laneId` in the body and starts/attaches a tmux-backed run. `GET /api/run/:id` returns the run handle. `DELETE /api/run/:id` kills the tmux session (sends SIGTERM to the pane, escalates to SIGKILL after 5 s). The PTY frames are streamed to the client over `/ws-pty/:runId` as binary frames (not JSON), rendering a real interactive terminal in xterm.js on the Workspace page. `tmux` must be installed on the dashboard server's machine (same as better-sqlite3's native-module requirements) |
|
||||
| `routes/lanes.js` | Durable-lane API. `POST /api/lanes/worktree`, `PATCH /api/lanes/:id`, destructive actions, and `DELETE /api/lanes/:id` use the Run route's same-origin guard. Worktree provisioning validates an absolute source git repository, persists a managed lane as `provisioning`, returns `202`, then uses the per-lane lock to resolve the base and add the worktree. Completion broadcasts the existing `lane_update` payload as `idle`; a git failure leaves a row that the non-destructive delete route can forget. `GET /api/lanes/:id/preflight?action=reset\|remove\|purge` produces counted confirmation facts. Confirmed `POST /:id/{reset,remove,purge}` actions require a complete `expect`, run under the same lock, kill a recorded run and wait for the spawner's actual child-exit timestamp (or return `500 ERUNTIMEOUT` before git), clear `run_id`, reject changed facts with `409 ESTALE` including expected/current diagnostics, and require `force` for unpushed managed reset/remove work. Reset and managed removal call the worktree's independent managed-kind, realpath-within-`LANES_ROOT`, and listed-worktree guard; adopted reset is refused, while adopted remove only forgets its row and never modifies its directory, and a managed lane whose directory was deleted by hand takes a prune path that still enforces the managed-kind and inside-`LANES_ROOT` checks. `start` returns `409 ERUNLIVE` rather than overwriting a live `run_id` and orphaning its child. `kind`, `source_repo`, `slug`, `base_branch`, `slot` and `ports` are not patchable — provisioning writes them through `lanesLib.setProvisioningFacts`. Worktree provisioning also runs `lane-runtime.js:provisionLane` (A2) when the repo declares a `.ccam/profile` — seed `.env`, `bootstrap`, create the database, migrate, seed — before the lane reports `idle`; `reset`/`remove` likewise call `resetLaneData`/`removeLaneData`, with `reset` accepting a body `keepDb: true` to skip the whole drop-recreate-migrate-reseed block. The runtime routes (`GET /:id/runtime`, `POST /:id/up`, `POST /:id/down`, `POST /:id/hook/:name`, `GET /:id/logs/:svc`) are registered **before** the `/:id/:action` catch-all so `up`/`down` are not swallowed as unknown actions, and are deliberately kept out of it: that catch-all drives a lane's Claude run, these drive the application the lane is working on. |
|
||||
| `lib/ports.js` | TCP probing for runtime allocation. `isListening(port)` connects rather than binds (binding races with the hook about to bind, and says nothing about a listener held by another user); a connect timeout counts as occupied. `listenerPids(port)` shells to `lsof`, falls back to `ss`, and returns `[]` with a one-time warning when neither exists — a missing tool must never fail a lane operation |
|
||||
| `lib/lane-slots.js` | Slot and port allocation — the numbering Shipyard gets free from fixed `lane1..lane9` directories and CCAM, keyed by `cwd`, must allocate. `allocateSlot` takes the lowest free of `LANE_MAX_SLOTS` (default 9) under the per-lane lock, with a partial unique index on `lanes.slot` as the backstop; allocation is **lazy**, so a lane that is only watched never consumes one. `releaseSlot` runs on remove but never on reset (moving a lane's ports mid-feature is a silent failure, not a fresh start). `resolvePorts` prefers `PORT_BASE_<name> + slot`, then steps `+100` at a time so the last digit still reads as the slot, skipping anything listening, recorded by another lane, or already taken in the same boot. `slotDirs` puts run/log state under `LANES_ROOT/.state/lane<slot>/` — outside the worktree, because `reset`'s `git clean -fd` would otherwise sweep live pid files. `dbName`/`dataFacts` (A2) derive the same kind of slot-based fact one layer up: database name, `DATABASE_URL`/`TEST_DATABASE_URL`, a Redis logical index, and the upload directory — each `null` when its owning profile declaration (`DB_PREFIX`, `REDIS`, `UPLOAD_SUBDIR`) is absent |
|
||||
@@ -647,7 +624,7 @@ graph LR
|
||||
| `/analytics` | Analytics | `GET /api/analytics` |
|
||||
| `/workflows` | Workflows | `GET /api/workflows?status=active\|completed`, `GET /api/workflows/session/:id` + WebSocket auto-refresh (3s debounce) |
|
||||
| `/cc-config` | CcConfig | 12-tab Claude Code configuration explorer. Reads via `GET /api/cc-config/{overview,skills,agents,commands,output-styles,plugins,marketplaces,mcp,hooks,hook-scripts,keybindings,statusline,settings,memory}`. Mutations for skills/agents/commands/output-styles/memory — including the per-project file-based auto-memory store (`*.md` under `~/.claude/projects/<slug>/memory/`, grouped by project and searchable in the Memory tab, with clickable `MEMORY.md` index links that scroll to + highlight the matching fact file) — via `PUT /api/cc-config/file` + `DELETE /api/cc-config/file` (timestamped backups, atomic writes). The Keybindings tab additionally offers a structured inline editor that persists via `PUT /api/cc-config/keybindings` (same backup-first, atomic-write guarantees). `GET /api/cc-config/file?path=…` for single-file viewer. `GET /api/cc-config/backups` for the recovery modal. Subscribes to `cc_config_changed` WS messages for live refresh on both dashboard mutations and external file edits picked up by `cc-watcher`. The Settings tab leads with a client-side **Current configuration** summary that resolves the `/config` options (model, verbose, theme, output style, effort, auto-compact, notifications, …) across user / project / project-local scopes, showing defaults when unset. Live / Offline indicator next to the title |
|
||||
| `/run` | Workspace | Merged workspace page combining lanes and runs. Spawns `claude` subprocesses with chat-style streaming UI, tied to lanes: the UI opens on a `cwd`, calls `POST /api/lanes/ensure` when no lane owns it yet, then starts runs through `POST /api/lanes/:id/start` (which accepts `mode: "conversation" \| "headless"` and `effort: "low" \| "medium" \| "high"`). **A finished run releases its lane** (clears `run_id`, returns status to `idle`). Displays a horizontal lane strip at the top, the selected lane's pipeline map, and run configuration/console/history below. `GET /api/run/{binary,cwds,files}` for pre-flight + `@`-file autocomplete; `POST /api/run/:id/message` for follow-up turns; `DELETE /api/run/:id` to stop (lane-tied runs go through `POST /api/lanes/:id/stop` instead). `GET /api/run/history?laneId=<n>` lists only that lane's runs. WS messages: `run_stream` (includes `stream_event` deltas), `run_status`, `run_input_ack`, `lane_update`. Streaming pipeline: each WS envelope is dispatched through `flushSync` so React 18 doesn't batch bursts into a single render; a `useTypewriterEnvelopes` hook drips text/thinking deltas via `requestAnimationFrame` so even short replies type in; the merge code preserves `_streaming` and the delta-accumulated content array when claude's canonical `assistant` envelope arrives mid-stream so thinking blocks aren't dropped. Tier 1 TUI parity: collapsible-to-pill limitations banner, slash + `@`-file autocomplete (dropdowns open upward, slash matching uses tiered scoring), live token / context-window meter, status header. **The console never writes a lane's stage** — stage moves only through `ccam stage` commands. Live / Offline indicator next to the title |
|
||||
| `/run` | Workspace | Merged workspace page combining lanes and runs. Attaches to a tmux-backed pseudoterminal tied to a lane: the UI selects a lane, calls `POST /api/run` with that lane's `id`, and receives a `runId` + tmux session name. The Workspace displays a horizontal lane strip at the top, the selected lane's pipeline map, and a real interactive terminal (xterm.js) fed by `/ws-pty/:runId` binary frames below. Pre-flight: `GET /api/run/{tmux,binary,cwds,files}` for tmux availability + `claude` binary check + `@`-file autocomplete. Start/resume: `POST /api/run` (requires `laneId`; optionally accepts `prompt` to send immediately); `GET /api/run/:id` (returns handle); `DELETE /api/run/:id` (stops). History: `GET /api/run/history?laneId=<n>` lists only that lane's runs. PTY streaming: `/ws-pty/:runId` delivers raw PTY frames as binary WebSocket frames — no JSON envelope overhead, direct to xterm.js for live rendering; the same tmux session can have multiple simultaneous clients (browser Workspace, `ccam lanes shell` CLI, other tools), all synced live. Lane self-heal: `GET /api/lanes/:id` auto-corrects `run_id`/`status` if the tmux session has been killed externally. Tier 1 TUI parity: tmux session is a real shell, not headless — supports editors, pagers, interactive subcommands. **The console never writes a lane's stage** — stage moves only through `ccam stage` commands. Live / Offline indicator next to the title |
|
||||
| `/settings` | Settings | `GET /api/settings/info`, `GET /api/pricing`, `GET /api/pricing/cost` + `localStorage` for notification prefs. Hosts the **Remote Data Sources** panel (`components/RemoteSources.tsx`) — CRUD + test + sync over `/api/remote-sources`, live status from `remote_source.status` WS messages |
|
||||
| `/*` | NotFound | None (static 404 page) |
|
||||
|
||||
@@ -2011,7 +1988,7 @@ Cache versioning is controlled by the `CACHE_NAME` constant (`dashboard-v2`). On
|
||||
|
||||
`client/src/main.tsx` snapshots `navigator.serviceWorker.controller` before registration and listens for `controllerchange`: when a new SW activates on an already-controlled page, it reloads exactly once so the page picks up the new asset URLs without a hard refresh. The first install (no previous controller) does **not** reload.
|
||||
|
||||
These behaviors are reinforced by explicit `Cache-Control` headers from the production Express static middleware in `server/index.js`: `immutable, max-age=31536000` for `/assets/*`; `no-cache, must-revalidate` for `index.html`, `sw.js`, and `manifest.json`; a short revalidation window for other static files. The SPA fallback `sendFile` sends the same `no-cache` header. The native desktop shell (macOS and Windows) loads the dashboard from this same in-process server (`NODE_ENV=production`), so it inherits the policy automatically.
|
||||
These behaviors are reinforced by explicit `Cache-Control` headers from the production Express static middleware in `server/index.js`: `immutable, max-age=31536000` for `/assets/*`; `no-cache, must-revalidate` for `index.html`, `sw.js`, and `manifest.json`; a short revalidation window for other static files. The SPA fallback `sendFile` sends the same `no-cache` header.
|
||||
|
||||
---
|
||||
|
||||
@@ -2308,299 +2285,6 @@ For the extension source code, refer to the [vscode-extension/](./vscode-extensi
|
||||
|
||||
---
|
||||
|
||||
## Desktop App Architecture (macOS & Windows / Electron)
|
||||
|
||||
The `desktop/` workspace ships the dashboard as a **native desktop app** for **macOS** (`Claude Code Monitor.app`, distributed as a `.dmg`) **and Windows** (`Claude Code Monitor.exe`, distributed as an NSIS installer plus a no-install portable build). It is an Electron shell that **embeds the existing Express server in-process** and renders the already-built React client in a `BrowserWindow`. The desktop app does not reimplement the dashboard -- it `require()`s `server/index.js` directly, in the same Node runtime as the Electron main process, and points a Chromium window at it.
|
||||
|
||||
For the user-facing guide (download, install, Gatekeeper / SmartScreen, tray menu, auto-start), see [DESKTOP.md](./DESKTOP.md). For the full contributor/architecture reference -- including build performance, code signing, notarization, and CI details -- see [desktop/README.md](./desktop/README.md).
|
||||
|
||||
### Workspace Position
|
||||
|
||||
`desktop/` is a **sibling workspace**, not an npm-workspaces conversion. It has its own `package.json`, its own `node_modules`, and its own TypeScript toolchain. It pins **Electron 35** (bundled Node 22.16). It consumes the rest of the repo as plain files and touches no other workspace's runtime behavior.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph repo["Claude-Code-Agent-Monitor (repo root)"]
|
||||
server["server/<br/>Express API · SQLite · WebSocket"]
|
||||
client["client/<br/>React + Vite SPA"]
|
||||
scripts["scripts/<br/>hook installer/handler, import, seed"]
|
||||
mcp["mcp/<br/>local MCP server"]
|
||||
vscode["vscode-extension/"]
|
||||
desktop["desktop/<br/>Electron shell (sibling workspace)"]
|
||||
end
|
||||
|
||||
desktop -->|"require() in-process"| server
|
||||
desktop -->|"loads built SPA from"| client
|
||||
desktop -->|"auto-installs hooks via"| scripts
|
||||
server -->|"serves static"| client
|
||||
|
||||
style desktop fill:#1f6feb,stroke:#1158c7,color:#fff
|
||||
style server fill:#238636,stroke:#196c2e,color:#fff
|
||||
```
|
||||
|
||||
The **only** change outside `desktop/` is a behavior-preserving refactor of `server/index.js` (see [Background Services & Hook Bootstrap](#background-services--hook-bootstrap-1) below). `client/`, `scripts/`, `mcp/`, and `vscode-extension/` are untouched.
|
||||
|
||||
### Process Model
|
||||
|
||||
Electron runs a **main process** (Node.js) and one or more **renderer processes** (Chromium). In this app:
|
||||
|
||||
- The **main process** hosts the embedded Express server _and_ manages the window, tray, and menus. There is **no child process and no IPC** for the server -- it runs inside the main process's own event loop.
|
||||
- The **renderer** is plain Chromium loading `http://127.0.0.1:<port>` -- exactly the same origin a normal browser would use. `preload.ts` is intentionally empty (`contextIsolation: true`, `nodeIntegration: false`, `webSecurity: true`), so the renderer has **zero privileged surface**.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph main["Electron Main Process (Node 22 / Electron 35)"]
|
||||
boot["main.ts<br/>lifecycle"]
|
||||
host["server-host.ts<br/>embedded server"]
|
||||
express["server/index.js<br/>Express + WS + SQLite"]
|
||||
tray["tray.ts"]
|
||||
menu["menu.ts"]
|
||||
host --> express
|
||||
boot --> host
|
||||
boot --> tray
|
||||
boot --> menu
|
||||
end
|
||||
|
||||
subgraph renderer["Renderer Process (Chromium)"]
|
||||
win["BrowserWindow<br/>React dashboard"]
|
||||
preload["preload.ts<br/>(empty -- no bridge)"]
|
||||
end
|
||||
|
||||
express -->|"http + ws on 127.0.0.1:port"| win
|
||||
win -.->|loads| preload
|
||||
|
||||
hooks["Claude Code hooks<br/>(separate node processes)"] -->|"POST /api/hooks/event"| express
|
||||
|
||||
style main fill:#0d1117,stroke:#30363d,color:#e6edf3
|
||||
style renderer fill:#161b22,stroke:#30363d,color:#e6edf3
|
||||
```
|
||||
|
||||
### In-Process Server Hosting
|
||||
|
||||
`server-host.ts` is the **only file** that imports `server/index.js`. The dashboard server already exports `{ createApp, startServer, startBackgroundServices }` and serves the built React client (`client/dist`) as static assets in production -- so the host imports that module directly, with no child process, no IPC, and no port marshalling.
|
||||
|
||||
| Component | Responsibility |
|
||||
| --- | --- |
|
||||
| **`main.ts`** | Main-process entry. Single-instance lock, app menu + tray wiring, dashboard window, `Restart Server`, lifecycle (`window-all-closed`, `before-quit`). |
|
||||
| **`server-host.ts`** | In-process Express boot: port discovery, adoption, `better-sqlite3` ABI patch, `startBackgroundServices()` + hook bootstrap, clean DB close. Returns a `ServerHandle`. |
|
||||
| **`window.ts`** | `BrowserWindow` with persisted geometry (`userData/window-state.json`). External links open in the system browser. Sets the window/taskbar `icon` to the colored app logo (`assets/icon.ico` on Windows, `icon.png` elsewhere) so an unpackaged `desktop:dev` run no longer shows the generic Electron icon. |
|
||||
| **`menu.ts` / `tray.ts`** | Native application menu and menu-bar / notification-area (tray) icon. `tray.ts` selects a platform tray image — a macOS template glyph that the OS tints for the menu bar, or the colored `assets/icon.ico` for the Windows notification area (a black template would vanish on the dark taskbar). Tray uses a single-click dropdown (left or right) with a **live status snapshot** queried straight from SQLite at click time — server port, active sessions, working agents, events today — followed by *Open Dashboard*, *Open in Browser*, *Restart Server*, *Show Logs*, *Open at Login* (toggle), and *Quit*. The menu is rebuilt on each open so every value stays current. Snapshot rows are enabled and click-to-open-dashboard rather than disabled (which the OS dims). The application menu's *File ▸ Open Dashboard* (⌘1) is **macOS-only** — there the global menu bar persists after the window hides; on Windows/Linux the window-attached menu can't reopen a hidden window, so reopening is the tray's job. `focusOrCreateWindow` calls `show()` unconditionally so the tray reliably raises a backgrounded/minimized window (a bare `focus()` on Windows often only flashes the taskbar). |
|
||||
| **`login-item.ts`** | Auto-start-at-login toggle through Electron's first-party `app.setLoginItemSettings` API on every platform. On macOS it drives the modern `SMAppService` Login Items (not a `LaunchAgent` plist); on Windows it writes a per-user `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` entry. Login launches are tagged with a `--ccam-hidden` arg so the app can stay tray-only at startup — Windows has no `wasOpenedAtLogin` signal, so the arg is the cross-platform detection mechanism. |
|
||||
| **`shell-path.ts`** | (macOS) Recovers the user's login-shell `PATH` at startup and merges it onto `process.env.PATH`, so the embedded server (and the `claude` CLI it spawns) is not limited to launchd's minimal `PATH`. On Windows the process already inherits the full user `PATH`, so no recovery is needed. |
|
||||
| **`logger.ts`** | File logger to `~/Library/Logs/Claude Code Monitor/desktop.log` (macOS) or `%APPDATA%\Claude Code Monitor\logs\desktop.log` (Windows) -- the main process has no console when launched from Finder / Explorer. |
|
||||
| **`constants.ts`** | Shared identifiers, including the `APP_ID` (`com.vn.smartgift.ccam.desktop`) that `main.ts` sets as the Windows AppUserModelId. |
|
||||
|
||||
`server-host.ts` resolves the directory containing the bundled `server/` and `client/dist/` via `resolveAppRoot()`: `process.resourcesPath/app` when packaged, or the repo root (one directory up from `desktop/`) in development.
|
||||
|
||||
The `ServerHandle` returned to `main.ts`:
|
||||
|
||||
```ts
|
||||
interface ServerHandle {
|
||||
url: string; // e.g. "http://127.0.0.1:4820"
|
||||
port: number;
|
||||
ownedByUs: boolean; // false when an existing server was adopted
|
||||
stop: () => Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
### Port Discovery & Adoption
|
||||
|
||||
On startup `server-host.ts` picks a port, then either adopts an already-healthy server or boots its own. **Adoption** -- `probePort()` connects to `:4820`, then checks that the listener answers `GET /api/health` with `{ status: "ok" }`. If a healthy dashboard server is already running there (e.g. the user ran `npm start` in a terminal), the desktop app **adopts** it rather than double-binding -- no SQLite contention. An adopted server is not owned by the app, so quitting the app leaves it running.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
start["startEmbeddedServer()"] --> forced{"CCAM_DESKTOP_BIND_PORT set?"}
|
||||
forced -->|yes| bind["bind exactly that port<br/>(no adoption, no fallback)"]
|
||||
forced -->|no| adopt{"healthy server<br/>already on :4820?"}
|
||||
adopt -->|yes| reuse["adopt it<br/>ownedByUs = false"]
|
||||
adopt -->|no| pick["pickFreePort()"]
|
||||
|
||||
pick --> p1{":4820 free?"}
|
||||
p1 -->|yes| use4820["use 4820"]
|
||||
p1 -->|no| p2{"any of<br/>:4821–:4829 free?"}
|
||||
p2 -->|yes| usefb["use that"]
|
||||
p2 -->|no| p3{"any of<br/>:49152–:49500 free?"}
|
||||
p3 -->|yes| userand["use that"]
|
||||
p3 -->|no| fail["throw — no free port"]
|
||||
|
||||
bind --> bootsrv["createApp() + startServer()"]
|
||||
use4820 --> bootsrv
|
||||
usefb --> bootsrv
|
||||
userand --> bootsrv
|
||||
bootsrv --> healthy["waitForHealthy()<br/>poll /api/health ≤ 30s"]
|
||||
healthy --> bg["bootstrapOwnedServer()"]
|
||||
bg --> handle["ServerHandle ownedByUs = true"]
|
||||
reuse --> handleR["ServerHandle ownedByUs = false"]
|
||||
|
||||
style reuse fill:#9e6a03,stroke:#7d5300,color:#fff
|
||||
style fail fill:#da3633,stroke:#b62324,color:#fff
|
||||
```
|
||||
|
||||
Port preference order is **4820 → 4821–4829 → a random port in 49152–49500**. Two environment overrides exist primarily for testing: `CCAM_DESKTOP_BIND_PORT` binds an exact port (disabling adoption and fallback, used by the smoke test), and `CCAM_DESKTOP_NO_ADOPT=1` always starts a fresh server. Before `require()`ing the server module, the host sets `NODE_ENV=production`, `DASHBOARD_PORT=<port>`, and `DASHBOARD_DATA_DIR=<userData>/data` (see [Writable Data Directory](#writable-data-directory) below) so the server reads them from `process.env`.
|
||||
|
||||
### Writable Data Directory
|
||||
|
||||
A packaged install directory is **read-only** in practice: on macOS a `.app` bundle installed under `/Applications`, code-signed, or run through **app translocation** cannot write to `Resources/app/`, and on Windows the NSIS install dir under `%ProgramFiles%` (or the read-only mount a portable build runs from) is no place for mutable state. The dashboard's SQLite database and the VAPID keypair (`server/lib/push.js`) are writable state, so they must not live inside the bundle / install dir. Before booting the embedded server, `server-host.ts` creates `app.getPath('userData')/data` and points the server at it via the `DASHBOARD_DATA_DIR` environment variable:
|
||||
|
||||
- `server/db.js` honors `DASHBOARD_DATA_DIR` for the SQLite file.
|
||||
- `server/lib/push.js` honors it for the persisted VAPID keys.
|
||||
|
||||
The resulting per-user location is `~/Library/Application Support/Claude Code Monitor/data/` on macOS and `%APPDATA%\Claude Code Monitor\data\` on Windows. Because this lives outside the bundle / install dir, imported history and persisted events **survive an app reinstall or update** (the Windows NSIS uninstaller keeps this data by default). Without this, writing a database into the read-only install location failed on a packaged build and broke History Import and event persistence.
|
||||
|
||||
The standalone `node server/index.js` path is **unaffected**: `DASHBOARD_DATA_DIR` is unset there, and `server-host.ts` only sets it when it is not already defined -- so `server/db.js` falls back to its usual repo-relative default.
|
||||
|
||||
### Shell `PATH` Recovery (macOS)
|
||||
|
||||
This step is **macOS-only**. A macOS app launched from Finder, the Dock, or Login Items auto-start is spawned by `launchd`, which hands it a **minimal `PATH`** (roughly `/usr/bin:/bin:/usr/sbin:/sbin`) and does **not** source the user's shell profile. The dashboard's "Run Claude" feature (`server/routes/run.js`, `server/lib/run-spawner.js`) spawns the `claude` CLI, which is almost always installed somewhere only the shell `PATH` knows about (`/opt/homebrew/bin`, `~/.local/bin`, `~/.claude/local`, a Node version-manager's bin dir). Under launchd's `PATH`, `claude` cannot be resolved or spawned.
|
||||
|
||||
`shell-path.ts` repairs this **before the server boots**: at startup it runs the user's login+interactive shell once (`$SHELL -ilc`, so `.zprofile`/`.zshrc` are sourced), captures the resulting `PATH` between sentinel markers, and merges it -- plus a fallback list of common CLI install directories -- onto `process.env.PATH`. The merge is order-preserving and deduplicated, so it is idempotent. Because the embedded server runs in the same process, it and every `claude` it spawns inherit the corrected `PATH`. (A `claude` shell _alias_ or _function_ still cannot be spawned -- only a real executable on the `PATH` can.)
|
||||
|
||||
On **Windows** there is no equivalent step: a process launched from Explorer, the Start menu, or the `HKCU\…\Run` startup entry already inherits the full user `PATH`, so the embedded server can resolve `claude` directly.
|
||||
|
||||
### `better-sqlite3` Native-Module Handling
|
||||
|
||||
`better-sqlite3` is the only **native** module in the dependency tree, and a native module must be compiled against the exact Node ABI it runs on. The repo-root copy is built for the **system Node** (so `npm run test:server` works for contributors); Electron ships its **own Node ABI**.
|
||||
|
||||
The desktop workspace solves this without disturbing the root install: the desktop workspace has its own `better-sqlite3`, rebuilt for Electron's Node ABI by `electron-builder install-app-deps` (run in its `postinstall`). `server-host.ts` then installs a one-time, **process-local** patch to `Module._resolveFilename` that redirects `require("better-sqlite3")` -- from anywhere in the embedded server -- to that ABI-correct copy.
|
||||
|
||||
Desktop setup is **guarded** so a missing or unbuilt binary never escapes as a raw node-gyp trace or a runtime crash: `desktop/scripts/preflight.js` (shared by `install.js` and `prebuild.js`) verifies the Electron-ABI binary exists and, when it doesn't, prints actionable, copy-pasteable setup help -- the per-OS C++ toolchain prerequisites (or a no-toolchain alternative that fetches Electron's prebuilt binary directly) -- before exiting non-zero. `desktop:install` runs this on install; the `prebuild` gate enforces it before every `desktop:*` build, turning a would-be runtime failure into a build-time error.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph desk["desktop/node_modules"]
|
||||
d1["better-sqlite3<br/>rebuilt for Electron's ABI<br/>(electron-builder install-app-deps)"]
|
||||
end
|
||||
subgraph root["node_modules (repo root)"]
|
||||
r1["better-sqlite3<br/>built for system Node<br/>(used by npm run test:server)"]
|
||||
end
|
||||
|
||||
patch["ensureNativeModulesPatched()<br/>overrides Module._resolveFilename"]
|
||||
srv["server/db.js<br/>require('better-sqlite3')"]
|
||||
|
||||
srv -->|"request intercepted"| patch
|
||||
patch -->|"redirected to"| d1
|
||||
patch -.->|"everything else<br/>passes through"| root
|
||||
|
||||
style d1 fill:#238636,stroke:#196c2e,color:#fff
|
||||
style patch fill:#1f6feb,stroke:#1158c7,color:#fff
|
||||
```
|
||||
|
||||
- The patch is installed exactly once, **before** `server/index.js` is `require()`d, and rewrites _only_ `require("better-sqlite3")` -- every other module resolves normally.
|
||||
- `electron-builder.yml` therefore **excludes** the root `better-sqlite3` from the bundle (it would trip `@electron/universal`'s identical-file detector) and `asarUnpack`s the desktop copy (native `.node` files cannot live inside an `asar` archive).
|
||||
- The `compat-sqlite` (`node:sqlite`) fallback remains a safety net -- one reason the desktop app pins **Electron 35**, whose bundled Node 22.16 has `node:sqlite`.
|
||||
|
||||
### Background Services & Hook Bootstrap
|
||||
|
||||
`node server/index.js` runs its production bootstrap from an `if (require.main === module)` block. Because the desktop app **`require()`s** that module, the block never fires -- so the bootstrap was extracted into an exported `startBackgroundServices()` that both paths call. This is a **behavior-preserving refactor** of `server/index.js`: the standalone server path is functionally unchanged.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph standalone["node server/index.js"]
|
||||
s1["require.main === module"] --> s2["startBackgroundServices()"]
|
||||
end
|
||||
subgraph desktopapp["desktop app"]
|
||||
d1["server-host.ts<br/>bootstrapOwnedServer()"] --> d2["startBackgroundServices()"]
|
||||
d1 --> d3["installHooks()"]
|
||||
end
|
||||
|
||||
d2 --> svc
|
||||
s2 --> svc
|
||||
subgraph svc["Background services"]
|
||||
u["update scheduler"]
|
||||
w["cc-watcher (Claude config watcher)"]
|
||||
r["orphaned-run reconciliation"]
|
||||
end
|
||||
|
||||
style d1 fill:#1f6feb,stroke:#1158c7,color:#fff
|
||||
```
|
||||
|
||||
`bootstrapOwnedServer()` runs **once** -- guarded by a module-level flag so a `Restart Server` does not double-register schedulers or watchers -- and:
|
||||
|
||||
1. Calls `startBackgroundServices()` -- the update scheduler, the `cc-watcher` config watcher, and one-time orphaned-run reconciliation.
|
||||
2. Calls `installHooks()` -- writes the Claude Code hook configuration to `~/.claude/settings.json`, so an install-only user (DMG on macOS, `.exe` on Windows) gets events flowing without ever running `npm run install-hooks` from a checkout.
|
||||
|
||||
It runs only when the server is **owned** by the app -- an adopted server has already done its own bootstrap.
|
||||
|
||||
### App Lifecycle
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant OS as macOS / Windows
|
||||
participant Main as main.ts
|
||||
participant Host as server-host.ts
|
||||
participant Srv as server/index.js
|
||||
participant UI as BrowserWindow
|
||||
|
||||
OS->>Main: launch app
|
||||
Main->>Main: setAppUserModelId (win32) · requestSingleInstanceLock()
|
||||
alt lock not acquired
|
||||
Main->>OS: exit(0) — focus existing instance
|
||||
end
|
||||
Main->>Host: ensureUserPath() — recover login-shell PATH (macOS only)
|
||||
Main->>Host: startEmbeddedServer()
|
||||
Host->>Host: probe :4820 — adopt if a healthy server answers
|
||||
alt no server to adopt
|
||||
Host->>Host: pickFreePort() · set DASHBOARD_DATA_DIR · patch better-sqlite3 ABI
|
||||
Host->>Srv: require() · createApp() · startServer(port)
|
||||
Host->>Srv: waitForHealthy() — poll /api/health ≤ 30s
|
||||
Host->>Srv: bootstrapOwnedServer() — schedulers, cc-watcher, install hooks
|
||||
end
|
||||
Host-->>Main: ServerHandle { url, port, ownedByUs, stop }
|
||||
Main->>Main: installApplicationMenu() · createTray()
|
||||
alt launched at login (--ccam-hidden / wasOpenedAtLogin)
|
||||
Main->>OS: stay tray-only, hide dock (macOS)
|
||||
else normal launch
|
||||
Main->>UI: createDashboardWindow(url)
|
||||
UI->>Srv: GET http://127.0.0.1:port
|
||||
end
|
||||
Note over Main: window "close" → hide (server keeps running)
|
||||
Note over Main: ⌘Q / Ctrl+Q → confirm (second press bypasses)
|
||||
Note over Main: before-quit → stop owned server + closeEmbeddedDatabase()
|
||||
```
|
||||
|
||||
| Event | Behavior |
|
||||
| --- | --- |
|
||||
| **Second launch** | `requestSingleInstanceLock()` (enabled on **every platform**) fails -- the new process exits and the existing window is focused. |
|
||||
| **Window close** | Intercepted -- the window **hides** (`hide()`); the server and tray keep running. |
|
||||
| **`window-all-closed`** | App stays alive in tray-only mode (the handler is intentionally a no-op). |
|
||||
| **Launched at login** | The dashboard window is **not** shown -- only the tray icon. Detected via macOS `wasOpenedAtLogin` (dock hidden, `openAsHidden`) or, on Windows, the `--ccam-hidden` arg written into the `HKCU\…\Run` startup command. |
|
||||
| **Quit shortcut** | ⌘Q (macOS) / Ctrl+Q (Windows) shows a confirmation dialog; a second press bypasses it. |
|
||||
| **`before-quit`** | If the server is owned: stop the HTTP server, then `closeEmbeddedDatabase()` for a clean WAL checkpoint, then `app.exit(0)`. The DB handle is closed here -- never on `Restart Server`, where the cached `server/db.js` singleton must stay usable. |
|
||||
|
||||
### Packaged App Layout
|
||||
|
||||
`electron-builder` produces `Claude Code Monitor.app` on macOS and `Claude Code Monitor.exe` (NSIS installer + portable) on Windows. On both platforms the Electron main-process code is compiled (`tsc` → `out/`) and packed into `app.asar`; the rest of the repo is shipped as **`extraResources`** -- plain files under the bundle's `Resources/app/` (macOS) or the install dir's `resources\app\` (Windows). The internal layout is the same shape on both:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
appbundle["Claude Code Monitor.app (macOS)<br/>Claude Code Monitor install dir (Windows)"]
|
||||
appbundle --> contents["Contents/ (macOS)<br/>install root (Windows)"]
|
||||
contents --> macos["MacOS/ — Electron binary (macOS)<br/>Claude Code Monitor.exe (Windows)"]
|
||||
contents --> res["Resources/ (macOS)<br/>resources\ (Windows)"]
|
||||
res --> asar["app.asar<br/>(compiled out/**, package.json)"]
|
||||
res --> unpacked["app.asar.unpacked/<br/>node_modules/better-sqlite3 (.node)"]
|
||||
res --> appdir["app/"]
|
||||
appdir --> a1["server/ — Express server (no tests)"]
|
||||
appdir --> a2["client/dist/ — built React SPA"]
|
||||
appdir --> a3["scripts/ — hook-handler, install-hooks"]
|
||||
appdir --> a4["node_modules/ — server runtime deps"]
|
||||
appdir --> a5["package.json"]
|
||||
|
||||
style asar fill:#1f6feb,stroke:#1158c7,color:#fff
|
||||
style appdir fill:#238636,stroke:#196c2e,color:#fff
|
||||
```
|
||||
|
||||
At runtime `server-host.ts` resolves this root as `process.resourcesPath/app` when packaged, on both platforms. Everything under the packaged `app/` is **read-only** on a packaged, signed, or app-translocated macOS bundle and on a Windows install under `%ProgramFiles%` (or a portable build's mount) -- so all writable state (the SQLite database, VAPID keys) lives in the per-user data dir (`~/Library/Application Support/Claude Code Monitor/data/` on macOS, `%APPDATA%\Claude Code Monitor\data\` on Windows), **never inside the bundle / install dir** (see [Writable Data Directory](#writable-data-directory)).
|
||||
|
||||
On macOS `electron-builder` produces **two per-architecture DMGs** — one `arm64` (Apple Silicon), one `x64` (Intel) — via `--mac --arm64 --x64` (not a merged universal binary; the release ships both), ad-hoc signed by default so anyone can build a working `.dmg` without a paid Apple Developer account; real Developer ID signing and notarization are opt-in via environment variables (`CSC_LINK`, `APPLE_ID`, etc.). On Windows it produces an **NSIS installer `.exe`** and a **no-install portable `.exe`** (both x64), using `assets/icon.ico` (generated from the source PNG by `desktop/scripts/build-win-icon.ps1`) as the application and tray icon. **`electron-builder` packages for the host OS** -- DMGs build on macOS, Windows `.exe`s build on Windows -- so the two artifacts come from two CI jobs (see below). The `desktop/scripts/prebuild.js` guard also **self-heals** a `better-sqlite3` native binary that a prior cross-arch DMG build (`electron-builder --mac --x64/--arm64`) left compiled for the wrong CPU architecture -- it detects the mismatch via `file` and re-runs `electron-builder install-app-deps`, so `desktop:dev` and `desktop:test` do not fail with `ERR_DLOPEN_FAILED`; on Windows it shells the `.cmd` shims for `npm`/`npx`. CI runs a path-filtered `🍎 macOS Desktop (DMG)` job on `macos-latest` (artifact `ClaudeCodeMonitor-dmg`) and a `🪟 Windows Desktop (EXE)` job on `windows-latest` (artifact `ClaudeCodeMonitor-win`); the release attaches both. See [`desktop/README.md`](./desktop/README.md) for the full build pipeline, build-performance notes, and signing details.
|
||||
|
||||
### Relation to Standalone Deployment
|
||||
|
||||
The desktop app is a fourth deployment mode alongside Development, Production, and Container (see [Deployment Modes](#deployment-modes)). The data path is **identical to the standalone Production path** -- Claude Code hooks `POST /api/hooks/event` to the embedded Express server, which writes to SQLite and broadcasts over WebSocket to the renderer. The only structural difference is that the server runs inside the Electron main process instead of a standalone `node server/index.js`, and the renderer is a `BrowserWindow` rather than a browser tab pointed at the same origin.
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
| Area | Approach |
|
||||
@@ -2687,26 +2371,6 @@ graph LR
|
||||
| **File watching** | `node --watch` + Vite HMR | None |
|
||||
| **Source maps** | Inline | External files |
|
||||
|
||||
### Desktop App (macOS & Windows)
|
||||
|
||||
The native desktop app (macOS `.app`/`.dmg`, Windows NSIS / portable `.exe`) is a self-contained deployment mode: a single Electron process embeds the Express server in-process and renders the React client in a `BrowserWindow`. No terminal, no separate `npm start`.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
LAUNCH["Open Claude Code Monitor<br/>(.app / .exe)"] --> MAIN["Electron main process<br/>(Node 22 / Electron 35)"]
|
||||
MAIN --> HOST["server-host.ts<br/>port discovery + adopt"]
|
||||
HOST --> SERVER["server/index.js (in-process)<br/>Port 4820 → fallback"]
|
||||
SERVER -->|serves| DIST["client/dist/<br/>(extraResources)"]
|
||||
MAIN --> WIN["BrowserWindow"]
|
||||
WIN --> SERVER
|
||||
|
||||
style MAIN fill:#1f6feb,stroke:#1158c7,color:#fff
|
||||
style SERVER fill:#339933,stroke:#5cb85c,color:#fff
|
||||
style DIST fill:#646CFF,stroke:#818cf8,color:#fff
|
||||
```
|
||||
|
||||
The hook ingestion path (Claude Code hooks → `POST /api/hooks/event` → SQLite → WebSocket) is **identical to the standalone Production path** -- only the process that hosts the server differs. See [Desktop App Architecture](#desktop-app-architecture-macos--windows--electron) for the full design.
|
||||
|
||||
### MCP Sidecar (Optional)
|
||||
|
||||
The MCP server runs as a sidecar alongside the dashboard, connecting to the same API. It supports three transport modes:
|
||||
@@ -2792,58 +2456,6 @@ docker run -d -p 4820:4820 \
|
||||
> [!NOTE]
|
||||
> **Hook note:** Claude Code hooks run on the host, not inside the container. The containerized server still receives hook events via HTTP on `localhost:4820` — run `npm run install-hooks` on the host after the container is up. `scripts/install-hooks.js` detects container execution and refuses there (issue #193) so it cannot write a container-internal handler path into a bind-mounted host `~/.claude`; the containerized server's boot-time auto-install is skipped for the same reason. Override with `CCAM_ALLOW_CONTAINER_HOOKS=1` only when Claude Code itself runs inside the container.
|
||||
|
||||
### Cloud Deployment
|
||||
|
||||
For production cloud deployments, the `deployments/` directory provides enterprise-grade infrastructure supporting four cloud providers and multiple deployment strategies.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Deployment Pipeline"
|
||||
direction LR
|
||||
CI["CI Pipeline<br/>Build · Test · Scan"] --> DEPLOY["Deployment<br/>Helm · Kustomize · Terraform"]
|
||||
DEPLOY --> VERIFY["Verification<br/>Health Check · Smoke Tests"]
|
||||
VERIFY -->|Fail| ROLLBACK["Rollback<br/>Instant Revert"]
|
||||
end
|
||||
|
||||
subgraph "Infrastructure"
|
||||
direction TB
|
||||
subgraph "Compute"
|
||||
BLUE["Blue Slot<br/>Current Version"]
|
||||
GREEN["Green Slot<br/>New Version"]
|
||||
end
|
||||
LB["Load Balancer<br/>TLS 1.3 · WebSocket<br/>Weighted Routing"]
|
||||
PV["Persistent Storage<br/>Encrypted NFS"]
|
||||
MON["Monitoring<br/>Prometheus · Grafana<br/>13 Alert Rules"]
|
||||
OTEL["OTel Collector<br/>Coralogix"]
|
||||
end
|
||||
|
||||
LB -->|"Active"| BLUE
|
||||
LB -.->|"Standby"| GREEN
|
||||
BLUE & GREEN --> PV
|
||||
MON -->|"Scrape"| BLUE & GREEN
|
||||
BLUE & GREEN -->|"logs + metrics + traces"| OTEL
|
||||
|
||||
style BLUE fill:#2563eb,color:#fff
|
||||
style GREEN fill:#16a34a,color:#fff
|
||||
style LB fill:#7c3aed,color:#fff
|
||||
style CI fill:#2088ff,color:#fff
|
||||
style OTEL fill:#4f46e5,color:#fff
|
||||
```
|
||||
|
||||
| Capability | Details |
|
||||
| --- | --- |
|
||||
| **Cloud Providers** | AWS (ECS Fargate + ALB), GCP (Cloud Run + GCLB), Azure (ACI + App Gateway), OCI (OKE + LBaaS) |
|
||||
| **Deployment Methods** | Helm chart, Kustomize overlays, Terraform modules |
|
||||
| **Release Strategies** | Rolling update, blue-green (instant switchover), canary (automated analysis) |
|
||||
| **Environments** | Dev, staging, production with per-environment configuration |
|
||||
| **CI/CD** | GitHub Actions and GitLab CI pipelines with Trivy security scanning |
|
||||
| **Observability** | Prometheus scraping, 13 alert rules, Grafana dashboard (16 panels), Alertmanager routing, Coralogix full-stack observability (logs, metrics, traces, SLO tracking) via OpenTelemetry Collector |
|
||||
| **Operations** | Scripts for deploy, rollback, blue-green switch, database backup/restore, teardown |
|
||||
| **Security** | Restricted PSS, network policies, TLS enforcement, OIDC auth, no long-lived credentials |
|
||||
|
||||
> [!NOTE]
|
||||
> 📘 **Full guide:** See [DEPLOYMENT.md](DEPLOYMENT.md) for step-by-step deployment instructions, and [deployments/README.md](deployments/README.md) for the infrastructure technical reference.
|
||||
|
||||
---
|
||||
|
||||
## Statusline Utility
|
||||
|
||||
-1080
File diff suppressed because it is too large
Load Diff
-253
@@ -1,253 +0,0 @@
|
||||
# Claude Code Monitor — Desktop App (macOS & Windows)
|
||||
|
||||
The dashboard ships with an optional **native desktop app** (built with Electron 35) that wraps the existing server + client into a single application you install once and forget — a macOS `.app` (shipped as a `.dmg`) and a Windows `.exe` (an NSIS installer plus a no-install portable build). Everything you see in the browser at `localhost:4820` lives inside this window, with native OS lifecycle on top: a menu-bar / notification-area (tray) icon, a native application menu, auto-start at login, and a single quit button that cleans up the server.
|
||||
|
||||
## Why this exists in addition to the PWA
|
||||
|
||||
The PWA (added in #144) makes the dashboard installable in Chromium-based browsers, which is great for users who already keep the server running. The desktop app solves the orthogonal problem: **starting and keeping the server running** without a terminal window. Concretely:
|
||||
|
||||
| Capability | PWA | Desktop App |
|
||||
|---|---|---|
|
||||
| Installs to dock / Applications | ✅ | ✅ |
|
||||
| Manages the Express server | ❌ — user must `npm start` separately | ✅ — embedded in-process |
|
||||
| Auto-starts at login | ❌ | ✅ via macOS Login Items / Windows `HKCU\…\Run` |
|
||||
| Menu-bar / notification-area (tray) icon for always-on status | ❌ | ✅ |
|
||||
| Native application menu (⌘ / Ctrl shortcuts, etc.) | ❌ | ✅ |
|
||||
| Survives browser restart | ⚠️ depends on browser | ✅ |
|
||||
|
||||
The two coexist — install whichever fits your workflow.
|
||||
|
||||
## Quick install
|
||||
|
||||
**Option A — download a pre-built installer** (recommended):
|
||||
|
||||
1. Open [**Releases → latest**](https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor/releases/latest) and grab the asset for your platform. Every `master` commit that bumps the version in `package.json` cuts a new `vX.Y.Z` release automatically (CI publishes it), so this link always lands on the current build — no GitHub sign-in required.
|
||||
|
||||
| Platform | Asset | Notes |
|
||||
|---|---|---|
|
||||
| macOS (Apple Silicon) | `ClaudeCodeMonitor-<ver>-arm64.dmg` | drag into `/Applications` |
|
||||
| macOS (Intel) | `ClaudeCodeMonitor-<ver>-x64.dmg` | drag into `/Applications` |
|
||||
| Windows (installer) | `ClaudeCodeMonitor-Setup-<ver>-x64.exe` | per-user install, no admin |
|
||||
| Windows (portable) | `ClaudeCodeMonitor-<ver>-x64-portable.exe` | run without installing |
|
||||
|
||||
2. Want a **per-commit build** instead of waiting for a release? Every green CI run uploads a workflow artifact (sign-in required, 14-day retention) — `ClaudeCodeMonitor-dmg` from the `🍎 macOS Desktop (DMG)` job and `ClaudeCodeMonitor-win` from the `🪟 Windows Desktop (EXE)` job:
|
||||
```bash
|
||||
gh run download <run-id> -R Smartgift-AI/Claude-Code-Monitor -n ClaudeCodeMonitor-dmg # or ClaudeCodeMonitor-win
|
||||
```
|
||||
3. **macOS:** double-click the DMG → drag `Claude Code Monitor.app` into your `Applications` folder. Open it; macOS may show a Gatekeeper warning the first time — see [Gatekeeper & SmartScreen](#gatekeeper--smartscreen-first-launch) below.
|
||||
4. **Windows:** run `ClaudeCodeMonitor-Setup-<ver>-x64.exe` (per-user, no admin) and follow the wizard, or just run the `*-portable.exe` to launch without installing. Windows **SmartScreen** may show *"Windows protected your PC"* the first time — see [Gatekeeper & SmartScreen](#gatekeeper--smartscreen-first-launch) below.
|
||||
|
||||
**Option B — build locally:**
|
||||
|
||||
```bash
|
||||
# In the project root, after `git clone`:
|
||||
npm run setup # installs root + client + vscode-extension deps
|
||||
npm run build # builds the React client
|
||||
npm run desktop:install # installs Electron + electron-builder
|
||||
|
||||
# Build for macOS (run ON macOS) — pick one:
|
||||
npm run desktop:dmg:arm64 # Apple Silicon only — FAST (~1 min); use this for your own Mac
|
||||
npm run desktop:dmg:x64 # Intel only — FAST
|
||||
npm run desktop:dmg # BOTH per-arch DMGs (arm64 + x64) — the release build; slower (packages each arch)
|
||||
npm run desktop:dmg:universal # ONE merged universal DMG (arm64 + x86_64 in a single file) — optional, slowest
|
||||
|
||||
# Build for Windows (run ON Windows) — pick one:
|
||||
npm run desktop:win # NSIS installer → desktop/release/ClaudeCodeMonitor-Setup-<ver>-x64.exe
|
||||
npm run desktop:win:portable # no-install portable → desktop/release/ClaudeCodeMonitor-<ver>-x64-portable.exe
|
||||
|
||||
# electron-builder packages for the HOST OS — you cannot build a Windows .exe
|
||||
# on macOS or a macOS .dmg on Windows.
|
||||
|
||||
# Open the macOS DMG you just built. desktop:dmg:arm64 / :x64 wipe release/ and emit
|
||||
# one DMG; desktop:dmg wipes release/ and emits both (…-arm64.dmg + …-x64.dmg).
|
||||
open desktop/release/ClaudeCodeMonitor-*-arm64.dmg # …-x64.dmg for the Intel build
|
||||
```
|
||||
|
||||
> **`desktop:dmg` builds both architectures, so it takes longer.** It packages
|
||||
> and ad-hoc-signs the app **twice** — once for `arm64`, once for `x64` — and
|
||||
> emits two separate DMGs (`…-arm64.dmg` + `…-x64.dmg`). It does **not** merge
|
||||
> them into a single universal binary; the release ships the two per-arch DMGs.
|
||||
> For running on **your own Mac**, use the arch-specific command
|
||||
> (`desktop:dmg:arm64` / `desktop:dmg:x64`) — half the work, and it finishes in
|
||||
> about a minute. CI runs `desktop:dmg` for you and uploads both DMGs as the
|
||||
> `ClaudeCodeMonitor-dmg` artifact, so you rarely need to build them locally.
|
||||
|
||||
## What happens when you launch the app
|
||||
|
||||
1. The Electron main process picks a free port — preferring **4820**, falling back to 4821–4829, then a random high port if all those are taken.
|
||||
2. If something already answers `/api/health` on port 4820 (e.g. you ran `npm start` in a terminal), the app **adopts that server** and skips starting a second one. No double-binding, no SQLite contention.
|
||||
3. Otherwise it `require()`s `server/index.js` directly in-process — same Node runtime as the main process, same memory. Boot is typically under two seconds.
|
||||
4. On startup the server records its **live port** to `~/.claude/.agent-dashboard.json`. The Claude Code hook handler reads that file, so events still reach the dashboard when the app bound a fallback port instead of 4820.
|
||||
5. The dashboard window opens — unless the app was launched at login (on macOS via Login Items; on Windows via the `HKCU\…\Run` entry, detected through a `--ccam-hidden` launch arg since Windows has no `wasOpenedAtLogin`), in which case it stays tray-only.
|
||||
6. A tray icon appears — the macOS **menu bar** or the Windows **notification area**. One click opens a dropdown with a **live status snapshot** (server port, active sessions, working agents, events today — all clickable to jump into the dashboard) plus *Open Dashboard*, *Open in Browser*, *Restart Server*, *Show Logs*, *Open at Login* (toggle), and *Quit*.
|
||||
|
||||
## Lifecycle semantics
|
||||
|
||||
- **Closing the window hides it.** The server keeps running, the tray icon stays, and (on macOS) the **dock icon stays too** — clicking either re-opens the window. Independent signals that the app is still alive.
|
||||
- **Quitting** (⌘Q / Ctrl+Q, *Quit* in the application menu, or *Quit* in the tray menu) pops a confirmation dialog — *"Quit Claude Code Monitor? Press ⌘Q again to skip this prompt and quit immediately."* Press **Quit** in the dialog, or **press ⌘Q / Ctrl+Q a second time** to bypass the prompt. Either way the SQLite handle is checkpointed cleanly before the process exits.
|
||||
- **Tray** — the macOS menu bar / Windows notification area. macOS uses a black template glyph the OS tints for light/dark menu bars; Windows uses the colored `icon.ico`, because a template glyph would vanish on the dark taskbar. A single click (left or right) opens the dropdown, which shows a **live status snapshot** pulled straight from the embedded SQLite handle each time it opens: server port, active sessions, working agents, and events today. Snapshot rows are clickable — they open the dashboard. The tray's *Open Dashboard* reliably **raises** the window even when it is minimized or behind other windows. (The application menu's *File ▸ Open Dashboard* / ⌘1 is **macOS-only** — on Windows/Linux a window-attached menu accelerator can't reopen a hidden window, so reopening is the tray's job there.)
|
||||
- **Window / taskbar icon** — the `BrowserWindow` sets its `icon` to the colored app logo (`icon.ico` on Windows, `icon.png` elsewhere — the same logo as the macOS Dock, rendered from `assets/icon.svg`), so an unpackaged `desktop:dev` run shows the real app logo in the title bar / taskbar instead of the generic Electron icon. The macOS dev Dock icon is set too; packaged apps already get theirs from the bundle `.icns`/`.exe`.
|
||||
- **Open-at-login toggle:** flip *Open at Login* in the tray menu (or the app menu). Both platforms go through Electron's first-party `app.*LoginItemSettings` API — no third-party deps. On **macOS** it registers via the `SMAppService` API, so the entry appears under → *System Settings → General → Login Items*. On **Windows** it writes a per-user `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` entry, visible under *Task Manager → Startup*; a login-triggered launch is detected via a `--ccam-hidden` arg (Windows has no `wasOpenedAtLogin`). On Linux the toggle is a no-op (unsupported).
|
||||
- **Single-instance:** double-launching just focuses the existing window. No second server, no port collision. (Applies on every platform.)
|
||||
- **Logs** live at `~/Library/Logs/Claude Code Monitor/desktop.log` on macOS and `%APPDATA%\Claude Code Monitor\logs\desktop.log` on Windows (use *Show Logs* in the tray menu to open the folder).
|
||||
- **Your data** (the SQLite database and VAPID keys) lives outside the app bundle / install dir, so it **survives app reinstalls and updates** — `~/Library/Application Support/Claude Code Monitor/data/` on macOS, `%APPDATA%\Claude Code Monitor\data\` on Windows. The Windows NSIS uninstaller **keeps this data by default** (`deleteAppDataOnUninstall: false`), mirroring how dragging the `.app` to the Trash on macOS never touches your data.
|
||||
- **The `claude` CLI on PATH.** On **macOS** the app resolves it using your login-shell `PATH`, recovered at startup — so "Run Claude" works even though a Finder/Dock-launched app would otherwise only inherit a minimal `PATH`. On **Windows** the inherited user `PATH` already includes it, so no recovery is needed.
|
||||
- **Notifications** (including the in-dashboard *Send test notification* button) are delivered as **native OS toasts** on both platforms when running inside the app — the embedded server calls Electron's `Notification` API directly. On Windows the app sets an `AppUserModelId` (`com.vn.smartgift.ccam.desktop`, matching the electron-builder `appId`) so toasts attribute to the app and its taskbar windows group correctly. Web Push doesn't work reliably inside Electron (Chromium-in-Electron ships without Firebase Cloud Messaging credentials, so `pushManager.subscribe` returns endpoints nothing can deliver to), and this path bypasses it entirely. The web dashboard at `npm start` continues to use Web Push as before.
|
||||
- **Coexists with the web dashboard.** You can run the desktop app and `npm run dev` (or `npm start`) at the same time. Each server writes its `{port, pid, startedAt, dataDir}` entry to a shared discovery file at `~/.claude/.agent-dashboard.json`, and the Claude Code hook handler POSTs to **one ingest target per unique SQLite data directory** (lowest port wins when both share `~/.claude/agent-dashboard`, so events are never double-ingested). Servers with **different** databases (e.g. the desktop app's Application Support dir alongside `npm run dev`) still each receive hooks and stay real-time.
|
||||
|
||||
## File layout (for contributors)
|
||||
|
||||
```
|
||||
desktop/
|
||||
├── package.json # Electron + electron-builder
|
||||
├── tsconfig.json
|
||||
├── electron-builder.yml # macOS (dmg) + Windows (nsis/portable) targets; signing/notarization hooks
|
||||
├── assets/ # icon.svg + generated icon.icns (macOS) + icon.ico (Windows) + tray PNGs
|
||||
├── src/
|
||||
│ ├── main.ts # main process entry, lifecycle; setAppUserModelId on win32
|
||||
│ ├── server-host.ts # in-process Express boot, port discovery, adopt
|
||||
│ ├── window.ts # BrowserWindow + persisted state
|
||||
│ ├── tray.ts # tray icon (platform image: template PNG on macOS, icon.ico on Windows) + context menu
|
||||
│ ├── menu.ts # native application menu
|
||||
│ ├── login-item.ts # open-at-login (macOS Login Items + Windows HKCU\…\Run startup)
|
||||
│ ├── shell-path.ts # recover the user's shell PATH (find `claude`)
|
||||
│ ├── preload.ts # (empty — kept for future renderer bridges)
|
||||
│ ├── logger.ts # file logger
|
||||
│ └── constants.ts # incl. APP_ID (matches electron-builder appId)
|
||||
├── scripts/
|
||||
│ ├── install.js # `desktop:install` wrapper: runs npm install, then prints actionable native-dep help + exits non-zero on failure
|
||||
│ ├── preflight.js # shared native-dep check (hasBetterSqliteBinary) + per-OS prerequisite help (printNativeDepHelp)
|
||||
│ ├── prebuild.js # ensures root + client are built before tsc; shells npm/npx on Windows (.cmd shims); fails fast with setup help when the better-sqlite3 native binary is missing
|
||||
│ ├── build-icons.sh # SVG → PNG/ICNS + tray PNGs via qlmanage/sips/iconutil (macOS)
|
||||
│ ├── build-win-icon.ps1 # icon.png → icon.ico for Windows (PowerShell + .NET)
|
||||
│ └── notarize.js # electron-builder afterSign hook (opt-in; macOS only)
|
||||
└── tests/
|
||||
└── smoke.test.mjs # spawn-and-probe /api/health (resolves the real electron binary via createRequire)
|
||||
```
|
||||
|
||||
**Changes outside `desktop/` are deliberately minimal:**
|
||||
|
||||
- `server/index.js` — a behavior-preserving refactor: the post-listen bootstrap (one-time legacy-session import, update scheduler, Claude Code config watcher, orphaned-run reconciliation) was extracted into an exported `startBackgroundServices()` so the embedded server runs exactly what `node server/index.js` runs. The standalone server path is functionally unchanged. (The legacy-session import previously sat in the standalone-only `require.main` block, so the desktop dashboard started empty — moving it into `startBackgroundServices()` fixes that.) It also now publishes its live port via `server/lib/server-info.js` on startup.
|
||||
- `server/lib/server-info.js` *(new)* — writes/reads the `~/.claude/.agent-dashboard.json` port discovery file.
|
||||
- `scripts/hook-handler.js` — resolves the dashboard port from the discovery file (falling back to `CLAUDE_DASHBOARD_PORT`, then 4820), so hook events reach the server even when it bound a fallback port.
|
||||
|
||||
`client/`, `mcp/`, and `vscode-extension/` are untouched. The Electron main process is otherwise just a host for the same code.
|
||||
|
||||
## Gatekeeper & SmartScreen (first launch)
|
||||
|
||||
### macOS — Gatekeeper
|
||||
|
||||
The DMG is **ad-hoc signed** by default — that's all the project can offer without a paid Apple Developer ID. macOS will warn the first time you open it: *"Apple could not verify…"*.
|
||||
|
||||
Two ways past it:
|
||||
|
||||
```bash
|
||||
# Easiest: strip the quarantine attribute from the DMG before opening.
|
||||
xattr -cr ~/Downloads/ClaudeCodeMonitor-*.dmg
|
||||
```
|
||||
|
||||
Or open → *System Settings → Privacy & Security*, scroll to the blocked DMG, click *Open Anyway*.
|
||||
|
||||
### Windows — SmartScreen
|
||||
|
||||
The Windows `.exe` (both the installer and the portable build) is **unsigned** by default, so Windows **SmartScreen** may show *"Windows protected your PC"* the first time you run it. Click **More info → Run anyway** to launch it.
|
||||
|
||||
Authenticode signing is opt-in for the maintainer: provide a code-signing certificate via `CSC_LINK` (a base64-encoded `.p12`) and `CSC_KEY_PASSWORD` and electron-builder signs the `.exe` automatically — no code change required. A signed build skips the SmartScreen prompt.
|
||||
|
||||
### Notarization (for the maintainer)
|
||||
|
||||
When you're ready to make this go away for everyone, add these three repository secrets:
|
||||
|
||||
| Secret | Where it comes from |
|
||||
|---|---|
|
||||
| `APPLE_ID` | Your Apple ID email |
|
||||
| `APPLE_TEAM_ID` | Your Apple Developer team ID |
|
||||
| `APPLE_APP_SPECIFIC_PASSWORD` | An app-specific password created at appleid.apple.com |
|
||||
|
||||
Optionally, also `CSC_LINK` (base64-encoded `.p12`) and `CSC_KEY_PASSWORD` to provide an explicit Developer ID certificate from outside the runner keychain. The CI workflow picks them up automatically — no code change required. See [`desktop/scripts/notarize.js`](desktop/scripts/notarize.js) for the hook.
|
||||
|
||||
> Local builds are **always ad-hoc signed**: the `package` script sets `CSC_IDENTITY_AUTO_DISCOVERY=false`, so a code-signing certificate already in your macOS keychain is never auto-discovered (an Apple Development cert would otherwise be picked up and fail distribution-type signing). Real signing activates only through the explicit `CSC_LINK` certificate above — that path is unaffected by the flag.
|
||||
|
||||
## Development workflow
|
||||
|
||||
```bash
|
||||
# Hot-iterate on the main process (rebuilds tsc on save would be next steps;
|
||||
# v1 ships without watch mode — just re-run desktop:dev after changes):
|
||||
npm run desktop:dev
|
||||
|
||||
# Smoke test (also runs in CI on macOS):
|
||||
npm run desktop:test
|
||||
|
||||
# macOS — single-architecture DMG — fast (~1 min):
|
||||
npm run desktop:dmg:arm64 # or desktop:dmg:x64 for Intel
|
||||
|
||||
# macOS — both per-arch DMGs — slower (builds + signs each architecture):
|
||||
npm run desktop:dmg
|
||||
|
||||
# macOS — one merged universal DMG (arm64 + x86_64 in a single file) — optional, slowest:
|
||||
npm run desktop:dmg:universal
|
||||
|
||||
# Windows — NSIS installer / no-install portable (run ON Windows):
|
||||
npm run desktop:win # NSIS installer .exe
|
||||
npm run desktop:win:portable # no-install portable .exe
|
||||
```
|
||||
|
||||
> electron-builder packages for the **host OS** — build DMGs on macOS and the
|
||||
> Windows `.exe`s on Windows. The Windows icon regenerates from `icon.png` with
|
||||
> `npm run build:win-icon` (PowerShell + .NET); the macOS icns + tray PNGs come
|
||||
> from `npm run build:icons`. On Windows, `better-sqlite3` is fetched as a
|
||||
> prebuilt Electron binary by `npm run desktop:install` (its postinstall runs
|
||||
> `electron-builder install-app-deps`), so no Visual Studio C++ toolchain is
|
||||
> needed in the common case. If that fetch/rebuild *does* fail (no C++ toolchain,
|
||||
> or a Node version with no prebuilt binary), `npm run desktop:install` — and any
|
||||
> `desktop:*` build, gated by `prebuild.js` — prints the exact per-OS fix plus a
|
||||
> no-toolchain alternative and **fails loudly** rather than crashing at runtime:
|
||||
>
|
||||
> ```bash
|
||||
> cd desktop
|
||||
> npm install --ignore-scripts
|
||||
> node node_modules/electron/install.js
|
||||
> npx electron-builder install-app-deps
|
||||
> ```
|
||||
>
|
||||
> A Node LTS (20/22) ships prebuilt `better-sqlite3` binaries and avoids the
|
||||
> compile entirely.
|
||||
|
||||
> After `npm run clean` in `desktop/`, you must `npm run build` again before
|
||||
> packaging — `clean` removes `out/`, and `electron-builder` only packages, it
|
||||
> does not compile. The `desktop:dmg*` scripts chain the build for you; a bare
|
||||
> `electron-builder` call does not, and fails with
|
||||
> _"entry file out/main.js does not exist"_.
|
||||
|
||||
The smoke test does not exercise the BrowserWindow (no display on headless CI). It spawns Electron, waits for the embedded server to answer `/api/health`, then shuts down. Anything that depends on the renderer is part of the manual QA checklist on the PR.
|
||||
|
||||
## Known caveats
|
||||
|
||||
- **Bundle size** ≈ 80 MB DMG, ≈ 250 MB on disk. The standard Electron tax. The Windows installer is comparable. Tauri would cut this dramatically but at the cost of a sidecar-process model and a Rust toolchain dependency — fair to revisit in a follow-up PR if bundle size becomes a real complaint.
|
||||
- **Native modules**: `better-sqlite3` is rebuilt against Electron's Node version automatically via `electron-builder install-app-deps` in the desktop workspace's `postinstall`. On Windows it is fetched as a **prebuilt Electron binary**, so no Visual Studio C++ toolchain is needed in the common case. If that build *does* fail (or the binary is missing afterward), `npm run desktop:install` — and any `desktop:*` build — prints the exact per-OS fix (Windows: Visual Studio Build Tools with the "Desktop development with C++" workload; macOS: `xcode-select --install`; Linux: build-essential + python3) plus a no-toolchain alternative (`npm install --ignore-scripts` → `node node_modules/electron/install.js` → `npx electron-builder install-app-deps`), and exits non-zero — failing loudly at install/build time rather than crashing at runtime. Even so, if the module is unavailable the server falls back to `node:sqlite` (per #37), so the app still boots.
|
||||
- **Per-architecture DMGs**: `npm run desktop:dmg` builds **both** macOS DMGs (one `arm64`, one `x64`) — the release build, and slower because it packages each architecture separately. It does **not** produce a merged universal binary; the release ships the two per-arch DMGs. `npm run desktop:dmg:arm64` and `npm run desktop:dmg:x64` build a single architecture instead — much faster, and roughly half the disk. If you specifically want a **single merged universal binary** (both slices in one `.dmg`, `lipo`-fat), `npm run desktop:dmg:universal` produces one via `@electron/universal` — the slowest option, and not what the release ships, but handy for hand-distributing one file that runs on any Mac.
|
||||
- **Auto-update**: not wired on either platform. The current update path is *re-download the latest installer* (DMG on macOS, `.exe` on Windows). `electron-updater` + GitHub Releases is the natural follow-up.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Cause | Fix |
|
||||
|---|---|---|
|
||||
| "Apple could not verify…" on first launch (macOS) | Unnotarized DMG | `xattr -cr ~/Downloads/ClaudeCodeMonitor-*.dmg` |
|
||||
| "Windows protected your PC" on first launch (Windows) | The `.exe` is unsigned by default (SmartScreen) | Click **More info → Run anyway**. To remove the prompt for everyone, the maintainer can enable Authenticode signing via `CSC_LINK` + `CSC_KEY_PASSWORD` |
|
||||
| macOS prompts to install Rosetta when opening the app | You installed the **x64** build on an Apple Silicon Mac | Check your arch with `uname -m` (`arm64` → Apple Silicon, build with `desktop:dmg:arm64`). The arch-specific `desktop:dmg:arm64` / `desktop:dmg:x64` builds each wipe `release/` and emit a single DMG whose mounted-volume title states the architecture — e.g. *Claude Code Monitor (Apple Silicon)* — so there is no ambiguous window to drag from. (`desktop:dmg` emits both per-arch DMGs at once, for release.) If stale DMGs from an older build linger, clear them with `rm -rf desktop/release` and rebuild |
|
||||
| Window shows but content is blank (macOS) | Server didn't boot — check `~/Library/Logs/Claude Code Monitor/desktop.log` | Restart from tray → *Restart Server* |
|
||||
| Window shows but content is blank (Windows) | Server didn't boot — check `%APPDATA%\Claude Code Monitor\logs\desktop.log` | Restart from tray → *Restart Server* |
|
||||
| Tray icon missing (macOS) | The OS hides tray icons when the menu bar is full | Move other menu-bar items aside, or look in the overflow chevron |
|
||||
| Tray icon missing (Windows) | Windows tucked it into the notification-area overflow | Click the **^** overflow chevron in the taskbar; drag the icon out to keep it pinned |
|
||||
| App didn't auto-start at login (macOS) | Login Items entry got revoked by macOS | Toggle *Open at Login* off and on again from the tray menu |
|
||||
| App didn't auto-start at login (Windows) | The `HKCU\…\Run` startup entry is missing or was disabled | Toggle *Open at Login* off and on again from the tray menu, then confirm the entry under *Task Manager → Startup* is **Enabled** |
|
||||
| `npm run desktop:win` / `:win:portable` fails or produces nothing | electron-builder packages for the host OS — you ran it on macOS/Linux | Build the Windows `.exe` **on Windows** (and DMGs on macOS) |
|
||||
| Desktop build/install fails on `better-sqlite3` / native binary missing | No C++ toolchain, or no prebuilt for your Node version | Run `npm run desktop:install` and follow the printed help, or use the no-toolchain alternative (`npm install --ignore-scripts` → `node node_modules/electron/install.js` → `npx electron-builder install-app-deps`); or use Node LTS 20/22 |
|
||||
| Port 4820 already in use, app refuses to start | Something other than the dashboard is on 4820 and it doesn't answer `/api/health` | The app will pick a fallback (4821–4829, then a random high port) — check the tray menu's port indicator |
|
||||
| Dashboard stays empty — 0 sessions, 0 agents, no real-time updates | The app bound a fallback port (4820 was taken), and the Claude Code hooks were posting events to the wrong port | Fixed — the server publishes its live port to `~/.claude/.agent-dashboard.json` and the hook handler reads it. After upgrading from a pre-fix build, **start a new Claude Code session** so the updated hooks take effect |
|
||||
| `desktop:dmg` seems slow | Not stuck — it packages two architectures back-to-back (`arch=x64` then `arch=arm64`) | Wait it out, or build a single architecture with `desktop:dmg:arm64` / `desktop:dmg:x64` |
|
||||
| Build fails: `entry file out/main.js does not exist` | `electron-builder` was run without compiling TypeScript first | Build via `npm run desktop:dmg*` (chains the build); don't invoke `electron-builder` bare |
|
||||
| Signing fails with `Application … could not be found` | A code-signing certificate in your keychain was auto-discovered | Fixed — the `package` script sets `CSC_IDENTITY_AUTO_DISCOVERY=false`; build via `npm run desktop:dmg*` |
|
||||
| "Run Claude" reports the `claude` CLI isn't on your PATH | A Finder/Dock-launched app inherits launchd's minimal PATH, not your shell PATH | Fixed — the app recovers your login-shell PATH at startup. If it persists, ensure `claude` is a real executable (not a shell alias/function) and on your shell PATH |
|
||||
| Imported history / sessions vanished after updating the app | Older builds stored the database inside the (replaceable) app bundle | Fixed — data now lives in `~/Library/Application Support/Claude Code Monitor/data/` and survives reinstalls. After upgrading from a pre-fix build, re-run **Import History → Rescan** once |
|
||||
| Signing fails: `Application … could not be found` after retries | A keychain code-signing certificate was auto-discovered | Fixed — the `package` script sets `CSC_IDENTITY_AUTO_DISCOVERY=false`; build via `npm run desktop:dmg*` |
|
||||
@@ -35,6 +35,10 @@ RUN npm run build
|
||||
FROM node:22-alpine
|
||||
WORKDIR /app
|
||||
|
||||
# Runs Claude Code sessions inside a named tmux session per lane so both the
|
||||
# dashboard (via node-pty attach) and a real terminal can share one live pane.
|
||||
RUN apk add --no-cache tmux
|
||||
|
||||
COPY --from=server-deps /app/node_modules ./node_modules/
|
||||
COPY package.json ./
|
||||
COPY server/ ./server/
|
||||
|
||||
+1
-140
@@ -1,6 +1,6 @@
|
||||
# Installation
|
||||
|
||||
A step-by-step guide to get the Claude Code Agent Monitor up and running on your machine, with optional sections for importing history, running in a container, and using the native desktop app (macOS & Windows).
|
||||
A step-by-step guide to get the Claude Code Agent Monitor up and running on your machine, with optional sections for importing history and running in a container.
|
||||
|
||||
## Fastest path — install it as a Claude Code plugin
|
||||
|
||||
@@ -189,122 +189,6 @@ Open **http://localhost:4820** in your browser.
|
||||
|
||||
---
|
||||
|
||||
## Desktop App (macOS & Windows) (optional)
|
||||
|
||||
If you'd rather not keep a terminal window open, the project also ships an Electron 35-based **native desktop app** (the `desktop/` workspace), available for both **macOS** and **Windows**. It embeds the Express server in-process, renders the built React client in a `BrowserWindow`, registers a menu-bar / notification-area (tray) icon, and offers a one-click "Open at Login" toggle. Everything you'd see in the browser at `localhost:4820` lives inside a single app you install once — distributed as a macOS `.app` (in a `.dmg`) and a Windows `.exe` (an NSIS installer plus a no-install portable build).
|
||||
|
||||
### Prerequisites
|
||||
|
||||
| For… | You need |
|
||||
|---|---|
|
||||
| Downloading a pre-built installer (macOS) | macOS — nothing else |
|
||||
| Downloading a pre-built installer (Windows) | Windows 10/11 (x64) — nothing else |
|
||||
| Building the DMG locally (macOS) | macOS, Node.js 20+ (22+ recommended), npm 9+, and **Xcode command-line tools** (`xcode-select --install`) so the native `better-sqlite3` module can be rebuilt for Electron's ABI |
|
||||
| Building the `.exe` locally (Windows) | Windows, Node.js 20+ (22+ recommended), npm 9+. `better-sqlite3` is fetched as a **prebuilt Electron binary** by `npm run desktop:install`, so no Visual Studio C++ toolchain is needed in the common case. If the build _does_ fail, `npm run desktop:install` prints the exact fix (Visual Studio Build Tools + "Desktop development with C++") plus a no-toolchain alternative and exits non-zero rather than failing silently |
|
||||
|
||||
### Way 1 — Download a pre-built installer
|
||||
|
||||
The fastest path. There are two flavours:
|
||||
|
||||
**1a. From the latest GitHub Release** *(recommended — public, no sign-in)*
|
||||
|
||||
Open [**Releases → latest**](https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor/releases/latest) and download the asset for your platform. CI publishes a new `vX.Y.Z` release automatically every time the version in `package.json` is bumped on `master`, so this link always points at the current shipping build.
|
||||
|
||||
| Platform | Asset | Notes |
|
||||
|---|---|---|
|
||||
| macOS (Apple Silicon) | `ClaudeCodeMonitor-<ver>-arm64.dmg` | drag into `/Applications` |
|
||||
| macOS (Intel) | `ClaudeCodeMonitor-<ver>-x64.dmg` | drag into `/Applications` |
|
||||
| Windows (installer) | `ClaudeCodeMonitor-Setup-<ver>-x64.exe` | per-user install, no admin |
|
||||
| Windows (portable) | `ClaudeCodeMonitor-<ver>-x64-portable.exe` | run without installing |
|
||||
|
||||
**1b. From the per-commit CI artifact** *(useful for testing master before it's tagged — sign-in required, 14-day retention)*
|
||||
|
||||
Every green run of the desktop CI jobs uploads a packaged artifact — `ClaudeCodeMonitor-dmg` from the `🍎 macOS Desktop (DMG)` job and `ClaudeCodeMonitor-win` from the `🪟 Windows Desktop (EXE)` job:
|
||||
|
||||
- **Via the GitHub UI:** open the latest passing run under [Actions](https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor/actions/workflows/ci.yml?query=branch%3Amaster+is%3Asuccess), scroll to **Artifacts**, and download `ClaudeCodeMonitor-dmg` (macOS) or `ClaudeCodeMonitor-win` (Windows).
|
||||
- **Via the `gh` CLI:**
|
||||
|
||||
```bash
|
||||
gh run download <run-id> -R Smartgift-AI/Claude-Code-Monitor -n ClaudeCodeMonitor-dmg # macOS
|
||||
gh run download <run-id> -R Smartgift-AI/Claude-Code-Monitor -n ClaudeCodeMonitor-win # Windows
|
||||
```
|
||||
|
||||
Unzip the macOS artifact to get the `.dmg`s, or the Windows artifact to get the NSIS installer + portable `.exe`s.
|
||||
|
||||
Then jump to [Install the app](#install-the-app).
|
||||
|
||||
### Way 2 — Build the installer locally
|
||||
|
||||
From the project root, after `git clone`. electron-builder packages for the **host OS**, so build the macOS DMG on a Mac and the Windows `.exe` on Windows. The common prelude is the same:
|
||||
|
||||
```bash
|
||||
npm run setup # install root + client + vscode-extension deps
|
||||
npm run build # build the React client (the SPA the window loads)
|
||||
npm run desktop:install # install Electron + electron-builder into desktop/
|
||||
|
||||
# macOS (run on macOS):
|
||||
npm run desktop:dmg:arm64 # fast single-arch DMG → desktop/release/
|
||||
|
||||
# Windows (run on Windows):
|
||||
npm run desktop:win # NSIS installer .exe → desktop/release/
|
||||
```
|
||||
|
||||
The artifact lands in `desktop/release/`. Pick the build command that matches your goal:
|
||||
|
||||
| Command | Platform / Architecture | Speed | Use when |
|
||||
|---|---|---|---|
|
||||
| `npm run desktop:dmg` | macOS — both per-arch DMGs (arm64 + x64) | **Slower** | Building the release DMGs for everyone |
|
||||
| `npm run desktop:dmg:arm64` | macOS — Apple Silicon only | Fast (~1 min) | Building for your own Apple Silicon Mac |
|
||||
| `npm run desktop:dmg:x64` | macOS — Intel only | Fast (~1 min) | Building for your own Intel Mac |
|
||||
| `npm run desktop:dmg:universal` | macOS — one merged universal DMG (arm64 + x86_64) | **Slowest** | Hand-distributing a single file that runs on any Mac (not what the release ships) |
|
||||
| `npm run desktop:win` | Windows — NSIS installer `.exe` (x64) | — | Building the per-user installer |
|
||||
| `npm run desktop:win:portable` | Windows — portable `.exe` (x64) | — | Building the no-install portable build |
|
||||
| `npm run desktop:install` | — | — | Install Electron + electron-builder deps; preflights the native `better-sqlite3` build and prints actionable setup help on failure |
|
||||
| `npm run desktop:build` | — | — | TypeScript compile only (`out/`) |
|
||||
| `npm run desktop:dev` | — | — | Build, then launch Electron locally |
|
||||
| `npm run desktop:test` | — | — | Smoke test (spawn Electron, probe `/api/health`) |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **DMGs build on macOS; Windows `.exe`s build on Windows** — electron-builder packages for the host OS. On macOS, `npm run desktop:dmg` builds the app **twice** (one tree per architecture) and emits **both** per-arch DMGs (`arm64` + `x64`) — the release build. It does **not** merge them into a single universal binary; the two DMGs are what ship. **When building for your own Mac, use `desktop:dmg:arm64` or `desktop:dmg:x64`** — a single architecture finishes in roughly a minute. CI already builds both DMGs and the Windows `.exe`s for you (see Way 1).
|
||||
|
||||
### Install the app
|
||||
|
||||
**macOS.** Each `desktop:dmg*` build wipes `release/` first. `desktop:dmg:arm64`
|
||||
→ `…-arm64.dmg` and `desktop:dmg:x64` → `…-x64.dmg` each emit a single DMG whose
|
||||
mounted-volume title states the architecture (e.g. *Claude Code Monitor (Apple
|
||||
Silicon)*); `desktop:dmg` emits **both** (`…-arm64.dmg` + `…-x64.dmg`) for
|
||||
release. Install the one matching your Mac: an x64 build on Apple Silicon makes
|
||||
macOS prompt for Rosetta.
|
||||
|
||||
```bash
|
||||
open desktop/release/ClaudeCodeMonitor-*-arm64.dmg # the arch you built
|
||||
```
|
||||
|
||||
1. The DMG mounts — drag **Claude Code Monitor** into your `Applications` folder.
|
||||
2. The DMG is ad-hoc signed, so macOS Gatekeeper shows a warning (*"Apple could not verify…"*) on first launch. Strip the quarantine attribute, then open it:
|
||||
|
||||
```bash
|
||||
xattr -cr "/Applications/Claude Code Monitor.app"
|
||||
open "/Applications/Claude Code Monitor.app"
|
||||
```
|
||||
|
||||
Alternatively, open → *System Settings → Privacy & Security* and click *Open Anyway*.
|
||||
|
||||
**Windows.**
|
||||
|
||||
1. Run `ClaudeCodeMonitor-Setup-<ver>-x64.exe`. It installs **per-user** (no administrator elevation) and lets you pick the install directory — or run the `*-portable.exe` to launch without installing.
|
||||
2. The installer is **unsigned** by default, so Windows **SmartScreen** may show *"Windows protected your PC"* on first launch — click **More info → Run anyway**.
|
||||
3. Launch from the Start menu / desktop shortcut.
|
||||
|
||||
Once running, the embedded server boots on port `4820` (or adopts an already-healthy server on `4820`, or falls back to `4821`–`4829` / a random high port), the menu-bar / notification-area (tray) icon appears, and the dashboard window opens. **Hooks are installed automatically on first boot** — an install-only user does not need `npm run install-hooks`; just start a new Claude Code session. Closing the window hides it but keeps the server running; **Quit** from the tray exits.
|
||||
|
||||
> [!NOTE]
|
||||
> The packaged app stores its SQLite database and VAPID keys in a per-user app-data directory **outside** the app bundle / install dir — `~/Library/Application Support/Claude Code Monitor/data/` on macOS, `%APPDATA%\Claude Code Monitor\data\` on Windows. Your imported history and events therefore **survive app reinstalls and updates** (the Windows NSIS uninstaller keeps this data by default). (Older macOS builds kept the database inside the bundle, which is read-only once installed and code-signed — that broke History Import; it is now fixed. If you are upgrading from a pre-fix build, there is a one-time data gap: re-run **Settings → Import History → Rescan** once.)
|
||||
|
||||
Full user guide: [`DESKTOP.md`](DESKTOP.md). Contributor / architecture reference: [`desktop/README.md`](desktop/README.md). Desktop-specific setup details (logs, auto-start, port adoption) are in [SETUP.md → Desktop App Setup](./SETUP.md#desktop-app-setup).
|
||||
|
||||
---
|
||||
|
||||
## Optional: Local MCP server
|
||||
|
||||
If you want AI agents to call dashboard functionality through MCP tools, run the local MCP server in `mcp/`:
|
||||
@@ -469,17 +353,6 @@ If you see an error box at startup saying *"SQLite backend not available"*, eith
|
||||
|
||||
Then run: `npm rebuild better-sqlite3`
|
||||
|
||||
### Desktop build or install fails on the native dependency
|
||||
|
||||
Unlike the root server (which falls back to `node:sqlite`), the desktop app **requires** `better-sqlite3` built for Electron's ABI. If that build can't happen, `npm run desktop:install` (and the desktop `prebuild` gate that runs before every `desktop:*` build) now stops with copy-pasteable setup help instead of a raw node-gyp trace or a runtime crash: it lists the per-OS C++ toolchain prerequisites (Windows: Visual Studio Build Tools + "Desktop development with C++"; macOS: `xcode-select --install`; Linux: build-essential + python3), notes that Node LTS 20/22 ship prebuilt binaries, and offers a no-toolchain alternative:
|
||||
|
||||
```bash
|
||||
cd desktop
|
||||
npm install --ignore-scripts
|
||||
node node_modules/electron/install.js
|
||||
npx electron-builder install-app-deps
|
||||
```
|
||||
|
||||
### `npm run dev` fails immediately
|
||||
|
||||
Ensure both server and client dependencies are installed:
|
||||
@@ -503,18 +376,6 @@ The Vite dev server and Express server run on different ports. Make sure both ar
|
||||
|
||||
See [SETUP.md — Troubleshooting](./SETUP.md#troubleshooting) for detailed hook debugging steps.
|
||||
|
||||
### Desktop App (macOS & Windows) issues
|
||||
|
||||
| Symptom | Cause | Fix |
|
||||
|---|---|---|
|
||||
| *"Apple could not verify…"* on first launch (macOS) | The DMG is ad-hoc signed (no paid Apple Developer ID) | `xattr -cr "/Applications/Claude Code Monitor.app"`, then open it — or use *System Settings → Privacy & Security → Open Anyway* |
|
||||
| *"Windows protected your PC"* on first launch (Windows) | The `.exe` is unsigned by default, so SmartScreen prompts | Click **More info → Run anyway** |
|
||||
| `npm run desktop:dmg` seems slow (macOS) | Not hung — it packages two architectures back-to-back (`arch=x64` then `arch=arm64`) | Wait it out, or use `npm run desktop:dmg:arm64` / `npm run desktop:dmg:x64` for a fast single-arch build |
|
||||
| `entry file out/main.js does not exist` | `npm run clean` (in `desktop/`) deleted `out/`; `electron-builder` only packages, it does not compile | Re-run `npm run desktop:build` (or just use a `desktop:dmg*` / `desktop:win*` script, which chains the build) |
|
||||
| Desktop window opens but is blank | The embedded server failed `/api/health` within 30 s | Check the desktop log (`~/Library/Logs/Claude Code Monitor/desktop.log` on macOS, `%APPDATA%\Claude Code Monitor\logs\desktop.log` on Windows), then tray → *Restart Server* |
|
||||
| "Run Claude" says `claude` is not on your PATH | A Finder/Dock-launched macOS app only inherits launchd's minimal PATH, not your login-shell PATH (on Windows the process already inherits the user PATH) | The app recovers your login-shell PATH at startup so it can find and spawn the `claude` CLI. If it still fails, make sure `claude` is a real executable on your shell PATH — not a shell alias or function |
|
||||
| Imported history vanished after updating the app | Older builds stored the database inside the (replaceable) `.app` bundle | Fixed — data now lives in the per-user app-data dir (`~/Library/Application Support/Claude Code Monitor/data/` on macOS, `%APPDATA%\Claude Code Monitor\data\` on Windows) and survives reinstalls/updates. After upgrading from a pre-fix build, re-run **Settings → Import History → Rescan** once |
|
||||
|
||||
---
|
||||
|
||||
## Ports
|
||||
|
||||
@@ -6,6 +6,8 @@ tool call to an Express + SQLite server, a React UI updates over WebSocket, and
|
||||
|
||||
Internal build — all rights reserved.
|
||||
|
||||
*(Tiếng Việt: [README.vi.md](README.vi.md))*
|
||||
|
||||
## What it does
|
||||
|
||||
- **Sessions, agents, events.** Everything Claude Code emits, recorded and
|
||||
@@ -15,8 +17,10 @@ Internal build — all rights reserved.
|
||||
- **Stage detection.** The stage is inferred from the tool stream, so a session
|
||||
that never calls `ccam stage` still shows progress — rendered dashed amber and
|
||||
never as done, because an inference is not evidence.
|
||||
- **Run Claude from the browser.** Spawn a session in a lane's directory, stream
|
||||
its output, send follow-ups, resume any past session.
|
||||
- **Run Claude from the browser.** A real terminal (tmux + a real PTY,
|
||||
rendered with xterm.js) attached to a lane's directory — the exact TUI you'd
|
||||
see locally, fully interactive, resumable, and attachable from a real
|
||||
terminal too via `ccam lanes shell`.
|
||||
- **Analytics, alerts, Kanban and a workflow view**, plus an MCP server and a CLI.
|
||||
|
||||
## Requirements
|
||||
@@ -75,6 +79,7 @@ ccam status # is the dashboard up
|
||||
ccam start # start it in the background and wait for healthy
|
||||
ccam sessions # recent sessions
|
||||
ccam lanes # lanes with stage and progress
|
||||
ccam lanes pipeline # this lane's pipeline template, or switch it
|
||||
ccam stage <name> # declare the current lane's stage
|
||||
ccam tail # live event feed
|
||||
```
|
||||
@@ -101,6 +106,12 @@ events and expires after `DETECTION_TTL_MS` (default 5 minutes), so a lane can
|
||||
move backwards between work sessions. Detection never writes the declared stage,
|
||||
and an inferred node never renders as done.
|
||||
|
||||
A lane's pipeline template can be switched after creation — `ccam lanes
|
||||
pipeline <template>` from the terminal, or the pipeline-template picker next to
|
||||
the lane's title in the Workspace detail panel. Both re-resolve the lane's
|
||||
current declared stage against the new template's nodes and warn if it no
|
||||
longer matches one.
|
||||
|
||||
A lane can also run **its own application stack**, isolated per lane, when its
|
||||
repository declares a profile at `<repo>/.ccam/profile/` — a `profile.env` of
|
||||
declarations plus shell hooks the dashboard calls. Each lane gets a slot, and its
|
||||
@@ -138,8 +149,7 @@ Both must be green before a commit; the pre-commit hook runs them plus Prettier.
|
||||
| `client/` | React 18 + Vite + Tailwind dashboard |
|
||||
| `bin/ccam.js` | CLI |
|
||||
| `mcp/` | MCP server exposing read-only dashboard tools |
|
||||
| `desktop/` | Electron wrapper that embeds the server |
|
||||
| `docs/` | Architecture, API, lanes, database, deployment |
|
||||
| `docs/` | Architecture, API, lanes, database |
|
||||
| `plugins/` | Claude Code plugins shipped with the dashboard |
|
||||
|
||||
## Docs
|
||||
@@ -148,5 +158,5 @@ Both must be green before a commit; the pre-commit hook runs them plus Prettier.
|
||||
- [`docs/LANES.md`](docs/LANES.md) — lanes, pipelines, stage detection
|
||||
- [`docs/API.md`](docs/API.md) — REST endpoints (`openapi.yaml` is generated)
|
||||
- [`docs/DATABASE.md`](docs/DATABASE.md) — tables and migrations
|
||||
- [`INSTALL.md`](INSTALL.md) · [`DEPLOYMENT.md`](DEPLOYMENT.md) · [`DESKTOP.md`](DESKTOP.md)
|
||||
- [`INSTALL.md`](INSTALL.md)
|
||||
- [`CLAUDE.md`](CLAUDE.md) — the rules an agent working in this repo must follow
|
||||
|
||||
+161
@@ -0,0 +1,161 @@
|
||||
# Claude Code Monitor
|
||||
|
||||
Bản build nội bộ SmartGift. Dashboard local-first cho Claude Code: hooks POST mỗi
|
||||
tool call lên server Express + SQLite, React UI cập nhật qua WebSocket, và
|
||||
**lane** (làn đường) theo dõi công việc song song của agent qua một pipeline.
|
||||
|
||||
Internal build — all rights reserved.
|
||||
|
||||
*(Bản dịch tiếng Việt của [README.md](README.md), tham khảo — README.md gốc là bản chính thức.)*
|
||||
|
||||
## Làm được gì
|
||||
|
||||
- **Session, agent, event.** Mọi thứ Claude Code emit ra, ghi lại và tìm kiếm
|
||||
được: tool call, token usage, cost, cây subagent, transcript.
|
||||
- **Lane.** Mỗi working directory một lane, sống sót qua session restart. Lane
|
||||
đi qua các pipeline stage và dashboard hiển thị nó đang ở đâu.
|
||||
- **Stage detection.** Stage được suy luận (infer) từ tool stream, nên một
|
||||
session không bao giờ gọi `ccam stage` vẫn hiển thị progress — render dạng
|
||||
viền chấm màu hổ phách (amber) và không bao giờ hiện `done`, vì suy luận
|
||||
không phải bằng chứng.
|
||||
- **Chạy Claude từ trình duyệt.** Spawn session trong thư mục của lane, stream
|
||||
output, gửi follow-up, resume session cũ bất kỳ.
|
||||
- **Analytics, alert, Kanban và workflow view**, cộng thêm MCP server và CLI.
|
||||
|
||||
## Yêu cầu
|
||||
|
||||
Node **>= 20** (`engines` trong `package.json`). Node **24** là bản test suite
|
||||
được verify — node 25 hiện đang làm gãy 6 test server do lệch ABI
|
||||
`better-sqlite3` và 20 test client do thay đổi global `localStorage`.
|
||||
|
||||
## Cài như Claude Code plugin
|
||||
|
||||
Hai lệnh, trên máy chỉ có Claude Code, không cần clone repo, không cần
|
||||
`npm run setup`:
|
||||
|
||||
```
|
||||
/plugin marketplace add Smartgift-AI/Claude-Code-Monitor
|
||||
/plugin install ccam@claude-code-agent-monitor-plugins
|
||||
```
|
||||
|
||||
Lần session-start đầu tiên sẽ cài hooks, boot server, đưa `ccam` vào PATH và
|
||||
kết nối MCP tools; chạy detached nên session không phải chờ. `/ccam-doctor`
|
||||
báo trạng thái, `/ccam-open` build UI và in URL, `/ccam-update` refresh sau
|
||||
khi plugin update. Đường này cần Node **>= 22.5** (không dùng
|
||||
`better-sqlite3` native, server dùng `node:sqlite`). Chi tiết, kể cả những gì
|
||||
cần xóa lúc uninstall: [`docs/PLUGINS.md`](docs/PLUGINS.md).
|
||||
|
||||
## Cài từ checkout
|
||||
|
||||
```bash
|
||||
npm run setup # cài dependency cho root, client và vscode-extension
|
||||
npm run build # build client vào client/dist
|
||||
npm start # serve client đã build + API trên :4820
|
||||
```
|
||||
|
||||
Mở <http://localhost:4820>.
|
||||
|
||||
Development, có hot reload:
|
||||
|
||||
```bash
|
||||
npm run dev # server trên :4820, Vite client trên :5173
|
||||
```
|
||||
|
||||
`DASHBOARD_PORT` override port, `DASHBOARD_CLIENT_DIST` override nơi UI đã
|
||||
build được serve (mặc định `client/dist`; bản cài qua plugin trỏ vào runtime
|
||||
directory riêng của nó). `postinstall` ghi các hook entry Claude Code để nạp
|
||||
dữ liệu cho dashboard — đừng chạy nó khi plugin `ccam` đã cài, không thì mỗi
|
||||
event bị đếm hai lần.
|
||||
|
||||
## CLI
|
||||
|
||||
`ccam` được link sẵn bởi `npm run setup`; không thì gọi `node bin/ccam.js`.
|
||||
|
||||
```bash
|
||||
ccam status # dashboard có đang chạy không
|
||||
ccam start # start ngầm (background) và chờ tới khi healthy
|
||||
ccam sessions # session gần đây
|
||||
ccam lanes # danh sách lane kèm stage và progress
|
||||
ccam lanes pipeline # pipeline template của lane này, hoặc đổi nó
|
||||
ccam stage <name> # khai báo stage hiện tại của lane
|
||||
ccam tail # xem live event feed
|
||||
```
|
||||
|
||||
`ccam --help` liệt kê phần còn lại.
|
||||
|
||||
## Lane
|
||||
|
||||
Lane là một working directory mà dashboard theo dõi. Hai loại:
|
||||
|
||||
- **adopted** (nhận nuôi) — một thư mục bạn đã có sẵn. Dashboard chỉ đọc nó;
|
||||
không bao giờ reset hay xóa.
|
||||
- **managed** (tự quản lý) — git worktree do dashboard tạo dưới `LANES_ROOT`.
|
||||
Dashboard sở hữu toàn bộ vòng đời và có thể reset/xóa nó, phía sau một guard
|
||||
ba lớp kiểm tra khi hủy (destroy guard) và một bước preflight đếm số mà bên
|
||||
gọi phải echo lại.
|
||||
|
||||
```bash
|
||||
ccam lanes add --cwd /path/to/repo --title "My feature" # adopt
|
||||
ccam lanes add --repo /path/to/repo --slug my-feature # managed worktree
|
||||
```
|
||||
|
||||
Stage khai báo (declared) đến từ `ccam stage`. Stage suy luận (inferred) đến
|
||||
từ tool event và hết hạn sau `DETECTION_TTL_MS` (mặc định 5 phút), nên lane có
|
||||
thể lùi lại giữa các work session. Detection không bao giờ ghi đè stage khai
|
||||
báo, và node suy luận không bao giờ render thành `done`.
|
||||
|
||||
Pipeline template của lane có thể đổi sau khi tạo — `ccam lanes
|
||||
pipeline <template>` từ terminal, hoặc dùng picker chọn pipeline-template
|
||||
cạnh tiêu đề lane trong panel chi tiết của trang Workspace. Cả hai đều
|
||||
re-resolve lại stage đã khai báo hiện tại của lane theo node-list của template
|
||||
mới, và cảnh báo nếu nó không còn khớp node nào.
|
||||
|
||||
Lane cũng có thể chạy **application stack riêng của nó**, cô lập theo từng
|
||||
lane, khi repository của nó khai báo một profile tại `<repo>/.ccam/profile/`
|
||||
— một file `profile.env` khai báo cộng shell hooks mà dashboard gọi. Mỗi lane
|
||||
được cấp một slot, port và thư mục riêng theo lane được suy ra từ đó:
|
||||
|
||||
```bash
|
||||
ccam lanes up # boot stack của lane sở hữu thư mục hiện tại
|
||||
ccam lanes runtime # slot, port, tình trạng service
|
||||
ccam lanes logs api # tail log của một service
|
||||
ccam lanes down
|
||||
```
|
||||
|
||||
Service chạy hoàn toàn detached, nên restart dashboard không bao giờ dừng
|
||||
lane đang chạy. Đây là namespacing tài nguyên trên host, không phải
|
||||
container: các lane chạy chung user và share network.
|
||||
|
||||
[`docs/LANES.md`](docs/LANES.md) có mô hình pipeline, destroy guard, hợp đồng
|
||||
(contract) preflight, trang Workspace, `GET /api/lanes/:id/git`, và toàn bộ
|
||||
hợp đồng runtime/profile.
|
||||
|
||||
## Test
|
||||
|
||||
```bash
|
||||
npm run test:server # node:test
|
||||
npm run test:client # Vitest
|
||||
```
|
||||
|
||||
Cả hai phải xanh (pass) trước khi commit; pre-commit hook chạy chúng cộng
|
||||
thêm Prettier.
|
||||
|
||||
## Cấu trúc thư mục
|
||||
|
||||
| Đường dẫn | Là gì |
|
||||
|---|---|
|
||||
| `server/` | Express API, schema SQLite, hook ingest, thư viện lane và worktree |
|
||||
| `client/` | Dashboard React 18 + Vite + Tailwind |
|
||||
| `bin/ccam.js` | CLI |
|
||||
| `mcp/` | MCP server expose các tool đọc dữ liệu dashboard (read-only) |
|
||||
| `docs/` | Architecture, API, lanes, database |
|
||||
| `plugins/` | Các Claude Code plugin đi kèm dashboard |
|
||||
|
||||
## Tài liệu
|
||||
|
||||
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — luồng request, schema, bề mặt WebSocket
|
||||
- [`docs/LANES.md`](docs/LANES.md) — lane, pipeline, stage detection
|
||||
- [`docs/API.md`](docs/API.md) — REST endpoint (`openapi.yaml` được generate tự động)
|
||||
- [`docs/DATABASE.md`](docs/DATABASE.md) — bảng và migration
|
||||
- [`INSTALL.md`](INSTALL.md)
|
||||
- [`CLAUDE.md`](CLAUDE.md) — quy tắc agent làm việc trong repo này phải tuân theo
|
||||
@@ -118,7 +118,7 @@ DASHBOARD_PORT=9000 npm run dev
|
||||
> [!NOTE]
|
||||
> You usually do **not** need to set `DASHBOARD_PORT` manually. `npm run dev` is wrapped by `scripts/dev.js`, which probes both `127.0.0.1` and `::1` (so an SSH `LocalForward` bound to one loopback can't slip past) and picks the first free port in `4820–4859` automatically. The chosen port is propagated to the Vite dev proxy via `DASHBOARD_PORT`, and the Express server writes it to `~/.claude/.agent-dashboard.json` so the Claude Code hook handler discovers it without any env var.
|
||||
>
|
||||
> Multiple dashboards can run side by side — for example `npm run dev` and the desktop app (macOS or Windows) at the same time. Each one appends its `{port, pid, startedAt}` entry to the discovery file, and `scripts/hook-handler.js` fan-outs every hook event to every live entry, so both UIs keep their real-time stream.
|
||||
> Multiple dashboards can run side by side — for example two `npm run dev` checkouts, or `npm run dev` alongside `npm start`. Each one appends its `{port, pid, startedAt}` entry to the discovery file, and `scripts/hook-handler.js` fan-outs every hook event to every live entry, so both UIs keep their real-time stream.
|
||||
>
|
||||
> Setting `CLAUDE_DASHBOARD_PORT=N` overrides discovery entirely and forces the hook handler to a single port — useful for tests and container setups where the in-process discovery file isn't reachable from the host.
|
||||
>
|
||||
@@ -217,59 +217,6 @@ The dashboard, landing page, and wiki each ship as independent Progressive Web A
|
||||
|
||||
**Verifying PWA status:** Open DevTools → Application → Manifest to confirm the manifest loads. Check the Service Workers section to verify the SW is registered and active. The Lighthouse PWA audit should pass all core checks.
|
||||
|
||||
### Desktop App Setup
|
||||
|
||||
The `desktop/` workspace ships the dashboard as a **native desktop app** for both **macOS** (a `.app` distributed as a `.dmg`) and **Windows** (an `.exe` — an NSIS installer plus a no-install portable build), built with Electron 35. It is an Electron shell that **embeds the existing Express server in-process** — it does not reimplement anything. For installation (download a pre-built installer from the [latest GitHub Release](https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor/releases/latest) or the per-commit `ClaudeCodeMonitor-dmg` / `ClaudeCodeMonitor-win` CI artifact, or build one locally — then on macOS mount, drag, Gatekeeper bypass; on Windows run the installer / portable, SmartScreen bypass), see [INSTALL.md → Desktop App (macOS & Windows)](./INSTALL.md#desktop-app-macos--windows-optional). The full user guide is [`DESKTOP.md`](./DESKTOP.md); the contributor / architecture reference is [`desktop/README.md`](./desktop/README.md).
|
||||
|
||||
This section covers the parts of running the desktop app that matter for setup.
|
||||
|
||||
**Building and running.** All commands run from the repo root. electron-builder packages for the **host OS** — build the macOS DMG on a Mac (`desktop:dmg*`) and the Windows `.exe` on Windows (`desktop:win*`):
|
||||
|
||||
| Script | Command | Description |
|
||||
|---|---|---|
|
||||
| `desktop:install` | `npm run desktop:install` | Install Electron + electron-builder into `desktop/`; fetches `better-sqlite3` as a prebuilt Electron binary for Electron's ABI (no Visual Studio C++ toolchain needed in the common case; on macOS, Xcode CLI tools cover any fallback build). Preflights the native `better-sqlite3` build; on failure prints actionable per-OS setup help plus a no-toolchain alternative and exits non-zero (also enforced by the desktop `prebuild` gate) |
|
||||
| `desktop:build` | `npm run desktop:build` | Prebuild guard + `tsc` → `desktop/out/` |
|
||||
| `desktop:dev` | `npm run desktop:dev` | Build, then launch Electron against `out/main.js` |
|
||||
| `desktop:test` | `npm run desktop:test` | Build, then run the smoke test (spawn Electron, probe `/api/health`) |
|
||||
| `desktop:dmg` | `npm run desktop:dmg` | **macOS** — **both** per-arch DMGs (arm64 + x64) → `desktop/release/`. Correct for release. **Slower** (packages each arch). |
|
||||
| `desktop:dmg:arm64` | `npm run desktop:dmg:arm64` | **macOS** — Apple-Silicon-only DMG → `desktop/release/`. **Fast (~1 min).** |
|
||||
| `desktop:dmg:x64` | `npm run desktop:dmg:x64` | **macOS** — Intel-only DMG → `desktop/release/`. **Fast (~1 min).** |
|
||||
| `desktop:win` | `npm run desktop:win` | **Windows** — NSIS installer `.exe` (x64) → `desktop/release/`. |
|
||||
| `desktop:win:portable` | `npm run desktop:win:portable` | **Windows** — no-install portable `.exe` (x64) → `desktop/release/`. |
|
||||
|
||||
> [!NOTE]
|
||||
> Every `desktop:dmg*` / `desktop:win*` script chains `npm run build` first. Running `electron-builder` bare skips the TypeScript compile and fails with `entry file out/main.js does not exist`. `npm run clean` inside `desktop/` deletes `out/` and `release/` — after a clean you must `npm run desktop:build` again before packaging.
|
||||
|
||||
> [!TIP]
|
||||
> On macOS, building a DMG rebuilds the native `better-sqlite3` module for the **target** architecture, which can leave it built for the wrong CPU arch for your local machine. The desktop `prebuild` step auto-heals this — it rebuilds `better-sqlite3` for the local machine on the next `desktop:build` — so `npm run desktop:dev` and `npm run desktop:test` keep working after a cross-arch DMG build with no manual `npm run desktop:install` needed.
|
||||
|
||||
**Hooks are auto-installed by the app.** On its first **owned-server** boot the desktop app writes the Claude Code hook configuration to `~/.claude/settings.json` itself, then starts the background services (update scheduler, `cc-watcher` config watcher, orphaned-run reconciliation) — the same `startBackgroundServices()` that `node server/index.js` runs. An install-only user (macOS or Windows) therefore never needs `npm run install-hooks` from a checkout: just **start a new Claude Code session** after the app is running. (If the app *adopts* an existing server instead of starting its own, that server already did its own hook bootstrap — see port adoption below.)
|
||||
|
||||
**Port-adoption behavior.** When the desktop app launches, its embedded server picks a port:
|
||||
|
||||
1. It prefers **`4820`**.
|
||||
2. If a healthy dashboard server already answers `GET /api/health` on `4820` (for example you ran `npm start` in a terminal), the app **adopts that server** instead of double-binding — no SQLite contention. An adopted server is *not* owned by the app, so quitting the app leaves it running.
|
||||
3. Otherwise it falls back to `4821`–`4829`, then to a random high port (`49152`–`49500`).
|
||||
|
||||
The chosen port is shown in the tray menu. The embedded server also honors the dashboard env vars in [Environment variables](#environment-variables) (`DASHBOARD_PORT` is set automatically by the desktop host).
|
||||
|
||||
**Data directory.** The packaged app stores its SQLite database and VAPID keys in a per-user app-data directory — `~/Library/Application Support/Claude Code Monitor/data/` on macOS, `%APPDATA%\Claude Code Monitor\data\` on Windows — **outside** the app bundle / install dir. The desktop host sets `DASHBOARD_DATA_DIR` to this per-user location automatically. Keeping writable state out of the bundle means a packaged, code-signed (and therefore read-only) `.app` never tries to write inside itself, and your imported history and events **survive app reinstalls and updates** (the Windows NSIS uninstaller keeps this data by default). (Older macOS builds kept the database inside the bundle, which broke History Import; after upgrading from a pre-fix build, re-run **Settings → Import History → Rescan** once to close the one-time data gap.)
|
||||
|
||||
**`claude` CLI resolution.** A Finder/Dock-launched macOS app inherits only launchd's minimal `PATH`, not your login-shell `PATH`. So the app can find and spawn the `claude` CLI for the "Run Claude" feature, the desktop host recovers your login-shell `PATH` at startup. (On Windows the process already inherits the user `PATH`, so no recovery is needed.) If "Run Claude" still reports that `claude` is not on `PATH`, make sure `claude` is a real executable on your shell `PATH` — a shell alias or function cannot be spawned.
|
||||
|
||||
**Auto-start at login.** Toggle *Open at Login* from the tray menu or the application menu. On macOS it registers via the first-party `SMAppService` API (Electron's `app.setLoginItemSettings`), so the entry appears under → *System Settings → General → Login Items*. On Windows it writes a per-user `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` entry, visible in *Task Manager → Startup*. When the app is launched at login, it starts **tray-only** — the dashboard window stays hidden until you click the tray icon.
|
||||
|
||||
**Logs.** The Electron main process has no terminal when launched from Finder / the Start menu, so it writes to a per-user log file:
|
||||
|
||||
```
|
||||
~/Library/Logs/Claude Code Monitor/desktop.log # macOS
|
||||
%APPDATA%\Claude Code Monitor\logs\desktop.log # Windows
|
||||
```
|
||||
|
||||
Open it from the tray menu → **Show Logs**. Set `CCAM_DESKTOP_VERBOSE=1` to also mirror `info`/`warn` lines to stdout when running via `npm run desktop:dev`.
|
||||
|
||||
**Lifecycle reminder.** Closing the dashboard window only **hides** it — the server and tray keep running. **Quit** (⌘Q or tray → *Quit*) shuts the embedded server down gracefully and exits. Double-launching just focuses the existing window (single-instance lock); it never starts a second server.
|
||||
|
||||
---
|
||||
|
||||
## Database
|
||||
@@ -607,48 +554,3 @@ If the build fails in Stage 1 with `better-sqlite3` errors, this is expected and
|
||||
- Ensure you are using the latest Dockerfile (it should use `node:22-alpine` and **not** install `python3`, `make`, or `g++`)
|
||||
- Run `docker build --no-cache -t agent-monitor .` to force a clean rebuild
|
||||
- Check that `package.json` has `better-sqlite3` under `optionalDependencies`, not `dependencies`
|
||||
|
||||
---
|
||||
|
||||
### macOS desktop app — `npm run desktop:dmg` is slow
|
||||
|
||||
This is expected. `desktop:dmg` compiles, packages, and ad-hoc-signs the app **twice** — once for `arm64`, once for `x64` — and emits **both** per-arch DMGs (`…-arm64.dmg` + `…-x64.dmg`). It does not merge them into a single universal binary; the two per-arch DMGs are what ship. Packaging two architectures back-to-back is what takes the time; it is not hung.
|
||||
|
||||
For a build that targets your own Mac, use a single-arch command instead — it builds one architecture and finishes in roughly a minute:
|
||||
|
||||
```bash
|
||||
npm run desktop:dmg:arm64 # Apple Silicon
|
||||
npm run desktop:dmg:x64 # Intel
|
||||
```
|
||||
|
||||
CI already produces both DMGs — pulled either from the [latest GitHub Release](https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor/releases/latest) (CI auto-publishes a `vX.Y.Z` when `package.json` is bumped on `master`) or from the per-commit `ClaudeCodeMonitor-dmg` workflow artifact — so you rarely need to build them locally.
|
||||
|
||||
---
|
||||
|
||||
### Desktop app — `entry file out/main.js does not exist`
|
||||
|
||||
You ran `electron-builder` without a TypeScript compile. `npm run clean` (in `desktop/`) deletes `out/`, and `electron-builder` only packages — it does not compile. Re-run `npm run desktop:build` first, or use a `desktop:dmg*` / `desktop:win*` script (each one chains `npm run build` for you). Never invoke `electron-builder` bare.
|
||||
|
||||
---
|
||||
|
||||
### macOS desktop app — Gatekeeper blocks the app on first launch
|
||||
|
||||
The DMG is **ad-hoc signed** by default (the project ships no paid Apple Developer ID), so macOS shows *"Apple could not verify…"* the first time you open the app. Strip the quarantine attribute:
|
||||
|
||||
```bash
|
||||
xattr -cr "/Applications/Claude Code Monitor.app"
|
||||
```
|
||||
|
||||
Or open → *System Settings → Privacy & Security* and click *Open Anyway*. Real Developer ID signing and notarization are opt-in via the `CSC_LINK` / `CSC_KEY_PASSWORD` and `APPLE_ID` / `APPLE_TEAM_ID` / `APPLE_APP_SPECIFIC_PASSWORD` repository secrets — see [`DESKTOP.md`](./DESKTOP.md#notarization-for-the-maintainer).
|
||||
|
||||
---
|
||||
|
||||
### Windows desktop app — SmartScreen blocks the app on first launch
|
||||
|
||||
The Windows `.exe` (NSIS installer and portable build) is **unsigned** by default, so Windows SmartScreen shows *"Windows protected your PC"* the first time you run it. Click **More info → Run anyway**. Authenticode signing is opt-in via the `CSC_LINK` / `CSC_KEY_PASSWORD` repository secrets — CI picks them up automatically when provided.
|
||||
|
||||
---
|
||||
|
||||
### Desktop app — no sessions appearing
|
||||
|
||||
The desktop app installs hooks on its **first owned-server boot**, not before. After the app is running, start a **new** Claude Code session and confirm `~/.claude/settings.json` contains entries referencing `hook-handler.js`. If the app adopted an existing server on `4820`, that server's own hook configuration applies instead. For a blank dashboard window, check the desktop log (`~/Library/Logs/Claude Code Monitor/desktop.log` on macOS, `%APPDATA%\Claude Code Monitor\logs\desktop.log` on Windows) via tray → *Show Logs* and use tray → *Restart Server*.
|
||||
|
||||
+33
@@ -2300,6 +2300,31 @@ async function cmdLanesPipeline(args) {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Attach a real terminal to the exact tmux session the dashboard uses for
|
||||
* this lane's run. Creates it if it doesn't exist yet (`tmux new-session -A`
|
||||
* is create-or-attach, the same idempotent semantics as clicking Start on
|
||||
* the dashboard). The user types `claude` themselves inside — this command's
|
||||
* only job is landing them in the right named session.
|
||||
*/
|
||||
async function cmdLanesShell(args) {
|
||||
const resolved = await resolveLaneArg(args);
|
||||
if (!resolved) return;
|
||||
const { lane } = await get(`/api/lanes/${resolved.laneId}`);
|
||||
const sessionName = `ccam-lane-${lane.id}`;
|
||||
const child = spawn("tmux", ["new-session", "-A", "-s", sessionName, "-c", lane.cwd], {
|
||||
stdio: "inherit",
|
||||
});
|
||||
await new Promise((resolve) => {
|
||||
child.on("close", resolve);
|
||||
child.on("error", (err) => {
|
||||
console.error(c.red(`✖ ${err?.message || err}`));
|
||||
process.exitCode = 1;
|
||||
resolve();
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
async function cmdFeatureShow(args) {
|
||||
const slug = args.find((arg) => !arg.startsWith("--"));
|
||||
if (!slug) {
|
||||
@@ -2484,6 +2509,11 @@ const COMMAND_GROUPS = [
|
||||
"[<template-id>] [<id>]",
|
||||
"Show, or switch, which pipeline template a lane renders against",
|
||||
],
|
||||
[
|
||||
"lanes shell",
|
||||
"[<id>]",
|
||||
"Attach a real terminal to the exact tmux session the dashboard uses for a lane's run",
|
||||
],
|
||||
[
|
||||
"lanes reset|remove|purge",
|
||||
"<id> [--force] [--keep-db] --yes",
|
||||
@@ -3362,6 +3392,9 @@ async function runCommand(argv) {
|
||||
if (rest[0] === "pipeline") {
|
||||
return cmdLanesPipeline(rest.slice(1));
|
||||
}
|
||||
if (rest[0] === "shell") {
|
||||
return cmdLanesShell(rest.slice(1));
|
||||
}
|
||||
if (rest[0] === "gc") {
|
||||
return cmdLanesGc(rest.slice(1));
|
||||
}
|
||||
|
||||
Generated
+17
@@ -10,6 +10,8 @@
|
||||
"dependencies": {
|
||||
"@fontsource/inter": "^5.2.8",
|
||||
"@fontsource/jetbrains-mono": "^5.2.8",
|
||||
"@xterm/addon-fit": "^0.10.0",
|
||||
"@xterm/xterm": "^5.5.0",
|
||||
"d3": "^7.9.0",
|
||||
"d3-sankey": "^0.12.3",
|
||||
"i18next": "^26.0.8",
|
||||
@@ -2100,6 +2102,21 @@
|
||||
"url": "https://opencollective.com/vitest"
|
||||
}
|
||||
},
|
||||
"node_modules/@xterm/addon-fit": {
|
||||
"version": "0.10.0",
|
||||
"resolved": "https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.10.0.tgz",
|
||||
"integrity": "sha512-UFYkDm4HUahf2lnEyHvio51TNGiLK66mqP2JoATy7hRZeXaGMRDr00JiSF7m63vR5WKATF605yEggJKsw0JpMQ==",
|
||||
"license": "MIT",
|
||||
"peerDependencies": {
|
||||
"@xterm/xterm": "^5.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/@xterm/xterm": {
|
||||
"version": "5.5.0",
|
||||
"resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-5.5.0.tgz",
|
||||
"integrity": "sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==",
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/agent-base": {
|
||||
"version": "7.1.4",
|
||||
"resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
|
||||
|
||||
@@ -13,6 +13,8 @@
|
||||
"dependencies": {
|
||||
"@fontsource/inter": "^5.2.8",
|
||||
"@fontsource/jetbrains-mono": "^5.2.8",
|
||||
"@xterm/addon-fit": "^0.10.0",
|
||||
"@xterm/xterm": "^5.5.0",
|
||||
"d3": "^7.9.0",
|
||||
"d3-sankey": "^0.12.3",
|
||||
"i18next": "^26.0.8",
|
||||
|
||||
@@ -35,11 +35,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./components/Layout`
|
||||
* - `./components/SplashScreen`
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./StatusBadge`
|
||||
* - `../lib/types`
|
||||
|
||||
@@ -27,11 +27,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/api`
|
||||
* - `../lib/eventBus`
|
||||
|
||||
@@ -31,11 +31,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `CheckboxProps` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `Checkbox` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `DateTimePicker` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
|
||||
@@ -35,11 +35,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `EmptyStateProps` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `EmptyState` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -24,11 +24,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/types`
|
||||
* - `../lib/event-grouping`
|
||||
|
||||
@@ -24,11 +24,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/api`
|
||||
* - `./DateTimePicker`
|
||||
|
||||
@@ -28,11 +28,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./StatusBadge`
|
||||
*
|
||||
|
||||
@@ -29,11 +29,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `FieldHelpProps` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `FieldHelp` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -29,11 +29,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/api`
|
||||
* - `../lib/eventBus`
|
||||
|
||||
@@ -35,11 +35,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./Sidebar`
|
||||
* - `./UpdateNotifier`
|
||||
|
||||
@@ -30,11 +30,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/api`
|
||||
* - `../lib/eventBus`
|
||||
|
||||
@@ -29,11 +29,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `SelectOption` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `SelectProps` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -23,11 +23,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./StatusBadge`
|
||||
* - `../lib/types`
|
||||
|
||||
@@ -24,11 +24,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/api`
|
||||
* - `../lib/eventBus`
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/api`
|
||||
* - `../lib/eventBus`
|
||||
|
||||
@@ -24,11 +24,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `Skeleton` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `StatValueSkeleton` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -27,11 +27,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `SplashScreen` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
|
||||
@@ -28,11 +28,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./Tip`
|
||||
* - `./Skeleton`
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/types`
|
||||
* - `./Tip`
|
||||
|
||||
@@ -26,11 +26,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./brain`
|
||||
*
|
||||
|
||||
@@ -29,11 +29,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `SpeechBubble` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
|
||||
@@ -29,11 +29,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./CatAvatar`
|
||||
* - `./SpeechBubble`
|
||||
|
||||
@@ -23,11 +23,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./brain`
|
||||
*
|
||||
|
||||
@@ -167,26 +167,11 @@ describe("reduceTabby counts and pulses", () => {
|
||||
expect(ok.state.worriedUntil).toBe(0);
|
||||
});
|
||||
|
||||
it("run_status completed exit 0 is happy, nonzero/error/killed is worried", () => {
|
||||
const good = reduceTabby(
|
||||
initialTabbyState(T0),
|
||||
runStatusMsg({ status: "completed", exitCode: 0 }),
|
||||
T0
|
||||
);
|
||||
expect(good.pulse).toBe("run_done");
|
||||
expect(deriveMood(good.state, T0)).toBe("happy");
|
||||
const bad = reduceTabby(
|
||||
initialTabbyState(T0),
|
||||
runStatusMsg({ status: "completed", exitCode: 1 }),
|
||||
T0
|
||||
);
|
||||
expect(bad.pulse).toBe("error");
|
||||
const err = reduceTabby(initialTabbyState(T0), runStatusMsg({ status: "error" }), T0);
|
||||
expect(err.pulse).toBe("error");
|
||||
const killed = reduceTabby(initialTabbyState(T0), runStatusMsg({ status: "killed" }), T0);
|
||||
expect(killed.pulse).toBe("error");
|
||||
it("run_status updates activity timestamp only (no exit code available)", () => {
|
||||
const running = reduceTabby(initialTabbyState(T0), runStatusMsg({ status: "running" }), T0);
|
||||
expect(running.pulse).toBe(null);
|
||||
const gone = reduceTabby(initialTabbyState(T0), runStatusMsg({ status: "gone" }), T0);
|
||||
expect(gone.pulse).toBe(null);
|
||||
});
|
||||
|
||||
it("any handled message refreshes lastActivityAt", () => {
|
||||
|
||||
@@ -24,11 +24,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
*
|
||||
@@ -345,25 +340,7 @@ export function reduceTabby(
|
||||
case "run_status": {
|
||||
const r = msg.data as RunStatusPayload;
|
||||
if (!r) return { state, pulse: null };
|
||||
// A run that finished cleanly (exit 0, or no exit code reported) → happy.
|
||||
if (r.status === "completed" && (r.exitCode == null || r.exitCode === 0)) {
|
||||
return {
|
||||
state: { ...state, happyUntil: now + HAPPY_MS, lastActivityAt: now },
|
||||
pulse: "run_done",
|
||||
};
|
||||
}
|
||||
// Errored, killed, or completed with a nonzero exit code → worried.
|
||||
if (
|
||||
r.status === "error" ||
|
||||
r.status === "killed" ||
|
||||
(r.status === "completed" && r.exitCode != null && r.exitCode !== 0)
|
||||
) {
|
||||
return {
|
||||
state: { ...state, worriedUntil: now + WORRIED_MS, lastActivityAt: now },
|
||||
pulse: "error",
|
||||
};
|
||||
}
|
||||
// spawning / running → activity only.
|
||||
// running / gone → activity only (no exit code to distinguish success/failure).
|
||||
return { state: { ...state, lastActivityAt: now }, pulse: null };
|
||||
}
|
||||
|
||||
|
||||
@@ -23,11 +23,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./brain`
|
||||
*
|
||||
|
||||
@@ -22,11 +22,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `TabbyPos` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `tabbyPrefs` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -22,11 +22,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./brain`
|
||||
*
|
||||
|
||||
@@ -23,11 +23,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/eventBus`
|
||||
* - `../../lib/api`
|
||||
|
||||
@@ -25,11 +25,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./prefs`
|
||||
*
|
||||
|
||||
@@ -32,11 +32,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `Tip` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
|
||||
@@ -33,11 +33,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/api`
|
||||
* - `../lib/eventBus`
|
||||
|
||||
@@ -27,11 +27,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/api`
|
||||
* - `./Select`
|
||||
|
||||
@@ -22,11 +22,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/highlight`
|
||||
*
|
||||
|
||||
@@ -25,11 +25,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/api`
|
||||
* - `../../lib/eventBus`
|
||||
|
||||
@@ -29,11 +29,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./CodeBlock`
|
||||
*
|
||||
|
||||
@@ -24,11 +24,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
* - `./ToolCallBlock`
|
||||
|
||||
@@ -24,11 +24,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
* - `./CodeBlock`
|
||||
|
||||
@@ -22,11 +22,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `ToolStyle` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `styleForTool` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -24,11 +24,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `TuiSegment` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `stripAnsi` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -24,11 +24,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `CopyButton` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `Terminal` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -36,11 +36,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./primitives`
|
||||
*
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
/**
|
||||
* @file The compact lane tile used in the Workspace carousel. It carries only
|
||||
* what you need to pick a lane — which lane, is it alive, what stage, how far —
|
||||
* because the full card, its controls and its working-copy facts live in the
|
||||
* detail panel below. Keeping the tile small is what lets a dozen lanes stay
|
||||
* scannable in one horizontal row.
|
||||
* @file The compact lane tile used in the Workspace's vertical lane list. It
|
||||
* carries only what you need to pick a lane — which lane, is it alive, what
|
||||
* stage, how far — because the full card, its controls and its working-copy
|
||||
* facts live in the detail panel beside it. Keeping the tile small and full
|
||||
* width is what lets many lanes stay scannable in one scrolling column.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
|
||||
@@ -42,7 +42,7 @@ export default function LaneStripCard({
|
||||
aria-pressed={selected}
|
||||
onClick={onSelect}
|
||||
title={lane.cwd}
|
||||
className={`w-56 shrink-0 snap-start rounded-lg border p-3 text-left shadow-sm transition-colors ${
|
||||
className={`w-full shrink-0 rounded-lg border p-3 text-left shadow-sm transition-colors ${
|
||||
selected
|
||||
? "border-accent bg-accent/10"
|
||||
: "border-border bg-surface-2 hover:border-border-light hover:bg-surface-3"
|
||||
|
||||
@@ -0,0 +1,403 @@
|
||||
/**
|
||||
* @file LaneConsolePane.tsx
|
||||
* @description One lane's run console: the RunSetup ↔ TerminalView switcher,
|
||||
* moved out of Workspace.tsx so the Workspace page can render 1, 2, or 4 of
|
||||
* these side by side (split terminal view). Owns its own prompt/cwd/model/
|
||||
* permissionMode/effort/resumeSession/handle/busy/runHistory state — nothing
|
||||
* is shared between panes. `lanes`, `binaryStatus`, `cwdSuggestions`, and
|
||||
* `activeRuns` are supplied as props because they are global, not
|
||||
* lane-specific, and fetching them per pane would mean N redundant identical
|
||||
* requests for an N-pane layout.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
|
||||
import { useCallback, useEffect, useState } from "react";
|
||||
import { useTranslation } from "react-i18next";
|
||||
import { Play, AlertCircle } from "lucide-react";
|
||||
import { api } from "../../lib/api";
|
||||
import type {
|
||||
CwdSuggestion,
|
||||
DashboardRunHistoryItem,
|
||||
EffortLevel,
|
||||
PermissionMode,
|
||||
RunHandle,
|
||||
RunListResponse,
|
||||
RunStartArgs,
|
||||
} from "../../lib/api";
|
||||
import type { Session, Lane } from "../../lib/types";
|
||||
import { TerminalView } from "./TerminalView";
|
||||
import { RunSetup } from "./RunSetup";
|
||||
import { ActiveRunsSwitcher } from "./RunHistory";
|
||||
|
||||
export interface LaneConsolePaneProps {
|
||||
lanes: Lane[];
|
||||
laneId: number | null;
|
||||
showLaneSelector: boolean;
|
||||
onLaneIdChange: (id: number) => void;
|
||||
onLaneCreated: (lane: Lane) => void;
|
||||
binaryStatus: { found: boolean; path: string | null } | null;
|
||||
cwdSuggestions: CwdSuggestion[];
|
||||
activeRuns: RunListResponse | null;
|
||||
wsConnected: boolean;
|
||||
defaultCwd?: string;
|
||||
onHasActiveRunChange?: (active: boolean) => void;
|
||||
}
|
||||
|
||||
export function LaneConsolePane({
|
||||
lanes,
|
||||
laneId,
|
||||
showLaneSelector,
|
||||
onLaneIdChange,
|
||||
onLaneCreated,
|
||||
binaryStatus,
|
||||
cwdSuggestions,
|
||||
activeRuns,
|
||||
wsConnected,
|
||||
defaultCwd,
|
||||
onHasActiveRunChange,
|
||||
}: LaneConsolePaneProps) {
|
||||
const { t } = useTranslation("run");
|
||||
const { t: tLanes } = useTranslation("lanes");
|
||||
const { t: tCommon } = useTranslation("common");
|
||||
|
||||
const [prompt, setPrompt] = useState("");
|
||||
const [model, setModel] = useState("");
|
||||
const [permissionMode, setPermissionMode] = useState<PermissionMode>("acceptEdits");
|
||||
const [effort, setEffort] = useState<EffortLevel>("");
|
||||
const [cwd, setCwd] = useState(() => lanes.find((l) => l.id === laneId)?.cwd ?? defaultCwd ?? "");
|
||||
const [resumeSession, setResumeSession] = useState<Session | null>(null);
|
||||
const [handle, setHandle] = useState<RunHandle | null>(null);
|
||||
const [busy, setBusy] = useState<"start" | "kill" | "attach" | null>(null);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
const [runHistory, setRunHistory] = useState<DashboardRunHistoryItem[]>([]);
|
||||
|
||||
const currentLane = laneId !== null ? lanes.find((l) => l.id === laneId) : null;
|
||||
|
||||
useEffect(() => {
|
||||
onHasActiveRunChange?.(handle !== null);
|
||||
}, [handle, onHasActiveRunChange]);
|
||||
|
||||
useEffect(() => {
|
||||
if (!currentLane && defaultCwd && cwd === "") {
|
||||
setCwd(defaultCwd);
|
||||
}
|
||||
}, [defaultCwd, currentLane, cwd]);
|
||||
|
||||
const refreshList = useCallback(() => {
|
||||
if (laneId !== null) {
|
||||
api.run
|
||||
.history(50, { laneId })
|
||||
.then((r) => setRunHistory(r.items))
|
||||
.catch(() => undefined);
|
||||
} else {
|
||||
api.run
|
||||
.history(50)
|
||||
.then((r) => setRunHistory(r.items))
|
||||
.catch(() => undefined);
|
||||
}
|
||||
}, [laneId]);
|
||||
|
||||
const attachToRun = useCallback(
|
||||
async (id: string) => {
|
||||
if (busy) return;
|
||||
setBusy("attach");
|
||||
setError(null);
|
||||
try {
|
||||
const fetched = await api.run.get(id);
|
||||
setHandle(fetched);
|
||||
} catch (err: unknown) {
|
||||
const m = err instanceof Error ? err.message : "unknown";
|
||||
setError(t("errors.attachFailed", { message: m }));
|
||||
} finally {
|
||||
setBusy(null);
|
||||
}
|
||||
},
|
||||
[busy, t]
|
||||
);
|
||||
|
||||
const onStartFromSetup = useCallback(
|
||||
async (args: RunStartArgs) => {
|
||||
if (busy) return;
|
||||
setBusy("start");
|
||||
setError(null);
|
||||
try {
|
||||
const effectiveCwd = args.cwd || undefined;
|
||||
|
||||
if (!effectiveCwd) {
|
||||
throw new Error(t("errors.cwdRequired"));
|
||||
}
|
||||
|
||||
// Resolve the lane from the cwd the user actually typed, not from
|
||||
// args.laneId — RunSetup always supplies this pane's laneId (a
|
||||
// required prop), which would otherwise silently start a run in the
|
||||
// wrong lane whenever the user types a cwd different from the one
|
||||
// this pane currently shows.
|
||||
const ownedLane = lanes.find((l) => l.cwd === effectiveCwd);
|
||||
let targetLaneId: number;
|
||||
if (ownedLane) {
|
||||
targetLaneId = ownedLane.id;
|
||||
if (ownedLane.id !== laneId) onLaneIdChange(ownedLane.id);
|
||||
} else {
|
||||
try {
|
||||
const ensureResult = await api.lanes.ensure({ cwd: effectiveCwd });
|
||||
targetLaneId = ensureResult.lane.id;
|
||||
onLaneIdChange(ensureResult.lane.id);
|
||||
onLaneCreated(ensureResult.lane);
|
||||
} catch (err) {
|
||||
throw new Error(
|
||||
t("errors.laneCreateFailed", {
|
||||
message: err instanceof Error ? err.message : "unknown",
|
||||
})
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
let laneStartResult;
|
||||
try {
|
||||
laneStartResult = await api.lanes.action(targetLaneId, "start", {
|
||||
prompt: args.initialPrompt || "",
|
||||
model: args.model || undefined,
|
||||
permissionMode: args.permissionMode,
|
||||
resumeSessionId: args.resumeSessionId,
|
||||
effort: args.effort || undefined,
|
||||
});
|
||||
} catch (laneErr: unknown) {
|
||||
const msg = laneErr instanceof Error ? laneErr.message : String(laneErr);
|
||||
if (msg.includes("409") || msg.includes("ERUNLIVE")) {
|
||||
const fresh = await api.lanes.list().catch(() => null);
|
||||
const updatedLane = fresh?.lanes.find((l) => l.id === targetLaneId);
|
||||
if (updatedLane?.run_id) {
|
||||
await attachToRun(updatedLane.run_id);
|
||||
return;
|
||||
}
|
||||
}
|
||||
throw laneErr;
|
||||
}
|
||||
|
||||
if (!laneStartResult.lane?.run_id) {
|
||||
throw new Error(t("errors.noRunIdReturned"));
|
||||
}
|
||||
|
||||
try {
|
||||
const fetched = await api.run.get(laneStartResult.lane.run_id);
|
||||
setHandle(fetched);
|
||||
refreshList();
|
||||
} catch {
|
||||
try {
|
||||
await attachToRun(laneStartResult.lane.run_id);
|
||||
refreshList();
|
||||
} catch (fallbackErr: unknown) {
|
||||
const attachMsg = fallbackErr instanceof Error ? fallbackErr.message : "unknown";
|
||||
throw new Error(t("errors.runStartedButNotAttached", { message: attachMsg }));
|
||||
}
|
||||
}
|
||||
} catch (err: unknown) {
|
||||
const m = err instanceof Error ? err.message : "unknown";
|
||||
setError(t("errors.startFailed", { message: m }));
|
||||
} finally {
|
||||
setBusy(null);
|
||||
}
|
||||
},
|
||||
[busy, t, lanes, laneId, onLaneIdChange, onLaneCreated, attachToRun, refreshList]
|
||||
);
|
||||
|
||||
const onResumeFromHistory = useCallback(
|
||||
async (item: DashboardRunHistoryItem) => {
|
||||
if (!item.session_id) return;
|
||||
if (busy) return;
|
||||
setBusy("start");
|
||||
setError(null);
|
||||
try {
|
||||
let fetched: RunHandle;
|
||||
|
||||
if (item.cwd) {
|
||||
const effectiveCwd = item.cwd;
|
||||
let targetLaneId = lanes.find((l) => l.cwd === effectiveCwd)?.id;
|
||||
|
||||
if (!targetLaneId) {
|
||||
const ensureResult = await api.lanes.ensure({ cwd: effectiveCwd });
|
||||
targetLaneId = ensureResult.lane.id;
|
||||
onLaneCreated(ensureResult.lane);
|
||||
}
|
||||
|
||||
const laneStartResult = await api.lanes.action(targetLaneId, "start", {
|
||||
prompt: "",
|
||||
model: item.model || undefined,
|
||||
permissionMode: item.permission_mode || undefined,
|
||||
effort: item.effort || undefined,
|
||||
resumeSessionId: item.session_id,
|
||||
});
|
||||
|
||||
if (!laneStartResult.lane?.run_id) {
|
||||
throw new Error("No run_id returned from lane start");
|
||||
}
|
||||
|
||||
fetched = await api.run.get(laneStartResult.lane.run_id);
|
||||
onLaneIdChange(targetLaneId);
|
||||
} else {
|
||||
fetched = await api.run.start({
|
||||
laneId: 0,
|
||||
initialPrompt: "",
|
||||
cwd: undefined,
|
||||
model: item.model || undefined,
|
||||
permissionMode: item.permission_mode || undefined,
|
||||
effort: item.effort || undefined,
|
||||
resumeSessionId: item.session_id,
|
||||
});
|
||||
}
|
||||
|
||||
setHandle(fetched);
|
||||
setResumeSession(null);
|
||||
refreshList();
|
||||
} catch (err) {
|
||||
const msg = err instanceof Error ? err.message : "unknown";
|
||||
setError(t("errors.startFailed", { message: msg }));
|
||||
} finally {
|
||||
setBusy(null);
|
||||
}
|
||||
},
|
||||
[busy, refreshList, t, lanes, onLaneCreated, onLaneIdChange]
|
||||
);
|
||||
|
||||
const onViewFromHistory = useCallback(
|
||||
(item: DashboardRunHistoryItem) => {
|
||||
if (item.session_id) void onResumeFromHistory(item);
|
||||
},
|
||||
[onResumeFromHistory]
|
||||
);
|
||||
|
||||
const newRun = useCallback(() => {
|
||||
setHandle(null);
|
||||
setPrompt("");
|
||||
setResumeSession(null);
|
||||
setError(null);
|
||||
}, []);
|
||||
|
||||
if (laneId === null && showLaneSelector) {
|
||||
return (
|
||||
<div data-testid="pane-empty" className="flex min-h-0 flex-1 flex-col gap-2 p-4">
|
||||
<select
|
||||
data-testid="pane-lane-select"
|
||||
aria-label={tLanes("splitView.paneLaneLabel")}
|
||||
className="rounded border border-border bg-surface-1 px-2 py-1 text-xs text-fg-secondary"
|
||||
value=""
|
||||
onChange={(e) => e.target.value && onLaneIdChange(Number(e.target.value))}
|
||||
>
|
||||
<option value="">{tLanes("splitView.pickLane")}</option>
|
||||
{lanes.map((l) => (
|
||||
<option key={l.id} value={l.id}>
|
||||
{l.title || l.cwd}
|
||||
</option>
|
||||
))}
|
||||
</select>
|
||||
<p className="text-xs text-fg-muted">{tLanes("splitView.emptyPane")}</p>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<div data-testid="console-body" className="flex min-h-0 flex-1 flex-col gap-5">
|
||||
{showLaneSelector && (
|
||||
<select
|
||||
data-testid="pane-lane-select"
|
||||
aria-label={tLanes("splitView.paneLaneLabel")}
|
||||
className="rounded border border-border bg-surface-1 px-2 py-1 text-xs text-fg-secondary"
|
||||
value={laneId ?? ""}
|
||||
onChange={(e) => e.target.value && onLaneIdChange(Number(e.target.value))}
|
||||
>
|
||||
<option value="">{tLanes("splitView.pickLane")}</option>
|
||||
{lanes.map((l) => (
|
||||
<option key={l.id} value={l.id}>
|
||||
{l.title || l.cwd}
|
||||
</option>
|
||||
))}
|
||||
</select>
|
||||
)}
|
||||
|
||||
<header className="flex items-start gap-3">
|
||||
<div className="w-9 h-9 rounded-xl bg-accent/15 flex items-center justify-center flex-shrink-0">
|
||||
<Play className="w-4.5 h-4.5 text-accent" />
|
||||
</div>
|
||||
<div className="min-w-0 flex-1">
|
||||
<div className="flex items-center gap-2">
|
||||
<h1 className="text-lg font-semibold text-fg-primary">{t("title")}</h1>
|
||||
{wsConnected ? (
|
||||
<span className="flex items-center gap-1.5 text-[11px] text-status-success bg-status-success/10 border border-status-success/20 px-2 py-0.5 rounded-full">
|
||||
<span className="w-1.5 h-1.5 rounded-full bg-status-success animate-pulse-dot" />
|
||||
{tCommon("live")}
|
||||
</span>
|
||||
) : (
|
||||
<span className="flex items-center gap-1.5 text-[11px] text-fg-secondary bg-surface-4/10 border border-border-light/20 px-2 py-0.5 rounded-full">
|
||||
<span className="w-1.5 h-1.5 rounded-full bg-surface-4" />
|
||||
{tCommon("offline")}
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
<p className="text-xs text-fg-muted max-w-3xl">{t("subtitle")}</p>
|
||||
</div>
|
||||
<ActiveRunsSwitcher
|
||||
activeRuns={activeRuns}
|
||||
currentHandleId={handle?.id || null}
|
||||
onAttach={attachToRun}
|
||||
runHistory={runHistory}
|
||||
onResumeFromHistory={onResumeFromHistory}
|
||||
onViewFromHistory={onViewFromHistory}
|
||||
onRefresh={refreshList}
|
||||
/>
|
||||
</header>
|
||||
|
||||
{binaryStatus && !binaryStatus.found && (
|
||||
<div className="rounded-lg border border-status-danger/40 bg-status-danger/10 px-4 py-3 text-sm text-status-danger flex items-center gap-2">
|
||||
<AlertCircle className="w-4 h-4 flex-shrink-0" />
|
||||
<span>{t("binary.missing")}</span>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{error && (
|
||||
<div className="rounded-lg border border-status-danger/40 bg-status-danger/10 px-4 py-3 text-sm text-status-danger flex items-center gap-2">
|
||||
<AlertCircle className="w-4 h-4 flex-shrink-0" />
|
||||
<span className="flex-1 break-all">{error}</span>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{!handle ? (
|
||||
<RunSetup
|
||||
laneId={laneId ?? 0}
|
||||
prompt={prompt}
|
||||
onPromptChange={setPrompt}
|
||||
cwd={cwd}
|
||||
onCwdChange={setCwd}
|
||||
cwdSuggestions={cwdSuggestions}
|
||||
model={model}
|
||||
onModelChange={setModel}
|
||||
permissionMode={permissionMode}
|
||||
onPermissionModeChange={setPermissionMode}
|
||||
effort={effort}
|
||||
onEffortChange={setEffort}
|
||||
binaryFound={binaryStatus?.found ?? true}
|
||||
busy={busy === "start"}
|
||||
onStart={onStartFromSetup}
|
||||
activeRuns={activeRuns}
|
||||
laneCwd={currentLane?.cwd}
|
||||
resumeSession={resumeSession}
|
||||
onResumeSessionChange={setResumeSession}
|
||||
runHistory={runHistory}
|
||||
onResumeFromHistory={onResumeFromHistory}
|
||||
/>
|
||||
) : (
|
||||
<div className="flex-1 min-h-0 flex flex-col">
|
||||
<TerminalView
|
||||
runId={handle!.id}
|
||||
wsBaseUrl={window.location.origin.replace(/^http/, "ws")}
|
||||
/>
|
||||
<button
|
||||
onClick={newRun}
|
||||
className="mt-3 px-3 py-1.5 text-sm rounded border border-border hover:border-border-light text-fg-secondary hover:text-fg-primary transition-colors"
|
||||
>
|
||||
{t("actions.newRun")}
|
||||
</button>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -33,8 +33,27 @@ import {
|
||||
RotateCcw,
|
||||
Eye,
|
||||
} from "lucide-react";
|
||||
import type { DashboardRunHistoryItem, RunListResponse, RunMode, RunStatus } from "../../lib/api";
|
||||
import { ModeBadge, StatusPill } from "./RunConsole";
|
||||
import type { DashboardRunHistoryItem, RunListResponse, RunStatus } from "../../lib/api";
|
||||
|
||||
// Minimal StatusPill component (from deleted RunConsole)
|
||||
function StatusPill({
|
||||
status,
|
||||
}: {
|
||||
status: RunStatus | "completed" | "error" | "killed" | "abandoned";
|
||||
}) {
|
||||
const colors: Record<string, string> = {
|
||||
running: "bg-status-success/10 text-status-success border-status-success/30",
|
||||
gone: "bg-surface-3 text-fg-secondary border-border",
|
||||
completed: "bg-sky-500/10 text-sky-300 border-sky-500/30",
|
||||
error: "bg-status-danger/10 text-status-danger border-status-danger/30",
|
||||
killed: "bg-surface-3 text-fg-secondary border-border",
|
||||
abandoned: "bg-surface-3 text-fg-secondary border-border",
|
||||
};
|
||||
const color = colors[status] || colors.abandoned;
|
||||
return (
|
||||
<span className={`text-[10px] font-mono px-1.5 py-0.5 rounded border ${color}`}>{status}</span>
|
||||
);
|
||||
}
|
||||
|
||||
type RunStatusFilter =
|
||||
| "all"
|
||||
@@ -44,15 +63,13 @@ type RunStatusFilter =
|
||||
| "error"
|
||||
| "killed"
|
||||
| "abandoned";
|
||||
type RunModeFilter = "all" | "conversation" | "headless";
|
||||
|
||||
export interface UnifiedRunRow {
|
||||
id: string;
|
||||
sessionId: string | null;
|
||||
mode: RunMode;
|
||||
cwd: string;
|
||||
model: string | null;
|
||||
status: RunStatus;
|
||||
status: RunStatus | "completed" | "error" | "killed" | "abandoned";
|
||||
promptPreview: string;
|
||||
startedAt: number;
|
||||
endedAt: number | null;
|
||||
@@ -105,14 +122,13 @@ export function ActiveRunsSwitcher({
|
||||
out.push({
|
||||
id: r.id,
|
||||
sessionId: r.sessionId,
|
||||
mode: r.mode,
|
||||
cwd: r.cwd,
|
||||
cwd: r.cwd || "",
|
||||
model: r.model,
|
||||
status: r.status,
|
||||
promptPreview: r.prompt || "",
|
||||
startedAt: r.startedAt,
|
||||
endedAt: r.endedAt,
|
||||
isLive: r.status === "running" || r.status === "spawning",
|
||||
promptPreview: r.promptPreview || "",
|
||||
startedAt: r.startedAt ? new Date(r.startedAt).getTime() : 0,
|
||||
endedAt: null,
|
||||
isLive: r.status === "running",
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -124,7 +140,6 @@ export function ActiveRunsSwitcher({
|
||||
out.push({
|
||||
id: h.id,
|
||||
sessionId: h.session_id,
|
||||
mode: h.mode,
|
||||
cwd: h.cwd,
|
||||
model: h.model,
|
||||
status: h.status,
|
||||
@@ -138,7 +153,7 @@ export function ActiveRunsSwitcher({
|
||||
return out;
|
||||
}, [activeRuns, runHistory]);
|
||||
|
||||
const liveCount = activeRuns?.activeCount ?? 0;
|
||||
const liveCount = rows.filter((r) => r.isLive).length;
|
||||
const totalCount = rows.length;
|
||||
|
||||
return (
|
||||
@@ -211,7 +226,6 @@ export function RunsModal({
|
||||
}) {
|
||||
const { t } = useTranslation("run");
|
||||
const [statusFilter, setStatusFilter] = useState<RunStatusFilter>("all");
|
||||
const [modeFilter, setModeFilter] = useState<RunModeFilter>("all");
|
||||
const [search, setSearch] = useState("");
|
||||
|
||||
// Snappy refresh while the modal is the foreground UI: pull immediately
|
||||
@@ -227,25 +241,22 @@ export function RunsModal({
|
||||
|
||||
const counts = useMemo(() => {
|
||||
const byStatus: Record<string, number> = { all: rows.length };
|
||||
const byMode: Record<string, number> = { all: rows.length };
|
||||
for (const r of rows) {
|
||||
byStatus[r.status] = (byStatus[r.status] || 0) + 1;
|
||||
byMode[r.mode] = (byMode[r.mode] || 0) + 1;
|
||||
}
|
||||
return { byStatus, byMode };
|
||||
return { byStatus };
|
||||
}, [rows]);
|
||||
|
||||
const filtered = useMemo(() => {
|
||||
const q = search.trim().toLowerCase();
|
||||
return rows.filter((r) => {
|
||||
if (statusFilter !== "all" && r.status !== statusFilter) return false;
|
||||
if (modeFilter !== "all" && r.mode !== modeFilter) return false;
|
||||
if (!q) return true;
|
||||
const hay =
|
||||
r.promptPreview + "\n" + r.cwd + "\n" + (r.sessionId || "") + "\n" + (r.model || "");
|
||||
return hay.toLowerCase().includes(q);
|
||||
});
|
||||
}, [rows, statusFilter, modeFilter, search]);
|
||||
}, [rows, statusFilter, search]);
|
||||
|
||||
const historyById = useMemo(() => {
|
||||
const m = new Map<string, DashboardRunHistoryItem>();
|
||||
@@ -261,7 +272,6 @@ export function RunsModal({
|
||||
"killed",
|
||||
"abandoned",
|
||||
];
|
||||
const MODES: RunModeFilter[] = ["all", "conversation", "headless"];
|
||||
|
||||
return (
|
||||
<div
|
||||
@@ -343,16 +353,6 @@ export function RunsModal({
|
||||
}))}
|
||||
onChange={(v) => setStatusFilter(v as RunStatusFilter)}
|
||||
/>
|
||||
<FilterChipGroup
|
||||
label={t("runs.filterMode", "Mode")}
|
||||
value={modeFilter}
|
||||
options={MODES.map((m) => ({
|
||||
value: m,
|
||||
label: m === "all" ? t("runs.allLabel", "All") : t(`mode.${m}`),
|
||||
count: counts.byMode[m] || 0,
|
||||
}))}
|
||||
onChange={(v) => setModeFilter(v as RunModeFilter)}
|
||||
/>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@@ -467,10 +467,9 @@ function UnifiedRunRowView({
|
||||
hour: "2-digit",
|
||||
minute: "2-digit",
|
||||
});
|
||||
const canResume = row.mode === "conversation" && !!row.sessionId && !row.isLive;
|
||||
// Headless runs are single-shot, so resume doesn't apply - but the captured
|
||||
// transcript is still worth viewing. Link to the Session detail page.
|
||||
const canView = row.mode === "headless" && !!row.sessionId && !row.isLive;
|
||||
// Without mode distinction, offer resume for any finished run with a session
|
||||
const canResume = !!row.sessionId && !row.isLive;
|
||||
const canView = !!row.sessionId && !row.isLive;
|
||||
return (
|
||||
<div
|
||||
className={`px-5 py-3 transition-colors ${
|
||||
@@ -479,7 +478,6 @@ function UnifiedRunRowView({
|
||||
>
|
||||
<div className="flex items-center gap-2 mb-1.5 flex-wrap">
|
||||
<StatusPill status={row.status} />
|
||||
<ModeBadge mode={row.mode} />
|
||||
{row.isLive && (
|
||||
<span className="text-[10px] font-semibold text-status-success bg-status-success/10 border border-status-success/25 px-1.5 py-0.5 rounded-full inline-flex items-center gap-1">
|
||||
<span className="w-1.5 h-1.5 rounded-full bg-status-success animate-pulse" />
|
||||
|
||||
@@ -5,14 +5,13 @@
|
||||
* the Run page and the Workspace page can both mount the same panel.
|
||||
*
|
||||
* What lives here:
|
||||
* - `RunSetup` — mode (conversation / headless), fresh-vs-resume source, the
|
||||
* prompt editor, and the cwd / model / permission-mode / effort fields,
|
||||
* plus the concurrency hint and the Start button. Its disabled state is
|
||||
* driven by the `binaryFound` prop, so a missing `claude` binary is a
|
||||
* surfaced state here rather than a probe of its own.
|
||||
* above the panel, with its own localStorage-persisted minimized state.
|
||||
* - `RunSetup` — fresh-vs-resume source, the prompt editor, and the cwd /
|
||||
* model / permission-mode / effort fields, plus the concurrency hint and
|
||||
* the Start button. Its disabled state is driven by the `binaryFound` prop,
|
||||
* so a missing `claude` binary is a surfaced state here rather than a probe
|
||||
* of its own.
|
||||
* - the pickers the panel owns: `CwdAutocomplete`, `SessionPicker`,
|
||||
* `ModelPicker`, and the small `ModeOption` / `Field` layout helpers.
|
||||
* `ModelPicker`, and the small `Field` layout helper.
|
||||
*
|
||||
* Props only for `RunSetup`: no `/stage` call, no lane API call, and no run
|
||||
* lifecycle — the page owns `api.run.start` and hands the result back through
|
||||
@@ -45,18 +44,53 @@ import type {
|
||||
RunListResponse,
|
||||
EffortLevel,
|
||||
PermissionMode,
|
||||
RunMode,
|
||||
RunStartArgs,
|
||||
} from "../../lib/api";
|
||||
import type { Session } from "../../lib/types";
|
||||
import { Select } from "../Select";
|
||||
import { PromptEditor } from "./RunConsole";
|
||||
import type { SlashCommand } from "./RunConsole";
|
||||
|
||||
// Minimal SlashCommand type (from deleted RunConsole)
|
||||
export interface SlashCommand {
|
||||
name: string;
|
||||
source: "project" | "user" | "plugin" | "builtin";
|
||||
description?: string;
|
||||
}
|
||||
|
||||
// Minimal PromptEditor component (from deleted RunConsole)
|
||||
interface PromptEditorProps {
|
||||
value: string;
|
||||
onChange: (s: string) => void;
|
||||
onSubmit: () => void;
|
||||
placeholder: string;
|
||||
rows?: number;
|
||||
slashCommands: SlashCommand[];
|
||||
fileCwd: string;
|
||||
}
|
||||
|
||||
function PromptEditor({ value, onChange, onSubmit, placeholder, rows = 5 }: PromptEditorProps) {
|
||||
const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
|
||||
if ((e.ctrlKey || e.metaKey) && e.key === "Enter") {
|
||||
e.preventDefault();
|
||||
onSubmit();
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<textarea
|
||||
value={value}
|
||||
onChange={(e) => onChange(e.target.value)}
|
||||
onKeyDown={handleKeyDown}
|
||||
placeholder={placeholder}
|
||||
rows={rows}
|
||||
className="w-full bg-surface-2 border border-border rounded-md px-3 py-2 text-[11px] font-mono text-fg-primary placeholder:text-fg-muted focus:outline-none focus:border-accent/50 resize-none"
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
// ── Limitations banner (above the config card) ────────────────────────
|
||||
|
||||
interface RunSetupProps {
|
||||
mode: RunMode;
|
||||
onModeChange: (m: RunMode) => void;
|
||||
laneId: number;
|
||||
prompt: string;
|
||||
onPromptChange: (s: string) => void;
|
||||
cwd: string;
|
||||
@@ -70,7 +104,7 @@ interface RunSetupProps {
|
||||
onEffortChange: (e: EffortLevel) => void;
|
||||
binaryFound: boolean;
|
||||
busy: boolean;
|
||||
onStart: () => void;
|
||||
onStart: (args: RunStartArgs) => void;
|
||||
activeRuns: RunListResponse | null;
|
||||
resumeSession: Session | null;
|
||||
onResumeSessionChange: (s: Session | null) => void;
|
||||
@@ -78,54 +112,27 @@ interface RunSetupProps {
|
||||
* sessions. Undefined when no lane is selected (the picker then lists
|
||||
* everything, same as before lanes existed). */
|
||||
laneCwd?: string;
|
||||
slashCommands: SlashCommand[];
|
||||
slashCommands?: SlashCommand[];
|
||||
runHistory: DashboardRunHistoryItem[];
|
||||
onResumeFromHistory: (item: DashboardRunHistoryItem) => void;
|
||||
}
|
||||
|
||||
export function RunSetup(props: RunSetupProps) {
|
||||
const { t } = useTranslation("run");
|
||||
const atCap =
|
||||
props.activeRuns != null && props.activeRuns.activeCount >= props.activeRuns.maxConcurrent;
|
||||
const atCap = false; // TODO: re-add when concurrency info is available
|
||||
const isResume = !!props.resumeSession;
|
||||
const [resumePicked, setResumePicked] = useState(isResume);
|
||||
// Keep "resume picked" in sync with the parent. Two cases:
|
||||
// 1. Parent set a resume session (e.g. user clicked Resume in the runs
|
||||
// modal) - flip the radio so the picker is shown and the selection
|
||||
// is visible.
|
||||
// 2. Parent cleared the session and mode flipped to headless - clear
|
||||
// the radio so the form is honest.
|
||||
// Keep "resume picked" in sync with the parent. Parent set a resume session
|
||||
// (e.g. user clicked Resume in the runs modal) - flip the radio so the picker
|
||||
// is shown and the selection is visible.
|
||||
useEffect(() => {
|
||||
if (isResume && !resumePicked) setResumePicked(true);
|
||||
else if (!isResume && resumePicked && props.mode === "headless") setResumePicked(false);
|
||||
}, [isResume, resumePicked, props.mode]);
|
||||
}, [isResume, resumePicked]);
|
||||
|
||||
return (
|
||||
<div className="rounded-xl border border-border bg-surface-1">
|
||||
{/* Mode and source on one line. Both are two-way choices made once at
|
||||
spawn time, so a segmented row carries them; the longer explanations
|
||||
live in each button's title rather than in a paragraph. */}
|
||||
{/* Fresh vs resume source picker */}
|
||||
<div className="flex flex-wrap items-center gap-x-3 gap-y-1.5 border-b border-border px-3 py-2 text-[11.5px]">
|
||||
<div className="flex items-center rounded-md border border-border bg-surface-2 p-0.5">
|
||||
<Seg
|
||||
active={props.mode === "conversation"}
|
||||
label={t("mode.conversation")}
|
||||
title={t("mode.conversationHint")}
|
||||
onClick={() => props.onModeChange("conversation")}
|
||||
/>
|
||||
<Seg
|
||||
active={props.mode === "headless"}
|
||||
label={t("mode.headless")}
|
||||
title={`${t("mode.headlessHint")} — ${t("hint.headlessExplain")}`}
|
||||
onClick={() => {
|
||||
props.onModeChange("headless");
|
||||
setResumePicked(false);
|
||||
}}
|
||||
/>
|
||||
</div>
|
||||
|
||||
{props.mode === "conversation" && (
|
||||
<>
|
||||
<div className="flex items-center rounded-md border border-border bg-surface-2 p-0.5">
|
||||
<Seg
|
||||
active={!resumePicked}
|
||||
@@ -152,8 +159,6 @@ export function RunSetup(props: RunSetupProps) {
|
||||
/>
|
||||
</div>
|
||||
)}
|
||||
</>
|
||||
)}
|
||||
</div>
|
||||
|
||||
{/* Prompt */}
|
||||
@@ -164,10 +169,10 @@ export function RunSetup(props: RunSetupProps) {
|
||||
<PromptEditor
|
||||
value={props.prompt}
|
||||
onChange={props.onPromptChange}
|
||||
onSubmit={props.onStart}
|
||||
placeholder={t("fields.promptPlaceholder")}
|
||||
onSubmit={() => handleStart(props)}
|
||||
placeholder={t("fields.promptPlaceholderTerminal")}
|
||||
rows={5}
|
||||
slashCommands={props.slashCommands}
|
||||
slashCommands={props.slashCommands ?? []}
|
||||
fileCwd={props.resumeSession?.cwd || props.cwd}
|
||||
/>
|
||||
<div className="mt-1 text-[10px] text-fg-muted">
|
||||
@@ -234,17 +239,12 @@ export function RunSetup(props: RunSetupProps) {
|
||||
{atCap ? (
|
||||
<span className="inline-flex items-center gap-1.5 text-status-warning">
|
||||
<AlertCircle className="w-3.5 h-3.5" />
|
||||
{t("concurrency.atCap", { max: props.activeRuns?.maxConcurrent ?? 0 })}
|
||||
</span>
|
||||
) : props.activeRuns && props.activeRuns.activeCount > 0 ? (
|
||||
<span className="inline-flex items-center gap-1.5 text-fg-secondary">
|
||||
<span className="w-1.5 h-1.5 rounded-full bg-status-success animate-pulse" />
|
||||
{t("concurrency.active", { count: props.activeRuns.activeCount })}
|
||||
{t("concurrency.atCap", { max: 0 })}
|
||||
</span>
|
||||
) : null}
|
||||
</div>
|
||||
<button
|
||||
onClick={props.onStart}
|
||||
onClick={() => handleStart(props)}
|
||||
disabled={
|
||||
!props.binaryFound ||
|
||||
!props.prompt.trim() ||
|
||||
@@ -270,6 +270,18 @@ export function RunSetup(props: RunSetupProps) {
|
||||
);
|
||||
}
|
||||
|
||||
function handleStart(props: RunSetupProps) {
|
||||
props.onStart({
|
||||
laneId: props.laneId,
|
||||
cwd: props.cwd || undefined,
|
||||
model: props.model || undefined,
|
||||
permissionMode: props.permissionMode || undefined,
|
||||
effort: props.effort || undefined,
|
||||
resumeSessionId: props.resumeSession?.id || undefined,
|
||||
initialPrompt: props.prompt || undefined,
|
||||
});
|
||||
}
|
||||
|
||||
/** One segment of a two-way inline choice. The explanation rides on `title`
|
||||
* instead of a hint line, which is what keeps the row to one line. */
|
||||
function Seg({
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
/**
|
||||
* @file TerminalView.tsx
|
||||
* @description Renders one lane's live terminal — a real `xterm.js` instance
|
||||
* attached via WebSocket to the server's `/ws-pty/:runId` path (see
|
||||
* server/lib/pty-attach.js), which is itself a `node-pty`-backed
|
||||
* `tmux attach-session`. Binary WS frames are raw PTY bytes in both
|
||||
* directions; a JSON text frame carries the initial `resize` on mount and
|
||||
* the server's one-shot `exit` notice when the pane process ends.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
import { useEffect, useRef } from "react";
|
||||
import { Terminal } from "@xterm/xterm";
|
||||
import { FitAddon } from "@xterm/addon-fit";
|
||||
import "@xterm/xterm/css/xterm.css";
|
||||
|
||||
interface TerminalViewProps {
|
||||
runId: string;
|
||||
wsBaseUrl: string;
|
||||
}
|
||||
|
||||
export function TerminalView({ runId, wsBaseUrl }: TerminalViewProps) {
|
||||
const containerRef = useRef<HTMLDivElement>(null);
|
||||
|
||||
useEffect(() => {
|
||||
const term = new Terminal({ convertEol: true, fontSize: 13, cursorBlink: true });
|
||||
const fit = new FitAddon();
|
||||
term.loadAddon(fit);
|
||||
if (containerRef.current) term.open(containerRef.current);
|
||||
fit.fit();
|
||||
|
||||
const ws = new WebSocket(`${wsBaseUrl}/ws-pty/${encodeURIComponent(runId)}`);
|
||||
// Server sends PTY bytes as binary frames — default binaryType ("blob")
|
||||
// would hand onmessage a Blob that the string checks below never match,
|
||||
// silently dropping all terminal output. "arraybuffer" keeps it sync.
|
||||
ws.binaryType = "arraybuffer";
|
||||
|
||||
const decoder = new TextDecoder();
|
||||
ws.onopen = () => {
|
||||
ws.send(JSON.stringify({ type: "resize", cols: term.cols, rows: term.rows }));
|
||||
};
|
||||
ws.onmessage = (event) => {
|
||||
const isArrayBuffer = Object.prototype.toString.call(event.data) === "[object ArrayBuffer]";
|
||||
const data = isArrayBuffer ? decoder.decode(event.data as ArrayBuffer) : event.data;
|
||||
if (typeof data === "string") {
|
||||
// A JSON control frame is the only thing that starts with `{"type"`.
|
||||
if (data.startsWith('{"type"')) {
|
||||
try {
|
||||
const msg = JSON.parse(data);
|
||||
if (msg.type === "exit") {
|
||||
term.write(`\r\n[session ended, exit code ${msg.code}]\r\n`);
|
||||
}
|
||||
return;
|
||||
} catch {
|
||||
/* not JSON — fall through and render as PTY output */
|
||||
}
|
||||
}
|
||||
term.write(data);
|
||||
}
|
||||
};
|
||||
|
||||
const dataDisposable = term.onData((data) => {
|
||||
if (ws.readyState === WebSocket.OPEN) ws.send(data);
|
||||
});
|
||||
|
||||
const resizeObserver = new ResizeObserver(() => {
|
||||
fit.fit();
|
||||
if (ws.readyState === WebSocket.OPEN) {
|
||||
ws.send(JSON.stringify({ type: "resize", cols: term.cols, rows: term.rows }));
|
||||
}
|
||||
});
|
||||
if (containerRef.current) resizeObserver.observe(containerRef.current);
|
||||
|
||||
return () => {
|
||||
resizeObserver.disconnect();
|
||||
dataDisposable.dispose();
|
||||
ws.close();
|
||||
term.dispose();
|
||||
};
|
||||
}, [runId, wsBaseUrl]);
|
||||
|
||||
return <div ref={containerRef} className="h-full w-full" data-testid="terminal-view" />;
|
||||
}
|
||||
@@ -0,0 +1,147 @@
|
||||
/**
|
||||
* @file LaneConsolePane.test.tsx
|
||||
* @description Test suite for the LaneConsolePane component
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import { render, screen, fireEvent, waitFor } from "@testing-library/react";
|
||||
import { LaneConsolePane } from "../LaneConsolePane";
|
||||
import { api } from "../../../lib/api";
|
||||
import type { Lane } from "../../../lib/types";
|
||||
|
||||
vi.mock("../TerminalView", () => ({
|
||||
TerminalView: ({ runId }: { runId: string }) => (
|
||||
<div data-testid="terminal-view" data-run-id={runId} />
|
||||
),
|
||||
}));
|
||||
|
||||
vi.mock("../../../lib/api", () => ({
|
||||
api: {
|
||||
lanes: {
|
||||
ensure: vi.fn(),
|
||||
action: vi.fn(),
|
||||
list: vi.fn(),
|
||||
},
|
||||
run: {
|
||||
list: vi.fn().mockResolvedValue({ items: [] }),
|
||||
history: vi.fn().mockResolvedValue({ items: [] }),
|
||||
get: vi.fn(),
|
||||
start: vi.fn(),
|
||||
},
|
||||
},
|
||||
RUN_MODEL_CHOICES: [],
|
||||
RUN_EFFORT_CHOICES: [],
|
||||
}));
|
||||
|
||||
const LANE: Lane = {
|
||||
id: 1,
|
||||
title: "demo",
|
||||
cwd: "/workspace/a",
|
||||
branch: null,
|
||||
kind: "adopted",
|
||||
source_repo: null,
|
||||
pipeline: "default",
|
||||
session_id: null,
|
||||
run_id: null,
|
||||
stage: "idle",
|
||||
stage_since: null,
|
||||
status: "idle",
|
||||
gate_decision: null,
|
||||
ci_status: null,
|
||||
needs_action: null,
|
||||
links: {},
|
||||
stages: {},
|
||||
notes: null,
|
||||
pipeline_name: "Default",
|
||||
pipeline_nodes: [],
|
||||
progress: 0,
|
||||
stage_seconds: null,
|
||||
last_event_seconds: null,
|
||||
liveness: "idle" as Lane["liveness"],
|
||||
detected_stage: null,
|
||||
detected_signal: null,
|
||||
slot: null,
|
||||
ports: {},
|
||||
active_feature_id: null,
|
||||
};
|
||||
|
||||
function baseProps() {
|
||||
return {
|
||||
lanes: [LANE],
|
||||
laneId: 1,
|
||||
showLaneSelector: false,
|
||||
onLaneIdChange: vi.fn(),
|
||||
onLaneCreated: vi.fn(),
|
||||
binaryStatus: { found: true, path: "/usr/local/bin/claude" },
|
||||
cwdSuggestions: [],
|
||||
activeRuns: { items: [] },
|
||||
wsConnected: true,
|
||||
};
|
||||
}
|
||||
|
||||
describe("LaneConsolePane", () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it("starts a run through /api/lanes/<id>/start, not /api/run/start", async () => {
|
||||
(api.lanes.action as ReturnType<typeof vi.fn>).mockResolvedValue({
|
||||
lane: { ...LANE, run_id: "run-1" },
|
||||
});
|
||||
(api.run.get as ReturnType<typeof vi.fn>).mockResolvedValue({
|
||||
id: "run-1",
|
||||
laneId: 1,
|
||||
status: "running",
|
||||
cwd: "/workspace/a",
|
||||
model: null,
|
||||
permissionMode: null,
|
||||
effort: null,
|
||||
resumeSessionId: null,
|
||||
sessionId: null,
|
||||
startedAt: null,
|
||||
promptPreview: null,
|
||||
});
|
||||
|
||||
render(<LaneConsolePane {...baseProps()} />);
|
||||
|
||||
// Set cwd and prompt
|
||||
const cwdInput = screen.getByPlaceholderText(/type to search/i);
|
||||
fireEvent.change(cwdInput, { target: { value: "/workspace/a" } });
|
||||
|
||||
const promptTextarea = screen.getByPlaceholderText(/ask claude/i);
|
||||
fireEvent.change(promptTextarea, { target: { value: "test prompt" } });
|
||||
|
||||
// Find and click the Run button (the main start button in RunSetup)
|
||||
fireEvent.click(screen.getByRole("button", { name: /^run$/i }));
|
||||
|
||||
await waitFor(() =>
|
||||
expect(api.lanes.action).toHaveBeenCalledWith(1, "start", expect.any(Object))
|
||||
);
|
||||
expect(api.run.start).not.toHaveBeenCalled();
|
||||
await waitFor(() =>
|
||||
expect(screen.getByTestId("terminal-view")).toHaveAttribute("data-run-id", "run-1")
|
||||
);
|
||||
});
|
||||
|
||||
it("shows a lane dropdown only when showLaneSelector is true", () => {
|
||||
const { rerender } = render(<LaneConsolePane {...baseProps()} showLaneSelector />);
|
||||
expect(screen.getByTestId("pane-lane-select")).toBeInTheDocument();
|
||||
|
||||
rerender(<LaneConsolePane {...baseProps()} showLaneSelector={false} />);
|
||||
expect(screen.queryByTestId("pane-lane-select")).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it("renders RunSetup when laneId is null and showLaneSelector is false (layout-1, fresh install)", () => {
|
||||
render(<LaneConsolePane {...baseProps()} laneId={null} showLaneSelector={false} />);
|
||||
expect(screen.getByTestId("console-body")).toBeInTheDocument();
|
||||
expect(screen.queryByTestId("pane-empty")).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it("renders an empty placeholder with selector when laneId is null but showLaneSelector is true (split-view)", () => {
|
||||
render(<LaneConsolePane {...baseProps()} laneId={null} showLaneSelector={true} />);
|
||||
expect(screen.getByTestId("pane-empty")).toBeInTheDocument();
|
||||
expect(screen.getByTestId("pane-lane-select")).toBeInTheDocument();
|
||||
expect(screen.queryByTestId("console-body")).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
@@ -1,172 +0,0 @@
|
||||
/**
|
||||
* @file RunConsole.test.tsx
|
||||
* @description Pins the props-only boundary of `RunConsole` after its move out
|
||||
* of `pages/Run.tsx`: the envelope stream renders from the `envelopes` prop
|
||||
* (no stream subscription of its own), the token meter rolls up usage from
|
||||
* those same envelopes, the prompt editor's `/` autocomplete filters and fills
|
||||
* the prompt through `onFollowUpChange`, and `onSend` / `onStop` fire from the
|
||||
* send and stop controls.
|
||||
*
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
|
||||
import { useState } from "react";
|
||||
import { MemoryRouter } from "react-router-dom";
|
||||
import { fireEvent, render, screen } from "@testing-library/react";
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import { RunConsole, type SlashCommand } from "../RunConsole";
|
||||
import type { Envelope } from "../../../hooks/useRunStream";
|
||||
import type { RunHandle } from "../../../lib/api";
|
||||
|
||||
const HANDLE: RunHandle = {
|
||||
id: "run-1",
|
||||
pid: 4242,
|
||||
mode: "conversation",
|
||||
cwd: "/tmp/project",
|
||||
model: "claude-opus-5",
|
||||
permissionMode: "acceptEdits",
|
||||
effort: "",
|
||||
prompt: "hi",
|
||||
argv: [],
|
||||
resumeSessionId: null,
|
||||
status: "running",
|
||||
startedAt: 1,
|
||||
endedAt: null,
|
||||
exitCode: null,
|
||||
signal: null,
|
||||
error: null,
|
||||
sessionId: null,
|
||||
envelopeCount: 0,
|
||||
stdoutTail: "",
|
||||
stderrTail: "",
|
||||
};
|
||||
|
||||
const COMMANDS: SlashCommand[] = [
|
||||
{ name: "code-review", description: "Review the working diff", source: "project" },
|
||||
{ name: "compact", description: "Compact the conversation context", source: "builtin" },
|
||||
{ name: "logout", description: "Sign out", source: "builtin" },
|
||||
];
|
||||
|
||||
/**
|
||||
* Mount the console with the parent-owned follow-up state it expects, so the
|
||||
* autocomplete assertions exercise the real controlled-input round trip.
|
||||
*/
|
||||
function renderConsole(
|
||||
props: Partial<React.ComponentProps<typeof RunConsole>> = {},
|
||||
onFollowUp?: (s: string) => void
|
||||
) {
|
||||
const seen = { followUp: "" };
|
||||
function Harness() {
|
||||
const [followUp, setFollowUp] = useState("");
|
||||
seen.followUp = followUp;
|
||||
return (
|
||||
<RunConsole
|
||||
handle={HANDLE}
|
||||
envelopes={[]}
|
||||
mode="conversation"
|
||||
isLive
|
||||
hasFinished={false}
|
||||
followUp={followUp}
|
||||
onFollowUpChange={(s) => {
|
||||
setFollowUp(s);
|
||||
onFollowUp?.(s);
|
||||
}}
|
||||
busy={null}
|
||||
onSend={() => {}}
|
||||
onStop={() => {}}
|
||||
onNewRun={() => {}}
|
||||
slashCommands={COMMANDS}
|
||||
{...props}
|
||||
/>
|
||||
);
|
||||
}
|
||||
render(
|
||||
<MemoryRouter>
|
||||
<Harness />
|
||||
</MemoryRouter>
|
||||
);
|
||||
return seen;
|
||||
}
|
||||
|
||||
describe("RunConsole", () => {
|
||||
it("renders assistant text from the envelopes prop", () => {
|
||||
const envelopes: Envelope[] = [
|
||||
{ type: "user", message: { content: "explain this repo" } },
|
||||
{ type: "assistant", message: { content: [{ type: "text", text: "Here is the answer." }] } },
|
||||
] as Envelope[];
|
||||
renderConsole({ envelopes });
|
||||
|
||||
expect(screen.getByText("explain this repo")).toBeInTheDocument();
|
||||
expect(screen.getByText("Here is the answer.")).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it("shows the empty-stream placeholder when there are no envelopes", () => {
|
||||
renderConsole({ isLive: false });
|
||||
expect(screen.getByText("Nothing yet")).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it("shows the token totals computed from the envelopes", () => {
|
||||
// Transcript-shaped assistant envelope (no `message.id`), which is the
|
||||
// branch computeTokens folds into the running totals.
|
||||
const envelopes: Envelope[] = [
|
||||
{
|
||||
type: "assistant",
|
||||
message: {
|
||||
content: [{ type: "text", text: "done" }],
|
||||
usage: { input_tokens: 12_000, output_tokens: 2_500, cache_read_input_tokens: 8_000 },
|
||||
},
|
||||
},
|
||||
] as Envelope[];
|
||||
renderConsole({ envelopes });
|
||||
|
||||
// Context gauge: (input + cache read) / default 200k window.
|
||||
// The CLI-style meter is one status line: context usage as a single label,
|
||||
// then output and cache-hit figures with terminal glyphs. Input is implied
|
||||
// by the context total rather than listed separately.
|
||||
expect(screen.getByText("20.0k / 200k (10%)")).toBeInTheDocument();
|
||||
expect(screen.getByText("↑2.5k")).toBeInTheDocument(); // Output
|
||||
expect(screen.getByText("⚡8.0k")).toBeInTheDocument(); // Cache hit
|
||||
});
|
||||
|
||||
it("filters slash commands as the user types and fills the prompt on pick", () => {
|
||||
const seen = renderConsole();
|
||||
const textarea = screen.getByRole("textbox");
|
||||
|
||||
fireEvent.change(textarea, { target: { value: "/co" } });
|
||||
|
||||
expect(screen.getByText("/code-review")).toBeInTheDocument();
|
||||
expect(screen.getByText("/compact")).toBeInTheDocument();
|
||||
expect(screen.queryByText("/logout")).not.toBeInTheDocument();
|
||||
|
||||
fireEvent.click(screen.getByText("/code-review"));
|
||||
|
||||
expect(seen.followUp).toBe("/code-review");
|
||||
expect(screen.queryByText("/compact")).not.toBeInTheDocument(); // dropdown closed
|
||||
});
|
||||
|
||||
it("fires onSend from the send button with the prompt the parent holds", () => {
|
||||
const onSend = vi.fn();
|
||||
const seen = renderConsole({ onSend });
|
||||
|
||||
fireEvent.change(screen.getByRole("textbox"), { target: { value: "follow up please" } });
|
||||
fireEvent.click(screen.getByRole("button", { name: /send/i }));
|
||||
|
||||
expect(onSend).toHaveBeenCalledTimes(1);
|
||||
expect(seen.followUp).toBe("follow up please");
|
||||
});
|
||||
|
||||
it("fires onStop from the stop control while live, and hides it when not", () => {
|
||||
const onStop = vi.fn();
|
||||
renderConsole({ onStop });
|
||||
|
||||
fireEvent.click(screen.getByRole("button", { name: /stop/i }));
|
||||
expect(onStop).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("hides the stop control and the follow-up editor once the run is not live", () => {
|
||||
renderConsole({ isLive: false, hasFinished: true });
|
||||
|
||||
expect(screen.queryByRole("button", { name: /stop/i })).not.toBeInTheDocument();
|
||||
expect(screen.queryByRole("textbox")).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
@@ -29,12 +29,11 @@ const activeRuns = {
|
||||
{
|
||||
id: LIVE_ID,
|
||||
sessionId: "sess-live",
|
||||
mode: "conversation",
|
||||
cwd: "/tmp/live",
|
||||
model: "claude-opus-5",
|
||||
status: "running",
|
||||
prompt: "the live prompt",
|
||||
startedAt: 3000,
|
||||
startedAt: "2000-01-01T00:50:00Z",
|
||||
promptPreview: "the live prompt",
|
||||
endedAt: null,
|
||||
},
|
||||
],
|
||||
@@ -44,7 +43,6 @@ function historyItem(over: Partial<DashboardRunHistoryItem>): DashboardRunHistor
|
||||
return {
|
||||
id: PAST_ID,
|
||||
session_id: "sess-past",
|
||||
mode: "conversation",
|
||||
cwd: "/tmp/past",
|
||||
model: "sonnet",
|
||||
status: "completed",
|
||||
@@ -64,7 +62,6 @@ const PAST = historyItem({});
|
||||
const HEADLESS = historyItem({
|
||||
id: HEADLESS_ID,
|
||||
session_id: "sess-headless",
|
||||
mode: "headless",
|
||||
cwd: "/tmp/headless",
|
||||
prompt_preview: "the headless prompt",
|
||||
started_at: new Date(1000).toISOString(),
|
||||
@@ -95,10 +92,9 @@ function row(id: string, over: Partial<UnifiedRunRow> = {}): UnifiedRunRow {
|
||||
return {
|
||||
id,
|
||||
sessionId: `sess-${id}`,
|
||||
mode: "conversation",
|
||||
cwd: `/tmp/${id}`,
|
||||
model: "sonnet",
|
||||
status: "completed",
|
||||
status: "abandoned",
|
||||
promptPreview: `prompt of ${id}`,
|
||||
startedAt: 1000,
|
||||
endedAt: 2000,
|
||||
@@ -216,39 +212,31 @@ describe("RunsModal", () => {
|
||||
expect(spies.onAttach).toHaveBeenCalledWith(LIVE_ID);
|
||||
});
|
||||
|
||||
it("fires resume with the history item behind a finished conversation row", () => {
|
||||
it("fires resume with the history item behind a finished row", () => {
|
||||
const { spies } = renderModal([row(PAST_ID)]);
|
||||
fireEvent.click(screen.getByText(i18n.t("run:resume.resumeOption")));
|
||||
expect(spies.onResume).toHaveBeenCalledWith(PAST);
|
||||
expect(spies.onView).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("fires view — not resume — for a finished headless row", () => {
|
||||
const { spies } = renderModal([row(HEADLESS_ID, { mode: "headless" })]);
|
||||
expect(screen.queryByText(i18n.t("run:resume.resumeOption"))).toBeNull();
|
||||
it("fires view for a finished row", () => {
|
||||
const { spies } = renderModal([row(HEADLESS_ID)]);
|
||||
fireEvent.click(screen.getByText(i18n.t("run:runs.viewLabel")));
|
||||
expect(spies.onView).toHaveBeenCalledWith(HEADLESS);
|
||||
expect(spies.onResume).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("filters by status, by mode and by free text", () => {
|
||||
it("filters by status and by free text", () => {
|
||||
const rows = [
|
||||
row("a", { status: "running", isLive: true, promptPreview: "alpha" }),
|
||||
row("b", { status: "error", promptPreview: "bravo" }),
|
||||
row("c", { status: "completed", mode: "headless", promptPreview: "charlie" }),
|
||||
row("b", { status: "killed", promptPreview: "bravo" }),
|
||||
row("c", { status: "abandoned", promptPreview: "charlie" }),
|
||||
];
|
||||
renderModal(rows);
|
||||
|
||||
fireEvent.click(chip(i18n.t("run:status.error")));
|
||||
fireEvent.click(chip(i18n.t("run:status.killed")));
|
||||
expect(screen.getByText("bravo")).toBeTruthy();
|
||||
expect(screen.queryByText("alpha")).toBeNull();
|
||||
|
||||
fireEvent.click(allChip(0));
|
||||
fireEvent.click(chip(i18n.t("run:mode.headless")));
|
||||
expect(screen.getByText("charlie")).toBeTruthy();
|
||||
expect(screen.queryByText("bravo")).toBeNull();
|
||||
|
||||
fireEvent.click(allChip(1));
|
||||
fireEvent.change(
|
||||
screen.getByPlaceholderText(
|
||||
i18n.t("run:runs.searchPlaceholder", "Search prompt, cwd, model, or session id…")
|
||||
|
||||
@@ -39,7 +39,6 @@ type Spies = ReturnType<typeof renderSetup>["spies"];
|
||||
|
||||
function renderSetup(overrides: Partial<React.ComponentProps<typeof RunSetup>> = {}) {
|
||||
const spies = {
|
||||
onModeChange: vi.fn(),
|
||||
onPromptChange: vi.fn(),
|
||||
onCwdChange: vi.fn(),
|
||||
onModelChange: vi.fn(),
|
||||
@@ -52,7 +51,7 @@ function renderSetup(overrides: Partial<React.ComponentProps<typeof RunSetup>> =
|
||||
const utils = render(
|
||||
<MemoryRouter>
|
||||
<RunSetup
|
||||
mode="conversation"
|
||||
laneId={1}
|
||||
prompt="do the thing"
|
||||
cwd="/Users/tester"
|
||||
cwdSuggestions={SUGGESTIONS}
|
||||
@@ -95,15 +94,6 @@ beforeEach(() => {
|
||||
});
|
||||
|
||||
describe("RunSetup — selections report through callbacks", () => {
|
||||
it("reports the mode from the one-shot / conversation options", () => {
|
||||
const { spies } = renderSetup();
|
||||
fireEvent.click(screen.getByText(i18n.t("run:mode.headless")));
|
||||
expect(spies.onModeChange).toHaveBeenCalledWith("headless");
|
||||
fireEvent.click(screen.getByText(i18n.t("run:mode.conversation")));
|
||||
expect(spies.onModeChange).toHaveBeenLastCalledWith("conversation");
|
||||
onlyCalled(spies, "onModeChange");
|
||||
});
|
||||
|
||||
it("reports the prompt from the editor", () => {
|
||||
const { spies } = renderSetup({ prompt: "" });
|
||||
const box = screen.getByPlaceholderText(i18n.t("run:fields.promptPlaceholder"));
|
||||
@@ -171,7 +161,7 @@ describe("RunSetup — missing binary and other blocked states", () => {
|
||||
expect(runButton().disabled).toBe(false);
|
||||
});
|
||||
|
||||
it("still disables Run without a prompt, without a cwd, or at the concurrency cap", () => {
|
||||
it("still disables Run without a prompt or without a cwd", () => {
|
||||
const { unmount } = renderSetup({ prompt: " " });
|
||||
expect(runButton().disabled).toBe(true);
|
||||
unmount();
|
||||
@@ -179,12 +169,6 @@ describe("RunSetup — missing binary and other blocked states", () => {
|
||||
const noCwd = renderSetup({ cwd: "" });
|
||||
expect(runButton().disabled).toBe(true);
|
||||
noCwd.unmount();
|
||||
|
||||
renderSetup({
|
||||
activeRuns: { items: [], activeCount: 2, maxConcurrent: 2 } as never,
|
||||
});
|
||||
expect(runButton().disabled).toBe(true);
|
||||
expect(screen.getByText(i18n.t("run:concurrency.atCap", { max: 2 }))).toBeTruthy();
|
||||
});
|
||||
|
||||
it("shows the Starting… label while busy", () => {
|
||||
@@ -237,7 +221,7 @@ describe("RunSetup — resume picker scopes sessions to the selected lane", () =
|
||||
rerender(
|
||||
<MemoryRouter>
|
||||
<RunSetup
|
||||
mode="conversation"
|
||||
laneId={1}
|
||||
prompt="do the thing"
|
||||
cwd="/Users/tester"
|
||||
cwdSuggestions={SUGGESTIONS}
|
||||
@@ -251,7 +235,6 @@ describe("RunSetup — resume picker scopes sessions to the selected lane", () =
|
||||
slashCommands={[]}
|
||||
runHistory={[]}
|
||||
laneCwd="/Users/tester/lane-b"
|
||||
onModeChange={vi.fn()}
|
||||
onPromptChange={vi.fn()}
|
||||
onCwdChange={vi.fn()}
|
||||
onModelChange={vi.fn()}
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
/**
|
||||
* @file TerminalView.test.tsx
|
||||
* @description Tests for the xterm.js-backed terminal view: verifies it opens
|
||||
* a WS connection to the right URL, writes incoming binary frames to the
|
||||
* mocked terminal, and forwards typed input as outgoing binary frames.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
|
||||
import { render, cleanup } from "@testing-library/react";
|
||||
import { TerminalView } from "../TerminalView";
|
||||
|
||||
const writeMock = vi.fn();
|
||||
const onDataHandlers: Array<(d: string) => void> = [];
|
||||
const openMock = vi.fn();
|
||||
const disposeMock = vi.fn();
|
||||
|
||||
vi.mock("@xterm/xterm", () => ({
|
||||
Terminal: vi.fn().mockImplementation(() => ({
|
||||
open: openMock,
|
||||
write: writeMock,
|
||||
onData: (fn: (d: string) => void) => {
|
||||
onDataHandlers.push(fn);
|
||||
return { dispose: vi.fn() };
|
||||
},
|
||||
dispose: disposeMock,
|
||||
loadAddon: vi.fn(),
|
||||
})),
|
||||
}));
|
||||
vi.mock("@xterm/addon-fit", () => ({
|
||||
FitAddon: vi.fn().mockImplementation(() => ({ fit: vi.fn() })),
|
||||
}));
|
||||
|
||||
class MockWebSocket {
|
||||
static instances: MockWebSocket[] = [];
|
||||
url: string;
|
||||
sent: unknown[] = [];
|
||||
onopen: (() => void) | null = null;
|
||||
onmessage: ((e: { data: unknown }) => void) | null = null;
|
||||
onclose: (() => void) | null = null;
|
||||
constructor(url: string) {
|
||||
this.url = url;
|
||||
MockWebSocket.instances.push(this);
|
||||
}
|
||||
send(data: unknown) {
|
||||
this.sent.push(data);
|
||||
}
|
||||
close() {
|
||||
this.onclose?.();
|
||||
}
|
||||
}
|
||||
// @ts-expect-error test override
|
||||
global.WebSocket = MockWebSocket;
|
||||
|
||||
describe("TerminalView", () => {
|
||||
beforeEach(() => {
|
||||
MockWebSocket.instances = [];
|
||||
onDataHandlers.length = 0;
|
||||
writeMock.mockClear();
|
||||
openMock.mockClear();
|
||||
});
|
||||
|
||||
afterEach(cleanup);
|
||||
|
||||
it("opens a WS connection to the run's ws-pty path", () => {
|
||||
render(<TerminalView runId="ccam-lane-1" wsBaseUrl="ws://localhost:4820" />);
|
||||
expect(MockWebSocket.instances).toHaveLength(1);
|
||||
expect(MockWebSocket.instances[0]!.url).toBe("ws://localhost:4820/ws-pty/ccam-lane-1");
|
||||
});
|
||||
|
||||
it("writes incoming WS data to the terminal", () => {
|
||||
render(<TerminalView runId="ccam-lane-1" wsBaseUrl="ws://localhost:4820" />);
|
||||
const ws = MockWebSocket.instances[0]!;
|
||||
ws.onopen?.();
|
||||
ws.onmessage?.({ data: "hello" });
|
||||
expect(writeMock).toHaveBeenCalledWith("hello");
|
||||
});
|
||||
|
||||
it("decodes binary ArrayBuffer frames (server sends PTY output as binary)", () => {
|
||||
render(<TerminalView runId="ccam-lane-1" wsBaseUrl="ws://localhost:4820" />);
|
||||
const ws = MockWebSocket.instances[0]!;
|
||||
ws.onopen?.();
|
||||
const bytes = new TextEncoder().encode("hello-binary").buffer;
|
||||
ws.onmessage?.({ data: bytes });
|
||||
expect(writeMock).toHaveBeenCalledWith("hello-binary");
|
||||
});
|
||||
|
||||
it("forwards terminal keystrokes as outgoing WS sends", () => {
|
||||
render(<TerminalView runId="ccam-lane-1" wsBaseUrl="ws://localhost:4820" />);
|
||||
const ws = MockWebSocket.instances[0]!;
|
||||
onDataHandlers[0]!("ls -la\r");
|
||||
expect(ws.sent).toEqual(["ls -la\r"]);
|
||||
});
|
||||
});
|
||||
@@ -23,11 +23,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/types`
|
||||
*
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `AgentCollaborationNetworkProps` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `AgentCollaborationNetwork` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -25,11 +25,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
*
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
*
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
*
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
* - `../../lib/format`
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
*
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
* - `../../lib/format`
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/api`
|
||||
* - `../../lib/format`
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
*
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
*
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
*
|
||||
|
||||
@@ -29,11 +29,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/api`
|
||||
* - `../../lib/eventBus`
|
||||
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../lib/types`
|
||||
*
|
||||
|
||||
@@ -1,174 +0,0 @@
|
||||
/**
|
||||
* @file useRunStream.test.tsx
|
||||
* @description Covers `useRunStream`, the hook that owns the Run page's live
|
||||
* envelope state: it subscribes to the event bus and folds `run_stream`
|
||||
* envelopes into an array, forwards `run_status` / `run_input_ack` for the
|
||||
* subscribed run id to the caller's callbacks, fires the id-agnostic
|
||||
* `onAnyStatus` for every `run_status`, and disposes its subscription on
|
||||
* unmount. `eventBus` is exercised for real (it is a plain in-memory pub/sub)
|
||||
* with only its `subscribe` spied on, so the disposer assertion pins the real
|
||||
* lifecycle rather than a mock's.
|
||||
*
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
|
||||
import { act, renderHook } from "@testing-library/react";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import { eventBus } from "../../lib/eventBus";
|
||||
import type { WSMessage } from "../../lib/types";
|
||||
import { useRunStream, type Envelope } from "../useRunStream";
|
||||
|
||||
/** `run_stream` frame carrying one envelope for `id`. */
|
||||
function streamMsg(id: string, envelope: unknown): WSMessage {
|
||||
return { type: "run_stream", data: { id, envelope } } as WSMessage;
|
||||
}
|
||||
|
||||
function statusMsg(id: string, status: string): WSMessage {
|
||||
return { type: "run_status", data: { id, status, at: 1 } } as WSMessage;
|
||||
}
|
||||
|
||||
const noopOpts = { onStatus: () => {}, onInputAck: () => {}, onAnyStatus: () => {} };
|
||||
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe("useRunStream", () => {
|
||||
it("merges envelopes for the subscribed run id in arrival order", () => {
|
||||
const { result } = renderHook(() => useRunStream("run-1", noopOpts));
|
||||
|
||||
act(() => {
|
||||
eventBus.publish(streamMsg("run-1", { type: "system", subtype: "init" }));
|
||||
eventBus.publish(streamMsg("run-1", { type: "result", subtype: "success" }));
|
||||
});
|
||||
|
||||
expect(result.current.envelopes.map((e) => (e as { type: string }).type)).toEqual([
|
||||
"system",
|
||||
"result",
|
||||
]);
|
||||
});
|
||||
|
||||
it("ignores an envelope for a different run id", () => {
|
||||
const { result } = renderHook(() => useRunStream("run-1", noopOpts));
|
||||
|
||||
act(() => {
|
||||
eventBus.publish(streamMsg("run-2", { type: "result" }));
|
||||
});
|
||||
|
||||
expect(result.current.envelopes).toEqual([]);
|
||||
});
|
||||
|
||||
it("updates a streaming assistant envelope in place instead of appending", () => {
|
||||
const { result } = renderHook(() => useRunStream("run-1", noopOpts));
|
||||
|
||||
act(() => {
|
||||
// message_start seeds the kept envelope + a streaming placeholder.
|
||||
eventBus.publish(
|
||||
streamMsg("run-1", {
|
||||
type: "stream_event",
|
||||
event: { type: "message_start", message: { id: "m1" } },
|
||||
})
|
||||
);
|
||||
});
|
||||
expect(result.current.envelopes).toHaveLength(2);
|
||||
|
||||
act(() => {
|
||||
eventBus.publish(
|
||||
streamMsg("run-1", {
|
||||
type: "stream_event",
|
||||
event: {
|
||||
type: "content_block_start",
|
||||
index: 0,
|
||||
message: { id: "m1" },
|
||||
content_block: { type: "text", text: "" },
|
||||
},
|
||||
})
|
||||
);
|
||||
eventBus.publish(
|
||||
streamMsg("run-1", {
|
||||
type: "stream_event",
|
||||
event: {
|
||||
type: "content_block_delta",
|
||||
index: 0,
|
||||
message: { id: "m1" },
|
||||
delta: { type: "text_delta", text: "hi" },
|
||||
},
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
// Still 2 envelopes: the deltas mutated the placeholder, they did not append.
|
||||
expect(result.current.envelopes).toHaveLength(2);
|
||||
const placeholder = result.current.envelopes[1] as {
|
||||
message: { content: { text?: string }[]; _streaming?: boolean };
|
||||
};
|
||||
expect(placeholder.message.content[0]?.text).toBe("hi");
|
||||
expect(placeholder.message._streaming).toBe(true);
|
||||
});
|
||||
|
||||
it("invokes onStatus only for the subscribed run id, onAnyStatus for every run_status", () => {
|
||||
const onStatus = vi.fn();
|
||||
const onAnyStatus = vi.fn();
|
||||
renderHook(() => useRunStream("run-1", { ...noopOpts, onStatus, onAnyStatus }));
|
||||
|
||||
act(() => {
|
||||
eventBus.publish(statusMsg("run-1", "completed"));
|
||||
eventBus.publish(statusMsg("run-2", "completed"));
|
||||
});
|
||||
|
||||
expect(onStatus).toHaveBeenCalledTimes(1);
|
||||
expect(onStatus.mock.calls[0]?.[0]).toMatchObject({ id: "run-1", status: "completed" });
|
||||
expect(onAnyStatus).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it("invokes onInputAck only for the subscribed run id", () => {
|
||||
const onInputAck = vi.fn();
|
||||
renderHook(() => useRunStream("run-1", { ...noopOpts, onInputAck }));
|
||||
|
||||
act(() => {
|
||||
eventBus.publish({ type: "run_input_ack", data: { id: "run-2" } } as WSMessage);
|
||||
eventBus.publish({ type: "run_input_ack", data: { id: "run-1" } } as WSMessage);
|
||||
});
|
||||
|
||||
expect(onInputAck).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("ignores every frame while the run id is null", () => {
|
||||
const onAnyStatus = vi.fn();
|
||||
const { result } = renderHook(() => useRunStream(null, { ...noopOpts, onAnyStatus }));
|
||||
|
||||
act(() => {
|
||||
eventBus.publish(streamMsg("run-1", { type: "result" }));
|
||||
eventBus.publish(statusMsg("run-1", "completed"));
|
||||
});
|
||||
|
||||
expect(result.current.envelopes).toEqual([]);
|
||||
expect(onAnyStatus).toHaveBeenCalledTimes(1); // id-agnostic by design
|
||||
});
|
||||
|
||||
it("disposes the event bus subscription on unmount", () => {
|
||||
const dispose = vi.fn();
|
||||
const subscribe = vi.spyOn(eventBus, "subscribe").mockReturnValue(dispose);
|
||||
|
||||
const { unmount } = renderHook(() => useRunStream("run-1", noopOpts));
|
||||
expect(subscribe).toHaveBeenCalledTimes(1);
|
||||
expect(dispose).not.toHaveBeenCalled();
|
||||
|
||||
unmount();
|
||||
expect(dispose).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("exposes setEnvelopes so the page can seed and clear the list", () => {
|
||||
const { result } = renderHook(() => useRunStream("run-1", noopOpts));
|
||||
|
||||
act(() => {
|
||||
result.current.setEnvelopes([{ type: "user", message: { content: "hello" } } as Envelope]);
|
||||
});
|
||||
expect(result.current.envelopes).toHaveLength(1);
|
||||
|
||||
act(() => {
|
||||
result.current.setEnvelopes([]);
|
||||
});
|
||||
expect(result.current.envelopes).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../i18n`
|
||||
* - `../lib/eventBus`
|
||||
|
||||
@@ -1,489 +0,0 @@
|
||||
/**
|
||||
* @file useRunStream.ts
|
||||
* @description Owns the Run page's live stream-json state. Subscribes to the
|
||||
* WebSocket event bus and folds every `run_stream` envelope for one run id into
|
||||
* an envelope array (`mergeEnvelope` and friends, moved here verbatim from
|
||||
* `pages/Run.tsx`), exposes the typewriter-smoothed view of that array, and
|
||||
* hands `run_status` / `run_input_ack` back to the caller — the page still owns
|
||||
* the `RunHandle` and the run-list refresh, so those arrive as callbacks.
|
||||
*
|
||||
* The stream-json envelope types live here too, since this hook is what
|
||||
* produces them; the page imports them for rendering.
|
||||
*
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
|
||||
import { useEffect, useMemo, useRef, useState } from "react";
|
||||
import { flushSync } from "react-dom";
|
||||
import { eventBus } from "../lib/eventBus";
|
||||
import type {
|
||||
RunInputAckPayload,
|
||||
RunStatusPayload,
|
||||
RunStreamPayload,
|
||||
WSMessage,
|
||||
} from "../lib/types";
|
||||
|
||||
// ── Stream-json envelope shapes (the bits we render) ──────────────────
|
||||
|
||||
export type ContentBlock =
|
||||
| { type: "text"; text: string }
|
||||
| { type: "thinking"; thinking?: string }
|
||||
| { type: "tool_use"; id: string; name: string; input: unknown }
|
||||
| { type: "tool_result"; tool_use_id: string; content: unknown; is_error?: boolean };
|
||||
|
||||
export interface AssistantMessage {
|
||||
type: "assistant";
|
||||
message?: {
|
||||
content?: ContentBlock[] | string;
|
||||
usage?: {
|
||||
input_tokens?: number;
|
||||
output_tokens?: number;
|
||||
cache_read_input_tokens?: number;
|
||||
cache_creation_input_tokens?: number;
|
||||
};
|
||||
};
|
||||
}
|
||||
export interface UserMessage {
|
||||
type: "user";
|
||||
message?: { content?: ContentBlock[] | string };
|
||||
}
|
||||
export interface SystemInit {
|
||||
type: "system";
|
||||
subtype: "init";
|
||||
session_id?: string;
|
||||
model?: string;
|
||||
cwd?: string;
|
||||
tools?: string[];
|
||||
permissionMode?: string;
|
||||
}
|
||||
export interface ResultEnvelope {
|
||||
type: "result";
|
||||
subtype?: string;
|
||||
is_error?: boolean;
|
||||
duration_ms?: number;
|
||||
duration_api_ms?: number;
|
||||
num_turns?: number;
|
||||
result?: string;
|
||||
session_id?: string;
|
||||
total_cost_usd?: number;
|
||||
usage?: { input_tokens?: number; output_tokens?: number };
|
||||
}
|
||||
export type Envelope =
|
||||
| AssistantMessage
|
||||
| UserMessage
|
||||
| SystemInit
|
||||
| ResultEnvelope
|
||||
| { type: string; [k: string]: unknown };
|
||||
|
||||
// ── Streaming envelope merge ───────────────────────────────────────────
|
||||
//
|
||||
// `claude --output-format stream-json --include-partial-messages` emits two
|
||||
// kinds of assistant output:
|
||||
//
|
||||
// 1. `stream_event` envelopes carrying Anthropic Messages API streaming
|
||||
// events (`message_start`, `content_block_start`, `content_block_delta`,
|
||||
// `content_block_stop`, `message_delta`, `message_stop`).
|
||||
// 2. Eventually, a single complete `assistant` envelope summarising the turn.
|
||||
//
|
||||
// To make the chat actually stream character-by-character we accumulate the
|
||||
// `stream_event` deltas into a synthetic assistant envelope. When the real
|
||||
// `assistant` envelope arrives, we replace the synthetic one with it (their
|
||||
// content is identical at that point, but the final envelope has authoritative
|
||||
// usage / metadata).
|
||||
|
||||
interface StreamEventEnvelope {
|
||||
type: "stream_event";
|
||||
event?: {
|
||||
type: string;
|
||||
index?: number;
|
||||
delta?: {
|
||||
type: string;
|
||||
text?: string;
|
||||
thinking?: string;
|
||||
partial_json?: string;
|
||||
};
|
||||
content_block?: {
|
||||
type: string;
|
||||
text?: string;
|
||||
thinking?: string;
|
||||
id?: string;
|
||||
name?: string;
|
||||
input?: unknown;
|
||||
};
|
||||
message?: { id?: string };
|
||||
};
|
||||
}
|
||||
|
||||
type StreamingAssistantBlock = ContentBlock & {
|
||||
_partialJson?: string;
|
||||
};
|
||||
|
||||
interface StreamingAssistantMessage {
|
||||
type: "assistant";
|
||||
_streamId?: string;
|
||||
message: {
|
||||
id?: string;
|
||||
content: StreamingAssistantBlock[];
|
||||
_streaming?: boolean;
|
||||
};
|
||||
}
|
||||
|
||||
function findLastStreamingAssistant(prev: Envelope[]): number {
|
||||
for (let i = prev.length - 1; i >= 0; i--) {
|
||||
const env = prev[i] as { type?: string; message?: { _streaming?: boolean } };
|
||||
if (env?.type === "assistant" && env.message?._streaming) return i;
|
||||
}
|
||||
return -1;
|
||||
}
|
||||
|
||||
function findAssistantByMessageId(prev: Envelope[], id: string | undefined): number {
|
||||
if (!id) return findLastStreamingAssistant(prev);
|
||||
for (let i = prev.length - 1; i >= 0; i--) {
|
||||
const env = prev[i] as { type?: string; message?: { id?: string } };
|
||||
if (env?.type === "assistant" && env.message?.id === id) return i;
|
||||
}
|
||||
return findLastStreamingAssistant(prev);
|
||||
}
|
||||
|
||||
function mutateAssistantAt(
|
||||
prev: Envelope[],
|
||||
idx: number,
|
||||
fn: (m: StreamingAssistantMessage["message"]) => StreamingAssistantMessage["message"]
|
||||
): Envelope[] {
|
||||
if (idx < 0) return prev;
|
||||
const env = prev[idx] as StreamingAssistantMessage;
|
||||
const next = [...prev];
|
||||
next[idx] = {
|
||||
...env,
|
||||
message: fn(env.message || ({ content: [] } as StreamingAssistantMessage["message"])),
|
||||
};
|
||||
return next;
|
||||
}
|
||||
|
||||
function mergeEnvelope(prev: Envelope[], envelope: Envelope): Envelope[] {
|
||||
if (!envelope || typeof envelope !== "object") return prev;
|
||||
const env = envelope as { type?: string };
|
||||
|
||||
if (env.type === "stream_event") {
|
||||
const sse = envelope as StreamEventEnvelope;
|
||||
const evt = sse.event;
|
||||
if (!evt) return prev;
|
||||
|
||||
if (evt.type === "message_start") {
|
||||
const placeholder: StreamingAssistantMessage = {
|
||||
type: "assistant",
|
||||
message: {
|
||||
id: evt.message?.id,
|
||||
content: [],
|
||||
_streaming: true,
|
||||
},
|
||||
};
|
||||
// Keep the message_start envelope itself in the array - its
|
||||
// `event.message.usage` is the only place we get the initial input /
|
||||
// cache token counts during live streaming. Without it, the meter is
|
||||
// stuck at zero until the post-reload replay re-injects the same
|
||||
// envelopes from the server.
|
||||
return [...prev, envelope, placeholder as unknown as Envelope];
|
||||
}
|
||||
|
||||
if (evt.type === "content_block_start") {
|
||||
const idx = findAssistantByMessageId(prev, evt.message?.id);
|
||||
if (idx < 0) return prev;
|
||||
const blockIdx = evt.index ?? 0;
|
||||
return mutateAssistantAt(prev, idx, (msg) => {
|
||||
const blocks = [...(msg.content || [])];
|
||||
blocks[blockIdx] = { ...(evt.content_block as ContentBlock) };
|
||||
return { ...msg, content: blocks };
|
||||
});
|
||||
}
|
||||
|
||||
if (evt.type === "content_block_delta") {
|
||||
const idx = findAssistantByMessageId(prev, evt.message?.id);
|
||||
if (idx < 0) return prev;
|
||||
const blockIdx = evt.index ?? 0;
|
||||
return mutateAssistantAt(prev, idx, (msg) => {
|
||||
const blocks = [...(msg.content || [])];
|
||||
const block = (blocks[blockIdx] || {}) as StreamingAssistantBlock;
|
||||
const next = { ...block } as StreamingAssistantBlock;
|
||||
const delta = evt.delta;
|
||||
if (delta?.type === "text_delta") {
|
||||
(next as { text?: string }).text =
|
||||
((next as { text?: string }).text || "") + (delta.text || "");
|
||||
if (!next.type) (next as { type: string }).type = "text";
|
||||
} else if (delta?.type === "thinking_delta") {
|
||||
(next as { thinking?: string }).thinking =
|
||||
((next as { thinking?: string }).thinking || "") + (delta.thinking || "");
|
||||
if (!next.type) (next as { type: string }).type = "thinking";
|
||||
} else if (delta?.type === "input_json_delta") {
|
||||
// tool_use input streams as JSON-string fragments; accumulate, parse
|
||||
// best-effort whenever the buffer is valid JSON.
|
||||
next._partialJson = (next._partialJson || "") + (delta.partial_json || "");
|
||||
try {
|
||||
(next as { input?: unknown }).input = JSON.parse(next._partialJson);
|
||||
} catch {
|
||||
/* still incomplete JSON - leave previous parsed value */
|
||||
}
|
||||
}
|
||||
blocks[blockIdx] = next;
|
||||
return { ...msg, content: blocks };
|
||||
});
|
||||
}
|
||||
|
||||
if (evt.type === "message_stop") {
|
||||
const idx = findAssistantByMessageId(prev, evt.message?.id);
|
||||
if (idx < 0) return prev;
|
||||
return mutateAssistantAt(prev, idx, (msg) => ({ ...msg, _streaming: false }));
|
||||
}
|
||||
|
||||
if (evt.type === "message_delta") {
|
||||
// message_delta carries the canonical per-message usage update (the
|
||||
// running output_tokens for this turn). Keep the envelope so
|
||||
// computeTokens can read it; otherwise the meter sits at the
|
||||
// message_start placeholder value (output_tokens=4 etc) for the
|
||||
// entire response.
|
||||
return [...prev, envelope];
|
||||
}
|
||||
|
||||
// content_block_start/stop and other stream_event subtypes are mutations
|
||||
// on the placeholder we already track - no usage info, no need to keep
|
||||
// the envelope itself.
|
||||
return prev;
|
||||
}
|
||||
|
||||
if (env.type === "assistant") {
|
||||
// Claude emits the canonical `assistant` envelope BEFORE `message_stop`,
|
||||
// so the message is still streaming at this point. Two regressions came
|
||||
// out of replacing the placeholder wholesale here:
|
||||
// 1. The `_streaming` flag was dropped, making the typewriter snap to
|
||||
// full text the moment this envelope arrived.
|
||||
// 2. The final envelope sometimes ships only the `text` content block
|
||||
// (the `thinking` block we accumulated from `thinking_delta`s
|
||||
// disappears), so the thinking section vanished as soon as the
|
||||
// stream finished.
|
||||
// Fix: when the placeholder was streaming, keep our delta-accumulated
|
||||
// content (it's the authoritative record of every block) and only pull
|
||||
// metadata from the incoming envelope. `message_stop` clears `_streaming`
|
||||
// and the typewriter then reveals any unrevealed tail instantly.
|
||||
const finalMsg = envelope as { message?: { id?: string; _streaming?: boolean } };
|
||||
const idx = findAssistantByMessageId(prev, finalMsg.message?.id);
|
||||
if (idx >= 0) {
|
||||
const prevEnv = prev[idx] as StreamingAssistantMessage;
|
||||
const next = [...prev];
|
||||
if (prevEnv.message?._streaming) {
|
||||
const incoming = envelope as { message?: Record<string, unknown> };
|
||||
const incomingMsg = (incoming.message || {}) as Record<string, unknown>;
|
||||
const accumulatedContent = prevEnv.message?.content || [];
|
||||
const incomingContent = (incomingMsg as { content?: ContentBlock[] }).content;
|
||||
// If the canonical envelope happens to carry MORE blocks (e.g. it
|
||||
// includes a tool_use we hadn't seen as a stream_event yet), prefer
|
||||
// it. Otherwise keep our accumulated blocks so we don't lose a
|
||||
// thinking section the canonical envelope omitted.
|
||||
const content =
|
||||
Array.isArray(incomingContent) && incomingContent.length > accumulatedContent.length
|
||||
? incomingContent
|
||||
: accumulatedContent;
|
||||
next[idx] = {
|
||||
...envelope,
|
||||
message: { ...incomingMsg, content, _streaming: true },
|
||||
} as Envelope;
|
||||
} else {
|
||||
next[idx] = envelope;
|
||||
}
|
||||
return next;
|
||||
}
|
||||
return [...prev, envelope];
|
||||
}
|
||||
|
||||
return [...prev, envelope];
|
||||
}
|
||||
|
||||
/**
|
||||
* Smooth out claude's bursty stream by dripping text/thinking deltas a few
|
||||
* characters per frame. Without this, short responses (where claude emits
|
||||
* the entire reply in one or two `text_delta` chunks) appear all-at-once.
|
||||
* The hook returns a derived envelope list with each actively-streaming
|
||||
* text/thinking block clamped to a displayed length that grows toward the
|
||||
* server's target via requestAnimationFrame.
|
||||
*/
|
||||
function useTypewriterEnvelopes(envelopes: Envelope[]): Envelope[] {
|
||||
const lengthsRef = useRef<Map<string, number>>(new Map());
|
||||
const envRef = useRef<Envelope[]>(envelopes);
|
||||
envRef.current = envelopes;
|
||||
const [tick, setTick] = useState(0);
|
||||
const rafRef = useRef<number | null>(null);
|
||||
const tickFnRef = useRef<(() => void) | null>(null);
|
||||
|
||||
if (!tickFnRef.current) {
|
||||
tickFnRef.current = function tickFn() {
|
||||
const envs = envRef.current;
|
||||
const lengths = lengthsRef.current;
|
||||
let needsAnother = false;
|
||||
let mutated = false;
|
||||
for (let ei = 0; ei < envs.length; ei++) {
|
||||
const env = envs[ei];
|
||||
if (!env || (env as { type?: string }).type !== "assistant") continue;
|
||||
const e = env as StreamingAssistantMessage;
|
||||
const streaming = !!e.message?._streaming;
|
||||
const blocks = e.message?.content || [];
|
||||
for (let bi = 0; bi < blocks.length; bi++) {
|
||||
const b = blocks[bi];
|
||||
if (!b) continue;
|
||||
let key: string;
|
||||
let target: string;
|
||||
if (b.type === "text") {
|
||||
key = `${ei}:${bi}:t`;
|
||||
target = (b as { text?: string }).text || "";
|
||||
} else if (b.type === "thinking") {
|
||||
key = `${ei}:${bi}:th`;
|
||||
target = (b as { thinking?: string }).thinking || "";
|
||||
} else {
|
||||
continue;
|
||||
}
|
||||
const cur = lengths.get(key) ?? 0;
|
||||
if (cur >= target.length) continue;
|
||||
if (streaming) {
|
||||
// Catch up to target in roughly 0.4s; bigger gaps drip faster.
|
||||
const remaining = target.length - cur;
|
||||
const step = Math.max(2, Math.ceil(remaining / 24));
|
||||
lengths.set(key, Math.min(target.length, cur + step));
|
||||
needsAnother = true;
|
||||
mutated = true;
|
||||
} else {
|
||||
// Block is no longer streaming → reveal the rest instantly.
|
||||
lengths.set(key, target.length);
|
||||
mutated = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
if (mutated) setTick((t) => (t + 1) & 0xffff);
|
||||
rafRef.current = needsAnother
|
||||
? requestAnimationFrame(tickFnRef.current as FrameRequestCallback)
|
||||
: null;
|
||||
};
|
||||
}
|
||||
|
||||
// Single long-lived RAF loop. Reads envelopes via ref so new server data
|
||||
// is picked up without tearing down and rescheduling the loop on every
|
||||
// websocket message - a previous version restarted on each envelope
|
||||
// change which dropped frames between bursts and hid the streaming.
|
||||
useEffect(() => {
|
||||
rafRef.current = requestAnimationFrame(tickFnRef.current as FrameRequestCallback);
|
||||
return () => {
|
||||
if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
|
||||
rafRef.current = null;
|
||||
};
|
||||
}, []);
|
||||
|
||||
// Wake the loop when new envelopes arrive if it's parked (no pending work).
|
||||
useEffect(() => {
|
||||
if (rafRef.current == null && envelopes.length > 0) {
|
||||
rafRef.current = requestAnimationFrame(tickFnRef.current as FrameRequestCallback);
|
||||
}
|
||||
}, [envelopes]);
|
||||
|
||||
// Reset lengths when envelopes shrink (e.g., the user starts a new run).
|
||||
useEffect(() => {
|
||||
if (envelopes.length === 0 && lengthsRef.current.size > 0) {
|
||||
lengthsRef.current.clear();
|
||||
}
|
||||
}, [envelopes.length]);
|
||||
|
||||
return useMemo(() => {
|
||||
const lengths = lengthsRef.current;
|
||||
return envelopes.map((env, ei) => {
|
||||
if (!env || (env as { type?: string }).type !== "assistant") return env;
|
||||
const e = env as StreamingAssistantMessage;
|
||||
const blocks = e.message?.content || [];
|
||||
let changed = false;
|
||||
const nextBlocks = blocks.map((b, bi) => {
|
||||
if (b.type === "text") {
|
||||
const full = (b as { text?: string }).text || "";
|
||||
const len = lengths.get(`${ei}:${bi}:t`) ?? full.length;
|
||||
if (len < full.length) {
|
||||
changed = true;
|
||||
return { ...b, text: full.slice(0, len) };
|
||||
}
|
||||
} else if (b.type === "thinking") {
|
||||
const full = (b as { thinking?: string }).thinking || "";
|
||||
const len = lengths.get(`${ei}:${bi}:th`) ?? full.length;
|
||||
if (len < full.length) {
|
||||
changed = true;
|
||||
return { ...b, thinking: full.slice(0, len) };
|
||||
}
|
||||
}
|
||||
return b;
|
||||
});
|
||||
if (!changed) return env;
|
||||
return {
|
||||
...e,
|
||||
message: { ...e.message, content: nextBlocks },
|
||||
} as unknown as Envelope;
|
||||
});
|
||||
// tick is intentionally a dep so this memo re-runs on each RAF step.
|
||||
// eslint-disable-next-line react-hooks/exhaustive-deps
|
||||
}, [envelopes, tick]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Subscribe to the live stream of one run.
|
||||
*
|
||||
* `runId` is the id whose frames this hook cares about — `null` while no run is
|
||||
* attached. `onStatus` and `onInputAck` fire only for a payload matching
|
||||
* `runId` (mirroring the page's old `handle && p.id === handle.id` guard);
|
||||
* `onAnyStatus` fires for EVERY `run_status` frame regardless of id, because
|
||||
* the page's run-list refresh has always been id-agnostic.
|
||||
*/
|
||||
export function useRunStream(
|
||||
runId: string | null,
|
||||
opts: {
|
||||
onStatus: (p: RunStatusPayload) => void;
|
||||
onInputAck: () => void;
|
||||
onAnyStatus: () => void;
|
||||
}
|
||||
): {
|
||||
envelopes: Envelope[];
|
||||
setEnvelopes: React.Dispatch<React.SetStateAction<Envelope[]>>;
|
||||
displayEnvelopes: Envelope[];
|
||||
} {
|
||||
const [envelopes, setEnvelopes] = useState<Envelope[]>([]);
|
||||
const displayEnvelopes = useTypewriterEnvelopes(envelopes);
|
||||
|
||||
// Latest callbacks in a ref so the subscription's lifetime depends on the
|
||||
// run id alone - re-subscribing whenever a caller passes a fresh closure
|
||||
// would tear down and rebuild the bus handler on every page render.
|
||||
const optsRef = useRef(opts);
|
||||
optsRef.current = opts;
|
||||
|
||||
// WebSocket subscription - only act on messages for the current run.
|
||||
useEffect(() => {
|
||||
return eventBus.subscribe((msg: WSMessage) => {
|
||||
if (msg.type === "run_stream") {
|
||||
const p = msg.data as RunStreamPayload;
|
||||
if (runId && p.id === runId) {
|
||||
// React 18 auto-batches async setStates, which collapses bursts of
|
||||
// stream_event deltas (and the final `assistant` envelope that
|
||||
// follows them) into a single render - visually erasing the
|
||||
// streaming effect. flushSync forces a commit per envelope so the
|
||||
// user sees text_delta / thinking_delta chunks paint as they
|
||||
// arrive instead of all at once.
|
||||
flushSync(() => {
|
||||
setEnvelopes((prev) => mergeEnvelope(prev, p.envelope as Envelope));
|
||||
});
|
||||
}
|
||||
} else if (msg.type === "run_status") {
|
||||
const p = msg.data as RunStatusPayload;
|
||||
if (runId && p.id === runId) {
|
||||
optsRef.current.onStatus(p);
|
||||
}
|
||||
optsRef.current.onAnyStatus();
|
||||
} else if (msg.type === "run_input_ack") {
|
||||
const p = msg.data as RunInputAckPayload;
|
||||
if (runId && p.id === runId) {
|
||||
optsRef.current.onInputAck();
|
||||
}
|
||||
}
|
||||
});
|
||||
}, [runId]);
|
||||
|
||||
return { envelopes, setEnvelopes, displayEnvelopes };
|
||||
}
|
||||
@@ -20,11 +20,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../lib/types`
|
||||
* - `../lib/eventBus`
|
||||
|
||||
@@ -35,11 +35,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./locales/en/common.json`
|
||||
* - `./locales/vi/common.json`
|
||||
|
||||
@@ -90,10 +90,14 @@
|
||||
"git.uncommitted": "{{dirty}} modified · {{untracked}} untracked",
|
||||
"kind.adopted": "adopted",
|
||||
"kind.managed": "managed",
|
||||
"laneDetail.hide": "Hide details",
|
||||
"laneDetail.show": "Lane details",
|
||||
"laneHeader": "Lane {{id}} · {{title}} · {{pipeline}}",
|
||||
"locks.held_one": "{{count}} lock held",
|
||||
"locks.held_other": "{{count}} locks held",
|
||||
"moreActions": "More actions",
|
||||
"pipelinePicker.label": "Pipeline template",
|
||||
"pipelinePicker.stageMismatch": "Stage \"{{stage}}\" matches no node in \"{{pipeline}}\" — declare one of: {{nodes}}",
|
||||
"preflightError": "Could not load the current lane facts.",
|
||||
"preflightErrorWithMessage": "Could not load the current lane facts: {{message}}",
|
||||
"runtime.boot": "▶ up",
|
||||
@@ -118,6 +122,10 @@
|
||||
"features.archived": "archived",
|
||||
"features.viewingArchived": "Viewing archived feature \"{{slug}}\" — the lane keeps running; this is a read-only snapshot.",
|
||||
"proof.ticketReport": "Task report",
|
||||
"splitView.emptyPane": "No lane selected for this pane.",
|
||||
"splitView.paneLaneLabel": "Pane lane selector",
|
||||
"splitView.paneCount": "{{count}} pane",
|
||||
"splitView.pickLane": "Pick a lane",
|
||||
"statusDead": "DEAD",
|
||||
"title": "Lanes",
|
||||
"tooltipStart": "Spawn a conversation-mode run with no initial prompt; driven from CLI or via message"
|
||||
|
||||
@@ -74,7 +74,8 @@
|
||||
"permissionMode": "Permission mode",
|
||||
"permissionPlan": "plan (read-only planning)",
|
||||
"prompt": "Prompt",
|
||||
"promptPlaceholder": "Ask Claude anything…"
|
||||
"promptPlaceholder": "Ask Claude anything…",
|
||||
"promptPlaceholderTerminal": "Ask Claude anything…"
|
||||
},
|
||||
"footer": {
|
||||
"cost": "Cost",
|
||||
|
||||
@@ -90,10 +90,14 @@
|
||||
"git.uncommitted": "{{dirty}} đã sửa · {{untracked}} chưa theo dõi",
|
||||
"kind.adopted": "đã nhận",
|
||||
"kind.managed": "được quản lý",
|
||||
"laneDetail.hide": "Ẩn chi tiết",
|
||||
"laneDetail.show": "Chi tiết lane",
|
||||
"laneHeader": "Làn đường {{id}} · {{title}} · {{pipeline}}",
|
||||
"locks.held_one": "Đang giữ {{count}} khóa",
|
||||
"locks.held_other": "Đang giữ {{count}} khóa",
|
||||
"moreActions": "Thêm hành động",
|
||||
"pipelinePicker.label": "Mẫu pipeline",
|
||||
"pipelinePicker.stageMismatch": "Stage \"{{stage}}\" không khớp node nào trong \"{{pipeline}}\" — khai báo một trong: {{nodes}}",
|
||||
"preflightError": "Không thể tải trạng thái làn đường hiện tại.",
|
||||
"preflightErrorWithMessage": "Không thể tải trạng thái làn đường hiện tại: {{message}}",
|
||||
"runtime.boot": "▶ chạy",
|
||||
@@ -118,6 +122,10 @@
|
||||
"features.archived": "đã lưu trữ",
|
||||
"features.viewingArchived": "Xem tính năng đã lưu trữ \"{{slug}}\" — lane tiếp tục chạy; đây là ảnh chụp nhanh chỉ đọc.",
|
||||
"proof.ticketReport": "Báo cáo nhiệm vụ",
|
||||
"splitView.emptyPane": "Chưa chọn lane cho ô này.",
|
||||
"splitView.paneLaneLabel": "Bộ chọn lane cho ô",
|
||||
"splitView.paneCount": "{{count}} ô",
|
||||
"splitView.pickLane": "Chọn lane",
|
||||
"statusDead": "ĐÃ CHẾT",
|
||||
"title": "Làn đường",
|
||||
"tooltipStart": "Tạo một lần chạy ở chế độ hội thoại mà không có lời nhắc ban đầu; được điều khiển từ CLI hoặc qua tin nhắn"
|
||||
|
||||
@@ -73,7 +73,8 @@
|
||||
"permissionMode": "Permission mode",
|
||||
"permissionPlan": "plan (chỉ đọc, lập kế hoạch)",
|
||||
"prompt": "Prompt",
|
||||
"promptPlaceholder": "Hỏi Claude bất cứ điều gì…"
|
||||
"promptPlaceholder": "Hỏi Claude bất cứ điều gì…",
|
||||
"promptPlaceholderTerminal": "Hỏi Claude bất cứ điều gì…"
|
||||
},
|
||||
"footer": {
|
||||
"cost": "Chi phí",
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
/**
|
||||
* @file splitViewStorage.test.ts
|
||||
* @description Tests for the splitViewStorage module.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach } from "vitest";
|
||||
import {
|
||||
readSplitViewState,
|
||||
writeSplitViewState,
|
||||
defaultSplitViewState,
|
||||
} from "../splitViewStorage";
|
||||
|
||||
describe("splitViewStorage", () => {
|
||||
beforeEach(() => {
|
||||
localStorage.clear();
|
||||
});
|
||||
|
||||
it("returns the default state when nothing is stored", () => {
|
||||
expect(readSplitViewState()).toEqual(defaultSplitViewState());
|
||||
});
|
||||
|
||||
it("defaults to a single unselected pane", () => {
|
||||
expect(defaultSplitViewState()).toEqual({ layout: 1, paneLaneIds: [null] });
|
||||
});
|
||||
|
||||
it("round-trips a written state", () => {
|
||||
writeSplitViewState({ layout: 4, paneLaneIds: [1, 2, null, null] });
|
||||
expect(readSplitViewState()).toEqual({ layout: 4, paneLaneIds: [1, 2, null, null] });
|
||||
});
|
||||
|
||||
it("falls back to the default when stored JSON is malformed", () => {
|
||||
localStorage.setItem("ccam.workspace.splitView", "{not json");
|
||||
expect(readSplitViewState()).toEqual(defaultSplitViewState());
|
||||
});
|
||||
|
||||
it("falls back to the default when the stored layout is not 1, 2, or 4", () => {
|
||||
localStorage.setItem(
|
||||
"ccam.workspace.splitView",
|
||||
JSON.stringify({ layout: 3, paneLaneIds: [] })
|
||||
);
|
||||
expect(readSplitViewState()).toEqual(defaultSplitViewState());
|
||||
});
|
||||
});
|
||||
+34
-150
@@ -78,11 +78,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./types`
|
||||
* - `./dataScope`
|
||||
@@ -1479,110 +1474,32 @@ export const api = {
|
||||
/** Spawn/manage headless or conversational `claude` CLI child processes
|
||||
* launched from the dashboard's Run page, and stream their output. */
|
||||
run: {
|
||||
/**
|
||||
* GET /api/run - currently tracked runs (in-memory handles) plus
|
||||
* concurrency limits.
|
||||
* @returns {@link RunListResponse} — live handles + `maxConcurrent`/`activeCount`.
|
||||
*/
|
||||
/** GET /api/run - lanes with a live tmux-backed run, computed fresh from tmux state. */
|
||||
list: () => request<RunListResponse>("/run"),
|
||||
/**
|
||||
* GET /api/run/history - persisted run history from the `dashboard_runs`
|
||||
* table, including runs whose in-memory handle has since been reaped.
|
||||
* Optionally filter by lane.
|
||||
*
|
||||
* `limit` defaults to 50 when the caller omits it and is always sent as a
|
||||
* query param.
|
||||
*
|
||||
* @param limit Max history rows to return (default 50).
|
||||
* @param options Optional filters like laneId.
|
||||
* @returns `{ items }` — {@link DashboardRunHistoryItem} rows, newest-first.
|
||||
*/
|
||||
/** GET /api/run/history - persisted run history from `dashboard_runs`. */
|
||||
history: (limit = 50, options?: { laneId?: number }) => {
|
||||
const qs = new URLSearchParams({ limit: String(limit) });
|
||||
if (options?.laneId !== undefined) qs.set("laneId", String(options.laneId));
|
||||
return request<{ items: DashboardRunHistoryItem[] }>(`/run/history?${qs.toString()}`);
|
||||
},
|
||||
/**
|
||||
* GET /api/run/binary - whether a `claude` executable was found on PATH.
|
||||
*
|
||||
* Lets the Run page disable/enable the "start" affordance and show where the
|
||||
* CLI resolved from (or that it's missing).
|
||||
*
|
||||
* @returns `{ found, path }` — whether a binary was located and its path.
|
||||
*/
|
||||
/** GET /api/run/binary - whether `claude` was found on PATH. */
|
||||
binary: () => request<{ found: boolean; path: string | null }>("/run/binary"),
|
||||
/**
|
||||
* GET /api/run/cwds - suggested working directories for the cwd picker.
|
||||
* @returns `{ items }` — {@link CwdSuggestion} entries (dashboard/home/recent).
|
||||
*/
|
||||
/** GET /api/run/tmux - whether the `tmux` binary was found on PATH. */
|
||||
tmuxAvailable: () => request<{ available: boolean }>("/run/tmux"),
|
||||
/** GET /api/run/cwds - suggested working directories for the cwd picker. */
|
||||
cwds: () => request<{ items: CwdSuggestion[] }>("/run/cwds"),
|
||||
/**
|
||||
* GET /api/run/files - path-completion suggestions under `cwd`, filtered
|
||||
* by an optional query fragment `q`.
|
||||
*
|
||||
* Backs the file/@-mention autocomplete when composing a run prompt: `cwd`
|
||||
* is always sent; `q` is appended only when non-empty to narrow matches.
|
||||
*
|
||||
* @param cwd The directory to complete paths within.
|
||||
* @param q Optional partial fragment to filter suggestions by.
|
||||
* @returns `{ items }` — matching path strings under `cwd`.
|
||||
*/
|
||||
/** GET /api/run/files - path-completion suggestions under `cwd`. */
|
||||
files: (cwd: string, q?: string) => {
|
||||
const qs = new URLSearchParams({ cwd });
|
||||
if (q) qs.set("q", q);
|
||||
return request<{ items: string[] }>(`/run/files?${qs.toString()}`);
|
||||
},
|
||||
/**
|
||||
* POST /api/run - spawn a new `claude` child process.
|
||||
*
|
||||
* Sends {@link RunStartArgs} (prompt, mode, and optional cwd/model/
|
||||
* permission-mode/resume/effort). The server spawns the CLI and returns the
|
||||
* initial {@link RunHandle}; subsequent output is streamed over the
|
||||
* `run_stream` WebSocket message rather than this response.
|
||||
*
|
||||
* @param args The spawn parameters.
|
||||
* @returns {@link RunHandle} — the freshly created run's handle.
|
||||
*/
|
||||
/** POST /api/run - start (or adopt, if already live) a lane's terminal run. */
|
||||
start: (args: RunStartArgs) =>
|
||||
request<RunHandle>("/run", { method: "POST", body: JSON.stringify(args) }),
|
||||
/**
|
||||
* GET /api/run/:id - one run's current handle; pass `envelopes: true` to
|
||||
* also include its buffered stream-json envelopes (for a page refresh
|
||||
* mid-run, since the WS `run_stream` history isn't otherwise replayed).
|
||||
*
|
||||
* The `envelopes` flag is translated to `?envelopes=1`. Use it when
|
||||
* re-hydrating the Run page after a reload: the WebSocket only pushes *new*
|
||||
* envelopes, so the buffered ones must be pulled once to backfill the view.
|
||||
*
|
||||
* @param id The run id.
|
||||
* @param opts Optional `{ envelopes }` — include buffered stream-json envelopes.
|
||||
* @returns {@link RunHandle} — the run's handle (with `envelopes` when requested).
|
||||
*/
|
||||
get: (id: string, opts?: { envelopes?: boolean }) =>
|
||||
request<RunHandle>(`/run/${encodeURIComponent(id)}${opts?.envelopes ? "?envelopes=1" : ""}`),
|
||||
/**
|
||||
* POST /api/run/:id/message - write `text` to the run's stdin (conversation
|
||||
* mode only); acked via the `run_input_ack` WS message.
|
||||
*
|
||||
* Only meaningful for a run started in "conversation" mode (stdin left
|
||||
* open). The HTTP response returns just the `messageId`; the actual
|
||||
* delivery/echo is confirmed asynchronously over the WebSocket.
|
||||
*
|
||||
* @param id The run id to send input to.
|
||||
* @param text The user's follow-up message written to the CLI's stdin.
|
||||
* @returns `{ messageId }` — id correlating this input with its `run_input_ack`.
|
||||
*/
|
||||
send: (id: string, text: string) =>
|
||||
request<{ messageId: string }>(`/run/${encodeURIComponent(id)}/message`, {
|
||||
method: "POST",
|
||||
body: JSON.stringify({ text }),
|
||||
}),
|
||||
/**
|
||||
* DELETE /api/run/:id - forcibly terminate a running process.
|
||||
*
|
||||
* @param id The run id to kill.
|
||||
* @returns `{ ok: true }` — acknowledgement that termination was requested.
|
||||
*/
|
||||
/** GET /api/run/:id - one run's current handle. */
|
||||
get: (id: string) => request<RunHandle>(`/run/${encodeURIComponent(id)}`),
|
||||
/** DELETE /api/run/:id - kill the tmux session. */
|
||||
kill: (id: string) =>
|
||||
request<{ ok: true }>(`/run/${encodeURIComponent(id)}`, { method: "DELETE" }),
|
||||
},
|
||||
@@ -2511,78 +2428,51 @@ export interface CcHookScripts {
|
||||
// mirror the CLI's own vocabulary so the dashboard can drive the CLI faithfully.
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
/** "headless" runs to completion unattended and streams only output;
|
||||
* "conversation" keeps stdin open so the user can send follow-up messages. */
|
||||
export type RunMode = "headless" | "conversation";
|
||||
/** Lifecycle of a spawned `claude` process, mirrored in `RunHandle.status`
|
||||
* and `RunStatusPayload.status`. "abandoned" is applied by server cleanup
|
||||
* when a handle is reaped without a clean exit ever being observed. */
|
||||
export type RunStatus = "spawning" | "running" | "completed" | "error" | "killed" | "abandoned";
|
||||
/** Maps 1:1 to the `claude --permission-mode` CLI flag. */
|
||||
export type PermissionMode = "acceptEdits" | "default" | "plan" | "bypassPermissions";
|
||||
/** Maps 1:1 to the `claude --effort` CLI flag; "" omits the flag (model default). */
|
||||
export type EffortLevel = "" | "low" | "medium" | "high" | "xhigh" | "max";
|
||||
/** "running" — a live tmux session exists; "gone" — it doesn't (killed,
|
||||
* crashed, claude exited and closed the pane). Computed fresh from tmux
|
||||
* state on every read, never cached. */
|
||||
export type RunStatus = "running" | "gone";
|
||||
|
||||
/** Body for POST /api/run - parameters for spawning a new `claude` process. */
|
||||
/** Body for POST /api/run - parameters for starting a lane's terminal run. */
|
||||
export interface RunStartArgs {
|
||||
/** Initial prompt/task text passed to the CLI. */
|
||||
prompt: string;
|
||||
mode: RunMode;
|
||||
/** Working directory to launch in; server default applies if omitted. */
|
||||
laneId: number;
|
||||
cwd?: string;
|
||||
/** `--model` value; omitted inherits the CLI's own default (settings.json). */
|
||||
model?: string;
|
||||
permissionMode?: PermissionMode;
|
||||
/** Resume an existing Claude Code session id (`--resume`) instead of starting fresh. */
|
||||
resumeSessionId?: string;
|
||||
effort?: EffortLevel;
|
||||
/** Sent as `claude`'s first positional message once the pane boots; omit
|
||||
* to just open the pane and let the user type. */
|
||||
initialPrompt?: string;
|
||||
}
|
||||
|
||||
/** In-memory (or freshly-fetched) handle for one spawned `claude` process,
|
||||
* from POST/GET /api/run - the live counterpart to {@link DashboardRunHistoryItem}.
|
||||
* Where {@link DashboardRunHistoryItem} is the persisted DB row (snake_case,
|
||||
* survives handle reaping), this is the richer live handle (camelCase, carries
|
||||
* argv/tails/envelope counters) that only exists while the server tracks it. */
|
||||
/** A lane's tmux-backed terminal run — one per lane, id is the tmux session
|
||||
* name (`ccam-lane-<laneId>`). */
|
||||
export interface RunHandle {
|
||||
id: string;
|
||||
/** OS process id; null before the process has actually spawned. */
|
||||
pid: number | null;
|
||||
mode: RunMode;
|
||||
cwd: string;
|
||||
model: string | null;
|
||||
permissionMode: PermissionMode;
|
||||
effort: EffortLevel | null;
|
||||
prompt: string;
|
||||
/** Full argv the server invoked the CLI with, for debugging. */
|
||||
argv: string[];
|
||||
resumeSessionId: string | null;
|
||||
laneId: number | null;
|
||||
status: RunStatus;
|
||||
/** Epoch-ms timestamp the process was spawned. */
|
||||
startedAt: number;
|
||||
/** Epoch-ms timestamp the process exited; null while still running. */
|
||||
endedAt: number | null;
|
||||
exitCode: number | null;
|
||||
/** POSIX signal that killed the process (e.g. "SIGTERM"); null otherwise. */
|
||||
signal: string | null;
|
||||
error: string | null;
|
||||
/** Claude Code session id the run created/resumed, once known. */
|
||||
cwd: string | null;
|
||||
model: string | null;
|
||||
permissionMode: PermissionMode | null;
|
||||
effort: EffortLevel | null;
|
||||
resumeSessionId: string | null;
|
||||
/** Claude Code session id this run created/resumed, once known. */
|
||||
sessionId: string | null;
|
||||
/** Count of stream-json envelopes emitted so far. */
|
||||
envelopeCount: number;
|
||||
/** Last chunk of captured stdout, for a quick inline preview. */
|
||||
stdoutTail: string;
|
||||
/** Last chunk of captured stderr, for a quick inline preview. */
|
||||
stderrTail: string;
|
||||
envelopes?: unknown[]; // present when fetched with ?envelopes=1
|
||||
/** ISO timestamp the tmux session was created. */
|
||||
startedAt: string | null;
|
||||
/** Initial prompt preview (first 500 chars), null when not provided. */
|
||||
promptPreview: string | null;
|
||||
}
|
||||
|
||||
/** Response shape of GET /api/run. */
|
||||
export interface RunListResponse {
|
||||
items: RunHandle[];
|
||||
/** Server-configured cap on simultaneously running processes. */
|
||||
maxConcurrent: number;
|
||||
/** Count of runs currently in "spawning"/"running" state. */
|
||||
activeCount: number;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -2596,23 +2486,17 @@ export interface RunListResponse {
|
||||
*/
|
||||
export interface DashboardRunHistoryItem {
|
||||
id: string;
|
||||
/** Claude Code session id the run created/resumed; null if never captured. */
|
||||
session_id: string | null;
|
||||
mode: RunMode;
|
||||
cwd: string;
|
||||
model: string | null;
|
||||
permission_mode: PermissionMode | null;
|
||||
effort: EffortLevel | null;
|
||||
resume_session_id: string | null;
|
||||
/** Truncated leading excerpt of the original prompt, for the history list. */
|
||||
prompt_preview: string | null;
|
||||
status: RunStatus;
|
||||
status: "running" | "killed" | "abandoned";
|
||||
exit_code: number | null;
|
||||
started_at: string;
|
||||
ended_at: string | null;
|
||||
/** True when an in-memory {@link RunHandle} for this row still exists (so
|
||||
* the UI can offer live actions like "send message"/"kill"); false once
|
||||
* the handle has been reaped and only the DB row remains. */
|
||||
isLive: boolean;
|
||||
}
|
||||
|
||||
|
||||
@@ -36,11 +36,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `ScopeMode` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `DataScope` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
@@ -51,11 +51,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./types`
|
||||
*
|
||||
|
||||
@@ -47,11 +47,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./types`
|
||||
*
|
||||
|
||||
@@ -44,11 +44,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `./types`
|
||||
*
|
||||
|
||||
@@ -41,11 +41,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../i18n`
|
||||
*
|
||||
|
||||
@@ -61,11 +61,6 @@
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `TokenType` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `Token` — exported API; see TSDoc on the symbol for behavior.
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user