switchroom 0.5.0

package/telegram-plugin/stream-reply-handler.ts

@@ -0,0 +1,664 @@
+/**
+ * `stream_reply` MCP tool handler — extracted from server.ts.
+ *
+ * The server.ts case block was ~110 lines of state-machine + I/O mixed
+ * together. This module pulls the logic into a pure-ish function with
+ * injected deps so it can be exercised by an integration test against
+ * the mock bot harness.
+ *
+ * Contract:
+ *   - First call for a chat+thread: creates a stream via
+ *     createStreamController, optionally prepending a handoff prefix.
+ *   - Subsequent calls: reuse the existing stream, push the new text.
+ *   - `done=true`: finalize, delete the map entry, fire status-reaction
+ *     completion, and (if history enabled) record the final message.
+ *   - Returns the message id + terminal status text that server.ts
+ *     wraps into an MCP content response.
+ */
+
+import type { DraftStreamHandle, StreamDraftFn } from './draft-stream.js'
+import {
+  createStreamController,
+  type StreamBotApi,
+  type RetryPolicy,
+} from './stream-controller.js'
+import { sanitizeTelegramHtml } from './html-sanitize.js'
+
+/**
+ * Builds the inline status-accent header line for `reply` / `stream_reply`.
+ *
+ * Returns a string to prepend to the effective (already-rendered) message
+ * body, including a trailing blank line so the header is visually separated.
+ * Returns an empty string when accent is undefined or unrecognised (silent
+ * ignore) so calls without `accent` produce identical output to today.
+ *
+ * The header uses Telegram HTML tags. Callers must ensure parseMode is HTML
+ * (or that the body has already been rendered to HTML) before prepending.
+ */
+export function buildAccentHeader(accent: string | undefined): string {
+  switch (accent) {
+    case 'in-progress':
+      return '🔵 <i>In progress…</i>\n\n'
+    case 'done':
+      return '✅ <b>Done</b>\n\n'
+    case 'issue':
+      return '⚠️ <b>Issue</b>\n\n'
+    default:
+      return ''
+  }
+}
+
+export interface StreamReplyArgs {
+  chat_id: string
+  text: string
+  done?: boolean
+  message_thread_id?: string
+  format?: string
+  /**
+   * Optional named lane. Each lane gets its own Telegram message per
+   * chat+thread — useful for surfacing "thinking" alongside the main
+   * "answer" stream. Lane names are caller-defined. Omit for the
+   * default (unnamed) lane, which preserves legacy behavior.
+   */
+  lane?: string
+  /**
+   * Explicit quote-reply target. When set, the initial streamed message
+   * quote-threads under this message_id. Overrides the default auto-quote
+   * behavior and ignores `quote`.
+   */
+  reply_to?: string
+  /**
+   * Opt out of the default quote-reply behavior. The handler's default
+   * (when `reply_to` is unset) is to look up the latest inbound user
+   * message via `getLatestInboundMessageId` and quote-reply to it. Pass
+   * `false` to send a bare (non-quoted) streamed message.
+   *
+   * The default is `undefined` (treated as true) so callers that pre-date
+   * this feature keep working. Only the progress-card / activity-lane
+   * internal callers routinely opt out, since those aren't user-visible
+   * conversation replies.
+   */
+  quote?: boolean
+  /**
+   * Optional turn identifier used to multiplex concurrent turns on the
+   * same chat+thread+lane. Without this, two concurrent turns emitting
+   * on the same lane (e.g. both on lane:'progress') collapse into a
+   * single draft stream and their Telegram messages flap between each
+   * other. The progress-card driver passes its unique per-turn key here
+   * so each active turn gets its own draft stream + pinned card. Other
+   * lane callers may leave this undefined to preserve legacy behavior.
+   */
+  turnKey?: string
+  /**
+   * Inline keyboard markup. When set, every send and edit for this stream
+   * includes it so Telegram doesn't strip an attached keyboard on text
+   * updates. Used by the progress-card driver to persist the Steer button.
+   */
+  reply_markup?: unknown
+  /**
+   * When true, Telegram prevents the message from being forwarded or saved.
+   * Applied on the initial send only (editMessageText ignores it).
+   */
+  protect_content?: boolean
+  /**
+   * Optional surgical quote text. When set along with `reply_to`, the initial
+   * send includes `reply_parameters: { message_id, quote: { text, position: 0 } }`
+   * so Telegram highlights the specific quoted sentence rather than the whole
+   * referenced message. Ignored when `reply_to` is absent.
+   */
+  quote_text?: string
+  /**
+   * Optional status accent prepended as a leading header line (issue #320
+   * fallback for missing Telegram quote-bar color API).
+   *
+   * - `'in-progress'` → `🔵 <i>In progress…</i>\n\n`
+   * - `'done'`        → `✅ <b>Done</b>\n\n`
+   * - `'issue'`       → `⚠️ <b>Issue</b>\n\n`
+   *
+   * Unrecognised values are silently ignored. Omit for plain reply (default
+   * behavior — identical to today's output).
+   */
+  accent?: string
+}
+
+export interface StreamReplyState {
+  activeDraftStreams: Map<string, DraftStreamHandle>
+  /**
+   * Tracks the parseMode each active stream was created with, keyed the
+   * same way as `activeDraftStreams`. Used by `handleStreamReply` to
+   * detect when a subsequent call's resolved parseMode differs from the
+   * one baked into the existing stream controller — in that case the
+   * stale stream is finalized + discarded and a fresh one is created
+   * with the new parseMode (see bug 1: PTY-tail creates an activity-lane
+   * stream with parseMode=undefined; a later explicit stream_reply on
+   * the same key with format:'html' would otherwise inherit undefined
+   * and send literal markdown).
+   *
+   * Optional for backwards compatibility with external callers that
+   * construct a StreamReplyState without it.
+   */
+  activeDraftParseModes?: Map<string, 'HTML' | 'MarkdownV2' | undefined>
+  /**
+   * Chats whose PTY preview is claimed by an in-flight reply/stream_reply
+   * handler. PTY-tail partials for these keys are dropped to avoid
+   * duplicate messages. Historically only the `reply` tool added to this
+   * set; `stream_reply` did not, so a PTY partial firing after a
+   * finalized stream would create a duplicate message with the raw TUI
+   * text (see regression in telegram-plugin.log where msg 559 was
+   * followed by a duplicate msg 560 via path=pty_preview). stream_reply
+   * now claims the slot on the first call so later PTY partials are
+   * suppressed for the rest of the turn.
+   *
+   * Optional for backwards compatibility with callers that don't yet
+   * thread this state through — without it the bug reopens silently.
+   */
+  suppressPtyPreview?: Set<string>
+}
+
+export interface StreamReplyDeps {
+  bot: { api: StreamBotApi }
+  retry?: RetryPolicy
+  /** Markdown → HTML renderer (used when format === 'html'). */
+  markdownToHtml: (text: string) => string
+  /** MarkdownV2 escaper (used when format === 'markdownv2'). */
+  escapeMarkdownV2: (text: string) => string
+  /** Whitespace repair applied to the raw caller text. */
+  repairEscapedWhitespace: (text: string) => string
+  /** Resolves the handoff prefix for a first-chunk stream. Empty string if none. */
+  takeHandoffPrefix: (format: 'html' | 'markdownv2' | 'text') => string
+  /** Validates the chat id against the access list. Throws on deny. */
+  assertAllowedChat: (chatId: string) => void
+  /** Resolves the effective thread id (explicit, last-inbound, or undefined). */
+  resolveThreadId: (chatId: string, explicit?: string) => number | undefined
+  /**
+   * Resolves the default quote-reply target: the message_id of the latest
+   * inbound user message in this chat+thread, or null if none (empty
+   * history, or history disabled). Called only when the caller didn't
+   * pass `reply_to` and didn't opt out via `quote:false`. Optional —
+   * omit to disable the auto-quote default (legacy behavior).
+   */
+  getLatestInboundMessageId?: (chatId: string, threadId: number | null) => number | null
+  /** Config: disable link previews. Default true. */
+  disableLinkPreview: boolean
+  /** Config: fallback parse mode when args.format is omitted ('html' | 'markdownv2' | 'text'). */
+  defaultFormat: string
+  /** Observability: per-call event. */
+  logStreamingEvent: (ev: {
+    kind: 'stream_reply_called'
+    chatId: string
+    charCount: number
+    done: boolean
+    streamExisted: boolean
+  } | {
+    kind: 'draft_send'
+    chatId: string
+    messageId: number
+    charCount: number
+  } | {
+    kind: 'draft_edit'
+    chatId: string
+    messageId: number
+    charCount: number
+    sameAsLast: boolean
+  }) => void
+  /** Called on done=true to transition the status reaction controller. */
+  endStatusReaction: (chatId: string, threadId: number | undefined, verdict: 'done') => void
+  /**
+   * Optional: progress-card driver completion hook. Wired by the gateway
+   * to `progressDriver.forceCompleteTurn(...)`. Invoked after a
+   * `stream_reply(done=true)` on the default (unnamed) lane finalizes,
+   * so the final-answer delivery acts as an authoritative turn-complete
+   * signal equal to session-tail `turn_end`. Skipped when args.lane is
+   * 'progress' (that's the driver's own emit — calling this would cause
+   * re-entry). Safe to leave unset for callers that don't use the driver.
+   */
+  forceCompleteTurn?: (chatId: string, threadId: number | undefined) => void
+  /**
+   * Optional: progress-card driver delivery counter hook. Wired by the
+   * gateway to `progressDriver.recordOutboundDelivered(...)`. Called
+   * BEFORE `forceCompleteTurn` so the driver's per-turn outbound counter
+   * is non-zero when the terminal render fires. Without this ordering
+   * guarantee, `forceCompleteTurn` flushes the card while
+   * `outboundDeliveredCount === 0` → ⚠️ false positive (issue #310).
+   * Only called on the default (unnamed) lane when `done=true` and the
+   * stream produced a non-null messageId. Safe to leave unset for callers
+   * that don't use the driver.
+   */
+  recordOutboundDelivered?: (chatId: string, threadId: number | undefined) => void
+  /** Whether to persist outbound history. */
+  historyEnabled: boolean
+  /** History row writer. Only called when historyEnabled && done && messageId != null. */
+  recordOutbound: (row: {
+    chat_id: string
+    thread_id: number | null
+    message_ids: number[]
+    texts: string[]
+  }) => void
+  /** Error-path stderr. */
+  writeError: (line: string) => void
+  throttleMs?: number
+  /**
+   * sendMessageDraft callback. When provided, stream_reply uses the draft
+   * API for intermediate updates (DM transport). On done=true, a real
+   * sendMessage fires for push notification, then the draft is cleared.
+   * Optional — omit to keep the existing sendMessage/editMessageText path.
+   */
+  sendMessageDraft?: StreamDraftFn
+  /**
+   * Idempotency hook for the duplicate-message class (issue #626).
+   *
+   * On every call where the handler would CREATE a new stream (no entry
+   * in `state.activeDraftStreams[sKey]`), this callback is consulted to
+   * see whether an external authority already knows the anchor message
+   * id for this lane+turn. If it returns a number, the new stream is
+   * initialized as if a previous send had landed with that id — the
+   * very next update fires `editMessageText` instead of `sendMessage`.
+   *
+   * Wired by the gateway to `pinMgr.pinnedMessageId(turnKey, agentId)`
+   * for the progress card. Without this hook, a `done=true` finalize
+   * deletes `activeDraftStreams[sKey]`, and the next emit on the same
+   * turn creates a fresh sendMessage — visible to the user as a second
+   * "status message" landing instead of an edit. The not-found
+   * fallback in draft-stream gracefully handles a stale id.
+   *
+   * Safe to omit. Optional. Returns null/undefined to fall through to
+   * the standard "first call sends" behavior.
+   */
+  lookupExistingMessageId?: (key: {
+    chatId: string
+    threadId: number | undefined
+    lane: string | undefined
+    turnKey: string | undefined
+  }) => number | null | undefined
+  /**
+   * True when the current chat is a private DM. Passed to the stream
+   * controller so "auto" transport activates draft in DMs only.
+   */
+  isPrivateChat?: boolean
+  /**
+   * True when the current chat is a forum topic. Forum topics do not
+   * support sendMessageDraft — this forces message transport.
+   */
+  isForumTopic?: boolean
+  /**
+   * When true, the progress-card driver is emitting a live checklist on
+   * the `progress` lane and owns mid-turn display. In that mode, a
+   * caller-initiated `stream_reply` on the default (unnamed) lane with
+   * `done=false` is suppressed — the card already shows what's happening,
+   * and a parallel default-lane message is visible noise (a duplicate
+   * surface for the same turn). The final `done=true` call still posts
+   * as the answer message.
+   *
+   * Named-lane calls (lane: 'progress', 'thinking', etc.) are always
+   * honored — this flag only gates the default lane. Omit or leave false
+   * to preserve legacy behavior.
+   */
+  progressCardActive?: boolean
+}
+
+export interface StreamReplyResult {
+  messageId: number | null
+  status: 'updated' | 'finalized'
+}
+
+function streamKey(
+  chatId: string,
+  threadId?: number,
+  lane?: string,
+  turnKey?: string,
+): string {
+  const base = `${chatId}:${threadId ?? '_'}`
+  const withLane = lane != null && lane.length > 0 ? `${base}:${lane}` : base
+  return turnKey != null && turnKey.length > 0 ? `${withLane}:${turnKey}` : withLane
+}
+
+export async function handleStreamReply(
+  args: StreamReplyArgs,
+  state: StreamReplyState,
+  deps: StreamReplyDeps,
+): Promise<StreamReplyResult> {
+  const chat_id = args.chat_id
+  const rawText = deps.repairEscapedWhitespace(args.text)
+  const done = Boolean(args.done)
+  const format = args.format ?? deps.defaultFormat
+  if (done) {
+    process.stderr.write(`telegram channel: stream_reply: invoked done=true chatId=${chat_id} lane=${args.lane ?? 'default'} charCount=${rawText.length}\n`)
+  }
+
+  // Access check runs BEFORE any other branch: a denied chat id must
+  // throw regardless of streaming mode. Previously the suppression path
+  // silently "succeeded" for unauthorized chats.
+  deps.assertAllowedChat(chat_id)
+  const threadId = deps.resolveThreadId(chat_id, args.message_thread_id)
+
+  // Note: caller-initiated stream_reply(done=false) used to be rejected
+  // when the progress card was active. The card and the answer message
+  // live on different lanes (progress vs default) and render different
+  // content (tool structure vs model prose), so they don't actually
+  // collide — the rejection forced single-shot final replies and broke
+  // the progressive-streaming contract documented in
+  // profiles/default/CLAUDE.md. See #481.
+
+  let parseMode: 'HTML' | 'MarkdownV2' | undefined
+  let effectiveText: string
+  if (format === 'html') {
+    parseMode = 'HTML'
+    // Pre-validate the rendered HTML against Telegram's tag allowlist
+    // before send. The sanitizer escapes unknown tags, drops disallowed
+    // attributes, and auto-closes unbalanced tags so we don't trip
+    // Telegram's `400 Bad Request: can't parse entities` (issue #657).
+    effectiveText = sanitizeTelegramHtml(deps.markdownToHtml(rawText))
+  } else if (format === 'markdownv2') {
+    parseMode = 'MarkdownV2'
+    effectiveText = deps.escapeMarkdownV2(rawText)
+  } else {
+    parseMode = undefined
+    effectiveText = rawText
+  }
+
+  // Inline status-accent header (issue #320 fallback). Prepended AFTER
+  // format rendering so it leads the fully-rendered body. Since
+  // stream_reply callers pass the full text snapshot each call, the
+  // header is prepended on every call that supplies `accent` — this
+  // keeps the rendered message consistent across edits. Callers that
+  // don't want the header on a subsequent edit simply omit `accent`.
+  // Unrecognised values are silently ignored (empty string returned).
+  if (args.accent != null) {
+    const accentHeader = buildAccentHeader(args.accent)
+    if (accentHeader.length > 0) {
+      effectiveText = accentHeader + effectiveText
+      // Re-sanitize after prepending the HTML header so the combined
+      // body is still guaranteed parse-mode=HTML safe.
+      if (parseMode === 'HTML') {
+        effectiveText = sanitizeTelegramHtml(effectiveText)
+      }
+    }
+  }
+
+  // Over-limit pre-check. Throws BEFORE touching stream state so that
+  // (a) a first call over 4096 fails cleanly instead of creating a
+  // half-initialized stream, and (b) a mid-stream update over 4096
+  // fails loudly instead of setting the internal `stopped=true` flag
+  // and silently dropping all subsequent text. Either way the caller
+  // sees isError:true and can fall back to `reply`, which chunks.
+  // Check the rendered text (post-markdown-to-HTML) because that's
+  // what actually goes to Telegram's 4096-char wire limit.
+  if (effectiveText.length > 4096) {
+    throw new Error(
+      `stream_reply rejected: text exceeds Telegram's 4096-char limit ` +
+        `(length=${effectiveText.length}, format=${format}). stream_reply does not ` +
+        `auto-chunk — split the text or use \`reply\`, which chunks.`,
+    )
+  }
+
+  const sKey = streamKey(chat_id, threadId, args.lane, args.turnKey)
+  // Claim the PTY-preview slot so any PTY-tail partial that fires mid-
+  // or post-turn for this chat+thread is dropped. Keyed WITHOUT lane
+  // because the PTY handler uses the lane-less key and we need to
+  // suppress its default lane regardless of which lane stream_reply
+  // targets. Cleared on turn_end by server.ts.
+  state.suppressPtyPreview?.add(streamKey(chat_id, threadId))
+  let stream = state.activeDraftStreams.get(sKey)
+
+  // Bug 1 fix: parseMode is baked into the stream controller at creation
+  // time. If a prior call created the stream with a different parseMode
+  // (e.g. PTY-tail auto-stream using 'text' → undefined, followed by an
+  // explicit stream_reply with format:'html'), reusing it would send
+  // literal markdown. Finalize + discard the stale stream so the block
+  // below creates a fresh one with the correct parseMode.
+  if (stream != null && state.activeDraftParseModes != null) {
+    const existingParseMode = state.activeDraftParseModes.get(sKey)
+    if (existingParseMode !== parseMode) {
+      try {
+        await stream.finalize()
+      } catch (err) {
+        // Best-effort: the in-flight edit may 429 or race. Surface to
+        // stderr so the orphaned message id isn't invisible.
+        deps.writeError(
+          `telegram channel: stream_reply parseMode-rotation finalize failed: ${err}\n`,
+        )
+      }
+      state.activeDraftStreams.delete(sKey)
+      state.activeDraftParseModes.delete(sKey)
+      stream = undefined
+    }
+  }
+
+  const streamExisted = stream != null
+
+  deps.logStreamingEvent({
+    kind: 'stream_reply_called',
+    chatId: chat_id,
+    charCount: effectiveText.length,
+    done,
+    streamExisted,
+  })
+
+  // First chunk of a session: consume any pending handoff prefix.
+  if (!stream) {
+    const prefix = deps.takeHandoffPrefix(
+      format === 'html' ? 'html' : format === 'markdownv2' ? 'markdownv2' : 'text',
+    )
+    if (prefix.length > 0) effectiveText = prefix + effectiveText
+  }
+
+  if (!stream) {
+    // Resolve the effective quote-reply target. Explicit `reply_to` wins;
+    // otherwise (unless the caller opted out with `quote:false`) fall back
+    // to the latest inbound user message in this chat+thread. Resolved
+    // only on stream creation — subsequent `stream_reply` calls for the
+    // same turn edit the existing message, which Telegram doesn't allow
+    // us to add a quote reference to retroactively.
+    let replyToMessageId: number | undefined
+    if (args.reply_to != null) {
+      replyToMessageId = Number(args.reply_to)
+    } else if (args.quote !== false && deps.getLatestInboundMessageId != null) {
+      try {
+        const latest = deps.getLatestInboundMessageId(chat_id, threadId ?? null)
+        if (latest != null) replyToMessageId = latest
+      } catch (err) {
+        deps.writeError(
+          `telegram channel: stream_reply quote-lookup failed: ${err}\n`,
+        )
+      }
+    }
+
+    // Resolve draft-transport options. Forum topics force message transport
+    // because sendMessageDraft does not support threads.
+    const isForumTopic = deps.isForumTopic === true
+    const resolvedTransport: 'auto' | 'message' | 'draft' =
+      isForumTopic || deps.sendMessageDraft == null
+        ? 'message'
+        : 'auto'
+
+    // Idempotency hook (#626): if an external authority (e.g. the
+    // gateway's pin manager) already knows the anchor message id for
+    // this lane+turn, initialize the stream with it so the next update
+    // edits in place rather than creating a fresh sendMessage. This
+    // closes the "done=true → activeDraftStreams entry deleted → next
+    // emit creates fresh sendMessage" path that produced multiple
+    // status messages per turn.
+    let initialMessageId: number | undefined
+    if (deps.lookupExistingMessageId != null) {
+      try {
+        const looked = deps.lookupExistingMessageId({
+          chatId: chat_id,
+          threadId,
+          lane: args.lane,
+          turnKey: args.turnKey,
+        })
+        if (typeof looked === 'number' && Number.isFinite(looked)) {
+          initialMessageId = looked
+        }
+      } catch (err) {
+        deps.writeError(
+          `telegram channel: stream_reply lookupExistingMessageId failed: ${err}\n`,
+        )
+      }
+    }
+
+    stream = createStreamController({
+      bot: deps.bot,
+      chatId: chat_id,
+      threadId,
+      parseMode,
+      disableLinkPreview: deps.disableLinkPreview,
+      throttleMs: deps.throttleMs ?? 600,
+      retry: deps.retry,
+      ...(replyToMessageId != null ? { replyToMessageId } : {}),
+      ...(args.quote_text != null && replyToMessageId != null ? { quoteText: args.quote_text } : {}),
+      ...(args.protect_content === true ? { protectContent: true } : {}),
+      ...(args.reply_markup != null ? { replyMarkup: args.reply_markup } : {}),
+      previewTransport: resolvedTransport,
+      isPrivateChat: deps.isPrivateChat === true,
+      ...(deps.sendMessageDraft != null ? { sendMessageDraft: deps.sendMessageDraft } : {}),
+      ...(initialMessageId != null ? { initialMessageId } : {}),
+      onSend: (messageId, charCount) =>
+        deps.logStreamingEvent({ kind: 'draft_send', chatId: chat_id, messageId, charCount }),
+      onEdit: (messageId, charCount) =>
+        deps.logStreamingEvent({
+          kind: 'draft_edit',
+          chatId: chat_id,
+          messageId,
+          charCount,
+          sameAsLast: false,
+        }),
+      // Route draft-stream diagnostics through the handler's stderr
+      // writer so transient failures are observable. Filter routine
+      // success chatter (sent/edited/finalized) — those are already
+      // captured by the structured onSend/onEdit observers — and only
+      // surface warnings/errors (stopped, edit failed, not-found
+      // recovery).
+      log: (msg) => {
+        if (
+          msg.startsWith('stream → sent')
+          || msg.startsWith('stream → edited')
+          || msg.startsWith('stream → not modified')
+          || msg.startsWith('stream finalized')
+          || msg.startsWith('stream → draft')
+          || msg.startsWith('stream → materialized')
+        ) return
+        deps.writeError(`telegram channel: stream_reply ${msg}\n`)
+      },
+      warn: (msg) => {
+        deps.writeError(`telegram channel: stream_reply ${msg}\n`)
+      },
+    })
+    state.activeDraftStreams.set(sKey, stream)
+    state.activeDraftParseModes?.set(sKey, parseMode)
+  }
+
+  await stream.update(effectiveText)
+
+  if (done) {
+    await stream.finalize()
+    state.activeDraftStreams.delete(sKey)
+    state.activeDraftParseModes?.delete(sKey)
+    // Bug Z fix: fire the terminal 👍 here, gated to the default
+    // (unnamed) lane and only after finalize() resolves so the emoji is
+    // tied to the final edit actually landing in Telegram.
+    //
+    // History (see prior comment removed in this commit): we previously
+    // deferred the 👍 to turn_end on the theory that a turn might call
+    // stream_reply(done=true) mid-flight and continue working. In
+    // practice the dedup-suppress branch in turn_end was firing setDone
+    // off a 500ms-lagged read of local history rather than from a real
+    // delivery confirmation, and the disconnect-flush path was leaving
+    // 👍 firing on disconnect even when the final edit had failed.
+    // Wiring endStatusReaction at the post-finalize callback keeps the
+    // emoji honest — it now means "the final draft edit hit Telegram".
+    //
+    // Gated to the default lane: named lanes (lane:'progress',
+    // lane:'thinking', lane:'activity', etc.) are internal driver
+    // emits, not user-visible answers — they must not be allowed to
+    // claim turn-completion. A lane:'progress' emit firing setDone
+    // would race the actual answer.
+    //
+    // Mid-turn done=true tradeoff: a turn that calls
+    // stream_reply(done=true) on the default lane and then continues
+    // working will fire 👍 early; subsequent intermediate emojis become
+    // no-ops (setDone is terminal). This is the contract: done=true on
+    // the default lane is "the answer is delivered". Agents that need
+    // to continue should use additional `reply` calls or named lanes.
+    const isDefaultLaneForCompletion = args.lane == null || args.lane.length === 0
+    if (isDefaultLaneForCompletion && stream.getMessageId() != null) {
+      try {
+        deps.endStatusReaction(chat_id, threadId, 'done')
+      } catch (err) {
+        deps.writeError(`telegram channel: stream_reply: endStatusReaction hook threw: ${err}\n`)
+      }
+    }
+
+    // Hard-fail surface: if the stream finalized without ever assigning
+    // a message id, the initial send never landed (4096+ chars hits
+    // draft-stream's length guard and silently stops). Throw so the MCP
+    // caller sees isError:true instead of a misleading "finalized
+    // (id: pending)". The caller can fall back to `reply`, which chunks.
+    if (stream.getMessageId() == null) {
+      throw new Error(
+        `stream_reply finalized without sending any message (length=${rawText.length}, ` +
+          `max=4096). Telegram's per-message limit is 4096 chars and stream_reply does not ` +
+          `auto-chunk. Split the text or use \`reply\` (which chunks).`,
+      )
+    }
+
+    if (deps.historyEnabled) {
+      const finalId = stream.getMessageId()
+      if (finalId != null) {
+        try {
+          deps.recordOutbound({
+            chat_id,
+            thread_id: threadId ?? null,
+            message_ids: [finalId],
+            texts: [rawText],
+          })
+        } catch (err) {
+          deps.writeError(
+            `telegram channel: history recordOutbound (stream_reply) failed: ${err}\n`,
+          )
+        }
+      }
+    }
+  }
+
+  const finalMessageId = stream.getMessageId()
+  if (done) {
+    process.stderr.write(`telegram channel: stream_reply: finalized done=true chatId=${chat_id} lane=${args.lane ?? 'default'} messageId=${finalMessageId ?? 'null'}\n`)
+    const isDefaultLaneForCompletion = args.lane == null || args.lane.length === 0
+    // Issue #310: record delivery BEFORE forceCompleteTurn so the
+    // progress-card driver's outboundDeliveredCount is non-zero when the
+    // terminal render fires. forceCompleteTurn synchronously flushes the
+    // card; if we recorded after that flush, outboundDeliveredCount would
+    // still be 0 at render time → ⚠️ false positive even though the
+    // message landed. Only record when a messageId is confirmed — a null
+    // id means the send never succeeded and the ⚠️ branch is correct.
+    if (
+      deps.recordOutboundDelivered != null
+      && finalMessageId != null
+      && isDefaultLaneForCompletion
+    ) {
+      try {
+        deps.recordOutboundDelivered(chat_id, threadId)
+      } catch (err) {
+        deps.writeError(`telegram channel: stream_reply: recordOutboundDelivered hook threw: ${err}\n`)
+      }
+    }
+    // Fire the authoritative turn-complete signal to the progress-card
+    // driver so any in-flight card for this chat is closed out alongside
+    // the final answer landing. Only for the default (unnamed) lane —
+    // the progress lane is the driver's own emit path and routing
+    // completion through it would re-enter the driver from within its
+    // own flush. Idempotent on the driver side: first caller wins.
+    if (deps.forceCompleteTurn != null && isDefaultLaneForCompletion) {
+      try {
+        deps.forceCompleteTurn(chat_id, threadId)
+      } catch (err) {
+        deps.writeError(`telegram channel: stream_reply: forceCompleteTurn hook threw: ${err}\n`)
+      }
+    }
+  }
+  return {
+    messageId: finalMessageId,
+    status: done ? 'finalized' : 'updated',
+  }
+}