blackbox-bill 0.2.0__tar.gz

blackbox_bill-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blackbox_bill-0.2.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: blackbox-bill
+Version: 0.2.0
+Summary: Explain where your AI-coding-tool money went: billing black-box explainer with tokenizer-aware per-project and subagent cost attribution
+Author: hao li
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# blackbox-bill
+
+**Explain where your AI-coding-tool money went.** A stdlib-only Python CLI that reads your Cursor billing export and your local session logs, then tells you — in plain English — why your bill looks the way it does. v2 adds tokenizer-aware cost attribution: per-project breakdowns and subagent token share, straight from your `~/.claude/projects` transcripts.
+
+No network. No API keys. Deterministic: every explanation cites the exact rows it was computed from.
+
+## The problem
+
+Cursor's billing pools confuse everyone:
+
+- u/josh3com on r/ClaudeCode: *"CURSOR TEAM PLEASE HELP - Cursor support keeps telling me my 100% full usage pool is from grok bot two months in a row"* — Grok Bot spend kept landing in "Other Models" with no explanation in the app.
+- u/FerretValuable9718: *"Why is the 'Other Models' usage being used so much with so little time?"* — screenshot showed **Other Models 100% used while Cursor Models sat at 16%**.
+- r/AI_Agents: *"My coding agent hit a cold-start 503, found a Gemini key in my repo, and burned $40 while I slept"* — spend routed to a provider the user never intended.
+- dev.to: *"$402 on one ticket"* in headless Claude Code — *"nothing in the app said so"*, so the author built manual bookkeeping.
+- r/ClaudeCode, October 2026: Fable 5.1 requests silently served by 5.5 — the model on the invoice doesn't match the model you asked for.
+
+Forums are full of people doing billing archaeology by hand. blackbox-bill automates the archaeology.
+
+## What it does
+
+```
+blackbox-bill --csv cursor-export.csv
+```
+
+Given a Cursor billing export CSV (columns vary — the parser is deliberately liberal), it prints:
+
+1. **Pool-normalized summary** — first-party Cursor pool vs "Other Models" pool vs API-key spend, per model, per day. Free-form pool labels are normalized to the three canonical pools; unrecognized labels are reported as `unknown`, never silently dropped.
+2. **Tokenizer-aware token figures** — every token total is shown in both tokenizer equivalents (`--tokenizer legacy|claude-4.7`, `--tokenizer-factor` to override the default 1.3 ratio). Claude 4.7+'s new tokenizer emits ~30% more tokens for the same text; without this, a workload looks cheaper than it bills.
+3. **Plain-English explanations** from rule-based anomaly detection:
+   - *"Why your 'Other Models' pool drained first"* — auto-model routing sent X% of requests to non-Cursor models.
+   - *"The grok-4 spend landed in unexpected pool(s)"* — one model billed across multiple pools.
+   - *"'fable-5.1' requests were routed to 'fable-5.5'"* — silent version swaps, with the N local sessions listed.
+   - *"Unattended burn: $X spent while no interactive session was open"* — the "$40 while I slept" case.
+   - *"Sudden pool switch on <date>"* — same usage pattern, different bucket mid-cycle.
+3. **Local-log cross-check** — joins bill rows against your `~/.claude/projects/**/*.jsonl` and `~/.codex/sessions/` by time window, reporting matched vs orphaned spend.
+4. **Plan-switch what-if simulator**:
+
+```
+blackbox-bill --csv cursor-export.csv --whatif cursor:ultra
+```
+
+re-prices observed token usage under a different plan's rates and prints the delta vs the actual bill. Bundled rate cards are **illustrative placeholders, not real Cursor pricing** — pass `--rates-file rates.json` with your own numbers (see `src/blackbox_bill/whatif.py` for the format).
+
+```
+blackbox-bill --csv export.csv --markdown report.md --since 2026-09-01
+```
+
+Exit codes: `0` ok, `2` usage error (unreadable CSV, unknown plan). Missing local log directories are warnings, not errors — the bill alone is still explainable.
+
+## Cost attribution from local logs (no bill needed)
+
+`blackbox-bill report` works without a CSV: it reads your Claude Code transcripts and answers the questions forums keep asking.
+
+**Per-project attribution** — which project burned the quota (u/rosehsu47's complaint: `/usage` can't tell you which project spent it, so people hand-roll quota-audit scripts over the same jsonl files):
+
+```
+blackbox-bill report --by-project
+```
+
+Aggregates tokens, estimated cost, and per-session detail per `~/.claude/projects/*` directory, sorted by estimated spend. Dollar figures are estimates from an illustrative built-in rate card — pass `--rates-file` with your own per-1M-token rates for real numbers.
+
+**Subagent attribution** — how much of the burn was subagents (u/aidiveyt measured 2,631 subagent runs eating **48.1%** of tokens):
+
+```
+blackbox-bill report --by-agent --top 10
+```
+
+Subagent token share is measured on sidechain transcript messages; the Top-N ranking attributes sidechain tokens to the invoked `subagent_type`s (Task tool calls), split proportionally.
+
+```
+blackbox-bill report --by-project --by-agent --tokenizer claude-4.7 \
+    --rates-file my-rates.json --markdown attribution.md
+```
+
+## Non-goals (what this is NOT)
+
+- **[agentcost-cli](https://dev.to/justinli2026/how-i-built-a-unified-cost-tracker-for-ai-coding-agents-claude-code-cursor-codex-1nid)** does multi-tool budget observability dashboards with WARN/OVERRUN budget lines. blackbox-bill has no dashboards, no budget lines, no MCP server — it explains one bill, once.
+- **resume-budget-guard** (sibling project) enforces cumulative spend caps across Claude Code `--resume` runs. blackbox-bill never blocks or enforces anything; it is read-only analysis.
+- **ccusage** covers Claude Code usage attribution (daily/monthly/session/blocks, per-model breakdown). blackbox-bill deliberately does not re-do Claude Code attribution — its job is the *cross-tool routing black box* (Cursor pools, unexpected providers, silent model swaps).
+
+One sentence: the others tell you *how much* you spent or *stop* you from spending; blackbox-bill tells you *why the bill looks wrong*.
+
+## How it differs from statusline dashboards
+
+Tools like [uppinote20/claude-dashboard](https://github.com/uppinote20/claude-dashboard) are **observability statuslines**: they live inside your IDE, rendering live context bars, rate-limit countdowns, and burn-rate widgets while you work. That's a telescope pointed at the present.
+
+blackbox-bill is a **billing-attribution ledger**: it runs after the fact, off local files only, and reconstructs *where the money went* — which pool, which project, which subagents, under which tokenizer's counting. No plugin install, no Node runtime, no live session needed — just the bill CSV and the transcripts you already have. Use the statusline to watch the burn; use blackbox-bill to audit it.
+
+## Honest limitations
+
+- **Cursor changes its export format.** The parser fuzzy-matches headers and fails soft on missing columns, but a radically new format may need new aliases — contributions welcome.
+- **Routing rules are inferred, not official.** Explanations are heuristics built from observed community patterns ("Other Models drains first", "Grok Bot mis-bucketing"). They are not Cursor/OpenAI/Anthropic documentation, and every explanation says so.
+- **Times are local-timezone best-effort.** Bill timestamps and local log timestamps are compared as wall-clock times on the same machine. If your export is in UTC and your logs are local, widen `--window-hours` or convert first.
+- **The join is evidence, not proof.** A bill row with no matching local session might be a background agent, a headless run, another machine, or a leaked key — the tool reports the gap; you investigate.
+- **Token-based re-pricing is approximate.** The what-if simulator re-prices tokens at flat rates; real plans have request-based pricing, overage rules, and weekly pools (e.g. SuperGrok bundles) that flat rates cannot model. Use `--rates-file` for your own numbers.
+
+## Install
+
+```bash
+pip install blackbox-bill
+# or from source:
+pip install .
+```
+
+Zero dependencies — Python 3.9+ stdlib only.
+
+## Example output
+
+```
+blackbox-bill v0.2.0 — where the money went
+============================================================
+Bill rows: 5   requests: 68   billed total: $27.00
+
+## Tokenizer-aware token figures
+Measured under: legacy tokenizer (Claude <=4.5).
+Input tokens:  300.0K (legacy) ~= 390.0K (claude-4.7, x1.3)
+Output tokens: 60.0K (legacy) ~= 78.0K (claude-4.7, x1.3)
+Total tokens:  360.0K (legacy) ~= 468.0K (claude-4.7, x1.3)
+(claude-4.7+ figures are approximations, not re-tokenized counts)
+
+## Pool-normalized summary
+cursor-models     2 rows       8 reqs  $     3.00
+    claude-opus-5.5                    8 reqs  $    3.00
+other-models      3 rows      60 reqs  $    24.00
+    grok-4                            40 reqs  $   16.00
+    gemini-4                          20 reqs  $    8.00
+
+## Explanations
+
+[pool-drain] Why your 'Other Models' pool drained first
+Auto-model routing sent most of your billable work to non-Cursor models...
+Evidence: 3 row(s), 60 request(s), $24.00.
+...
+```
+
+## Development
+
+```bash
+python3 tests/test_blackbox_bill.py          # 41 checks, <1s
+PYTHONPATH=src python3 -m unittest discover -s tests -t .   # 28 v2 checks
+```
+
+## License
+
+MIT

blackbox_bill-0.2.0/README.md

@@ -0,0 +1,145 @@
+# blackbox-bill
+
+**Explain where your AI-coding-tool money went.** A stdlib-only Python CLI that reads your Cursor billing export and your local session logs, then tells you — in plain English — why your bill looks the way it does. v2 adds tokenizer-aware cost attribution: per-project breakdowns and subagent token share, straight from your `~/.claude/projects` transcripts.
+
+No network. No API keys. Deterministic: every explanation cites the exact rows it was computed from.
+
+## The problem
+
+Cursor's billing pools confuse everyone:
+
+- u/josh3com on r/ClaudeCode: *"CURSOR TEAM PLEASE HELP - Cursor support keeps telling me my 100% full usage pool is from grok bot two months in a row"* — Grok Bot spend kept landing in "Other Models" with no explanation in the app.
+- u/FerretValuable9718: *"Why is the 'Other Models' usage being used so much with so little time?"* — screenshot showed **Other Models 100% used while Cursor Models sat at 16%**.
+- r/AI_Agents: *"My coding agent hit a cold-start 503, found a Gemini key in my repo, and burned $40 while I slept"* — spend routed to a provider the user never intended.
+- dev.to: *"$402 on one ticket"* in headless Claude Code — *"nothing in the app said so"*, so the author built manual bookkeeping.
+- r/ClaudeCode, October 2026: Fable 5.1 requests silently served by 5.5 — the model on the invoice doesn't match the model you asked for.
+
+Forums are full of people doing billing archaeology by hand. blackbox-bill automates the archaeology.
+
+## What it does
+
+```
+blackbox-bill --csv cursor-export.csv
+```
+
+Given a Cursor billing export CSV (columns vary — the parser is deliberately liberal), it prints:
+
+1. **Pool-normalized summary** — first-party Cursor pool vs "Other Models" pool vs API-key spend, per model, per day. Free-form pool labels are normalized to the three canonical pools; unrecognized labels are reported as `unknown`, never silently dropped.
+2. **Tokenizer-aware token figures** — every token total is shown in both tokenizer equivalents (`--tokenizer legacy|claude-4.7`, `--tokenizer-factor` to override the default 1.3 ratio). Claude 4.7+'s new tokenizer emits ~30% more tokens for the same text; without this, a workload looks cheaper than it bills.
+3. **Plain-English explanations** from rule-based anomaly detection:
+   - *"Why your 'Other Models' pool drained first"* — auto-model routing sent X% of requests to non-Cursor models.
+   - *"The grok-4 spend landed in unexpected pool(s)"* — one model billed across multiple pools.
+   - *"'fable-5.1' requests were routed to 'fable-5.5'"* — silent version swaps, with the N local sessions listed.
+   - *"Unattended burn: $X spent while no interactive session was open"* — the "$40 while I slept" case.
+   - *"Sudden pool switch on <date>"* — same usage pattern, different bucket mid-cycle.
+3. **Local-log cross-check** — joins bill rows against your `~/.claude/projects/**/*.jsonl` and `~/.codex/sessions/` by time window, reporting matched vs orphaned spend.
+4. **Plan-switch what-if simulator**:
+
+```
+blackbox-bill --csv cursor-export.csv --whatif cursor:ultra
+```
+
+re-prices observed token usage under a different plan's rates and prints the delta vs the actual bill. Bundled rate cards are **illustrative placeholders, not real Cursor pricing** — pass `--rates-file rates.json` with your own numbers (see `src/blackbox_bill/whatif.py` for the format).
+
+```
+blackbox-bill --csv export.csv --markdown report.md --since 2026-09-01
+```
+
+Exit codes: `0` ok, `2` usage error (unreadable CSV, unknown plan). Missing local log directories are warnings, not errors — the bill alone is still explainable.
+
+## Cost attribution from local logs (no bill needed)
+
+`blackbox-bill report` works without a CSV: it reads your Claude Code transcripts and answers the questions forums keep asking.
+
+**Per-project attribution** — which project burned the quota (u/rosehsu47's complaint: `/usage` can't tell you which project spent it, so people hand-roll quota-audit scripts over the same jsonl files):
+
+```
+blackbox-bill report --by-project
+```
+
+Aggregates tokens, estimated cost, and per-session detail per `~/.claude/projects/*` directory, sorted by estimated spend. Dollar figures are estimates from an illustrative built-in rate card — pass `--rates-file` with your own per-1M-token rates for real numbers.
+
+**Subagent attribution** — how much of the burn was subagents (u/aidiveyt measured 2,631 subagent runs eating **48.1%** of tokens):
+
+```
+blackbox-bill report --by-agent --top 10
+```
+
+Subagent token share is measured on sidechain transcript messages; the Top-N ranking attributes sidechain tokens to the invoked `subagent_type`s (Task tool calls), split proportionally.
+
+```
+blackbox-bill report --by-project --by-agent --tokenizer claude-4.7 \
+    --rates-file my-rates.json --markdown attribution.md
+```
+
+## Non-goals (what this is NOT)
+
+- **[agentcost-cli](https://dev.to/justinli2026/how-i-built-a-unified-cost-tracker-for-ai-coding-agents-claude-code-cursor-codex-1nid)** does multi-tool budget observability dashboards with WARN/OVERRUN budget lines. blackbox-bill has no dashboards, no budget lines, no MCP server — it explains one bill, once.
+- **resume-budget-guard** (sibling project) enforces cumulative spend caps across Claude Code `--resume` runs. blackbox-bill never blocks or enforces anything; it is read-only analysis.
+- **ccusage** covers Claude Code usage attribution (daily/monthly/session/blocks, per-model breakdown). blackbox-bill deliberately does not re-do Claude Code attribution — its job is the *cross-tool routing black box* (Cursor pools, unexpected providers, silent model swaps).
+
+One sentence: the others tell you *how much* you spent or *stop* you from spending; blackbox-bill tells you *why the bill looks wrong*.
+
+## How it differs from statusline dashboards
+
+Tools like [uppinote20/claude-dashboard](https://github.com/uppinote20/claude-dashboard) are **observability statuslines**: they live inside your IDE, rendering live context bars, rate-limit countdowns, and burn-rate widgets while you work. That's a telescope pointed at the present.
+
+blackbox-bill is a **billing-attribution ledger**: it runs after the fact, off local files only, and reconstructs *where the money went* — which pool, which project, which subagents, under which tokenizer's counting. No plugin install, no Node runtime, no live session needed — just the bill CSV and the transcripts you already have. Use the statusline to watch the burn; use blackbox-bill to audit it.
+
+## Honest limitations
+
+- **Cursor changes its export format.** The parser fuzzy-matches headers and fails soft on missing columns, but a radically new format may need new aliases — contributions welcome.
+- **Routing rules are inferred, not official.** Explanations are heuristics built from observed community patterns ("Other Models drains first", "Grok Bot mis-bucketing"). They are not Cursor/OpenAI/Anthropic documentation, and every explanation says so.
+- **Times are local-timezone best-effort.** Bill timestamps and local log timestamps are compared as wall-clock times on the same machine. If your export is in UTC and your logs are local, widen `--window-hours` or convert first.
+- **The join is evidence, not proof.** A bill row with no matching local session might be a background agent, a headless run, another machine, or a leaked key — the tool reports the gap; you investigate.
+- **Token-based re-pricing is approximate.** The what-if simulator re-prices tokens at flat rates; real plans have request-based pricing, overage rules, and weekly pools (e.g. SuperGrok bundles) that flat rates cannot model. Use `--rates-file` for your own numbers.
+
+## Install
+
+```bash
+pip install blackbox-bill
+# or from source:
+pip install .
+```
+
+Zero dependencies — Python 3.9+ stdlib only.
+
+## Example output
+
+```
+blackbox-bill v0.2.0 — where the money went
+============================================================
+Bill rows: 5   requests: 68   billed total: $27.00
+
+## Tokenizer-aware token figures
+Measured under: legacy tokenizer (Claude <=4.5).
+Input tokens:  300.0K (legacy) ~= 390.0K (claude-4.7, x1.3)
+Output tokens: 60.0K (legacy) ~= 78.0K (claude-4.7, x1.3)
+Total tokens:  360.0K (legacy) ~= 468.0K (claude-4.7, x1.3)
+(claude-4.7+ figures are approximations, not re-tokenized counts)
+
+## Pool-normalized summary
+cursor-models     2 rows       8 reqs  $     3.00
+    claude-opus-5.5                    8 reqs  $    3.00
+other-models      3 rows      60 reqs  $    24.00
+    grok-4                            40 reqs  $   16.00
+    gemini-4                          20 reqs  $    8.00
+
+## Explanations
+
+[pool-drain] Why your 'Other Models' pool drained first
+Auto-model routing sent most of your billable work to non-Cursor models...
+Evidence: 3 row(s), 60 request(s), $24.00.
+...
+```
+
+## Development
+
+```bash
+python3 tests/test_blackbox_bill.py          # 41 checks, <1s
+PYTHONPATH=src python3 -m unittest discover -s tests -t .   # 28 v2 checks
+```
+
+## License
+
+MIT

blackbox_bill-0.2.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blackbox-bill"
+version = "0.2.0"
+description = "Explain where your AI-coding-tool money went: billing black-box explainer with tokenizer-aware per-project and subagent cost attribution"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "hao li" }]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.scripts]
+blackbox-bill = "blackbox_bill.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

blackbox_bill-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

blackbox_bill-0.2.0/src/blackbox_bill/__init__.py

@@ -0,0 +1,7 @@
+"""blackbox-bill: explain where your AI-coding-tool money went.
+
+Deterministic, stdlib-only, no network, no API keys. Reads files you
+already have (Cursor billing CSV exports, local Claude Code / Codex
+session logs) and explains routing anomalies in plain English.
+"""
+__version__ = "0.2.0"

blackbox_bill-0.2.0/src/blackbox_bill/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

blackbox_bill-0.2.0/src/blackbox_bill/attribution.py

@@ -0,0 +1,269 @@
+"""Cost attribution: per-project and subagent breakdowns from local logs.
+
+A billing CSV tells you *which pool* the money left from. These reports
+answer the questions users actually ask in forums:
+
+- "which project burned my quota?" (per-project attribution over
+  ``~/.claude/projects/*/*.jsonl``)
+- "how much of my spend was subagents?" (subagent share + Top-N ranking)
+
+Token counts come straight from the transcripts. Dollar figures are
+*estimates*: they re-price observed tokens with a rate card. The bundled
+card is illustrative; pass ``--rates-file`` with your own numbers.
+"""
+
+import json
+
+from .tokenizer import dual_line, fmt_tokens
+
+# Illustrative rates, USD per 1M tokens. NOT real vendor pricing — the tool
+# has no network and vendor pricing changes. See --rates-file.
+ILLUSTRATIVE_RATES = {
+    "label": "illustrative built-in rates (NOT real pricing — use --rates-file)",
+    "default": {"input": 3.0, "output": 15.0},
+    "patterns": [
+        (["opus"], {"input": 15.0, "output": 75.0}),
+        (["sonnet"], {"input": 3.0, "output": 15.0}),
+        (["haiku"], {"input": 1.0, "output": 5.0}),
+        (["gpt-5", "gpt-4"], {"input": 5.0, "output": 20.0}),
+        (["gemini"], {"input": 2.0, "output": 12.0}),
+        (["grok"], {"input": 3.0, "output": 15.0}),
+    ],
+}
+
+
+def load_rate_card(path=None):
+    """Load a rate card: {'label', 'default': {input, output}, 'patterns': [...]}.
+
+    JSON format for --rates-file::
+
+        {
+          "label": "my actual rates",
+          "default": {"input": 3.0, "output": 15.0},
+          "patterns": [
+            {"match": ["opus"], "input": 15.0, "output": 75.0}
+          ]
+        }
+
+    Rates are USD per 1M tokens. Without a file, the illustrative
+    built-in card is returned (clearly labeled as such).
+    """
+    if path is None:
+        return ILLUSTRATIVE_RATES
+    with open(path, "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    card = {
+        "label": data.get("label", path),
+        "default": {
+            "input": float(data.get("default", {}).get("input", 3.0)),
+            "output": float(data.get("default", {}).get("output", 15.0)),
+        },
+        "patterns": [],
+    }
+    for p in data.get("patterns", []) or []:
+        match = p.get("match") or []
+        if isinstance(match, str):
+            match = [match]
+        card["patterns"].append((
+            [str(m).lower() for m in match],
+            {"input": float(p.get("input", 3.0)),
+             "output": float(p.get("output", 15.0))},
+        ))
+    return card
+
+
+def rate_for(model, card=None):
+    """Pick (input_per_1M, output_per_1M) for a model name."""
+    card = card or ILLUSTRATIVE_RATES
+    name = (model or "").lower()
+    for needles, rate in card.get("patterns", []):
+        if any(n in name for n in needles):
+            return rate["input"], rate["output"]
+    d = card.get("default", {"input": 3.0, "output": 15.0})
+    return d["input"], d["output"]
+
+
+def estimate_cost(input_tokens, output_tokens, model, card=None):
+    """Estimated USD cost of token usage under a rate card."""
+    rin, rout = rate_for(model, card)
+    return input_tokens / 1e6 * rin + output_tokens / 1e6 * rout
+
+
+def _in_window(session, since, until):
+    ts = session.get("first_ts") or session.get("last_ts")
+    if ts is None:
+        return True  # undated sessions are kept, same as undated bill rows
+    d = ts.date()
+    if since and d < since:
+        return False
+    if until and d > until:
+        return False
+    return True
+
+
+def _session_cost(session, card):
+    model = session.get("model") or ""
+    return estimate_cost(session.get("input_tokens", 0),
+                         session.get("output_tokens", 0), model, card)
+
+
+def by_project(sessions, since=None, until=None, card=None):
+    """Aggregate sessions by project directory.
+
+    Returns a list of project dicts sorted by estimated cost desc:
+    {project, tokens, input_tokens, output_tokens, est_cost, requests,
+     sessions: [...], subagent_tokens, subagent_runs}
+    """
+    card = card or ILLUSTRATIVE_RATES
+    projects = {}
+    for s in sessions:
+        if not _in_window(s, since, until):
+            continue
+        key = s.get("project") or "(unknown project)"
+        p = projects.setdefault(key, {
+            "project": key,
+            "tokens": 0, "input_tokens": 0, "output_tokens": 0,
+            "est_cost": 0.0, "requests": 0,
+            "sessions": [], "subagent_tokens": 0, "subagent_runs": 0,
+        })
+        tin = s.get("input_tokens", 0)
+        tout = s.get("output_tokens", 0)
+        stin = s.get("subagent_input_tokens", 0)
+        stout = s.get("subagent_output_tokens", 0)
+        p["tokens"] += tin + tout
+        p["input_tokens"] += tin
+        p["output_tokens"] += tout
+        p["est_cost"] += _session_cost(s, card)
+        p["requests"] += s.get("requests", 0)
+        p["subagent_tokens"] += stin + stout
+        p["subagent_runs"] += s.get("subagent_runs", 0)
+        p["sessions"].append({
+            "session_id": s.get("session_id", ""),
+            "model": s.get("model", ""),
+            "tokens": tin + tout,
+            "est_cost": _session_cost(s, card),
+            "requests": s.get("requests", 0),
+            "subagent_tokens": stin + stout,
+            "subagent_runs": s.get("subagent_runs", 0),
+        })
+    result = sorted(projects.values(), key=lambda p: -p["est_cost"])
+    for p in result:
+        p["sessions"].sort(key=lambda x: -x["est_cost"])
+    return result
+
+
+def by_agent(sessions, since=None, until=None, card=None, top=10):
+    """Subagent attribution.
+
+    Returns {total_tokens, subagent_tokens, share, runs, agents: [...]}
+    where agents is a Top-N list of
+    {agent_type, tokens, share_of_subagent, runs, sessions} sorted by
+    tokens desc. A session's sidechain tokens are split across the agent
+    types it invoked, proportional to invocation counts.
+    """
+    card = card or ILLUSTRATIVE_RATES
+    total_tokens = 0
+    subagent_tokens = 0
+    runs = 0
+    agents = {}
+    for s in sessions:
+        if not _in_window(s, since, until):
+            continue
+        tin = s.get("input_tokens", 0)
+        tout = s.get("output_tokens", 0)
+        st = s.get("subagent_input_tokens", 0) + s.get("subagent_output_tokens", 0)
+        total_tokens += tin + tout
+        subagent_tokens += st
+        types = s.get("subagent_types") or {}
+        n_runs = sum(types.values())
+        runs += n_runs
+        if st and n_runs:
+            for agent_type, count in types.items():
+                a = agents.setdefault(agent_type, {
+                    "agent_type": agent_type, "tokens": 0, "runs": 0,
+                    "sessions": set()})
+                a["tokens"] += st * count / n_runs
+                a["runs"] += count
+                a["sessions"].add(s.get("session_id", ""))
+    agent_list = []
+    for a in agents.values():
+        agent_list.append({
+            "agent_type": a["agent_type"],
+            "tokens": a["tokens"],
+            "share_of_subagent": a["tokens"] / subagent_tokens if subagent_tokens else 0.0,
+            "runs": a["runs"],
+            "sessions": len(a["sessions"]),
+        })
+    agent_list.sort(key=lambda a: -a["tokens"])
+    return {
+        "total_tokens": total_tokens,
+        "subagent_tokens": subagent_tokens,
+        "share": subagent_tokens / total_tokens if total_tokens else 0.0,
+        "runs": runs,
+        "agents": agent_list[:top],
+    }
+
+
+def project_report_text(projects, tokenizer, tok_factor, card=None):
+    card = card or ILLUSTRATIVE_RATES
+    L = []
+    L.append("## Per-project attribution (local Claude Code logs)")
+    L.append("Rate card: %s" % card.get("label", "built-in illustrative"))
+    L.append("Tokenizer: %s figures shown both ways; cost estimated from "
+             "measured tokens." % tokenizer)
+    L.append("")
+    if not projects:
+        L.append("No sessions found. Check --claude-dir.")
+        return "\n".join(L)
+    total_tokens = sum(p["tokens"] for p in projects)
+    total_cost = sum(p["est_cost"] for p in projects)
+    L.append("All projects: %s tokens, est. $%.2f"
+             % (dual_line(total_tokens, tokenizer, tok_factor), total_cost))
+    L.append("")
+    for p in projects:
+        share = p["est_cost"] / total_cost if total_cost else 0.0
+        sub_share = (p["subagent_tokens"] / p["tokens"]
+                     if p["tokens"] else 0.0)
+        L.append("%s  —  %s tokens  est. $%.2f (%.1f%% of total)"
+                 % (p["project"], dual_line(p["tokens"], tokenizer, tok_factor),
+                    p["est_cost"], share * 100))
+        L.append("    %d session(s), %d requests, subagent %.1f%% of tokens "
+                 "(%d runs)"
+                 % (len(p["sessions"]), p["requests"], sub_share * 100,
+                    p["subagent_runs"]))
+        for s in p["sessions"][:8]:
+            L.append("      %-28.28s %-22.22s %9s tok  est. $%7.2f  %4d reqs"
+                     % (s["session_id"][:28], s["model"][:22],
+                        fmt_tokens(s["tokens"]), s["est_cost"],
+                        s["requests"]))
+        if len(p["sessions"]) > 8:
+            L.append("      ... and %d more session(s)"
+                     % (len(p["sessions"]) - 8))
+        L.append("")
+    return "\n".join(L)
+
+
+def agent_report_text(result, tokenizer, tok_factor, card=None):
+    card = card or ILLUSTRATIVE_RATES
+    L = []
+    L.append("## Subagent attribution (local Claude Code logs)")
+    L.append("Rate card: %s" % card.get("label", "built-in illustrative"))
+    L.append("Subagent tokens are measured on sidechain transcript messages; "
+             "agent-type split is proportional to Task invocations.")
+    L.append("")
+    L.append("Subagent share of all tokens: %s tokens = %.1f%% (%d runs)"
+             % (dual_line(result["subagent_tokens"], tokenizer, tok_factor),
+                result["share"] * 100, result["runs"]))
+    L.append("Total measured tokens: %s"
+             % dual_line(result["total_tokens"], tokenizer, tok_factor))
+    L.append("")
+    if not result["agents"]:
+        L.append("No subagent activity detected. (Subagents appear as "
+                 "sidechain transcript messages with Task tool calls.)")
+        return "\n".join(L)
+    L.append("Top subagent types:")
+    for i, a in enumerate(result["agents"], 1):
+        L.append("  %2d. %-24.24s %9s tok  %5.1f%% of subagent  %4d runs  %3d sessions"
+                 % (i, a["agent_type"], fmt_tokens(a["tokens"]),
+                    a["share_of_subagent"] * 100, a["runs"], a["sessions"]))
+    return "\n".join(L)