switchroom 0.18.31 → 0.18.33

package/telegram-plugin/gateway/voice-ondemand-callback-handler.ts

@@ -0,0 +1,204 @@
+/**
+ * On-demand voice ('🔊 Listen') callback family (`voice:<token>`) extracted
+ * verbatim from the gateway's `callback_query:data` dispatcher
+ * (switchroom#2996 P6 dispatcher drain).
+ *
+ * Handles the tap INTERNALLY — synthesizes the cached reply text and sends it
+ * as a native voice note. MUST run before the agent-callback routing in the
+ * dispatcher so a tap never reaches the agent as an inbound message.
+ *
+ * Returns true when the callback was a voice-on-demand tap (handled —
+ * dispatcher must `return`), false otherwise (dispatcher falls through).
+ *
+ * DI note (check-bot-api-wrapping, cluster-F pattern): the raw
+ * `bot.api.sendVoice` / `bot.api.editMessageReplyMarkup` calls are NOT made
+ * here — they are injected as `sendVoiceByFileId` / `sendVoiceByUpload` /
+ * `stripListenKeyboard`, bound in gateway.ts inside `robustApiCall(...)` with
+ * their existing allow-raw-bot-api markers. This module has no raw Bot API
+ * site.
+ */
+
+import { readFileSync } from 'node:fs'
+import type { Context } from 'grammy'
+import {
+  isVoiceOnDemandCallback,
+  parseVoiceOnDemandToken,
+  type VoiceOnDemandPayload,
+} from '../voice-ondemand.js'
+import { sendVoiceReusingFileId, type SentVoiceMessage } from '../voice-send.js'
+import { synthesizeViaSidecar } from '../voice-synthesize-sidecar.js'
+import { normalizeForTts } from '../tts-normalize.js'
+import { materializeSidecarToken } from '../../src/telegram/materialize-sidecar-token.js'
+
+export interface VoiceSendOpts {
+  reply_parameters?: { message_id: number }
+  message_thread_id?: number
+}
+
+export interface VoiceOnDemandCallbackDeps {
+  loadAccess: () => { allowFrom: string[] }
+  voiceOnDemandCache: {
+    get: (token: string) => VoiceOnDemandPayload | null
+    setTelegramFileId: (token: string, fileId: string) => void
+  }
+  /** robustApiCall(() => bot.api.sendVoice(chatId, fileId, opts), verbOpts) — bound in gateway.ts. */
+  sendVoiceByFileId: (
+    chatId: string,
+    fileId: string,
+    sendOpts: VoiceSendOpts,
+    threadId: number | undefined,
+  ) => Promise<SentVoiceMessage>
+  /** robustApiCall(() => bot.api.sendVoice(chatId, new InputFile(audio), opts), verbOpts) — bound in gateway.ts. */
+  sendVoiceByUpload: (
+    chatId: string,
+    audio: Uint8Array,
+    sendOpts: VoiceSendOpts,
+    threadId: number | undefined,
+  ) => Promise<SentVoiceMessage>
+  /** robustApiCall(() => bot.api.editMessageReplyMarkup(...)) — bound in gateway.ts; swallows failure. */
+  stripListenKeyboard: (
+    chatId: string,
+    messageId: number,
+    threadId: number | undefined,
+  ) => Promise<void>
+  /** stderr log sink. */
+  log: (line: string) => void
+}
+
+/** Handle a `voice:` callback. Returns false if `data` is not one. */
+export async function handleVoiceOnDemandCallback(
+  ctx: Context,
+  data: string,
+  deps: VoiceOnDemandCallbackDeps,
+): Promise<boolean> {
+  if (!isVoiceOnDemandCallback(data)) return false
+  const access = deps.loadAccess()
+  const senderId = String(ctx.from!.id)
+  if (!access.allowFrom.includes(senderId)) {
+    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
+    return true
+  }
+  const token = parseVoiceOnDemandToken(data)
+  const entry = token != null ? deps.voiceOnDemandCache.get(token) : null
+  if (entry == null) {
+    await ctx
+      .answerCallbackQuery({ text: 'Voice expired — send again to hear it.' })
+      .catch(() => {})
+    return true
+  }
+  const cbChatId = String(ctx.chat?.id ?? ctx.from!.id)
+  const cbMessageId = ctx.callbackQuery?.message?.message_id
+  const cbThreadId = (() => {
+    const msg = ctx.callbackQuery?.message
+    if (msg && 'is_topic_message' in msg && msg.is_topic_message && 'message_thread_id' in msg) {
+      const tid = (msg as { message_thread_id?: number }).message_thread_id
+      return typeof tid === 'number' ? tid : undefined
+    }
+    return undefined
+  })()
+  const tok = token as string
+  const sendOpts: VoiceSendOpts = {
+    ...(cbMessageId != null ? { reply_parameters: { message_id: cbMessageId } } : {}),
+    ...(cbThreadId != null ? { message_thread_id: cbThreadId } : {}),
+  }
+
+  // #2763 attach-on-tap: prefer the eagerly pre-synthesized file (written by
+  // the pre-synth queue at reply time). If it's on disk, attach it
+  // immediately — no GPU wait. Missing/unreadable file (expired + swept,
+  // crash, pre-feature entry, kill-switched gateway) falls back transparently
+  // to the lazy synth path. Only invoked when there's no reusable file_id (or
+  // a stored id was rejected as stale) — see sendVoiceReusingFileId.
+  const loadAudio = async (): Promise<Uint8Array | null> => {
+    let audio: Uint8Array | null = null
+    if (entry.filePath != null) {
+      try {
+        audio = readFileSync(entry.filePath)
+      } catch {
+        audio = null // swept/missing — lazy fallback
+      }
+    }
+    if (audio != null) {
+      await ctx.answerCallbackQuery({ text: '🔊' }).catch(() => {})
+      return audio
+    }
+    await ctx.answerCallbackQuery({ text: '🔊 Synthesizing…' }).catch(() => {})
+    // Local sidecar (kokoro) synthesis — same helper the immediate voice-out
+    // path uses. On-demand is a local-engine feature; the cache is only
+    // populated when resolveVoiceOutPlan gated the local verdict.
+    const sidecarToken = await materializeSidecarToken()
+    if (!sidecarToken) {
+      await ctx
+        .answerCallbackQuery({ text: 'Voice sidecar unavailable — try again later.' })
+        .catch(() => {})
+      return null
+    }
+    const result = await synthesizeViaSidecar({
+      token: sidecarToken,
+      // #2760 Phase 1: same deterministic normalization as the immediate
+      // voice-out path — the Listen lazy path builds its own /tts body from
+      // the persisted cache, so it must normalize independently (cache
+      // entries may predate the flag flip).
+      text: normalizeForTts(entry.text),
+      voice: entry.voice,
+      speed: entry.speed,
+    })
+    if (!result.ok) {
+      deps.log(
+        `telegram gateway: voice-out on-demand: synthesis failed reason=${result.reason}\n`,
+      )
+      await ctx
+        .answerCallbackQuery({ text: `Voice failed: ${result.reason}` })
+        .catch(() => {})
+      return null
+    }
+    return result.audio
+  }
+
+  // Fast path: if we already captured a reusable file_id, ack instantly and
+  // send BY the id — no disk read, no re-upload. First tap (no id yet) and a
+  // stale-id fallback both go through loadAudio + InputFile below and refresh
+  // the stored id from the returned message.
+  if (entry.telegramFileId != null) {
+    await ctx.answerCallbackQuery({ text: '🔊' }).catch(() => {})
+  }
+  const sendResult = await sendVoiceReusingFileId({
+    fileId: entry.telegramFileId ?? null,
+    sendByFileId: (fid) => deps.sendVoiceByFileId(cbChatId, fid, sendOpts, cbThreadId),
+    loadAudio,
+    sendByUpload: (audioOut) => deps.sendVoiceByUpload(cbChatId, audioOut, sendOpts, cbThreadId),
+    onFileId: (fid) => deps.voiceOnDemandCache.setTelegramFileId(tok, fid),
+    log: (line) => deps.log(line),
+  })
+
+  if (!sendResult.ok) {
+    // no-audio already surfaced a toast inside loadAudio; send-failed is
+    // logged non-fatally — the '🔊 Listen' keyboard is left intact so the
+    // user can retry (only a successful send strips it below).
+    if (sendResult.reason === 'send-failed') {
+      const err = sendResult.error
+      const msg = err instanceof Error ? err.message : String(err)
+      deps.log(
+        `telegram gateway: voice-out on-demand: sendVoice failed (non-fatal): ${msg}\n`,
+      )
+    }
+    return true
+  }
+  try {
+    // Single-use on SUCCESS: strip the '🔊 Listen' keyboard so the button
+    // can't be re-tapped now that the audio has been delivered. Mirrors the
+    // agent-button single_use strip (keyboardIsSingleUse) house style.
+    // Best-effort + non-fatal — a failed strip only leaves a replayable
+    // button, never drops the delivered audio. Only reached on a successful
+    // sendVoice; expiry / synth-failure / sidecar-unavailable all return
+    // earlier WITHOUT stripping, so the user can retry those.
+    if (cbMessageId != null) {
+      await deps.stripListenKeyboard(cbChatId, cbMessageId, cbThreadId).catch(() => {})
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    deps.log(
+      `telegram gateway: voice-out on-demand: strip-listen-keyboard failed (non-fatal): ${msg}\n`,
+    )
+  }
+  return true
+}

package/telegram-plugin/gateway/worker-feed-dispatch.ts

@@ -1,5 +1,45 @@
 import type { Subagent } from '../registry/subagents-schema.js'
 
+/**
+ * The narrow slice of the worker-activity feed `handleWorkerResume` needs —
+ * structurally satisfied by `WorkerActivityFeed` (worker-activity-feed.ts)
+ * without importing it (keeps this module dependency-light and the seam
+ * trivially mockable in tests).
+ */
+export interface WorkerFeedForResume {
+  resurrect(agentId: string): void
+}
+
+/**
+ * Issue #3373 (SendMessage-resume feed re-surface) — the gateway's `onResume`
+ * handler body, extracted so the seam is unit-testable and gateway.ts keeps
+ * only a thin delegation (the line-ratchet drains inline bodies).
+ *
+ * A worker with a GENUINE terminal completion that is resumed via SendMessage
+ * grows its jsonl past the terminal boundary and is re-registered live by the
+ * watcher (#3315). This clears the feed's terminal `finalized` latch
+ * (`feed.resurrect`) so the resumed worker's next onProgress cue repaints a
+ * fresh live row — without it the latch swallows every resumed cue and the
+ * worker reads as silence. Distinct from the #3023 `onResurrect` path: no
+ * bounded-chain budget (a worker may be stopped/resumed any number of times).
+ *
+ * Best-effort: a resurrect failure is logged, never thrown back into the
+ * watcher's poll loop. `feed` may be null/undefined (feed disabled) — the
+ * re-surface log line is still emitted for the audit trail.
+ */
+export function handleWorkerResume(
+  feed: WorkerFeedForResume | null | undefined,
+  agentId: string,
+  log: (msg: string) => void,
+): void {
+  try {
+    feed?.resurrect(agentId)
+  } catch (err) {
+    log(`telegram gateway: worker resume feed re-surface error agent=${agentId}: ${(err as Error).message}`)
+  }
+  log(`telegram gateway: worker ${agentId} card RE-SURFACED — resumed via SendMessage after a genuine terminal (issue #3373)`)
+}
+
 export interface WorkerFeedDispatch {
   /** True when the sub-agent was dispatched with `run_in_background: true`. */
   isBackground: boolean

package/telegram-plugin/narrative-dedup.ts

@@ -25,9 +25,32 @@
  * message.
  */
 
-/** Tools whose `input.text` IS the canonical answer surface. */
+/** Tool suffixes whose `input.text` IS the canonical answer surface. */
 export const REPLY_TOOLS = new Set(['reply', 'stream_reply'])
 
+/**
+ * Strip this plugin's `mcp__<server-key>__telegram__` prefix, matched by the
+ * same key-agnostic regex `computeLabel` / `isTelegramReplyTool` use so renames
+ * and forks (`clerk-telegram`, `switchroom-telegram`, …) all resolve. A bare
+ * name (no prefix) is returned unchanged.
+ */
+const TELEGRAM_TOOL_PREFIX_RE = /^mcp__[^_].*?telegram__/
+
+/**
+ * Prefix-aware membership test for {@link REPLY_TOOLS}.
+ *
+ * Production jsonl carries the fully-qualified MCP tool name
+ * (`mcp__switchroom-telegram__stream_reply`), so a bare `REPLY_TOOLS.has(name)`
+ * is always false in prod and the draft-then-send suppression path silently
+ * goes inert (#3231). Bare names ('reply' / 'stream_reply') can still appear
+ * from non-MCP sources, so both wire shapes must match: strip the telegram MCP
+ * prefix (a no-op for bare names) then test the suffix against REPLY_TOOLS.
+ */
+export function isReplyTool(toolName: string | null | undefined): boolean {
+  if (typeof toolName !== 'string') return false
+  return REPLY_TOOLS.has(toolName.replace(TELEGRAM_TOOL_PREFIX_RE, ''))
+}
+
 /**
  * Normalize for prefix comparison: strip markdown/HTML-ish emphasis,
  * heading and quote marks, collapse whitespace, lowercase. Mirrors the

package/telegram-plugin/narrative-flush.ts

@@ -39,7 +39,7 @@
  * effects and the per-turn lifetime.
  */
 
-import { REPLY_TOOLS, isDraftOfReply } from './narrative-dedup.js'
+import { isReplyTool, isDraftOfReply } from './narrative-dedup.js'
 
 /**
  * Time-box for the parked-narrative early-paint (the kernel's home for the
@@ -139,7 +139,7 @@ export class NarrativeFlushController {
   resolveOnTool(toolName: string, input: Record<string, unknown> | undefined): void {
     this.scheduler.disarm()
     const replyText =
-      REPLY_TOOLS.has(toolName) && typeof input?.text === 'string' ? (input.text as string) : null
+      isReplyTool(toolName) && typeof input?.text === 'string' ? (input.text as string) : null
     if (replyText != null) this.maybeRetract(replyText)
     const pending = this.pending
     if (pending == null) return

package/telegram-plugin/pending-user-notice.ts

@@ -36,6 +36,25 @@ export interface PendingUserNotice {
   kind: string
   /** When the notice was scheduled (ms epoch). */
   atMs: number
+  /**
+   * TOPIC KEY (#3294) — `statusKey(chatId, threadId)` of the turn that was live
+   * when the error surfaced, or `undefined` when no turn was attributable (the
+   * error arrived between turns, or after a silence poke nulled the live turn).
+   *
+   * Why it exists: the api_error operator event is agent-level (its wire
+   * `chatId` is always empty), so the gate USED to collapse per-agent and let
+   * ANY turn end resolve the notice. Under the PR-4e keyed-liveness flag
+   * (concurrent per-topic turns) that is a bug: turn B's reply-less end would
+   * flush turn A's pending notice while A may still recover — a FALSE "couldn't
+   * complete" claim. Keying the notice by the live turn's topic means only a
+   * turn end on the SAME topic resolves it (see {@link
+   * PendingUserNoticeGate.resolveTurnEnd}).
+   *
+   * A notice with an UNDEFINED key keeps the legacy agent-wide resolution (any
+   * turn end resolves it), so single-turn gateways — the current norm, where
+   * there is only ever one topic — are byte-identical to the pre-#3294 gate.
+   */
+  key?: string
 }
 
 /** How long a scheduled notice may wait for a resolving turn end. */
@@ -45,28 +64,55 @@ export class PendingUserNoticeGate {
   private pending: PendingUserNotice[] = []
 
   /**
-   * Schedule a notice for turn-end resolution. Collapses per agent — a burst
-   * of error lines within one turn holds ONE pending notice, not a stack.
+   * Schedule a notice for turn-end resolution. Collapses per (agent, topic key)
+   * — a burst of error lines within one turn holds ONE pending notice for that
+   * topic, not a stack. Distinct concurrent topics (keyed liveness) each keep
+   * their own pending notice, so one topic's burst never overwrites another's.
+   * (For a single-turn gateway every notice shares the one topic — or an
+   * undefined key — so the collapse is identical to the pre-#3294 per-agent one.)
    */
   schedule(notice: PendingUserNotice): void {
     this.prune(notice.atMs)
-    this.pending = this.pending.filter((p) => p.agent !== notice.agent)
+    this.pending = this.pending.filter(
+      (p) => !(p.agent === notice.agent && p.key === notice.key),
+    )
     this.pending.push(notice)
   }
 
   /**
-   * Resolve at turn end. `turnDeliveredReply` is the turn's outcome signal
-   * (the gateway passes `finalAnswerDelivered || replyCalled`):
-   *   - true  → the turn recovered; every pending notice is dropped, [] returned.
-   *   - false → the turn died without a reply; the un-expired pending notices
-   *     are returned EXACTLY ONCE for the caller to send.
-   * Either way the ledger is cleared (a notice never survives its turn end).
+   * Resolve at the end of the turn whose topic is `turnKey`. `turnDeliveredReply`
+   * is the turn's outcome signal (the gateway passes `finalAnswerDelivered ||
+   * replyCalled`).
+   *
+   * A pending notice is RESOLVED by this turn end iff it belongs to the ending
+   * turn's topic (`p.key === turnKey`) OR it is unattributed (`p.key ===
+   * undefined` — legacy agent-wide resolution, kept so single-turn gateways are
+   * unchanged). Notices scheduled for a DIFFERENT live topic stay pending until
+   * their own topic's turn ends (or the TTL expires) — this is the #3294 fix:
+   * turn B's end no longer flushes turn A's pending notice.
+   *
+   * Of the resolved notices:
+   *   - `turnDeliveredReply === true`  → the turn recovered; the resolved
+   *     notices are dropped and `[]` is returned.
+   *   - `turnDeliveredReply === false` → the turn died reply-less; the resolved,
+   *     un-expired notices are returned EXACTLY ONCE for the caller to send.
+   * Either way the resolved notices leave the ledger (a notice never survives
+   * the end of the turn it is keyed to).
    */
-  resolveTurnEnd(turnDeliveredReply: boolean, now: number = Date.now()): PendingUserNotice[] {
+  resolveTurnEnd(
+    turnKey: string | undefined,
+    turnDeliveredReply: boolean,
+    now: number = Date.now(),
+  ): PendingUserNotice[] {
     this.prune(now)
-    const out = turnDeliveredReply ? [] : [...this.pending]
-    this.pending = []
-    return out
+    const resolved: PendingUserNotice[] = []
+    const remaining: PendingUserNotice[] = []
+    for (const p of this.pending) {
+      if (p.key === turnKey || p.key === undefined) resolved.push(p)
+      else remaining.push(p)
+    }
+    this.pending = remaining
+    return turnDeliveredReply ? [] : resolved
   }
 
   /** True when at least one un-expired notice is pending (does not mutate). */

package/telegram-plugin/render/render.ts

@@ -203,10 +203,34 @@ function renderTable(node: TableNode): string {
   return [headerLine, sepLine, ...bodyLines].join("\n");
 }
 
+/**
+ * Escape a line-leading `#` in rendered PROSE so Telegram cannot promote the
+ * line to a heading (#3304 regression).
+ *
+ * Per CommonMark/GFM, `#` opens an ATX heading only when followed by a space,
+ * another `#`, or end-of-line — so micromark correctly parses `#3304 is
+ * merged.` as a plain paragraph, and this renderer re-emits it verbatim
+ * (`escapeMarkdown` deliberately leaves `#` alone). But Telegram's Bot API
+ * 10.1 server-side rich-markdown parser is NON-spec here: any line-leading
+ * `#` run is read as a heading, so an issue reference opening a line renders
+ * the whole paragraph as huge heading text. Backslash-escaping the first `#`
+ * of each such line keeps it literal on Telegram while remaining a no-op
+ * visually (Telegram honours backslash escapes, same mechanism the link-href
+ * `)` escape relies on).
+ *
+ * Applied ONLY to paragraph output (including paragraphs nested in
+ * blockquotes / list items via their renderBlock recursion), never to
+ * heading, code-block, or table nodes — so a genuine `# Title` heading node
+ * still renders as `# Title`.
+ */
+function escapeLineLeadingHash(text: string): string {
+  return text.replace(/^([ \t]{0,3})#/gm, "$1\\#");
+}
+
 function renderBlock(node: Block): string {
   switch (node.type) {
     case "paragraph":
-      return renderInlineChildren(node.children);
+      return escapeLineLeadingHash(renderInlineChildren(node.children));
     case "heading":
       return `${"#".repeat(node.level)} ${renderInlineChildren(node.children)}`;
     case "blockquote":

package/telegram-plugin/status-no-truncate.ts

@@ -28,6 +28,19 @@ import { RICH_MESSAGE_MAX_CHARS } from './format.js'
  */
 export const STATUS_ROLLING_LINES = 5
 
+/**
+ * Ceiling on the per-worker recent-step history RETAINED in `row.narrative`
+ * (worker-activity-feed.ts) and the deepest trail the worker cards will render.
+ *
+ * Distinct from `STATUS_ROLLING_LINES` (which governs the 🤖 agent card's
+ * window and stays at 5) so raising the worker trail never widens the agent
+ * card. Set to 6 because the deterministic per-worker depth curve
+ * (`workerHistoryDepth`, tool-activity-summary.ts) peaks at 6 for a lone
+ * worker — `max(3, 7 − workerCount)` at `w = 1`. The buffer must retain at
+ * least this many lines or the renderer would ask for 6 and only find 5.
+ */
+export const WORKER_HISTORY_MAX = 6
+
 /**
  * Per-line character cap, applied to every step + child step on BOTH
  * surfaces before HTML-escaping (clip raw → escape last). A line longer