switchroom 0.13.57 → 0.13.58

package/telegram-plugin/gateway/gateway.ts

@@ -53,7 +53,12 @@ import { OutboundDedupCache } from '../recent-outbound-dedup.js'
 import { createInboundCoalescer, inboundCoalesceKey } from './inbound-coalesce.js'
 import { StatusReactionController } from '../status-reactions.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
-import { deriveIntentSurface } from '../tool-intent-surface.js'
+import { allocateDraftId } from '../draft-transport.js'
+import {
+  makeEmptyActivityState,
+  registerAndRender,
+  type ActivityState,
+} from '../tool-activity-summary.js'
 import { toolLabel } from '../tool-labels.js'
 import { createTypingWrapper } from '../typing-wrap.js'
 import { type DraftStreamHandle } from '../draft-stream.js'
@@ -1292,15 +1297,39 @@ type CurrentTurn = {
   // Phase 1 of #332: count of tool_use events in the current turn, for
   // the tool_call_count column in the turns registry.
   toolCallCount: number
-  // Tool-intent surface (the human-feel UX follow-up to #1921's
-  // PreToolUse gate). When the model emits its first non-reply tool_use
-  // of a turn AND no outbound has happened yet, the gateway lifts the
-  // tool's already-formed intent (name + input → `toolLabel()`) into a
-  // user-visible "<i>running</i>: ls -la /var/log" message. One-shot
-  // per turn — subsequent tool_use events stay quiet so a multi-tool
-  // turn doesn't spam. The model never has to call reply just to ack;
-  // its own intent stream IS the ack source.
-  intentSurfaceFired: boolean
+  // Tool-activity summary — mirrors Claude Code's native chat-UI
+  // rendering ("Ran 5 commands, read a file"). Counters are
+  // incremented in `case 'tool_use'`; `activityMessageId` holds the
+  // Telegram message id we send/edit so a single message accumulates
+  // the summary in place. Stops updating once `replyCalled` flips —
+  // the model's own reply lands below the summary as the actual
+  // content.
+  //
+  // Parallel-tool-use coalescing (PR #1926 review): modern Claude
+  // emits multiple tool_uses in a tight synchronous loop (e.g. 3
+  // parallel Reads). Without coalescing, each would see
+  // `activityMessageId == null` and fire its own sendMessage,
+  // producing N messages instead of one editable summary. Pattern
+  // mirrors `telegram-plugin/answer-stream.ts`:
+  //   - `activityInFlight` — promise that resolves when the current
+  //     send/edit settles. While set, NEW tool_uses just update
+  //     `activityState` and `activityPendingRender` and return.
+  //   - When the in-flight resolves, it picks the latest
+  //     `activityPendingRender`, fires the next send/edit, and
+  //     repeats until the pending matches the last-sent.
+  // Result: at most one Telegram call in flight at a time; the
+  // final state always lands.
+  toolActivity: ActivityState
+  activityMessageId: number | null
+  // Draft-transport id when the activity summary is streamed via
+  // sendMessageDraft (DM-only, no thread). Each call to
+  // sendMessageDraft(chat, draftId, text) REPLACES the draft text —
+  // simpler than send+edit. Cleared by `clearActivitySummary` (which
+  // sends an empty draft) when the model's reply takes over.
+  activityDraftId: number | null
+  activityInFlight: Promise<void> | null
+  activityPendingRender: string | null
+  activityLastSentRender: string | null
   // Issue #195 — answer-lane streaming. Lazily created on the first text
   // event of a turn (once enough text has accumulated, the stream itself
   // gates on minInitialChars). Materialized and cleared at turn_end.
@@ -6777,6 +6806,120 @@ function closeProgressLane(chatId: string, threadId: number | undefined): void {
   }
 }
 
+/**
+ * Drain the tool-activity summary's pending render queue. Single-flight
+ * by construction (caller assigns the returned promise to
+ * `turn.activityInFlight`; while set, new tool_uses only update
+ * `turn.activityPendingRender` and return).
+ *
+ * Transport priority (mirrors the existing answer-stream pattern):
+ *
+ *   1. DM with no thread AND sendMessageDraft API available →
+ *      DRAFT TRANSPORT. Each call REPLACES the draft text (no
+ *      edit-in-place needed); the user sees a live preview in their
+ *      Telegram compose area as the agent works. When the model's
+ *      reply tool lands, `clearActivitySummary` sends an empty draft
+ *      to wipe it — only the real reply persists.
+ *
+ *   2. Anything else (forum topic, draft API absent) → fall through
+ *      to sendMessage + editMessageText. The activity message is a
+ *      real chat message; `clearActivitySummary` deletes it when the
+ *      reply tool takes over.
+ *
+ * The drain holds a reference to `turn`, so a turn-swap mid-drain
+ * doesn't corrupt the next turn's atom — late writes land on the
+ * captured `turn` (already-completed turn, harmless).
+ */
+async function drainActivitySummary(turn: CurrentTurn): Promise<void> {
+  try {
+    while (turn.activityPendingRender !== turn.activityLastSentRender) {
+      const target = turn.activityPendingRender
+      if (target == null) break
+      const html = `<i>${target}</i>`
+      const chat = turn.sessionChatId
+      const thread = turn.sessionThreadId
+      // sendMessageDraft doesn't support forum threads.
+      const useDraft = turn.isDm && thread == null && sendMessageDraftFn != null
+      try {
+        if (useDraft) {
+          if (turn.activityDraftId == null) {
+            turn.activityDraftId = allocateDraftId()
+          }
+          const draftId = turn.activityDraftId
+          await sendMessageDraftFn!(chat, draftId, html, undefined)
+        } else if (turn.activityMessageId == null) {
+          const sent = await robustApiCall(
+            () => bot.api.sendMessage(chat, html, {
+              ...(thread != null ? { message_thread_id: thread } : {}),
+              parse_mode: 'HTML',
+              disable_notification: true,
+            }),
+            { chat_id: chat, ...(thread != null ? { threadId: thread } : {}), verb: 'activity-summary.send' },
+          )
+          turn.activityMessageId = sent.message_id
+        } else {
+          const id = turn.activityMessageId
+          await robustApiCall(
+            () => bot.api.editMessageText(chat, id, html, { parse_mode: 'HTML' }),
+            { chat_id: chat, ...(thread != null ? { threadId: thread } : {}), verb: 'activity-summary.edit' },
+          )
+        }
+        turn.activityLastSentRender = target
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        if (!msg.includes('message is not modified')) {
+          process.stderr.write(`telegram gateway: activity-summary drain failed: ${msg}\n`)
+        }
+        // Mark as sent so we don't infinite-loop on a stuck render.
+        turn.activityLastSentRender = target
+      }
+    }
+  } finally {
+    turn.activityInFlight = null
+  }
+}
+
+/**
+ * Clear the activity summary when the model's reply tool takes over
+ * as the authoritative surface. Awaits any in-flight render so we
+ * don't race a stale write against the clear, then either sends an
+ * empty draft (clears the compose-area preview) or deletes the
+ * persisted message. Idempotent + best-effort — failure stderr-logs
+ * but does not block.
+ *
+ * Called from `case 'tool_use'` the moment we see a Telegram reply
+ * tool fire, so the user sees the real reply land in the same beat
+ * the summary disappears.
+ */
+function clearActivitySummary(turn: CurrentTurn): void {
+  const chat = turn.sessionChatId
+  const thread = turn.sessionThreadId
+  const inFlight = turn.activityInFlight ?? Promise.resolve()
+  void inFlight.then(async () => {
+    if (turn.activityDraftId != null && sendMessageDraftFn != null) {
+      const draftId = turn.activityDraftId
+      turn.activityDraftId = null
+      try {
+        // Empty text → Telegram clears the draft.
+        await sendMessageDraftFn(chat, draftId, '', undefined)
+      } catch (err) {
+        process.stderr.write(`telegram gateway: activity-summary draft-clear failed: ${err}\n`)
+      }
+    } else if (turn.activityMessageId != null) {
+      const id = turn.activityMessageId
+      turn.activityMessageId = null
+      try {
+        await robustApiCall(
+          () => bot.api.deleteMessage(chat, id),
+          { chat_id: chat, ...(thread != null ? { threadId: thread } : {}), verb: 'activity-summary.delete' },
+        )
+      } catch (err) {
+        process.stderr.write(`telegram gateway: activity-summary delete failed: ${err}\n`)
+      }
+    }
+  })
+}
+
 function handleSessionEvent(ev: SessionEvent): void {
   switch (ev.kind) {
     case 'enqueue': {
@@ -6842,7 +6985,12 @@ function handleSessionEvent(ev: SessionEvent): void {
           lastAssistantMsgId: null,
           lastAssistantDone: false,
           toolCallCount: 0,
-          intentSurfaceFired: false,
+          toolActivity: makeEmptyActivityState(),
+          activityMessageId: null,
+          activityDraftId: null,
+          activityInFlight: null,
+          activityPendingRender: null,
+          activityLastSentRender: null,
           answerStream: null,
           isDm: isDmChatId(ev.chatId),
         }
@@ -6954,70 +7102,56 @@ function handleSessionEvent(ev: SessionEvent): void {
       // Phase tracking removed in #553 PR 5 — phases only fed the
       // placeholder-heartbeat label, which has been retired.
       if (isTelegramReplyTool(name)) {
+        const wasFirstReply = !turn.replyCalled
         turn.replyCalled = true
         if (turn.orphanedReplyTimeoutId != null) {
           clearTimeout(turn.orphanedReplyTimeoutId)
           turn.orphanedReplyTimeoutId = null
         }
+        // The model's real reply takes over as the authoritative
+        // surface. Clear the activity summary — for drafts, send an
+        // empty draft to wipe the compose-area preview; for persisted
+        // messages, delete. The user sees the real reply land in the
+        // same beat the summary disappears.
+        if (wasFirstReply) {
+          clearActivitySummary(turn)
+        }
       }
       // Tool-intent surface — companion to the PreToolUse ack-first gate
       // (#1921). On the FIRST non-reply tool_use of a turn AND only when
-      // no outbound has happened yet, the gateway lifts the model's tool
-      // intent (name + input → `toolLabel()`) into a brief framework-voice
-      // status: `<i>running:</i> ls -la /var/log`. The model never has to
-      // call reply just to ack — its own intent stream IS the ack. The
-      // gate continues to fire IN PARALLEL: if it produces a model-voice
-      // ack first (`replyCalled=true`), the surface stays quiet by the
-      // condition below. One-shot per turn.
-      if (
-        !turn.replyCalled
-        && !turn.intentSurfaceFired
-        && !isTelegramSurfaceTool(name)
-      ) {
-        turn.intentSurfaceFired = true
-        // `ev.input` is the canonical SessionEvent property
-        // (`telegram-plugin/session-tail.ts:95`). All other tool_use
-        // sites in this file use `ev.input` — keep that consistent.
-        const surface = deriveIntentSurface(name, ev.input, ev.precomputedLabel)
-        if (surface.text != null) {
-          // Mark the ack-flag synchronously BEFORE the async send so a
-          // PreToolUse ack-first hook (#1921) firing concurrently for this
-          // same tool call sees the flag already present and allows the
-          // tool through. The Telegram send is fire-and-forget; failure
+      // Tool-activity summary — same shape Claude Code natively renders
+      // in its CLI/chat UI ("Ran 5 commands, read a file"). The gateway
+      // accumulates non-reply tool_use events into `turn.toolActivity`
+      // and sends ONE Telegram message that edits in place as more tools
+      // land. Stops editing once the model calls `reply` — the summary
+      // line stays as the final state. No model-side prompting; no per-
+      // tool labels. Just surface what's already in the stream.
+      //
+      // Single-flight coalescing (PR #1926 review): modern Claude emits
+      // multiple tool_uses in a synchronous burst (parallel Reads,
+      // Bashes, etc.). All would otherwise race past the message-id
+      // capture and produce N messages. Pattern mirrors answer-stream:
+      // update `activityPendingRender` synchronously here; a single
+      // worker promise drains the pending state, sending or editing
+      // exactly once at a time and re-running until pending matches
+      // the last-sent. Captures `turn` so a late drain after turn-swap
+      // can't corrupt the next turn's atom.
+      if (!turn.replyCalled && !isTelegramSurfaceTool(name)) {
+        const rendered = registerAndRender(turn.toolActivity, name)
+        if (rendered != null) {
+          // Mark the ack-flag synchronously so a PreToolUse hook firing
+          // concurrently for THIS tool call (#1921) sees the flag set
+          // and allows the tool through. The drain runs async; failure
           // is logged but does not block the model.
           try {
             markAckSent()
           } catch (err) {
-            process.stderr.write(`telegram gateway: intent-surface markAckSent failed: ${err}\n`)
+            process.stderr.write(`telegram gateway: activity-summary markAckSent failed: ${err}\n`)
+          }
+          turn.activityPendingRender = rendered
+          if (turn.activityInFlight == null) {
+            turn.activityInFlight = drainActivitySummary(turn)
           }
-          const surfaceChat = turn.sessionChatId
-          const surfaceThread = turn.sessionThreadId
-          const surfaceText = surface.text
-          void (async () => {
-            try {
-              await robustApiCall(
-                () => bot.api.sendMessage(surfaceChat, surfaceText, {
-                  ...(surfaceThread != null ? { message_thread_id: surfaceThread } : {}),
-                  parse_mode: 'HTML',
-                  // Framework-narrating beat — silent, ambient, not a
-                  // device buzz. The user is meant to glance and know
-                  // the model is alive + on-task.
-                  disable_notification: true,
-                }),
-                { chat_id: surfaceChat, ...(surfaceThread != null ? { threadId: surfaceThread } : {}), verb: 'intent-surface' },
-              )
-              // Deliberately NOT calling signalTracker.noteOutbound /
-              // silencePoke.noteOutbound here — framework-owned
-              // ambient messages are not model-author outbounds, so
-              // they should not reset the TTFO clock or short-circuit
-              // the silence-poke ladder. Mirrors the sibling
-              // `onAwarenessPing` handler (silence-poke.ts:169
-              // contract: "Caller must NOT call back into noteOutbound
-              // for this — it's a framework-sourced message").
-            } catch (err) {
-              process.stderr.write(`telegram gateway: intent-surface send failed: ${err}\n`)
-            }
-          })()
         }
       }
       if (!ctrl) return

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

@@ -0,0 +1,191 @@
+import { describe, it, expect } from "vitest";
+import {
+  makeEmptyActivityState,
+  register,
+  formatSummary,
+  registerAndRender,
+  verbForTool,
+} from "../tool-activity-summary.js";
+
+describe("verbForTool — tool name → past-tense verb", () => {
+  it("maps standard CLI tools to readable verbs", () => {
+    expect(verbForTool("Read")).toBe("read");
+    expect(verbForTool("Write")).toBe("created");
+    expect(verbForTool("Edit")).toBe("edited");
+    expect(verbForTool("MultiEdit")).toBe("edited");
+    expect(verbForTool("NotebookEdit")).toBe("edited");
+    expect(verbForTool("Bash")).toBe("ran");
+    expect(verbForTool("BashOutput")).toBe("ran");
+    expect(verbForTool("WebSearch")).toBe("searched");
+    expect(verbForTool("Grep")).toBe("searched");
+    expect(verbForTool("Glob")).toBe("searched");
+    expect(verbForTool("WebFetch")).toBe("fetched");
+    expect(verbForTool("Task")).toBe("dispatched");
+    expect(verbForTool("Agent")).toBe("dispatched");
+    expect(verbForTool("TodoWrite")).toBe("noted");
+  });
+
+  it("skips user-facing switchroom-telegram tools (those ARE the surface)", () => {
+    expect(verbForTool("mcp__switchroom-telegram__reply")).toBeNull();
+    expect(verbForTool("mcp__switchroom-telegram__stream_reply")).toBeNull();
+    expect(verbForTool("mcp__switchroom-telegram__edit_message")).toBeNull();
+    expect(verbForTool("mcp__switchroom-telegram__react")).toBeNull();
+  });
+
+  it("returns 'used' for unknown / non-switchroom MCP tools", () => {
+    expect(verbForTool("mcp__google-workspace__list_files")).toBe("used");
+    expect(verbForTool("mcp__notion__query_database")).toBe("used");
+    expect(verbForTool("SomeFutureUnknownTool")).toBe("used");
+  });
+
+  it("returns null for empty toolName (defensive)", () => {
+    expect(verbForTool("")).toBeNull();
+  });
+});
+
+describe("register + formatSummary — Claude Code-style summary", () => {
+  it("formats a single Read as 'Read a file'", () => {
+    const s = makeEmptyActivityState();
+    register(s, "Read");
+    expect(formatSummary(s)).toBe("Read a file");
+  });
+
+  it("formats multiple Reads as 'Read N files'", () => {
+    const s = makeEmptyActivityState();
+    register(s, "Read");
+    register(s, "Read");
+    register(s, "Read");
+    expect(formatSummary(s)).toBe("Read 3 files");
+  });
+
+  it("formats single Bash as 'Ran a command'", () => {
+    const s = makeEmptyActivityState();
+    register(s, "Bash");
+    expect(formatSummary(s)).toBe("Ran a command");
+  });
+
+  it("formats multiple Bash as 'Ran N commands'", () => {
+    const s = makeEmptyActivityState();
+    for (let i = 0; i < 5; i++) register(s, "Bash");
+    expect(formatSummary(s)).toBe("Ran 5 commands");
+  });
+
+  it("joins multiple verb-classes with commas (first-occurrence order)", () => {
+    const s = makeEmptyActivityState();
+    // Tools fire in this order: Read → Bash → Edit
+    register(s, "Read");
+    register(s, "Bash");
+    register(s, "Edit");
+    // The summary renders chronologically: read, ran, edited.
+    expect(formatSummary(s)).toBe("Read a file, ran a command, edited a file");
+  });
+
+  it("matches the Claude Code screenshot examples", () => {
+    // "Ran 5 commands, read a file"
+    const s1 = makeEmptyActivityState();
+    for (let i = 0; i < 5; i++) register(s1, "Bash");
+    register(s1, "Read");
+    expect(formatSummary(s1)).toBe("Ran 5 commands, read a file");
+
+    // "Edited a file, read a file, ran a command"
+    const s2 = makeEmptyActivityState();
+    register(s2, "Edit");
+    register(s2, "Read");
+    register(s2, "Bash");
+    expect(formatSummary(s2)).toBe("Edited a file, read a file, ran a command");
+
+    // "Created a file, ran a command"
+    const s3 = makeEmptyActivityState();
+    register(s3, "Write");
+    register(s3, "Bash");
+    expect(formatSummary(s3)).toBe("Created a file, ran a command");
+  });
+
+  it("returns null when state is empty", () => {
+    expect(formatSummary(makeEmptyActivityState())).toBeNull();
+  });
+
+  it("ignores user-facing tools (reply/stream_reply etc.)", () => {
+    const s = makeEmptyActivityState();
+    register(s, "mcp__switchroom-telegram__reply");
+    register(s, "mcp__switchroom-telegram__stream_reply");
+    expect(formatSummary(s)).toBeNull(); // nothing tracked
+  });
+
+  it("includes generic 'used' for unknown MCP tools", () => {
+    const s = makeEmptyActivityState();
+    register(s, "mcp__google-workspace__list_files");
+    expect(formatSummary(s)).toBe("Used a tool");
+    register(s, "mcp__google-workspace__create_file");
+    expect(formatSummary(s)).toBe("Used 2 tools");
+  });
+
+  it("tracks firstToolName for forensic / telemetry use", () => {
+    const s = makeEmptyActivityState();
+    register(s, "Read");
+    register(s, "Bash");
+    expect(s.firstToolName).toBe("Read");
+  });
+});
+
+describe("parallel-tool-use coalescing — render only reflects accumulated state", () => {
+  it("synchronous burst of N tool_uses produces the right summary at each step", () => {
+    // Modern Claude emits parallel tool_uses in a tight sync loop. The
+    // gateway calls register() N times before any async drain runs.
+    // After N registers, the rendered string should reflect ALL of them
+    // — so when the drain fires once with the latest pendingRender, the
+    // sent text is correct and complete.
+    const s = makeEmptyActivityState();
+    register(s, "Read");
+    register(s, "Read");
+    register(s, "Read");
+    register(s, "Bash");
+    register(s, "Bash");
+    expect(formatSummary(s)).toBe("Read 3 files, ran 2 commands");
+  });
+
+  it("ordering is preserved across a chronological burst", () => {
+    const s = makeEmptyActivityState();
+    // Simulates: Bash, then Read, then Bash, then Read, then Edit
+    register(s, "Bash");
+    register(s, "Read");
+    register(s, "Bash");
+    register(s, "Read");
+    register(s, "Edit");
+    // Bash was first, then Read, then Edit. Counts: bash 2, read 2, edit 1.
+    expect(formatSummary(s)).toBe(
+      "Ran 2 commands, read 2 files, edited a file",
+    );
+  });
+
+  it("registerAndRender returns null on user-facing tools (no race contribution)", () => {
+    const s = makeEmptyActivityState();
+    register(s, "Read");
+    // A reply tool fires concurrently — should not enter the activity state.
+    expect(
+      registerAndRender(s, "mcp__switchroom-telegram__reply"),
+    ).toBeNull();
+    // State still reflects only the Read.
+    expect(formatSummary(s)).toBe("Read a file");
+  });
+});
+
+describe("registerAndRender — ergonomic full-pipeline call", () => {
+  it("returns the updated rendered text on a real tool (chronological)", () => {
+    const s = makeEmptyActivityState();
+    expect(registerAndRender(s, "Read")).toBe("Read a file");
+    // Bash fires AFTER Read — chronological order shows read first.
+    expect(registerAndRender(s, "Bash")).toBe(
+      "Read a file, ran a command",
+    );
+  });
+
+  it("returns null on a surface tool (no-op)", () => {
+    const s = makeEmptyActivityState();
+    expect(
+      registerAndRender(s, "mcp__switchroom-telegram__reply"),
+    ).toBeNull();
+    // State unchanged
+    expect(s.firstToolName).toBeNull();
+  });
+});

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

@@ -0,0 +1,164 @@
+/**
+ * Tool-activity summary — Claude Code-style natural-language progress
+ * line that batches tool_use events for a turn into a single Telegram
+ * message that updates in place.
+ *
+ * Replaces the per-tool intent surface (#1924). The screenshot from
+ * Claude Code's own UI shows lines like:
+ *
+ *   "Ran 5 commands, read a file"
+ *   "Edited a file, read a file, ran a command"
+ *
+ * Past tense, comma-joined, singular/plural-aware. One message per
+ * "phase" (turn start → first reply), progressively edited as tools
+ * accumulate. NOT raw tool calls — descriptions of what the agent has
+ * been doing.
+ *
+ * Why this beats per-tool labels:
+ *   - One Telegram message per phase (low signal-to-noise vs N
+ *     messages on a heavy turn)
+ *   - The user sees ACCUMULATED work in a glanceable form, not a flood
+ *   - Plays nicely with the existing answer-lane stream that handles
+ *     the actual reply text
+ *
+ * Tracking shape: per-turn counters keyed by `verb` (the action class
+ * derived from tool name). One counter per verb so the summary line
+ * collapses neatly regardless of which specific Read/Bash/WebSearch
+ * the model chose. `register()` increments the counter; `formatSummary()`
+ * renders the current state.
+ */
+
+const READ_VERBS = new Set(["read"]);
+const WRITE_VERBS = new Set(["wrote", "created", "edited"]);
+
+export type ActivityVerb =
+  | "read"
+  | "edited"
+  | "created"
+  | "ran"
+  | "searched"
+  | "fetched"
+  | "dispatched"
+  | "noted"
+  | "used"; // generic fallback
+
+/** Object form so `register()` can mutate; pure functions inside the
+ *  module work against this shape (easier to unit-test than a Map). */
+export interface ActivityState {
+  counts: Partial<Record<ActivityVerb, number>>;
+  /** Order verbs were first observed this turn. The summary renders in
+   *  this order so the line reads as a chronological natural-language
+   *  account: "edited a file, read a file, ran a command" matches the
+   *  agent's actual sequence of actions. Stable — once a verb is added
+   *  to this list, it never moves. */
+  order: ActivityVerb[];
+  /** First non-trivial tool name observed this turn (for telemetry / future
+   *  "what kicked this off" forensic). Not used in the rendered summary. */
+  firstToolName: string | null;
+}
+
+export function makeEmptyActivityState(): ActivityState {
+  return { counts: {}, order: [], firstToolName: null };
+}
+
+/** Map a tool name → verb. Mirrors the existing `tool-intent-surface.ts`
+ *  verb table but in past tense. Tools that don't map (or surface tools
+ *  like reply/stream_reply) return null — the caller skips them. */
+export function verbForTool(toolName: string): ActivityVerb | null {
+  if (!toolName) return null;
+  const mcpMatch = /^mcp__([^_]+)__(.+)$/.exec(toolName);
+  // Skip user-facing Telegram-plugin tools entirely — those ARE the
+  // surface, never to be summarised.
+  if (mcpMatch && mcpMatch[1] === "switchroom-telegram") return null;
+  const suffix = (mcpMatch ? mcpMatch[2] : toolName).toLowerCase();
+  switch (suffix) {
+    case "read":
+      return "read";
+    case "write":
+      return "created";
+    case "edit":
+    case "multiedit":
+    case "notebookedit":
+      return "edited";
+    case "bash":
+    case "bashoutput":
+    case "killshell":
+      return "ran";
+    case "websearch":
+    case "grep":
+    case "glob":
+      return "searched";
+    case "webfetch":
+      return "fetched";
+    case "task":
+    case "agent":
+      return "dispatched";
+    case "todowrite":
+    case "todoread":
+      return "noted";
+    default:
+      return "used";
+  }
+}
+
+/** Mutates `state` to record one tool_use of `toolName`. Returns true
+ *  iff the activity state changed (so the caller knows to refresh the
+ *  rendered summary). */
+export function register(state: ActivityState, toolName: string): boolean {
+  const verb = verbForTool(toolName);
+  if (!verb) return false;
+  if (state.firstToolName == null) state.firstToolName = toolName;
+  const prior = state.counts[verb] ?? 0;
+  if (prior === 0) state.order.push(verb);
+  state.counts[verb] = prior + 1;
+  return true;
+}
+
+interface VerbPhrase {
+  singular: string;
+  plural: string;
+}
+
+const VERB_PHRASE: Record<ActivityVerb, VerbPhrase> = {
+  read: { singular: "read a file", plural: "read $N files" },
+  edited: { singular: "edited a file", plural: "edited $N files" },
+  created: { singular: "created a file", plural: "created $N files" },
+  ran: { singular: "ran a command", plural: "ran $N commands" },
+  searched: { singular: "ran a search", plural: "ran $N searches" },
+  fetched: { singular: "fetched a URL", plural: "fetched $N URLs" },
+  dispatched: { singular: "dispatched a sub-agent", plural: "dispatched $N sub-agents" },
+  noted: { singular: "updated the todo list", plural: "updated the todo list ($N edits)" },
+  used: { singular: "used a tool", plural: "used $N tools" },
+};
+
+/** Render the activity state as a single natural-language line.
+ *  Verbs are rendered in `state.order` — first-occurrence order — so
+ *  the line reads chronologically ("edited a file, read a file, ran
+ *  a command" mirrors the agent's actual action sequence). Returns
+ *  null when the state is empty (nothing to show yet). */
+export function formatSummary(state: ActivityState): string | null {
+  const phrases: string[] = [];
+  for (const verb of state.order) {
+    const n = state.counts[verb] ?? 0;
+    if (n <= 0) continue;
+    const p = VERB_PHRASE[verb];
+    phrases.push(n === 1 ? p.singular : p.plural.replace("$N", String(n)));
+  }
+  if (phrases.length === 0) return null;
+  // Capitalize first letter so the sentence reads as a statement.
+  const sentence = phrases.join(", ");
+  return sentence.charAt(0).toUpperCase() + sentence.slice(1);
+}
+
+/** Convenience: ergonomic full pipeline for callers that just want
+ *  "given the new tool name and prior state, give me the updated rendered
+ *  text or null if nothing changed". Returns null when the tool is a
+ *  surface tool / no-op (so the caller can skip the Telegram edit). */
+export function registerAndRender(
+  state: ActivityState,
+  toolName: string,
+): string | null {
+  const changed = register(state, toolName);
+  if (!changed) return null;
+  return formatSummary(state);
+}