Report per-lane cost and run spend in --json and transcripts (#79), v1.3.0

[CryptoJones]

Closes #79

What

• Every result has a cost. It is a dollar amount when the lane was priced and returned usage, 0.0 when the lane is free or on a subscription, and null when the cost is unknown (an unpriced model, or no usage returned). Before, the field was missing unless the lane was priced, so a caller couldn't tell a free lane from an unknown one.
• A new spend object, {actual, estimated_worst_case, budget, unpriced}, in --diff --json, --discuss --json, --synthesize --json and every transcript. actual includes the --diff readers. If unpriced names any lanes, actual is a lower bound, not the bill.
• --diff and --synthesize now print the human spend: line, which they used to drop.
• The README Cost section documents the new fields.

The one judgement call

Plain --json, with no --diff or --discuss, prints a bare list, so a top-level key can't be added without changing the shape and breaking any caller that indexes it. That form keeps its shape. Each result's cost makes the total a one-liner: jq 'map(.cost // 0) | add'. The object form is filed as #131 for a 2.0 release and added to BACKLOG.md.

The version goes from 1.2.0 to 1.3.0, a minor bump because the change only adds fields.

Verification

• New end-to-end tests cover:
  • cost for a paid, a free and an unpriced lane (0.3 / 0.0 / null);
  • --diff --json spend that includes the readers;
  • the unpriced list;
  • the --diff spend line;
  • spend in the transcript and in --synthesize --json.
• Full suite: 258 tests OK, 0 ResourceWarnings.

🤖 Generated with Claude Code

https://claude.ai/code/session_015eWZfxrGjWj2QpwdgFwBjR

Proudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 15f45b0c-e6df-40a7-a1a5-2baad8af18e1

📥 Commits

Reviewing files that changed from the base of the PR and between aaac5f4 and f5f2d24.

📒 Files selected for processing (4)

• BACKLOG.md
• README.md
• roundtable
• tests/test_roundtable.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (4)

• GitHub Check: test (3.11)
• GitHub Check: test (3.14)
• GitHub Check: test (3.13)
• GitHub Check: test (3.12)

🔇 Additional comments (4)

roundtable (1)

100-100: LGTM!

Also applies to: 343-363, 3397-3409, 4021-4036, 4138-4156

tests/test_roundtable.py (1)

2711-2764: LGTM!

Also applies to: 3233-3247

README.md (1)

241-253: LGTM!

BACKLOG.md (1)

87-93: LGTM!

---

📝 Summary

Summary by CodeRabbit

• New Features
  • JSON results now include per-lane costs: a dollar amount for priced usage, 0.0 for known free usage, or null when the cost is unknown.
  • Diff, discussion, and synthesis JSON output and saved transcripts now include run-level spending details, including actual spend, estimated worst-case spend, budget, and unpriced lanes.
  • Text synthesis output now reports actual and estimated spend.
• Documentation
  • Updated the README to explain cost reporting and clarify that plain --json remains a list of results.

Walkthrough

The release adds per-result cost values and run-level spend reports to JSON, diff, synthesis, transcript, and text outputs. Transcripts can store spend data. The README documents output shapes, and the backlog records completion of #79 and a deferred breaking change for plain --json.

Changes

Spend reporting

Layer / File(s)	Summary
Per-result cost values roundtable, tests/test_roundtable.py	The new helpers assign costs to results. Priced results receive their calculated cost, free or subscription-priced results receive 0.0, and results with unknown prices receive null.
Run spend outputs and transcripts roundtable, tests/test_roundtable.py, README.md, BACKLOG.md	Synthesis and final run outputs include spend details in JSON and text output. Transcripts can store the spend report. Tests and documentation describe spend fields, and the backlog records the completed reporting item and a proposed breaking change to plain --json.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant FinalRun
  participant fill_costs
  participant spend_report
  participant save
  participant JSONOutput
  FinalRun->>fill_costs: Assign per-result cost values
  FinalRun->>spend_report: Build run spend details
  FinalRun->>save: Save results and spend report
  FinalRun->>JSONOutput: Include results and spend report

Loading

Merge Risk: ⚪ Minimal · up to f5f2d

No confirmed spend-reporting issue blocks merging.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	Issue #79 requires a top-level spend object in --json. The PR adds per-result cost and adds spend to --diff --json, --discuss --json, --synthesize --json, and transcripts, but plain `--j…	Add the required run-level spend object to plain --json output, with automated test coverage. If preserving the bare-list shape remains necessary, resolve that requirement with the issue owner rather than treating the deferral as comple…
Docstring Coverage	⚠️ Warning	Docstring coverage is 44.44% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 1 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: per-lane cost and run-spend reporting in JSON and transcripts. The version suffix adds minor detail but does not make the title unclear.
Description check	✅ Passed	The description explains the cost fields, spend reporting, JSON compatibility decision, documentation, and tests. It is directly related to the changeset.
Out of Scope Changes check	✅ Passed	The reported changes implement Issue #79's cost and spend reporting objectives. The README updates document those fields, the tests cover the reporting behavior, and the backlog note records the relat…

Full details: Linked Issues check

Explanation

Issue #79 requires a top-level spend object in --json. The PR adds per-result cost and adds spend to --diff --json, --discuss --json, --synthesize --json, and transcripts, but plain --json remains a bare list. The stated compatibility decision and deferral to #131 do not satisfy this active requirement. The PR summary reports tests for per-lane costs, diff spend, reader costs, and spend in transcripts and synthesis output.

Resolution

Add the required run-level spend object to plain --json output, with automated test coverage. If preserving the bare-list shape remains necessary, resolve that requirement with the issue owner rather than treating the deferral as completion.

Full details: Docstring Coverage

Explanation

Docstring coverage is 44.44% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 1 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}