operate-pi-dispatch

Operating pi-dispatch

pi-dispatch is a queue that runs paid autonomous agent jobs. The admin extension exposes tools to observe and operate a deployment. Some tools only read; some turn processing on and off; some change money-affecting configuration and are gated behind a human confirmation.

The tools

Observe (no approval needed):

• dispatch_status — queue/worker state, today's budget, settings overlay, schedulers.
• dispatch_runs — recent run records (PII-free). Raw job logs are never available to tools.
• dispatch_costs — cost analytics folded from the run history: window totals (window = 7d/30d/mtd), daily buckets, per-flow and per-model rollups, subscription plan verdicts, provenance (flow filters to one flow). Every dollar in the result is typed { usd, class, ... } — quote the class with the number (metered is measured, estimated/seeded are not), and never present an estimate as an exact spend. The operator sees the same fold drawn as charts on the insights page (/dispatch insights [7d|30d|mtd] writes and opens it), and /dispatch insights whatif <provider/model> --flow <flow> estimates what a flow would cost per run on another model's rates.
• dispatch_triggers — the configured triggers with their array index (needed to edit/delete one).

Control (no approval needed — reversible and money-safe):

• dispatch_pause — stop starting new jobs (running ones finish). This is "turn dispatch off".
• dispatch_resume — re-enable processing. This is "turn dispatch on".

Start a run (paid, already gated producer-side):

• dispatch_run — enqueue one agent run against an allowlisted local folder.

The human confirm gates — how to use them

These tools change money-affecting configuration and each one asks the operator to approve a confirmation dialog before it takes effect:

• dispatch_set — change a limit/setting (e.g. dailyCap, weeklyCap, maxTurns, model). Omit value to unset.
• dispatch_trigger_add / dispatch_trigger_edit / dispatch_trigger_delete — manage triggers.
• dispatch_pause_add / dispatch_pause_edit / dispatch_pause_delete — manage scheduled pause windows (per folder/repo "quiet hours": runs for a scope are deferred between certain times and auto-resume after; dispatch_pauses lists them with their index). dispatch_pause_edit is a partial change — pass the index plus only the fields to alter. Deferring never drops a job and costs no budget.
• dispatch_waits — list the jobs the worker is HOLDING on a trigger's run.waitFor condition: job id, an id-only target, the operator's own words for what it waits on, and how long it has waited. Different from the queue's delayed count, which also mixes cron next-occurrences, retry backoff and quiet hours.
• dispatch_wait_cancel — remove a held job so it never runs (confirm-gated). It is the only lever that reaches one: a held job has spent nothing, so no budget cap will ever refuse it, and deleting the trigger does not reach a job already enqueued.
• dispatch_limit_add / dispatch_limit_edit / dispatch_limit_delete — manage scoped limits (per repo/folder budget caps and concurrency: day/week/month job-count caps refuse a job pre-spend with reason scope-cap, never retried; concurrent defers the excess, never drops it; dispatch_limits lists them with their index and used counts). dispatch_limit_edit is a partial change — pass the index plus only the fields to alter. Scopes match exactly (a repo owner/name or an ABSOLUTE folder path, no globs).