Add task and team budget controls for token, turn, and estimated cost usage

[legreffier]

Summary

Add first-class cost-control for MoltNet task execution using token/turn budgets as the reliable enforcement layer, with optional dollar-cost estimates derived from runtime profile pricing metadata. Team budget is authoritative; task budget can only narrow it.

Desired behavior

• Add task-level budget fields to task creation and task rows: max input tokens, max output tokens, max total tokens, max tool-use turns, and optional max cost.
• Add team-level monthly budget policy. V1 only needs monthly team budgets.
• Runtime profiles should carry provider/model pricing metadata, either user-defined or synced from themolt.net catalogs, but should not own budgets.
• Track usage per attempt and roll it up by team, month, provider/model, and runtime profile when the task declares one.
• Count every task attempt toward team usage. If a task has no declared profile, count tokens from actual attempt provider/model; estimate cost only when pricing metadata is available.
• Enforce the effective cap as the strictest applicable cap: remaining team monthly budget first, then task-level budget.
• When a cap is exceeded, abort/fail the attempt with a specific non-retryable error code such as budget_exceeded, preserving partial usage.

Notes

• Token and turn caps are always enforceable and should be the minimum viable budget system.
• Dollar costs are derived telemetry/enforcement only when pricing metadata exists for the provider/model at execution time.
• Runtime profile pricing catalogs should be syncable so themolt.net-maintained profiles stay current with provider pricing.

Acceptance criteria

• Creating a task with a task budget persists and returns the budget fields.
• Attempt usage increments team monthly usage totals.
• Attempts with declared profiles aggregate usage by profile id.
• Attempts without profiles still count toward team token usage.
• Task execution fails when max turns or token caps are exceeded.
• Remaining team monthly budget takes precedence over a larger task budget.
• Cost estimates are omitted or marked unknown when pricing metadata is unavailable.

[legreffier]

Design & implementation plan — V1: task cost visibility

Scoped down from the full issue after design discussion. This PR delivers the cost/ROI visibility layer only; enforcement and sync are deferred (ledger at bottom). Design decisions are signed in the LeGreffier diary (decision entries on branch issue-1412-task-team-budget-controls).

Why this scope

Tokens and turns already measure task efficiency (shipped in #1550). The missing dimension for ROI is cost — the investment to run a model. V1 makes cost computable and surfaces it in the existing analytics, so value ÷ cost is comparable across models / profiles / months. Enforcement (team caps, runaway abort, budget_exceeded) is a later phase — the issue's own note says token/turn caps are the "minimum viable" enforcement, but visibility must come first to know what to enforce.

Key reality that shaped the design: the server has no live mid-run token/turn visibility — usage is measured client-side by the daemon/runtime and reported once per attempt at /complete into the untyped task_attempts.usage JSONB. So V1 is purely read-side cost derivation over data that already lands.

1. Data model — dated price history (compute-on-read)

New table runtime_model_prices, one row per dated price entry, FK to the existing runtime_models catalog (which already partitions global team_id IS NULL vs team-owned rows):

column	type	notes
id	uuid PK
runtime_model_id	uuid FK → runtime_models.id (cascade)	inherits global/team scope
kind	enum runtime_price_kind	per_token | flat_rate | per_request | unpriced
currency	varchar(3)	ISO 4217; null for unpriced
input_per_1m, output_per_1m	numeric	per_token
cache_read_per_1m, cache_write_per_1m	numeric nullable	per_token, optional
per_call	numeric	per_request
flat_note	text nullable	flat_rate
source	enum runtime_price_source	themoltnet | user (sync-ready)
valid_from	timestamptz NOT NULL	inclusive
valid_to	timestamptz nullable	exclusive; null = current
created_at	timestamptz

Constraints: kind-appropriate column population check; valid_to > valid_from; a no-overlap EXCLUDE USING gist on tstzrange(valid_from, valid_to) per runtime_model_id (custom-SQL migration) so at most one price per model per instant. Index (runtime_model_id, valid_from).

runtime_models is unchanged — pricing lives entirely in the child table, so a model can transition kinds over time and retain history. This mirrors the simonw/llm-prices from_date/to_date model.

2. Cost computation & analytics surfacing

Compute-on-read, no stored dollars. Each attempt has usage (tokens + provider/model) and completed_at:

1. Resolve runtime_models by (provider, model) from usage, team row overrides global.
2. Pick the runtime_model_prices entry where valid_from <= completed_at < COALESCE(valid_to,'infinity').
3. Apply kind: per_token → token math (+ cache rates when present); per_request → per_call; flat_rate / unpriced / no-match → unknown (never a fabricated 0).

Cost is a typed result: {status:'estimated', amount, currency} or {status:'unknown', reason}. Past runs always reflect their run-day price; fixing a mispriced catalog row self-heals history.

Surface by extending the #1550 endpoint, not adding one. GET /tasks/analytics/activity:

• task.repository.ts (summarizeActivityRows / queryActivityAttemptRows, which already read usage + coalesce provider/model) gain the price join + cost accumulation.
• New metric fields on TaskActivityMetricBucket (+ overall): estimatedCost, estimatedCostCurrency, pricedAttemptCount, unpricedAttemptCount — so a rollup with mixed priced/unpriced attempts never implies a total that hides gaps. Mixed currencies reported per-currency, never silently summed.
• Response TypeBox schema in apps/rest-api/src/schemas/tasks.ts extended; clients regenerated.

3. Price seeding & update tooling

Checked-in catalog is the source of truth; llm-prices is a dev-time import only (no deploy/e2e network dependency, no unresolved-license exposure in prod).

• tools/runtime-prices/catalog.json — human-reviewed, llm-prices-superset shape, covers per_token + flat_rate + unpriced (Ollama Cloud stays honest).
• tools/runtime-prices/apply.mjs (Nx tools target) — idempotent upsert of the committed catalog into runtime_model_prices via DATABASE_URL → identical in prod / local / e2e, no network. Reconciliation: unchanged = no-op; newer validFrom closes the open entry (valid_to = new validFrom) + inserts; guarded by the DB no-overlap constraint. --dry-run prints the diff.
• apply.mjs --import-from-llm-prices (dev only) — fetches historical-v1.json, maps their id → (provider, model), merges per-token entries into catalog.json as a reviewable git diff (license reviewed per-diff; flat-rate rows untouched).
• e2e: applies a committed minimal catalog so tasks-analytics.e2e.test.ts cost assertions are deterministic.

4. Error handling & testing

Fail honest, never fabricate — missing model / no price for date / flat_rate / unpriced / missing usage → cost unknown, tokens/turns still reported, no crash. Bad catalog edit → rejected by the exclusion constraint loudly. Import fetch failure → dev-time only, catalog untouched.

Testing (AAA, Vitest): unit cost calc (per_token ±cache, per_request, flat/unpriced/no-model → unknown, temporal boundary inclusive/exclusive, team-override-beats-global) and apply.mjs reconciliation (insert / no-op / price-change / idempotent re-run / dry-run); repository analytics with seeded catalog (cost aggregates + priced/unpriced counts); e2e extends tasks-analytics.e2e.test.ts. Client regen per #1550: generate:openapi, generate:client, go:generate + go:fmt.

Scope ledger

In scope (this PR — V1)	Deferred (follow-up issues)
runtime_model_prices table + constraints/migration	Automated live price-sync pipeline
Cost-on-read temporal join, typed cost result	runtime_profiles → runtime_models FK normalization
Cost fields on GET /tasks/analytics/activity	All enforcement: team monthly cap, runaway per-attempt abort, budget_exceeded (non-retryable, partial usage preserved)
catalog.json + idempotent apply.mjs (+ dev import mode)	Chargeback / attribution reporting
Unit + repository + e2e coverage, client regen	Daemon-side live budget enforcement

Follow-up issues will be filed for the deferred enforcement + sync phases so #1412's later goals aren't lost.