agentgui 1.0.946 → 1.0.947

package/AGENTS.md

@@ -10,7 +10,7 @@ When `PASSWORD` env var is set, every HTTP route is gated by `lib/http-handler.j
 - `site/app/js/backend.js` — same-origin WS/HTTP client (`DEFAULT_BACKEND = ''`); the transport glue that wires the kit; `?backend=` query override for cross-origin debugging
 - `site/app/js/app.js` — webjsx view + state; renders the `AgentChat` kit (from `anentrypoint-design`) for the chat surface and wires agentgui's WS/ccsniff state as kit callbacks; history/settings remain agentgui-local. Exposes `window.__agentgui`
 
-The chat GUI lives in the design kit, not in agentgui. The reusable multi-agent chat surface is the `AgentChat` component in `anentrypoint-design` (`src/components/agent-chat.js`); agentgui keeps only the transport glue (WS `backend.js`, ccsniff history wiring, agent orchestration) and passes state + callbacks into the kit. To change chat UI, edit the kit and push it (CI publishes to npm → unpkg `@latest`), not agentgui.
+The chat GUI lives in the design kit, not in agentgui. The reusable multi-agent chat surface is the `AgentChat` component in `anentrypoint-design` (`src/components/agent-chat.js`); agentgui keeps only the transport glue (WS `backend.js`, ccsniff history wiring, agent orchestration) and passes state + callbacks into the kit. To change chat UI, edit the kit and push it (CI publishes to npm -> unpkg `@latest`), not agentgui.
 - `server.js` — boots ACP/agents/websocket plugins, mounts `createHistoryRouter()` from `ccsniff` at `/`, serves `site/app/` as static root
 - Plugins kept (lib/plugins/): acp, agents, database, files, stream, websocket, workflow
 
@@ -60,7 +60,7 @@ Pattern: all imports in lib/plugins/* must be either built-in (crypto, fs, path,
 
 ## Plugin Tool Provisioning on Windows
 
-**`lib/tool-spawner.js` must iterate bun → npx fallback and match cross-platform command-not-found errors.**
+**`lib/tool-spawner.js` must iterate bun -> npx fallback and match cross-platform command-not-found errors.**
 
 On Windows hosts without bun installed, the auto-provisioner on startup and 6h periodic update checker failed silently when spawnBunxProc tried `bun.cmd` directly. The missing command error came via process stderr+close, not the 'error' event, so simple ENOENT detection was insufficient. Additionally, the error message format differs by OS: Windows shows "'bun.cmd' is not recognized as an internal or external command", Linux/Mac show "command not found" or "cannot find".
 
@@ -72,7 +72,7 @@ Pattern: When a binary might not exist on all platforms, use a runner fallback s
 
 **gm plugin's pre-tool-use-hook.js enforces "must invoke gm:gm first" gate, blocking multi-tool autonomy. Hook content is NOT sourced from gm-starter/hooks/ files — it is templated from somewhere else.**
 
-The gm plugin enforces a gate via `.gm/needs-gm` marker that requires invoking `gm:gm` before any other tool use, which fragments multi-tool autonomous sessions in agentgui. A bypass patch was committed to c:/dev/gm (commit e300acf7, origin/main) in gm-starter/hooks/{pre-tool-use,prompt-submit}-hook.js to skip the gate when `.gm/prd.yml` exists, but it did NOT propagate after `/plugin update gm` (cache hash changed 495e36843d77 → 075e64d58498 but hook content unchanged).
+The gm plugin enforces a gate via `.gm/needs-gm` marker that requires invoking `gm:gm` before any other tool use, which fragments multi-tool autonomous sessions in agentgui. A bypass patch was committed to c:/dev/gm (commit e300acf7, origin/main) in gm-starter/hooks/{pre-tool-use,prompt-submit}-hook.js to skip the gate when `.gm/prd.yml` exists, but it did NOT propagate after `/plugin update gm` (cache hash changed 495e36843d77 -> 075e64d58498 but hook content unchanged).
 
 The actual hook content is generated/templated from c:/dev/gm, likely from `lib/cli-adapter.js` or `platforms/cli-config-shared.js` or `lib/template-builder.js`, not from gm-starter/hooks/. Next session must:
 1. Locate the real hook generator in the gm codebase
@@ -99,33 +99,19 @@ The function previously returned "Model: X." when agentId was 'claude-code' and
 
 **WebSocket `/sync` endpoint — message ordering requires registering handler BEFORE sending.**
 
-Server sends `sync_connected` with `clientId` on connect. Legacy handler (`lib/ws-legacy-handlers.js`) handles `ping→pong`, `subscribe→subscription_confirmed`, `get_subscriptions→subscriptions`, `unsubscribe`, `latency_report`. All responses use codec encode/decode (`lib/codec.js`). Pattern: queue outbound messages and use a waiters array + sequential promises to avoid race between send and handler registration. Test structure: `const queued = []; let waiting; ws.on('message', ...); queued.forEach(msg => ws.send(msg)); waiting.resolve(...)` ensures the handler is live before messages flow.
+Server sends `sync_connected` with `clientId` on connect. Legacy handler (`lib/ws-legacy-handlers.js`) handles `ping->pong`, `subscribe->subscription_confirmed`, `get_subscriptions->subscriptions`, `unsubscribe`, `latency_report`. All responses use codec encode/decode (`lib/codec.js`). Pattern: queue outbound messages and use a waiters array + sequential promises to avoid race between send and handler registration. Test structure: `const queued = []; let waiting; ws.on('message', ...); queued.forEach(msg => ws.send(msg)); waiting.resolve(...)` ensures the handler is live before messages flow.
 
-## better-sqlite3 & Node v24 Startup (2026-05-03)
+## better-sqlite3 & Node v24 Startup
 
-**Node v24 has no prebuilt binary for better-sqlite3 (module version 137); npm rebuild silently fails.**
-
-When npm install runs on Node v24, the postinstall hook for better-sqlite3 silently fails because no prebuilt `.node` binary exists for that module version. The server then fails to require better-sqlite3 and crashes. npm rebuild also silently fails.
-
-Fix: compile from source in postinstall:
-```json
-"postinstall": "node scripts/patch-fsbrowse.js && node scripts/copy-vendor.js && (cd node_modules/better-sqlite3 && node-gyp rebuild 2>/dev/null) || true"
-```
-
-Paired changes:
-- `package.json` `start` script: `"bun server.js || node server.js"` (prefer bun, fall back to node)
-- `bin/gmgui.cjs` runtime detection: `spawnSync('bun', ['--version'], { shell: true })` to auto-detect bun availability, fallback to node (lines 46-47)
-- better-sqlite3 bumped ^12.6.2 → ^12.9.0
-
-bun start was already working (bun has native sqlite support via `bun:sqlite`). The node path was broken due to the missing native binding. Only compile from source fixes the node path.
+Node v24 lacks a prebuilt better-sqlite3 binary; the node path needs a from-source `postinstall` compile, and `start` is `bun server.js || node server.js`. `database.js` tries `bun:sqlite` first. Detail (postinstall command, paired package.json/bin changes, CI must-run-under-bun) in rs-learn (recall "agentgui startup better-sqlite3 node v24 bun").
 
 ## webjsx applyDiff Array Keying (2026-05-04)
 
 **Children arrays that mix keyed VElements with raw text/numbers crash in `vendor/webjsx/applyDiff.js`.**
 
-`webjsx` requires all siblings in an array prop (children, right, left, breadcrumbs, etc.) to either ALL be VElements with keys or ALL be non-keyed. Passing `Crumb({ right: [h('span', { key: 'a' }, 'A'), h('span', { key: 'b' }, 'B'), '● connected'] })` crashes on render with `TypeError: Cannot read properties of undefined (reading 'key')` at line 247420.js when the render loop tries to read `.key` on the bare string.
+`webjsx` requires all siblings in an array prop (children, right, left, breadcrumbs, etc.) to either ALL be VElements with keys or ALL be non-keyed. Passing `Crumb({ right: [h('span', { key: 'a' }, 'A'), h('span', { key: 'b' }, 'B'), 'connected'] })` crashes on render with `TypeError: Cannot read properties of undefined (reading 'key')` at line 247420.js when the render loop tries to read `.key` on the bare string.
 
-Fix: wrap any bare strings as keyed VElements: `h('span', { key: 'dot' }, '● connected')`. Rule: if ANY sibling in an array has a key, ALL siblings must be VElements (no raw strings or numbers).
+Fix: wrap any bare strings as keyed VElements: `h('span', { key: 'dot' }, 'connected')`. Rule: if ANY sibling in an array has a key, ALL siblings must be VElements (no raw strings or numbers).
 
 Surfaced 2026-05-04 while validating the chat surface in `site/app/`. Fix applied to crumbRight construction in `site/app/js/app.js` view().
 
@@ -143,7 +129,7 @@ Event dispatch loop:
 
 Throttle renders via `requestAnimationFrame` to avoid event storm during burst loads.
 
-**First request to `/v1/history/*` triggers loadOnce() that walks all JSONL files under ~/.claude/projects** (env default; override with `CLAUDE_PROJECTS_DIR`). In our test env: 299 files, 80MB, 69k events → 30-90s startup latency. Health check timeouts during this window are normal and expected. Subsequent requests are fast (cached index).
+**First request to `/v1/history/*` triggers loadOnce() that walks all JSONL files under ~/.claude/projects** (env default; override with `CLAUDE_PROJECTS_DIR`). In our test env: 299 files, 80MB, 69k events -> 30-90s startup latency. Health check timeouts during this window are normal and expected. Subsequent requests are fast (cached index).
 
 The endpoints are served by ccsniff's Express router mounted in-process from `server.js`. No external proxy.
 
@@ -153,10 +139,18 @@ The GUI loads `anentrypoint-design` from `https://unpkg.com/anentrypoint-design@
 
 ## Agent/model/session management (2026-05-28)
 
-- `agents.list` (WS) returns `available` + `npxInstallable` per agent; `agents.models` returns model choices (claude-code → sonnet/opus/haiku). The chat picker is **agent-then-model**, not a flat model list. Unavailable agents are disabled/gated.
+- `agents.list` (WS) returns `available` + `npxInstallable` per agent; `agents.models` returns model choices (claude-code -> sonnet/opus/haiku). The chat picker is **agent-then-model**, not a flat model list. Unavailable agents are disabled/gated.
 - `chat.sendMessage` accepts `cwd` (defaults to STARTUP_CWD) and `model`/`agentId` separately. `chat.active` (WS) lists in-flight chats with agentId/model/cwd/startedAt/pid; the history tab polls it (3s) and shows a running panel with per-session stop.
 - Client (`app.js`): chat transcript persists to `localStorage[agentgui.chat]` and restores on load; tool_use/result events render as chat parts; keyboard shortcuts (g+c/h/s, n, /, ?); settings has an agents-status panel from `health.acp[]`.
 
+## Kit Row rail + rank contract
+
+The design-kit `Row` (`anentrypoint-design` `src/components/content.js`) renders a leading status **rail** from a `rail` prop (`green` | `purple` | `flame`, via a `.row.rail-<tone>::before` bar) and accepts `rank` as an alias for the leading `code` index. A `state: 'disabled'` Row is inert — no `onClick`/`role=button`/tab-stop, `aria-disabled=true`. agentgui's history sessions, search results, and agents panel pass `rail` + `rank` and rely on this; the rendering reaches the live GUI only after the kit publishes to npm -> unpkg `@latest`. agentgui keeps the rail semantics consistent everywhere: **green = selected/ok, purple = subagent, flame = error/unavailable**.
+
+## GUI glyph policy
+
+GUI source keeps typographic product characters — the middot separator `·`, the ellipsis `…`, and em/en dashes in prose — as established design (AGENTS.md itself uses `·`). It carries **no** decorative tells: arrows, box-drawing, bullets, status dots, checks. Status is words + the CSS-drawn `.status-dot-disc`. Convert any arrow/box-drawing/bullet glyph to ASCII on sight (`->`, `// --- x ---`, `-`/`*`).
+
 ## DS CSS cascade — overriding component styles (2026-05-28)
 
 **`installStyles()` injects DS CSS into a runtime `<style>` after the head `<style>`, so local overrides need `!important` or higher specificity than the DS's `.ds-247420`-prefixed rules.** Full detail (font vars `--ff-display`/`--ff-mono`, the `.chat-head .sub` "00 msgs" quirk, EventList `.row[role=button]`, `[data-prog-focus]` focus suppression, `projectLabel()` for cwd slugs) is in rs-learn (recall "agentgui GUI styling DS cascade installStyles").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.946",
+  "version": "1.0.947",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "electron/main.js",