typeclaw 0.18.0 → 0.20.0

package/src/channels/router.ts

@@ -7,13 +7,21 @@ import { createSession, renderTurnRoleAnchor, renderTurnTimeAnchor, type AgentSe
 import { subscribeProviderErrors } from '@/agent/provider-error'
 import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
 import { renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
-import { createCommandRegistry } from '@/commands'
+import { type Command, type CommandResult, createCommandRegistry } from '@/commands'
 import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
 import type { HookBus } from '@/plugin'
 import { extractClaimCode } from '@/role-claim'
 import type { Stream } from '@/stream'
 
-import { decideEngagement, grantStickyForReplyTargets, StickyLedger, type EngagementDecision } from './engagement'
+import { formatChannelCommandHelp } from './commands'
+import {
+  countEffectiveHumans,
+  decideEngagement,
+  grantStickyForReplyTargets,
+  isMultiHumanGroup,
+  StickyLedger,
+  type EngagementDecision,
+} from './engagement'
 import {
   MEMBERSHIP_COLD_FETCH_TIMEOUT_MS,
   type MembershipCount,
@@ -46,6 +54,10 @@ import type {
   OutboundCallback,
   OutboundMessage,
   QuoteAnchorSource,
+  ReactionCallback,
+  ReactionRef,
+  ReactionRequest,
+  ReactionResult,
   ResolvedChannelNames,
   SendErrorCode,
   SendResult,
@@ -100,6 +112,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
@@ -268,6 +281,7 @@ type QueuedInbound = {
   authorName: string
   authorIsBot: boolean
   externalMessageId: string
+  reactionRef?: ReactionRef
   isBotMention: boolean
   replyToBotMessageId: string | null
   isDm: boolean
@@ -316,6 +330,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
@@ -326,6 +348,11 @@ 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
   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
@@ -429,6 +456,10 @@ type LiveSession = {
   recentEngagedPeerBotTurns: { authorId: string; ts: number }[]
   consecutiveEngagedPeerBotTurns: number
   loopGuardActive: boolean
+  // Set in route() from the same membership+participants the engagement
+  // decision used, so the prompt nudge and sticky suppression agree on
+  // "is this a multi-human group". Read by composeTurnPrompt().
+  multiHumanGroup: boolean
   membershipFetch: Promise<MembershipCount | null> | null
   destroyed: boolean
   unsubProviderErrors: (() => void) | null
@@ -439,14 +470,16 @@ type LiveSession = {
 // pipeline (e.g. Discord native slash commands fired from listener.on
 // ('interaction_create')). Handlers that need a real inbound — for some
 // future hypothetical command like `/quote` — must guard on event !== null
-// instead of assuming it.
+// instead of assuming it. `live` is null for session-less commands
+// (requiresLiveSession:false, e.g. /help); session-control handlers run only
+// after the dispatch layer has resolved a live session, so they may assert it.
 type ChannelCommandContext = {
-  live: LiveSession
+  live: LiveSession | null
   event: InboundMessage | null
 }
 
 export type ExecuteCommandResult =
-  | { kind: 'handled'; name: string }
+  | { kind: 'handled'; name: string; reply?: string }
   | { kind: 'unknown-command'; name: string }
   | { kind: 'no-live-session' }
   | { kind: 'permission-denied' }
@@ -497,6 +530,14 @@ 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>
   registerTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
   unregisterTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
   registerChannelNameResolver: (adapter: ChannelKey['adapter'], resolver: ChannelNameResolver) => void
@@ -689,6 +730,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: () => {},
 }
@@ -714,6 +756,7 @@ 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 typingCallbacks = new Map<ChannelKey['adapter'], Set<TypingCallback>>()
   const channelNameResolvers = new Map<ChannelKey['adapter'], Set<ChannelNameResolver>>()
   const membershipResolvers = new Map<ChannelKey['adapter'], Set<MembershipResolver>>()
@@ -721,14 +764,31 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const historyCallbacks = new Map<ChannelKey['adapter'], Set<HistoryCallback>>()
   const fetchAttachmentCallbacks = new Map<ChannelKey['adapter'], Set<FetchAttachmentCallback>>()
   const stickyLedger = new StickyLedger()
-  const commands = createCommandRegistry<ChannelCommandContext>([
+  // The /help handler reads the live registry to enumerate commands, so it
+  // forward-references `commands`. Safe at runtime — the handler only runs on
+  // invocation, long after the assignment below completes.
+  const channelCommands: readonly Command<ChannelCommandContext>[] = [
+    {
+      name: 'help',
+      description: 'List available commands.',
+      permission: 'none',
+      requiresLiveSession: false,
+      handler: () => ({ reply: formatChannelCommandHelp(commands.list()) }),
+    },
     {
       name: 'stop',
+      description: 'Stop the current agent turn in this channel.',
+      permission: 'session.control',
+      requiresLiveSession: true,
       handler: async ({ live }) => {
-        await stopCurrentChannelTurn(live)
+        // requiresLiveSession:true guarantees the dispatch layer resolved a
+        // session before running this handler, so `live` is non-null here.
+        await stopCurrentChannelTurn(live!)
+        return { reply: 'Stopped the current turn.' }
       },
     },
-  ])
+  ]
+  const commands = createCommandRegistry<ChannelCommandContext>(channelCommands)
 
   // Implicit dir-name alias: agent folder basename matches Docker
   // container name (per AGENTS.md), the typical Discord/Slack bot
@@ -1050,6 +1110,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         promptQueue: [],
         pendingSystemReminders: [],
         contextBuffer: [],
+        currentTurnAttachments: [],
         draining: false,
         debounceTimer: null,
         typingTimer: null,
@@ -1060,6 +1121,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         firstUnprocessedAt: 0,
         currentTurnAuthorId: null,
         currentTurnAuthorIds: new Set(),
+        currentTurnReactionRef: null,
         // `lastTurnAuthorId` (string, used for `lastInboundAuthorId` in
         // origin) and `lastTurnAuthorIds` (Set, used by
         // `grantStickyForReplyTargets` as the fallback when
@@ -1086,6 +1148,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         recentEngagedPeerBotTurns: [],
         consecutiveEngagedPeerBotTurns: 0,
         loopGuardActive: false,
+        multiHumanGroup: false,
         membershipFetch,
         destroyed: false,
         unsubProviderErrors: null,
@@ -1419,6 +1482,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 } : {}),
     }
@@ -1462,10 +1526,12 @@ 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.consecutiveSends.clear()
           live.lastSentText.clear()
           live.pendingQuoteCandidate = captureQuoteCandidate(live.key.adapter, batch, observed)
@@ -1499,6 +1565,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         const text = composeTurnPrompt(observed, batch, {
           adapter: live.key.adapter,
           loopGuardActive: live.loopGuardActive,
+          groupChatNudge: live.multiHumanGroup,
           systemReminders: reminders,
           role: liveRole,
         })
@@ -1535,6 +1602,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       live.draining = false
       live.currentTurnAuthorId = null
       live.currentTurnAuthorIds = new Set()
+      live.currentTurnReactionRef = null
+      live.currentTurnAttachments = []
       await stopTypingHeartbeat(live)
     }
   }
@@ -1603,6 +1672,28 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  // Executes a parsed channel command and posts its reply (if any) back to the
+  // originating channel. Shared by the pre-gate public-command fast path and the
+  // post-gate command block so the execute→reply shape can't drift between them.
+  // Gating (channel.respond / session.control) and live-session resolution stay
+  // at the call sites — this helper only runs the handler and delivers the reply.
+  const runChannelCommand = async (event: InboundMessage, live: LiveSession | null): Promise<CommandResult> => {
+    const result = await commands.execute(event.text, { live, event })
+    if (result.kind === 'handled' && result.reply !== undefined) {
+      await send(
+        {
+          adapter: event.adapter,
+          workspace: event.workspace,
+          chat: event.chat,
+          thread: event.thread,
+          text: result.reply,
+        },
+        { source: 'system' },
+      )
+    }
+    return result
+  }
+
   const route = async (event: InboundMessage): Promise<void> => {
     const adapterConfig = options.configForAdapter(event.adapter)
     if (!adapterConfig) return
@@ -1650,6 +1741,25 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       }
     }
 
+    // Parse once, here, so the public-command fast path (below) and the
+    // post-gate command block share one parse and lookup.
+    const parsedCommand = commands.parse(event.text)
+    const commandInfo = parsedCommand === null ? undefined : commands.get(parsedCommand.name)
+
+    // Public-command fast path: a known command that is both ungated
+    // (permission:'none') AND informational (requiresLiveSession:false) runs
+    // BEFORE the channel.respond gate, mirroring the native-slash path where
+    // such commands skip permissions entirely. Both conditions are required so
+    // a future "public but live-session-aware" command can't silently bypass
+    // the gate. It only reveals already-public command names — it never creates
+    // a session or prompts the agent — so it is not a channel.respond bypass in
+    // any meaningful sense. Unknown commands, /stop, //escaped text, and plain
+    // messages all fall through to the gate unchanged.
+    if (parsedCommand !== null && commandInfo?.permission === 'none' && !commandInfo.requiresLiveSession) {
+      await runChannelCommand(event, null)
+      return
+    }
+
     if (isChannelRespondDenied(event)) {
       publishInbound(event, 'denied')
       logger.info(
@@ -1658,27 +1768,31 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
-    const parsedCommand = commands.parse(event.text)
     if (parsedCommand !== null) {
       // Commands are control traffic, not engaged inbounds; if the session is stale,
       // the next engaged inbound will perform the rollover before prompting.
       const keyId = channelKeyId(key)
-      if (!commands.has(parsedCommand.name)) {
+      if (commandInfo === undefined) {
         logger.info(`[channels] ${keyId}: ignoring unknown command /${parsedCommand.name}`)
         return
       }
-      if (isSessionControlDenied(event)) {
+      if (commandInfo.permission === 'session.control' && isSessionControlDenied(event)) {
         logger.info(
           `[channels] ${keyId}: denied command /${parsedCommand.name} by permissions (session.control) author=${event.authorId}`,
         )
         return
       }
-      const existingLive = liveSessions.get(keyId)
-      if (!existingLive || existingLive.destroyed) {
-        logger.info(`[channels] ${keyId}: ignoring command /${parsedCommand.name} with no live session`)
-        return
+      // Session-less commands (e.g. /help) are informational and run without a
+      // live session; their handler reply is posted straight back to the channel.
+      let existingLive: LiveSession | null = null
+      if (commandInfo.requiresLiveSession) {
+        existingLive = liveSessions.get(keyId) ?? null
+        if (existingLive === null || existingLive.destroyed) {
+          logger.info(`[channels] ${keyId}: ignoring command /${parsedCommand.name} with no live session`)
+          return
+        }
       }
-      const commandResult = await commands.execute(event.text, { live: existingLive, event })
+      const commandResult = await runChannelCommand(event, existingLive)
       if (commandResult.kind !== 'not-command') return
     }
 
@@ -1712,6 +1826,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     const membership = await membershipForEngagement(live)
 
+    live.multiHumanGroup = isMultiHumanGroup(event.isDm, countEffectiveHumans(live.participants, membership, now()))
+
     const decision: EngagementDecision = decideEngagement({
       message: event,
       config: adapterConfig.engagement,
@@ -1736,6 +1852,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     publishInbound(event, 'engage', live.sessionId)
 
+    autoReactOnEngage(event)
+
     updateLoopGuard(live, event)
 
     enqueue(live, event)
@@ -1828,6 +1946,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       authorName: event.authorName,
       authorIsBot: event.authorIsBot,
       externalMessageId: event.externalMessageId,
+      ...(event.reactionRef !== undefined ? { reactionRef: event.reactionRef } : {}),
       isBotMention: event.isBotMention,
       replyToBotMessageId: event.replyToBotMessageId,
       isDm: event.isDm,
@@ -1845,6 +1964,69 @@ 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 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' }
+  }
+
+  // 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): void => {
+    if (event.reactionRef === undefined) return
+    void react({
+      adapter: event.adapter,
+      workspace: event.workspace,
+      chat: event.chat,
+      thread: event.thread,
+      reactionRef: event.reactionRef,
+      emoji: ENGAGE_REACTION_EMOJI,
+    })
+      .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)}`)
+      })
+  }
+
   const unregisterOutbound = (adapter: ChannelKey['adapter'], cb: OutboundCallback): void => {
     outboundCallbacks.get(adapter)?.delete(cb)
   }
@@ -1978,9 +2160,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,
@@ -1988,8 +2175,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
@@ -1999,6 +2186,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)
     }
@@ -2416,38 +2604,49 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     options: ExecuteCommandOptions,
   ): Promise<ExecuteCommandResult> => {
     const lowered = name.toLowerCase()
-    if (!commands.has(lowered)) {
+    const commandInfo = commands.get(lowered)
+    if (commandInfo === undefined) {
       return { kind: 'unknown-command', name: lowered }
     }
     // Gates on session.control (not channel.respond) so a respond-capable
     // guest cannot abort another speaker's turn. Runs BEFORE the live-session
     // lookup so an unauthorized invoker gets 'permission-denied' regardless of
     // session state, rather than leaking session presence via the
-    // 'no-live-session' vs 'permission-denied' distinction.
-    const partial: SessionOrigin = {
-      kind: 'channel',
-      adapter: key.adapter,
-      workspace: key.workspace,
-      chat: key.chat,
-      thread: key.thread,
-      lastInboundAuthorId: options.invokerId,
-    }
-    if (!permissions.has(partial, CORE_PERMISSIONS.sessionControl)) {
-      return { kind: 'permission-denied' }
-    }
-    const resolved = resolveLiveSessionForCommand(liveSessions, key)
-    if (resolved.kind === 'none') {
-      return { kind: 'no-live-session' }
+    // 'no-live-session' vs 'permission-denied' distinction. Session-less
+    // informational commands (e.g. /help) declare permission:'none' and skip
+    // both the gate and the lookup so they work in channels with no live turn.
+    if (commandInfo.permission === 'session.control') {
+      const partial: SessionOrigin = {
+        kind: 'channel',
+        adapter: key.adapter,
+        workspace: key.workspace,
+        chat: key.chat,
+        thread: key.thread,
+        lastInboundAuthorId: options.invokerId,
+      }
+      if (!permissions.has(partial, CORE_PERMISSIONS.sessionControl)) {
+        return { kind: 'permission-denied' }
+      }
     }
-    if (resolved.kind === 'ambiguous') {
-      return { kind: 'ambiguous', matchCount: resolved.count }
+    let live: LiveSession | null = null
+    if (commandInfo.requiresLiveSession) {
+      const resolved = resolveLiveSessionForCommand(liveSessions, key)
+      if (resolved.kind === 'none') {
+        return { kind: 'no-live-session' }
+      }
+      if (resolved.kind === 'ambiguous') {
+        return { kind: 'ambiguous', matchCount: resolved.count }
+      }
+      live = resolved.session
     }
-    const result = await commands.execute(`/${lowered}`, { live: resolved.session, event: null })
+    const result = await commands.execute(`/${lowered}`, { live, event: null })
     if (result.kind === 'handled') {
-      return { kind: 'handled', name: result.name }
+      return result.reply !== undefined
+        ? { kind: 'handled', name: result.name, reply: result.reply }
+        : { kind: 'handled', name: result.name }
     }
     // commands.execute can only return not-command (impossible — we pass a
-    // leading slash), unknown-command (impossible — we just checked has()),
+    // leading slash), unknown-command (impossible — we just checked get()),
     // or handled. Any other outcome is a bug.
     return { kind: 'unknown-command', name: lowered }
   }
@@ -2526,6 +2725,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     getSendRate,
     registerOutbound,
     unregisterOutbound,
+    registerReaction,
+    unregisterReaction,
+    react,
     registerTyping,
     unregisterTyping,
     registerChannelNameResolver,
@@ -2610,12 +2812,31 @@ 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[],
   state: {
     adapter?: AdapterId
     loopGuardActive: boolean
+    groupChatNudge?: boolean
     systemReminders?: readonly string[]
     now?: Date
     role?: string
@@ -2689,6 +2910,38 @@ function composeTurnPrompt(
       '',
     )
   }
+  // Group-chat nudge: same SYSTEM MESSAGE convention as the loop guard. We
+  // 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(
+      '---',
+      '**[SYSTEM MESSAGE — not from a human]**',
+      '',
+      'You are in a group chat with multiple people. This is an automated',
+      'signal from the channel router, not a message from anyone in the chat.',
+      '**Do not acknowledge or reply to this notice.**',
+      '',
+      'You are woken on every message from someone you recently talked with, so',
+      'most turns you should stay quiet. 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).',
+      '',
+      'Otherwise — chatter between others, 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.',
+      '',
+      '---',
+      '',
+    )
+  }
   if (observed.length > 0) {
     parts.push('## Recent context (not addressed to you, for awareness only)')
     for (const o of observed) {

package/src/channels/types.ts

@@ -94,8 +94,50 @@ 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 ReactionErrorCode = 'permission-denied' | 'not-found' | 'unsupported' | 'rate-limited' | 'transient'
+
+export type ReactionResult = { ok: true } | { ok: false; error: string; code?: ReactionErrorCode }
+
+export type ReactionCallback = (req: ReactionRequest) => 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/inspect.ts

@@ -75,6 +75,9 @@ export const inspectCommand = defineCommand({
           if (escListener === null) return new AbortController().signal
           return escListener.armForStream()
         },
+        afterEscStream: () => {
+          escListener?.pause()
+        },
         ...(liveHint !== undefined ? { liveHint } : {}),
         stdout: (line) => process.stdout.write(`${line}\n`),
         stderr: (line) => process.stderr.write(`${line}\n`),