Outbox Operator CLI

Inspect, retry, and purge individual entries in the durable outbound queue

Inspect why an agent reply is stuck, retry it after a channel recovers, or drop a genuinely-dead one — one entry at a time.

Quick Start

1. Run an agent bot (writes to the outbox automatically)

   A running gateway bot persists every outbound reply to ~/.praisonai/state/gateway_outbox.sqlite — no code change needed.

   praisonai gateway start --config gateway.yaml

2. Find stuck replies

   praisonai gateway outbox list --status failed

3. Retry one after the channel recovers

   praisonai gateway outbox retry slack:C0abc:msg-d4e5:18

4. Or drop a genuinely-dead one

   praisonai gateway outbox purge telegram:12345:msg-a1b2:17

User interaction flow

An operator moves a stuck reply from failed to delivered without restarting the gateway.

Commands

Four subcommands mounted under praisonai gateway outbox.

$ praisonai gateway outbox list --status failed
Outbox /Users/…/state/gateway_outbox.sqlite — 2 entries (showing 2):
  key=telegram:12345:msg-a1b2:17
      target=telegram:12345 status=permanent_failure attempts=5 age=3200s error=chat not found
  key=slack:C0abc:msg-d4e5:18
      target=slack:C0abc status=failed attempts=2 age=45s error=429 rate limited

$ praisonai gateway outbox retry slack:C0abc:msg-d4e5:18
requeued 1 entry

outbox stats gives an at-a-glance breakdown instead of a single counter:

$ praisonai gateway outbox stats
Outbox /Users/…/state/gateway_outbox.sqlite:
  failed             1
  pending            3
  permanent_failure  2

Clear everything in one shot (asks for confirmation unless --yes):

praisonai gateway outbox purge --all --yes

Where the outbox lives

outbox resolves the SQLite path in a fixed precedence order.

Entry keys

outbox list prints a full tracking key per entry in the form target:idempotency_key:id, e.g. slack:C0abc:msg-d4e5:18. outbox retry and outbox purge consume that key verbatim.

Keys are always printed un-truncated so operators can copy them directly. The key is matched in full against the stored row, so a stale key from another outbox — or a mistyped one — can never mutate the wrong message.

Safe to run alongside a live gateway

All four subcommands — outbox list, outbox stats, outbox retry, outbox purge — open the SQLite store with read_only=True.

read_only=True only skips the sending → recovered crash-recovery migration. Targeted ops still work: retry only touches failed/permanent_failure rows, and purge <key> refuses sending rows. purge --all is an explicit, confirmed operator action and still deletes every row, including sending ones.

Fixed in PraisonAI PR #5954 (issue #5953) — before the fix, retry and purge opened the store read-write and could duplicate a live gateway’s in-flight sends.

Python API

The CLI mirrors four OutboundQueue methods. Wire them from Python directly.

from praisonai_bot.bots import OutboundQueue

# Safe to run alongside a live gateway — no crash recovery runs
outbox = OutboundQueue(
    path="~/.praisonai/state/gateway_outbox.sqlite",
    read_only=True,
)

# Inspection
entries = outbox.list(status="failed", target="slack:C0abc", limit=50)
counts = outbox.stats()  # e.g. {"pending": 3, "permanent_failure": 2}

# Targeted ops still work under read_only=True. retry only touches
# failed/permanent_failure rows; purge_entry refuses to delete a 'sending' row.
await outbox.retry("slack:C0abc:msg-d4e5:18")
outbox.purge_entry("slack:C0abc:msg-d4e5:18")

read_only=True only skips the sending → recovered migration — targeted writes still succeed. Runtime drainers (the gateway itself, DurableAdapterMixin adapters) still open the store read-write and run crash recovery on open; this guidance is for operator code running alongside a live gateway.

list(*, status=None, target=None, limit=100)

Returns — a list of OutboundEntry (newest first). Never mutates state.

Status filter values: pending, sending, recovered, sent, failed, permanent_failure.

stats() -> dict[str, int]

Returns — a per-status count map; only statuses with at least one entry are present.

retry(key) -> bool (async)

Resets a failed/permanent_failure entry back to pending and clears its attempts so the next drain() re-dispatches it. Returns True if requeued, False if the key is unknown, already sent, in-flight (sending), or crash-recovered.

purge_entry(key) -> bool

Deletes a single entry by its full tracking key. Returns True if removed, False on unknown/mismatched key or an in-flight sending entry.

Best Practices

Related