Skip to main content

Command Queue (2026-01-16)

We serialize inbound auto-reply runs (all channels) through a tiny in-process queue to prevent multiple agent runs from colliding, while still allowing safe parallelism across sessions.

Why

  • Auto-reply runs can be expensive (LLM calls) and can collide when multiple inbound messages arrive close together.
  • Serializing avoids competing for shared resources (session files, logs, CLI stdin) and reduces the chance of upstream rate limits.

How it works

  • A lane-aware FIFO queue drains each lane with a configurable concurrency cap (default 1 for unconfigured lanes; main defaults to 4, subagent to 8).
  • runEmbeddedPiAgent enqueues by session key (lane session:<key>) to guarantee only one active run per session.
  • Each session run is then queued into a global lane (main by default) so overall parallelism is capped by agents.defaults.maxConcurrent.
  • When verbose logging is enabled, queued runs emit a short notice if they waited more than ~2s before starting.
  • Typing indicators still fire immediately on enqueue (when supported by the channel) so user experience is unchanged while we wait our turn.

Queue modes (per channel)

Inbound messages can steer the current run, wait for a followup turn, or do both:
  • steer: inject immediately into the current run (cancels pending tool calls after the next tool boundary). If not streaming, falls back to followup.
  • followup: enqueue for the next agent turn after the current run ends.
  • collect: coalesce all queued messages into a single followup turn (default). If messages target different channels/threads, they drain individually to preserve routing.
  • steer-backlog (aka steer+backlog): steer now and preserve the message for a followup turn.
  • interrupt (legacy): abort the active run for that session, then run the newest message.
  • queue (legacy alias): same as steer.
Steer-backlog means you can get a followup response after the steered run, so streaming surfaces can look like duplicates. Prefer collect/steer if you want one response per inbound message. Send /queue collect as a standalone command (per-session) or set messages.queue.byChannel.discord: "collect". Defaults (when unset in config):
  • All surfaces → collect
Configure globally or per channel via messages.queue:

Queue options

Options apply to followup, collect, and steer-backlog (and to steer when it falls back to followup):
  • debounceMs: wait for quiet before starting a followup turn (prevents “continue, continue”).
  • cap: max queued messages per session.
  • drop: overflow policy (old, new, summarize).
Summarize keeps a short bullet list of dropped messages and injects it as a synthetic followup prompt. Each dropped turn is retained with its own run context, so the overflow summary drains with the dropped turns’ own trigger, identity, workspace lane, routing, run id and lifecycle, grouped by those provenance fields — not with the surviving turn’s. A collect batch absorbs only overflow that matches its own run; a system batch (cron/heartbeat) never absorbs the summary of dropped human turns. Defaults: debounceMs: 1000, cap: 20, drop: summarize.

When a followup turn fails

  • A followup turn runs its agent at most once. If the agent run finishes but sending its reply fails, the gateway logs Followup reply failed after the agent run: <error> and does not run the turn again. The run stays recorded as completed. Payloads that reach channel delivery are still retried by the outbound delivery queue.
  • Any other failed followup (for example, one that cannot start its run) is retried once. If the retry also fails, the followup is dropped and the gateway logs followup queue: dropped a follow-up for <session> after its retry failed: <error>.
  • Aborted followups are not retried.
  • Messages queued behind a failed followup still run.

Per-session overrides

  • Send /queue <mode> as a standalone command to store the mode for the current session.
  • Options can be combined: /queue collect debounce:2s cap:25 drop:summarize
  • /queue default or /queue reset clears the session override.

Scope and guarantees

  • Applies to auto-reply agent runs across all inbound channels that use the gateway reply pipeline (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, etc.).
  • Default lane (main) is process-wide for inbound + main heartbeats; set agents.defaults.maxConcurrent to allow multiple sessions in parallel.
  • Additional lanes isolate other work: subagent uses agents.defaults.subagents.maxConcurrent, nested uses agents.defaults.nested.maxConcurrent, and cron uses cron.maxConcurrentRuns.
  • Per-session lanes guarantee that only one agent run touches a given session at a time.
  • No external dependencies or background worker threads; pure TypeScript + promises.

Troubleshooting

Replies arrive late or out of order The queue is draining but a long run is blocking newer messages. Enable verbose logs (wednesdayai gateway run --verbose) and look for queued for …ms lines. Switch to followup mode if the agent’s previous run must finish before the next one starts. Use collect if messages arrive faster than runs complete. Messages are dropped The cap limit was reached and drop: old or drop: new discarded messages. Check your cap setting (agents.defaults.queue.cap); the default is 20. Increase it, or switch drop: summarize to keep a compact summary of dropped messages instead of discarding them. A queued message never got a reply Search the gateway log (wednesdayai logs --follow) for Followup reply failed after the agent run or dropped a follow-up. The first means the agent ran but its reply could not be sent; the turn is not re-run, so resend the message once the channel is healthy. The second means the followup failed twice and was dropped; the error after the colon names the cause. Agent seems stuck and won’t process new messages Check wednesdayai status for a session that is still marked active. A crashed run can leave the per-session lane locked. Restart the gateway to clear in-process state. For persistent issues, check wednesdayai logs --follow for abort or timeout events. /queue <mode> has no effect The command must be sent as a standalone message (nothing else on the line). Inline use (Hi /queue collect) is not detected. Send /queue collect by itself. Cron jobs block inbound replies Cron runs use the dedicated cron lane. If cron work still competes with inbound replies, lower cron.maxConcurrentRuns, raise agents.defaults.maxConcurrent for the main lane, or move expensive cron jobs to a dedicated agent/model so shared host and provider capacity stay predictable. Related: Agent loop · Heartbeat · Configuration reference