Channels/Messaging — Message Processing Pipeline

Reactions Typing State Machine TTL Safety

Architecture

flowchart TD
    subgraph AckReactions["Ack Reactions"]
        SCOPE["AckReactionScope"]
        GATE["shouldAckReaction()"]
        WAGATE["shouldAckReactionForWhatsApp()"]
    end
    subgraph StatusReactions["Status Reactions"]
        CTRL["StatusReactionController"]
        EMOJIS["StatusReactionEmojis"]
        TIMING["StatusReactionTiming"]
        DEBOUNCE["Debounce Timer"]
        STALL["Stall Timers"]
    end
    subgraph Typing["Typing Indicators"]
        CALLBACKS["TypingCallbacks"]
        GUARD["TypingStartGuard"]
        KEEPALIVE["KeepaliveLoop"]
        TTL["TTL Safety Timer"]
    end

    SCOPE --> GATE
    GATE --> CTRL
    EMOJIS --> CTRL
    TIMING --> CTRL
    CTRL --> DEBOUNCE
    CTRL --> STALL
    CALLBACKS --> GUARD
    CALLBACKS --> KEEPALIVE
    CALLBACKS --> TTL

Acknowledgement Reactions

Ack reactions confirm that the agent received a message. The scope determines when reactions appear:

export function shouldAckReaction(params: AckReactionGateParams): boolean {
  const scope = params.scope ?? "group-mentions";
  if (scope === "off" || scope === "none") return false;
  if (scope === "all") return true;
  if (scope === "direct") return params.isDirect;
  if (scope === "group-all") return params.isGroup;
  if (scope === "group-mentions") {
    if (!params.isMentionableGroup) return false;
    if (!params.requireMention) return false;
    if (!params.canDetectMention) return false;
    return params.effectiveWasMentioned || params.shouldBypassMention === true;
  }
  return false;
}

Status Reaction State Machine

The status reaction controller provides visual agent state via emoji reactions. Each state transition is debounced, stall timers detect long-running tasks, and terminal states fire immediately.

Default Emoji Map

stateDiagram-v2
    [*] --> queued
    queued --> thinking : Agent starts processing
    thinking --> tool : Tool invoked
    tool --> thinking : Tool returns
    thinking --> coding : Code exec tool
    coding --> thinking : Code complete
    thinking --> web : Web tool
    web --> thinking : Web returns
    thinking --> compacting : Context overflow
    compacting --> thinking : Compaction done
    thinking --> done : Reply ready
    tool --> done : Reply ready
    thinking --> error : Failure
    tool --> error : Failure
    thinking --> stallSoft : 10s elapsed
    stallSoft --> stallHard : 30s elapsed
    stallSoft --> done : Reply ready
    stallHard --> done : Reply ready
    done --> [*]
    error --> [*]

Timing Defaults

Typing Indicators

The typing system provides reliable typing indicator management with three safety layers:

1. Start guard — Tracks consecutive failures, trips the keepalive loop after N failures (default 2)
2. Keepalive loop — Fires start() every 3s to refresh the typing indicator
3. TTL safety — Auto-stops typing after 60s maximum duration

export function createTypingCallbacks(params: {
  start: () => Promise<void>;
  stop?: () => Promise<void>;
  onStartError: (err: unknown) => void;
  keepaliveIntervalMs?: number;      // Default: 3000
  maxConsecutiveFailures?: number;    // Default: 2
  maxDurationMs?: number;            // Default: 60000
}): TypingCallbacks

Tool-Specific Emoji Resolution

When a tool is invoked, the controller resolves the appropriate emoji based on tool name tokens:

Focus Deep-Dives