tokenjam 0.4.2__tar.gz → 0.5.0__tar.gz

{tokenjam-0.4.2 → tokenjam-0.5.0}/CLAUDE.md

@@ -376,7 +376,7 @@ Key runtime dependency: `pytz` is required by DuckDB for `TIMESTAMPTZ` column ha
 - `tokenjam[bloat]` — `llmlingua>=0.2`, used by the Trim analyzer. Pulls PyTorch + transformers (~2GB). Kept out of base install. The analyzer self-registers without the extra installed; the deferred `import llmlingua` inside the analysis function body raises a typed message pointing the user at the install command.
 - Framework extras `[langchain]`, `[crewai]`, `[autogen]`, `[litellm]` for SDK patches.
 - `[dev]` for local development (`pytest`, `ruff`, `mypy`, `httpx`).
-- `[mcp]` for the FastMCP stdio server.
+- `[mcp]` — empty no-op alias. `fastmcp` moved into the base install in v0.3.5 (#101), so the FastMCP stdio server (`tj mcp`) works on a plain `pipx install tokenjam`. The extra is kept so old `tokenjam[mcp]` install commands still succeed; it pulls nothing extra.
 
 ## Further Reading
 

{tokenjam-0.4.2 → tokenjam-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tokenjam
-Version: 0.4.2
+Version: 0.5.0
 Summary: TokenJam — local-first OTel-native observability for Autonomous AI agents
 Project-URL: Homepage, https://opencla.watch
 Project-URL: Repository, https://github.com/Metabuilder-Labs/openclawwatch

{tokenjam-0.4.2 → tokenjam-0.5.0}/docs/claude-code-integration.md

@@ -3,7 +3,7 @@
 Monitor every Claude Code session — costs, tool calls, API requests, errors — with two commands:
 
 ```bash
-pipx install 'tokenjam[mcp]'
+pipx install tokenjam
 tj onboard --claude-code
 # Restart Claude Code, then:
 tj status --agent claude-code-<project>
@@ -35,7 +35,7 @@ Claude Code emits OTLP log events which `tj serve` converts into spans — every
 
 ## MCP server
 
-The MCP server is included in the `[mcp]` extra and registered automatically by `tj onboard --claude-code`. It gives Claude Code direct access to your observability data inside the session itself. After restarting Claude Code you have 13 tools available in every session:
+The MCP server ships in the base install (`pipx install tokenjam` — no extra needed) and is registered automatically by `tj onboard --claude-code`. It gives Claude Code direct access to your observability data inside the session itself. After restarting Claude Code you have 13 tools available in every session:
 
 | Tool | What it does |
 |---|---|

{tokenjam-0.4.2 → tokenjam-0.5.0}/docs/installation.md

@@ -52,8 +52,8 @@ TokenJam keeps heavyweight ML dependencies, framework adapters, and the MCP serv
 
 | Extra | What it pulls in | Why it's optional |
 |---|---|---|
-| `tokenjam[mcp]` | `fastmcp` | Only needed for the Claude Code / Codex MCP server (`tj mcp`). Pulled by `tj onboard --claude-code` automatically when invoked through the documented one-liner. |
-| `tokenjam[bloat]` | `llmlingua>=0.2`, transitively PyTorch + transformers (~2GB) | The Trim analyzer (`tj optimize trim`) scores token significance with LLMLingua-2. Most users don't run it; keeping torch out of the base install means `pip install tokenjam` stays small and fast on machines that don't have a GPU/CPU build of torch already. |
+| `tokenjam[mcp]` | nothing (no-op alias) | **No longer needed.** `fastmcp` moved into the base install in v0.3.5, so the Claude Code / Codex MCP server (`tj mcp`) works on a plain `pipx install tokenjam`. The extra is kept as an empty no-op so old `pipx install 'tokenjam[mcp]'` commands still succeed; it pulls nothing extra. |
+| `tokenjam[bloat]` | `llmlingua>=0.2`, transitively PyTorch + transformers (~2GB) | The Trim analyzer (`tj optimize trim`) scores token significance with LLMLingua-2. Most users don't run it; keeping torch out of the base install keeps it small and fast on machines that don't have a GPU/CPU build of torch already. |
 | `tokenjam[langchain]` | `langchain>=0.2` | Convenience pin for `patch_langchain()`; you can also install langchain yourself. |
 | `tokenjam[crewai]` | `crewai>=0.28` | Convenience pin for `patch_crewai()`. |
 | `tokenjam[autogen]` | `pyautogen>=0.2` | Convenience pin for `patch_autogen()`. |
@@ -63,7 +63,7 @@ TokenJam keeps heavyweight ML dependencies, framework adapters, and the MCP serv
 Combine multiple extras:
 
 ```bash
-pipx install 'tokenjam[mcp,bloat]'
+pipx install 'tokenjam[bloat,litellm]'
 ```
 
 ### Bloat extra details

{tokenjam-0.4.2 → tokenjam-0.5.0}/docs/optimize/trim.md

@@ -25,7 +25,7 @@ base install:
 pipx install 'tokenjam[bloat]'
 ```
 
-The base `pip install tokenjam` does NOT pull torch. Trim shows up in
+The base install (`pipx install tokenjam`) does NOT pull torch. Trim shows up in
 `tj optimize` analyzer choices regardless, but running it without the
 extra prints a clear install hint and exits.
 

{tokenjam-0.4.2 → tokenjam-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tokenjam"
-version = "0.4.2"
+version = "0.5.0"
 description = "TokenJam — local-first OTel-native observability for Autonomous AI agents"
 readme = "README.md"
 requires-python = ">=3.10"

{tokenjam-0.4.2 → tokenjam-0.5.0}/sdk-ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenjam/sdk",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "TypeScript SDK for TokenJam — local-first observability for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

tokenjam-0.5.0/tests/integration/test_analytics.py

@@ -0,0 +1,191 @@
+"""Endpoint tests for the Analytics pivot explorer (#210).
+
+Covers the generalized group-by: metric × group_by × stack_by × filters → a
+grouped series + KPI totals + the plan-tier framing block. The explorer's
+line / bar / hbar views are all client-side pivots of this one `rows` shape.
+"""
+from __future__ import annotations
+
+from datetime import timedelta
+
+import httpx
+import pytest
+
+from tokenjam.api.app import create_app
+from tokenjam.core.config import ProviderBudget, TjConfig
+from tokenjam.core.db import InMemoryBackend
+from tokenjam.core.ingest import IngestPipeline
+from tokenjam.utils.time_parse import utcnow
+from tests.factories import make_llm_span, make_session, make_tool_span
+
+
+def _app(db, config):
+    return create_app(config=config, db=db, ingest_pipeline=IngestPipeline(db=db, config=config))
+
+
+def _seed(db, plan="api"):
+    now = utcnow()
+    for d in range(4):
+        for model, provider, cost in [("claude-opus-4-7", "anthropic", 0.06),
+                                       ("gpt-4o", "openai", 0.03)]:
+            sid = f"s{d}-{model}"
+            db.upsert_session(make_session(session_id=sid, plan_tier=plan, agent_id="cc"))
+            llm = make_llm_span(
+                session_id=sid, agent_id="cc", model=model, provider=provider,
+                input_tokens=2000, output_tokens=300, cost_usd=cost,
+                start_time=now - timedelta(days=d),
+            )
+            db.insert_span(llm)
+            for tool in ["Read", "Bash", "Grep"]:
+                t = make_tool_span(agent_id="cc", tool_name=tool, trace_id=llm.trace_id)
+                t.session_id = sid
+                t.start_time = now - timedelta(days=d)
+                db.insert_span(t)
+
+
+async def _get(db, cfg, qs):
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        return (await c.get("/api/v1/analytics?" + qs)).json()
+
+
+@pytest.mark.asyncio
+async def test_spend_by_model_grouped_series_and_kpis():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, "metric=spend&group_by=model&since=30d")
+    assert d["metric"] == "spend" and d["value_unit"] == "usd"
+    # groups sorted by total desc; opus (0.06×4) > gpt (0.03×4)
+    assert d["groups"] == ["claude-opus-4-7", "gpt-4o"]
+    assert d["rows"], "expected grouped rows"
+    for r in d["rows"]:
+        assert {"bucket", "group", "stack", "value", "tokens"} <= set(r)
+    # KPIs are window totals, independent of group_by
+    assert d["kpis"]["spend"] == pytest.approx(0.36)
+    assert d["kpis"]["sessions"] == 8
+    assert d["framing"]["pricing_mode"] == "api"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("metric,unit", [
+    ("tokens", "tokens"), ("sessions", "count"), ("events", "count"),
+])
+async def test_metric_dimension_matrix(metric, unit):
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, f"metric={metric}&group_by=agent&since=30d")
+    assert d["value_unit"] == unit
+    assert d["groups"] == ["cc"]
+    assert d["rows"]
+
+
+@pytest.mark.asyncio
+async def test_tool_category_dimension_includes_tool_spans():
+    """tool / tool_category breakdowns must see tool spans (NULL model), which
+    the LLM-cost `model IS NOT NULL` gate would otherwise hide."""
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, "metric=events&group_by=tool_category&since=30d")
+    assert set(d["groups"]) == {"file", "shell", "search"}  # Read/Edit, Bash, Grep
+    assert "(none)" not in d["groups"]
+    # KPI totals reflect the FULL window (LLM spend included), not the tool-only
+    # subtype gate the breakdown applies — so "events by tool" never zeroes Spend.
+    assert d["kpis"]["spend"] > 0
+    assert d["kpis"]["tokens"] > 0
+
+
+@pytest.mark.asyncio
+async def test_stack_by_returns_second_dimension():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, "metric=spend&group_by=provider&stack_by=model&since=30d")
+    assert d["stack_by"] == "model"
+    assert set(d["groups"]) == {"anthropic", "openai"}
+    assert set(d["stacks"]) == {"claude-opus-4-7", "gpt-4o"}
+    assert any(r["stack"] for r in d["rows"])
+
+
+@pytest.mark.asyncio
+async def test_filters_scope_the_window():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, "metric=spend&group_by=model&provider=anthropic&since=30d")
+    assert d["groups"] == ["claude-opus-4-7"]
+    assert "gpt-4o" not in d["groups"]
+
+
+@pytest.mark.asyncio
+async def test_subscription_framing_suppresses_dollars():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1", budgets={"anthropic": ProviderBudget(plan="max_20x")})
+    _seed(db, plan="max_20x")
+    d = await _get(db, cfg, "metric=spend&group_by=model&since=30d")
+    assert d["framing"]["pricing_mode"] == "subscription"
+    # token volume is present per row so the UI renders token-share, not $
+    assert all("tokens" in r for r in d["rows"])
+
+
+@pytest.mark.asyncio
+async def test_unknown_metric_and_dimension_rejected():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        assert (await c.get("/api/v1/analytics?metric=bogus")).status_code == 400
+        assert (await c.get("/api/v1/analytics?group_by=bogus")).status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_empty_window_is_safe():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    d = await _get(db, cfg, "metric=spend&group_by=model&since=7d")
+    assert d["rows"] == [] and d["groups"] == []
+    assert d["kpis"]["spend"] == 0
+    assert "framing" in d
+    # #217: the sparkline/delta fields are always present. With a window set,
+    # the delta keys exist but are null (no prior data → no divide-by-zero).
+    assert d["kpi_series"] == []
+    assert set(d["kpi_deltas"]) == {"spend", "tokens", "events", "sessions"}
+    assert all(v is None for v in d["kpi_deltas"].values())
+
+
+@pytest.mark.asyncio
+async def test_kpi_series_and_deltas_for_sparklines():
+    """#217: the explorer returns a per-bucket `kpi_series` (all four metrics)
+    and a period-over-period `kpi_deltas` vs the prior equal-length window —
+    both computed server-side so the UI never aggregates per-bucket in JS."""
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)  # 4 days of data, two models/day
+    d = await _get(db, cfg, "metric=spend&group_by=model&since=30d")
+    # Per-bucket series carries every KPI metric for each bucket.
+    assert d["kpi_series"], "expected a non-empty kpi_series"
+    for b in d["kpi_series"]:
+        assert {"bucket", "spend", "tokens", "events", "sessions"} <= set(b)
+    # Series spend reconciles with the window KPI total.
+    assert sum(b["spend"] for b in d["kpi_series"]) == pytest.approx(d["kpis"]["spend"])
+    # Prior window had no data (seed is the most recent 4 days) → prev=0 → null
+    # delta, never a divide-by-zero.
+    assert set(d["kpi_deltas"]) == {"spend", "tokens", "events", "sessions"}
+    assert d["kpi_deltas"]["spend"] is None
+    assert d["kpi_prev"]["spend"] == 0
+
+
+@pytest.mark.asyncio
+async def test_kpi_delta_non_null_when_prior_window_has_data():
+    """#217: a real period-over-period % when both the current and prior
+    equal-length windows carry data (the seed spans 4 consecutive days, so a
+    2-day window's prior 2 days are non-empty)."""
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, "metric=spend&group_by=model&since=2d")
+    assert d["kpi_prev"]["spend"] > 0, "prior window should have seeded data"
+    assert d["kpi_deltas"]["spend"] is not None
+    assert isinstance(d["kpi_deltas"]["spend"], float)

tokenjam-0.5.0/tests/integration/test_cmd_route.py

@@ -0,0 +1,163 @@
+"""Integration tests for the `tj route` CLI surface (CliRunner)."""
+from __future__ import annotations
+
+import json
+from datetime import timedelta
+from unittest.mock import patch
+
+import pytest
+from click.testing import CliRunner
+
+from tokenjam.cli.main import cli
+from tokenjam.core.config import TjConfig
+from tokenjam.core.db import InMemoryBackend
+from tokenjam.utils.time_parse import utcnow
+from tests.factories import make_llm_span, make_tool_span
+
+
+@pytest.fixture
+def db():
+    backend = InMemoryBackend()
+    yield backend
+    backend.close()
+
+
+@pytest.fixture
+def config():
+    return TjConfig(version="1")
+
+
+@pytest.fixture
+def runner():
+    return CliRunner()
+
+
+@pytest.fixture(autouse=True)
+def _exports_in_tmp(monkeypatch, tmp_path):
+    """Redirect ~/.config/tokenjam/exports to a tmp dir so tests never touch
+    the real home directory."""
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    return tmp_path
+
+
+def _seed_downsize_candidate(db, session_id="s-small"):
+    """One small Opus session + 2 tool spans — matches the downsize heuristic,
+    so build_report yields a downgrade finding with a suggestion."""
+    start = utcnow() - timedelta(days=2)
+    llm = make_llm_span(
+        agent_id="claude-code-x", model="claude-opus-4-7", provider="anthropic",
+        input_tokens=1000, output_tokens=200, cost_usd=0.030,
+        session_id=session_id, start_time=start,
+    )
+    db.insert_span(llm)
+    for _ in range(2):
+        tool = make_tool_span(agent_id="claude-code-x", tool_name="Read",
+                              trace_id=llm.trace_id)
+        tool.session_id = session_id
+        tool.start_time = start
+        db.insert_span(tool)
+
+
+def _invoke(runner, db, config, args):
+    with patch("tokenjam.cli.main.load_config", return_value=config), \
+         patch("tokenjam.cli.main.open_db", return_value=db):
+        return runner.invoke(cli, args)
+
+
+# --- export writes a valid config with honesty comments --------------------
+
+@pytest.mark.parametrize("target,ext", [("ccr", "jsonc"), ("litellm", "yaml")])
+def test_export_writes_config_with_caveat(runner, db, config, _exports_in_tmp, target, ext):
+    _seed_downsize_candidate(db)
+    result = _invoke(runner, db, config, ["route", "export", "--target", target])
+    assert result.exit_code == 0, result.output
+
+    exports = _exports_in_tmp / ".config" / "tokenjam" / "exports"
+    written = list(exports.glob(f"{target}-*.{ext}"))
+    assert len(written) == 1, f"expected one {target} export, got {written}"
+    body = written[0].read_text()
+    # honesty strings embedded
+    assert "Candidate-flagging heuristic" in body          # MODEL_DOWNGRADE_CAVEAT
+    assert "evidence: L1" in body
+    assert "Derivation window:" in body
+    assert "Derived at:" in body
+    # the suggestion made it in
+    assert "claude-haiku-4-5" in body
+
+
+def test_export_only_writes_to_exports_dir(runner, db, config, _exports_in_tmp):
+    """Nothing outside ~/.config/tokenjam/exports/ is created."""
+    _seed_downsize_candidate(db)
+    _invoke(runner, db, config, ["route", "export", "--target", "litellm"])
+    # The only thing under the fake home is the exports tree.
+    created = [p for p in _exports_in_tmp.rglob("*") if p.is_file()]
+    assert created, "expected an export file"
+    for p in created:
+        assert ".config/tokenjam/exports" in str(p), p
+
+
+def test_export_json_output(runner, db, config):
+    _seed_downsize_candidate(db)
+    result = _invoke(runner, db, config,
+                     ["route", "export", "--target", "ccr", "--json"])
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["target"] == "ccr"
+    assert payload["rule_count"] == 1
+    assert payload["path"].endswith(".jsonc")
+
+
+def test_export_requires_target_or_check(runner, db, config):
+    _seed_downsize_candidate(db)
+    result = _invoke(runner, db, config, ["route", "export"])
+    assert result.exit_code != 0
+    assert "--target" in result.output
+
+
+# --- --check staleness ------------------------------------------------------
+
+def test_check_reports_no_export_then_current_then_stale(runner, db, config):
+    _seed_downsize_candidate(db)
+
+    # 1. No export yet.
+    r1 = _invoke(runner, db, config,
+                 ["route", "export", "--check", "--target", "ccr", "--json"])
+    assert r1.exit_code == 0, r1.output
+    assert json.loads(r1.output)["results"][0]["status"] == "no_export"
+
+    # 2. Export, then check → current.
+    _invoke(runner, db, config, ["route", "export", "--target", "ccr"])
+    r2 = _invoke(runner, db, config,
+                 ["route", "export", "--check", "--target", "ccr", "--json"])
+    assert json.loads(r2.output)["results"][0]["status"] == "current"
+
+    # 3. Findings change (add a second distinct candidate model) → stale.
+    start = utcnow() - timedelta(days=1)
+    llm = make_llm_span(
+        agent_id="claude-code-x", model="claude-sonnet-4-5", provider="anthropic",
+        input_tokens=900, output_tokens=150, cost_usd=0.02,
+        session_id="s-small-2", start_time=start,
+    )
+    db.insert_span(llm)
+    for _ in range(2):
+        t = make_tool_span(agent_id="claude-code-x", tool_name="Read",
+                           trace_id=llm.trace_id)
+        t.session_id = "s-small-2"
+        t.start_time = start
+        db.insert_span(t)
+    r3 = _invoke(runner, db, config,
+                 ["route", "export", "--check", "--target", "ccr", "--json"])
+    assert json.loads(r3.output)["results"][0]["status"] == "stale"
+
+
+# --- the existing claude_code alias must still work ------------------------
+
+def test_optimize_export_config_still_works(runner, db, config, _exports_in_tmp):
+    _seed_downsize_candidate(db)
+    result = _invoke(runner, db, config,
+                     ["optimize", "--export-config", "claude-code"])
+    assert result.exit_code == 0, result.output
+    exports = _exports_in_tmp / ".config" / "tokenjam" / "exports"
+    written = list(exports.glob("claude-code-*.jsonc"))
+    assert len(written) == 1, written
+    assert "routing_recommendations" in written[0].read_text()

tokenjam-0.5.0/tests/integration/test_cost_charts.py

@@ -0,0 +1,198 @@
+"""Endpoint tests for the Lens Visualizations Wave 1 cost charts (#212, #213).
+
+Covers the server-side data shaping the charts consume:
+- /cost `series` carries the reusable (bucket, agent, model, provider) group-by
+  shape with the full token-component split (#213 stacked + #210 explorer reuse).
+- /cost/cache returns per-bucket hit-rate + measured captured savings + the
+  cache analyzer's *estimated recoverable*, plus a plan-tier framing block.
+"""
+from __future__ import annotations
+
+from datetime import timedelta
+
+import httpx
+import pytest
+
+from tokenjam.api.app import create_app
+from tokenjam.core.config import ProviderBudget, TjConfig
+from tokenjam.core.db import InMemoryBackend
+from tokenjam.core.ingest import IngestPipeline
+from tokenjam.utils.time_parse import utcnow
+from tests.factories import make_llm_span, make_session, make_tool_span
+
+
+def _app(db, config):
+    return create_app(config=config, db=db, ingest_pipeline=IngestPipeline(db=db, config=config))
+
+
+def _seed(db, plan_tier="api"):
+    now = utcnow()
+    for i in range(3):
+        s = make_session(session_id=f"s{i}", plan_tier=plan_tier)
+        db.upsert_session(s)
+        db.insert_span(make_llm_span(
+            session_id=f"s{i}", model="claude-haiku-4-5", provider="anthropic",
+            input_tokens=10_000, output_tokens=500,
+            cache_tokens=4_000, cache_write_tokens=1_000,
+            cost_usd=0.02, start_time=now - timedelta(days=i),
+        ))
+
+
+@pytest.mark.asyncio
+async def test_cost_series_carries_reusable_groupby_shape():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        d = (await c.get("/api/v1/cost?since=30d&group_by=model")).json()
+    assert d["series"], "expected a window series"
+    row = d["series"][0]
+    # The group-by shape carries every dimension + the full token split so the
+    # stacked chart and the future explorer can pivot client-side.
+    for key in ("bucket", "agent_id", "model", "provider", "cost_usd",
+                "input_tokens", "output_tokens", "cache_tokens", "cache_write_tokens"):
+        assert key in row, f"series row missing {key}"
+    assert row["provider"] == "anthropic"
+    assert row["cache_tokens"] == 4_000
+
+
+@pytest.mark.asyncio
+async def test_cost_cache_endpoint_hitrate_and_captured():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        d = (await c.get("/api/v1/cost/cache?since=30d")).json()
+
+    assert d["series"], "expected per-bucket cache series"
+    p = d["series"][0]
+    # hit-rate = cache_read / (cache_read + input) = 4000 / 14000
+    assert abs(p["hit_rate"] - (4000 / 14000)) < 1e-3
+    # captured = cache_read * (input_rate - cache_read_rate) / 1e6
+    #          = 4000 * (0.80 - 0.08) / 1e6 = 0.00288  (Haiku 4.5)
+    assert abs(p["captured_usd"] - 0.00288) < 1e-6
+    assert p["captured_tokens"] == 4000
+    # window totals + estimated recoverable from the cache analyzer
+    assert d["total_captured_tokens"] == 12_000
+    assert d["estimated_recoverable_usd"] is not None
+    # framing block present (single compute path)
+    assert d["framing"]["pricing_mode"] == "api"
+
+
+@pytest.mark.asyncio
+async def test_cost_cache_framing_subscription_suppresses_dollars():
+    """Subscription plan → framing suppresses dollars; tokens stay meaningful."""
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1", budgets={"anthropic": ProviderBudget(plan="max_20x")})
+    _seed(db, plan_tier="max_20x")
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        d = (await c.get("/api/v1/cost/cache?since=30d")).json()
+    assert d["framing"]["pricing_mode"] == "subscription"
+    # token figures are still present so the UI can render the tokens framing
+    assert d["total_captured_tokens"] == 12_000
+
+
+@pytest.mark.asyncio
+async def test_cost_cache_empty_window_is_safe():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        d = (await c.get("/api/v1/cost/cache?since=7d")).json()
+    assert d["series"] == []
+    assert d["total_captured_usd"] == 0
+    assert "framing" in d
+
+
+# --- #211: cost-by-component + recoverable-waste overlay ------------------- #
+def _seed_downsize_and_cache(db, plan_tier="api"):
+    """Small Opus sessions (downsize candidate) with cache tokens (cache
+    recoverable) + tool spans, so build_report yields multiple recoverables."""
+    now = utcnow()
+    for i in range(6):
+        s = make_session(session_id=f"s{i}", plan_tier=plan_tier, agent_id="cc")
+        db.upsert_session(s)
+        llm = make_llm_span(
+            session_id=f"s{i}", agent_id="cc", model="claude-opus-4-7",
+            provider="anthropic", input_tokens=1200, output_tokens=200,
+            cache_tokens=3000, cache_write_tokens=800, cost_usd=0.05,
+            start_time=now - timedelta(days=i),
+        )
+        db.insert_span(llm)
+        for _ in range(2):
+            t = make_tool_span(agent_id="cc", tool_name="Read", trace_id=llm.trace_id)
+            t.session_id = f"s{i}"
+            t.start_time = now - timedelta(days=i)
+            db.insert_span(t)
+
+
+@pytest.mark.asyncio
+async def test_components_split_priced_per_component():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed_downsize_and_cache(db)
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        d = (await c.get("/api/v1/cost/components?since=30d")).json()
+    keys = [c["key"] for c in d["components"]]
+    assert keys == ["input", "output", "cache_read", "cache_write"]
+    by = {c["key"]: c for c in d["components"]}
+    # Opus 4.7 input rate; 6 × 1200 = 7200 input tokens. Cost must be > 0 and
+    # token volume exact.
+    assert by["input"]["tokens"] == 7200
+    assert by["cache_read"]["tokens"] == 18000
+    assert by["input"]["cost_usd"] > 0
+    assert d["framing"]["pricing_mode"] == "api"
+
+
+@pytest.mark.asyncio
+async def test_components_recoverable_is_registry_driven_and_honest():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed_downsize_and_cache(db)
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        d = (await c.get("/api/v1/cost/components?since=30d")).json()
+    rec = {r["analyzer"]: r for r in d["recoverable"]}
+    # downsize is the typed slot; reuse comes from the findings dict — its
+    # presence proves the collector is registry-driven (not a hard-coded list).
+    assert "downsize" in rec
+    assert "reuse" in rec
+    # each carries a component attribution
+    assert rec["downsize"]["component"] == "call"
+    assert rec["cache"]["component"] == "input" if "cache" in rec else True
+    # downsize keeps its mandatory caveat verbatim (Rule 14)
+    from tokenjam.core.optimize.types import MODEL_DOWNGRADE_CAVEAT
+    assert rec["downsize"]["caveat"] == MODEL_DOWNGRADE_CAVEAT
+    # honesty: the payload never calls recoverable "saved"
+    import json
+    assert "saved" not in json.dumps(d).lower()
+    assert d["total_recoverable_usd"] > 0
+
+
+@pytest.mark.asyncio
+async def test_components_subscription_framing_suppresses_dollars():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1", budgets={"anthropic": ProviderBudget(plan="max_20x")})
+    _seed_downsize_and_cache(db, plan_tier="max_20x")
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        d = (await c.get("/api/v1/cost/components?since=30d")).json()
+    assert d["framing"]["pricing_mode"] == "subscription"
+    # token volumes stay present so the UI can render the tokens framing
+    assert sum(c["tokens"] for c in d["components"]) > 0
+
+
+@pytest.mark.asyncio
+async def test_components_empty_window_is_safe():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        d = (await c.get("/api/v1/cost/components?since=7d")).json()
+    assert d["total_cost_usd"] == 0
+    assert d["recoverable"] == []
+    assert "framing" in d