Add oa run --usage PATH so scripts can meter spend

[sgriffiths]

Summary

• Adds oa run --usage PATH, which writes a JSON usage report (leaf task, depends_on chain, and rolled-up total) without changing stdout.
• Closes the gap where --quiet dropped the usage block, so scripts could not meter spend (oa run --quiet drops the usage block, so scripts cannot meter spend #106).
• estimated_cost_usd is included on total only when every contributing block has a cost.

Test plan

• python3 -m pytest tests/test_usage.py tests/test_main.py -q
• oa run --spec .agents/example.yaml --task greet --input '{"name":"Alice"}' --quiet --usage /tmp/usage.json — stdout is task output only; /tmp/usage.json has usage and total
• Confirm a depends_on task's total.total_tokens is leaf + dependency, not leaf-only
• ruff check oas_cli/usage.py oas_cli/main.py oas_cli/ui.py tests/test_usage.py tests/test_main.py
• ruff format --check oas_cli/usage.py oas_cli/main.py oas_cli/ui.py tests/test_usage.py tests/test_main.py

Closes #106

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
open-agent-spec	Ready	Preview	Aug 30, 2026 3:30am

[aswhitehouse]

The implementation matches #106 well: quiet stdout remains unchanged, dependency usage is included in the rolled-up total, partial cost totals are avoided, the focused tests pass, and Ruff is clean.

One blocking issue before merge: CI currently fails in the Mypy step. In oas_cli/usage.py, costs remains typed as list[Any | None]; the all(isinstance(c, (int, float)) for c in costs) check does not narrow the list for the following sum(float(c) for c in costs). Mypy reports both an incompatible generator item type and an incompatible argument to float at line 184.

Please build a separately narrowed numeric list (and only sum it when its length matches costs) or otherwise make the narrowing explicit, then rerun Mypy. The branch should also be updated from current main before the final CI run.