switchroom 0.15.45 → 0.16.5

package/telegram-plugin/tests/tool-label-pretool.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Unit tests for the computeLabel function in hooks/tool-label-pretool.mjs.
+ *
+ * These tests verify:
+ *   1. computeLabel returns non-null for unknown built-in tools (never-null fallthrough)
+ *   2. computeLabel returns non-null for unknown MCP tools (humanized name fallback)
+ *   3. Surface-tool suppression works for non-switchroom-telegram telegram-suffixed keys
+ *      (e.g. clerk-telegram, custom fork) — not just the hardcoded "switchroom-telegram"
+ */
+
+import { describe, it, expect } from 'vitest'
+// The hook exports computeLabel for unit testing (see "Skip main() when imported" guard).
+import { computeLabel } from '../hooks/tool-label-pretool.mjs'
+
+describe('computeLabel — never-null built-in fallthrough', () => {
+  it('returns non-null for an unrecognized built-in tool', () => {
+    // A future Claude built-in tool that the hook doesn't know about yet.
+    // The never-null fallthrough must prevent a dark-turn (no feed, no label).
+    expect(computeLabel('SomeFutureBuiltin', {})).not.toBeNull()
+    // Must be a non-empty string too.
+    expect(computeLabel('SomeFutureBuiltin', {})).toBeTruthy()
+  })
+
+  it('returns non-null for an unknown MCP tool (operator-configured server)', () => {
+    // An operator-installed MCP server the hook has no explicit label for.
+    // Falls through to the humanized-name fallback: "Using dothing".
+    expect(computeLabel('mcp__brandnew__dothing', {})).not.toBeNull()
+    expect(computeLabel('mcp__brandnew__dothing', {})).toBeTruthy()
+  })
+
+  it('humanizes the tool name for an unknown MCP tool with no description', () => {
+    expect(computeLabel('mcp__brandnew__dothing', {})).toBe('Using dothing')
+    expect(computeLabel('mcp__acme_corp__send_message', {})).toBe('Using send message')
+  })
+
+  it('uses the model-authored description for an unknown MCP tool when present', () => {
+    expect(
+      computeLabel('mcp__brandnew__dothing', { description: 'Fetched the quarterly report' }),
+    ).toBe('Fetched the quarterly report')
+  })
+})
+
+describe('computeLabel — surface-tool suppression is key-agnostic', () => {
+  it('returns null for telegram reply/stream_reply under any registration key', () => {
+    // Standard switchroom-telegram key.
+    expect(computeLabel('mcp__switchroom-telegram__reply', {})).toBeNull()
+    expect(computeLabel('mcp__switchroom-telegram__stream_reply', {})).toBeNull()
+
+    // Legacy clerk-telegram key — same plugin, different registration name.
+    expect(computeLabel('mcp__clerk-telegram__reply', {})).toBeNull()
+    expect(computeLabel('mcp__clerk-telegram__stream_reply', {})).toBeNull()
+
+    // Hypothetical custom fork.
+    expect(computeLabel('mcp__my-custom-telegram__reply', {})).toBeNull()
+    expect(computeLabel('mcp__my-custom-telegram__stream_reply', {})).toBeNull()
+  })
+
+  it('returns null for telegram react under any registration key', () => {
+    expect(computeLabel('mcp__switchroom-telegram__react', {})).toBeNull()
+    expect(computeLabel('mcp__clerk-telegram__react', {})).toBeNull()
+  })
+
+  it('returns null for telegram send_typing under any registration key', () => {
+    expect(computeLabel('mcp__switchroom-telegram__send_typing', {})).toBeNull()
+    expect(computeLabel('mcp__clerk-telegram__send_typing', {})).toBeNull()
+  })
+
+  it('returns a label (not null) for telegram get_recent_messages', () => {
+    // get_recent_messages is a read/query tool, not a surface tool — it should be labeled.
+    expect(computeLabel('mcp__switchroom-telegram__get_recent_messages', {})).toBe('Reading chat history')
+    expect(computeLabel('mcp__clerk-telegram__get_recent_messages', {})).toBe('Reading chat history')
+  })
+})

package/telegram-plugin/tests/tool-label-sidecar.test.ts

@@ -147,4 +147,48 @@ describe('tool-label-sidecar', () => {
     expect(s.getLabel('A')).toBe('first')
     s.stop()
   })
+
+  /**
+   * Issue #2461: the sidecar's `onLabel` callback exposes `toolName` so the
+   * gateway can filter surface tools (reply/stream_reply/edit_message/react)
+   * from the surfaced step count. This test pins that the toolName flows
+   * through correctly for both non-surface and surface-tool entries, so the
+   * gateway's `isTelegramSurfaceTool(ev.toolName)` guard works as the single
+   * filter that keeps reply/react out of `labeledToolCount`.
+   *
+   * Note: send_typing and sync_retain never appear here because
+   * computeLabel returns null for them → hook never writes to the sidecar.
+   */
+  it('toolName flows through onLabel so callers can exclude surface tools from counts', () => {
+    const sessionId = 'sess-count'
+    const sched = makeManualScheduler()
+    const f = join(stateDir, `tool-labels-${sessionId}.jsonl`)
+    writeFileSync(
+      f,
+      // Non-surface tools — should be counted.
+      JSON.stringify({ ts: 1, tool_use_id: 'R1', agent_id: null, label: 'Reading CLAUDE.md', tool_name: 'Read' }) + '\n' +
+      JSON.stringify({ ts: 2, tool_use_id: 'M1', agent_id: null, label: 'Searching memory', tool_name: 'mcp__hindsight__recall' }) + '\n' +
+      // Surface tool — must NOT be counted.
+      JSON.stringify({ ts: 3, tool_use_id: 'RP', agent_id: null, label: 'Replying', tool_name: 'mcp__switchroom-telegram__reply' }) + '\n' +
+      // Another non-surface.
+      JSON.stringify({ ts: 4, tool_use_id: 'B1', agent_id: null, label: 'List workspace', tool_name: 'Bash' }) + '\n',
+    )
+    const s = createToolLabelSidecar({ stateDir, sessionId, scheduler: sched })
+
+    const SURFACE_TOOLS = new Set([
+      'mcp__switchroom-telegram__reply',
+      'mcp__switchroom-telegram__stream_reply',
+      'mcp__switchroom-telegram__edit_message',
+      'mcp__switchroom-telegram__react',
+    ])
+
+    let surfacedCount = 0
+    s.onLabel((_id, _label, toolName) => {
+      if (!SURFACE_TOOLS.has(toolName)) surfacedCount++
+    })
+
+    // Read + mcp__hindsight__recall + Bash = 3 surfaced; reply = 0.
+    expect(surfacedCount).toBe(3)
+    s.stop()
+  })
 })

package/telegram-plugin/tests/tool-labels.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import { toolLabel, isHumanDescription } from '../tool-labels.js'
+import { isTelegramSurfaceTool } from '../tool-names.js'
 
 describe('toolLabel', () => {
   it('Read: uses basename of file_path', () => {
@@ -381,3 +382,69 @@ describe('isHumanDescription', () => {
     expect(isHumanDescription('Bash')).toBe(false)
   })
 })
+
+/**
+ * Surface-tool exclusion contract (#2461).
+ *
+ * The gateway's `labeledToolCount` is incremented in `case 'tool_label':` AFTER
+ * `isTelegramSurfaceTool(ev.toolName)` returns false — so the count reflects
+ * only non-surface tools. This describe block pins that contract by verifying
+ * which tool names are classified as surface tools (never counted) vs
+ * non-surface tools (counted when they produce a label).
+ *
+ * send_typing and sync_retain are excluded at the hook level: `computeLabel`
+ * returns null for them → no sidecar line → no tool_label event → never reach
+ * the `labeledToolCount++` path. That suppression is tested in
+ * tool-label-sidecar.test.ts (the sidecar never gets those entries).
+ */
+describe('isTelegramSurfaceTool — surface-tool exclusion for labeledToolCount (#2461)', () => {
+  it('reply and stream_reply are surface tools — never counted', () => {
+    expect(isTelegramSurfaceTool('mcp__switchroom-telegram__reply')).toBe(true)
+    expect(isTelegramSurfaceTool('mcp__switchroom-telegram__stream_reply')).toBe(true)
+  })
+
+  it('edit_message and react are surface tools — never counted', () => {
+    expect(isTelegramSurfaceTool('mcp__switchroom-telegram__edit_message')).toBe(true)
+    expect(isTelegramSurfaceTool('mcp__switchroom-telegram__react')).toBe(true)
+  })
+
+  it('Read tool is NOT a surface tool — counted when it produces a label', () => {
+    expect(isTelegramSurfaceTool('Read')).toBe(false)
+  })
+
+  it('mcp__hindsight__* tools are NOT surface tools — counted', () => {
+    expect(isTelegramSurfaceTool('mcp__hindsight__recall')).toBe(false)
+    expect(isTelegramSurfaceTool('mcp__hindsight__retain')).toBe(false)
+    expect(isTelegramSurfaceTool('mcp__hindsight__reflect')).toBe(false)
+  })
+
+  it('Bash, Edit, Write, Grep are NOT surface tools — counted', () => {
+    expect(isTelegramSurfaceTool('Bash')).toBe(false)
+    expect(isTelegramSurfaceTool('Edit')).toBe(false)
+    expect(isTelegramSurfaceTool('Write')).toBe(false)
+    expect(isTelegramSurfaceTool('Grep')).toBe(false)
+  })
+
+  it('operator MCP tools (perplexity, webkite, etc.) are NOT surface tools — counted', () => {
+    expect(isTelegramSurfaceTool('mcp__perplexity__perplexity_search')).toBe(false)
+    expect(isTelegramSurfaceTool('mcp__webkite__read')).toBe(false)
+    expect(isTelegramSurfaceTool('mcp__google-workspace__list_events')).toBe(false)
+  })
+
+  it('other switchroom-telegram tools (get_recent_messages, send_typing) are NOT surface tools', () => {
+    // get_recent_messages is a read/query tool — not a conversation surface tool.
+    expect(isTelegramSurfaceTool('mcp__switchroom-telegram__get_recent_messages')).toBe(false)
+    // send_typing is suppressed at the hook level (computeLabel returns null),
+    // so it never generates a tool_label event. But isTelegramSurfaceTool itself
+    // does NOT classify it as a surface tool — the two suppression mechanisms
+    // are orthogonal. The hook suppression is the right gate for send_typing.
+    expect(isTelegramSurfaceTool('mcp__switchroom-telegram__send_typing')).toBe(false)
+  })
+
+  it('clerk-telegram prefix also works (legacy registration key)', () => {
+    expect(isTelegramSurfaceTool('mcp__clerk-telegram__reply')).toBe(true)
+    expect(isTelegramSurfaceTool('mcp__clerk-telegram__stream_reply')).toBe(true)
+    expect(isTelegramSurfaceTool('mcp__clerk-telegram__edit_message')).toBe(true)
+    expect(isTelegramSurfaceTool('mcp__clerk-telegram__react')).toBe(true)
+  })
+})

package/telegram-plugin/tests/turn-liveness-floor.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Unit coverage for the mid-turn liveness floor decision (#2527).
+ *
+ * The floor is the missing TEXT signal during a busy-but-silent turn. These
+ * tests pin the pure policy: WHEN it fires (user role, undelivered, busy,
+ * past threshold, below the 300s fallback window, not already fired) and
+ * WHY it skips otherwise — plus the role derivation that keys the whole
+ * primitive (and is the antidote to per-surface / per-turn-type enumeration).
+ *
+ * The gateway wiring (send via the shared path, "Status?" short-circuit,
+ * role-aware terminal reaction) is covered separately; here we lock the
+ * decision so a regression in eligibility is caught without booting the
+ * 22k-line gateway.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest'
+import {
+  deriveTurnRole,
+  decideMidTurnFloor,
+  decideTerminalReason,
+  midTurnFloorEnabled,
+  parsePostAnswerLivenessMs,
+  DEFAULT_FLOOR_THRESHOLD_MS,
+  type MidTurnFloorInput,
+} from '../turn-liveness-floor.js'
+
+const FALLBACK_MS = 300_000
+
+/** A baseline that FIRES — each test perturbs exactly one field. */
+function fireBase(over: Partial<MidTurnFloorInput> = {}): MidTurnFloorInput {
+  return {
+    enabled: true,
+    role: 'user',
+    finalAnswerDelivered: false,
+    silenceMs: 60_000,
+    floorThresholdMs: DEFAULT_FLOOR_THRESHOLD_MS,
+    fallbackThresholdMs: FALLBACK_MS,
+    legitimatelyWorking: true,
+    alreadyFired: false,
+    ...over,
+  }
+}
+
+describe('deriveTurnRole — the single provenance discriminator', () => {
+  it('a plain human DM (no envelope) is a user turn', () => {
+    expect(deriveTurnRole(undefined)).toBe('user')
+    expect(deriveTurnRole(null)).toBe('user')
+    expect(deriveTurnRole('hello there')).toBe('user')
+  })
+
+  it('a cron/scheduled envelope is a system turn', () => {
+    expect(deriveTurnRole('<channel chat_id="123" source="cron">do the thing</channel>')).toBe('system')
+    expect(deriveTurnRole('<channel source="wake" chat_id="1">')).toBe('system')
+    expect(deriveTurnRole('<channel source="scheduler">')).toBe('system')
+  })
+
+  it('an unknown source defaults to user (gets the never-silent guarantee, not silently exempt)', () => {
+    // A novel/unknown source must NOT opt out of the floor by accident.
+    expect(deriveTurnRole('<channel source="handback" chat_id="1">')).toBe('user')
+    expect(deriveTurnRole('<channel source="some-new-thing">')).toBe('user')
+  })
+
+  it('never returns sub-agent — the gateway makes no turn atom for sub-agents', () => {
+    // Type-level guarantee, asserted at runtime for the documented cases.
+    const r = deriveTurnRole('<channel source="cron">')
+    expect(r === 'user' || r === 'system').toBe(true)
+  })
+})
+
+describe('decideMidTurnFloor — fires on busy-but-silent user turns', () => {
+  it('fires for a user turn working silently past the threshold', () => {
+    expect(decideMidTurnFloor(fireBase())).toEqual({ kind: 'fire' })
+  })
+
+  it('skips when disabled (kill switch)', () => {
+    expect(decideMidTurnFloor(fireBase({ enabled: false }))).toEqual({ kind: 'skip', reason: 'disabled' })
+  })
+
+  it('skips when already fired (fire-once per turn)', () => {
+    expect(decideMidTurnFloor(fireBase({ alreadyFired: true }))).toEqual({ kind: 'skip', reason: 'already-fired' })
+  })
+
+  it('skips a system/cron turn — its silence is legitimate', () => {
+    expect(decideMidTurnFloor(fireBase({ role: 'system' }))).toEqual({ kind: 'skip', reason: 'non-user-role' })
+  })
+
+  it('skips a sub-agent turn — liveness is carried by the parent', () => {
+    expect(decideMidTurnFloor(fireBase({ role: 'sub-agent' }))).toEqual({ kind: 'skip', reason: 'non-user-role' })
+  })
+
+  it('skips once a substantive answer was delivered', () => {
+    expect(decideMidTurnFloor(fireBase({ finalAnswerDelivered: true }))).toEqual({ kind: 'skip', reason: 'answer-delivered' })
+  })
+
+  it('skips below the floor threshold (a normal short turn stays quiet)', () => {
+    expect(decideMidTurnFloor(fireBase({ silenceMs: 10_000 }))).toEqual({ kind: 'skip', reason: 'below-threshold' })
+  })
+
+  it('skips inside the 300s fallback window — the loud fallback owns that beat', () => {
+    expect(decideMidTurnFloor(fireBase({ silenceMs: FALLBACK_MS }))).toEqual({ kind: 'skip', reason: 'fallback-window' })
+    expect(decideMidTurnFloor(fireBase({ silenceMs: FALLBACK_MS + 1 }))).toEqual({ kind: 'skip', reason: 'fallback-window' })
+  })
+
+  it('skips when not legitimately working — a genuine wedge is the fallback\'s job', () => {
+    expect(decideMidTurnFloor(fireBase({ legitimatelyWorking: false }))).toEqual({ kind: 'skip', reason: 'not-working' })
+  })
+
+  it('fires exactly at the threshold boundary', () => {
+    expect(decideMidTurnFloor(fireBase({ silenceMs: DEFAULT_FLOOR_THRESHOLD_MS }))).toEqual({ kind: 'fire' })
+  })
+})
+
+describe('decideMidTurnFloor — forced "Status?" short-circuit', () => {
+  it('fires immediately on force, bypassing threshold and the working check', () => {
+    expect(decideMidTurnFloor(fireBase({ force: true, silenceMs: 1_000, legitimatelyWorking: false })))
+      .toEqual({ kind: 'fire' })
+  })
+
+  it('force still honours role / delivery / fire-once / enabled', () => {
+    expect(decideMidTurnFloor(fireBase({ force: true, role: 'system' }))).toEqual({ kind: 'skip', reason: 'non-user-role' })
+    expect(decideMidTurnFloor(fireBase({ force: true, finalAnswerDelivered: true }))).toEqual({ kind: 'skip', reason: 'answer-delivered' })
+    expect(decideMidTurnFloor(fireBase({ force: true, alreadyFired: true }))).toEqual({ kind: 'skip', reason: 'already-fired' })
+    expect(decideMidTurnFloor(fireBase({ force: true, enabled: false }))).toEqual({ kind: 'skip', reason: 'disabled' })
+  })
+})
+
+describe('decideTerminalReason — the "thumbs-up false done" gate', () => {
+  it('an undelivered user turn finalizes undelivered (😐), not done (👍)', () => {
+    expect(decideTerminalReason({ enabled: true, role: 'user', finalAnswerDelivered: false })).toBe('undelivered')
+  })
+
+  it('a delivered user turn finalizes done', () => {
+    expect(decideTerminalReason({ enabled: true, role: 'user', finalAnswerDelivered: true })).toBe('done')
+  })
+
+  it('a system/cron turn keeps done even when undelivered — its silence is legitimate', () => {
+    expect(decideTerminalReason({ enabled: true, role: 'system', finalAnswerDelivered: false })).toBe('done')
+  })
+
+  it('a sub-agent turn keeps done', () => {
+    expect(decideTerminalReason({ enabled: true, role: 'sub-agent', finalAnswerDelivered: false })).toBe('done')
+  })
+
+  it('the kill switch reverts to always-done', () => {
+    expect(decideTerminalReason({ enabled: false, role: 'user', finalAnswerDelivered: false })).toBe('done')
+  })
+})
+
+describe('midTurnFloorEnabled — default-on kill switch', () => {
+  const KEY = 'SWITCHROOM_TG_LIVENESS_FLOOR'
+  afterEach(() => { delete process.env[KEY] })
+
+  it('defaults on when unset', () => {
+    delete process.env[KEY]
+    expect(midTurnFloorEnabled()).toBe(true)
+  })
+
+  it('disables on 0/false/off/no (case-insensitive)', () => {
+    for (const v of ['0', 'false', 'off', 'no', 'OFF', 'False']) {
+      process.env[KEY] = v
+      expect(midTurnFloorEnabled()).toBe(false)
+    }
+  })
+
+  it('stays on for any other value', () => {
+    for (const v of ['1', 'true', 'on', 'yes']) {
+      process.env[KEY] = v
+      expect(midTurnFloorEnabled()).toBe(true)
+    }
+  })
+})
+
+describe('parsePostAnswerLivenessMs — PR1 Item-3a DORMANT escape hatch (default OFF)', () => {
+  // The load-bearing contract: UNSET ⇒ 0 ⇒ behaviour byte-identical to today
+  // (the guarded post-answer branch in feedHeartbeatTick is dead). No surface
+  // ships enabled in this PR; this only pins that nothing changes by default.
+  it('UNSET (undefined) ⇒ 0 — exactly today’s silent post-answer behaviour', () => {
+    expect(parsePostAnswerLivenessMs(undefined)).toBe(0)
+  })
+
+  it('empty / whitespace / non-numeric ⇒ 0 (dormant)', () => {
+    expect(parsePostAnswerLivenessMs('')).toBe(0)
+    expect(parsePostAnswerLivenessMs('   ')).toBe(0)
+    expect(parsePostAnswerLivenessMs('nope')).toBe(0)
+  })
+
+  it('0 and negative ⇒ 0 (dormant — never enables a post-answer surface)', () => {
+    expect(parsePostAnswerLivenessMs('0')).toBe(0)
+    expect(parsePostAnswerLivenessMs('-5000')).toBe(0)
+  })
+
+  it('a positive integer ⇒ that threshold in ms (the opt-in future surface)', () => {
+    expect(parsePostAnswerLivenessMs('8000')).toBe(8000)
+    expect(parsePostAnswerLivenessMs('45000')).toBe(45000)
+  })
+})