switchroom 0.13.65 → 0.14.0

package/telegram-plugin/gateway/gateway.ts

@@ -57,6 +57,7 @@ import { allocateDraftId } from '../draft-transport.js'
 import {
   makeEmptyActivityState,
   registerAndRender,
+  describeToolUse,
   type ActivityState,
 } from '../tool-activity-summary.js'
 import { toolLabel } from '../tool-labels.js'
@@ -6837,7 +6838,12 @@ async function drainActivitySummary(turn: CurrentTurn): Promise<void> {
     while (turn.activityPendingRender !== turn.activityLastSentRender) {
       const target = turn.activityPendingRender
       if (target == null) break
-      const html = `<i>${target}</i>`
+      // Escape before wrapping in <i> + parse_mode HTML. The legacy
+      // verb-count summaries were safe ASCII, but the draft-mirror's
+      // describeToolUse content (file names, Bash descriptions, search
+      // queries) can contain <, >, & — which would break HTML parsing
+      // and surface literal tags (the exact #1942 bug class).
+      const html = `<i>${escapeHtmlForTg(target)}</i>`
       const chat = turn.sessionChatId
       const thread = turn.sessionThreadId
       // sendMessageDraft doesn't support forum threads.
@@ -7130,14 +7136,21 @@ function handleSessionEvent(ev: SessionEvent): void {
       // 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.
-      // DRAFT_MIRROR (RFC draft-mirror-preview, Phase 1): the model's
-      // prose narration owns the single per-chat draft slot. Suppress
-      // the activity-summary tool-count draft so the two don't collide
-      // (Telegram shows one draft per chat — the later write clobbers
-      // the earlier). The activity-summary code stays intact for the
-      // kill-switch path; it's retired for good only in Phase 4.
-      if (!DRAFT_MIRROR_ENABLED && !turn.replyCalled && !isTelegramSurfaceTool(name)) {
-        const rendered = registerAndRender(turn.toolActivity, name)
+      // DRAFT_MIRROR (RFC draft-mirror-preview): render each tool_use as a
+      // human-friendly line in the live preview, using the model-authored
+      // descriptive field (Bash.description, Read/Edit file basename,
+      // hindsight→"Searching memory", etc. — see describeToolUse). Latest
+      // action wins (the draft shows "doing X" live), clears on reply.
+      // Never surfaces raw shell/query syntax — option A, uniform across
+      // code + non-code agents.
+      //
+      // Flag OFF (default): the legacy generic verb-count summary
+      // ("Ran 5 commands") via registerAndRender — byte-identical to
+      // pre-draft-mirror behavior.
+      if (!turn.replyCalled && !isTelegramSurfaceTool(name)) {
+        const rendered = DRAFT_MIRROR_ENABLED
+          ? describeToolUse(name, ev.input)
+          : registerAndRender(turn.toolActivity, name)
         if (rendered != null) {
           turn.activityPendingRender = rendered
           if (turn.activityInFlight == null) {
@@ -7185,19 +7198,19 @@ function handleSessionEvent(ev: SessionEvent): void {
             isPrivateChat: turn.isDm,
             threadId: turn.sessionThreadId,
             // Transport selection:
-            // - DRAFT_MIRROR (RFC draft-mirror-preview, Phase 1): force
-            //   the ephemeral compose-area draft so narration is a
-            //   clears-on-reply preview. Wins over visible-answer-stream.
-            //   No-reply delivery is owned by turn-flush, not materialize.
-            // - else #869-Phase1 visible-answer-stream: omit the draft
-            //   API so the lane edits a user-visible chat-timeline
-            //   message (minInitialChars:1 opens it on the first chunk).
-            // - else legacy: draft transport.
-            ...(DRAFT_MIRROR_ENABLED
-              ? { sendMessageDraft: sendMessageDraftFn }
-              : ANSWER_STREAM_VISIBLE_ENABLED
-                ? { minInitialChars: 1 }
-                : { sendMessageDraft: sendMessageDraftFn }),
+            // #869-Phase1 visible-answer-stream: omit the draft API so
+            // the lane edits a user-visible chat-timeline message
+            // (minInitialChars:1 opens it on the first chunk). The
+            // draft-mirror does NOT touch this lane — the canary proved
+            // the model emits almost no interstitial assistant.text
+            // (it thinks→tool→reply), so routing it to the draft just
+            // emptied the preview. The draft-mirror instead renders the
+            // tool_use stream (case 'tool_use' above) where the real
+            // signal lives. assistant.text keeps its visible-message
+            // home; the reply tool stays the canonical answer.
+            ...(ANSWER_STREAM_VISIBLE_ENABLED
+              ? { minInitialChars: 1 }
+              : { sendMessageDraft: sendMessageDraftFn }),
             // #1075: route through robustApiCall so flood-wait,
             // benign-400, and THREAD_NOT_FOUND are handled uniformly
             // instead of crashing the answer-stream loop on a deleted

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/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…";
+  }
+}