switchroom 0.5.0

package/telegram-plugin/status-reactions.ts

@@ -0,0 +1,332 @@
+/**
+ * Status reaction state machine for Telegram bot messages.
+ *
+ * Ports the pattern from openclaw's src/channels/status-reactions.ts +
+ * extensions/telegram/src/status-reaction-variants.ts. The goal is to give
+ * the user a glanceable, non-spammy progress signal on their inbound
+ * message: 👀 received → 🤔 thinking → ✍/👨‍💻/⚡ working → 👍 done → 😱 error.
+ *
+ * Three load-bearing properties (all from openclaw research):
+ *
+ *  1. Debounce intermediate transitions by 700ms so a model that flashes
+ *     thinking → tool → thinking → tool doesn't burn the rate limit.
+ *
+ *  2. Terminal states (queued / done / error) bypass the debounce.
+ *
+ *  3. Serialize all API calls through a single chain promise so two
+ *     concurrent transitions never race the Telegram API. Telegram's
+ *     setMessageReaction replaces atomically — no removeReaction needed.
+ *
+ * Stall watchdogs auto-promote to 🥱 / 😨 if no transition arrives within
+ * 30s / 90s, so a stuck/dead inference loop is visually distinguishable
+ * from a long but healthy one.
+ *
+ * Emoji choices use Telegram's bot reaction whitelist
+ * (https://core.telegram.org/bots/api#reactiontype). The fallback chain
+ * tries each variant in order — if a chat restricts available reactions
+ * (admin-configured in some groups) the controller silently no-ops the
+ * unsupported choice instead of throwing.
+ */
+
+/** Telegram allows only this fixed set of emoji as bot reactions. */
+export const TELEGRAM_REACTION_WHITELIST = new Set([
+  '👍', '👎', '❤', '🔥', '🥰', '👏', '😁', '🤔', '🤯', '😱',
+  '🤬', '😢', '🎉', '🤩', '🤮', '💩', '🙏', '👌', '🕊', '🤡',
+  '🥱', '🥴', '😍', '🐳', '❤‍🔥', '🌚', '🌭', '💯', '🤣', '⚡',
+  '🍌', '🏆', '💔', '🤨', '😐', '🍓', '🍾', '💋', '🖕', '😈',
+  '😴', '😭', '🤓', '👻', '👨‍💻', '👀', '🎃', '🙈', '😇', '😨',
+  '🤝', '✍', '🤗', '🫡', '🎅', '🎄', '☃', '💅', '🤪', '🗿',
+  '🆒', '💘', '🙉', '🦄', '😘', '💊', '🙊', '😎', '👾',
+  '🤷‍♂', '🤷', '🤷‍♀', '😡',
+])
+
+/** Logical reaction states the controller tracks. */
+export type ReactionState =
+  | 'queued'
+  | 'thinking'
+  | 'coding'
+  | 'web'
+  | 'tool'
+  | 'compacting'
+  | 'done'
+  | 'silent'
+  | 'error'
+  | 'stallSoft'
+  | 'stallHard'
+
+/**
+ * Per-state emoji preference, with fallbacks if the first isn't allowed
+ * in this particular chat. Modeled on openclaw's
+ * TELEGRAM_STATUS_REACTION_VARIANTS.
+ *
+ * Semantic split — do not conflate these three tiers:
+ *   READ     👀  = "I have seen your message" (acknowledgement only)
+ *   WORKING  ✍   = actively doing something (tools, coding, compacting)
+ *   FINISHED 👍/💯/🎉 = definitively done; a reply landed
+ *
+ * 🔥 is reserved for genuine 5xx server errors (operator-events.ts).
+ * It reads as "on fire / broken" — keep it out of normal active-work states.
+ */
+export const REACTION_VARIANTS: Record<ReactionState, string[]> = {
+  queued:    ['👀', '🤔', '🤓'],     // READ: I see your message
+  thinking:  ['🤔', '🤓', '👀'],     // unchanged
+  tool:      ['✍', '⚡', '👌'],      // WORKING: actively using a tool
+  coding:    ['👨‍💻', '✍', '⚡'],     // WORKING: writing / running code
+  web:       ['⚡', '🤔', '👌'],      // WORKING: lookup in motion (👀 reserved for READ)
+  compacting:['✍', '🤔', '👀'],      // unchanged
+  done:      ['👍', '💯', '🎉'],      // FINISHED: reply landed
+  // 🙊 — turn ended without producing a user-visible reply. Distinct from
+  // 'done' (which means "reply landed") so the user doesn't read 👍 as
+  // "agent acknowledged" when actually nothing was sent. See issue #132.
+  silent:    ['🙊', '🤔', '😐'],      // unchanged
+  error:     ['😱', '😨', '🤯'],      // unchanged (genuine alarm)
+  stallSoft: ['🥱', '😴', '🤔'],      // unchanged
+  stallHard: ['😨', '🤯', '😱'],      // unchanged
+}
+
+/**
+ * Map a tool name string from a CallToolRequest into the appropriate
+ * reaction state. Falls back to generic 'tool' for anything we don't
+ * have a more specific bucket for.
+ */
+export function resolveToolReactionState(toolName: string): ReactionState {
+  const n = toolName.toLowerCase()
+  if (n.includes('bash') || n.includes('exec') || n.includes('shell')) return 'coding'
+  if (n.includes('read') || n.includes('write') || n.includes('edit')
+    || n.includes('multiedit') || n.includes('notebook') || n.includes('glob')
+    || n.includes('grep')) return 'coding'
+  if (n.includes('webfetch') || n.includes('websearch') || n.includes('browser')
+    || n.includes('fetch') || n.includes('search')) return 'web'
+  return 'tool'
+}
+
+/** Configuration knobs the controller respects. */
+export interface StatusReactionConfig {
+  /** Milliseconds to wait before applying a non-immediate transition. Default 700. */
+  debounceMs?: number
+  /** Milliseconds without progress before promoting to stallSoft. Default 30000. */
+  stallSoftMs?: number
+  /** Milliseconds without progress before promoting to stallHard. Default 90000. */
+  stallHardMs?: number
+  /** Optional logger for debugging — receives a single string per event. */
+  log?: (msg: string) => void
+}
+
+/**
+ * Function the controller calls to actually emit a reaction. Receives the
+ * resolved emoji (already filtered through the chat's allowed set) and
+ * should return a promise that resolves once the API call completes.
+ *
+ * The function should NOT throw on Telegram errors — silently swallow
+ * unsupported-reaction failures so the controller can move on.
+ */
+export type ReactionEmitter = (emoji: string) => Promise<void>
+
+/**
+ * Controller managing the reaction lifecycle for a single inbound message.
+ *
+ * Lifecycle: construct → setQueued() → arbitrary intermediate transitions
+ * → setDone() / setError() to terminate. After termination, all further
+ * setX calls are no-ops.
+ */
+export class StatusReactionController {
+  private currentEmoji: string | null = null
+  private pendingEmoji: string | null = null
+  private chainPromise: Promise<unknown> = Promise.resolve()
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null
+  private stallSoftTimer: ReturnType<typeof setTimeout> | null = null
+  private stallHardTimer: ReturnType<typeof setTimeout> | null = null
+  private finished = false
+  private readonly debounceMs: number
+  private readonly stallSoftMs: number
+  private readonly stallHardMs: number
+  private readonly log?: (msg: string) => void
+
+  constructor(
+    private readonly emit: ReactionEmitter,
+    /** Chat reactions allowed in this specific chat (null = all whitelisted). */
+    private readonly allowedReactions: Set<string> | null = null,
+    config: StatusReactionConfig = {},
+  ) {
+    this.debounceMs = config.debounceMs ?? 700
+    this.stallSoftMs = config.stallSoftMs ?? 30000
+    this.stallHardMs = config.stallHardMs ?? 90000
+    this.log = config.log
+  }
+
+  /** 👀 — message received and queued for processing. Bypasses debounce. */
+  setQueued(): void {
+    this.scheduleState('queued', { immediate: true })
+  }
+
+  /** 🤔 — model is generating. Debounced. */
+  setThinking(): void {
+    this.scheduleState('thinking')
+  }
+
+  /** Tool-specific reaction. Debounced. */
+  setTool(toolName?: string): void {
+    const state = toolName ? resolveToolReactionState(toolName) : 'tool'
+    this.scheduleState(state)
+  }
+
+  /** ✍ — context compaction in progress. */
+  setCompacting(): void {
+    this.scheduleState('compacting')
+  }
+
+  /** 👍 — final reply delivered. Terminal, bypasses debounce. */
+  setDone(): void {
+    this.finishWithState('done')
+  }
+
+  /**
+   * 🙊 — turn ended without producing a user-visible reply.
+   *
+   * Distinct from `setDone()` so the user doesn't read 👍 as "agent
+   * acknowledged but stayed silent on purpose" when in fact nothing was
+   * actually sent. Common case (#132): agent ran a long Bash chain to
+   * answer a question, never called `reply` / `stream_reply`, and the
+   * orphaned-reply backstop had no captured text to forward either.
+   * Terminal, bypasses debounce.
+   */
+  setSilent(): void {
+    this.finishWithState('silent')
+  }
+
+  /** 😱 — generation failed. Terminal, bypasses debounce. */
+  setError(): void {
+    this.finishWithState('error')
+  }
+
+  /** Stop the controller without applying any new reaction. Terminal. */
+  cancel(): void {
+    if (this.finished) return
+    this.finished = true
+    this.clearDebounceTimer()
+    this.clearStallTimers()
+  }
+
+  // ──────────────────────────────────────────────────────────────────────
+
+  private scheduleState(
+    state: ReactionState,
+    opts: { immediate?: boolean; skipStallReset?: boolean } = {},
+  ): void {
+    if (this.finished) return
+    const emoji = this.resolveEmoji(state)
+    if (emoji == null) {
+      // No allowed variant for this chat — silently skip rather than fall
+      // through to the chain. We still reset stall timers so that progress
+      // signals continue to keep the watchdogs at bay.
+      if (!opts.skipStallReset) this.resetStallTimers()
+      return
+    }
+    if (emoji === this.currentEmoji || emoji === this.pendingEmoji) {
+      if (!opts.skipStallReset) this.resetStallTimers()
+      return
+    }
+    this.pendingEmoji = emoji
+    this.clearDebounceTimer()
+    if (opts.immediate) {
+      this.enqueue(emoji)
+    } else {
+      this.debounceTimer = setTimeout(() => {
+        this.debounceTimer = null
+        this.enqueue(emoji)
+      }, this.debounceMs)
+    }
+    if (!opts.skipStallReset) this.resetStallTimers()
+  }
+
+  private finishWithState(state: ReactionState): void {
+    if (this.finished) return
+    this.finished = true
+    this.clearStallTimers()
+    // F1 fix (#553): if a non-terminal reaction is sitting in the
+    // debounce window when the turn ends, flush it BEFORE the terminal
+    // emoji emits. Pre-fix, `clearDebounceTimer()` here silently
+    // dropped the pending state — every Class B turn that completed in
+    // under `debounceMs` (default 700ms) collapsed to 👀 → 👍 with no
+    // intermediate signal that the agent did any work.
+    //
+    // Gate on `debounceTimer != null`: a `pendingEmoji` with no timer
+    // is already enqueued (immediate emit waiting on chainPromise) and
+    // re-enqueuing would produce a duplicate. Only debounced-but-not-
+    // yet-enqueued emojis need to be flushed here.
+    const flushPending = this.debounceTimer != null && this.pendingEmoji != null
+      ? this.pendingEmoji
+      : null
+    this.clearDebounceTimer()
+    if (flushPending != null && flushPending !== this.currentEmoji) {
+      this.enqueue(flushPending)
+    }
+    const emoji = this.resolveEmoji(state)
+    if (emoji != null && emoji !== this.currentEmoji && emoji !== flushPending) {
+      this.enqueue(emoji)
+    }
+  }
+
+  private enqueue(emoji: string): void {
+    this.chainPromise = this.chainPromise.then(async () => {
+      try {
+        await this.emit(emoji)
+        this.currentEmoji = emoji
+        if (this.pendingEmoji === emoji) this.pendingEmoji = null
+        this.log?.(`reaction → ${emoji}`)
+      } catch (err) {
+        this.log?.(`reaction emit failed (${emoji}): ${(err as Error).message}`)
+      }
+    })
+  }
+
+  private resolveEmoji(state: ReactionState): string | null {
+    const variants = REACTION_VARIANTS[state]
+    for (const v of variants) {
+      if (!TELEGRAM_REACTION_WHITELIST.has(v)) continue
+      if (this.allowedReactions == null || this.allowedReactions.has(v)) {
+        return v
+      }
+    }
+    // Last resort: any whitelisted-and-allowed emoji from the broad fallback set
+    for (const v of ['👍', '👀', '✍']) {
+      if (this.allowedReactions == null || this.allowedReactions.has(v)) {
+        return v
+      }
+    }
+    return null
+  }
+
+  private resetStallTimers(): void {
+    this.clearStallTimers()
+    if (this.finished) return
+    this.stallSoftTimer = setTimeout(() => {
+      this.stallSoftTimer = null
+      // Don't reset the stall timers when the stall transition itself fires —
+      // otherwise stallHard would never get a chance to run after stallSoft.
+      this.scheduleState('stallSoft', { immediate: true, skipStallReset: true })
+    }, this.stallSoftMs)
+    this.stallHardTimer = setTimeout(() => {
+      this.stallHardTimer = null
+      this.scheduleState('stallHard', { immediate: true, skipStallReset: true })
+    }, this.stallHardMs)
+  }
+
+  private clearStallTimers(): void {
+    if (this.stallSoftTimer) {
+      clearTimeout(this.stallSoftTimer)
+      this.stallSoftTimer = null
+    }
+    if (this.stallHardTimer) {
+      clearTimeout(this.stallHardTimer)
+      this.stallHardTimer = null
+    }
+  }
+
+  private clearDebounceTimer(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer)
+      this.debounceTimer = null
+    }
+  }
+}

package/telegram-plugin/steering.ts

@@ -0,0 +1,155 @@
+/**
+ * Pure helpers for mid-turn steering and the `/queue` opt-in.
+ *
+ * Context: Telegram messages that arrive while a prior turn is still in
+ * flight are now queued by default (queued="true"). The user can explicitly
+ * prefix with `/steer ` or `/s ` to declare "this is a course-correction,
+ * not a new task" (steering="true"). The legacy `/queue ` / `/q ` prefix
+ * still works as an alias for the new default (queued) behavior.
+ * These helpers are pure so server.ts stays testable without standing up
+ * grammy.
+ */
+import { escapeHtml } from './format.js'
+
+/**
+ * Detect and strip the `/queue ` or `/q ` prefix.
+ *
+ * These are now aliases for the default queued behavior (mid-turn messages
+ * default to queued="true"), but the prefix is still accepted so existing
+ * muscle-memory and scripts keep working.
+ *
+ * Rules (intentionally strict so we don't match `/queued` or `/q\nfoo`):
+ *   - Must start with `/queue ` or `/q ` (exactly one leading slash,
+ *     keyword case-insensitive, MANDATORY single space after keyword).
+ *   - No leading whitespace — first character must be `/`.
+ *   - Keyword must be `queue` or `q` exactly; `/queued`, `/queuefoo`,
+ *     `/queue\tfoo` all fail to match.
+ *   - On match, only the first prefix is stripped. `/queue /q foo`
+ *     returns `{queued: true, body: "/q foo"}` — we do not recurse.
+ *   - On match, the returned body is whitespace-trimmed.
+ *   - `/queue` alone (no trailing space) does NOT match (we require the
+ *     space so the prefix can't collide with a message that literally
+ *     starts with the word "queue"). Document in tests.
+ */
+export function parseQueuePrefix(body: string): { queued: boolean; body: string } {
+  const m = /^\/(queue|q) (.*)$/is.exec(body)
+  if (!m) return { queued: false, body }
+  return { queued: true, body: m[2]!.trim() }
+}
+
+/**
+ * Detect and strip the `/steer ` or `/s ` explicit steer prefix.
+ *
+ * Mid-turn messages now default to queued="true". To explicitly mark a
+ * message as a course-correction for the in-flight turn, the user can
+ * prefix with `/steer ` or `/s `.
+ *
+ * Rules mirror parseQueuePrefix exactly:
+ *   - Must start with `/steer ` or `/s ` (keyword case-insensitive,
+ *     MANDATORY single space after keyword).
+ *   - No leading whitespace — first character must be `/`.
+ *   - Keyword must be `steer` or `s` exactly; `/steered`, `/steerfoo`,
+ *     `/steer\tfoo` all fail to match.
+ *   - On match, only the first prefix is stripped; body is trimmed.
+ *   - `/steer` alone (no trailing space) does NOT match.
+ */
+export function parseSteerPrefix(body: string): { steering: boolean; body: string } {
+  const m = /^\/(steer|s) (.*)$/is.exec(body)
+  if (!m) return { steering: false, body }
+  return { steering: true, body: m[2]!.trim() }
+}
+
+/**
+ * Escape the five XML attribute entities. Idempotent on already-safe
+ * strings because the order is &-first (any `&` we produce won't be
+ * re-processed — the first pass only rewrites bare `&`).
+ */
+export function escapeXmlAttribute(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+/**
+ * Produce a short, safe preview of the last assistant turn for injection
+ * as an XML attribute. Strips HTML tags (so `<b>foo</b>` becomes `foo`),
+ * collapses all whitespace runs into single spaces, truncates to
+ * `maxChars` visible characters, then XML-escapes.
+ *
+ * We do NOT decode HTML entities — a literal `&amp;` in the source
+ * survives as `&amp;amp;` after escape, which is fine: the attribute is
+ * for the model's situational awareness, not faithful rendering.
+ */
+export function formatPriorAssistantPreview(text: string, maxChars = 200): string {
+  // Strip HTML tags. Anything angle-bracketed between < and > goes away;
+  // this is deliberately liberal (no tag-name whitelist) because the
+  // preview is for the model's eyes only.
+  const stripped = text.replace(/<[^>]*>/g, '')
+  const collapsed = stripped.replace(/\s+/g, ' ').trim()
+  const truncated = collapsed.length > maxChars ? collapsed.slice(0, maxChars) : collapsed
+  return escapeXmlAttribute(truncated)
+}
+
+/**
+ * Format the `reply_to_text` channel-meta attribute (issue #119) — used by
+ * both `server.ts` and `gateway/gateway.ts` so the two paths can't drift.
+ *
+ * Difference from `formatPriorAssistantPreview`: we do NOT strip HTML or
+ * collapse whitespace. The original Telegram message text is plain text
+ * already, and preserving its shape (line breaks excluded by truncation,
+ * special chars escaped at the boundary) helps the agent see what the
+ * user was looking at when they hit "Reply".
+ *
+ * Returns undefined when `text` is null/undefined so the call site can
+ * conditionally include the attribute via spread without an extra guard.
+ */
+export function formatReplyToText(text: string | null | undefined, maxChars: number): string | undefined {
+  if (text == null) return undefined
+  const truncated = text.length > maxChars
+    ? text.slice(0, maxChars - 1) + '…'
+    : text
+  return escapeXmlAttribute(truncated)
+}
+
+export interface ChannelMetaAttributeOptions {
+  queued?: boolean
+  steering?: boolean
+  priorTurnInProgress?: boolean
+  secondsSinceTurnStart?: number
+  /** Already-escaped preview (as returned by formatPriorAssistantPreview). */
+  priorAssistantPreview?: string
+}
+
+/**
+ * Build the extra attributes for the `<channel>` open tag. Returns a
+ * space-prefixed string (or empty string if no attributes apply) so the
+ * caller can concatenate it directly after the existing attributes.
+ *
+ * Order is fixed (documented here, tested in steering.test.ts):
+ *   queued, steering, prior_turn_in_progress,
+ *   seconds_since_turn_start, prior_assistant_preview
+ *
+ * Attributes with missing / undefined values are omitted entirely rather
+ * than emitted as empty strings. `queued` and `steering` are treated as
+ * mutually exclusive by the caller in server.ts — this helper does not
+ * enforce that invariant; if both are true, both are emitted.
+ */
+export function buildChannelMetaAttributes(opts: ChannelMetaAttributeOptions): string {
+  const parts: string[] = []
+  if (opts.queued) parts.push('queued="true"')
+  if (opts.steering) parts.push('steering="true"')
+  if (opts.priorTurnInProgress) parts.push('prior_turn_in_progress="true"')
+  if (opts.priorTurnInProgress && typeof opts.secondsSinceTurnStart === 'number') {
+    parts.push(`seconds_since_turn_start="${Math.max(0, Math.floor(opts.secondsSinceTurnStart))}"`)
+  }
+  if (opts.priorTurnInProgress && opts.priorAssistantPreview != null && opts.priorAssistantPreview.length > 0) {
+    parts.push(`prior_assistant_preview="${opts.priorAssistantPreview}"`)
+  }
+  return parts.length === 0 ? '' : ' ' + parts.join(' ')
+}
+
+/** Re-export so callers that want HTML-escape for body content don't need a second import. */
+export { escapeHtml }