switchroom 0.15.7 → 0.15.9

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<')
+  })
+})