typeclaw 0.19.0 → 0.21.0

package/src/channels/router.ts

@@ -51,9 +51,15 @@ import type {
   HistoryCallback,
   InboundAttachment,
   InboundMessage,
+  RemoveReactionCallback,
+  RemoveReactionRequest,
   OutboundCallback,
   OutboundMessage,
   QuoteAnchorSource,
+  ReactionCallback,
+  ReactionRef,
+  ReactionRequest,
+  ReactionResult,
   ResolvedChannelNames,
   SendErrorCode,
   SendResult,
@@ -108,6 +114,7 @@ export const SESSION_GC_INTERVAL_MS = 60 * 1000
 // Enforced inside router.send for `source: 'tool'` callers; system
 // recovery paths (`source: 'system'`) bypass.
 export const MAX_CHANNEL_SENDS_PER_TURN = 10
+export const ENGAGE_REACTION_EMOJI = 'eyes'
 // Ceiling on tool-source channel sends that a same-turn router policy DENIED
 // without delivering — `skip-locked`, `turn-cap`, or `duplicate`. Such denials
 // return a soft error and do NOT increment `consecutiveSends`, so a model that
@@ -276,6 +283,8 @@ type QueuedInbound = {
   authorName: string
   authorIsBot: boolean
   externalMessageId: string
+  reactionRef?: ReactionRef
+  engageReaction?: Promise<ReactionRef | null>
   isBotMention: boolean
   replyToBotMessageId: string | null
   isDm: boolean
@@ -324,6 +333,14 @@ type LiveSession = {
   originRef: { current: SessionOrigin | undefined }
   promptQueue: QueuedInbound[]
   contextBuffer: ObservedInbound[]
+  // Attachments of the messages composing the in-flight turn. drain()
+  // splices promptQueue/contextBuffer empty BEFORE calling prompt(), but
+  // the model only requests an attachment (look_at_channel_attachment /
+  // channel_fetch_attachment) DURING prompt() — by which point both queues
+  // are empty. This turn-scoped snapshot, populated right after the splice
+  // and cleared when the turn ends, is what the lookup reads so a freshly-
+  // arrived attachment stays resolvable for the whole turn it belongs to.
+  currentTurnAttachments: readonly InboundAttachment[]
   draining: boolean
   debounceTimer: ReturnType<typeof setTimeout> | null
   typingTimer: ReturnType<typeof setInterval> | null
@@ -334,6 +351,16 @@ type LiveSession = {
   firstUnprocessedAt: number
   currentTurnAuthorId: string | null
   currentTurnAuthorIds: Set<string>
+  // Reaction target of the inbound that triggered THIS turn (the last item in
+  // the drained batch, mirroring `currentTurnAuthorId`). Surfaced on the live
+  // origin so `channel_react` reacts to the triggering message, not whichever
+  // inbound happens to be latest in the queue. Null on reminder-only turns.
+  currentTurnReactionRef: ReactionRef | null
+  // One engage-:eyes:-add promise per inbound coalesced into THIS turn, each
+  // resolving to its removable per-instance ref (or null). A debounced turn can
+  // batch several inbounds that each got their own :eyes:, so every entry is
+  // removed after the reply. Empty on turns with no reactable inbound.
+  currentTurnEngageReactions: Array<Promise<ReactionRef | null>>
   lastTurnAuthorIds: Set<string>
   // Mirror of currentTurnAuthorId at end-of-turn (the LAST speaker of the
   // prior batch), preserved across the drain finally-block which resets
@@ -511,6 +538,17 @@ export type ChannelRouter = {
   }) => { count: number; windowMs: number }
   registerOutbound: (adapter: ChannelKey['adapter'], cb: OutboundCallback) => void
   unregisterOutbound: (adapter: ChannelKey['adapter'], cb: OutboundCallback) => void
+  // Reaction support is opt-in per adapter: an adapter that never calls
+  // registerReaction makes `react` resolve to `code: 'unsupported'`, and
+  // auto-react-on-engage becomes a silent no-op for it. Kept separate from
+  // the outbound path on purpose — reactions are best-effort side effects, not
+  // messages, so they must not flow through send()'s flood/cap/dup/sticky guards.
+  registerReaction: (adapter: ChannelKey['adapter'], cb: ReactionCallback) => void
+  unregisterReaction: (adapter: ChannelKey['adapter'], cb: ReactionCallback) => void
+  react: (req: ReactionRequest) => Promise<ReactionResult>
+  registerRemoveReaction: (adapter: ChannelKey['adapter'], cb: RemoveReactionCallback) => void
+  unregisterRemoveReaction: (adapter: ChannelKey['adapter'], cb: RemoveReactionCallback) => void
+  removeReaction: (req: RemoveReactionRequest) => Promise<ReactionResult>
   registerTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
   unregisterTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
   registerChannelNameResolver: (adapter: ChannelKey['adapter'], resolver: ChannelNameResolver) => void
@@ -703,6 +741,7 @@ export type ClaimHandler = (input: ClaimHandlerInput) => Promise<ClaimHandlerOut
 const GRANT_ALL_PERMISSIONS: PermissionService = {
   has: () => true,
   resolveRole: () => 'owner',
+  compareRoleSeverity: () => 1,
   describe: () => ({ role: 'owner', permissions: [CORE_PERMISSIONS.channelRespond] }),
   replaceRoles: () => {},
 }
@@ -728,6 +767,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   // teardown was meant to clear.
   let liveGeneration = 0
   const outboundCallbacks = new Map<ChannelKey['adapter'], Set<OutboundCallback>>()
+  const reactionCallbacks = new Map<ChannelKey['adapter'], Set<ReactionCallback>>()
+  const removeReactionCallbacks = new Map<ChannelKey['adapter'], Set<RemoveReactionCallback>>()
   const typingCallbacks = new Map<ChannelKey['adapter'], Set<TypingCallback>>()
   const channelNameResolvers = new Map<ChannelKey['adapter'], Set<ChannelNameResolver>>()
   const membershipResolvers = new Map<ChannelKey['adapter'], Set<MembershipResolver>>()
@@ -1081,6 +1122,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         promptQueue: [],
         pendingSystemReminders: [],
         contextBuffer: [],
+        currentTurnAttachments: [],
         draining: false,
         debounceTimer: null,
         typingTimer: null,
@@ -1091,6 +1133,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         firstUnprocessedAt: 0,
         currentTurnAuthorId: null,
         currentTurnAuthorIds: new Set(),
+        currentTurnReactionRef: null,
+        currentTurnEngageReactions: [],
         // `lastTurnAuthorId` (string, used for `lastInboundAuthorId` in
         // origin) and `lastTurnAuthorIds` (Set, used by
         // `grantStickyForReplyTargets` as the fallback when
@@ -1223,6 +1267,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           receivedAt: now(),
           ts: item.message.ts,
           source: 'prefetch',
+          ...(item.message.attachments !== undefined ? { attachments: item.message.attachments } : {}),
         })
       } else {
         observed.push({
@@ -1451,6 +1496,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       ...(live.resolvedNames.chatName !== undefined ? { chatName: live.resolvedNames.chatName } : {}),
       thread: live.key.thread,
       ...(live.currentTurnAuthorId !== null ? { lastInboundAuthorId: live.currentTurnAuthorId } : {}),
+      ...(live.currentTurnReactionRef !== null ? { reactionRef: live.currentTurnReactionRef } : {}),
       participants: live.participants,
       ...(membership !== null ? { membership } : {}),
     }
@@ -1494,14 +1540,20 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         const batch = live.promptQueue.splice(0, live.promptQueue.length)
         const observed = live.contextBuffer.splice(0, live.contextBuffer.length)
         const reminders = live.pendingSystemReminders.splice(0, live.pendingSystemReminders.length)
+        live.currentTurnAttachments = collectTurnAttachments(observed, batch)
 
         if (batch.length > 0) {
           live.currentTurnAuthorId = batch[batch.length - 1]!.authorId
           live.currentTurnAuthorIds = new Set(batch.map((m) => m.authorId))
+          live.currentTurnReactionRef = batch[batch.length - 1]!.reactionRef ?? null
+          live.currentTurnEngageReactions = batch.flatMap((m) =>
+            m.engageReaction !== undefined ? [m.engageReaction] : [],
+          )
           live.consecutiveSends.clear()
           live.lastSentText.clear()
           live.pendingQuoteCandidate = captureQuoteCandidate(live.key.adapter, batch, observed)
         } else if (live.lastTurnAuthorId !== null) {
+          live.currentTurnEngageReactions = []
           // Reminder-only turn (batch.length === 0, reminders.length > 0):
           // restore the author identity from the prior turn so author-
           // scoped role resolution still works on this turn. The drain
@@ -1516,6 +1568,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           // author prior turn like alice→bob restores `bob`, not alice.
           live.currentTurnAuthorId = live.lastTurnAuthorId
           live.currentTurnAuthorIds = new Set(live.lastTurnAuthorIds)
+        } else {
+          live.currentTurnEngageReactions = []
         }
 
         // Update the live origin holder so this turn's tool.before events
@@ -1542,6 +1596,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(`[channels] ${live.keyId} prompting batch=${batch.length} text_len=${text.length}`)
         const promptStart = now()
         const successfulSendsBeforePrompt = live.successfulChannelSends
+        const engageAddPromises = live.currentTurnEngageReactions
         live.turnSeq++
         live.successfulSendsAtTurnStart = successfulSendsBeforePrompt
         live.policyDeniedToolSendsThisTurn.clear()
@@ -1556,6 +1611,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.consecutiveSends.clear()
           live.lastSentText.clear()
         } finally {
+          const sentReplyThisTurn = live.successfulChannelSends > successfulSendsBeforePrompt
+          if (sentReplyThisTurn) dropEngageReactionsAfterReply(live, engageAddPromises)
           await fireSessionTurnEnd(live)
         }
         await fireSessionIdle(live)
@@ -1568,6 +1625,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       live.draining = false
       live.currentTurnAuthorId = null
       live.currentTurnAuthorIds = new Set()
+      live.currentTurnReactionRef = null
+      live.currentTurnEngageReactions = []
+      live.currentTurnAttachments = []
       await stopTypingHeartbeat(live)
     }
   }
@@ -1816,9 +1876,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     publishInbound(event, 'engage', live.sessionId)
 
+    const engageReaction = autoReactOnEngage(event)
+
     updateLoopGuard(live, event)
 
-    enqueue(live, event)
+    enqueue(live, event, engageReaction)
 
     // Start showing "typing..." the moment we know we're going to engage,
     // so users see the indicator during the debounce window — not just
@@ -1900,7 +1962,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
-  const enqueue = (live: LiveSession, event: InboundMessage): void => {
+  const enqueue = (
+    live: LiveSession,
+    event: InboundMessage,
+    engageReaction: Promise<ReactionRef | null> | null,
+  ): void => {
     live.promptQueue.push({
       text: event.text,
       ...(event.attachments !== undefined && event.attachments.length > 0 ? { attachments: event.attachments } : {}),
@@ -1908,6 +1974,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       authorName: event.authorName,
       authorIsBot: event.authorIsBot,
       externalMessageId: event.externalMessageId,
+      ...(event.reactionRef !== undefined ? { reactionRef: event.reactionRef } : {}),
+      ...(engageReaction !== null ? { engageReaction } : {}),
       isBotMention: event.isBotMention,
       replyToBotMessageId: event.replyToBotMessageId,
       isDm: event.isDm,
@@ -1925,6 +1993,134 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     set.add(cb)
   }
 
+  const registerReaction = (adapter: ChannelKey['adapter'], cb: ReactionCallback): void => {
+    let set = reactionCallbacks.get(adapter)
+    if (!set) {
+      set = new Set()
+      reactionCallbacks.set(adapter, set)
+    }
+    set.add(cb)
+  }
+
+  const unregisterReaction = (adapter: ChannelKey['adapter'], cb: ReactionCallback): void => {
+    reactionCallbacks.get(adapter)?.delete(cb)
+  }
+
+  const registerRemoveReaction = (adapter: ChannelKey['adapter'], cb: RemoveReactionCallback): void => {
+    let set = removeReactionCallbacks.get(adapter)
+    if (!set) {
+      set = new Set()
+      removeReactionCallbacks.set(adapter, set)
+    }
+    set.add(cb)
+  }
+
+  const unregisterRemoveReaction = (adapter: ChannelKey['adapter'], cb: RemoveReactionCallback): void => {
+    removeReactionCallbacks.get(adapter)?.delete(cb)
+  }
+
+  const react = async (req: ReactionRequest): Promise<ReactionResult> => {
+    if (req.reactionRef.adapter !== req.adapter) {
+      return { ok: false, error: 'reaction ref adapter mismatch', code: 'unsupported' }
+    }
+    const callbacks = reactionCallbacks.get(req.adapter)
+    if (!callbacks || callbacks.size === 0) {
+      return { ok: false, error: `adapter "${req.adapter}" does not support reactions`, code: 'unsupported' }
+    }
+    let lastError: ReactionResult | undefined
+    for (const cb of Array.from(callbacks)) {
+      // A ReactionCallback that throws must not reject this promise: react() is
+      // called both fire-and-forget (autoReactOnEngage) and awaited by the
+      // channel_react tool, and neither should have to wrap it in try/catch. A
+      // throw is converted to a transient failure result so every caller gets a
+      // uniform { ok: false } instead of an exception.
+      const result = await cb(req).catch(
+        (err): ReactionResult => ({ ok: false, error: describe(err), code: 'transient' }),
+      )
+      if (result.ok) return result
+      lastError = result
+    }
+    return lastError ?? { ok: false, error: 'no reaction callback handled request', code: 'unsupported' }
+  }
+
+  const removeReaction = async (req: RemoveReactionRequest): Promise<ReactionResult> => {
+    if (req.reactionRef.adapter !== req.adapter) {
+      return { ok: false, error: 'reaction ref adapter mismatch', code: 'unsupported' }
+    }
+    const callbacks = removeReactionCallbacks.get(req.adapter)
+    if (!callbacks || callbacks.size === 0) {
+      return { ok: false, error: `adapter "${req.adapter}" does not support reaction removal`, code: 'unsupported' }
+    }
+    let lastError: ReactionResult | undefined
+    for (const cb of Array.from(callbacks)) {
+      const result = await cb(req).catch(
+        (err): ReactionResult => ({ ok: false, error: describe(err), code: 'transient' }),
+      )
+      if (result.ok) return result
+      lastError = result
+    }
+    return lastError ?? { ok: false, error: 'no reaction removal callback handled request', code: 'unsupported' }
+  }
+
+  // Best-effort acknowledgment: drop an :eyes: on the triggering inbound the
+  // moment we decide to engage, replacing the old "On it" ack comment on
+  // GitHub. Fire-and-forget so a reaction failure (missing permission, the
+  // adapter not supporting reactions, a transient API error) can NEVER block
+  // engagement, enqueueing, or the agent's actual reply. No reactionRef =
+  // nothing reactable (synthetic inbounds, reaction-less adapters) = silent skip.
+  const autoReactOnEngage = (event: InboundMessage): Promise<ReactionRef | null> | null => {
+    if (event.reactionRef === undefined) return null
+    const addResult = react({
+      adapter: event.adapter,
+      workspace: event.workspace,
+      chat: event.chat,
+      thread: event.thread,
+      reactionRef: event.reactionRef,
+      emoji: ENGAGE_REACTION_EMOJI,
+    })
+    const addReactionRef = addResult.then((r) => (r.ok ? (r.reactionRef ?? null) : null)).catch(() => null)
+    void addResult
+      .then((result) => {
+        if (!result.ok && result.code !== 'unsupported') {
+          logger.info(`[channels] engage-react failed adapter=${event.adapter} chat=${event.chat}: ${result.error}`)
+        }
+      })
+      .catch((err) => {
+        logger.info(`[channels] engage-react threw adapter=${event.adapter} chat=${event.chat}: ${describe(err)}`)
+      })
+    return addReactionRef
+  }
+
+  const dropEngageReactionsAfterReply = (live: LiveSession, addPromises: Array<Promise<ReactionRef | null>>): void => {
+    for (const addPromise of addPromises) dropOneEngageReactionAfterReply(live, addPromise)
+  }
+
+  const dropOneEngageReactionAfterReply = (live: LiveSession, addPromise: Promise<ReactionRef | null>): void => {
+    void addPromise
+      .then((reactionRef) => {
+        if (reactionRef === null) return undefined
+        return removeReaction({
+          adapter: live.key.adapter,
+          workspace: live.key.workspace,
+          chat: live.key.chat,
+          thread: live.key.thread,
+          reactionRef,
+        })
+      })
+      .then((result) => {
+        if (result && !result.ok && result.code !== 'unsupported' && result.code !== 'not-found') {
+          logger.info(
+            `[channels] engage-unreact failed adapter=${live.key.adapter} chat=${live.key.chat}: ${result.error}`,
+          )
+        }
+      })
+      .catch((err) => {
+        logger.info(
+          `[channels] engage-unreact threw adapter=${live.key.adapter} chat=${live.key.chat}: ${describe(err)}`,
+        )
+      })
+  }
+
   const unregisterOutbound = (adapter: ChannelKey['adapter'], cb: OutboundCallback): void => {
     outboundCallbacks.get(adapter)?.delete(cb)
   }
@@ -2058,9 +2254,14 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     // Walk newest → oldest so that when an id collides across messages
     // (e.g. two photos in the same session each labelled `#1`) the agent's
     // `attachment_id: 1` always resolves to the CURRENT inbound's
-    // attachment. promptQueue holds the about-to-be-delivered turn and
-    // is therefore the freshest; within each list, append-order maps to
-    // wall-clock order, so iterating in reverse gives recency.
+    // attachment. currentTurnAttachments holds the in-flight turn — the
+    // only place the about-to-be-viewed attachment lives once drain() has
+    // spliced promptQueue empty — and is therefore the freshest; promptQueue
+    // then holds any inbound that arrived mid-turn. Within each list,
+    // append-order maps to wall-clock order, so iterating in reverse gives
+    // recency.
+    const found = findAttachmentById(live.currentTurnAttachments, args.id)
+    if (found !== null) return found
     const haystacks: ReadonlyArray<ReadonlyArray<{ attachments?: readonly InboundAttachment[] }>> = [
       live.promptQueue,
       live.contextBuffer,
@@ -2068,8 +2269,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     for (const haystack of haystacks) {
       for (let i = haystack.length - 1; i >= 0; i--) {
         const item = haystack[i]
-        const found = item?.attachments?.find((attachment) => attachment.id === args.id)
-        if (found !== undefined) return found
+        const hit = item?.attachments?.find((attachment) => attachment.id === args.id)
+        if (hit !== undefined) return hit
       }
     }
     return null
@@ -2079,6 +2280,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const live = liveSessions.get(channelKeyId(args))
     if (live === undefined) return []
     const ids = new Set<number>()
+    for (const attachment of live.currentTurnAttachments) ids.add(attachment.id)
     for (const item of [...live.promptQueue, ...live.contextBuffer]) {
       for (const attachment of item.attachments ?? []) ids.add(attachment.id)
     }
@@ -2617,6 +2819,12 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     getSendRate,
     registerOutbound,
     unregisterOutbound,
+    registerReaction,
+    unregisterReaction,
+    react,
+    registerRemoveReaction,
+    unregisterRemoveReaction,
+    removeReaction,
     registerTyping,
     unregisterTyping,
     registerChannelNameResolver,
@@ -2701,6 +2909,24 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   }
 }
 
+function collectTurnAttachments(
+  observed: readonly ObservedInbound[],
+  batch: readonly QueuedInbound[],
+): readonly InboundAttachment[] {
+  const out: InboundAttachment[] = []
+  for (const item of observed) out.push(...(item.attachments ?? []))
+  for (const item of batch) out.push(...(item.attachments ?? []))
+  return out
+}
+
+function findAttachmentById(attachments: readonly InboundAttachment[], id: number): InboundAttachment | null {
+  for (let i = attachments.length - 1; i >= 0; i--) {
+    const attachment = attachments[i]
+    if (attachment?.id === id) return attachment
+  }
+  return null
+}
+
 function composeTurnPrompt(
   observed: readonly ObservedInbound[],
   batch: readonly QueuedInbound[],
@@ -2782,13 +3008,14 @@ function composeTurnPrompt(
     )
   }
   // Group-chat nudge: same SYSTEM MESSAGE convention as the loop guard. We
-  // engaged this turn (explicit mention/reply/alias, or a fresh trigger),
-  // but the room has multiple humans, so the default "answer everything"
-  // posture is wrong. The engagement gate already stopped sticky credit
-  // from waking us on every follow-up; this tells the model to be
-  // selective on the turns it IS woken for. Cache-neutral (user-turn
-  // suffix), and skipped when the loop guard already fired to avoid
-  // stacking two silence notices in one turn.
+  // engaged this turn — possibly via sticky credit, which now wakes us on
+  // every follow-up in a group too (the engagement gate is content-blind by
+  // design). In a multi-human room the default "answer everything" posture is
+  // wrong, so this nudge is the ONLY thing that makes the bot selective: it
+  // tells the model to answer genuine follow-ups and stay silent on chatter.
+  // The gate gets us into the turn; the model decides whether to speak.
+  // Cache-neutral (user-turn suffix), and skipped when the loop guard already
+  // fired to avoid stacking two silence notices in one turn.
   if (state.groupChatNudge === true && !state.loopGuardActive) {
     parts.push(
       '---',
@@ -2798,10 +3025,20 @@ function composeTurnPrompt(
       'signal from the channel router, not a message from anyone in the chat.',
       '**Do not acknowledge or reply to this notice.**',
       '',
-      'Guidance:',
-      '- Reply only if the current message is addressed to you or clearly needs your input.',
-      '- For chatter between others, side-conversation, or messages that do not need you,',
-      '  reply with `NO_REPLY` (or call `skip_response`) to stay silent and just keep watching.',
+      'You are woken on every message from someone you recently talked with, so',
+      'most turns you should stay quiet. In a group the target shifts every',
+      'message: before replying, identify who THIS latest message is aimed at.',
+      'Reply ONLY when:',
+      '- the current message is addressed to you (by name, @-mention, or reply), or',
+      '- it directly continues your own last exchange and clearly wants an answer',
+      '  (e.g. a follow-up question about what you just said).',
+      '',
+      'If it is aimed at someone else — another person by name or @-mention, a',
+      'reply to their message, or another bot — it is not your turn, even if you',
+      'were just talking with its author. Otherwise too — chatter, side-',
+      'conversation, banter, or anything not actually waiting on you — reply with',
+      '`NO_REPLY` (or call `skip_response`) to stay silent and keep watching.',
+      'When unsure, prefer silence.',
       '',
       '---',
       '',

package/src/channels/types.ts

@@ -94,8 +94,65 @@ export type InboundMessage = {
   // means "unknown" — the formatter renders such lines without a
   // timestamp prefix instead of stamping them with the wrong clock.
   ts: number
+  // Opaque, adapter-owned handle for the entity an emoji reaction would
+  // attach to. The classifier stamps it because only there is the platform-
+  // side target type still known (GitHub: issue body vs issue-comment vs
+  // pr-review-comment — all collapse to the same `chat`/`externalMessageId`
+  // pair downstream). Mirrors the `InboundAttachment.ref` opaque-handle
+  // pattern: ONLY the originating adapter's ReactionCallback knows how to
+  // parse `value`; the router and tools treat it as a pass-through token and
+  // never inspect it. Omitted when the inbound has no reactable target (e.g.
+  // synthetic review-request inbounds, or adapters without reaction support).
+  reactionRef?: ReactionRef
 }
 
+// Opaque reaction target handle. `adapter` lets the router refuse a ref to
+// the wrong adapter's callback; `value` is an adapter-private encoding (for
+// GitHub, a JSON blob distinguishing issue / issue-comment / pr-review-comment
+// / discussion plus the numeric id). Never rendered into prompt context.
+export type ReactionRef = {
+  adapter: AdapterId
+  value: string
+}
+
+// A request to add an emoji reaction to a previously-seen inbound. Distinct
+// from OutboundMessage on purpose: reactions are best-effort side effects, not
+// messages, so they bypass `send()`'s flood guard, per-turn send cap, exact-
+// duplicate guard, sticky-credit grants, and typing heartbeat — all of which
+// are message semantics that would misbehave on a reaction.
+export type ReactionRequest = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread?: string | null
+  reactionRef: ReactionRef
+  // Bare emoji name, no surrounding colons (e.g. 'eyes', '+1'). Each adapter
+  // maps this to its platform's reaction vocabulary and rejects unsupported
+  // names via `code: 'unsupported'`.
+  emoji: string
+}
+
+export type RemoveReactionRequest = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread?: string | null
+  // Per-reaction-instance ref returned by ReactionResult.reactionRef from the
+  // add request, not the inbound message target ref used by ReactionRequest.
+  reactionRef: ReactionRef
+}
+
+export type ReactionErrorCode = 'permission-denied' | 'not-found' | 'unsupported' | 'rate-limited' | 'transient'
+
+export type ReactionResult =
+  // Optional success ref identifies THIS created reaction instance for later
+  // removal, not the original message target. Adapters that cannot remove omit it.
+  { ok: true; reactionRef?: ReactionRef } | { ok: false; error: string; code?: ReactionErrorCode }
+
+export type ReactionCallback = (req: ReactionRequest) => Promise<ReactionResult>
+
+export type RemoveReactionCallback = (req: RemoveReactionRequest) => Promise<ReactionResult>
+
 // File on disk that the agent wants to attach to an outbound message. The
 // agent runs inside a container with /agent bind-mounted from the host;
 // `path` should be an absolute path the container can `readFile`. The

package/src/cli/builtins.ts

@@ -13,6 +13,7 @@ export const BUILTIN_COMMAND_NAMES = [
   'reload',
   'logs',
   'inspect',
+  'dreams',
   'shell',
   'compose',
   'channel',