agentgui 1.0.944 → 1.0.946

package/AGENTS.md

@@ -6,9 +6,11 @@ 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 unpkg
-- `site/app/js/backend.js` — same-origin client (`DEFAULT_BACKEND = ''`); `?backend=` query override for cross-origin debugging
-- `site/app/js/app.js` — webjsx view + state, kits-only rendering (PageHeader, SearchInput, TextField, EventList, Panel, Row, Section); exposes `window.__agentgui`
+- `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/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.
 - `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
 
@@ -145,9 +147,9 @@ Throttle renders via `requestAnimationFrame` to avoid event storm during burst l
 
 The endpoints are served by ccsniff's Express router mounted in-process from `server.js`. No external proxy.
 
-## Zero-runtime-CDN: vendored DS deps (2026-05-28)
+## Runtime CDN: GUI loaded from unpkg (2026-05-29)
 
-The GUI runs fully offline. `site/app/vendor/cdn/` holds marked, dompurify, prismjs components, and JetBrains+Space Grotesk woff2. The DS bundle (`anentrypoint-design/247420.js`) had its CDN string constants rewritten to local paths, AND its gzip+base64-embedded CSS blob (`Ha`) regenerated to point at local fonts. Full mechanism is in rs-learn (recall "DS bundle gzip Ha vendoring"). Witness offline by browser route-abort of non-origin hosts.
+The GUI loads `anentrypoint-design` from `https://unpkg.com/anentrypoint-design@latest` at runtime (import map + CSS link in `index.html`) so agentgui always tracks the latest published kit with no hand-maintained vendored copy. This **requires a network connection** — the earlier offline guarantee was intentionally dropped in favour of always-latest. The DS itself fetches its fonts from `unpkg.com/anentrypoint-design@latest/dist/fonts/` (set in the kit's `scripts/build.mjs` `FONT_BASE`). The `site/app/vendor/` tree is no longer imported; the old vendored DS bundle + `vendor/cdn/` assets are dead and may be removed. Witness the live GUI by confirming the import map resolves to unpkg and `.agentchat` renders with 0 console errors.
 
 ## Agent/model/session management (2026-05-28)
 

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [Unreleased] - GUI moved into the anentrypoint-design kit, loaded from unpkg
+
+- the chat GUI now lives in the design kit: added a reusable `AgentChat` component to anentrypoint-design (agent-then-model picker + AICat auto-scroll/thinking + tool parts + cwd bar + caret-stable composer), pure props-in/vnode-out with all transport as host callbacks. Published via the kit's CI to npm -> unpkg.
+- site/app/index.html: imports anentrypoint-design from https://unpkg.com/anentrypoint-design@latest at runtime (always-latest), replacing the vendored bundle. Trades the offline guarantee for always-latest, per project decision.
+- site/app/js/app.js: chatMain renders the AgentChat kit and wires agentgui state + WS/ccsniff glue as callbacks; the agent/model picker, cwd bar, and composer moved out of agentgui into the kit. backend.js (WS client) stays as the transport glue.
+- verified end-to-end in a real browser: GUI sourced from unpkg, AgentChat renders, chat round-trips (reply streams into the kit's transcript), 0 console errors.
+
 ## [Unreleased] - live e2e chat verified + composer caret fix + ccsniff memory cap
 
 - verified the full GUI chat round-trip end-to-end in a real browser: compose -> WS chat.sendMessage -> claude-code -> streaming_progress -> transcript renders the streamed reply (not just the runner harness).

package/package.json

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

package/site/app/index.html

@@ -5,9 +5,13 @@
   <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.">
-  <link rel="stylesheet" href="vendor/anentrypoint-design/247420.css">
+  <!-- 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.) -->
+  <link rel="stylesheet" href="https://unpkg.com/anentrypoint-design@latest/dist/247420.css">
   <script type="importmap">
-    { "imports": { "anentrypoint-design": "./vendor/anentrypoint-design/247420.js" } }
+    { "imports": { "anentrypoint-design": "https://unpkg.com/anentrypoint-design@latest/dist/247420.js" } }
   </script>
   <style>
     :root {
@@ -15,6 +19,18 @@
       --agentgui-fg: #e6e6ea;
       --agentgui-accent: #50c878;
       --agentgui-warn: #ff6b6b;
+      /* status-dot state colours, brightened for >=3:1 contrast on the dark bg */
+      --agentgui-status-connecting: #f0b84a;
+      --agentgui-status-offline: #e06b66;
+      /* unified muted text fallback (was an inconsistent mix of #888/#999) */
+      --agentgui-muted: #8a8f98;
+    }
+
+    /* visually-hidden but screen-reader-available (aria-live announcer, labels) */
+    .sr-only {
+      position: absolute !important; width: 1px; height: 1px;
+      padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0);
+      white-space: nowrap; border: 0;
     }
     html, body {
       margin: 0;
@@ -76,8 +92,8 @@
       background: var(--accent, var(--agentgui-accent, #50c878));
       animation: agentgui-pulse 2s infinite;
     }
-    .status-dot.is-connecting .status-dot-disc { background: #d9a441; }
-    .status-dot.is-offline .status-dot-disc { background: #c0504d; animation: none; }
+    .status-dot.is-connecting .status-dot-disc { background: var(--agentgui-status-connecting); }
+    .status-dot.is-offline .status-dot-disc { background: var(--agentgui-status-offline); animation: none; }
     @keyframes agentgui-pulse {
       0%   { box-shadow: 0 0 0 0 rgba(80, 200, 120, .5); }
       70%  { box-shadow: 0 0 0 6px rgba(80, 200, 120, 0); }
@@ -155,7 +171,7 @@
 
     /* empty-state: keep it from wrapping awkwardly in the narrow sidebar */
     .empty-state { white-space: normal; }
-    p.empty-state { text-align: left; padding: .6em 0; color: var(--fg-3, #888); }
+    p.empty-state { text-align: left; padding: .6em 0; color: var(--fg-3, var(--agentgui-muted)); }
 
     /* generic interactive focus ring */
     button:focus-visible, [tabindex]:focus-visible, a:focus-visible {
@@ -194,7 +210,7 @@
     }
     .cwd-bar-text {
       font-family: var(--ff-mono, ui-monospace, monospace);
-      color: var(--fg-3, #999); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 60vw;
+      color: var(--fg-3, var(--agentgui-muted)); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 60vw;
     }
     .cwd-bar-btn {
       cursor: pointer; font: inherit; line-height: 1.3;
@@ -209,9 +225,8 @@
     /* History no-session empty state: fill the void with a centered prompt. */
     .history-empty {
       display: flex; flex-direction: column; align-items: center; justify-content: center;
-      gap: .4em; text-align: center; min-height: 50vh; color: var(--fg-3, #888);
+      gap: .4em; text-align: center; min-height: 50vh; color: var(--fg-3, var(--agentgui-muted));
     }
-    .history-empty-glyph { font-size: 3rem; opacity: .25; line-height: 1; }
     .history-empty-title { margin: 0; font-size: 1.05rem; color: var(--fg-2, var(--agentgui-fg)); }
     .history-empty-sub { margin: 0; max-width: 42ch; }
 
@@ -248,10 +263,21 @@
     .chat-composer textarea { overflow-y: auto; scrollbar-width: thin; }
     .chat-composer textarea:not(:focus) { overflow-y: hidden; }
 
+    /* tablet: keep the chat control cluster from wrapping the status dot alone */
+    @media (max-width: 900px) {
+      .chat-controls select,
+      .chat-controls .select,
+      .chat-controls [role="combobox"] { min-width: 110px; max-width: 170px; }
+    }
+
     /* touch targets on small screens */
     @media (max-width: 640px) {
       .pill { min-height: 36px; padding: .4em .8em; }
+      .history-actions { gap: .75em; }
       .history-actions .btn, .history-actions button { min-height: 44px; }
+      /* cwd path can't eat the whole row beside its label + buttons on a phone */
+      .cwd-bar-text { max-width: 42vw; }
+      .cwd-bar { gap: .3em; }
     }
 
     @media print {
@@ -266,7 +292,6 @@
   </style>
 </head>
 <body>
-  <a href="#agentgui-main" class="skip-link">Skip to main content</a>
   <div id="app"></div>
   <script type="module" src="./js/app.js"></script>
 </body>

package/site/app/js/app.js

@@ -3,7 +3,7 @@ import * as B from './backend.js';
 
 installStyles().catch(() => {});
 
-const { AppShell, Topbar, Crumb, Side, Status, Chat, ChatComposer, Row, Panel, PageHeader, SearchInput, TextField, Select, Btn, EventList, Spinner, Alert } = C;
+const { AppShell, Topbar, Crumb, Side, Status, Chat, ChatComposer, AgentChat, Row, Panel, PageHeader, SearchInput, TextField, Select, Btn, EventList, Spinner, Alert } = C;
 
 const state = {
   backend: B.getBackend(),
@@ -85,6 +85,24 @@ function debounce(fn, ms) {
 function lsSet(k, v) { try { localStorage.setItem(k, v); } catch {} }
 function lsRemove(k) { try { localStorage.removeItem(k); } catch {} }
 
+// A single visually-hidden aria-live region for transient announcements (tab
+// changes, etc.) so screen-reader users hear context that's otherwise conveyed
+// only by focus movement or color.
+let _announcer = null;
+function announce(msg) {
+  if (typeof document === 'undefined') return;
+  if (!_announcer) {
+    _announcer = document.createElement('div');
+    _announcer.setAttribute('aria-live', 'polite');
+    _announcer.setAttribute('role', 'status');
+    _announcer.className = 'sr-only';
+    document.body.appendChild(_announcer);
+  }
+  // Clear then set on the next frame so repeated identical messages re-announce.
+  _announcer.textContent = '';
+  requestAnimationFrame(() => { if (_announcer) _announcer.textContent = msg; });
+}
+
 function pillButton(key, label, active, title, onClick) {
   return h('button', {
     key,
@@ -113,15 +131,22 @@ function timeNow() {
 }
 
 async function selectAgent(id) {
+  // Re-selecting the same agent would needlessly refetch models and reset the
+  // current model selection — no-op early.
+  if (id === state.selectedAgent && state.agentModels.length) return;
   state.selectedAgent = id;
   localStorage.setItem('agentgui.agent', id);
   state.agentModels = [];
   state.selectedModel = '';
+  state.modelsLoading = true;
   render();
   const models = await B.listAgentModels(state.backend, id);
   if (state.selectedAgent !== id) return; // changed while loading
+  state.modelsLoading = false;
   state.agentModels = models;
   const saved = localStorage.getItem('agentgui.model');
+  // Only restore a saved model that the NEW agent actually offers; otherwise
+  // fall back to its first model (never carry a stale model from a prior agent).
   state.selectedModel = (saved && models.some(m => m.id === saved)) ? saved : (models[0]?.id || '');
   render();
 }
@@ -135,8 +160,32 @@ function selectModel(id) {
 function agentById(id) { return state.agents.find(a => a.id === id); }
 function agentAvailable(id) { const a = agentById(id); return !a || a.available !== false; }
 
+// The four flagship orchestration targets surface first, then other available
+// agents, then npx-installable, then not-installed — so the agents the GUI
+// exists to drive are reachable without scanning a flat 17-item list. This
+// ordering is agentgui's orchestration priority, so it stays in the host and is
+// passed pre-sorted to the (app-agnostic) AgentChat kit.
+const PRIMARY_AGENTS = ['claude-code', 'opencode', 'kilo', 'agy'];
+function sortedAgents() {
+  const rank = (a) => {
+    const primary = PRIMARY_AGENTS.indexOf(a.id);
+    const avail = a.available !== false;
+    if (primary !== -1 && avail) return primary;
+    if (avail) return 10;
+    if (a.npxInstallable) return 20;
+    return 30;
+  };
+  return state.agents
+    .map(a => ({ a, rank: rank(a) }))
+    .sort((x, y) => x.rank - y.rank || x.a.name.localeCompare(y.a.name))
+    .map(({ a }) => a);
+}
+
 function navTo(tab) {
   const prev = state.tab;
+  // Leaving chat clears any pending new-chat confirmation so it doesn't linger
+  // as a stale banner when the user returns.
+  if (prev === 'chat' && tab !== 'chat') state.confirmingNewChat = false;
   state.tab = tab;
   // Live history SSE is only needed on the history tab; active-chat polling
   // runs globally (started at boot) so running chats show on every tab.
@@ -147,6 +196,7 @@ function navTo(tab) {
     closeLiveStream();
   }
   writeHash(state.selectedSid && tab === 'history' ? state.selectedSid : null);
+  announce('Now on ' + tab + ' tab');
   render();
   // Move focus into the new region for keyboard/AT users.
   requestAnimationFrame(() => {
@@ -166,7 +216,7 @@ function navTo(tab) {
   });
 }
 
-// The DS Topbar derives aria-current from href↔location.hash matching, which
+// The DS Topbar derives aria-current from href<->location.hash matching, which
 // drifts from our hash-based active tab (e.g. aria-current lands on "settings"
 // while we're on "chat"). Re-assert aria-current on the actually-active tab.
 function syncAriaCurrent() {
@@ -287,61 +337,26 @@ function view() {
     onNav: (label) => navTo(label),
   });
 
-  // The four flagship orchestration targets surface first, then the rest of the
-  // available agents, then unavailable ones — so the agents the GUI exists to
-  // drive are reachable without scanning a flat 17-item list. Ordering only;
-  // the DS Select renders a plain option list.
-  const PRIMARY_AGENTS = ['claude-code', 'opencode', 'kilo', 'agy'];
-  const agentRank = (a) => {
-    const primary = PRIMARY_AGENTS.indexOf(a.id);
-    const avail = a.available !== false;
-    if (primary !== -1 && avail) return primary;           // 0..3 flagship + available
-    if (avail) return 10;                                   // other available
-    if (a.npxInstallable) return 20;                        // installable via npx
-    return 30;                                              // not installed
-  };
-  const agentOptions = state.agents
-    .map(a => ({ a, rank: agentRank(a) }))
-    .sort((x, y) => x.rank - y.rank || x.a.name.localeCompare(y.a.name))
-    .map(({ a }) => ({
-      value: a.id,
-      label: a.name + (a.available === false ? (a.npxInstallable ? ' (via npx)' : ' (not installed)') : ''),
-      disabled: a.available === false && !a.npxInstallable,
-    }));
-  const showModelPicker = state.tab === 'chat' && state.agentModels.length > 0;
-
-  const crumbRight = state.tab === 'chat'
-    ? [h('div', { key: 'cc', class: 'chat-controls' },
-        Select({
-          key: 'agentsel',
-          value: state.selectedAgent,
-          placeholder: '— agent —',
-          title: 'Select coding agent',
-          options: agentOptions,
-          onChange: (v) => { selectAgent(v); },
-        }),
-        showModelPicker
-          ? Select({
-              key: 'modelsel',
-              value: state.selectedModel,
-              placeholder: '— model —',
-              title: 'Select model for this agent',
-              options: state.agentModels.map(m => ({ value: m.id, label: m.name || m.id })),
-              onChange: (v) => { selectModel(v); },
-            })
-          : null,
-        state.chat.busy
-          ? Btn({ key: 'stop', onClick: cancelChat, children: 'stop', title: 'Stop streaming' })
-          : Btn({ key: 'new',  onClick: newChat,    children: '+ new', title: 'Start new chat (clears history)' }),
-        dot,
-      )]
-    : [dot];
-
-  // Topbar already shows "agentgui / <tab>"; the crumb is reserved for contextual
-  // controls (model picker, new/stop, live status) so it doesn't duplicate the path.
+  // The crumb's right slot carries the live/connection status dot on every tab.
+  const crumbRight = [dot];
+
+  // Give the crumb contextual content on the left so it isn't a bare bar holding
+  // only the dot: on history it names the selected session (or "all sessions"),
+  // on chat it names the active agent, on settings it's "configuration".
+  let crumbLeaf = '';
+  if (state.tab === 'history') {
+    const sel = state.selectedSid && (Array.isArray(state.sessions) ? state.sessions : []).find(s => s.sid === state.selectedSid);
+    crumbLeaf = state.selectedSid
+      ? truncate(projectLabel(sel?.title) || projectLabel(sel?.project) || state.selectedSid, 24, 48)
+      : 'all sessions';
+  } else if (state.tab === 'chat') {
+    crumbLeaf = state.selectedAgent ? (agentById(state.selectedAgent)?.name || state.selectedAgent) : 'no agent';
+  } else if (state.tab === 'settings') {
+    crumbLeaf = 'configuration';
+  }
   const crumb = Crumb({
     trail: [],
-    leaf: '',
+    leaf: crumbLeaf,
     right: crumbRight,
   });
 
@@ -354,7 +369,7 @@ function view() {
     : 'no agent';
   const status = Status({
     left: [state.backend || 'same-origin', ok ? 'live' : 'offline'],
-    right: [agentLabel],
+    right: [agentLabel, 'press ? for shortcuts'],
   });
 
   // The design system now owns the full-height column + inner scroll for
@@ -367,7 +382,10 @@ function view() {
         children: 'g then c/h/s — chat/history/settings · n — new chat · / — focus search/composer · ? — toggle this · Esc — blur field' })
     : null;
   const main = h('div', { id: 'agentgui-main', role: 'main', 'data-chat-scroll': '', class: 'agentgui-main agentgui-main-' + state.tab, style: mainStyle }, [shortcutsHint, ...mainContent()].filter(Boolean));
-  return AppShell({ topbar, crumb, side, main, status, narrow: false });
+  // narrow drives the DS main-column class; the history sidebar itself collapses
+  // behind the DS .app-side-toggle hamburger (provided by AppShell when a side
+  // exists), so mobile users get a togglable session list.
+  return AppShell({ topbar, crumb, side, main, status, narrow: isNarrow() });
 }
 
 function mainContent() {
@@ -376,7 +394,7 @@ function mainContent() {
   return settingsMain();
 }
 
-// ── chat ───────────────────────────────────────────────────────────────────
+// --- chat ---
 function canSend() {
   return !!state.selectedAgent && agentAvailable(state.selectedAgent) && !state.chat.busy;
 }
@@ -407,56 +425,21 @@ function errText(e) {
 }
 
 function chatMain() {
-  const lastIdx = state.chat.messages.length - 1;
   const agentName = agentById(state.selectedAgent)?.name || state.selectedAgent || 'agent';
-  const msgs = state.chat.messages.map((m, i) => {
-    const isAssistant = m.role === 'assistant';
-    const isStreaming = state.chat.busy && i === lastIdx && isAssistant;
-    const hasParts = Array.isArray(m.parts) && m.parts.length > 0;
-    const isEmptyStreaming = isStreaming && !m.content && !hasParts;
-    const parts = [];
-    if (m.content) parts.push({ kind: isAssistant ? 'md' : 'text', text: m.content });
-    if (hasParts) for (const p of m.parts) parts.push({ kind: 'text', text: p });
-    return {
-      key: m.id || String(i),
-      who: isAssistant ? 'them' : 'you',
-      name: isAssistant ? agentName : 'you',
-      time: m.time || '',
-      typing: isEmptyStreaming,
-      parts: isEmptyStreaming ? undefined : (parts.length ? parts : [{ kind: 'text', text: '' }]),
-    };
-  });
-
-  const placeholder = !state.selectedAgent
-    ? 'choose an agent first'
-    : (!agentAvailable(state.selectedAgent) ? agentName + ' is not installed' : 'message…');
-  const composer = ChatComposer({
-    value: state.chat.draft,
-    disabled: !canSend(),
-    placeholder,
-    // The DS textarea is controlled and reads its live DOM value on send, so we
-    // do NOT re-render on every keystroke (that fights the cursor and is wasteful).
-    // Re-render only when the draft crosses empty<->non-empty, since that is the
-    // only transition that changes the send button's disabled state.
-    onInput: (v) => {
-      const was = !!(state.chat.draft && state.chat.draft.trim());
-      const now = !!(v && v.trim());
-      state.chat.draft = v;
-      if (was !== now) render();
-    },
-    onSend: (v) => { state.chat.draft = v; sendChat(); },
-  });
 
+  // Banners agentgui owns (resume, agent-switched, unavailable, confirm-clear,
+  // stream error) are pre-built here and handed to the kit, which renders them
+  // above the thread. The kit holds no agentgui-specific banner logic.
   const banners = [];
   if (state.chat.resumeSid) {
+    // The agent-switched note (if any) lives inside the resume banner rather
+    // than as a separate stacked Alert, so resume context reads as one block.
     banners.push(h('div', { key: 'rb', class: 'resume-banner', role: 'status' },
-      h('span', { key: 'rbtxt', class: 'lede' }, 'resuming session ' + state.chat.resumeSid.slice(0, 8) + '… via --resume'),
+      h('span', { key: 'rbtxt', class: 'lede' },
+        'resuming session ' + state.chat.resumeSid.slice(0, 8) + '… via --resume'
+        + (state.chat.resumeNote ? ' — ' + state.chat.resumeNote : '')),
       Btn({ key: 'rclr', onClick: () => { state.chat.resumeSid = null; state.chat.resumeNote = null; render(); }, children: 'clear' })));
-    if (state.chat.resumeNote) {
-      banners.push(Alert({ key: 'rnote', kind: 'info', title: 'Agent switched', children: state.chat.resumeNote }));
-    }
   }
-  banners.push(cwdBanner());
   if (state.selectedAgent && !agentAvailable(state.selectedAgent)) {
     banners.push(Alert({ key: 'unavail', kind: 'warn', title: agentName + ' is not installed',
       children: 'This agent\'s CLI was not found on the server. Pick another agent or install it.' }));
@@ -468,26 +451,79 @@ function chatMain() {
         Btn({ key: 'cnyes', danger: true, onClick: newChat, children: 'clear' }),
         Btn({ key: 'cnno', onClick: () => { state.confirmingNewChat = false; render(); }, children: 'cancel' })] }));
   }
-  // Last stream error surfaced as a proper Alert instead of raw JSON in the bubble.
-  const lastErr = state.chat.messages.length ? state.chat.messages[state.chat.messages.length - 1].error : null;
+  if (state.cwdError) {
+    banners.push(Alert({ key: 'cwderr', kind: 'warn', title: 'Invalid working directory', children: state.cwdError }));
+  }
+  const lastMsg = state.chat.messages.length ? state.chat.messages[state.chat.messages.length - 1] : null;
+  const lastErr = lastMsg ? lastMsg.error : null;
   if (lastErr && !state.chat.busy) {
-    banners.push(Alert({ key: 'chaterr', kind: 'error', title: 'Stream error', children: lastErr }));
+    banners.push(Alert({ key: 'chaterr', kind: 'error', title: 'Stream error',
+      children: [
+        h('span', { key: 'cetxt' }, lastErr + ' '),
+        Btn({ key: 'cedismiss', onClick: () => { if (lastMsg) { delete lastMsg.error; persistChat(); render(); } }, children: 'dismiss' })] }));
   }
+
+  const placeholder = !state.selectedAgent
+    ? 'choose an agent first'
+    : (!agentAvailable(state.selectedAgent) ? agentName + ' is not installed' : 'message…');
+
+  // The reusable AgentChat kit owns the agent/model picker, cwd bar, transcript
+  // (with AICat-style auto-scroll + thinking), and the caret-stable composer.
+  // agentgui supplies state and wires every server interaction as a callback.
   return [
     offlineBanner(),
-    ...banners,
-    Chat({
-      title: agentName + (state.selectedModel ? ' · ' + state.selectedModel : '') + (state.chat.resumeSid ? ' · resume' : ''),
-      // Explicit human-readable sub; the DS default ("NN msgs", zero-padded)
-      // leaks an event-list style into chat. Hide it when there are no messages
-      // (the empty-state already says "no messages yet").
-      sub: state.chat.busy
-        ? 'streaming…'
-        : (state.chat.messages.length
-            ? state.chat.messages.length + (state.chat.messages.length === 1 ? ' message' : ' messages')
-            : ''),
-      messages: msgs,
-      composer,
+    AgentChat({
+      agents: sortedAgents(),
+      selectedAgent: state.selectedAgent,
+      models: state.agentModels,
+      selectedModel: state.selectedModel,
+      modelsLoading: !!state.modelsLoading,
+      messages: state.chat.messages,
+      busy: state.chat.busy,
+      draft: state.chat.draft,
+      status: state.chat.busy
+        ? (state.health.ws === 'reconnecting' ? 'reconnecting…' : 'streaming…')
+        : (state.modelsLoading ? 'loading models…' : (state.chat.resumeSid ? 'resume' : 'ready')),
+      agentName,
+      placeholder,
+      canSend: canSend(),
+      banners,
+      cwd: state.chatCwd,
+      cwdEditing: !!state.cwdEditing,
+      cwdDraft: state.cwdDraft,
+      onSelectAgent: (v) => selectAgent(v),
+      onSelectModel: (v) => selectModel(v),
+      onNewChat: newChat,
+      onStop: cancelChat,
+      onInput: (v) => {
+        // The kit's textarea is controlled and reads its live DOM value on send,
+        // so re-render only when the draft crosses empty<->non-empty (the only
+        // transition that toggles the send button's disabled state).
+        const was = !!(state.chat.draft && state.chat.draft.trim());
+        const now = !!(v && v.trim());
+        state.chat.draft = v;
+        if (was !== now) render();
+      },
+      onSend: (v) => { state.chat.draft = v; sendChat(); },
+      onCwdEdit: () => { state.cwdEditing = true; state.cwdDraft = state.chatCwd || ''; state.cwdError = null; render(); },
+      onCwdSave: () => {
+        const path = (state.cwdDraft ?? '').trim();
+        // A relative cwd would resolve against the server process dir, not what
+        // the user means — require an absolute path (POSIX /…, UNC \\…, or
+        // Windows drive X:\…). Blank is valid (server default).
+        if (path && !/^([/\\]|[A-Za-z]:[/\\])/.test(path)) {
+          state.cwdError = 'enter an absolute path (e.g. /home/you/proj or C:\\proj) or leave blank';
+          render();
+          return;
+        }
+        state.cwdError = null;
+        state.chatCwd = path;
+        if (state.chatCwd) lsSet('agentgui.cwd', state.chatCwd); else lsRemove('agentgui.cwd');
+        state.cwdEditing = false; state.cwdDraft = undefined; render();
+      },
+      onCwdCancel: () => { state.cwdEditing = false; state.cwdDraft = undefined; state.cwdError = null; render(); },
+      onCwdClear: () => { state.chatCwd = ''; lsRemove('agentgui.cwd'); render(); },
+      onCwdDraft: (v) => { state.cwdDraft = v; },
     }),
   ].filter(Boolean);
 }
@@ -498,24 +534,8 @@ function offlineBanner() {
     children: 'agentgui can\'t reach the server (' + (state.health.error || state.health.status) + '). Chat and history actions will fail until it reconnects.' });
 }
 
-function cwdBanner() {
-  if (state.cwdEditing) {
-    return h('div', { key: 'cwdb', class: 'resume-banner', role: 'group', 'aria-label': 'Set working directory' },
-      TextField({ key: 'cwdfield', label: 'working directory (blank = server default)', value: state.cwdDraft ?? state.chatCwd ?? '',
-        placeholder: 'absolute path', onInput: (v) => { state.cwdDraft = v; } }),
-      Btn({ key: 'cwdsave', primary: true, onClick: () => {
-        state.chatCwd = (state.cwdDraft ?? '').trim();
-        if (state.chatCwd) lsSet('agentgui.cwd', state.chatCwd); else lsRemove('agentgui.cwd');
-        state.cwdEditing = false; state.cwdDraft = undefined; render();
-      }, children: 'save' }),
-      Btn({ key: 'cwdcancel', onClick: () => { state.cwdEditing = false; state.cwdDraft = undefined; render(); }, children: 'cancel' }));
-  }
-  return h('div', { key: 'cwdb', class: 'cwd-bar', role: 'group', 'aria-label': 'Working directory' },
-    h('span', { key: 'cwdtxt', class: 'lede cwd-bar-text', title: state.chatCwd || 'server default working directory' },
-      state.chatCwd ? 'cwd: ' + truncate(state.chatCwd, 28, 60) : 'cwd: server default'),
-    h('button', { key: 'cwdset', type: 'button', class: 'cwd-bar-btn', onClick: () => { state.cwdEditing = true; state.cwdDraft = state.chatCwd || ''; render(); } }, state.chatCwd ? 'change' : 'set'),
-    state.chatCwd ? h('button', { key: 'cwdclr', type: 'button', class: 'cwd-bar-btn', onClick: () => { state.chatCwd = ''; lsRemove('agentgui.cwd'); render(); } }, 'use default') : null);
-}
+// (The working-directory bar now lives in the AgentChat kit; agentgui wires its
+// cwd state + handlers as kit callbacks in chatMain.)
 
 function newChat() {
   if (state.chat.messages.length && !state.confirmingNewChat) {
@@ -529,7 +549,12 @@ function newChat() {
   render();
 }
 
-function cancelChat() { state.chat.abort?.abort(); }
+function cancelChat() {
+  // Clear busy immediately so the composer re-enables and the "stop" button
+  // flips back to "new" without waiting for the stream's finally block.
+  state.chat.abort?.abort();
+  if (state.chat.busy) { state.chat.busy = false; render(); }
+}
 
 const CHAT_KEY = 'agentgui.chat';
 function persistChat() {
@@ -592,7 +617,7 @@ async function sendChat() {
   }
 }
 
-// ── history ────────────────────────────────────────────────────────────────
+// --- history ---
 function reconnectAlert() {
   if (!state.live.error) return null;
   return Alert({
@@ -632,7 +657,7 @@ function historyMain() {
     lede,
   });
 
-  const actions = h('div', { key: 'acts', class: 'history-actions' },
+  const actions = h('div', { key: 'acts', class: 'history-actions', role: 'status', 'aria-live': 'polite' },
     Btn({ key: 'resume', primary: true, onClick: () => resumeInChat(sess || { sid: state.selectedSid }), children: 'open in chat' }),
     Btn({ key: 'copy', onClick: copySid, children: copyToast || 'copy sid' }),
   );
@@ -641,7 +666,9 @@ function historyMain() {
     // Distinguish "still loading" from "genuinely empty" so a 0-event session
     // doesn't spin forever.
     const body = state.eventsLoaded
-      ? h('p', { key: 'noev', class: 'lede empty-state', role: 'status' }, 'no events in this session')
+      ? h('div', { key: 'noev', class: 'lede empty-state', role: 'status' },
+          h('span', { key: 'noevtxt' }, 'no events in this session — '),
+          Btn({ key: 'reload', onClick: () => loadSession(state.selectedSid), children: 'reload' }))
       : h('div', { key: 'loading', class: 'lede empty-state', role: 'status', 'aria-live': 'polite' }, Spinner({ key: 'spin', size: 'sm' }), 'loading events…');
     return [reconnectAlert(), head, actions, Panel({ title: 'events', children: body })].filter(Boolean);
   }
@@ -655,13 +682,17 @@ function historyMain() {
     head,
     actions,
     Panel({
-      title: total + ' events' + (hiddenCount > 0 ? ' (showing last 300)' : ''),
+      title: total + ' events' + (hiddenCount > 0 ? ' (showing last 300; ' + hiddenCount + ' older not rendered)' : ''),
       children: EventList({
         items: shown.map((e, i) => {
           // Stable key: prefer the server-assigned event index, else the
           // event timestamp + position, never a bare array index (which
           // collides between loaded and live-pushed events).
-          const key = e.i != null ? 'ev' + e.i : 'ev-' + (e.ts || 0) + '-' + (total - shown.length + i);
+          // Stable key: server event index when present, else ts + the event's
+          // ABSOLUTE position in state.events (not the sliced-view index, which
+          // shifts when live events append and would collide loaded vs live rows).
+          const absIdx = total - shown.length + i;
+          const key = e.i != null ? 'ev' + e.i : 'ev-' + (e.ts || 0) + '-' + (e.type || '') + '-' + absIdx;
           const role = e.role || '?';
           const type = e.type || '?';
           const tool = e.tool ? ' · tool: ' + e.tool : '';
@@ -672,9 +703,12 @@ function historyMain() {
           const full = e.toolInput ? (text + '\n\n' + JSON.stringify(e.toolInput, null, 2)) : raw;
           return {
             key,
-            code: String(total - shown.length + i + 1).padStart(4, '0'),
+            code: String(absIdx + 1).padStart(4, '0'),
             title: expanded ? (full || '(' + type + ')') : (text.slice(0, 220) || '(' + type + ')'),
-            sub: new Date(e.ts).toLocaleString() + ' · ' + role + ' · ' + type + tool + errMark + (raw.length > 220 ? ' · ' + (expanded ? 'click to collapse' : 'click to expand') : ''),
+            // Guard ts: a missing/zero timestamp renders "Invalid Date" otherwise.
+            // Every row is click-to-expand, so always show the affordance word
+            // (not only when text overflows 220 chars).
+            sub: (e.ts ? new Date(e.ts).toLocaleString() : 'no time') + ' · ' + role + ' · ' + type + tool + errMark + ' · ' + (expanded ? 'collapse' : 'expand'),
             onClick: () => { expanded ? state.expandedEvents.delete(key) : state.expandedEvents.add(key); render(); },
           };
         }),
@@ -684,20 +718,22 @@ function historyMain() {
 }
 
 let copyToast = null;
+// Hold the toast long enough to read (2.5s); the copy button label is inside a
+// role=status region (history-actions) so AT announces the change.
+function setCopyToast(msg) { copyToast = msg; render(); setTimeout(() => { copyToast = null; render(); }, 2500); }
 function copySid() {
   const sid = state.selectedSid;
   if (!sid) return;
-  const done = () => { copyToast = 'copied'; render(); setTimeout(() => { copyToast = null; render(); }, 1500); };
   if (navigator.clipboard?.writeText) {
-    navigator.clipboard.writeText(sid).then(done).catch(() => { copyToast = 'copy failed'; render(); setTimeout(() => { copyToast = null; render(); }, 1500); });
+    navigator.clipboard.writeText(sid).then(() => setCopyToast('copied')).catch(() => setCopyToast('copy failed'));
   } else {
     // Fallback for insecure (http) origins where navigator.clipboard is absent.
     try {
       const ta = document.createElement('textarea');
       ta.value = sid; ta.style.position = 'fixed'; ta.style.opacity = '0';
       document.body.appendChild(ta); ta.select(); document.execCommand('copy'); ta.remove();
-      done();
-    } catch { copyToast = 'copy failed'; render(); setTimeout(() => { copyToast = null; render(); }, 1500); }
+      setCopyToast('copied');
+    } catch { setCopyToast('copy failed'); }
   }
 }
 
@@ -757,11 +793,14 @@ function historySide() {
   const rows = searching
     ? visible.map((r, i) =>
         Row({
-          key: 'sr' + i,
+          // sid can repeat across hits, so key on sid+position; rank is the
+          // absolute result position (stable across the 60-row slice).
+          key: 'sr-' + (r.sid || '?') + '-' + i,
           rank: String(i + 1).padStart(3, '0'),
           title: r.snippet || '(no snippet)',
           sub: (r.project || '?') + ' · ' + (r.role || '?') + (r.tool ? ' · ' + r.tool : ''),
-          rail: 'purple',
+          // Rail carries the same semantics as session rows: error > subagent > normal.
+          rail: r.isError ? 'flame' : (r.isSubagent ? 'purple' : 'green'),
           onClick: () => loadSession(r.sid),
         })
       )
@@ -769,8 +808,10 @@ function historySide() {
         Row({
           key: 'sess' + s.sid,
           rank: String(i + 1).padStart(3, '0'),
-          title: (s.isSubagent ? '- ' : '') + (projectLabel(s.title) || projectLabel(s.project) || s.sid),
-          sub: fmtRelTime(s.last) + ' · ' + (s.events || 0) + ' ev · ' + (s.tools || 0) + ' tools' + (s.errors ? ' · ' + s.errors + ' err' : ''),
+          // Subagent is conveyed by the purple rail, not a "- " text prefix.
+          title: projectLabel(s.title) || projectLabel(s.project) || s.sid,
+          // Always show the error count so 0 reads as "no errors", not "untracked".
+          sub: fmtRelTime(s.last) + ' · ' + (s.events || 0) + ' ev · ' + (s.tools || 0) + ' tools · ' + (s.errors || 0) + ' err',
           rail: s.errors ? 'flame' : (s.isSubagent ? 'purple' : 'green'),
           active: s.sid === state.selectedSid,
           onClick: () => loadSession(s.sid),
@@ -802,8 +843,8 @@ function historySide() {
       children: [
         SearchInput({
           key: 'searchInput',
-          placeholder: 'search sessions…',
-          'aria-label': 'Search sessions by text or project',
+          placeholder: 'search event text…',
+          'aria-label': 'Search event text across sessions',
           value: state.searchQ,
           onInput: (v) => { state.searchQ = v; debouncedSearch(); },
         }),
@@ -831,7 +872,7 @@ function historySide() {
         !searching && subagentCount
           ? h('label', { key: 'subtog', class: 'lede subagent-toggle' },
               h('input', { type: 'checkbox', checked: state.showSubagents, onChange: (e) => { state.showSubagents = e.target.checked; render(); } }),
-              'show subagents (' + subagentCount + ')')
+              'show subagents (' + (state.showSubagents ? subagentCount + ' shown' : subagentCount + ' hidden') + ')')
           : null,
         state.historyError
           ? h('p', { key: 'err', class: 'lede field-error', role: 'alert' }, state.historyError)
@@ -839,12 +880,17 @@ function historySide() {
         !searching && truncatedBy > 0
           ? Btn({ key: 'more', onClick: () => { state.sessionsLimit += 60; render(); }, children: 'show '+Math.min(60, truncatedBy)+' more ('+truncatedBy+' hidden)' })
           : null,
+        // Search is server-capped at 60 hits; there is no deeper page, so tell
+        // the user the result set is truncated rather than silently hiding it.
+        searching && truncatedBy > 0
+          ? h('p', { key: 'searchmore', class: 'lede empty-state' }, 'showing first 60 matches (' + truncatedBy + ' more — refine your search)')
+          : null,
       ],
     }),
   ].filter(Boolean);
 }
 
-// ── settings ───────────────────────────────────────────────────────────────
+// --- settings ---
 function isValidUrl(s) {
   if (!s) return true; // blank = same-origin is valid
   try { new URL(s.startsWith('http') ? s : 'http://' + s); return true; }
@@ -853,6 +899,12 @@ function isValidUrl(s) {
 
 async function saveBackend() {
   if (!isValidUrl(state.backendDraft) || state.backendDraft === state.backend) return;
+  // Switching backend orphans the local chat transcript (it belongs to the old
+  // server's sessions). Confirm once if there's a transcript to lose.
+  if (state.chat.messages.length && !state.confirmingBackend) {
+    state.confirmingBackend = true; render(); return;
+  }
+  state.confirmingBackend = false;
   B.setBackend(state.backendDraft);
   state.backend = state.backendDraft;
   state.health = { status: 'unknown' };
@@ -866,14 +918,15 @@ async function saveBackend() {
 function healthSummary() {
   const hh = state.health || {};
   const ok = hh.status === 'ok';
+  // Each chip carries a title so its meaning isn't left to inference.
   const bits = [];
-  bits.push(hh.status || 'unknown');
-  if (hh.version) bits.push('v' + hh.version);
-  if (typeof hh.agents === 'number') bits.push(hh.agents + ' agents');
-  if (typeof hh.activeExecutions === 'number') bits.push(hh.activeExecutions + ' active');
-  if (hh.db) bits.push('db ' + (hh.db.ok ? 'ok' : 'down'));
-  return h('div', { key: 'hp', class: 'health-summary' + (ok ? ' health-ok' : '') },
-    ...bits.map((b, i) => h('span', { key: 'hb' + i, class: 'health-chip' }, b)));
+  bits.push([hh.status || 'unknown', 'Backend connection status']);
+  if (hh.version) bits.push(['v' + hh.version, 'Server version']);
+  if (typeof hh.agents === 'number') bits.push([hh.agents + ' agents', 'Agents registered on the server']);
+  if (typeof hh.activeExecutions === 'number') bits.push([hh.activeExecutions + ' active', 'Chats currently executing']);
+  if (hh.db) bits.push(['db ' + (hh.db.ok ? 'ok' : 'down'), 'History database status']);
+  return h('div', { key: 'hp', class: 'health-summary' + (ok ? ' health-ok' : ''), role: 'group', 'aria-label': 'Backend health' },
+    ...bits.map(([b, t], i) => h('span', { key: 'hb' + i, class: 'health-chip', title: t }, b)));
 }
 
 function settingsMain() {
@@ -905,6 +958,7 @@ function settingsMain() {
         state.backendStatus === 'connecting' ? h('p', { key: 'bst', class: 'lede', role: 'status' }, 'connecting…') : null,
         state.backendStatus === 'ok' ? h('p', { key: 'bst', class: 'lede', role: 'status' }, 'connected') : null,
         state.backendStatus === 'failed' ? h('p', { key: 'bst', class: 'lede field-error', role: 'alert' }, 'connection failed — check the URL') : null,
+        state.confirmingBackend ? h('p', { key: 'bcw', class: 'lede field-error', role: 'alert' }, 'changing backend discards this browser\'s chat transcript — press save again to confirm') : null,
         healthSummary(),
         Btn({
           key: 'savebtn',
@@ -918,10 +972,40 @@ function settingsMain() {
       ]),
     }),
     agentsPanel(),
+    preferencesPanel(),
     ]),
   ];
 }
 
+function clearLocalData() {
+  if (!state.confirmingClearData) { state.confirmingClearData = true; render(); return; }
+  state.confirmingClearData = false;
+  // Wipe agentgui's own localStorage keys (chat transcript, agent/model/cwd,
+  // backend). Leaves the page reload to re-init from defaults.
+  for (const k of ['agentgui.chat', 'agentgui.agent', 'agentgui.model', 'agentgui.cwd', 'agentgui.backend']) lsRemove(k);
+  state.chat = { messages: [], busy: false, abort: null, draft: '', resumeSid: null };
+  render();
+}
+
+function preferencesPanel() {
+  const hh = state.health || {};
+  return Panel({
+    title: 'preferences',
+    children: [
+      h('div', { key: 'ver', class: 'lede' }, 'server ' + (hh.version ? 'v' + hh.version : 'version unknown') + (window.__SERVER_VERSION ? ' · build ' + window.__SERVER_VERSION : '')),
+      h('div', { key: 'sc', class: 'lede', style: 'margin:.5em 0' },
+        'keyboard: g then c/h/s — switch tabs · n — new chat · / — focus search/composer · ? — toggle hint · Esc — blur field'),
+      state.confirmingClearData
+        ? Alert({ key: 'cld', kind: 'warn', title: 'Clear all local data?',
+            children: [
+              h('span', { key: 'cldtxt' }, 'Removes saved chat, agent/model/cwd, and backend from this browser. This cannot be undone. '),
+              Btn({ key: 'cldyes', danger: true, onClick: clearLocalData, children: 'clear' }),
+              Btn({ key: 'cldno', onClick: () => { state.confirmingClearData = false; render(); }, children: 'cancel' })] })
+        : Btn({ key: 'cldbtn', onClick: clearLocalData, children: 'clear local data' }),
+    ],
+  });
+}
+
 function acpStatusFor(agentId) {
   const acp = Array.isArray(state.health.acp) ? state.health.acp : [];
   return acp.find(a => a.id === agentId) || null;
@@ -935,6 +1019,7 @@ function agentsPanel() {
       ? state.agents.map((a, i) => {
           const acp = acpStatusFor(a.id);
           const avail = a.available !== false;
+          const usable = avail || a.npxInstallable;     // selectable from this row
           const bits = [a.protocol || 'agent'];
           if (!avail) bits.push(a.npxInstallable ? 'runs via npx' : 'not installed');
           if (acp) bits.push(acp.healthy ? 'running·healthy' : (acp.running ? 'running' : 'stopped'));
@@ -943,18 +1028,21 @@ function agentsPanel() {
           return Row({
             key: 'ag' + a.id,
             rank: String(i + 1).padStart(3, '0'),
-            title: a.name + (avail ? '' : ' ·'),
+            title: a.name,
             sub: bits.join(' · '),
             rail: a.id === state.selectedAgent ? 'green' : (avail ? 'purple' : 'flame'),
             active: a.id === state.selectedAgent,
-            onClick: () => { if (avail || a.npxInstallable) { navTo('chat'); selectAgent(a.id); } },
+            // Non-installable agents are genuinely inert: mark them disabled (no
+            // click, no button role) instead of looking clickable but doing nothing.
+            state: usable ? 'default' : 'disabled',
+            onClick: usable ? () => { navTo('chat'); selectAgent(a.id); } : undefined,
           });
         })
       : h('p', { key: 'none', class: 'lede' }, 'no agents loaded'),
   });
 }
 
-// ── data ──────────────────────────────────────────────────────────────────
+// --- data ---
 async function refreshHistory() {
   try {
     state.sessions = await B.listSessions(state.backend);
@@ -994,6 +1082,11 @@ async function loadSession(sid) {
   state.expandedEvents = new Set();   // don't carry expansion to the new session
   writeHash(sid, { push: true });
   render();
+  // Bring the now-active sidebar row into view (deep-link / back-forward may
+  // select a row that's scrolled out of the session list).
+  requestAnimationFrame(() => {
+    document.querySelector('.app-side .row.active')?.scrollIntoView({ block: 'nearest' });
+  });
   try {
     state.events = await B.getSessionEvents(state.backend, sid);
     state.eventsLoaded = true;
@@ -1102,7 +1195,13 @@ window.addEventListener('keydown', (e) => {
   }
   if (e.key === 'g') { gPending = true; setTimeout(() => { gPending = false; }, 1000); return; }
   if (e.key === 'n' && state.tab === 'chat') { e.preventDefault(); newChat(); return; }
-  if (e.key === '/') { e.preventDefault(); state.tab === 'history' ? focusSearch() : focusComposer(); return; }
+  if (e.key === '/') {
+    // / focuses search on history, composer on chat; on settings there is no
+    // such field, so ignore it cleanly rather than focusing nothing.
+    if (state.tab === 'history') { e.preventDefault(); focusSearch(); announce('search focused'); }
+    else if (state.tab === 'chat') { e.preventDefault(); focusComposer(); announce('composer focused'); }
+    return;
+  }
   if (e.key === '?') { state.showShortcuts = !state.showShortcuts; render(); return; }
 });