switchroom 0.13.55 → 0.13.57

package/telegram-plugin/tests/silence-poke.test.ts

@@ -26,20 +26,27 @@ const ORIGINAL_KILL_SWITCH = process.env.SWITCHROOM_DISABLE_SILENCE_POKE
 interface TestFixtures {
   emitted: SilencePokeMetric[]
   fallbacks: FrameworkFallbackContext[]
+  awarenessPings: FrameworkFallbackContext[]
 }
 
 function setupDeps(opts?: { thresholds?: Partial<typeof DEFAULT_THRESHOLDS> }): TestFixtures {
-  const fixtures: TestFixtures = { emitted: [], fallbacks: [] }
+  const fixtures: TestFixtures = { emitted: [], fallbacks: [], awarenessPings: [] }
   __setDepsForTests({
     emitMetric: (e) => fixtures.emitted.push(e),
     onFrameworkFallback: (ctx) => { fixtures.fallbacks.push(ctx) },
+    onAwarenessPing: (ctx) => { fixtures.awarenessPings.push(ctx) },
     // The ack budget (a new poke that fires *earlier* than `soft`) is
     // disabled by default in this fixture so the soft/firm/fallback
     // ladder tests stay isolated from it. The 'ack budget' describe
     // block opts back in with a real value.
+    //
+    // The 60s awarenessPing is also disabled by default so the existing
+    // soft/firm/fallback ladder tests don't see the new sibling event;
+    // the 'awareness ping' describe block opts back in.
     thresholdsMs: {
       ...DEFAULT_THRESHOLDS,
       ack: Number.MAX_SAFE_INTEGER,
+      awarenessPing: Number.MAX_SAFE_INTEGER,
       ...(opts?.thresholds ?? {}),
     },
   })
@@ -733,13 +740,18 @@ describe('silence-poke — independence across turns', () => {
 
 describe('silence-poke — fallback handler errors do not break timer', () => {
   it('continues to function if onFrameworkFallback throws', () => {
-    const fx: TestFixtures = { emitted: [], fallbacks: [] }
+    const fx: TestFixtures = { emitted: [], fallbacks: [], awarenessPings: [] }
     __setDepsForTests({
       emitMetric: (e) => fx.emitted.push(e),
       onFrameworkFallback: () => { throw new Error('oh no') },
-      // ack budget out of the way — this test exercises the
+      onAwarenessPing: () => {},
+      // ack + awareness-ping out of the way — this test exercises the
       // soft/firm/fallback ladder under a throwing fallback handler.
-      thresholdsMs: { ...DEFAULT_THRESHOLDS, ack: Number.MAX_SAFE_INTEGER },
+      thresholdsMs: {
+        ...DEFAULT_THRESHOLDS,
+        ack: Number.MAX_SAFE_INTEGER,
+        awarenessPing: Number.MAX_SAFE_INTEGER,
+      },
     })
     startTurn('k', 0)
     expect(() => {
@@ -752,12 +764,17 @@ describe('silence-poke — fallback handler errors do not break timer', () => {
   })
 
   it('continues to function if onFrameworkFallback returns a rejected promise', async () => {
-    const fx: TestFixtures = { emitted: [], fallbacks: [] }
+    const fx: TestFixtures = { emitted: [], fallbacks: [], awarenessPings: [] }
     __setDepsForTests({
       emitMetric: (e) => fx.emitted.push(e),
       onFrameworkFallback: () => Promise.reject(new Error('async fail')),
-      // ack budget out of the way — see the throwing-handler test above.
-      thresholdsMs: { ...DEFAULT_THRESHOLDS, ack: Number.MAX_SAFE_INTEGER },
+      onAwarenessPing: () => {},
+      // ack + awareness-ping out of the way — see the throwing-handler test above.
+      thresholdsMs: {
+        ...DEFAULT_THRESHOLDS,
+        ack: Number.MAX_SAFE_INTEGER,
+        awarenessPing: Number.MAX_SAFE_INTEGER,
+      },
     })
     startTurn('k', 0)
     __tickForTests(75_000)
@@ -860,3 +877,96 @@ describe('silence-poke — performance', () => {
     expect(elapsed).toBeLessThan(50)
   })
 })
+
+describe('silence-poke — awareness ping (early framework-owned user-visible status)', () => {
+  it('fires once at 60s when no outbound has happened', () => {
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    __tickForTests(59_000)
+    expect(fx.awarenessPings.length).toBe(0)
+    __tickForTests(60_000)
+    expect(fx.awarenessPings.length).toBe(1)
+    expect(fx.awarenessPings[0]!.silenceMs).toBeGreaterThanOrEqual(60_000)
+    expect(fx.emitted.some(e => e.kind === 'awareness_ping_sent')).toBe(true)
+  })
+
+  it('is one-shot per turn — does not re-fire as silence continues', () => {
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    __tickForTests(60_000)
+    __tickForTests(120_000)
+    __tickForTests(180_000)
+    expect(fx.awarenessPings.length).toBe(1)
+  })
+
+  it('is suppressed by an early outbound', () => {
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    noteOutbound('k', 30_000)
+    __tickForTests(90_000)
+    expect(fx.awarenessPings.length).toBe(0)
+  })
+
+  it('is suppressed when subagentDispatchActive is true', () => {
+    // Sub-agent dispatch already widens soft to 300s; the awareness-ping
+    // should also defer so we don't pre-empt the sub-agent's natural
+    // progress signal.
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    noteSubagentDispatch('k')
+    __tickForTests(120_000)
+    expect(fx.awarenessPings.length).toBe(0)
+  })
+
+  it('does NOT advance the soft/firm/fallback ladder', () => {
+    // Awareness ping is a sibling signal; soft/firm/fallback continue
+    // to escalate on their own schedule (and the model-targeted ack-poke
+    // similarly remains independent).
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    __tickForTests(60_000) // awareness fires
+    __tickForTests(75_000) // soft fires
+    __tickForTests(180_000) // firm fires
+    __tickForTests(300_000) // fallback fires
+    expect(fx.awarenessPings.length).toBe(1)
+    expect(fx.fallbacks.length).toBe(1)
+    expect(fx.emitted.filter(e => e.kind === 'silence_poke_fired').map(e => (e as { level: string }).level))
+      .toEqual(['soft', 'firm'])
+    expect(fx.emitted.some(e => e.kind === 'silence_fallback_sent')).toBe(true)
+  })
+
+  it('carries fallbackKind=thinking when a recent thinking event landed', () => {
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    noteThinking('k', 45_000)
+    __tickForTests(60_000)
+    expect(fx.awarenessPings.length).toBe(1)
+    expect(fx.awarenessPings[0]!.fallbackKind).toBe('thinking')
+  })
+
+  it('does not fire if turn ends before the threshold', () => {
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    endTurn('k')
+    __tickForTests(120_000)
+    expect(fx.awarenessPings.length).toBe(0)
+  })
+
+  it('handler errors do not break the timer', () => {
+    const fx: TestFixtures = { emitted: [], fallbacks: [], awarenessPings: [] }
+    __setDepsForTests({
+      emitMetric: (e) => fx.emitted.push(e),
+      onFrameworkFallback: () => {},
+      onAwarenessPing: () => { throw new Error('awareness handler boom') },
+      thresholdsMs: {
+        ...DEFAULT_THRESHOLDS,
+        ack: Number.MAX_SAFE_INTEGER,
+        awarenessPing: 60_000,
+      },
+    })
+    startTurn('k', 0)
+    expect(() => __tickForTests(60_000)).not.toThrow()
+    // Telemetry still emitted
+    expect(fx.emitted.some(e => e.kind === 'awareness_ping_sent')).toBe(true)
+  })
+})

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