agentgui 1.0.948 → 1.0.949

package/.claude/workflows/gui-audit.js

@@ -0,0 +1,86 @@
+export const meta = {
+  name: 'gui-audit',
+  description: 'Sweep every agentgui GUI surface for jank, verify findings adversarially, and emit kit-update tasks',
+  whenToUse: 'Run a maximum-effort GUI audit of agentgui: review chat, history, settings, a11y, security, performance, and glyph hygiene across the client (site/app) and the design kit (c:\\dev\\anentrypoint-design). Fans out one reviewer per surface, verifies each finding with an independent skeptic, then synthesizes a prioritized punch-list. GUI fixes land in the design kit.',
+  phases: [
+    { title: 'Review', detail: 'one reviewer agent per GUI surface/aspect' },
+    { title: 'Verify', detail: 'independent skeptic confirms each finding is real' },
+    { title: 'Synthesize', detail: 'dedupe + prioritize into a punch-list with kit-vs-app split' },
+  ],
+};
+
+// Every GUI surface and cross-cutting aspect the audit must cover. Each becomes
+// one reviewer agent. Add a row to widen coverage; the fan-out scales with it.
+const SURFACES = [
+  { key: 'chat', prompt: 'Audit the agentgui CHAT surface for jank. Read site/app/js/app.js (chatMain, sendChat, toolPart, applyToolResult), site/app/js/backend.js (streamChat), and the kit AgentChat at c:\\dev\\anentrypoint-design/src/components/agent-chat.js + chat.js. Check: tool_use/tool_result render as structured collapsible cards (not flattened text); markdown/text/tool parts interleave in arrival order; empty state; composer stop button while streaming; thinking/working indicator during silent tool runs; aborted-empty turn pruning; multi-turn resume correctness. Report each issue with file:line, why it is jank, and whether the fix is in the kit or the app.' },
+  { key: 'history', prompt: 'Audit the agentgui HISTORY surface (site/app/js/app.js historyMain, historySide, loadSession, EventList usage). Check: event rendering consistency with chat (same event same way), expand/collapse + keyboard activation, the silent 300-event cap with no load-older, search-result click landing on the matched event, live SSE wiring, session list filtering/subagent toggle. Report each issue with file:line and kit-vs-app.' },
+  { key: 'settings', prompt: 'Audit the agentgui SETTINGS surface (site/app/js/app.js settingsMain, agentsPanel, preferencesPanel, saveBackend). Check: ACP agent start/stop/restart/health controls (read-only today), cwd surfacing + server-side validation, backend URL validation, clear-local-data flow, health summary clarity. Report each issue with file:line and kit-vs-app.' },
+  { key: 'a11y', prompt: 'Audit agentgui ACCESSIBILITY across site/app and the kit. Check: skip-link target reachability/focus, tab order on each tab, agent/model select labels, EventList row role=button keyboard activation + expand announcement, aria-live over/under-announcing, color contrast on the dark theme (WCAG AA 4.5:1 text / 3:1 UI), focus-visible rings, reduced-motion. Report each issue with file:line.' },
+  { key: 'security', prompt: 'Audit agentgui GUI-reachable SECURITY. Read lib/http-handler.js. Check: Access-Control-Allow-Origin:* with Authorization + ?token= cross-origin/leak risk; /api/image arbitrary-file-read (the .. check runs after path.normalize); markdown XSS (kit marked+dompurify) — does DOMPurify actually neutralize script/javascript: URLs in agent output. Report each issue with file:line, severity, and the concrete exploit path.' },
+  { key: 'perf', prompt: 'Audit agentgui GUI PERFORMANCE. Check: per-token render+scroll thrash on the chat stream (should be rAF-coalesced via scheduleStreamRender), history EventList rebuild cost on burst SSE loads (last-300 map per rAF), webjsx keying stability, markdown/Prism cache warmup, resize/relTime tick cost. Report each hotspot with file:line and a concrete fix.' },
+  { key: 'glyph', prompt: 'Sweep EVERY GUI source file (site/app/**, c:\\dev\\anentrypoint-design/src/**, *.css) for decorative tell-tale glyphs: arrows, box-drawing, bullets, status dots, checks, emoji, any non-ASCII decorative symbol. KEEP the typographic set (middot, ellipsis, em/en-dash in prose), SVG line-icons via Icon(), CSS-drawn discs, and intentional ascii-art (AICAT_FACE). Report every decorative glyph found with file:line and its ASCII replacement.' },
+  { key: 'responsive', prompt: 'Audit agentgui RESPONSIVE behavior from site/app/index.html media queries + the kit AppShell. Check: chat controls cluster wrap at 360/640/900px, cwd path overflow, history sidebar drawer (open/close/scrim/select-closes-it), touch-target sizes, settings two-column collapse. Report each issue with the breakpoint and file:line.' },
+  { key: 'consistency', prompt: 'Audit agentgui PREDICTABILITY/CONSISTENCY. Check that the same state reads the same way everywhere: connection/activity status vocabulary across crumb dot, chat status, AgentControls status, settings health, agentsPanel; ellipsis convention (… vs ...); rail tone semantics (green=ok/selected, purple=subagent, flame=error); button labels. Report each divergence with file:line.' },
+];
+
+const FINDINGS_SCHEMA = {
+  type: 'object',
+  required: ['surface', 'findings'],
+  properties: {
+    surface: { type: 'string' },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['title', 'where', 'why', 'fixLocation'],
+        properties: {
+          title: { type: 'string' },
+          where: { type: 'string', description: 'file:line' },
+          why: { type: 'string' },
+          fixLocation: { type: 'string', enum: ['kit', 'app', 'server', 'both'] },
+          severity: { type: 'string', enum: ['low', 'medium', 'high'] },
+        },
+      },
+    },
+  },
+};
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  required: ['isReal', 'reason'],
+  properties: {
+    isReal: { type: 'boolean' },
+    reason: { type: 'string' },
+    correctedFix: { type: 'string' },
+  },
+};
+
+phase('Review');
+
+// Pipeline: each surface is reviewed, then every finding it produced is
+// independently verified — a surface's findings start verifying the moment that
+// surface's review returns, without waiting for slower surfaces.
+const reviewed = await pipeline(
+  SURFACES,
+  (s) => agent(s.prompt, { label: 'review:' + s.key, phase: 'Review', schema: FINDINGS_SCHEMA }),
+  (review, surface) =>
+    parallel((review.findings || []).map((f) => () =>
+      agent(
+        'Adversarially verify this GUI audit finding. Default to isReal=false if you cannot confirm it from the actual source. Finding: "' + f.title + '" at ' + f.where + ' — ' + f.why,
+        { label: 'verify:' + surface.key, phase: 'Verify', schema: VERDICT_SCHEMA }
+      ).then((v) => ({ ...f, surface: surface.key, verdict: v }))
+    ))
+);
+
+const confirmed = reviewed.flat().filter(Boolean).filter((f) => f.verdict && f.verdict.isReal);
+log(confirmed.length + ' confirmed findings across ' + SURFACES.length + ' surfaces');
+
+phase('Synthesize');
+
+const punchList = await agent(
+  'Synthesize these confirmed agentgui GUI audit findings into a prioritized punch-list. Group by fixLocation (kit vs app vs server), order by severity then user impact, dedupe overlaps, and for each give a one-line concrete remedy. Findings JSON:\n' +
+    JSON.stringify(confirmed, null, 2),
+  { label: 'synthesize', phase: 'Synthesize' }
+);
+
+return { confirmedCount: confirmed.length, confirmed, punchList };

package/AGENTS.md

@@ -6,7 +6,7 @@ One surface. `server.js` serves `site/app/` under `BASE_URL` (default `/gm`) and
 
 When `PASSWORD` env var is set, every HTTP route is gated by `lib/http-handler.js` accepting **Basic auth**, **`Authorization: Bearer <pwd>`**, OR **`?token=<pwd>`** query param (added 2026-05-26 so `EventSource` and direct deep-links work — neither can set headers). WS `/sync` requires `?token=` only. The HTML head script injects `window.__BASE_URL`, `window.__SERVER_VERSION`, and `window.__WS_TOKEN`; `site/app/js/backend.js` reads `__WS_TOKEN` and threads it onto every fetch (Bearer header) / EventSource (qs) / WebSocket (qs).
 
-- `site/app/index.html` — shell + CSS; imports `anentrypoint-design` from `https://unpkg.com/anentrypoint-design@latest` at runtime (always-latest; requires network — the prior offline guarantee is intentionally dropped)
+- `site/app/index.html` — shell + CSS; imports `anentrypoint-design` from the **local vendored copy** `./vendor/anentrypoint-design/247420.{js,css}` (re-vendored 2026-06-04 for a PREDICTABLE shipped UI that does not shift when upstream publishes, and offline operation — the markdown stack marked/dompurify/prismjs still fetches from jsdelivr on first chat render). Update flow: edit the kit at `c:\dev\anentrypoint-design`, `node scripts/build.mjs`, copy `dist/247420.{js,css}` into `site/app/vendor/anentrypoint-design/`, then publish the kit so unpkg stays in sync.
 - `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`
 
@@ -18,6 +18,20 @@ Dependencies:
 - `ccsniff` (>=1.1.0) — exports `createHistoryRouter({projectsDir})` mountable on Express; serves `/v1/history/{sessions,sessions/:sid/events,search,snapshot,reindex,stream}`. Reads `~/.claude/projects` (override via `CLAUDE_PROJECTS_DIR`).
 - `anentrypoint-design` (>=0.0.119) — kit library, single-file ESM from unpkg
 
+## GUI audit pass (2026-06-04) — structured chat, predictable presentation
+
+A maximum-effort GUI sweep landed these, GUI changes in the kit `c:\dev\anentrypoint-design` (built+vendored locally), correctness/security in agentgui:
+
+- **Structured tool cards in chat.** `app.js sendChat` now emits structured parts — `toolPart()` builds `{kind:'tool',name,label,args,status,_id}` and `applyToolResult()` matches a `tool_result` back to its `tool_use` by id (sets `result`+done/error status). The kit `AgentChat` passes structured `{kind,...}` parts straight through to `ChatMessage.renderPart` (only bare strings are wrapped as text), so the kit's collapsible `ToolCallNode` (args/result sections, status icons) renders instead of the old flattened `'-> '+text`. Full args/result live in the card (no 120/160-char truncation).
+- **AgentChat kit additions** (`src/components/agent-chat.js`): empty state (`.agentchat-empty*`, title/sub/`suggestions`+`onSuggestionClick`), composer stop button while streaming (`busy`+`onCancel:onStop` into `ChatComposer`), a `working…` tail (`.agentchat-working`) when a content-bearing turn is still streaming (silent tool runs no longer read as frozen). CSS in `chat.css`.
+- **Streaming render is rAF-coalesced** via `scheduleStreamRender()` (was render+scroll per token).
+- **Multi-turn resume wired end-to-end.** Server `chat.sendMessage` is one-shot (new ephemeral `chat-` id per call); claude's real session id is `parsed.session_id` in the stream. `ws-handlers-util.js onEvent` now broadcasts `streaming_session{claudeSessionId}` once; `backend.js` yields `{type:'session'}`; `app.js` captures it into `state.chat.resumeSid` (claude-code only) + persists, so the next turn `--resume`s.
+- **Skip link works.** Kit `AppShell` `<main id=app-main>` now has `tabindex=-1` so the skip-link moves focus, not just scrolls.
+- **History:** `state.eventsLimit` (default 300, reset per session) + `load N older` control (no more silently-unreachable older events); expand-all/collapse-all; per-event rail tone (green=normal, purple=tool_use, flame=error) matching the GUI-wide rail semantics; search hits carry `{focusEventI,focusEventTs}` so a click scrolls to + flashes (`.event-flash`) the matched event; mobile drawer auto-closes on session select (`loadSession` removes `.side-open` since DS only auto-closes on `<a>` clicks).
+- **Security** (`lib/http-handler.js`): `/api/image` confined to an allowlist root (`CLAUDE_PROJECTS_DIR`, home, `IMAGE_ROOTS`) — was arbitrary-file-read (the `..` check was a no-op after `path.normalize`); CORS no longer advertises `Access-Control-Allow-Origin:*` when `PASSWORD` is set (reflects `CORS_ORIGIN` if set, else same-origin only). Markdown XSS verified inert (DOMPurify strips script/onerror/`javascript:`).
+- **Consistency:** unified ellipsis to `…` (kept set); settings health chip uses connection vocab (`connected/connecting/offline`) matching the crumb dot; running-chats panel now shows on chat tab too (extracted `runningPanel()`); aborted-empty turns pruned from persisted/restored chat; restored transcript reopens under its own agent (`restoredAgent`).
+- **Workflow:** `.claude/workflows/gui-audit.js` — a reusable multi-agent GUI-audit workflow (per-surface reviewers -> adversarial verify -> synthesize, kit-vs-app fixLocation).
+
 ## Orchestration agents
 
 The four flagship agents the GUI drives are **Claude Code, OpenCode, Kilo, and Antigravity (`agy`)**; the agent picker (`site/app/js/app.js`, `PRIMARY_AGENTS`) sorts these first, then other-available, then npx-installable, then not-installed.

package/lib/http-handler.js

@@ -6,7 +6,19 @@ import * as term from './terminal.js';
 
 export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, serveFile, staticDir, messageQueues, getWss, activeExecutions, getACPStatus, discoveredAgents, PKG_VERSION, RATE_LIMIT_MAX, rateLimitMap, routes, PORT }) {
   return async function httpHandler(req, res) {
-    res.setHeader('Access-Control-Allow-Origin', '*');
+    // CORS: when PASSWORD is set the server holds credentials a cross-origin
+    // page must not be able to spend, so we do NOT advertise a wildcard origin
+    // (a wildcard + a leaked Bearer/token would let any site the user visits
+    // drive this server). Reflect an explicitly-allowed origin (CORS_ORIGIN)
+    // when configured, else same-origin only. With no PASSWORD the server is
+    // already open, so the permissive wildcard is harmless and kept for tools.
+    const _corsOrigin = process.env.CORS_ORIGIN;
+    if (_corsOrigin) {
+      res.setHeader('Access-Control-Allow-Origin', _corsOrigin);
+      res.setHeader('Vary', 'Origin');
+    } else if (!process.env.PASSWORD) {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+    } // else: no ACAO header -> browsers block cross-origin reads (same-origin still works)
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
     if (req.method === 'OPTIONS') { res.writeHead(200); res.end(); return; }
@@ -124,7 +136,22 @@ export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, ser
         const normalizedPath = path.normalize(expandedPath);
         const isWindows = os.platform() === 'win32';
         const isAbsolute = isWindows ? /^[A-Za-z]:[\\\/]/.test(normalizedPath) : normalizedPath.startsWith('/');
-        if (!isAbsolute || normalizedPath.includes('..')) { res.writeHead(403); res.end('Forbidden'); return; }
+        // Confine reads to an allowlist root. Without this the route is an
+        // arbitrary-file-read of any image-extensioned path on the host (the
+        // prior `includes('..')` guard is a no-op after path.normalize resolves
+        // the segments). Allowed roots: the Claude projects dir (history images)
+        // and the user home; override/add via IMAGE_ROOTS (path-separated).
+        const allowRoots = [
+          process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects'),
+          os.homedir(),
+          ...(process.env.IMAGE_ROOTS ? process.env.IMAGE_ROOTS.split(path.delimiter) : []),
+        ].map(r => path.normalize(r));
+        const norm = isWindows ? normalizedPath.toLowerCase() : normalizedPath;
+        const withinAllowed = allowRoots.some(root => {
+          const r = isWindows ? root.toLowerCase() : root;
+          return norm === r || norm.startsWith(r + path.sep);
+        });
+        if (!isAbsolute || !withinAllowed) { res.writeHead(403); res.end('Forbidden'); return; }
         try {
           if (!fs.existsSync(normalizedPath)) { res.writeHead(404); res.end('Not found'); return; }
           const ext = path.extname(normalizedPath).toLowerCase();

package/lib/ws-handlers-util.js

@@ -85,8 +85,17 @@ export function register(router, deps) {
     (async () => {
       let eventCount = 0;
       broadcastSync({ type: 'streaming_start', sessionId, agentId, timestamp: Date.now() });
+      let claudeSessionBroadcast = false;
       const onEvent = (parsed) => {
         eventCount++;
+        // Surface claude's REAL session id (from the stream) once, so the client
+        // can --resume this conversation on its next turn. The ephemeral
+        // 'chat-...' sessionId is not a claude session id and cannot be resumed.
+        if (!claudeSessionBroadcast && parsed?.session_id) {
+          claudeSessionBroadcast = true;
+          ctrl.claudeSessionId = parsed.session_id;
+          broadcastSync({ type: 'streaming_session', sessionId, claudeSessionId: parsed.session_id, agentId, timestamp: Date.now() });
+        }
         if (parsed?.type === 'assistant' && parsed.message?.content) {
           for (const block of parsed.message.content) {
             broadcastSync({ type: 'streaming_progress', sessionId, block, blockRole: 'assistant', seq: eventCount, timestamp: Date.now() });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.948",
+  "version": "1.0.949",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "electron/main.js",
@@ -43,7 +43,7 @@
     "webjsx": "^0.0.73",
     "webtalk": "^1.0.31",
     "ws": "^8.14.2",
-    "xstate": "^5.28.0",
+    "xstate": "^5.32.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/site/app/index.html

@@ -5,15 +5,16 @@
   <meta name="viewport" content="width=device-width,initial-scale=1">
   <title>agentgui</title>
   <meta name="description" content="agentgui - multi-agent client with same-origin server, in-process ccsniff history, and ACP chat.">
-  <!-- The GUI lives in the anentrypoint-design kit and is loaded from unpkg at
-       its latest published version, so agentgui always tracks the kit without a
-       hand-maintained vendored copy. (This trades the prior offline guarantee for
-       always-latest, per project decision; a network connection is required.)
-       NOTE: re-vendoring 0.0.186+ locally (it adds the load-bearing AgentChat
-       component) would restore offline + predictability -- tracked in AGENTS.md. -->
-  <link rel="stylesheet" href="https://unpkg.com/anentrypoint-design@latest/dist/247420.css">
+  <!-- The GUI lives in the anentrypoint-design kit and is vendored locally under
+       ./vendor/anentrypoint-design so the shipped UI is PREDICTABLE: it does not
+       silently shift when the upstream package publishes, and it works offline
+       (the markdown stack still fetches marked/dompurify/prismjs on first chat
+       render). Update flow: edit the kit at c:\dev\anentrypoint-design, run
+       `node scripts/build.mjs`, copy dist/247420.{js,css} here, then publish the
+       kit so unpkg stays in sync. -->
+  <link rel="stylesheet" href="./vendor/anentrypoint-design/247420.css">
   <script type="importmap">
-    { "imports": { "anentrypoint-design": "https://unpkg.com/anentrypoint-design@latest/dist/247420.js" } }
+    { "imports": { "anentrypoint-design": "./vendor/anentrypoint-design/247420.js" } }
   </script>
   <style>
     :root {
@@ -72,14 +73,8 @@
     .ds-247420 [data-prog-focus]:focus-visible,
     [data-prog-focus]:focus, [data-prog-focus]:focus-visible { outline: none !important; box-shadow: none !important; }
 
-    /* skip link for keyboard/AT users */
-    .skip-link {
-      position: absolute; left: -9999px; top: 0; z-index: 1000;
-      padding: .5em .9em; border-radius: 6px;
-      background: var(--accent, var(--agentgui-accent)); color: #06120a;
-      text-decoration: none; font-weight: 600;
-    }
-    .skip-link:focus { left: 8px; top: 8px; outline: 2px solid #fff; outline-offset: 2px; }
+    /* (The skip link is rendered + styled by the design system's AppShell;
+       agentgui carries no local .skip-link rule.) */
 
     /* status connection dot - a CSS-drawn disc (real UI affordance, not a text
        glyph). The .status-dot-disc child is always present; the parent's state
@@ -260,6 +255,15 @@
        them a pointer cursor, so the affordance is invisible. */
     .ds-event-list .row[role="button"] { cursor: pointer; }
     .ds-event-list .row[role="button"]:hover { background: color-mix(in srgb, var(--fg, var(--agentgui-fg)) 5%, transparent); }
+    /* Flash the row a search result landed on, so the match is obvious. */
+    .ds-event-list .row.event-flash { animation: agentgui-event-flash 2s ease-out; }
+    @keyframes agentgui-event-flash {
+      0%   { background: color-mix(in srgb, var(--accent, var(--agentgui-accent)) 40%, transparent); }
+      100% { background: transparent; }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      .ds-event-list .row.event-flash { animation: none; outline: 2px solid var(--accent, var(--agentgui-accent)); }
+    }
 
     /* Chat composer: hide the idle scrollbar on the (empty/short) textarea. */
     .chat-composer textarea { overflow-y: auto; scrollbar-width: thin; }