switchroom 0.15.7 → 0.15.9

package/dist/vault/broker/server.js

@@ -327,6 +327,18 @@ function mergeAgentConfig(defaultsIn, agentIn) {
     }
     merged.reactions = combined;
   }
+  const dReactionDispatch = defaults.reaction_dispatch;
+  const mReactionDispatch = merged.reaction_dispatch;
+  if (dReactionDispatch || mReactionDispatch) {
+    const base = dReactionDispatch ?? {};
+    const override = mReactionDispatch ?? {};
+    const combined = { ...base };
+    for (const [k, v] of Object.entries(override)) {
+      if (v !== undefined)
+        combined[k] = v;
+    }
+    merged.reaction_dispatch = combined;
+  }
   if (defaults.resources || merged.resources) {
     const d = defaults.resources ?? {};
     const a = merged.resources ?? {};
@@ -11277,7 +11289,7 @@ var init_zod = __esm(() => {
 });
 
 // src/config/schema.ts
-var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, TelegramReactionsPollSchema, PollSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReleaseBlock, NetworkIsolationSchema, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, SwitchroomConfigSchema;
+var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, TelegramReactionsPollSchema, PollSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReactionDispatchSchema, ReleaseBlock, NetworkIsolationSchema, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, SwitchroomConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   CodeRepoEntrySchema = exports_external.object({
@@ -11553,6 +11565,10 @@ var init_schema = __esm(() => {
     per_hour_cap: exports_external.number().int().nonnegative().optional().describe("Max reaction-triggered synthetic turns per chat per rolling hour. " + "Refusals are stderr-logged but not surfaced to the agent. " + "Default 10. Set to 0 to disable triggering via the cap path."),
     group_admin_only: exports_external.boolean().optional().describe("In groups/supergroups (negative chat_id), only trigger a synthetic " + "turn when the reacter is a chat admin (creator or administrator). " + "Failing the lookup is treated as non-admin (fail-closed). " + "DMs are never affected by this flag — the reacter IS the user. " + "Default true.")
   }).optional();
+  ReactionDispatchSchema = exports_external.object({
+    enabled: exports_external.boolean().optional().describe("Master switch for the reaction-dispatch path. Default false — " + "with no reaction_dispatch block, reactions are persisted (and may " + "feed the `reactions` feedback path) but are NEVER dispatched as " + "event-driven inbound turns."),
+    emojis: exports_external.array(exports_external.string()).optional().describe('Emoji allowlist that triggers a `<channel event="reaction">` ' + "inbound turn when reacted to any message. Default [] (nothing " + "fires). Cascade mode: REPLACE (not union) — a layer's list " + "replaces lower layers entirely so an operator can narrow per-agent.")
+  }).optional();
   ReleaseBlock = exports_external.object({
     channel: exports_external.enum(["dev", "rc", "latest"]).optional(),
     pin: exports_external.string().regex(/^(sha-[0-9a-f]{7,40}|v\d+\.\d+\.\d+)$/).optional()
@@ -11588,6 +11604,7 @@ var init_schema = __esm(() => {
     schedule: exports_external.array(ScheduleEntrySchema).optional(),
     secrets: exports_external.array(exports_external.string().regex(/^[a-zA-Z0-9_\-/]+$/, "Secret key names must contain only alphanumeric characters, underscores, hyphens, and forward slashes")).optional().describe("Operator-granted STANDING vault keys this agent may read via the " + "broker — independent of any cron or MCP server. Use when an agent " + "needs a credential both interactively and in its own (agent-managed) " + "schedules, so the grant lives with the agent rather than welded to a " + "specific cron's `secrets[]`. OPERATOR-SET ONLY: agents cannot edit " + "switchroom.yaml or self-grant (reference/vision.md outcome 2 — 'you " + "hold the leash; only your tap grants it'). Exact key names. Cascades " + "UNION across defaults -> profile -> agent (see docs/configuration.md)."),
     reactions: ReactionsSchema,
+    reaction_dispatch: ReactionDispatchSchema,
     model: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._\-/\[\]:]*$/, "Model name must be alphanumeric with ._-/[]: only").optional(),
     thinking_effort: exports_external.enum(["low", "medium", "high", "xhigh", "max"]).optional().describe("Adaptive-thinking effort level passed as --effort to the claude CLI. " + "lower = faster/cheaper, higher = more reasoning. Omit to use Claude's default."),
     permission_mode: exports_external.enum(["acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan"]).optional().describe("Permission mode passed as --permission-mode to the claude CLI. " + "Omit to use Claude's default (acceptEdits for switchroom agents). " + "Warning: bypassPermissions and dontAsk skip all safety checks — use only in trusted sandboxes."),
@@ -11657,6 +11674,7 @@ var init_schema = __esm(() => {
     schedule: exports_external.array(ScheduleEntrySchema).default([]),
     secrets: exports_external.array(exports_external.string().regex(/^[a-zA-Z0-9_\-/]+$/, "Secret key names must contain only alphanumeric characters, underscores, hyphens, and forward slashes")).optional(),
     reactions: ReactionsSchema,
+    reaction_dispatch: ReactionDispatchSchema,
     model: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._\-/\[\]:]*$/, "Model name must be alphanumeric with ._-/[]: only (no spaces or shell specials)").optional().describe("Claude model override (e.g., 'claude-sonnet-4-6')"),
     thinking_effort: exports_external.enum(["low", "medium", "high", "xhigh", "max"]).optional().describe("Adaptive-thinking effort level passed as --effort to the claude CLI. " + "Per-agent override wins over defaults.thinking_effort. " + "lower = faster/cheaper, higher = more reasoning. Omit to use Claude's default."),
     permission_mode: exports_external.enum(["acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan"]).optional().describe("Permission mode passed as --permission-mode to the claude CLI. " + "Per-agent override wins over defaults.permission_mode. " + "Warning: bypassPermissions and dontAsk skip all safety checks — use only in trusted sandboxes."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.15.7",
+  "version": "0.15.9",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/profiles/_shared/agent-self-service.md.hbs

@@ -28,14 +28,33 @@ tools is to let you do the edit yourself.
 
 ### Tools
 
-- **`schedule_add(cron_expr, prompt, name?, secrets?)`** — append a new schedule
-  entry. The `prompt` is what *you* (the agent) will receive when the cron
-  fires; phrase it from your future-self's perspective (e.g.
-  `"Time for the daily digest — pull yesterday's GitHub activity and DM the
-  summary to chat 12345"`, not `"please send the digest"`). Optional
+- **`schedule_add(cron_expr, prompt, name?, secrets?, model?, context?)`** —
+  append a new schedule entry. Takes effect within **~30s** (the scheduler
+  hot-reloads — no restart needed). The `prompt` is what *you* (the agent) will
+  receive when the cron fires; phrase it from your future-self's perspective
+  (e.g. `"Time for the daily digest — pull yesterday's GitHub activity and DM
+  the summary to chat 12345"`, not `"please send the digest"`). Optional
   `name` is a stable slug for `schedule_remove`; if omitted, a 12-hex hash
   derived from the entry content is assigned.
 
+  **Mind the cost — pick the cheapest tier that does the job:**
+  - *Default (no `model`)* — the fire runs as a **full turn in your live
+    session**: your model, your whole context + memory. Right for work that
+    genuinely needs *you* (your persona, your conversation history). Costly for
+    routine checks — every fire pays your full context.
+  - *`model: "sonnet"`* (or `context: "fresh"`) — routes the fire to a **cheap,
+    minimal-context cron session** (Tier 1): a fresh Sonnet with just the
+    prompt, no heavy context. Use for light, self-contained recurring work
+    (summarise a feed, format a digest) where you don't need your memory. Much
+    cheaper per fire. *(Honoured only when the operator has enabled cheap-cron;
+    otherwise it still runs as a normal turn — never silently dropped.)*
+  - *"Only act when X changes"* — don't poll with a frequent prompt cron (every
+    fire is a wasted turn when nothing changed). Ask the **operator** to set up
+    a **poll** (model-free check, e.g. a webpage/API via `kind: poll`) or, for
+    reaction-triggered work, **`reaction_dispatch`** (an emoji reaction wakes
+    you instantly — zero polling). These need an operator config commit
+    (egress/identity gates), so request them rather than authoring them yourself.
+
 - **`schedule_remove(name | cron_hash)`** — delete by `name` (the slug from
   add) or by 12-hex `cron_hash` (shown in `cron_list` output). Both
   arguments are accepted; pass one.

package/telegram-plugin/dist/gateway/gateway.js

@@ -23802,7 +23802,7 @@ var init_dist = __esm(() => {
 });
 
 // ../src/config/schema.ts
-var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, TelegramReactionsPollSchema, PollSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReleaseBlock, NetworkIsolationSchema, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, SwitchroomConfigSchema;
+var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, TelegramReactionsPollSchema, PollSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReactionDispatchSchema, ReleaseBlock, NetworkIsolationSchema, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, SwitchroomConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   CodeRepoEntrySchema = exports_external.object({
@@ -24078,6 +24078,10 @@ var init_schema = __esm(() => {
     per_hour_cap: exports_external.number().int().nonnegative().optional().describe("Max reaction-triggered synthetic turns per chat per rolling hour. " + "Refusals are stderr-logged but not surfaced to the agent. " + "Default 10. Set to 0 to disable triggering via the cap path."),
     group_admin_only: exports_external.boolean().optional().describe("In groups/supergroups (negative chat_id), only trigger a synthetic " + "turn when the reacter is a chat admin (creator or administrator). " + "Failing the lookup is treated as non-admin (fail-closed). " + "DMs are never affected by this flag \u2014 the reacter IS the user. " + "Default true.")
   }).optional();
+  ReactionDispatchSchema = exports_external.object({
+    enabled: exports_external.boolean().optional().describe("Master switch for the reaction-dispatch path. Default false \u2014 " + "with no reaction_dispatch block, reactions are persisted (and may " + "feed the `reactions` feedback path) but are NEVER dispatched as " + "event-driven inbound turns."),
+    emojis: exports_external.array(exports_external.string()).optional().describe('Emoji allowlist that triggers a `<channel event="reaction">` ' + "inbound turn when reacted to any message. Default [] (nothing " + "fires). Cascade mode: REPLACE (not union) \u2014 a layer's list " + "replaces lower layers entirely so an operator can narrow per-agent.")
+  }).optional();
   ReleaseBlock = exports_external.object({
     channel: exports_external.enum(["dev", "rc", "latest"]).optional(),
     pin: exports_external.string().regex(/^(sha-[0-9a-f]{7,40}|v\d+\.\d+\.\d+)$/).optional()
@@ -24113,6 +24117,7 @@ var init_schema = __esm(() => {
     schedule: exports_external.array(ScheduleEntrySchema).optional(),
     secrets: exports_external.array(exports_external.string().regex(/^[a-zA-Z0-9_\-/]+$/, "Secret key names must contain only alphanumeric characters, underscores, hyphens, and forward slashes")).optional().describe("Operator-granted STANDING vault keys this agent may read via the " + "broker \u2014 independent of any cron or MCP server. Use when an agent " + "needs a credential both interactively and in its own (agent-managed) " + "schedules, so the grant lives with the agent rather than welded to a " + "specific cron's `secrets[]`. OPERATOR-SET ONLY: agents cannot edit " + "switchroom.yaml or self-grant (reference/vision.md outcome 2 \u2014 'you " + "hold the leash; only your tap grants it'). Exact key names. Cascades " + "UNION across defaults -> profile -> agent (see docs/configuration.md)."),
     reactions: ReactionsSchema,
+    reaction_dispatch: ReactionDispatchSchema,
     model: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._\-/\[\]:]*$/, "Model name must be alphanumeric with ._-/[]: only").optional(),
     thinking_effort: exports_external.enum(["low", "medium", "high", "xhigh", "max"]).optional().describe("Adaptive-thinking effort level passed as --effort to the claude CLI. " + "lower = faster/cheaper, higher = more reasoning. Omit to use Claude's default."),
     permission_mode: exports_external.enum(["acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan"]).optional().describe("Permission mode passed as --permission-mode to the claude CLI. " + "Omit to use Claude's default (acceptEdits for switchroom agents). " + "Warning: bypassPermissions and dontAsk skip all safety checks \u2014 use only in trusted sandboxes."),
@@ -24182,6 +24187,7 @@ var init_schema = __esm(() => {
     schedule: exports_external.array(ScheduleEntrySchema).default([]),
     secrets: exports_external.array(exports_external.string().regex(/^[a-zA-Z0-9_\-/]+$/, "Secret key names must contain only alphanumeric characters, underscores, hyphens, and forward slashes")).optional(),
     reactions: ReactionsSchema,
+    reaction_dispatch: ReactionDispatchSchema,
     model: exports_external.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._\-/\[\]:]*$/, "Model name must be alphanumeric with ._-/[]: only (no spaces or shell specials)").optional().describe("Claude model override (e.g., 'claude-sonnet-4-6')"),
     thinking_effort: exports_external.enum(["low", "medium", "high", "xhigh", "max"]).optional().describe("Adaptive-thinking effort level passed as --effort to the claude CLI. " + "Per-agent override wins over defaults.thinking_effort. " + "lower = faster/cheaper, higher = more reasoning. Omit to use Claude's default."),
     permission_mode: exports_external.enum(["acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan"]).optional().describe("Permission mode passed as --permission-mode to the claude CLI. " + "Per-agent override wins over defaults.permission_mode. " + "Warning: bypassPermissions and dontAsk skip all safety checks \u2014 use only in trusted sandboxes."),
@@ -24857,6 +24863,18 @@ function mergeAgentConfig(defaultsIn, agentIn) {
     }
     merged.reactions = combined;
   }
+  const dReactionDispatch = defaults.reaction_dispatch;
+  const mReactionDispatch = merged.reaction_dispatch;
+  if (dReactionDispatch || mReactionDispatch) {
+    const base = dReactionDispatch ?? {};
+    const override = mReactionDispatch ?? {};
+    const combined = { ...base };
+    for (const [k, v] of Object.entries(override)) {
+      if (v !== undefined)
+        combined[k] = v;
+    }
+    merged.reaction_dispatch = combined;
+  }
   if (defaults.resources || merged.resources) {
     const d = defaults.resources ?? {};
     const a = merged.resources ?? {};
@@ -45770,6 +45788,18 @@ function mergeAgentConfig2(defaultsIn, agentIn) {
     }
     merged.reactions = combined;
   }
+  const dReactionDispatch = defaults.reaction_dispatch;
+  const mReactionDispatch = merged.reaction_dispatch;
+  if (dReactionDispatch || mReactionDispatch) {
+    const base = dReactionDispatch ?? {};
+    const override = mReactionDispatch ?? {};
+    const combined = { ...base };
+    for (const [k, v] of Object.entries(override)) {
+      if (v !== undefined)
+        combined[k] = v;
+    }
+    merged.reaction_dispatch = combined;
+  }
   if (defaults.resources || merged.resources) {
     const d = defaults.resources ?? {};
     const a = merged.resources ?? {};
@@ -49848,6 +49878,50 @@ function escapeBody(s) {
   return s.replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
+// gateway/reaction-dispatch.ts
+var REACTION_DISPATCH_DEFAULTS = Object.freeze({
+  enabled: false,
+  emojis: Object.freeze(new Set)
+});
+function resolveReactionDispatchConfig(raw) {
+  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
+  };
+}
+function evaluateReactionDispatch(cfg, c) {
+  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 };
+}
+function buildReactionDispatchInbound(input) {
+  const safeEmoji = escapeAttr2(input.emoji);
+  const safeUser = escapeAttr2(input.user);
+  const safeChat = escapeAttr2(input.chatId);
+  const body = escapeBody2(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 = {
+    source: "switchroom-telegram",
+    event: "reaction",
+    reaction_emoji: input.emoji,
+    target_message_id: String(input.messageId),
+    reacted_text: input.reactedText
+  };
+  return { text, meta };
+}
+function escapeAttr2(s) {
+  return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeBody2(s) {
+  return s.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
 // gateway/pid-file.ts
 import { writeFileSync as writeFileSync11, readFileSync as readFileSync18, unlinkSync as unlinkSync7, renameSync as renameSync6 } from "node:fs";
 function writePidFile(path, record) {
@@ -53683,10 +53757,10 @@ function readTurnActiveMarkerAgeMs(stateDir, now) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.15.7";
-var COMMIT_SHA = "c0a8b988";
-var COMMIT_DATE = "2026-06-12T04:28:04Z";
-var LATEST_PR = 2286;
+var VERSION = "0.15.9";
+var COMMIT_SHA = "6ed776e2";
+var COMMIT_DATE = "2026-06-13T00:47:35Z";
+var LATEST_PR = 2300;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -65034,6 +65108,84 @@ function getReactionDebounce() {
   }
   return reactionDebounce;
 }
+var reactionDispatchCfg = null;
+function getReactionDispatchConfig() {
+  if (reactionDispatchCfg)
+    return reactionDispatchCfg;
+  let raw = undefined;
+  try {
+    const cfg = loadConfig2();
+    const agentName3 = process.env.SWITCHROOM_AGENT_NAME;
+    if (agentName3) {
+      const rawAgent = cfg.agents?.[agentName3];
+      if (rawAgent) {
+        const resolved = resolveAgentConfig2(cfg.defaults, cfg.profiles, rawAgent);
+        raw = resolved.reaction_dispatch;
+      }
+    }
+  } catch (err) {
+    process.stderr.write(`telegram gateway: reaction_dispatch: config load failed, defaulting OFF: ${err.message}
+`);
+  }
+  reactionDispatchCfg = resolveReactionDispatchConfig(raw ?? null);
+  return reactionDispatchCfg;
+}
+function maybeDispatchReaction(args) {
+  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}
+`);
+    }
+    return;
+  }
+  const agentName3 = process.env.SWITCHROOM_AGENT_NAME;
+  if (!agentName3) {
+    process.stderr.write(`telegram gateway: reaction_dispatch: skipped \u2014 SWITCHROOM_AGENT_NAME unset
+`);
+    return;
+  }
+  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}
+`);
+    }
+  }
+  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 = {
+    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(agentName3, inbound);
+  if (delivered)
+    markClaudeBusyForInbound(inbound);
+  process.stderr.write(`telegram gateway: reaction_dispatch agent=${agentName3} chat=${args.chatId} emoji=${args.emoji} message_id=${args.messageId} delivered=${delivered}
+`);
+  if (!delivered) {
+    pendingInboundBuffer.push(agentName3, inbound);
+  }
+}
 function flushReactionBatch(batch) {
   const agentName3 = process.env.SWITCHROOM_AGENT_NAME;
   if (!agentName3) {
@@ -65109,11 +65261,21 @@ async function handleMessageReaction(ctx) {
 `);
     if (action === "remove" || emoji === null)
       return;
-    if (!HISTORY_ENABLED)
-      return;
     const reacter = update.user;
     if (!reacter)
       return;
+    const reacterName = reacter.first_name ?? reacter.username ?? String(reacter.id);
+    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;
     const cfg = getReactionsConfig();
     if (!cfg.enabled)
       return;
@@ -65163,7 +65325,7 @@ async function handleMessageReaction(ctx) {
       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 } : {}
     };
     getReactionDebounce().enqueue(update.chat.id, pending2);

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 }
         : {}),