agent-decoder 0.3.2__py3-none-any.whl

clau_decode/_auth_env.py

@@ -0,0 +1,118 @@
+"""Shared spawn-environment construction for claude-compatible binaries.
+
+Centralises the "strip API-key vars or pass them through?" decision so all
+PTY-backed spawn sites apply identical rules.
+
+Decision matrix
+---------------
+
+``authMethod`` returned by ``<bin> auth status``:
+
+- ``"claude.ai"`` — subscription auth. Strip ``ANTHROPIC_API_KEY`` and
+  ``ANTHROPIC_AUTH_TOKEN`` from the spawn env, even if the user set them.
+  This is the original billing safeguard: a stale env var would silently
+  re-route traffic to an API account the user may not have intended to bill.
+- ``"api_key"`` — pass everything through. The binary is self-aware that it
+  uses API key auth; both the env key and any other config it cares about
+  should reach the spawn.
+- ``"none"`` / probe failure / unknown — pass everything through. The probe
+  is unreliable for env-based wrappers (e.g. cc-mirror's ``zai``, which
+  unsets the token before the probe runs, so the probe never sees it as
+  ``api_key``). Stripping here would break the wrapper's only authentication
+  path. The trade-off: a user with ``ANTHROPIC_API_KEY`` exported and a
+  binary that reports ``"none"`` will route to that key — but that requires
+  the user to have explicitly exported the key, which is their signal.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json as _json
+import os
+from typing import Final
+
+_SUBSCRIPTION_BLOCKED_ENV: Final = frozenset(
+    {"ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"}
+)
+
+# Session-identity vars the `claude` CLI sets on itself so a nested/child
+# invocation can detect it's not a top-level session (e.g. it disables
+# transcript saving). If clau-decode's own server process was launched from
+# inside a Claude Code session, these leak into ``os.environ`` and — because
+# spawn_env otherwise starts from a raw copy of it — get inherited by every
+# native PTY clau-decode spawns, making an unrelated top-level `claude`
+# session falsely believe it's a child of another one. Every PTY clau-decode
+# spawns is its own top-level session, so these must never survive the copy.
+_SESSION_IDENTITY_BLOCKED_ENV: Final = frozenset({"CLAUDE_CODE_CHILD_SESSION"})
+
+_AUTH_PROBE_TIMEOUT_S: Final = 5.0
+
+
+def _strip_session_identity_env(env: dict[str, str]) -> dict[str, str]:
+    """Remove Claude-Code session-identity markers that must never be inherited."""
+    for key in _SESSION_IDENTITY_BLOCKED_ENV:
+        env.pop(key, None)
+    return env
+
+
+def _subscription_env() -> dict[str, str]:
+    """Pure strip helper: ``os.environ`` minus the API-key vars.
+
+    Exposed for tests and as a primitive for ``spawn_env``. Direct callers
+    outside tests should prefer ``spawn_env(bin_name)`` so the strip is
+    gated by the binary's actual auth method.
+    """
+    env = {
+        k: v for k, v in os.environ.items() if k not in _SUBSCRIPTION_BLOCKED_ENV
+    }
+    return _strip_session_identity_env(env)
+
+
+async def _bin_auth_method(bin_name: str) -> str:
+    """Probe ``<bin_name> auth status`` for its ``authMethod`` string.
+
+    Returns the method name (``"claude.ai"`` / ``"api_key"`` / ``"none"``)
+    or ``""`` on any probe failure (spawn error, non-zero exit, JSON parse
+    failure, or timeout). Callers must treat ``""`` and ``"none"`` the same.
+
+    Inherits the full parent env so the probe can see any API key the user
+    has exported — some wrappers report ``"api_key"`` when a key is present
+    and ``"none"`` otherwise.
+    """
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            bin_name,
+            "auth",
+            "status",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+    except (FileNotFoundError, PermissionError):
+        return ""
+    try:
+        stdout, _stderr = await asyncio.wait_for(
+            proc.communicate(), timeout=_AUTH_PROBE_TIMEOUT_S
+        )
+    except asyncio.TimeoutError:
+        proc.kill()
+        return ""
+    if proc.returncode != 0:
+        return ""
+    try:
+        data = _json.loads(stdout.decode("utf-8", errors="replace"))
+    except _json.JSONDecodeError:
+        return ""
+    method = data.get("authMethod") if isinstance(data, dict) else None
+    return str(method) if isinstance(method, str) else ""
+
+
+async def spawn_env(bin_name: str) -> dict[str, str]:
+    """Build the spawn env for ``bin_name``.
+
+    See module docstring for the strip/keep decision matrix. The returned
+    dict starts from ``os.environ`` and is safe to mutate (it's a copy).
+    """
+    auth_method = await _bin_auth_method(bin_name)
+    if auth_method == "claude.ai":
+        return _subscription_env()
+    return _strip_session_identity_env(dict(os.environ))

clau_decode/_pty_preexec.py

@@ -0,0 +1,42 @@
+"""PTY controlling-TTY attach wrapper.
+
+uvloop's subprocess implementation does not run ``preexec_fn`` for safety
+reasons (libuv constraint). The PTY runner needs ``setsid()`` +
+``TIOCSCTTY`` on the slave fd before the spawned ``claude`` binary's main()
+runs, or the TUI will fail to render.
+
+Solution: invoke this wrapper as the entry point. It performs the
+controlling-TTY claim in the *child* process (after Python's subprocess
+infrastructure has dup2'd the slave fd into fd 0/1/2), then ``execvp`` into
+the real target binary. From here on the child is fully detached and runs
+under its own session with the slave as its controlling TTY.
+
+Usage:
+    python3 -m clau_decode._pty_preexec <bin_name> [args...]
+
+The first argv after the module name is the target binary; remaining args
+are forwarded.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import sys
+import termios
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        sys.stderr.write("usage: _pty_preexec <binary> [args...]\n")
+        raise SystemExit(2)
+
+    os.setsid()
+    fcntl.ioctl(0, termios.TIOCSCTTY, 0)
+
+    target = sys.argv[1]
+    os.execvp(target, sys.argv[1:])
+
+
+if __name__ == "__main__":
+    main()

clau_decode/analytics/aggregator.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+from datetime import date, timezone
+from clau_decode.models import Message
+from .extractor import DeduplicatingExtractor, TokenExtractor
+from .models import DailyBucket, TokenBreakdown
+
+
+class SessionAggregator:
+    """Aggregate token breakdowns across all messages in a session."""
+
+    def __init__(self, extractor: TokenExtractor) -> None:
+        self._extractor = extractor
+
+    def aggregate(self, messages: list[Message]) -> TokenBreakdown:
+        dedup = DeduplicatingExtractor(self._extractor)
+        total = TokenBreakdown()
+        for msg in messages:
+            total = total + dedup.extract(msg)
+        return total
+
+
+class DailyAggregator:
+    """Bucket messages into UTC calendar days."""
+
+    def __init__(self, extractor: TokenExtractor) -> None:
+        self._extractor = extractor
+
+    def aggregate(self, messages: list[Message]) -> list[DailyBucket]:
+        dedup = DeduplicatingExtractor(self._extractor)
+        by_id: dict[str, Message] = {m.id: m for m in messages}
+        buckets: dict[date, DailyBucket] = {}
+        seen_sessions: dict[date, set[str]] = {}
+        for msg in messages:
+            if msg.timestamp is None:
+                continue
+            day = msg.timestamp.astimezone(timezone.utc).date()
+            bd = dedup.extract(msg)
+            if bd.total == 0:
+                continue
+            if day not in buckets:
+                buckets[day] = DailyBucket(day=day)
+                seen_sessions[day] = set()
+            buckets[day].breakdown = buckets[day].breakdown + bd
+            seen_sessions[day].add(msg.session_id)
+            if (
+                msg.role == "assistant"
+                and not msg.is_sidechain
+                and not msg.is_meta
+                and msg.parent_id in by_id
+                and by_id[msg.parent_id].role == "user"
+            ):
+                buckets[day].prompt_count += 1
+        for day, bucket in buckets.items():
+            bucket.session_count = len(seen_sessions[day])
+        return sorted(buckets.values(), key=lambda b: b.day)

clau_decode/analytics/cost.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from .models import PromptCost, TokenBreakdown
+
+if TYPE_CHECKING:
+    from .pricing import CachedPricingStrategy, ModelPricing
+
+
+@dataclass
+class SessionCost:
+    model: str
+    pricing: "ModelPricing | None"
+    breakdown: TokenBreakdown
+    input_usd: Decimal
+    output_usd: Decimal
+    cache_write_usd: Decimal
+    cache_read_usd: Decimal
+    total_usd: Decimal
+
+
+@dataclass
+class MultiModelCost:
+    models: list[SessionCost]
+    total_usd: Decimal
+
+
+class CostEngine:
+    """Compute USD cost for a model+breakdown pair using a pricing strategy."""
+
+    def __init__(self, strategy: "CachedPricingStrategy") -> None:
+        self._strategy = strategy
+
+    def compute(self, model: str, breakdown: TokenBreakdown) -> SessionCost:
+        pricing = self._strategy.get_pricing(model)
+        if pricing is None:
+            zero = Decimal("0")
+            return SessionCost(
+                model=model,
+                pricing=None,
+                breakdown=breakdown,
+                input_usd=zero,
+                output_usd=zero,
+                cache_write_usd=zero,
+                cache_read_usd=zero,
+                total_usd=zero,
+            )
+        M = Decimal("1000000")
+        inp = pricing.input_per_mtok * breakdown.input_tokens / M
+        out = pricing.output_per_mtok * breakdown.output_tokens / M
+        cw = pricing.cache_write_per_mtok * breakdown.cache_creation_tokens / M
+        cr = pricing.cache_read_per_mtok * breakdown.cache_read_tokens / M
+        return SessionCost(
+            model=model,
+            pricing=pricing,
+            breakdown=breakdown,
+            input_usd=inp,
+            output_usd=out,
+            cache_write_usd=cw,
+            cache_read_usd=cr,
+            total_usd=inp + out + cw + cr,
+        )
+
+    def compute_multi(self, prompts: list[PromptCost]) -> MultiModelCost:
+        by_model: dict[str, TokenBreakdown] = {}
+        for p in prompts:
+            bd = by_model.setdefault(p.model, TokenBreakdown())
+            by_model[p.model] = bd + p.breakdown
+        results: list[SessionCost] = []
+        for model, bd in sorted(by_model.items()):
+            results.append(self.compute(model, bd))
+        total = sum((r.total_usd for r in results), Decimal("0"))
+        return MultiModelCost(models=results, total_usd=total)

clau_decode/analytics/extractor.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+from clau_decode.models import Message
+from .models import TokenBreakdown
+
+
+class TokenExtractor:
+    """Extract a TokenBreakdown from a single Message."""
+
+    def extract(self, message: Message) -> TokenBreakdown:
+        if message.usage is None:
+            return TokenBreakdown()
+        u = message.usage
+        return TokenBreakdown(
+            input_tokens=u.input_tokens,
+            output_tokens=u.output_tokens,
+            cache_creation_tokens=u.cache_creation_input_tokens,
+            cache_read_tokens=u.cache_read_input_tokens,
+        )
+
+
+class DeduplicatingExtractor:
+    """Wraps an extractor; returns zero breakdown for duplicate message IDs."""
+
+    def __init__(self, inner: TokenExtractor) -> None:
+        self._inner = inner
+        self.seen_ids: set[str] = set()
+
+    def extract(self, message: Message) -> TokenBreakdown:
+        if message.id in self.seen_ids:
+            return TokenBreakdown()
+        self.seen_ids.add(message.id)
+        return self._inner.extract(message)

clau_decode/analytics/fast.py

@@ -0,0 +1,289 @@
+"""SQL-backed analytics over the full message corpus.
+
+The Python scanners (``stats.py`` / ``service.py``) answer the dashboard's
+all-message questions by loading every row — ``SELECT *`` pulls ~500 MB of
+``content_json`` and ~145k rows become pydantic ``Message`` objects (~9 s) —
+then scanning in memory. These functions compute the **identical shapes**
+from data materialized at ingest:
+
+  - per-message token columns (``input_tokens`` … ``cache_read_tokens``)
+  - the ``message_blocks`` table (one row per tool_use / tool_result block,
+    with tool name, file path, and result char-count already extracted)
+
+So the dashboard never reads ``content_json`` at query time — it aggregates
+small indexed columns. Empirically ~1 s cold vs ~9 s, and the existing
+signature cache keeps warm loads at ~3 ms.
+
+Verified byte-for-byte against the scanners in
+``tests/analytics/test_fast_parity.py``. Per-session/small-list analytics
+keep using the scanners — these are only for the whole-corpus dashboard.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from clau_decode.models import Message, TokenUsage, ToolResultBlock, ToolUseBlock
+
+from .stats import compute_stats
+from .tips import (
+    _SEVERITY_ORDER,
+    _WRITE_TOOLS,
+    LowCacheHitRule,
+    OversizedToolResultRule,
+    RepeatedFileReadRule,
+)
+
+# Read + write tool names that drive RepeatedFileReadRule's state machine;
+# every other tool_use is a no-op there, so we only fetch these.
+_RW_TOOLS = ("Read", *sorted(_WRITE_TOOLS))
+
+
+async def _rows(conn, sql: str, params: tuple = ()) -> list:
+    async with conn.execute(sql, params) as cur:
+        return await cur.fetchall()
+
+
+async def _build_usage(conn) -> None:
+    """Materialize a small per-message usage temp table in ONE scan, so the
+    four usage aggregates (daily / models / prompt_stats / cache rollup)
+    don't each re-scan the 145k-row messages table. The parent role/meta
+    flags that ``daily`` and ``prompt_stats`` need are resolved here via a
+    single PK self-join instead of one join per aggregate.
+    """
+    await conn.execute("PRAGMA temp_store=MEMORY")
+    await conn.execute("DROP TABLE IF EXISTS temp._usage")
+    await conn.execute(
+        """
+        CREATE TEMP TABLE _usage AS
+        SELECT date(m.timestamp) AS day, m.session_id AS session_id, m.role AS role,
+               m.is_sidechain AS is_sidechain, m.is_meta AS is_meta,
+               CASE WHEN m.usage_json IS NOT NULL THEN 1 ELSE 0 END AS has_usage,
+               m.model AS model,
+               COALESCE(m.input_tokens,0) AS it, COALESCE(m.output_tokens,0) AS ot,
+               COALESCE(m.cache_creation_tokens,0) AS cc,
+               COALESCE(m.cache_read_tokens,0) AS cr,
+               CASE WHEN p.id IS NOT NULL AND p.role='user' THEN 1 ELSE 0 END
+                   AS parent_is_user,
+               CASE WHEN p.id IS NOT NULL AND p.is_meta=1 THEN 1 ELSE 0 END
+                   AS parent_is_meta
+        FROM messages m LEFT JOIN messages p ON m.parent_id = p.id
+        """
+    )
+
+
+async def _drop_usage(conn) -> None:
+    await conn.execute("DROP TABLE IF EXISTS temp._usage")
+
+
+async def daily(conn) -> list[dict[str, Any]]:
+    """Per-UTC-day token totals + prompt/session counts (from ``_usage``).
+    Mirrors ``DailyAggregator``: only non-zero-usage messages contribute;
+    ``prompt_count`` counts non-sidechain/non-meta assistant messages whose
+    parent is a user message; ``session_count`` is the distinct sessions."""
+    sql = """
+      SELECT day,
+             SUM(it) AS it, SUM(ot) AS ot, SUM(cc) AS cc, SUM(cr) AS cr,
+             COUNT(DISTINCT session_id) AS sessions,
+             SUM(CASE WHEN role='assistant' AND is_sidechain=0 AND is_meta=0
+                       AND parent_is_user=1 THEN 1 ELSE 0 END) AS prompts
+      FROM _usage
+      WHERE day IS NOT NULL AND (it+ot+cc+cr) > 0
+      GROUP BY day ORDER BY day ASC
+    """
+    out = []
+    for r in await _rows(conn, sql):
+        it, ot, cc, cr = r["it"], r["ot"], r["cc"], r["cr"]
+        out.append(
+            {
+                "day": r["day"],
+                "input_tokens": it,
+                "output_tokens": ot,
+                "cache_creation_tokens": cc,
+                "cache_read_tokens": cr,
+                "total": it + ot + cc + cr,
+                "prompt_count": r["prompts"],
+                "session_count": r["sessions"],
+            }
+        )
+    return out
+
+
+async def models(conn) -> list[dict[str, Any]]:
+    """Token usage per model (from ``_usage``). Mirrors ``ModelUsageScanner``:
+    assistant messages with a model and a usage block, sorted by total desc."""
+    sql = """
+      SELECT model, COUNT(*) AS message_count,
+             SUM(it) AS input_tokens, SUM(ot) AS output_tokens,
+             SUM(it+ot+cc+cr) AS total_tokens
+      FROM _usage
+      WHERE role='assistant' AND model IS NOT NULL AND model != '' AND has_usage=1
+      GROUP BY model ORDER BY total_tokens DESC, model ASC
+    """
+    return [
+        {
+            "model": r["model"],
+            "message_count": r["message_count"],
+            "input_tokens": r["input_tokens"],
+            "output_tokens": r["output_tokens"],
+            "total_tokens": r["total_tokens"],
+        }
+        for r in await _rows(conn, sql)
+    ]
+
+
+async def prompt_stats(conn) -> dict[str, Any]:
+    """Distribution of per-prompt token counts (from ``_usage``). Mirrors
+    ``PromptStatsScanner`` + ``PromptIterator``: one prompt per non-sidechain
+    assistant message whose parent is a non-meta user message; percentiles
+    reuse the canonical ``compute_stats``."""
+    sql = """
+      SELECT it, ot, (it+ot+cc+cr) AS tot FROM _usage
+      WHERE role='assistant' AND is_sidechain=0
+            AND parent_is_user=1 AND parent_is_meta=0
+    """
+    inputs, outputs, totals = [], [], []
+    for r in await _rows(conn, sql):
+        inputs.append(r["it"])
+        outputs.append(r["ot"])
+        totals.append(r["tot"])
+    return {
+        "prompt_count": len(inputs),
+        "input_tokens": compute_stats(inputs),
+        "output_tokens": compute_stats(outputs),
+        "total_tokens": compute_stats(totals),
+    }
+
+
+async def _low_cache_totals(conn) -> tuple[int, int]:
+    """(total_input, total_cache_read) over assistant messages with usage
+    (from ``_usage``) — the inputs LowCacheHitRule needs."""
+    row = (
+        await _rows(
+            conn,
+            "SELECT SUM(it+cr+cc) AS total_input, SUM(cr) AS cache_read "
+            "FROM _usage WHERE role='assistant' AND has_usage=1",
+        )
+    )[0]
+    return row["total_input"] or 0, row["cache_read"] or 0
+
+
+def _fake_msg(blocks: list) -> Message:
+    """Minimal Message carrying just content blocks, so the real tip rules
+    run unchanged on materialized data (guarantees byte-for-byte parity)."""
+    return Message(id="x", session_id="x", role="assistant", content_blocks=blocks)
+
+
+async def _tips(conn, cache_totals: tuple[int, int]) -> list[dict[str, Any]]:
+    """Reproduce ``TipRegistry`` by running the real rule classes on minimal
+    messages rebuilt from ``message_blocks`` + the cache rollup, so
+    heuristics, copy, and ordering stay identical to the scanners.
+
+    ``cache_totals`` is ``(total_input, total_cache_read)`` from the usage
+    pass, reused here so LowCacheHit needs no extra scan.
+    """
+    placeholders = ",".join("?" * len(_RW_TOOLS))
+    rw_rows = await _rows(
+        conn,
+        f"""SELECT mb.tool_name AS name, mb.file_path AS path
+            FROM message_blocks mb JOIN messages m ON mb.message_id = m.id
+            WHERE mb.btype='tool_use' AND mb.tool_name IN ({placeholders})
+            ORDER BY m.timestamp, m.rowid, mb.block_index""",
+        _RW_TOOLS,
+    )
+    repeated = RepeatedFileReadRule().check(
+        [
+            _fake_msg(
+                [
+                    ToolUseBlock(
+                        id="t", name=r["name"], input={"file_path": r["path"] or ""}
+                    )
+                ]
+            )
+            for r in rw_rows
+        ]
+    )
+
+    over_rows = await _rows(
+        conn,
+        """SELECT mb.tool_use_id AS tid, mb.result_chars AS chars
+           FROM message_blocks mb JOIN messages m ON mb.message_id = m.id
+           WHERE mb.btype='tool_result' AND mb.result_chars >= ?
+           ORDER BY m.timestamp, m.rowid, mb.block_index""",
+        (OversizedToolResultRule()._threshold,),
+    )
+    oversized = OversizedToolResultRule().check(
+        [
+            _fake_msg(
+                [ToolResultBlock(tool_use_id=r["tid"] or "", content="x" * r["chars"])]
+            )
+            for r in over_rows
+        ]
+    )
+
+    total_input, cache_read = cache_totals
+    usage_msg = _fake_msg([])
+    usage_msg.usage = TokenUsage(
+        input_tokens=total_input - cache_read, cache_read_input_tokens=cache_read
+    )
+    low_cache = LowCacheHitRule().check([usage_msg])
+
+    tips = sorted(
+        repeated + oversized + low_cache,
+        key=lambda t: _SEVERITY_ORDER.get(t.severity, 99),
+    )
+    return [
+        {
+            "rule_id": t.rule_id,
+            "severity": t.severity,
+            "title": t.title,
+            "detail": t.detail,
+            "evidence": t.evidence,
+        }
+        for t in tips
+    ]
+
+
+async def compute_bundle(conn, files_top_n: int = 20) -> dict[str, Any]:
+    """The whole-corpus analytics bundle, entirely from materialized data.
+
+    No ``content_json`` is read: token metrics come from per-message columns,
+    tool/file/tip facts from ``message_blocks``. Verified against the Python
+    scanners in ``tests/analytics/test_fast_parity.py``.
+
+    Counts match the scanners exactly; the order *among equal counts* uses a
+    deterministic name tiebreak rather than the scanners' first-seen order
+    (matching it needs a join + per-row composite key that cost ~600ms for a
+    purely cosmetic chart ordering).
+    """
+    # One scan into a per-message temp table feeds all four usage aggregates.
+    await _build_usage(conn)
+    try:
+        daily_r = await daily(conn)
+        models_r = await models(conn)
+        stats_r = await prompt_stats(conn)
+        cache_totals = await _low_cache_totals(conn)
+    finally:
+        await _drop_usage(conn)
+
+    tool_rows = await _rows(
+        conn,
+        """SELECT tool_name AS name, COUNT(*) AS n FROM message_blocks
+           WHERE btype='tool_use' AND tool_name IS NOT NULL
+           GROUP BY tool_name ORDER BY n DESC, tool_name ASC""",
+    )
+    file_rows = await _rows(
+        conn,
+        """SELECT file_path AS path, COUNT(*) AS n FROM message_blocks
+           WHERE btype='tool_use' AND file_path IS NOT NULL AND file_path != ''
+           GROUP BY file_path ORDER BY n DESC, file_path ASC LIMIT ?""",
+        (files_top_n,),
+    )
+    return {
+        "daily": daily_r,
+        "models": models_r,
+        "stats": stats_r,
+        "tools": [{"tool": r["name"], "count": r["n"]} for r in tool_rows],
+        "files": [{"file": r["path"], "count": r["n"]} for r in file_rows],
+        "tips": await _tips(conn, cache_totals),
+    }

clau_decode/analytics/models.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from datetime import date
+
+
+@dataclass
+class TokenBreakdown:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_tokens: int = 0
+    cache_read_tokens: int = 0
+
+    @property
+    def total(self) -> int:
+        return (
+            self.input_tokens
+            + self.output_tokens
+            + self.cache_creation_tokens
+            + self.cache_read_tokens
+        )
+
+    def __add__(self, other: "TokenBreakdown") -> "TokenBreakdown":
+        return TokenBreakdown(
+            input_tokens=self.input_tokens + other.input_tokens,
+            output_tokens=self.output_tokens + other.output_tokens,
+            cache_creation_tokens=self.cache_creation_tokens
+            + other.cache_creation_tokens,
+            cache_read_tokens=self.cache_read_tokens + other.cache_read_tokens,
+        )
+
+
+@dataclass
+class PromptCost:
+    """Token breakdown for a single user→assistant turn."""
+
+    user_message_id: str
+    assistant_message_id: str
+    model: str = "unknown"
+    breakdown: TokenBreakdown = field(default_factory=TokenBreakdown)
+
+
+@dataclass
+class DailyBucket:
+    """Aggregated token breakdown for a UTC calendar day."""
+
+    day: date
+    breakdown: TokenBreakdown = field(default_factory=TokenBreakdown)
+    session_count: int = 0
+    prompt_count: int = 0