@agenticmail/api 0.9.3 → 0.9.5

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.3",
+  "version": "0.9.5",
   "description": "REST API server for AgenticMail — email and SMS endpoints for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -36,7 +36,7 @@
     "uuid": "^11.1.0"
   },
   "optionalDependencies": {
-    "@agenticmail/claudecode": "^0.2.2"
+    "@agenticmail/claudecode": "^0.2.4"
   },
   "devDependencies": {
     "@types/cors": "^2.8.17",

package/public/index.html

@@ -39,6 +39,11 @@
       <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">

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,6 +14,7 @@ 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';
 
@@ -98,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.
@@ -122,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.
@@ -170,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);

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,25 @@ 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
@@ -229,9 +271,12 @@ async function loadDraftsList(agent) {
 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 rows = Array.isArray(data?.drafts) ? data.drafts : [];
+      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,
@@ -249,9 +294,12 @@ export async function silentRefresh(agent, folder) {
     const isStarred = folder === 'starred';
     const imap = isStarred ? 'INBOX' : (state.folderNames?.[folder]);
     if (!imap) return;
-    const url = `/mail/digest?folder=${encodeURIComponent(imap)}&limit=50&offset=0&previewLength=240`;
+    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 */ }
 }
@@ -295,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/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

@@ -164,6 +164,61 @@ a { color: var(--accent-strong); }
 #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 {
   width: 40px; height: 40px; border-radius: 50%;
@@ -421,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