switchroom 0.13.65 → 0.14.1

package/telegram-plugin/tests/quota-watch.test.ts

@@ -0,0 +1,366 @@
+/**
+ * Unit tests for the proactive quota threshold-tier push helper (#E4).
+ * Mirrors the shape of credits-watch.test.ts. Covers:
+ *   - Pure decision logic across all transition-table cases
+ *   - State persistence round-trip
+ *   - Message body content sanity
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  evaluateQuotaWatchAccount,
+  loadQuotaWatchState,
+  saveQuotaWatchState,
+  patchQuotaWatchState,
+  emptyQuotaWatchState,
+  emptyAccountState,
+} from "../quota-watch.js";
+import type { AccountSnapshot } from "../auth-snapshot-format.js";
+import type { QuotaUtilization } from "../quota-check.js";
+
+// ── test fixtures ────────────────────────────────────────────────────────────
+
+const NOW = 1_780_000_000_000;
+
+/** Build a minimal QuotaUtilization at given utilization percentages. */
+function makeQuota(
+  fivePct: number,
+  sevenPct: number,
+  fiveHourResetAt?: Date,
+  sevenDayResetAt?: Date,
+): QuotaUtilization {
+  return {
+    fiveHourUtilizationPct: fivePct,
+    sevenDayUtilizationPct: sevenPct,
+    fiveHourResetAt: fiveHourResetAt ?? null,
+    sevenDayResetAt: sevenDayResetAt ?? null,
+    representativeClaim: null,
+    overageStatus: null,
+    overageDisabledReason: null,
+  };
+}
+
+/** Build an AccountSnapshot with given quota. */
+function makeSnap(
+  label: string,
+  quota: QuotaUtilization | null,
+  isActive = false,
+): AccountSnapshot {
+  return { label, isActive, quota };
+}
+
+const HEALTHY_SNAP = makeSnap("alice@example.com", makeQuota(30, 40));
+const THROTTLING_5H = makeSnap("alice@example.com", makeQuota(85, 40));
+const THROTTLING_7D = makeSnap("alice@example.com", makeQuota(40, 90));
+const BLOCKED_SNAP = makeSnap("alice@example.com", makeQuota(99.9, 99.9));
+const UNKNOWN_SNAP = makeSnap("alice@example.com", null);
+
+const PREV_NEVER_NOTIFIED = emptyAccountState(); // lastNotifiedHealth: null
+const PREV_WAS_HEALTHY = { lastNotifiedHealth: "healthy" as const, lastNotifiedAt: NOW - 1000 };
+const PREV_WAS_THROTTLING = { lastNotifiedHealth: "throttling" as const, lastNotifiedAt: NOW - 1000 };
+
+// ── transition decision tests ────────────────────────────────────────────────
+
+describe("evaluateQuotaWatchAccount — transition table", () => {
+  it("healthy → healthy (never notified) skips", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: HEALTHY_SNAP,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(d.kind).toBe("skip");
+    if (d.kind !== "skip") return;
+    expect(d.reason).toBe("steady-state");
+  });
+
+  it("healthy → healthy (was healthy) skips", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: HEALTHY_SNAP,
+      prev: PREV_WAS_HEALTHY,
+      now: NOW,
+    });
+    expect(d.kind).toBe("skip");
+  });
+
+  it("healthy → throttling (5h) fires entered-throttling notification", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    expect(d.transition).toBe("entered-throttling");
+    expect(d.newAccountState.lastNotifiedHealth).toBe("throttling");
+    expect(d.newAccountState.lastNotifiedAt).toBe(NOW);
+  });
+
+  it("healthy → throttling (7d) fires entered-throttling notification", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_7D,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    expect(d.transition).toBe("entered-throttling");
+  });
+
+  it("throttling → throttling skips (already notified)", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: PREV_WAS_THROTTLING,
+      now: NOW,
+    });
+    expect(d.kind).toBe("skip");
+    if (d.kind !== "skip") return;
+    expect(d.reason).toBe("steady-state");
+  });
+
+  it("throttling → healthy fires recovered-to-healthy notification", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: HEALTHY_SNAP,
+      prev: PREV_WAS_THROTTLING,
+      now: NOW,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    expect(d.transition).toBe("recovered-to-healthy");
+    expect(d.newAccountState.lastNotifiedHealth).toBe("healthy");
+    expect(d.newAccountState.lastNotifiedAt).toBe(NOW);
+  });
+
+  it("* → blocked skips (credits-watch domain)", () => {
+    const dFromHealthy = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: BLOCKED_SNAP,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(dFromHealthy.kind).toBe("skip");
+    if (dFromHealthy.kind !== "skip") return;
+    expect(dFromHealthy.reason).toBe("blocked-not-our-domain");
+  });
+
+  it("blocked → healthy skips (credits-watch domain)", () => {
+    // blocked → healthy: credits-watch handles the blocked recovery path.
+    // Our watcher should not fire for it (we never tracked 'blocked').
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: HEALTHY_SNAP,
+      prev: PREV_NEVER_NOTIFIED, // we were never tracking as throttling
+      now: NOW,
+    });
+    // healthy → healthy from null-prev should skip, not fire
+    expect(d.kind).toBe("skip");
+  });
+
+  it("unknown quota snap skips (probe failed)", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: UNKNOWN_SNAP,
+      prev: PREV_WAS_THROTTLING,
+      now: NOW,
+    });
+    expect(d.kind).toBe("skip");
+    if (d.kind !== "skip") return;
+    expect(d.reason).toBe("unknown-not-our-domain");
+  });
+
+  it("no duplicate: two consecutive polls in throttling state produce one notify then skip", () => {
+    // First poll: healthy → throttling → notify
+    const d1 = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(d1.kind).toBe("notify");
+    if (d1.kind !== "notify") return;
+
+    // Second poll: throttling → throttling → skip
+    const d2 = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: d1.newAccountState,
+      now: NOW + 15 * 60_000,
+    });
+    expect(d2.kind).toBe("skip");
+  });
+});
+
+// ── message content tests ────────────────────────────────────────────────────
+
+describe("evaluateQuotaWatchAccount — message content", () => {
+  it("throttling message contains account label and percentages", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    expect(d.message).toContain("alice@example.com");
+    expect(d.message).toContain("85%");
+    expect(d.message).toContain("40%");
+    expect(d.message).toContain("5-hour");
+  });
+
+  it("recovery message contains account label and percentages", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: HEALTHY_SNAP,
+      prev: PREV_WAS_THROTTLING,
+      now: NOW,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    expect(d.message).toContain("alice@example.com");
+    expect(d.message).toContain("Quota back in healthy range");
+    expect(d.message).toContain("30%");
+  });
+
+  it("throttling message HTML-escapes account label", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: makeSnap("<evil>@example.com", makeQuota(85, 40)),
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    expect(d.message).toContain("&lt;evil&gt;");
+    expect(d.message).not.toContain("<evil>");
+  });
+
+  it("throttling message for active account mentions /auth use", () => {
+    const activeSnap = makeSnap("alice@example.com", makeQuota(85, 40), /* isActive */ true);
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: activeSnap,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    // Active account message should mention switching
+    expect(d.message).toContain("/auth");
+  });
+
+  it("throttling message includes reset time when provided", () => {
+    const resetAt = new Date(NOW + 3 * 60 * 60_000); // 3 hours from now
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: makeSnap("alice@example.com", makeQuota(85, 40, resetAt)),
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    expect(d.message).toContain("refills in");
+  });
+});
+
+// ── state persistence tests ──────────────────────────────────────────────────
+
+describe("loadQuotaWatchState / saveQuotaWatchState — round-trip", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "quota-watch-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns emptyQuotaWatchState when no file exists", () => {
+    expect(loadQuotaWatchState(tmp)).toEqual(emptyQuotaWatchState());
+  });
+
+  it("round-trips a saved state with multiple accounts", () => {
+    const state = {
+      "alice@example.com": { lastNotifiedHealth: "throttling" as const, lastNotifiedAt: 1_780_000_000_000 },
+      "bob@example.com": { lastNotifiedHealth: null, lastNotifiedAt: 0 },
+    };
+    saveQuotaWatchState(tmp, state);
+    expect(loadQuotaWatchState(tmp)).toEqual(state);
+  });
+
+  it("falls back to empty on malformed JSON", () => {
+    mkdirSync(tmp, { recursive: true });
+    writeFileSync(join(tmp, "quota-watch.json"), "{broken");
+    expect(loadQuotaWatchState(tmp)).toEqual(emptyQuotaWatchState());
+  });
+
+  it("falls back to empty on shape mismatch (not an object)", () => {
+    writeFileSync(join(tmp, "quota-watch.json"), JSON.stringify([1, 2, 3]));
+    expect(loadQuotaWatchState(tmp)).toEqual(emptyQuotaWatchState());
+  });
+
+  it("drops malformed entries but preserves valid ones", () => {
+    writeFileSync(
+      join(tmp, "quota-watch.json"),
+      JSON.stringify({
+        "good@example.com": { lastNotifiedHealth: "throttling", lastNotifiedAt: 1000 },
+        "bad@example.com": { lastNotifiedHealth: "invalid", lastNotifiedAt: "not-a-number" },
+      }),
+    );
+    const loaded = loadQuotaWatchState(tmp);
+    expect(loaded["good@example.com"]).toEqual({ lastNotifiedHealth: "throttling", lastNotifiedAt: 1000 });
+    expect(loaded["bad@example.com"]).toBeUndefined();
+  });
+
+  it("creates the state dir on save (if it doesn't exist yet)", () => {
+    const fresh = join(tmp, "fresh-subdir");
+    saveQuotaWatchState(fresh, {});
+    expect(loadQuotaWatchState(fresh)).toEqual({});
+  });
+});
+
+// ── patchQuotaWatchState tests ────────────────────────────────────────────────
+
+describe("patchQuotaWatchState", () => {
+  it("adds a new account entry without clobbering others", () => {
+    const current: ReturnType<typeof emptyQuotaWatchState> = {
+      "alice@example.com": { lastNotifiedHealth: "throttling", lastNotifiedAt: 1000 },
+    };
+    const updated = patchQuotaWatchState(
+      current,
+      "bob@example.com",
+      { lastNotifiedHealth: "healthy", lastNotifiedAt: 2000 },
+    );
+    expect(updated["alice@example.com"]).toEqual({ lastNotifiedHealth: "throttling", lastNotifiedAt: 1000 });
+    expect(updated["bob@example.com"]).toEqual({ lastNotifiedHealth: "healthy", lastNotifiedAt: 2000 });
+  });
+
+  it("updates an existing account entry", () => {
+    const current = {
+      "alice@example.com": { lastNotifiedHealth: "throttling" as const, lastNotifiedAt: 1000 },
+    };
+    const updated = patchQuotaWatchState(
+      current,
+      "alice@example.com",
+      { lastNotifiedHealth: "healthy", lastNotifiedAt: 2000 },
+    );
+    expect(updated["alice@example.com"]).toEqual({ lastNotifiedHealth: "healthy", lastNotifiedAt: 2000 });
+  });
+
+  it("does not mutate the original state object", () => {
+    const current = {
+      "alice@example.com": { lastNotifiedHealth: "throttling" as const, lastNotifiedAt: 1000 },
+    };
+    patchQuotaWatchState(current, "bob@example.com", { lastNotifiedHealth: null, lastNotifiedAt: 0 });
+    expect(current["bob@example.com"]).toBeUndefined();
+  });
+});

package/telegram-plugin/tests/tool-activity-summary.test.ts

@@ -5,8 +5,74 @@ import {
   formatSummary,
   registerAndRender,
   verbForTool,
+  describeToolUse,
 } from "../tool-activity-summary.js";
 
+describe("describeToolUse — friendly per-tool rendering (draft-mirror)", () => {
+  it("Bash uses the model-authored description verbatim, never the command", () => {
+    expect(
+      describeToolUse("Bash", { command: "ls -la /tmp", description: "List workspace" }),
+    ).toBe("List workspace");
+    // No description → safe generic, still never the raw command.
+    expect(describeToolUse("Bash", { command: "grep -r foo ." })).toBe("Running a command");
+  });
+
+  it("Read/Edit/Write render the file basename, not the full path", () => {
+    expect(describeToolUse("Read", { file_path: "/home/ken/code/switchroom/gateway.ts" })).toBe(
+      "Reading gateway.ts",
+    );
+    expect(describeToolUse("Edit", { file_path: "/a/b/CLAUDE.md" })).toBe("Editing CLAUDE.md");
+    expect(describeToolUse("Write", { file_path: "notes.txt" })).toBe("Writing notes.txt");
+    expect(describeToolUse("Read", {})).toBe("Reading a file");
+  });
+
+  it("Grep/Glob show the pattern; WebFetch shows the hostname", () => {
+    expect(describeToolUse("Grep", { pattern: "TODO" })).toBe("Searching for TODO");
+    expect(describeToolUse("WebFetch", { url: "https://www.example.com/path?q=1" })).toBe(
+      "Reading example.com",
+    );
+    expect(describeToolUse("WebSearch", { query: "best running shoes" })).toBe(
+      "Searching the web for best running shoes",
+    );
+  });
+
+  it("Task/Agent surface the sub-agent task description", () => {
+    expect(describeToolUse("Task", { description: "Review the migration" })).toBe(
+      "Delegating: Review the migration",
+    );
+  });
+
+  it("domain MCP tools render human-meaningful labels (no jargon)", () => {
+    expect(describeToolUse("mcp__hindsight__reflect", { query: "x" })).toBe("Searching memory");
+    expect(describeToolUse("mcp__hindsight__retain", {})).toBe("Saving to memory");
+    expect(describeToolUse("mcp__claude_ai_Google_Calendar__list_events", {})).toBe(
+      "Checking your calendar",
+    );
+    expect(describeToolUse("mcp__claude_ai_Gmail__search", {})).toBe("Checking your email");
+    expect(describeToolUse("mcp__claude_ai_Google_Drive__search_files", {})).toBe(
+      "Looking through your files",
+    );
+    expect(describeToolUse("mcp__claude_ai_Notion__notion-search", {})).toBe("Checking your notes");
+  });
+
+  it("surface tools (reply/stream_reply) return null — never mirrored", () => {
+    expect(describeToolUse("mcp__switchroom-telegram__reply", { text: "hi" })).toBeNull();
+    expect(describeToolUse("mcp__switchroom-telegram__stream_reply", {})).toBeNull();
+  });
+
+  it("unknown MCP tool prefers a model-authored field, else humanizes the name", () => {
+    expect(describeToolUse("mcp__acme__do_thing", { description: "Fetched the report" })).toBe(
+      "Fetched the report",
+    );
+    expect(describeToolUse("mcp__acme__do_thing", {})).toBe("Using do thing");
+  });
+
+  it("unknown built-in falls back to a generic working line, never raw syntax", () => {
+    expect(describeToolUse("SomeFutureTool", {})).toBe("Working…");
+    expect(describeToolUse("", {})).toBeNull();
+  });
+});
+
 describe("verbForTool — tool name → past-tense verb", () => {
   it("maps standard CLI tools to readable verbs", () => {
     expect(verbForTool("Read")).toBe("read");

package/telegram-plugin/tests/turn-flush-safety.test.ts

@@ -17,9 +17,57 @@ import { describe, it, expect } from 'vitest'
 import {
   decideTurnFlush,
   isSilentFlushMarker,
+  isCompositeSilentNoise,
   isTurnFlushSafetyEnabled,
 } from '../turn-flush-safety.js'
 
+describe('isCompositeSilentNoise — Stop-hook re-prompt leak backstop', () => {
+  it('suppresses the observed leak "Sent.\\nNO_REPLY\\nNO_REPLY"', () => {
+    expect(isCompositeSilentNoise('Sent.\nNO_REPLY\nNO_REPLY')).toBe(true)
+  })
+  it('suppresses repeated bare markers and marker+confirmation variants', () => {
+    expect(isCompositeSilentNoise('NO_REPLY\nNO_REPLY')).toBe(true)
+    expect(isCompositeSilentNoise('Done\nNO_REPLY')).toBe(true)
+    expect(isCompositeSilentNoise('NO_REPLY\nHEARTBEAT_OK')).toBe(true)
+  })
+  it('requires at least one real marker — standalone confirmations still flush', () => {
+    // Conservative: no NO_REPLY/HEARTBEAT_OK present → NOT suppressed here,
+    // so we never silently drop a turn that wasn\'t already signalling silence.
+    expect(isCompositeSilentNoise('Sent.')).toBe(false)
+    expect(isCompositeSilentNoise('Done.\nOK')).toBe(false)
+  })
+  it('does NOT suppress real content glued to a marker', () => {
+    expect(
+      isCompositeSilentNoise('Here is the summary of the page.\nNO_REPLY'),
+    ).toBe(false)
+    expect(isCompositeSilentNoise('NO_REPLY\nThe answer is 42.')).toBe(false)
+  })
+  it('handles non-strings / empty safely', () => {
+    expect(isCompositeSilentNoise(undefined)).toBe(false)
+    expect(isCompositeSilentNoise('')).toBe(false)
+    expect(isCompositeSilentNoise('   \n  ')).toBe(false)
+  })
+})
+
+describe('decideTurnFlush — composite silent noise is skipped, not leaked', () => {
+  it('skips "Sent.\\nNO_REPLY\\nNO_REPLY" (the live clerk/test-harness leak)', () => {
+    const d = decideTurnFlush({
+      chatId: '12345',
+      replyCalled: false,
+      capturedText: ['Sent.', 'NO_REPLY', 'NO_REPLY'],
+    })
+    expect(d).toEqual({ kind: 'skip', reason: 'silent-marker' })
+  })
+  it('still flushes genuine trailing answer text', () => {
+    const d = decideTurnFlush({
+      chatId: '12345',
+      replyCalled: false,
+      capturedText: ['The page summarises three news stories.'],
+    })
+    expect(d.kind).toBe('flush')
+  })
+})
+
 describe('decideTurnFlush', () => {
   it('(a) does NOT flush when the reply tool was called', () => {
     const decision = decideTurnFlush({

package/telegram-plugin/tool-activity-summary.ts

@@ -198,3 +198,140 @@ export function registerAndRender(
   if (!changed) return null;
   return formatSummary(state);
 }
+
+// ─── Friendly per-tool rendering (draft-mirror, RFC draft-mirror-preview) ───
+//
+// Claude Code's own UI reads human-friendly because the model AUTHORS the
+// descriptive text inside each tool_use.input — verified against a real
+// session JSONL (1360 Bash calls etc.):
+//   Bash         → input.description   ("Get CLAUDE.md size and recent history")
+//   Read         → input.file_path     (basename → "Reading CLAUDE.md")
+//   Edit/Write   → input.file_path     (basename)
+//   Grep/Glob    → input.pattern
+//   Task/Agent   → input.description   (the sub-agent's task)
+//   WebFetch     → input.url           (hostname → "Reading example.com")
+//   hindsight    → friendly label      ("Searching memory")
+// There is never a raw `grep`/`jq`/`ls` to surface — only the model's own
+// plain-English description or a domain label. This is the signal the
+// draft-mirror renders (option A: uniform across code + non-code agents).
+
+/** Strip a path to its basename for display. */
+function baseName(p: unknown): string | null {
+  if (typeof p !== "string" || p.length === 0) return null;
+  const parts = p.split("/").filter(Boolean);
+  return parts.length > 0 ? parts[parts.length - 1] : p;
+}
+
+/** Extract a bare hostname from a URL for display (no scheme/path). */
+function hostName(u: unknown): string | null {
+  if (typeof u !== "string" || u.length === 0) return null;
+  try {
+    return new URL(u).hostname.replace(/^www\./, "");
+  } catch {
+    return u.replace(/^https?:\/\//, "").split("/")[0] || null;
+  }
+}
+
+function clip(s: unknown, n: number): string | null {
+  if (typeof s !== "string") return null;
+  const t = s.trim();
+  if (t.length === 0) return null;
+  return t.length > n ? t.slice(0, n - 1) + "…" : t;
+}
+
+/**
+ * Render a single tool_use into a human-friendly, present-tense activity
+ * line for the live draft preview — or null when the tool should NOT be
+ * surfaced (the Telegram-plugin surface tools, which ARE the conversation).
+ *
+ * Leads with the model-authored descriptive field per the map above; falls
+ * back to a domain label, then to a humanized tool name. Never emits raw
+ * shell/query syntax.
+ */
+export function describeToolUse(
+  toolName: string,
+  input: Record<string, unknown> | undefined,
+): string | null {
+  if (!toolName) return null;
+  const inp = input ?? {};
+
+  const mcpMatch = /^mcp__(.+?)__(.+)$/.exec(toolName);
+  if (mcpMatch) {
+    const server = mcpMatch[1].toLowerCase();
+    const tool = mcpMatch[2].toLowerCase();
+    // Surface tools ARE the conversation — never mirror them.
+    if (server === "switchroom-telegram") return null;
+    if (server === "hindsight") {
+      if (tool === "recall" || tool === "reflect") return "Searching memory";
+      if (tool === "retain" || tool === "update_memory" || tool === "sync_retain")
+        return "Saving to memory";
+      return "Working with memory";
+    }
+    if (
+      server === "google-workspace" ||
+      server === "claude_ai_google_calendar"
+    ) {
+      return "Checking your calendar";
+    }
+    if (server === "claude_ai_gmail") return "Checking your email";
+    if (server === "claude_ai_google_drive") return "Looking through your files";
+    if (server === "notion" || server === "claude_ai_notion") {
+      return "Checking your notes";
+    }
+    // Unknown MCP tool: prefer a model-authored field, else a humanized name.
+    const desc = clip(inp.description, 60) ?? clip(inp.query, 50) ?? clip(inp.title, 50);
+    if (desc) return desc;
+    return "Using " + tool.replace(/[-_]+/g, " ");
+  }
+
+  switch (toolName) {
+    case "Bash": {
+      // The model writes a plain-English description for every command.
+      return clip(inp.description, 70) ?? "Running a command";
+    }
+    case "BashOutput":
+    case "KillShell":
+      return "Managing a background command";
+    case "Read": {
+      const f = baseName(inp.file_path);
+      return f ? `Reading ${f}` : "Reading a file";
+    }
+    case "Edit":
+    case "MultiEdit":
+    case "NotebookEdit": {
+      const f = baseName(inp.file_path) ?? baseName(inp.notebook_path);
+      return f ? `Editing ${f}` : "Editing a file";
+    }
+    case "Write": {
+      const f = baseName(inp.file_path);
+      return f ? `Writing ${f}` : "Writing a file";
+    }
+    case "Grep":
+    case "Glob": {
+      const p = clip(inp.pattern, 40);
+      return p ? `Searching for ${p}` : "Searching files";
+    }
+    case "WebFetch": {
+      const h = hostName(inp.url);
+      return h ? `Reading ${h}` : "Reading a web page";
+    }
+    case "WebSearch": {
+      const q = clip(inp.query, 50);
+      return q ? `Searching the web for ${q}` : "Searching the web";
+    }
+    case "Task":
+    case "Agent": {
+      const d = clip(inp.description, 60);
+      return d ? `Delegating: ${d}` : "Delegating to a sub-agent";
+    }
+    case "TodoWrite":
+    case "TaskCreate":
+    case "TaskUpdate":
+    case "TaskList":
+      return "Updating the plan";
+    case "ToolSearch":
+      return "Finding the right tool";
+    default:
+      return "Working…";
+  }
+}