Skip to main content

wednesdayai sessions

List stored conversation sessions. The command reads session data through SQL session storage: it asks the running gateway for the rows (zero direct database access), or — with no gateway running — takes session-storage ownership and reads the configured database in-process. The per-agent sessions.json path is that agent’s store identity; the session index itself lives in the database. See Session Management / Session storage.
Scope selection:
  • default: configured default agent store
  • --agent <id>: one configured agent store
  • --all-agents: aggregate all configured agent stores
  • --store <path>: explicit store path (cannot be combined with --agent or --all-agents). The path must name a configured agent’s session store; an unknown path exits with an error telling you to use --agent.
JSON examples: wednesdayai sessions --all-agents --json:
Each entry in sessions is one session index row. Fields (optional ones may be absent): Notes:
  • modelOverride, providerOverride, and groupActivation come from the session index row, so they appear whenever the underlying entry carries them — both when the listing is served by the gateway (sessions.list) and for a local in-process listing.

Cleanup maintenance

Run maintenance now (instead of waiting for the next write cycle):
wednesdayai sessions cleanup uses session.maintenance settings from config:
  • Scope note: wednesdayai sessions cleanup maintains the session index and retention only. It does not prune cron run logs (cron/runs/<jobId>.jsonl), which are managed by cron.runLog.maxBytes and cron.runLog.keepLines in Cron configuration and explained in Cron maintenance.
  • --dry-run: preview how many entries would be pruned/capped without writing.
    • In text mode, dry-run prints a per-session action table (Action, Key, Age, Model, Flags) so you can see what would be kept vs removed.
  • --enforce: apply maintenance even when session.maintenance.mode is warn.
  • --active-key <key>: treats <key> as the active session. In warn mode, when that key is old enough to prune or falls over the maxEntries cap, the cleanup logs a session maintenance would evict active session warning. With --enforce the key is kept: it is never retired, and the cap is applied to the other rows.
  • --agent <id>: run cleanup for one configured agent store.
  • --all-agents: run cleanup for all configured agent stores.
  • --store <path>: run against a specific agent’s store path. The path must name a configured agent’s session store; an unknown path exits with an error telling you to use --agent. --store cannot be combined with --agent or --all-agents: the conflicting combination is rejected with an error before anything is routed, so the refusal is identical locally and when a gateway owns the store (no request is sent in that case).
  • --fix-missing: accepted for compatibility and does nothing under SQL session storage; the CLI prints --fix-missing has no effect with SQL session storage and will be removed in the next release.
  • --json: print a JSON summary. With --all-agents, output includes one summary per store.
Cleanup only retires session index rows (tombstones): --enforce drops index entries whose updatedAt is older than session.maintenance.pruneAfter (and caps the index at maxEntries). Conversation history is never deleted and stays readable. With the default warn mode it retires nothing. wednesdayai sessions cleanup --all-agents --enforce --dry-run --json:
With --dry-run, pruned and capped are the index keys that would be retired; nothing changes. storePath identifies the agent’s session index; under SQL storage no sessions.json file is read or written.

Claims status

View session consumer claim ledger status — what work is owed, stalled, or dead-lettered:
The command calls the gateway RPC sessions.claims.status. Text output shows:
  • Consumers table: one row per consumer lane — consumer ID, lane, effect kind, enabled flag, and counts by claim status (pending, claimed, processing, dlq).
  • Stalled leases table: expired leases still in claimed/processing state (claim ID, consumer, session, lease-until timestamp).
  • Last sweep timestamp (when the reconciler last ran).
  • Recent events table: last diagnostic events from the in-memory ring buffer (timestamp, kind, consumer, session, count).
--json outputs the raw RPC response:
recentEvents currently carries skipped_backlog events (emitted when a sweep observes a consumer’s watermark transition from disabled to enabled). dlq_terminal events go through the global diagnostic event stream instead, so they appear in logs and diagnostics exports but not in this RPC. Related: Related: