switchroom 0.15.6 → 0.15.8

package/telegram-plugin/gateway/gateway.ts

@@ -366,6 +366,7 @@ import type {
   PermissionEvent,
 } from './ipc-protocol.js'
 import { DebounceBuffer, HourCap, buildReactionInboundMeta, buildReactionInboundText, evaluateTriggerCandidate, isGroupChat, resolveReactionsConfig, truncatePreview, type PendingReaction, type ReactionBatch, type ReactionsResolvedConfig } from './reaction-trigger.js'
+import { buildReactionDispatchInbound, evaluateReactionDispatch, resolveReactionDispatchConfig, type ReactionDispatchResolvedConfig } from './reaction-dispatch.js'
 import { writePidFile, clearPidFile } from './pid-file.js'
 import { acquireStartupLock, releaseStartupLock } from './startup-mutex.js'
 import { drainShutdown } from './shutdown-drain.js'
@@ -19825,6 +19826,120 @@ function getReactionDebounce(): DebounceBuffer {
   return reactionDebounce
 }
 
+// ─── reaction_dispatch (#2291) ─────────────────────────────────────────────
+// Event-driven dispatch of ANY qualifying message_reaction as an inbound
+// `<channel event="reaction">` turn. Default OFF; independent of the
+// bot-authored `reactions` feedback path above.
+let reactionDispatchCfg: ReactionDispatchResolvedConfig | null = null
+
+function getReactionDispatchConfig(): ReactionDispatchResolvedConfig {
+  if (reactionDispatchCfg) return reactionDispatchCfg
+  let raw: unknown = undefined
+  try {
+    const cfg = loadSwitchroomConfig()
+    const agentName = process.env.SWITCHROOM_AGENT_NAME
+    if (agentName) {
+      const rawAgent = cfg.agents?.[agentName]
+      if (rawAgent) {
+        const resolved = resolveAgentConfig(cfg.defaults, cfg.profiles, rawAgent)
+        raw = (resolved as { reaction_dispatch?: unknown }).reaction_dispatch
+      }
+    }
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: reaction_dispatch: config load failed, defaulting OFF: ${(err as Error).message}\n`,
+    )
+  }
+  reactionDispatchCfg = resolveReactionDispatchConfig(
+    raw as Parameters<typeof resolveReactionDispatchConfig>[0] ?? null,
+  )
+  return reactionDispatchCfg
+}
+
+/**
+ * Event-driven reaction → inbound turn (#2291). Called from the
+ * message_reaction handler for add/change events. Filters by the
+ * `reaction_dispatch` emoji allowlist (default empty ⇒ no-op), looks up
+ * the reacted message's text from the SQLite history buffer (graceful on
+ * miss), and injects an inbound shaped like a button-callback event via
+ * the same ipcServer.sendToAgent path cron uses. Removals never reach
+ * here (the caller filters them).
+ */
+function maybeDispatchReaction(args: {
+  chatId: string
+  messageId: number
+  emoji: string | null
+  action: 'add' | 'change'
+  user: string
+  userId: number
+  threadId?: number
+}): void {
+  const cfg = getReactionDispatchConfig()
+  const decision = evaluateReactionDispatch(cfg, { emoji: args.emoji, action: args.action })
+  if (!decision.ok) {
+    if (decision.reason === 'emoji_not_in_allowlist' && cfg.enabled) {
+      process.stderr.write(
+        `telegram gateway: reaction_dispatch.reject reason=allowlist_miss emoji=${args.emoji} chat=${args.chatId}\n`,
+      )
+    }
+    return
+  }
+
+  const agentName = process.env.SWITCHROOM_AGENT_NAME
+  if (!agentName) {
+    process.stderr.write(
+      `telegram gateway: reaction_dispatch: skipped — SWITCHROOM_AGENT_NAME unset\n`,
+    )
+    return
+  }
+
+  // History lookup is best-effort; a miss yields an empty body. The
+  // envelope still carries emoji / message_id / chat_id / user.
+  let reactedText = ''
+  if (HISTORY_ENABLED) {
+    try {
+      const row = lookupMessageRoleAndText(args.chatId, args.messageId)
+      reactedText = row?.text ?? ''
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: reaction_dispatch: history lookup failed: ${err}\n`,
+      )
+    }
+  }
+
+  const { text, meta } = buildReactionDispatchInbound({
+    emoji: args.emoji!,
+    chatId: args.chatId,
+    messageId: args.messageId,
+    user: args.user,
+    userId: args.userId,
+    reactedText,
+    ...(typeof args.threadId === 'number' ? { threadId: args.threadId } : {}),
+  })
+
+  const ts = Date.now()
+  const inbound: InboundMessage = {
+    type: 'inbound',
+    chatId: args.chatId,
+    ...(typeof args.threadId === 'number' ? { threadId: args.threadId } : {}),
+    messageId: ts,
+    user: args.user,
+    userId: args.userId,
+    ts,
+    text,
+    meta,
+  }
+  const delivered = ipcServer.sendToAgent(agentName, inbound)
+  if (delivered) markClaudeBusyForInbound(inbound)
+  process.stderr.write(
+    `telegram gateway: reaction_dispatch agent=${agentName} chat=${args.chatId} ` +
+    `emoji=${args.emoji} message_id=${args.messageId} delivered=${delivered}\n`,
+  )
+  if (!delivered) {
+    pendingInboundBuffer.push(agentName, inbound)
+  }
+}
+
 /**
  * Dispatch a debounce-flushed batch as a synthetic InboundMessage via
  * the same `ipcServer.sendToAgent` path the cron-fold-in uses.
@@ -19949,10 +20064,29 @@ async function handleMessageReaction(ctx: Context): Promise<void> {
     // From here on we ignore failures rather than reject (the persist
     // path above is the v1 contract; trigger is best-effort).
     if (action === 'remove' || emoji === null) return
-    if (!HISTORY_ENABLED) return // need history to identify bot-authored target
     const reacter = update.user
     if (!reacter) return // anonymous group-channel reactions — not user-attributable
 
+    const reacterName = reacter.first_name ?? reacter.username ?? String(reacter.id)
+
+    // ─── reaction_dispatch (#2291) ───────────────────────────────────────
+    // Event-driven dispatch of ANY qualifying reaction as a button-style
+    // inbound turn. Independent of (and runs before) the bot-authored
+    // `reactions` feedback path below; both may fire for one reaction.
+    maybeDispatchReaction({
+      chatId: chat_id,
+      messageId: message_id,
+      emoji,
+      action,
+      user: reacterName,
+      userId: reacter.id,
+      ...(typeof update.message_thread_id === 'number'
+        ? { threadId: update.message_thread_id }
+        : {}),
+    })
+
+    if (!HISTORY_ENABLED) return // need history to identify bot-authored target
+
     const cfg = getReactionsConfig()
     if (!cfg.enabled) return
 
@@ -20025,7 +20159,7 @@ async function handleMessageReaction(ctx: Context): Promise<void> {
       ts: Date.now(),
       preview,
       userId: reacter.id,
-      user: reacter.first_name ?? reacter.username ?? String(reacter.id),
+      user: reacterName,
       ...(typeof update.message_thread_id === 'number'
         ? { threadId: update.message_thread_id }
         : {}),

package/telegram-plugin/gateway/reaction-dispatch.ts

@@ -0,0 +1,174 @@
+/**
+ * Reaction-dispatch: event-driven Telegram `message_reaction` → agent turn.
+ *
+ * Issue: https://github.com/switchroom/switchroom/issues/2291
+ *
+ * Distinct from the `reactions` trigger module (`reaction-trigger.ts`,
+ * #1074), which forwards reactions on the BOT's own messages as feedback
+ * (debounced, hour-capped, default ON, bot-authored-gated). This module
+ * implements the #2291 request: deliver ANY qualifying `message_reaction`
+ * update — regardless of who authored the reacted message — as an inbound
+ * channel turn shaped like a button-callback event:
+ *
+ *   <channel source="switchroom-telegram" event="reaction"
+ *            emoji="👨‍💻" message_id="123" chat_id="456" user="Ken">
+ *   <reacted message text>
+ *   </channel>
+ *
+ * It exists so reaction-driven workflows (e.g. clerk's Telegram→Linear
+ * capture on a 👨‍💻 reaction) stop polling get_recent_messages on a cron.
+ *
+ * Design:
+ *   - Default OFF. No turns fire unless an operator configures a
+ *     `reaction_dispatch` block with a non-empty `emojis` allowlist.
+ *   - Emoji allowlist filter. Only additions/changes whose new emoji is
+ *     in the allowlist dispatch. Removals never fire (handled by the
+ *     gateway before this module is consulted).
+ *   - No bot-authored gate — the whole point is reacting to arbitrary
+ *     messages (the user's own, peers', or the bot's).
+ *   - The reacted message's text is looked up from the SQLite history
+ *     buffer; a miss degrades to an empty body (the envelope still
+ *     carries emoji / message_id / chat_id / user).
+ *
+ * This module is pure gateway-internal logic — no Telegram API calls,
+ * no IPC. The gateway's `message_reaction` handler calls
+ * `evaluateReactionDispatch` then `buildReactionDispatchInbound`.
+ */
+
+export interface ReactionDispatchResolvedConfig {
+  enabled: boolean;
+  /** Allowlist of emoji that trigger a dispatch. Empty ⇒ nothing fires. */
+  emojis: ReadonlySet<string>;
+}
+
+/**
+ * Built-in defaults — applied when the cascade does not set a field.
+ * Default OFF: no `reaction_dispatch` block ⇒ no reaction turns. This is
+ * the noise-avoidance contract from #2291.
+ */
+export const REACTION_DISPATCH_DEFAULTS: ReactionDispatchResolvedConfig = Object.freeze({
+  enabled: false,
+  emojis: Object.freeze(new Set<string>()) as ReadonlySet<string>,
+});
+
+/**
+ * Cascade-resolved `reaction_dispatch` slice as it appears on the agent
+ * config. Shape mirrors `ReactionDispatchSchema` in `src/config/schema.ts`.
+ * Typed loosely so this module stays independent of the src/ zod schemas.
+ */
+export interface ReactionDispatchConfigInput {
+  enabled?: boolean;
+  emojis?: readonly string[];
+}
+
+/**
+ * Fold a raw cascade-resolved `reaction_dispatch:` block into the runtime
+ * shape, filling defaults for missing fields. A `null`/`undefined` raw
+ * input collapses to the (OFF) built-in defaults.
+ */
+export function resolveReactionDispatchConfig(
+  raw: ReactionDispatchConfigInput | null | undefined,
+): ReactionDispatchResolvedConfig {
+  if (!raw) return REACTION_DISPATCH_DEFAULTS;
+  return {
+    enabled: raw.enabled ?? REACTION_DISPATCH_DEFAULTS.enabled,
+    emojis: raw.emojis !== undefined
+      ? new Set(raw.emojis)
+      : REACTION_DISPATCH_DEFAULTS.emojis,
+  };
+}
+
+// ─── Predicate ───────────────────────────────────────────────────────────
+
+export interface ReactionDispatchCandidate {
+  /** Emoji string from the new_reaction; null when not a plain emoji. */
+  emoji: string | null;
+  /** 'add' | 'change' — 'remove' candidates are rejected pre-call. */
+  action: 'add' | 'change';
+}
+
+export type ReactionDispatchDecision =
+  | { ok: true }
+  | { ok: false; reason: 'disabled' | 'no_emoji' | 'emoji_not_in_allowlist' };
+
+/**
+ * Synchronous predicate. Returns `ok: true` only when the dispatch path
+ * is enabled and the candidate's emoji is in the allowlist. Removals are
+ * the caller's responsibility to filter (the Bot API distinguishes them
+ * via empty `new_reaction`); this predicate only ever sees add/change.
+ */
+export function evaluateReactionDispatch(
+  cfg: ReactionDispatchResolvedConfig,
+  c: ReactionDispatchCandidate,
+): ReactionDispatchDecision {
+  if (!cfg.enabled) return { ok: false, reason: 'disabled' };
+  if (c.emoji === null) return { ok: false, reason: 'no_emoji' };
+  if (!cfg.emojis.has(c.emoji)) return { ok: false, reason: 'emoji_not_in_allowlist' };
+  return { ok: true };
+}
+
+// ─── Inbound envelope builder ─────────────────────────────────────────────
+
+export interface ReactionDispatchInput {
+  emoji: string;
+  chatId: string;
+  messageId: number;
+  /** Display name of the reacter (first_name → username → string id). */
+  user: string;
+  /** Numeric user_id of the reacter, for the wire's userId field. */
+  userId: number;
+  /** Reacted message's text from the history buffer; '' on miss. */
+  reactedText: string;
+  /** Forum thread id if the reacted message lived in a topic. */
+  threadId?: number;
+}
+
+export interface ReactionDispatchInbound {
+  text: string;
+  meta: Record<string, string>;
+}
+
+/**
+ * Build the synthesized inbound's `text` + `meta`. The envelope mirrors
+ * the button-callback event shape so the agent reads reactions and button
+ * taps the same way. The reacted message's text lands in the element body.
+ */
+export function buildReactionDispatchInbound(
+  input: ReactionDispatchInput,
+): ReactionDispatchInbound {
+  const safeEmoji = escapeAttr(input.emoji);
+  const safeUser = escapeAttr(input.user);
+  const safeChat = escapeAttr(input.chatId);
+  const body = escapeBody(input.reactedText);
+
+  const text =
+    `<channel source="switchroom-telegram" event="reaction" ` +
+    `emoji="${safeEmoji}" message_id="${input.messageId}" ` +
+    `chat_id="${safeChat}" user="${safeUser}">` +
+    body +
+    `</channel>`;
+
+  const meta: Record<string, string> = {
+    source: 'switchroom-telegram',
+    event: 'reaction',
+    reaction_emoji: input.emoji,
+    target_message_id: String(input.messageId),
+    reacted_text: input.reactedText,
+  };
+
+  return { text, meta };
+}
+
+// Minimal XML-attr escape; the body uses a looser escape because it lands
+// inside the element body, not an attribute value.
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function escapeBody(s: string): string {
+  return s.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}

package/telegram-plugin/tests/reaction-dispatch.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Unit tests for the reaction-dispatch primitives (#2291).
+ *
+ * Covers config resolution (default OFF), the synchronous emoji-allowlist
+ * predicate (match / no-match / removed-ignored / no-emoji), and the
+ * inbound envelope builder (shape + history-hit / history-miss body).
+ */
+
+import { describe, it, expect } from 'bun:test'
+import {
+  REACTION_DISPATCH_DEFAULTS,
+  resolveReactionDispatchConfig,
+  evaluateReactionDispatch,
+  buildReactionDispatchInbound,
+  type ReactionDispatchResolvedConfig,
+} from '../gateway/reaction-dispatch.ts'
+
+function cfg(over: Partial<{ enabled: boolean; emojis: string[] }> = {}): ReactionDispatchResolvedConfig {
+  return resolveReactionDispatchConfig({
+    enabled: over.enabled ?? true,
+    emojis: over.emojis ?? ['👨‍💻'],
+  })
+}
+
+describe('resolveReactionDispatchConfig — default OFF', () => {
+  it('null/undefined raw collapses to the OFF defaults', () => {
+    expect(resolveReactionDispatchConfig(undefined)).toBe(REACTION_DISPATCH_DEFAULTS)
+    expect(resolveReactionDispatchConfig(null)).toBe(REACTION_DISPATCH_DEFAULTS)
+    expect(REACTION_DISPATCH_DEFAULTS.enabled).toBe(false)
+    expect(REACTION_DISPATCH_DEFAULTS.emojis.size).toBe(0)
+  })
+
+  it('a block with emojis but no enabled flag stays disabled by default', () => {
+    const r = resolveReactionDispatchConfig({ emojis: ['👨‍💻'] })
+    // enabled defaults to false even when an allowlist is provided.
+    expect(r.enabled).toBe(false)
+    expect(r.emojis.has('👨‍💻')).toBe(true)
+  })
+
+  it('emojis REPLACE (set membership), enabled overrides', () => {
+    const r = resolveReactionDispatchConfig({ enabled: true, emojis: ['✅', '❌'] })
+    expect(r.enabled).toBe(true)
+    expect([...r.emojis].sort()).toEqual(['✅', '❌'].sort())
+  })
+})
+
+describe('evaluateReactionDispatch — emoji filtering', () => {
+  it('allowlist match → ok', () => {
+    expect(evaluateReactionDispatch(cfg(), { emoji: '👨‍💻', action: 'add' })).toEqual({ ok: true })
+  })
+
+  it('allowlist no-match → rejected', () => {
+    expect(evaluateReactionDispatch(cfg(), { emoji: '👍', action: 'add' })).toEqual({
+      ok: false,
+      reason: 'emoji_not_in_allowlist',
+    })
+  })
+
+  it('disabled config → rejected even on an allowlisted emoji', () => {
+    expect(
+      evaluateReactionDispatch(cfg({ enabled: false }), { emoji: '👨‍💻', action: 'add' }),
+    ).toEqual({ ok: false, reason: 'disabled' })
+  })
+
+  it('default-off config never fires', () => {
+    expect(
+      evaluateReactionDispatch(REACTION_DISPATCH_DEFAULTS, { emoji: '👨‍💻', action: 'add' }),
+    ).toEqual({ ok: false, reason: 'disabled' })
+  })
+
+  it('null emoji (custom emoji) → rejected', () => {
+    expect(evaluateReactionDispatch(cfg(), { emoji: null, action: 'add' })).toEqual({
+      ok: false,
+      reason: 'no_emoji',
+    })
+  })
+
+  it('change action with allowlisted emoji → ok (add/change both dispatch)', () => {
+    expect(evaluateReactionDispatch(cfg(), { emoji: '👨‍💻', action: 'change' })).toEqual({
+      ok: true,
+    })
+  })
+})
+
+describe('buildReactionDispatchInbound — envelope shape', () => {
+  it('history hit: body carries the reacted message text', () => {
+    const { text, meta } = buildReactionDispatchInbound({
+      emoji: '👨‍💻',
+      chatId: '456',
+      messageId: 123,
+      user: 'Ken',
+      userId: 999,
+      reactedText: 'capture this to Linear',
+    })
+    expect(text).toBe(
+      '<channel source="switchroom-telegram" event="reaction" ' +
+        'emoji="👨‍💻" message_id="123" chat_id="456" user="Ken">' +
+        'capture this to Linear</channel>',
+    )
+    expect(meta).toMatchObject({
+      source: 'switchroom-telegram',
+      event: 'reaction',
+      reaction_emoji: '👨‍💻',
+      target_message_id: '123',
+      reacted_text: 'capture this to Linear',
+    })
+  })
+
+  it('history miss: empty body, envelope still well-formed', () => {
+    const { text, meta } = buildReactionDispatchInbound({
+      emoji: '✅',
+      chatId: '456',
+      messageId: 7,
+      user: 'Ken',
+      userId: 999,
+      reactedText: '',
+    })
+    expect(text).toBe(
+      '<channel source="switchroom-telegram" event="reaction" ' +
+        'emoji="✅" message_id="7" chat_id="456" user="Ken"></channel>',
+    )
+    expect(meta.reacted_text).toBe('')
+  })
+
+  it('escapes XML-significant chars in attrs and body', () => {
+    const { text } = buildReactionDispatchInbound({
+      emoji: '👨‍💻',
+      chatId: '456',
+      messageId: 1,
+      user: 'A & B "x"',
+      userId: 1,
+      reactedText: 'a <b> & c',
+    })
+    expect(text).toContain('user="A &amp; B &quot;x&quot;"')
+    expect(text).toContain('>a &lt;b&gt; & c<')
+  })
+})