switchroom 0.5.0

package/telegram-plugin/html-sanitize.ts

@@ -0,0 +1,244 @@
+/**
+ * Telegram-HTML sanitizer.
+ *
+ * Telegram's HTML parser is strict: it accepts only a small whitelist of
+ * tags (b/strong, i/em, u/ins, s/strike/del, code, pre, a, tg-spoiler,
+ * span class="tg-spoiler", tg-emoji, blockquote) and rejects the entire
+ * message with `400 Bad Request: can't parse entities` when it encounters
+ * an unknown tag, an unbalanced tag, or a stray `<` that doesn't open a
+ * known tag.
+ *
+ * `markdownToHtml()` already produces well-formed HTML for content the
+ * model wrote *as markdown*. This module is the second line of defence
+ * for content the model wrote *as raw HTML* (or as a mix that produces
+ * malformed HTML after rendering): we run the rendered string through a
+ * pure-text scanner that:
+ *
+ *   1. Escapes any `<` / `>` that doesn't open or close a whitelisted
+ *      tag (e.g. `<frobnicate>` → `&lt;frobnicate&gt;`,
+ *      `1 < 2 < 3` → `1 &lt; 2 &lt; 3`).
+ *   2. Escapes attributes that aren't on the small per-tag allowlist
+ *      (only `<a href>`, `<code class>`, `<span class="tg-spoiler">`,
+ *      `<tg-emoji emoji-id>`, `<blockquote expandable>` are accepted —
+ *      everything else gets stripped from the tag).
+ *   3. Auto-closes any tag opened but never closed (so an "unclosed
+ *      `<b>` at end of message" doesn't trip Telegram's parser).
+ *   4. Drops any unmatched closing tag (e.g. `</foo>` without an opener).
+ *
+ * The sanitizer is conservative: when in doubt, escape. The output is
+ * guaranteed to round-trip through Telegram's HTML parser without a
+ * `can't parse entities` 400 — at the cost of some false positives where
+ * raw `<` characters inside model prose end up as `&lt;` (which is the
+ * correct Telegram-HTML behaviour anyway).
+ *
+ * Idempotent: sanitize(sanitize(x)) === sanitize(x).
+ */
+
+/** Telegram's parse_mode=HTML allowed tag names. */
+const ALLOWED_TAGS = new Set([
+  'b', 'strong',
+  'i', 'em',
+  'u', 'ins',
+  's', 'strike', 'del',
+  'a',
+  'code',
+  'pre',
+  'span',
+  'tg-spoiler',
+  'tg-emoji',
+  'blockquote',
+])
+
+/**
+ * Per-tag attribute allowlist. Keys are tag names; values are the set of
+ * attribute names that survive the sanitizer. Anything not listed is
+ * silently dropped from the opening tag.
+ */
+const ALLOWED_ATTRS: Record<string, Set<string>> = {
+  a: new Set(['href']),
+  code: new Set(['class']),
+  span: new Set(['class']),
+  'tg-emoji': new Set(['emoji-id']),
+  blockquote: new Set(['expandable']),
+  pre: new Set(['language']),
+}
+
+/** Allowed schemes for `<a href>` — block javascript:, data:, etc. */
+const ALLOWED_HREF_SCHEMES = /^(?:https?|mailto|tel|tg):/i
+
+/**
+ * Strip every `<…>` from a string, escaping the `<` and `>`. Used as the
+ * fallback when the input genuinely cannot be made HTML-safe.
+ */
+export function escapeAllHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/**
+ * Sanitize a string of Telegram HTML so it cannot trip the
+ * `can't parse entities` 400. See module docstring for the rules.
+ *
+ * @param input - the rendered HTML (post markdownToHtml).
+ * @returns the sanitized HTML, guaranteed parse-mode=HTML safe.
+ */
+export function sanitizeTelegramHtml(input: string): string {
+  // Walk the input character by character. When we see `<`, try to match
+  // a tag against our whitelist. If it matches, emit a normalized form;
+  // otherwise escape the `<` and continue.
+  //
+  // Tag regex: opening tag name, optional attributes (anything up to
+  // the next `>` that isn't inside a quoted string), and the closing
+  // `>`. We use a small hand-rolled parser rather than a generic regex
+  // because we need to validate attributes per-tag.
+  const out: string[] = []
+  const stack: string[] = [] // names of open tags, oldest-first
+  let i = 0
+  const len = input.length
+
+  while (i < len) {
+    const ch = input[i]
+
+    if (ch === '&') {
+      // Pass through known entities verbatim; escape bare `&`.
+      // A "known entity" is `&` followed by [a-z]+; or `&#` followed by digits;
+      // both terminated by `;` within ~10 chars.
+      const m = /^&(?:#\d+|#x[0-9a-f]+|[a-z]+);/i.exec(input.slice(i, i + 12))
+      if (m) {
+        out.push(m[0])
+        i += m[0].length
+      } else {
+        out.push('&amp;')
+        i++
+      }
+      continue
+    }
+
+    if (ch !== '<') {
+      out.push(ch)
+      i++
+      continue
+    }
+
+    // We're at a `<`. Try to parse a tag.
+    const tagMatch = /^<\s*(\/?)\s*([a-zA-Z][a-zA-Z0-9-]*)\b([^>]*)>/.exec(input.slice(i))
+    if (!tagMatch) {
+      // Stray `<` — escape it.
+      out.push('&lt;')
+      i++
+      continue
+    }
+    const isClose = tagMatch[1] === '/'
+    const tagName = tagMatch[2].toLowerCase()
+    const attrText = tagMatch[3]
+
+    if (!ALLOWED_TAGS.has(tagName)) {
+      // Unknown tag — escape the whole `<…>` literal.
+      out.push(escapeAllHtml(tagMatch[0]))
+      i += tagMatch[0].length
+      continue
+    }
+
+    if (isClose) {
+      // Closing tag: only emit if it matches the most recently opened
+      // tag of the same name. If the stack contains a matching opener
+      // earlier, close out everything above it (auto-close any
+      // unbalanced inner tags). If there's no matching opener at all,
+      // drop the closing tag silently.
+      const idx = stack.lastIndexOf(tagName)
+      if (idx === -1) {
+        // No matching opener — drop the close tag.
+        i += tagMatch[0].length
+        continue
+      }
+      // Auto-close anything above the matching opener.
+      while (stack.length > idx + 1) {
+        const top = stack.pop()!
+        out.push(`</${top}>`)
+      }
+      stack.pop()
+      out.push(`</${tagName}>`)
+      i += tagMatch[0].length
+      continue
+    }
+
+    // Opening tag: filter attributes.
+    const cleanAttrs = sanitizeAttrs(tagName, attrText)
+    out.push(`<${tagName}${cleanAttrs}>`)
+    // Self-closing void tags? Telegram has none — every allowed tag is
+    // a container. Push onto stack so we can auto-close later.
+    stack.push(tagName)
+    i += tagMatch[0].length
+  }
+
+  // Auto-close any unclosed tags so the output is balanced.
+  while (stack.length > 0) {
+    const top = stack.pop()!
+    out.push(`</${top}>`)
+  }
+
+  return out.join('')
+}
+
+/**
+ * Filter the attribute string of an opening tag against the per-tag
+ * allowlist. Returns the cleaned attribute string with a leading space
+ * (or empty string when no attributes survive).
+ */
+function sanitizeAttrs(tagName: string, attrText: string): string {
+  const allowed = ALLOWED_ATTRS[tagName]
+  if (!allowed || allowed.size === 0) return ''
+
+  // Match attribute name=value or bare name. Value may be double-quoted,
+  // single-quoted, or unquoted.
+  const attrRe = /([a-zA-Z_][a-zA-Z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g
+  const kept: string[] = []
+  let m: RegExpExecArray | null
+  while ((m = attrRe.exec(attrText)) != null) {
+    const name = m[1].toLowerCase()
+    if (!allowed.has(name)) continue
+    const rawValue = m[2] ?? m[3] ?? m[4] ?? ''
+
+    // Per-attribute value sanitization.
+    if (tagName === 'a' && name === 'href') {
+      const trimmed = rawValue.trim()
+      if (!ALLOWED_HREF_SCHEMES.test(trimmed)) continue
+      kept.push(`href="${escapeAttrValue(trimmed)}"`)
+      continue
+    }
+    if (rawValue.length === 0) {
+      // Bare attribute like `<blockquote expandable>`.
+      kept.push(name)
+      continue
+    }
+    kept.push(`${name}="${escapeAttrValue(rawValue)}"`)
+  }
+  return kept.length > 0 ? ' ' + kept.join(' ') : ''
+}
+
+function escapeAttrValue(v: string): string {
+  return v
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/**
+ * Convert a rendered HTML body to a plain-text fallback. Used when
+ * Telegram still rejects the (presumably-already-sanitized) HTML — we
+ * strip every tag and unescape entities so the message lands as text
+ * instead of disappearing.
+ */
+export function htmlToPlainText(html: string): string {
+  return html
+    // Drop tags entirely.
+    .replace(/<\/?[a-zA-Z][a-zA-Z0-9-]*\b[^>]*>/g, '')
+    // Unescape the four entities the encoder produces.
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, '&')
+}

package/telegram-plugin/idle-footer.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure renderer for the idle/active footer shown on each agent's Telegram topic.
+ *
+ * No DB, no IO, no time-source coupling. Both `rows` and `now` are
+ * caller-supplied so the function is trivially testable.
+ *
+ * ## "Most recent" definition
+ * We pick the row with the greatest `startedAt` value. Using `startedAt` (rather
+ * than `endedAt ?? startedAt`) keeps the semantics simple: the most recently
+ * *started* turn is the one that best reflects the agent's current engagement.
+ * A turn that finished long ago but whose `endedAt` happens to be later than a
+ * newer turn's `startedAt` would give a misleading "working since" signal; that
+ * edge case can't occur in practice (turns are sequential per chat), but the
+ * comment documents the deliberate choice.
+ */
+
+export interface TurnRow {
+  turnKey: string;
+  chatId: string;
+  startedAt: number;     // ms epoch
+  endedAt: number | null; // ms epoch, or null if the turn is still running
+}
+
+/**
+ * Format a past timestamp as a human-readable "ago" string.
+ *
+ *   <60 s  → "<1m ago"
+ *   60 s..59 min → "Nm ago"
+ *   60 min..23 h → "Nh ago"
+ *   >=24 h → "Nd ago"
+ */
+function formatAgo(ts: number, now: number): string {
+  const diffMs = now - ts;
+  const diffSec = diffMs / 1000;
+  if (diffSec < 60) return "<1m ago";
+  const diffMin = Math.floor(diffMs / 60_000);
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHr = Math.floor(diffMs / 3_600_000);
+  if (diffHr < 24) return `${diffHr}h ago`;
+  const diffDay = Math.floor(diffMs / 86_400_000);
+  return `${diffDay}d ago`;
+}
+
+/**
+ * Format an array of turn rows into a footer string for the agent's topic.
+ *
+ * States:
+ * - No rows            → "🟡 quiet · no turns yet"
+ * - Latest turn running → "⚙️ working since <Nm ago>"  (uses startedAt)
+ * - Latest turn ended  → "🟢 idle · last reply <Nm ago>" (uses endedAt)
+ */
+export function formatIdleFooter(rows: ReadonlyArray<TurnRow>, now: number): string {
+  if (rows.length === 0) {
+    return "🟡 quiet · no turns yet";
+  }
+
+  // Pick most recent by MAX(startedAt).
+  const latest = rows.reduce((best, row) => (row.startedAt > best.startedAt ? row : best));
+
+  if (latest.endedAt == null) {
+    return `⚙️ working since ${formatAgo(latest.startedAt, now)}`;
+  }
+
+  return `🟢 idle · last reply ${formatAgo(latest.endedAt, now)}`;
+}

package/telegram-plugin/inline-keyboard-callbacks.ts

@@ -0,0 +1,166 @@
+/**
+ * Agent-emitted inline-keyboard callback routing (#271).
+ *
+ * Agents emit `inline_keyboard` buttons via the `reply` / `stream_reply`
+ * MCP tools. URL buttons need no routing — Telegram opens them in the
+ * user's browser. callback_data buttons are different: the user's tap
+ * arrives as a `callback_query` update on the gateway's bot, and we
+ * need to deliver it back to the agent as an inbound channel event.
+ *
+ * Wire format
+ * ───────────
+ * The gateway namespaces agent-emitted callback_data with an `agent:`
+ * prefix BEFORE sending to Telegram. Two reasons:
+ *
+ *   1. The existing callback_query dispatcher in gateway.ts routes by
+ *      data prefix (`auth:`, `op:`, `vd:`, `vg:`, `aq:`, `perm:`).
+ *      Any unprefixed data falls through to "ack-and-ignore". Agents
+ *      could otherwise collide with infrastructure prefixes — `auth:`
+ *      from an agent would silently invoke the auth dashboard handler.
+ *
+ *   2. Round-tripping. On callback_query receipt the gateway sees the
+ *      `agent:` prefix, strips it, and forwards the raw data the agent
+ *      originally supplied. Agent code only ever sees its own opaque
+ *      payload — no leaky abstraction.
+ *
+ * Effective payload budget: 64 bytes (Telegram limit) − 6 bytes
+ * (`agent:` prefix) = 58 bytes for agent-supplied data. This is
+ * documented in the MCP tool schema.
+ */
+
+import {
+  validateInlineKeyboard,
+  type AnyButton,
+  type ButtonValidationError,
+} from './telegram-button-constraints.js'
+
+/** Prefix used to namespace agent-emitted callback_data on the wire. */
+export const AGENT_CALLBACK_PREFIX = 'agent:'
+
+/**
+ * Maximum bytes available to the agent for callback_data payloads.
+ * Telegram's hard limit is 64 bytes; the gateway reserves 6 bytes for
+ * the `agent:` prefix.
+ */
+export const AGENT_CALLBACK_DATA_MAX = 64 - AGENT_CALLBACK_PREFIX.length
+
+/**
+ * Per-button agent-supplied metadata that controls post-tap UX (#710).
+ * These fields are stripped before the keyboard is sent to Telegram —
+ * they are NOT part of the Bot API. The gateway extracts and stores
+ * them via {@link extractAgentButtonMeta} so the callback handler can
+ * honor them when the user taps.
+ */
+export interface AgentButtonMeta {
+  /** Toast text shown via answerCallbackQuery on tap. Default `'✓ received'`. */
+  ack_text?: string
+  /**
+   * When false, the button keyboard is preserved after tap (re-tappable).
+   * When true (default), tapping ANY single_use button on the message
+   * removes the entire keyboard to prevent double-fire.
+   */
+  single_use?: boolean
+}
+
+/** Fields the gateway adds to button objects — not valid Telegram API fields. */
+const AGENT_META_FIELDS: ReadonlyArray<keyof AgentButtonMeta> = ['ack_text', 'single_use']
+
+/**
+ * Wrap every callback_data field in a 2D inline-keyboard with the
+ * gateway's `agent:` namespace prefix. URL-only buttons pass through
+ * unchanged. Returns a fresh array — does not mutate the input.
+ *
+ * Also strips agent-only meta fields (`ack_text`, `single_use`) so they
+ * don't leak into the Telegram API request. Use
+ * {@link extractAgentButtonMeta} on the raw keyboard BEFORE wrapping to
+ * recover those fields for the callback handler.
+ *
+ * Throws when an agent-supplied callback_data exceeds the effective
+ * 58-byte budget (so the operator sees a clear error, not a silent
+ * Telegram 400 BUTTON_DATA_INVALID at send time).
+ */
+export function wrapAgentCallbacks(keyboard: AnyButton[][]): AnyButton[][] {
+  return keyboard.map((row) =>
+    row.map((btn) => {
+      const cleaned: AnyButton = { ...btn }
+      for (const f of AGENT_META_FIELDS) delete cleaned[f]
+      if (typeof btn.callback_data !== 'string') return cleaned
+      const raw = btn.callback_data
+      const rawBytes = new TextEncoder().encode(raw).byteLength
+      if (rawBytes > AGENT_CALLBACK_DATA_MAX) {
+        throw new Error(
+          `inline_keyboard.callback_data exceeds ${AGENT_CALLBACK_DATA_MAX}-byte agent budget ` +
+          `(actual=${rawBytes}, raw="${raw.slice(0, 32)}${raw.length > 32 ? '…' : ''}")`,
+        )
+      }
+      cleaned.callback_data = `${AGENT_CALLBACK_PREFIX}${raw}`
+      return cleaned
+    }),
+  )
+}
+
+/**
+ * Extract per-button {@link AgentButtonMeta} from a raw (pre-wrap)
+ * keyboard. Returns a map keyed by the raw (unprefixed) callback_data
+ * string. Buttons without callback_data or without any meta fields are
+ * omitted. Used by the gateway to remember post-tap UX preferences for
+ * each button on a sent message.
+ */
+export function extractAgentButtonMeta(
+  keyboard: AnyButton[][],
+): Map<string, AgentButtonMeta> {
+  const out = new Map<string, AgentButtonMeta>()
+  for (const row of keyboard) {
+    for (const btn of row) {
+      if (typeof btn.callback_data !== 'string') continue
+      const meta: AgentButtonMeta = {}
+      if (typeof btn.ack_text === 'string') meta.ack_text = btn.ack_text
+      if (typeof btn.single_use === 'boolean') meta.single_use = btn.single_use
+      if (meta.ack_text != null || meta.single_use != null) {
+        out.set(btn.callback_data, meta)
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * Aggregate the message-level "should we strip the keyboard after a tap"
+ * decision (#710). Default policy is single-use=true. The keyboard is
+ * preserved only when at least one button on the message explicitly opts
+ * out via `single_use: false`.
+ */
+export function keyboardIsSingleUse(
+  metaByRawData: Map<string, AgentButtonMeta>,
+): boolean {
+  for (const meta of metaByRawData.values()) {
+    if (meta.single_use === false) return false
+  }
+  return true
+}
+
+/**
+ * Parse a callback_query.data string. Returns the raw agent payload
+ * (sans prefix) when the data is agent-emitted; null otherwise so the
+ * gateway dispatcher can fall through to its other routes.
+ */
+export function parseAgentCallback(data: string): { raw: string } | null {
+  if (!data.startsWith(AGENT_CALLBACK_PREFIX)) return null
+  return { raw: data.slice(AGENT_CALLBACK_PREFIX.length) }
+}
+
+/**
+ * Convenience: validate + wrap in one call. Returns either the
+ * wrapped keyboard or a structured error list — caller throws so the
+ * tool result carries the diagnostic upstream.
+ */
+export function validateAndWrapAgentKeyboard(
+  keyboard: AnyButton[][],
+): { ok: true; wrapped: AnyButton[][] } | { ok: false; errors: ButtonValidationError[] } {
+  const errors = validateInlineKeyboard(keyboard)
+  if (errors.length > 0) return { ok: false, errors }
+  // wrapAgentCallbacks may throw on byte-budget overflow; let it
+  // propagate so the caller surfaces the message verbatim.
+  const wrapped = wrapAgentCallbacks(keyboard)
+  return { ok: true, wrapped }
+}

package/telegram-plugin/interrupt-marker.ts

@@ -0,0 +1,66 @@
+/**
+ * `!`-prefix interrupt marker — closes #575 / part of `reference/steer-or-queue-mid-flight.md`.
+ *
+ * The product contract: when the user starts a Telegram message with
+ * `!`, they're saying "drop what you're doing and handle this
+ * instead." The gateway:
+ *   1. Bypasses the inbound coalescer so the `!` always lands at
+ *      the start of the parsed text (otherwise an earlier non-`!`
+ *      message inside the same coalesce window would prepend itself
+ *      and the marker would no longer be at position 0).
+ *   2. Sends SIGINT to the agent service so any in-flight turn dies.
+ *   3. Forwards the message with the `!` stripped as a fresh turn,
+ *      so the agent sees clean intent without the marker character
+ *      bleeding into its prompt.
+ *
+ * Pure helper — no side effects. Parses the marker; the gateway
+ * decides what to do with the verdict. Tested in
+ * `tests/interrupt-marker.test.ts` without grammY.
+ */
+
+export interface InterruptParseResult {
+  /** True iff the message is a deliberate interrupt request. */
+  isInterrupt: boolean
+  /** The text the agent should see, minus the marker + leading whitespace. */
+  body: string
+  /** True iff the body would be empty (just `!` with nothing useful after).
+   *  Caller may want to send a clarifying reply rather than forward an
+   *  empty turn to the agent. */
+  emptyBody: boolean
+}
+
+/**
+ * Parse an inbound text body for the `!` interrupt marker.
+ *
+ * Rules:
+ *   - Marker is `!` at position 0 of the trimmed body.
+ *   - Doubled `!!` is NOT an interrupt — common typo / emphasis. The
+ *     agent sees the literal `!!...` text. Single `!` is the rule.
+ *   - Markdown-bold `*!*` or any other escape is NOT an interrupt.
+ *     Strict literal match keeps the rule learnable.
+ *   - The marker is consumed; the body returned is everything after,
+ *     leading whitespace trimmed. So `! do this instead` → body `do
+ *     this instead`.
+ *
+ * Why not other prefixes (e.g. `/stop`, `STOP`, `interrupt`):
+ *   - `/`-prefixed strings are reserved for Telegram bot commands.
+ *   - Word prefixes collide with normal speech ("Stop, that's wrong").
+ *   - `!` is a single keystroke, hard to type by accident, easy to
+ *     teach. Same convention as e.g. linuz90/claude-telegram-bot.
+ */
+export function parseInterruptMarker(text: string): InterruptParseResult {
+  const trimmed = text.trimStart()
+  if (!trimmed.startsWith('!')) {
+    return { isInterrupt: false, body: text, emptyBody: false }
+  }
+  // Doubled `!!` is intentional emphasis or typo — not a marker.
+  if (trimmed.startsWith('!!')) {
+    return { isInterrupt: false, body: text, emptyBody: false }
+  }
+  const body = trimmed.slice(1).trimStart()
+  return {
+    isInterrupt: true,
+    body,
+    emptyBody: body.length === 0,
+  }
+}