> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Queue

# 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`:

```json5 theme={"dark"}
{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}
```

## 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](https://docs.wednesdayai.dev/admin/gateway/outbound-delivery.md).
* 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](https://docs.wednesdayai.dev/next/developers/concepts/agent-loop.md) · [Heartbeat](https://docs.wednesdayai.dev/next/admin/gateway/heartbeat.md) · [Configuration reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.