Cost Tracking -- Budget-Aware Orchestration

Tracks costs per agent and per run, enforces budgets, and selects cost-optimal models.

Model Pricing

Local provider (Ollama)

When models.provider: ollama in .archeflow/config.yaml or ARCHEFLOW_MODEL_PROVIDER=ollama (legacy ARCHFLOW_MODEL_PROVIDER also accepted):

• Record USD 0 for API spend on those runs. Optionally log compute: local in the daily ledger line for transparency.
• Skip cloud budget enforcement for Ollama-backed steps (still respect wall-clock and disk if logging huge artifacts).
• If only some steps use <archeflow-root>/lib/archeflow-ollama.sh and the rest use Claude, split ledger entries by provider per agent.

Prompt caching: 90% discount on cached input tokens. Structure system prompts for cache hits. Batches API: 50% discount. Use for non-time-sensitive bulk ops.

Cost Calculation

cost = (input - cache_read) * input_price/1M
     + cache_read * input_price * 0.10/1M
     + output * output_price/1M

If exact tokens unavailable, estimate: tokens ~= chars / 4. Mark with cost_estimated: true.

Default Model Assignments

Opus is user-opt-in only (team preset model_overrides).

Resolution order: team preset override > domain override > archetype default.

Pre-Agent Cost Estimates

After 10+ runs, use actual averages from metrics.jsonl instead.

Budget Configuration

costs:
  budget_usd: 10.00        # per run; wiggum-check soft-breaks above 95%
  per_agent_usd: 3.00
  daily_usd: 50.00
  warn_at_percent: 75

Team preset budget overrides global config. No budget = unlimited (costs still tracked).

Budget Enforcement

Pre-agent: Estimate cost. If > remaining budget: stop (autonomous) or warn (attended).

Post-agent: Update total. Warn at threshold. Stop if budget exceeded.

Cost Optimization

1. Prompt caching: Stable content first (archetype instructions, voice profiles). Saves 30-50% on input.
2. Guardian fast-path (A2): 0 issues = skip remaining reviewers. Saves $0.30-0.80/cycle.
3. Explorer cache: Reuse recent research. Saves $0.02-0.05/hit.
4. Batches API: For autonomous/overnight review passes (50% discount).
5. Early termination: Clean Guardian + clean Maker self-review = skip remaining cycles.

Daily Cost Tracking

Ledger at .archeflow/costs/<YYYY-MM-DD>.jsonl. One line per run with cost, tokens, models, domain. Daily budget enforcement reads this before starting new runs.