switchroom 0.5.0

package/telegram-plugin/sticker-aliases.ts

@@ -0,0 +1,249 @@
+/**
+ * Pure helpers for the `send_sticker` MCP tool's alias-resolution path.
+ *
+ * Stickers in Telegram are addressed by `file_id` — opaque, ~70-char,
+ * agent-unfriendly. To make outbound stickers usable by personas we
+ * let operators declare named aliases in switchroom.yaml under
+ * `telegram.stickers: { mood_happy: "<file_id>", thinking: "<file_id>" }`.
+ * The agent then calls `send_sticker(chat_id, alias='mood_happy')` and
+ * we resolve to the file_id at send time.
+ *
+ * This file owns the resolution + validation. Pure — no Telegram API
+ * calls, no I/O, fully unit-testable.
+ *
+ * Why operator-curated and not Tenor/Giphy: subscription-honest
+ * principle says no third-party API keys. Stickers the agent wants to
+ * send must be ones an operator has explicitly approved by capturing
+ * a file_id and putting it in config. Same model the existing access
+ * surface uses: trust-by-explicit-listing.
+ */
+
+export interface StickerAliasMap {
+  /** alias name → Telegram file_id. Both validated on read. */
+  [alias: string]: string
+}
+
+export interface StickerSendArgs {
+  chat_id: string
+  /** Either a raw Telegram file_id OR an alias declared in
+   *  `telegram.stickers`. We accept both to match the agent's
+   *  conversational intent: it might pass `'mood_happy'` from the
+   *  config, or echo back a file_id it saw on inbound. */
+  sticker: string
+  message_thread_id?: string
+  reply_to?: string
+}
+
+export interface ValidatedStickerSendArgs {
+  chatId: string
+  fileId: string
+  /** What the resolution path was, for log lines + telemetry. Lets
+   *  operators see "agent used alias 'happy' which mapped to file_id
+   *  CAACAg..." vs "agent passed raw file_id." */
+  resolution: 'alias' | 'raw'
+  /** Original alias name if resolution === 'alias'. */
+  aliasName?: string
+  threadId?: number
+  replyTo?: number
+}
+
+/**
+ * Telegram file_ids are alphanumeric + `-` + `_`, typically 50-100
+ * chars. Reject anything outside that shape early so the agent gets
+ * a clear error rather than Telegram's generic 400.
+ *
+ * The 200-char ceiling matches the existing `download_attachment`
+ * tool's validator — same shape across the surface.
+ */
+export function looksLikeFileId(s: string): boolean {
+  return /^[A-Za-z0-9_-]{10,200}$/.test(s)
+}
+
+/**
+ * Aliases are operator-typed config keys. Restrict to safe shell-ish
+ * characters so a misconfigured alias can't accidentally collide with
+ * a file_id on the boundary, and so config files stay diff-friendly.
+ */
+export function isValidAliasName(s: string): boolean {
+  return /^[a-z0-9][a-z0-9_-]{0,63}$/i.test(s)
+}
+
+/**
+ * Validate raw sticker-send args + resolve any alias against the
+ * configured map. Throws with an actionable error on every failure
+ * mode so the agent's tool-error reply tells the user (or operator)
+ * exactly what to fix.
+ */
+export function resolveStickerSendArgs(
+  raw: StickerSendArgs,
+  aliasMap: StickerAliasMap,
+): ValidatedStickerSendArgs {
+  if (typeof raw.chat_id !== 'string' || raw.chat_id.length === 0) {
+    throw new Error('send_sticker: chat_id is required')
+  }
+  if (typeof raw.sticker !== 'string' || raw.sticker.length === 0) {
+    throw new Error('send_sticker: sticker (file_id or alias) is required')
+  }
+
+  let fileId: string
+  let resolution: 'alias' | 'raw'
+  let aliasName: string | undefined
+
+  // Distinguishing alias vs file_id: file_ids include only alnum + `-`
+  // + `_`, but they're long (50-100). Aliases are short (under 64).
+  // First check: is it a known alias? If yes, use that. Otherwise, is
+  // it a valid file_id? If yes, pass through. Otherwise, error.
+  //
+  // The "known alias" check first means an operator can never have an
+  // alias collide with a file_id by accident — config wins.
+  if (Object.prototype.hasOwnProperty.call(aliasMap, raw.sticker)) {
+    aliasName = raw.sticker
+    fileId = aliasMap[raw.sticker]
+    resolution = 'alias'
+    if (!looksLikeFileId(fileId)) {
+      throw new Error(
+        `send_sticker: alias '${raw.sticker}' resolves to malformed file_id ` +
+        `in switchroom.yaml — fix telegram.stickers.${raw.sticker}`,
+      )
+    }
+  } else if (looksLikeFileId(raw.sticker)) {
+    fileId = raw.sticker
+    resolution = 'raw'
+  } else if (isValidAliasName(raw.sticker)) {
+    // The agent asked for an alias that doesn't exist. Tell it
+    // explicitly so it can ask the user to add one or pick a
+    // different one.
+    const known = Object.keys(aliasMap).sort()
+    const hint = known.length > 0
+      ? ` Available aliases: ${known.join(', ')}.`
+      : ' No sticker aliases are configured for this agent.'
+    throw new Error(`send_sticker: unknown alias '${raw.sticker}'.${hint}`)
+  } else {
+    throw new Error(
+      `send_sticker: '${raw.sticker}' is neither a valid Telegram file_id ` +
+      `nor a configured alias name`,
+    )
+  }
+
+  let threadId: number | undefined
+  if (raw.message_thread_id != null) {
+    threadId = Number(raw.message_thread_id)
+    if (!Number.isFinite(threadId) || threadId <= 0) {
+      throw new Error('send_sticker: message_thread_id must be a positive integer string')
+    }
+  }
+  let replyTo: number | undefined
+  if (raw.reply_to != null) {
+    replyTo = Number(raw.reply_to)
+    if (!Number.isFinite(replyTo) || replyTo <= 0) {
+      throw new Error('send_sticker: reply_to must be a positive integer string')
+    }
+  }
+
+  return {
+    chatId: raw.chat_id,
+    fileId,
+    resolution,
+    aliasName,
+    threadId,
+    replyTo,
+  }
+}
+
+export interface GifSendArgs {
+  chat_id: string
+  /** Either a Telegram file_id OR an https URL pointing at an
+   *  animated mp4/gif. URLs let agents embed GIFs from operator-
+   *  curated sources without the alias-config overhead — but we
+   *  validate the URL is https + has a known media extension. */
+  gif: string
+  caption?: string
+  message_thread_id?: string
+  reply_to?: string
+}
+
+export interface ValidatedGifSendArgs {
+  chatId: string
+  /** Either a file_id or a URL — Telegram's sendAnimation accepts
+   *  both via the same `animation` field. */
+  animationRef: string
+  refKind: 'file_id' | 'url'
+  caption?: string
+  threadId?: number
+  replyTo?: number
+}
+
+/**
+ * Animated-media URLs: https, ends in `.mp4` / `.gif` / `.webm`.
+ * Telegram accepts these via sendAnimation's URL form. Reject other
+ * URLs so the agent can't accidentally try to embed an HTML page.
+ */
+export function isAcceptableGifUrl(s: string): boolean {
+  if (!/^https:\/\//.test(s)) return false
+  if (s.length > 1024) return false
+  // Strip query string before extension check so e.g.
+  // ?cache=123 doesn't trip us up.
+  const noQuery = s.split('?')[0].split('#')[0]
+  return /\.(mp4|gif|webm)$/i.test(noQuery)
+}
+
+export function resolveGifSendArgs(raw: GifSendArgs): ValidatedGifSendArgs {
+  if (typeof raw.chat_id !== 'string' || raw.chat_id.length === 0) {
+    throw new Error('send_gif: chat_id is required')
+  }
+  if (typeof raw.gif !== 'string' || raw.gif.length === 0) {
+    throw new Error('send_gif: gif (file_id or url) is required')
+  }
+
+  let animationRef: string
+  let refKind: 'file_id' | 'url'
+
+  if (raw.gif.startsWith('http')) {
+    if (!isAcceptableGifUrl(raw.gif)) {
+      throw new Error(
+        'send_gif: url must be https with .mp4 / .gif / .webm extension',
+      )
+    }
+    animationRef = raw.gif
+    refKind = 'url'
+  } else if (looksLikeFileId(raw.gif)) {
+    animationRef = raw.gif
+    refKind = 'file_id'
+  } else {
+    throw new Error(
+      `send_gif: '${raw.gif.slice(0, 40)}...' is neither a valid Telegram ` +
+      `file_id nor an acceptable https URL`,
+    )
+  }
+
+  if (raw.caption != null && typeof raw.caption !== 'string') {
+    throw new Error('send_gif: caption must be a string')
+  }
+  if (raw.caption != null && raw.caption.length > 1024) {
+    throw new Error('send_gif: caption too long (max 1024 chars)')
+  }
+
+  let threadId: number | undefined
+  if (raw.message_thread_id != null) {
+    threadId = Number(raw.message_thread_id)
+    if (!Number.isFinite(threadId) || threadId <= 0) {
+      throw new Error('send_gif: message_thread_id must be a positive integer string')
+    }
+  }
+  let replyTo: number | undefined
+  if (raw.reply_to != null) {
+    replyTo = Number(raw.reply_to)
+    if (!Number.isFinite(replyTo) || replyTo <= 0) {
+      throw new Error('send_gif: reply_to must be a positive integer string')
+    }
+  }
+
+  return {
+    chatId: raw.chat_id,
+    animationRef,
+    refKind,
+    caption: raw.caption,
+    threadId,
+    replyTo,
+  }
+}

package/telegram-plugin/stream-controller.ts

@@ -0,0 +1,311 @@
+/**
+ * Thin integration layer between `createDraftStream` and grammy's `bot.api`.
+ *
+ * Deduplicates the send/edit closure wiring that previously lived inline in
+ * two places in server.ts:
+ *   - the `stream_reply` MCP case block (model-driven streaming)
+ *   - `handlePtyPartial` (PTY-tail TUI extractor → live preview)
+ *
+ * Both paths do the same thing: given a chat/thread/parseMode, create a
+ * draft stream whose `send` closure calls `bot.api.sendMessage` and whose
+ * `edit` closure calls `bot.api.editMessageText`, both wrapped in the
+ * shared retry/429/not-modified policy (`robustApiCall`).
+ *
+ * This module exists primarily so that wiring can be exercised by
+ * integration tests against a mock bot.api, without having to mock the
+ * entire server.ts top-level initialization.
+ */
+
+import { createDraftStream, type DraftStreamHandle, type StreamDraftFn } from './draft-stream.js'
+import { htmlToPlainText } from './html-sanitize.js'
+
+/**
+ * Telegram returns `400 Bad Request: can't parse entities: …` when the
+ * body contains malformed HTML / MarkdownV2 / nested unbalanced tags.
+ * Detect that specific error class so we can fall back to plain text
+ * without confusing it with other 400s (rate-limit, message-not-found,
+ * thread-not-found, etc.).
+ */
+function isParseEntitiesError(err: unknown): boolean {
+  const msg =
+    typeof err === 'string'
+      ? err
+      : err instanceof Error
+        ? err.message
+        : typeof err === 'object' && err != null && 'description' in err
+          ? typeof (err as { description: unknown }).description === 'string'
+            ? (err as { description: string }).description
+            : ''
+          : ''
+  return /can't parse entities|can't find end of the entity|unsupported start tag|unmatched end tag/i.test(msg)
+}
+
+/**
+ * Minimal bot.api surface the controller needs. Real callers pass grammy's
+ * `bot.api`; tests pass a mock with just these two methods.
+ */
+export interface StreamBotApi {
+  sendMessage(
+    chat_id: string,
+    text: string,
+    opts: StreamSendOpts,
+  ): Promise<{ message_id: number }>
+  editMessageText(
+    chat_id: string,
+    message_id: number,
+    text: string,
+    opts: StreamSendOpts,
+  ): Promise<unknown>
+}
+
+export interface StreamSendOpts {
+  parse_mode?: 'HTML' | 'MarkdownV2'
+  message_thread_id?: number
+  link_preview_options?: { is_disabled: boolean }
+  /**
+   * Telegram's reply_parameters, used for quote-replying to an earlier
+   * message. Only meaningful on the initial `sendMessage` — `editMessageText`
+   * cannot add a quote reference to an existing message, so the controller
+   * strips this from edit opts internally.
+   */
+  reply_parameters?: { message_id: number; quote?: { text: string; position: number } }
+  /**
+   * Inline keyboard markup. Included in both sendMessage and editMessageText
+   * so that inline buttons persist through text edits. Without this,
+   * editMessageText strips any previously attached keyboard.
+   */
+  reply_markup?: unknown
+  /**
+   * When true, Telegram prevents the message from being forwarded or saved.
+   * Only meaningful on the initial `sendMessage` — `editMessageText` does not
+   * accept this parameter, so the controller omits it from edit opts.
+   */
+  protect_content?: boolean
+}
+
+export type RetryPolicy = <T>(
+  fn: () => Promise<T>,
+  opts?: { threadId?: number; chat_id?: string },
+) => Promise<T>
+
+export interface StreamControllerConfig {
+  bot: { api: StreamBotApi }
+  chatId: string
+  threadId?: number
+  parseMode?: 'HTML' | 'MarkdownV2'
+  disableLinkPreview?: boolean
+  /**
+   * Optional quote-reply target. When set, the initial send attaches
+   * `reply_parameters: { message_id: replyToMessageId }` so the first
+   * streamed message quote-threads under the referenced message. Edits
+   * don't include it (Telegram rejects reply_parameters on edit).
+   */
+  replyToMessageId?: number
+  /**
+   * Optional quote text for surgical quoting. When set along with
+   * `replyToMessageId`, the initial send includes
+   * `reply_parameters: { message_id, quote: { text, position: 0 } }`.
+   */
+  quoteText?: string
+  /**
+   * When true, Telegram prevents the message from being forwarded or saved.
+   * Applied on the initial `sendMessage` only — editMessageText does not
+   * accept protect_content.
+   */
+  protectContent?: boolean
+  /**
+   * Inline keyboard markup attached to every send and edit. Without this,
+   * editMessageText strips any previously attached keyboard. The progress-
+   * card driver passes the Steer button here so it persists through edits.
+   */
+  replyMarkup?: unknown
+  throttleMs?: number
+  /** Pre-send idle debounce. See DraftStreamConfig.idleMs. */
+  idleMs?: number
+  /**
+   * Retry wrapper around bot.api calls. Defaults to calling `fn` directly
+   * (no retry) so tests that don't care about policy can omit it. In
+   * production, pass server.ts's `robustApiCall`.
+   */
+  retry?: RetryPolicy
+  /** Observers — fire after each successful send/edit. Optional. */
+  onSend?: (messageId: number, chars: number) => void
+  onEdit?: (messageId: number, chars: number) => void
+  /**
+   * Optional diagnostic logger. Receives the draft-stream's internal
+   * status lines (edit-failed, not-modified, re-sending, finalize).
+   * When omitted, those lines are dropped — which is what the plugin
+   * did for its entire history, silently hiding transient edit errors.
+   * Pass a stderr writer in production to surface them.
+   */
+  log?: (msg: string) => void
+  /**
+   * Optional warning logger. Used for transport fallback notices.
+   */
+  warn?: (msg: string) => void
+  /**
+   * Transport selector passed to createDraftStream.
+   * - "auto" (default): use draft transport for DMs only
+   * - "draft": always prefer draft (if sendMessageDraft is available)
+   * - "message": always use sendMessage/editMessageText
+   *
+   * The gateway forces "message" for forum topics (threads), since
+   * sendMessageDraft does not support threaded chats.
+   */
+  previewTransport?: 'auto' | 'message' | 'draft'
+  /**
+   * True when the chat is a private DM. Passed to createDraftStream so
+   * "auto" transport knows whether to activate draft.
+   */
+  isPrivateChat?: boolean
+  /**
+   * sendMessageDraft callback. When provided (and transport allows it),
+   * intermediate stream updates use the draft API. On finalize(), a real
+   * sendMessage is posted for push notification and the draft is cleared.
+   */
+  sendMessageDraft?: StreamDraftFn
+  /**
+   * If set, the controller is initialized as if a previous send had
+   * landed with this `message_id`. The first `update()` invokes
+   * `editMessageText` against this id rather than `sendMessage`.
+   * Threads through to `createDraftStream`'s `initialMessageId`. Used
+   * by callers that know the anchor message id from an external source
+   * (e.g. the gateway's pin manager) to guarantee subsequent emits
+   * edit in place rather than create a fresh sendMessage. Closes the
+   * "done=true → activeDraftStreams entry deleted → next emit creates
+   * fresh sendMessage" duplicate-message class (issue #626).
+   */
+  initialMessageId?: number | null
+}
+
+/**
+ * Build a draft stream that writes to Telegram via `bot.api`.
+ *
+ * The returned handle is the standard `DraftStreamHandle` contract:
+ * `update(text)`, `finalize()`, `getMessageId()`, `isFinal()`.
+ */
+export function createStreamController(cfg: StreamControllerConfig): DraftStreamHandle {
+  const {
+    bot,
+    chatId,
+    threadId,
+    parseMode,
+    disableLinkPreview = true,
+    throttleMs,
+    idleMs,
+    retry = <T>(fn: () => Promise<T>) => fn(),
+    onSend,
+    onEdit,
+    log,
+    warn,
+    replyToMessageId,
+    quoteText,
+    protectContent,
+    replyMarkup,
+    previewTransport,
+    isPrivateChat,
+    sendMessageDraft,
+    initialMessageId,
+  } = cfg
+
+  // Base opts shared by send + edit. The initial send adds reply_parameters
+  // and protect_content on top (see below); edits must NOT carry those —
+  // Telegram's editMessageText rejects them.
+  const baseOpts: StreamSendOpts = {
+    ...(parseMode ? { parse_mode: parseMode } : {}),
+    ...(threadId != null ? { message_thread_id: threadId } : {}),
+    ...(disableLinkPreview ? { link_preview_options: { is_disabled: true } } : {}),
+    ...(replyMarkup != null ? { reply_markup: replyMarkup } : {}),
+  }
+  const sendOpts: StreamSendOpts = {
+    ...baseOpts,
+    ...(replyToMessageId != null
+      ? {
+          reply_parameters: {
+            message_id: replyToMessageId,
+            ...(quoteText != null ? { quote: { text: quoteText, position: 0 } } : {}),
+          },
+        }
+      : {}),
+    ...(protectContent === true ? { protect_content: true } : {}),
+  }
+
+  // Strip parse_mode from a copy of opts — used for the parse-entities
+  // fallback path. We keep thread/preview/reply markup untouched.
+  const sendOptsPlain: StreamSendOpts = { ...sendOpts }
+  delete sendOptsPlain.parse_mode
+  const baseOptsPlain: StreamSendOpts = { ...baseOpts }
+  delete baseOptsPlain.parse_mode
+
+  return createDraftStream(
+    async (text) => {
+      try {
+        const sent = await retry(
+          () => bot.api.sendMessage(chatId, text, sendOpts),
+          { threadId, chat_id: chatId },
+        )
+        onSend?.(sent.message_id, text.length)
+        return sent.message_id
+      } catch (err) {
+        if (parseMode != null && isParseEntitiesError(err)) {
+          // First send rejected for parse_mode error. There is no
+          // message_id to edit (the send 400'd before any message was
+          // created), so a single fresh send in plain-text is the
+          // correct recovery — see issue #657. Strip tags from the
+          // body so the user sees readable prose, not raw markup.
+          warn?.(
+            `stream-controller: sendMessage parse-entities rejected — retrying once as plain text (${err instanceof Error ? err.message : String(err)})`,
+          )
+          const plainText = htmlToPlainText(text)
+          const sent = await retry(
+            () => bot.api.sendMessage(chatId, plainText, sendOptsPlain),
+            { threadId, chat_id: chatId },
+          )
+          onSend?.(sent.message_id, plainText.length)
+          return sent.message_id
+        }
+        throw err
+      }
+    },
+    async (id, text) => {
+      try {
+        await retry(
+          () => bot.api.editMessageText(chatId, id, text, baseOpts),
+          { threadId, chat_id: chatId },
+        )
+        onEdit?.(id, text.length)
+      } catch (err) {
+        if (parseMode != null && isParseEntitiesError(err)) {
+          // Edit rejected for parse_mode error — DO NOT send a fresh
+          // message. The whole point of issue #657 is that the previous
+          // implementation sent a duplicate plain-text message every
+          // time HTML rejection fired. Retry the edit on the SAME
+          // message_id with parse_mode stripped and the body
+          // tag-stripped to plain text.
+          warn?.(
+            `stream-controller: editMessageText parse-entities rejected — retrying same id=${id} as plain text (${err instanceof Error ? err.message : String(err)})`,
+          )
+          const plainText = htmlToPlainText(text)
+          await retry(
+            () => bot.api.editMessageText(chatId, id, plainText, baseOptsPlain),
+            { threadId, chat_id: chatId },
+          )
+          onEdit?.(id, plainText.length)
+          return
+        }
+        throw err
+      }
+    },
+    {
+      ...(throttleMs != null ? { throttleMs } : {}),
+      ...(idleMs != null ? { idleMs } : {}),
+      ...(log != null ? { log } : {}),
+      ...(warn != null ? { warn } : {}),
+      ...(previewTransport != null ? { previewTransport } : {}),
+      ...(isPrivateChat != null ? { isPrivateChat } : {}),
+      ...(sendMessageDraft != null ? { sendMessageDraft } : {}),
+      ...(initialMessageId != null ? { initialMessageId } : {}),
+      chatId,
+    },
+  )
+}