---
kind: task
slug: cost-budget-ui-and-caps
title: Cost visibility and dispatch budget caps
plan_slug: automation-foundation
epic_slug: model-provider-registry
status: draft
priority: P2
tenant_id: global
owner: unassigned
cursor_todo_id: null
updated_at: "2026-08-03"
---

# Task summary

Surface spend from `convoy_events.estimated_cost_usd` and `agent_runs` token metadata; add optional workspace budget caps that pause orchestrator dispatch when exceeded.

## Description

**Benchmark:** Autensa per-task/product cost tracking and daily/monthly budget caps. Epic 1 deferred billing — this follow-on uses data already on `convoy_events` and run completion.

### Read path (UI)

- Settings → AI → **Usage & budgets**
- Rollups: today / this month by `model_alias`, by convoy, by role
- Mission control convoy detail: spend to date for selected convoy

### Write path (enforcement)

- `workspace_budget_caps` table: `period` (`daily` | `monthly`), `cap_usd`, `action` (`pause_dispatch` | `warn_only`)
- Orchestrator tick: sum `estimated_cost_usd` for period; if over cap and `pause_dispatch`, skip new `role_dispatch` enqueue and write health event

### Cost estimation

- Worker/orchestrator populate `estimated_cost_usd` on `convoy_events.role_complete` using provider-reported usage × static price table in shared config (v1 — no live pricing API)

## Dependencies

- Epic 1 model registry + `convoy_events` cost column (shipped)
- Epic 7 worker records token totals on complete

## Subtasks

- [ ] Price table stub in `packages/shared` (document as operator-editable later)
- [ ] tRPC usage queries (workspace-scoped aggregates)
- [ ] Settings usage page
- [ ] Budget cap schema + orchestrator guard

## Estimation

M

## Acceptance criteria

- [ ] Settings shows month-to-date spend grouped by model alias
- [ ] With cap set and exceeded, orchestrator logs skip reason and does not enqueue new jobs
- [ ] Warn-only cap emits event but does not block dispatch

## Links

- Epic: `./Epic-model-provider-registry.md`
- Unblocks: Epic 9 fleet spend rollup