@agenticmail/api 0.9.2 → 0.9.4

package/dist/index.js

@@ -5198,6 +5198,13 @@ function createDispatcherActivityRoutes() {
     existing.lastHeartbeatMs = Date.now();
     if (typeof body.lastTool === "string") existing.lastTool = body.lastTool;
     if (typeof body.turnCount === "number") existing.turnCount = body.turnCount;
+    try {
+      pushSystemEvent({
+        type: "worker_heartbeat",
+        worker: { ...existing }
+      });
+    } catch {
+    }
     res.json({ ok: true });
   });
   router.get("/dispatcher/activity", requireMaster, (_req, res) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/api",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "REST API server for AgenticMail — email and SMS endpoints for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/public/index.html

@@ -39,6 +39,12 @@
       <button id="search-clear" class="search-clear-btn" title="Clear (Esc)" data-icon="close"></button>
     </div>
     <div class="topbar-right">
+      <!-- Real-time worker activity badges. Populated by SSE; one
+           badge per active dispatcher worker showing what each
+           agent is doing right now (reading, editing, running
+           shell, etc.). Empty when no workers are active. -->
+      <div id="activity-badges" class="activity-badges"></div>
+      <button class="icon-btn" id="sound-toggle-btn" title="Notification sound"></button>
       <button class="icon-btn" id="refresh-btn" title="Refresh (r)" data-icon="refresh"></button>
       <button id="profile-btn" class="profile-trigger" title="Account">
         <span id="profile-avatar"></span>

package/public/js/activity-badges.js

@@ -0,0 +1,132 @@
+// Real-time worker activity badges in the topbar.
+//
+// The dispatcher posts worker_started / worker_heartbeat /
+// worker_finished events to /system/events. This module
+// subscribes (master-key auth), maintains a map of active
+// workers, and paints a small badge per active worker
+// between the search bar and the notification bell.
+//
+// Each badge shows: agent avatar/initial · friendly status
+// derived from the last tool the worker invoked. Updates
+// arrive at the heartbeat cadence (30 s) so the badge text
+// reflects what the agent is doing right now.
+
+import { state, API_URL } from './state.js';
+
+const BADGE_CONTAINER_ID = 'activity-badges';
+
+/**
+ * Map of workerId → { agentName, kind, lastTool, turnCount,
+ * startedAtMs }. Maintained off the SSE stream; rendered into
+ * the badge container on every event.
+ */
+const workers = new Map();
+let sseController = null;
+
+/**
+ * Map an SDK tool name (or the truncated head we capture in
+ * dispatcher logs) to a short verb. Falls back to "working"
+ * when we don't recognise the tool. The mapping is intentionally
+ * generic — exotic tools default to "working" rather than
+ * leaking the raw tool name to a user-facing badge.
+ */
+function statusFor(lastTool) {
+  if (!lastTool) return 'starting';
+  const t = lastTool.toLowerCase();
+  if (t.startsWith('read'))         return 'reading';
+  if (t.startsWith('write'))        return 'writing code';
+  if (t.startsWith('edit'))         return 'editing code';
+  if (t.startsWith('bash'))         return 'running shell';
+  if (t.startsWith('grep'))         return 'searching';
+  if (t.startsWith('glob'))         return 'searching';
+  if (t.startsWith('webfetch'))     return 'fetching web';
+  if (t.startsWith('websearch'))    return 'searching web';
+  if (t.startsWith('notebookedit')) return 'editing notebook';
+  if (t.includes('send_email'))     return 'sending mail';
+  if (t.includes('reply_email'))    return 'replying';
+  if (t.includes('read_email'))     return 'reading mail';
+  if (t.includes('list_inbox'))     return 'checking inbox';
+  if (t.includes('search_emails'))  return 'searching mail';
+  if (t.includes('call_agent'))     return 'delegating';
+  if (t.includes('submit_result'))  return 'finishing';
+  if (t.includes('save_thread_memory')) return 'saving memory';
+  if (t.startsWith('mcp__'))        return 'using tool';
+  return 'working';
+}
+
+function render() {
+  const root = document.getElementById(BADGE_CONTAINER_ID);
+  if (!root) return;
+  const list = Array.from(workers.values()).sort((a, b) => (a.startedAtMs ?? 0) - (b.startedAtMs ?? 0));
+  if (list.length === 0) { root.innerHTML = ''; return; }
+  root.innerHTML = list.map(w => {
+    const initial = (w.agentName ?? '?').slice(0, 1).toUpperCase();
+    const status = statusFor(w.lastTool);
+    const tooltip = `${w.agentName} — ${status}${w.turnCount ? ` · ${w.turnCount} tool calls` : ''}${w.lastTool ? `\nlast tool: ${w.lastTool}` : ''}`;
+    return `
+      <div class="activity-badge" title="${escapeAttr(tooltip)}" data-worker-id="${escapeAttr(w.workerId ?? '')}">
+        <span class="badge-dot"></span>
+        <span class="badge-initial">${escapeHtml(initial)}</span>
+        <span class="badge-name">${escapeHtml(w.agentName ?? '?')}</span>
+        <span class="badge-status">${escapeHtml(status)}</span>
+      </div>
+    `;
+  }).join('');
+}
+
+function handleEvent(event) {
+  if (!event || typeof event !== 'object') return;
+  const w = event.worker;
+  if (!w?.workerId) return;
+  if (event.type === 'worker_started' || event.type === 'worker_heartbeat') {
+    // Merge so a heartbeat-after-started preserves the start
+    // metadata without re-fetching.
+    const existing = workers.get(w.workerId) ?? {};
+    workers.set(w.workerId, { ...existing, ...w });
+    render();
+  } else if (event.type === 'worker_finished') {
+    workers.delete(w.workerId);
+    render();
+  }
+}
+
+/**
+ * Subscribe to /system/events with the master key. The web UI
+ * already holds the master key in state.masterKey (set on
+ * sign-in). Re-subscribes idempotently — safe to call after
+ * agent-list refresh.
+ */
+export function subscribeToActivity() {
+  if (sseController) { try { sseController.abort(); } catch {} }
+  sseController = new AbortController();
+  fetch(`${API_URL}/api/agenticmail/system/events`, {
+    headers: { Authorization: `Bearer ${state.masterKey}`, Accept: 'text/event-stream' },
+    signal: sseController.signal,
+  }).then(async res => {
+    if (!res.ok || !res.body) return;
+    const reader = res.body.getReader();
+    const dec = new TextDecoder();
+    let buf = '';
+    while (!sseController.signal.aborted) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      let i;
+      while ((i = buf.indexOf('\n\n')) !== -1) {
+        const frame = buf.slice(0, i); buf = buf.slice(i + 2);
+        for (const line of frame.split('\n')) {
+          if (!line.startsWith('data: ')) continue;
+          try { handleEvent(JSON.parse(line.slice(6))); } catch {}
+        }
+      }
+    }
+  }).catch(() => { /* dropped — user can refresh to reconnect */ });
+}
+
+// Tiny HTML escapers (kept local to avoid an import cycle).
+function escapeHtml(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+function escapeAttr(s) { return escapeHtml(s); }

package/public/js/app.js

@@ -14,7 +14,9 @@ import { loadList, renderList, clearSearch, ensureFolderCache } from './list-vie
 import { openMessage } from './message-view.js';
 import { populateComposeFrom, openCompose, openDraft, closeCompose, discardCompose, sendCompose } from './compose.js';
 import { subscribeToAllAgents, maybeRequestNotificationPermission } from './sse.js';
+import { subscribeToActivity } from './activity-badges.js';
 import { icon } from './icons.js';
+import { isSoundEnabled, setSoundEnabled, playNotificationSound } from './sound.js';
 
 // Hydrate every `data-icon="name"` placeholder in the static HTML
 // with the corresponding inline SVG. Done once on load so we don't
@@ -97,6 +99,11 @@ async function bootstrap() {
     renderProfile();
     populateComposeFrom();
     subscribeToAllAgents();
+    // Real-time worker activity badges. Master-key-scoped SSE on
+    // /system/events; the dispatcher's worker_started /
+    // worker_heartbeat / worker_finished events drive the badge
+    // rendering. Idempotent — safe to call after bootstrap reruns.
+    subscribeToActivity();
     maybeRequestNotificationPermission();
     // Initial route: if the URL already has a hash (e.g. a refresh
     // on /#/folder/sent), respect it; otherwise default to inbox.
@@ -121,6 +128,8 @@ async function selectAgent(agent) {
   // account that uses different folder names (e.g. Gmail relay
   // vs vanilla Stalwart) keeps the previous cache.
   state.folderNames = {};
+  // Reset pagination — each inbox starts at page 1.
+  state.pagination = { offset: 0, limit: 50, total: 0 };
   // Discover folders BEFORE the first sidebar render so the
   // `requiresDiscovery` hide-rule (All Mail on non-Gmail servers)
   // has the cache to consult. Falls back to defaults on failure.
@@ -169,6 +178,10 @@ function route() {
   const folder = folderMatch ? folderMatch[1] : 'inbox';
   if (state.selectedFolder !== folder) {
     state.selectedFolder = folder;
+    // Reset pagination on every folder switch — a fresh folder
+    // starts at page 1. Preserved across silent SSE refreshes so
+    // a new arrival doesn't yank the user back from page 3.
+    state.pagination = { offset: 0, limit: 50, total: 0 };
     renderSidebar(onFolderSelect);
   }
   if (state.selectedAgent) loadList(state.selectedAgent, folder);
@@ -188,6 +201,27 @@ document.getElementById('sidebar-backdrop').addEventListener('click', () => {
   document.getElementById('main')?.classList.remove('sidebar-open');
 });
 
+// Sound toggle. Stateful icon button — bell (on) / bell-slash (off).
+// Clicking flips the preference (persisted to localStorage by the
+// sound module), updates the icon, and plays a single test chime
+// on transitions to ON so the user hears what they just enabled.
+function renderSoundToggle() {
+  const btn = document.getElementById('sound-toggle-btn');
+  if (!btn) return;
+  const on = isSoundEnabled();
+  btn.innerHTML = icon(on ? 'soundOn' : 'soundOff', { size: 18 });
+  btn.title = on ? 'Notification sound: on (click to mute)' : 'Notification sound: off (click to enable)';
+  btn.classList.toggle('sound-on', on);
+  btn.classList.toggle('sound-off', !on);
+}
+document.getElementById('sound-toggle-btn')?.addEventListener('click', () => {
+  const next = !isSoundEnabled();
+  setSoundEnabled(next);
+  renderSoundToggle();
+  if (next) playNotificationSound();   // sample the chime on enable
+});
+renderSoundToggle();
+
 document.getElementById('refresh-btn').addEventListener('click', async () => {
   if (state.selectedAgent) {
     await loadList(state.selectedAgent, state.selectedFolder);

package/public/js/icons.js

@@ -47,6 +47,13 @@ const PATHS = {
   // ─── Status / dots ──────────────────────────────────────────────
   dot:     'M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8z',
   check:   'M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41L9 16.17z',
+  // Material-style notifications bell — used for the sound-on
+  // state. Off uses the same path with a diagonal slash overlay
+  // applied via CSS (.icon-svg.off → ::after rule in styles.css).
+  soundOn:  'M12 22a2 2 0 0 0 2-2h-4a2 2 0 0 0 2 2zm6-6V11c0-3.07-1.64-5.64-4.5-6.32V4a1.5 1.5 0 0 0-3 0v.68C7.63 5.36 6 7.92 6 11v5l-2 2v1h16v-1l-2-2z',
+  // Bell with a slash through it (off state). Single-path so the
+  // icon hot-swaps cleanly without dependency on overlay rules.
+  soundOff: 'M16.27 19.27 18 21l-1.27 1.27-1.45-1.45A1.98 1.98 0 0 1 14 22h-4a2 2 0 0 1-2-2h4a2 2 0 0 0 .27-.27L3 9.46 4.27 8.19 16.27 19.27zM18 16v-5a6 6 0 0 0-4.5-5.81V5a1.5 1.5 0 0 0-3 0v.19a6 6 0 0 0-2.16.91L18 16z',
 };
 
 export function icon(name, opts = {}) {

package/public/js/list-view.js

@@ -107,9 +107,19 @@ export async function loadList(agent, folder) {
       </div>
       <div class="list-toolbar-spacer"></div>
       <span class="count-text" id="list-count"></span>
+      <button class="icon-btn pager-btn" id="pager-prev" title="Newer" data-icon="back"></button>
+      <button class="icon-btn pager-btn" id="pager-next" title="Older"></button>
     </div>
     <div class="list-rows" id="list-rows"><div class="empty">Loading…</div></div>
   `;
+  // Pager buttons. "Newer" goes back to a lower offset (closer to
+  // the head of the inbox); "Older" advances to higher offsets.
+  // Each handler clamps to valid bounds and refetches via loadList
+  // with the new offset preserved in state.pagination.
+  document.getElementById('pager-next').innerHTML = icon('back', { size: 18 });
+  document.getElementById('pager-next').style.transform = 'rotate(180deg)';
+  document.getElementById('pager-prev')?.addEventListener('click', () => goToPage(agent, folder, -1));
+  document.getElementById('pager-next')?.addEventListener('click', () => goToPage(agent, folder, +1));
   document.getElementById('list-refresh-btn')?.addEventListener('click', () => loadList(agent, folder));
   document.getElementById('list-select-all-input')?.addEventListener('change', (e) => {
     const checked = e.target.checked;
@@ -152,9 +162,18 @@ export async function loadList(agent, folder) {
     // Previously we used `/mail/inbox` (no preview) and `/mail/
     // folders/:folder` (no preview, wrong folder names), which left
     // every row stuck on subject + sender alone.
-    const url = `/mail/digest?folder=${encodeURIComponent(imap)}&limit=50&offset=0&previewLength=240`;
+    const { offset, limit } = state.pagination;
+    const url = `/mail/digest?folder=${encodeURIComponent(imap)}&limit=${limit}&offset=${offset}&previewLength=240`;
     const data = await apiGet(url, { agentKey: agent.apiKey });
     state.messages = data.messages ?? [];
+    // The digest endpoint returns `total` — use it for the pager.
+    // Fall back to (offset + page-size) when missing so the
+    // pager still functions in a degraded "we don't know the
+    // upper bound" mode (Next stays enabled until a fetch
+    // returns a short page).
+    state.pagination.total = typeof data?.total === 'number'
+      ? data.total
+      : (state.messages.length === limit ? offset + limit + 1 : offset + state.messages.length);
     renderList();
   } catch (err) {
     const msg = String(err.message ?? err);
@@ -188,7 +207,11 @@ function folderTitle(folder) {
 async function loadDraftsList(agent) {
   try {
     const data = await apiGet('/drafts', { agentKey: agent.apiKey });
-    const rows = Array.isArray(data?.drafts) ? data.drafts : [];
+    const all = Array.isArray(data?.drafts) ? data.drafts : [];
+    const { offset, limit } = state.pagination;
+    // Drafts come from SQL as a single list; paginate client-side.
+    const rows = all.slice(offset, offset + limit);
+    state.pagination.total = all.length;
     state.messages = rows.map(r => ({
       // We store the draft id under `uid` so renderList +
       // click handlers can use the same field. Drafts also
@@ -214,6 +237,73 @@ async function loadDraftsList(agent) {
   }
 }
 
+/**
+ * Advance the pager by one page in the given direction (-1 newer,
+ * +1 older). Clamps to valid bounds, then triggers loadList for the
+ * fresh offset. Bound to the prev/next toolbar buttons.
+ */
+function goToPage(agent, folder, direction) {
+  const { offset, limit, total } = state.pagination;
+  const next = offset + direction * limit;
+  if (next < 0) return;                      // already at newest
+  if (next >= total && direction > 0) return; // already at oldest
+  state.pagination.offset = Math.max(0, next);
+  // Scroll to top so the user lands on the first row of the new
+  // page rather than at the bottom of where the previous page
+  // ended.
+  const rows = document.getElementById('list-rows');
+  if (rows) rows.scrollTop = 0;
+  loadList(agent, folder);
+}
+
+/**
+ * Refresh the currently-rendered list without rebuilding the
+ * toolbar. Used by the SSE new-mail handler so a new email
+ * silently slides into the list — no flicker, no "Loading…",
+ * no bulk-action selection wiped, no scroll jump.
+ *
+ * Drafts have their own loader; everything else uses the
+ * generic digest path. Falls through to a noop on errors
+ * (the SSE notification already pinged the user, so a silent
+ * refresh failure is acceptable — the next user-driven
+ * refresh / folder switch will repair).
+ */
+export async function silentRefresh(agent, folder) {
+  if (!agent) return;
+  try {
+    const { offset, limit } = state.pagination;
+    if (folder === 'drafts') {
+      const data = await apiGet('/drafts', { agentKey: agent.apiKey });
+      const all = Array.isArray(data?.drafts) ? data.drafts : [];
+      state.pagination.total = all.length;
+      const rows = all.slice(offset, offset + limit);
+      state.messages = rows.map(r => ({
+        uid: r.id,
+        __draftId: r.id,
+        subject: r.subject || '(no subject)',
+        from: [{ name: agent.name, address: agent.email }],
+        date: r.updated_at ? `${r.updated_at}Z`.replace('ZZ', 'Z') : null,
+        preview: (r.text_body || '').slice(0, 240),
+        flags: [],
+        __recipient: r.to_addr || '(no recipient)',
+      }));
+      renderList();
+      return;
+    }
+    await ensureFolderCache(agent);
+    const isStarred = folder === 'starred';
+    const imap = isStarred ? 'INBOX' : (state.folderNames?.[folder]);
+    if (!imap) return;
+    const url = `/mail/digest?folder=${encodeURIComponent(imap)}&limit=${limit}&offset=${offset}&previewLength=240`;
+    const data = await apiGet(url, { agentKey: agent.apiKey });
+    state.messages = data.messages ?? [];
+    state.pagination.total = typeof data?.total === 'number'
+      ? data.total
+      : (state.messages.length === limit ? offset + limit + 1 : offset + state.messages.length);
+    renderList();
+  } catch { /* silent — next user action will repair */ }
+}
+
 export function renderList() {
   const root = document.getElementById('list-rows');
   if (!root) return;
@@ -253,8 +343,23 @@ export function renderList() {
   } else if (hintEl) {
     hintEl.classList.remove('show');
   }
+  // Gmail-style "X-Y of Z" pager label + button enable/disable.
+  // We show the current PAGE range against the server-reported
+  // total, not just the filtered window — pagination is page-
+  // level; search is row-level filtering within the current page.
   const countEl = document.getElementById('list-count');
-  if (countEl) countEl.textContent = `${filtered.length} of ${state.messages.length}`;
+  const { offset, limit, total } = state.pagination;
+  const pageStart = state.messages.length > 0 ? offset + 1 : 0;
+  const pageEnd = offset + state.messages.length;
+  if (countEl) {
+    countEl.textContent = total > 0
+      ? `${pageStart}–${pageEnd} of ${total}`
+      : (state.messages.length > 0 ? `${pageStart}–${pageEnd}` : '0');
+  }
+  const prevBtn = document.getElementById('pager-prev');
+  const nextBtn = document.getElementById('pager-next');
+  if (prevBtn) prevBtn.disabled = offset <= 0;
+  if (nextBtn) nextBtn.disabled = pageEnd >= total || state.messages.length < limit;
 
   if (filtered.length === 0) {
     root.innerHTML = q

package/public/js/sound.js

@@ -0,0 +1,61 @@
+// Notification sound — soft 2-note chime synthesised via Web Audio
+// API (no external asset shipped, zero network cost). User
+// preference (on/off) lives in localStorage.
+//
+// Why Web Audio and not an <audio src="...">: the asset would have
+// to be bundled (cache invalidation, MIME types, paths under
+// `/branding/`, etc.), and we'd still need code to gate playback
+// on a user-toggle. Synthesizing a chime is one short function
+// with no asset surface and lets us tweak the timbre by editing
+// numbers.
+
+const STORAGE_KEY = 'agenticmail.notif.soundEnabled';
+
+/** True if the user has the chime turned on. Defaults to true. */
+export function isSoundEnabled() {
+  // null = never set → default ON. 'false' string = explicitly off.
+  return localStorage.getItem(STORAGE_KEY) !== 'false';
+}
+
+/** Persist the user's choice. */
+export function setSoundEnabled(enabled) {
+  try { localStorage.setItem(STORAGE_KEY, enabled ? 'true' : 'false'); } catch { /* private mode */ }
+}
+
+/**
+ * Play the new-mail chime. Two short sine pulses an octave apart
+ * (E5 → A5), 220 ms total, gain envelope quick attack + 60 ms
+ * decay so it reads as a soft "ding" rather than a buzz. Bails
+ * silently when sound is disabled or the browser blocks audio
+ * (e.g. tab hasn't received a user gesture yet — first arrival
+ * after a page load with no interaction may be muted by the
+ * autoplay policy; subsequent arrivals work).
+ */
+export function playNotificationSound() {
+  if (!isSoundEnabled()) return;
+  try {
+    const Ctor = window.AudioContext || window.webkitAudioContext;
+    if (!Ctor) return;
+    const ctx = new Ctor();
+    const now = ctx.currentTime;
+    const playTone = (freq, startOffset, duration = 0.08) => {
+      const osc = ctx.createOscillator();
+      const gain = ctx.createGain();
+      osc.type = 'sine';
+      osc.frequency.value = freq;
+      const start = now + startOffset;
+      // Quick attack + exponential decay = "chime" not "beep".
+      gain.gain.setValueAtTime(0.0001, start);
+      gain.gain.exponentialRampToValueAtTime(0.18, start + 0.01);
+      gain.gain.exponentialRampToValueAtTime(0.0001, start + duration);
+      osc.connect(gain).connect(ctx.destination);
+      osc.start(start);
+      osc.stop(start + duration);
+    };
+    playTone(659.25, 0);     // E5
+    playTone(880.00, 0.12);  // A5 — major sixth above
+    // Close the context shortly after the tones end so we don't
+    // leak audio contexts. Some browsers cap at ~6 concurrent.
+    setTimeout(() => { try { ctx.close(); } catch {} }, 600);
+  } catch { /* audio blocked; user-toggle is still respected */ }
+}

package/public/js/sse.js

@@ -1,13 +1,16 @@
 // Real-time mail delivery via Server-Sent Events. Every agent gets
 // its own subscription; the dispatcher pushes a `new` event per
 // arrived message. We fan that out to:
-//   1. List view — reload if it's the active inbox (instant ping)
+//   1. List view — silent in-place refresh (no flicker, no scroll
+//      jump, no bulk-selection wipe) if it's the active inbox
 //   2. Profile dropdown — bump the per-agent unread counter
 //   3. Browser notification — system ping when the tab is in the background
+//   4. Soft chime (toggleable) when sound is enabled
 import { state, API_URL } from './state.js';
 import { toast } from './utils.js';
 import { renderProfile } from './profile.js';
-import { loadList } from './list-view.js';
+import { silentRefresh } from './list-view.js';
+import { playNotificationSound } from './sound.js';
 
 export function subscribeToAllAgents() {
   // Tear down previous controllers (called on agent-list refresh).
@@ -49,11 +52,23 @@ async function handleSseEvent(agent, event) {
 
   const isOpen = state.selectedAgent?.id === agent.id;
   if (isOpen) {
-    await loadList(agent, state.selectedFolder);
+    // Silent in-place refresh — re-fetches the list digest and
+    // re-renders ONLY the rows div. Toolbar (select-all, refresh,
+    // bulk-actions) is untouched; existing row checkboxes survive;
+    // scroll position is preserved by the browser since we replace
+    // only the inner content. No "Loading…" flicker.
+    await silentRefresh(agent, state.selectedFolder);
     state.unread[agent.id] = 0;   // user is looking — clear badge
     renderProfile();
   }
 
+  // Soft chime — respects the user's sound toggle. Plays for every
+  // arrival regardless of whether the tab is focused, because that
+  // is the whole point of the chime (a foregrounded tab still
+  // benefits from the audible ping when the user's attention is
+  // elsewhere on screen).
+  playNotificationSound();
+
   fireBrowserNotification(agent, event, isOpen);
 
   if (!isOpen) {

package/public/js/state.js

@@ -24,6 +24,16 @@ export const state = {
    * showed.
    */
   folderNames: {},             // { [sidebarId]: imapFolderName }
+  /**
+   * Pagination state for the currently-rendered list. `offset` is
+   * the index of the FIRST message in the current view; `limit` is
+   * the page size; `total` is the server-reported total count for
+   * the folder (or the local row count for drafts). Reset to
+   * offset=0 on folder switch + agent switch; preserved across
+   * silent SSE refreshes so a new arrival doesn't yank the user
+   * back to page 1.
+   */
+  pagination: { offset: 0, limit: 50, total: 0 },
 };
 
 export const API_URL = window.location.origin;

package/public/styles.css

@@ -159,6 +159,65 @@ a { color: var(--accent-strong); }
   color: var(--ink-soft); font-size: 18px;
 }
 .icon-btn:hover { background: var(--bg-hover); }
+/* Sound-toggle state colours. On = brand pink (alive); off = muted
+   so the button reads as "currently silent". */
+#sound-toggle-btn.sound-on { color: var(--pink); }
+#sound-toggle-btn.sound-off { color: var(--muted); }
+
+/* ─── Activity badges (live worker status) ───────────────────────
+   One pill per active dispatcher worker. Populated by SSE on the
+   `worker_started` / `worker_heartbeat` / `worker_finished`
+   events. Each badge shows the agent's initial + name + a short
+   verb derived from the worker's `lastTool`. The green dot
+   gently pulses so the row reads as "alive" rather than static. */
+.activity-badges {
+  display: flex; align-items: center; gap: 6px;
+  max-width: 480px;
+  overflow-x: auto;
+  scrollbar-width: none;
+  margin-right: 4px;
+}
+.activity-badges::-webkit-scrollbar { display: none; }
+.activity-badge {
+  display: inline-flex; align-items: center; gap: 6px;
+  padding: 4px 10px 4px 6px;
+  background: var(--bg);
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  font-size: 12px;
+  color: var(--ink-soft);
+  white-space: nowrap;
+  cursor: default;
+}
+.activity-badge:hover { background: var(--bg-hover); }
+.activity-badge .badge-dot {
+  width: 6px; height: 6px; border-radius: 50%;
+  background: #34a853;          /* live-green */
+  flex-shrink: 0;
+  box-shadow: 0 0 0 0 rgba(52, 168, 83, 0.5);
+  animation: activity-pulse 2s infinite;
+}
+@keyframes activity-pulse {
+  0%   { box-shadow: 0 0 0 0 rgba(52, 168, 83, 0.5); }
+  70%  { box-shadow: 0 0 0 6px rgba(52, 168, 83, 0); }
+  100% { box-shadow: 0 0 0 0 rgba(52, 168, 83, 0); }
+}
+.activity-badge .badge-initial {
+  display: inline-flex; align-items: center; justify-content: center;
+  width: 18px; height: 18px; border-radius: 50%;
+  background: var(--pink); color: white;
+  font-size: 10px; font-weight: 700;
+  flex-shrink: 0;
+}
+.activity-badge .badge-name { font-weight: 500; color: var(--ink); }
+.activity-badge .badge-status { color: var(--muted); }
+.activity-badge .badge-status::before { content: '· '; opacity: .6; }
+
+/* Mobile — hide badges on narrow viewports; they fold to the
+   topbar's account avatar dropdown anyway. */
+@media (max-width: 800px) {
+  .activity-badges { display: none; }
+}
 
 /* ─── Profile (top right) ─────────────────────────────────────────── */
 .profile-trigger {
@@ -417,6 +476,19 @@ a { color: var(--accent-strong); }
 .list-toolbar-spacer { flex: 1; }
 .list-toolbar .count-text {
   font-size: 12px; color: var(--muted);
+  margin-right: 8px;
+}
+/* Gmail-style pager. Buttons inherit .icon-btn styling; disabled
+   state mutes the colour so the user can tell at a glance whether
+   prev/next is available without trying to click. */
+.pager-btn {
+  width: 32px; height: 32px;
+  color: var(--ink-soft);
+}
+.pager-btn:hover:not(:disabled) { background: var(--bg-hover); color: var(--ink); }
+.pager-btn:disabled {
+  color: var(--line);
+  cursor: default;
 }
 
 /* Bulk-action toolbar — appears between select-all and refresh