switchroom 0.13.56 → 0.13.57

package/telegram-plugin/gateway/gateway.ts

@@ -53,6 +53,7 @@ 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 { toolLabel } from '../tool-labels.js'
 import { createTypingWrapper } from '../typing-wrap.js'
 import { type DraftStreamHandle } from '../draft-stream.js'
@@ -1291,6 +1292,15 @@ 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
   // 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.
@@ -6832,6 +6842,7 @@ function handleSessionEvent(ev: SessionEvent): void {
           lastAssistantMsgId: null,
           lastAssistantDone: false,
           toolCallCount: 0,
+          intentSurfaceFired: false,
           answerStream: null,
           isDm: isDmChatId(ev.chatId),
         }
@@ -6949,6 +6960,66 @@ function handleSessionEvent(ev: SessionEvent): void {
           turn.orphanedReplyTimeoutId = null
         }
       }
+      // 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
+          // is logged but does not block the model.
+          try {
+            markAckSent()
+          } catch (err) {
+            process.stderr.write(`telegram gateway: intent-surface markAckSent failed: ${err}\n`)
+          }
+          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
       if (isTelegramSurfaceTool(name)) return
       ctrl.setTool(name)

package/telegram-plugin/tests/tool-intent-surface.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from "vitest";
+import { deriveIntentSurface } from "../tool-intent-surface.js";
+
+describe("deriveIntentSurface — gateway lifts model's tool intent into framework-voice status", () => {
+  describe("tool-class verb mapping", () => {
+    it("Bash → running", () => {
+      const out = deriveIntentSurface("Bash", { command: "ls -la /var/log" });
+      expect(out.text).toContain("<i>running:</i>");
+      expect(out.text).toContain("ls -la /var/log");
+    });
+
+    it("WebSearch → searching", () => {
+      const out = deriveIntentSurface("WebSearch", { query: "Victoria drink driving" });
+      expect(out.text).toContain("<i>searching:</i>");
+      expect(out.text).toContain("Victoria drink driving");
+    });
+
+    it("WebFetch → fetching (hostname extracted)", () => {
+      const out = deriveIntentSurface("WebFetch", { url: "https://example.com/a/b" });
+      expect(out.text).toContain("<i>fetching:</i>");
+      expect(out.text).toContain("example.com");
+    });
+
+    it("Read → reading (basename only)", () => {
+      const out = deriveIntentSurface("Read", { file_path: "/etc/os-release" });
+      expect(out.text).toContain("<i>reading:</i>");
+      expect(out.text).toContain("os-release");
+      expect(out.text).not.toContain("/etc/");
+    });
+
+    it("Write → writing", () => {
+      const out = deriveIntentSurface("Write", { file_path: "/tmp/hello.sh" });
+      expect(out.text).toContain("<i>writing:</i>");
+      expect(out.text).toContain("hello.sh");
+    });
+
+    it("Edit / MultiEdit / NotebookEdit → editing", () => {
+      for (const t of ["Edit", "MultiEdit", "NotebookEdit"]) {
+        expect(
+          deriveIntentSurface(t, { file_path: "/a/foo.ts" }).text,
+        ).toContain("<i>editing:</i>");
+      }
+    });
+
+    it("Grep / Glob → searching", () => {
+      expect(
+        deriveIntentSurface("Grep", { pattern: "TODO", path: "src/" }).text,
+      ).toContain("<i>searching:</i>");
+      expect(
+        deriveIntentSurface("Glob", { pattern: "**/*.ts" }).text,
+      ).toContain("<i>searching:</i>");
+    });
+
+    it("Task / Agent → dispatching", () => {
+      expect(
+        deriveIntentSurface("Task", { description: "review the auth code" }).text,
+      ).toContain("<i>dispatching:</i>");
+    });
+  });
+
+  describe("user-facing tools stay quiet (never re-surfaced)", () => {
+    const surfaceTools = [
+      "mcp__switchroom-telegram__reply",
+      "mcp__switchroom-telegram__stream_reply",
+      "mcp__switchroom-telegram__edit_message",
+      "mcp__switchroom-telegram__react",
+      "mcp__switchroom-telegram__send_typing",
+      "mcp__switchroom-telegram__progress_update",
+    ];
+    for (const tool of surfaceTools) {
+      it(`returns null for ${tool}`, () => {
+        expect(
+          deriveIntentSurface(tool, { text: "hi", chat_id: "1" }).text,
+        ).toBeNull();
+      });
+    }
+  });
+
+  describe("unknown MCP tools", () => {
+    it("uses 'using <tool>' for unknown MCP tool servers", () => {
+      const out = deriveIntentSurface(
+        "mcp__google-workspace__list_drive_files",
+        { folderId: "abc" },
+      );
+      expect(out.text).toMatch(/<i>using list[ _]drive[ _]files:?<\/i>/);
+    });
+
+    it("falls back gracefully when input has no recognisable label field", () => {
+      const out = deriveIntentSurface("Bash", { weird: "no-command-here" });
+      // No label resolved → verb-only output
+      expect(out.text).toBe("<i>running</i>");
+    });
+  });
+
+  describe("privacy / safety", () => {
+    it("escapes HTML in the label so a malicious input can't inject markup", () => {
+      const out = deriveIntentSurface("Bash", {
+        command: "echo '<script>alert(1)</script>'",
+      });
+      expect(out.text).not.toContain("<script>");
+      expect(out.text).toContain("&lt;script&gt;");
+    });
+
+    it("truncates long labels to keep the surface message tight", () => {
+      const longCmd = "echo " + "x".repeat(500);
+      const out = deriveIntentSurface("Bash", { command: longCmd });
+      // toolLabel already truncates Bash to 40 chars; safety cap then
+      // bounds anything else to MAX_LABEL_LEN.
+      expect((out.text ?? "").length).toBeLessThan(200);
+    });
+
+    it("returns null when toolName is empty (defensive)", () => {
+      expect(deriveIntentSurface("", { command: "x" }).text).toBeNull();
+    });
+  });
+
+  describe("precomputed label precedence", () => {
+    it("uses precomputed label when present (matches toolLabel's contract)", () => {
+      const out = deriveIntentSurface(
+        "Bash",
+        { command: "ls" },
+        "checking the logs",
+      );
+      expect(out.text).toContain("<i>running:</i>");
+      expect(out.text).toContain("checking the logs");
+    });
+  });
+});

package/telegram-plugin/tool-intent-surface.ts

@@ -0,0 +1,155 @@
+/**
+ * Tool-intent surface — lifts the model's already-formed `tool_use`
+ * intent (tool name + input) into a brief user-visible Telegram
+ * message when the model goes to work without first calling reply.
+ *
+ * Companion to the PreToolUse ack-first gate (#1921). The gate forces
+ * the model to author a brief acknowledgement via the reply tool
+ * before any other tool runs. THIS surface is the lower-overhead
+ * sibling: when the model's own `tool_use` stream already carries the
+ * intent (e.g. `Bash {command: "ls -la /var/log"}`), the gateway can
+ * pass that intent through as the user-visible "we're alive and this
+ * is what we're doing" beat, without the model having to call any
+ * extra tool.
+ *
+ * Why both. The gate produces MODEL-VOICE acks ("on it — checking the
+ * logs") — warmer, persona-driven. The surface produces FRAMEWORK-
+ * VOICE pass-throughs ("_running:_ ls -la /var/log") — honest and
+ * cheaper. They compose: if the gate fires, the model authors an ack
+ * which lands first; the surface stays quiet (already-acked). If the
+ * gate fails (kill-switched / regression / hook spawn failure), the
+ * surface still lands — defence in depth.
+ *
+ * Output format: italicised framework verb + colon + the model's own
+ * `toolLabel()` output. Italics are the conventional "framework
+ * narrating, not the model speaking" marker; the verb signals which
+ * lane the work is in. Length capped at ~140 chars by `toolLabel()`
+ * already; nothing more is added on top.
+ *
+ * Privacy posture. The model's `tool_use.input` may contain user-
+ * provided strings (web search queries, file paths the user named).
+ * Those are already going to land in chat history one way or another
+ * (e.g. via the model's reply describing what it did), so surfacing
+ * a brief label here doesn't expand the leakage surface materially.
+ * `toolLabel()` already truncates and HTML-escapes its output via
+ * the renderer.
+ */
+
+import { toolLabel } from "./tool-labels.js";
+
+const MAX_LABEL_LEN = 140;
+
+/**
+ * Compute the user-facing "framework verb" for a tool. Verbs match
+ * the action class so the user reads "running" for Bash, "searching"
+ * for WebSearch, etc. Tools without a friendly verb fall back to
+ * `using <ToolName>` — better than blanking out.
+ */
+function frameworkVerbFor(toolName: string): string {
+  // Strip "mcp__<server>__" prefix to match suffixes consistently.
+  // Most MCP tools surface as `mcp__<server>__<tool>` in the stream.
+  const m = /^mcp__[^_]+__(.+)$/.exec(toolName);
+  const suffix = (m ? m[1] : toolName).toLowerCase();
+
+  switch (suffix) {
+    case "bash":
+    case "bashoutput":
+    case "killshell":
+      return "running";
+    case "websearch":
+    case "grep":
+    case "glob":
+      return "searching";
+    case "webfetch":
+      return "fetching";
+    case "read":
+      return "reading";
+    case "write":
+      return "writing";
+    case "edit":
+    case "multiedit":
+    case "notebookedit":
+      return "editing";
+    case "todowrite":
+    case "todoread":
+      return "noting";
+    case "task":
+    case "agent":
+      return "dispatching";
+    case "toolsearch":
+      return "loading tools";
+    default:
+      // For unknown / MCP tools, prefer a short generic — "using gdrive"
+      // is more honest than guessing.
+      if (m) return `using ${m[1].replace(/_/g, " ")}`;
+      return `using ${toolName}`;
+  }
+}
+
+/** A tool that surfaces in the chat itself (reply / stream_reply / etc.)
+ *  — these tools ARE the user surface, so the gateway never re-surfaces
+ *  them. Mirrors `isTelegramSurfaceTool` in `tool-names.ts`. */
+function isUserFacingTool(toolName: string): boolean {
+  const m = /^mcp__switchroom-telegram__(.+)$/.exec(toolName);
+  const suffix = m ? m[1] : toolName;
+  return (
+    suffix === "reply" ||
+    suffix === "stream_reply" ||
+    suffix === "edit_message" ||
+    suffix === "react" ||
+    suffix === "send_typing" ||
+    suffix === "pin_message" ||
+    suffix === "delete_message" ||
+    suffix === "forward_message" ||
+    suffix === "download_attachment" ||
+    suffix === "get_recent_messages" ||
+    suffix === "progress_update"
+  );
+}
+
+export interface SurfaceTextResult {
+  /** Final HTML text the gateway sends to Telegram, or null when the
+   *  surface should NOT fire (tool is user-facing, label is empty, etc.) */
+  text: string | null;
+}
+
+/**
+ * Pure decision: given a tool name + input + optional precomputed label
+ * (from the existing PreToolUse label hook), return the HTML the
+ * gateway should send, or null to stay quiet.
+ *
+ * Exposed for unit tests; the gateway wires this into the `tool_use`
+ * session-event handler.
+ */
+export function deriveIntentSurface(
+  toolName: string,
+  toolInput: Record<string, unknown> | undefined,
+  precomputedLabel?: string,
+): SurfaceTextResult {
+  if (!toolName) return { text: null };
+  if (isUserFacingTool(toolName)) return { text: null };
+
+  const label = toolLabel(toolName, toolInput, undefined, precomputedLabel);
+  if (!label || !label.trim()) {
+    // No label available for this tool/input shape — fall back to just
+    // the verb so the user at least sees "_running_" rather than
+    // nothing. Keeps the beat reliable on weird inputs.
+    return {
+      text: `<i>${escapeHtml(frameworkVerbFor(toolName))}</i>`,
+    };
+  }
+
+  const verb = frameworkVerbFor(toolName);
+  // `toolLabel()` may include backticks / quotes — let those through
+  // (Telegram HTML doesn't choke on them) but escape any stray inline
+  // HTML markers so a malicious or odd input can't inject markup.
+  const safeLabel = escapeHtml(label).slice(0, MAX_LABEL_LEN);
+  return { text: `<i>${escapeHtml(verb)}:</i> ${safeLabel}` };
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}