Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(costs): meter every provider call through a shared usage ledger

rubenluetke10-beep39f247ad1b14
diff --git a/jarvis/agent_chat/runner_api.py b/jarvis/agent_chat/runner_api.py
index 5fe0474134..cccf1e8d98 100644
--- a/jarvis/agent_chat/runner_api.py
+++ b/jarvis/agent_chat/runner_api.py
@@ -523,7 +523,11 @@ async def _run_gated_tool(
async def _stream(brain: Any, req: BrainRequest, cancel: asyncio.Event):
"""Iterate the brain stream, ending early when ``cancel`` is set."""
- agen = brain.complete(req)
+ from jarvis.costs.ledger import usage_context
+
+ # The chat store records this turn's usage itself (``turn_finished``).
+ with usage_context("agent-chat"):
+ agen = brain.complete(req)
try:
while True:
if cancel.is_set():
diff --git a/jarvis/awareness/verdichter.py b/jarvis/awareness/verdichter.py
index 643921fc3c..e661ec1485 100644
--- a/jarvis/awareness/verdichter.py
+++ b/jarvis/awareness/verdichter.py
@@ -20,6 +20,14 @@ with an empty summary instead of crashing.
"""
from __future__ import annotations
+from jarvis.costs.ledger import usage_context
+
+
+def _tagged_complete(brain, request): # type: ignore[no-untyped-def]
+ """The digest's model calls are ledgered as awareness work."""
+ with usage_context("awareness"):
+ return brain.complete(request)
+
import asyncio
import logging
import time
@@ -115,7 +123,7 @@ class Verdichter:
start_ns = time.time_ns()
try:
agg = await asyncio.wait_for(
- aggregate(self._brain.complete(request)),
+ aggregate(_tagged_complete(self._brain, request)),
timeout=self._config.timeout_s,
)
except TimeoutError:
diff --git a/jarvis/brain/provider_registry.py b/jarvis/brain/provider_registry.py
index d09ffbd38e..d918875119 100644
--- a/jarvis/brain/provider_registry.py
+++ b/jarvis/brain/provider_registry.py
@@ -51,7 +51,12 @@ class BrainProviderRegistry:
f"Failed: {list(self._failed.keys())}"
)
cls = self._classes[name]
- return cls(**kwargs)
+ from jarvis.brain.usage_meter import meter_brain
+
+ # Every instance leaves here metered: whatever asks it for tokens —
+ # a voice turn, the wiki curator, a dictation polish — is written to
+ # the usage ledger without the caller having to know (BUG-178).
+ return meter_brain(cls(**kwargs), name)
def get_class(self, name: str) -> type:
self._load()
diff --git a/jarvis/brain/usage_meter.py b/jarvis/brain/usage_meter.py
new file mode 100644
index 0000000000..a003546b30
--- /dev/null
+++ b/jarvis/brain/usage_meter.py
@@ -0,0 +1,135 @@
+"""Wrap a brain provider so every call it answers is written to the ledger.
+
+Applied once, at construction, by :class:`jarvis.brain.provider_registry.
+BrainProviderRegistry` — the one door every provider instance comes through
+(the manager, the resolver, the health check, the vision brain). Callers keep
+the object they always had: attributes forward, ``estimate_cost`` forwards,
+``isinstance`` against the plugin class is the one thing that changes, and
+nothing in the tree does that.
+
+The usage block a plugin yields follows the canonical contract
+(``input_tokens`` = uncached input, ``cache_hit_tokens`` = cache reads,
+``output_tokens``). ``complete`` is a plain ``def`` that returns an async
+generator, exactly like the plugins, so both calling conventions in the tree
+keep working; the caller tag is read when ``complete`` is CALLED, so a
+``usage_context`` around the call expression is enough even when the stream
+is consumed later.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+
+from jarvis.core.protocols import BrainDelta, BrainRequest
+from jarvis.costs.ledger import current_caller, record_usage
+
+log = logging.getLogger(__name__)
+
+_IN_KEYS = ("input_tokens", "prompt_tokens")
+_OUT_KEYS = ("output_tokens", "completion_tokens")
+_CACHED_KEYS = ("cache_hit_tokens", "cache_read_input_tokens", "cached_input_tokens")
+
+
+def _totals(usage: dict[str, Any]) -> tuple[int, int, int]:
+ def first(keys: tuple[str, ...]) -> int:
+ for key in keys:
+ value = usage.get(key)
+ if value is not None:
+ try:
+ return max(0, int(value))
+ except (TypeError, ValueError):
+ return 0
+ return 0
+
+ return first(_IN_KEYS), first(_OUT_KEYS), first(_CACHED_KEYS)
+
+
+class MeteredBrain:
+ """A :class:`~jarvis.core.protocols.Brain` that reports what it spent."""
+
+ __slots__ = ("_inner", "_provider_name")
+
+ def __init__(self, inner: Any, provider_name: str) -> None:
+ object.__setattr__(self, "_inner", inner)
+ object.__setattr__(self, "_provider_name", provider_name)
+
+ # -- forwarding ------------------------------------------------------
+
+ def __getattr__(self, name: str) -> Any:
+ return getattr(self._inner, name)
+
+ def __setattr__(self, name: str, value: Any) -> None:
+ setattr(self._inner, name, value)
+
+ def __repr__(self) -> str: # pragma: no cover — logging nicety
+ return f"MeteredBrain({self._inner!r})"
+
+ @property
+ def unwrapped(self) -> Any:
+ return self._inner
+
+ @property # type: ignore[misc]
+ def __class__(self) -> type: # type: ignore[override]
+ # ``isinstance(provider, SomePluginClass)`` keeps its answer: the
+ # pipeline asks exactly that of its brain (a subscription voice brain
+ # is handled differently), and a wrapper must not change it.
+ return type(self._inner)
+
+ def estimate_cost(self, req: BrainRequest) -> float:
+ return float(self._inner.estimate_cost(req))
+
+ # -- the metered call ---------------------------------------------------
+
+ def complete(self, req: BrainRequest) -> AsyncIterator[BrainDelta]:
+ caller = current_caller()
+ return self._metered(self._inner.complete(req), caller, self._model_of(req))
+
+ def _model_of(self, req: BrainRequest) -> str:
+ """The model the call runs on: the request's override, else whatever
+ the plugin calls its configured model."""
+ for source, attr in ((req, "model"), (self._inner, "model"), (self._inner, "_model"),
+ (self._inner, "model_name"), (self._inner, "_model_name")):
+ value = getattr(source, attr, None)
+ if isinstance(value, str) and value:
+ return value
+ return ""
+
+ async def _metered(
+ self, stream: AsyncIterator[BrainDelta], caller: str, model: str
+ ) -> AsyncIterator[BrainDelta]:
+ tokens_in = tokens_out = tokens_cached = 0
+ seen = False
+ try:
+ async for delta in stream:
+ usage = getattr(delta, "usage", None)
+ if isinstance(usage, dict) and usage:
+ # One call reports its usage once, on its last chunk; a
+ # plugin that reports running totals is covered by taking
+ # the LAST block rather than summing.
+ tokens_in, tokens_out, tokens_cached = _totals(usage)
+ seen = True
+ yield delta
+ finally:
+ if seen:
+ record_usage(
+ provider=self._provider_name,
+ model=model,
+ tokens_in=tokens_in,
+ tokens_out=tokens_out,
+ tokens_cached=tokens_cached,
+ caller=caller,
+ )
+
+
+def meter_brain(provider: Any, provider_name: str) -> Any:
+ """Wrap once; a provider that is already metered is handed back as is."""
+ if type(provider) is MeteredBrain:
+ return provider
+ if not callable(getattr(provider, "complete", None)):
+ return provider
+ return MeteredBrain(provider, provider_name)
+
+
+__all__ = ["MeteredBrain", "meter_brain"]
diff --git a/jarvis/costs/aggregate.py b/jarvis/costs/aggregate.py
index 44cbe68338..b2e18b2513 100644
--- a/jarvis/costs/aggregate.py
+++ b/jarvis/costs/aggregate.py
@@ -158,6 +158,9 @@ class CostReport:
series: list[dict[str, Any]]
top_refs: list[dict[str, Any]]
models: list[dict[str, Any]]
+ #: How many conversations/missions/sessions the window holds in all — the
+ #: top list is a slice of these, and must say so.
+ refs_total: int = 0
def to_dict(self) -> dict[str, Any]:
return {
@@ -172,6 +175,7 @@ class CostReport:
"series": self.series,
"top_refs": self.top_refs,
"models": self.models,
+ "refs_total": self.refs_total,
}
@@ -184,8 +188,13 @@ def filter_entries(
surfaces: set[str] | None = None,
refs: set[str] | None = None,
search: str = "",
+ billing: str = "all",
) -> list[CostEntry]:
- """Narrow the line items. An empty filter set means "everything"."""
+ """Narrow the line items. An empty filter set means "everything".
+
+ ``billing``: ``all``, ``billed`` (an API key paid — everything but seat
+ quotes) or ``subscription`` (seat quotes only).
+ """
needle = search.strip().casefold()
def keep(e: CostEntry) -> bool:
@@ -199,6 +208,10 @@ def filter_entries(
return False
if refs and e.ref_id not in refs:
return False
+ if billing == "billed" and e.price_source == "subscription":
+ return False
+ if billing == "subscription" and e.price_source != "subscription":
+ return False
if needle and needle not in f"{e.model} {e.provider} {e.label}".casefold():
return False
return True
@@ -307,6 +320,7 @@ def build_report(
}
for row in _ranked(refs, total_cost, total_tokens, top_n)
],
+ refs_total=len(refs),
models=sorted(
(
{
diff --git a/jarvis/costs/cli_usage_index.py b/jarvis/costs/cli_usage_index.py
index 80307f3458..a06e4b4a26 100644
--- a/jarvis/costs/cli_usage_index.py
+++ b/jarvis/costs/cli_usage_index.py
@@ -1025,7 +1025,7 @@ def _agy_row(
def _grok_row(
record: Mapping[str, Any], offset: int, cand: _Candidate, cursor: _Cursor
-) -> _Row | None:
+) -> _PricedRow | None:
params = _payload(record, "params")
update = _payload(params, "update")
if update.get("sessionUpdate") != "turn_completed":
@@ -1047,6 +1047,10 @@ def _grok_row(
session_id = str(params.get("sessionId") or cursor.session_id)
prompt_id = str(update.get("prompt_id") or "")
dedup = f"{session_id}:{prompt_id}" if session_id and prompt_id else f"{cand.key}:{offset}"
+ # xAI writes what it billed for the turn, in ticks of 1e-10 USD (verified
+ # against its list price to the cent, 2026-08-25). Grok Build runs on the
+ # user's own key, so this IS the bill, not an estimate.
+ cost_usd = _int(usage.get("costUsdTicks")) / 1e10
return (
cand.agent,
dedup,
@@ -1059,6 +1063,7 @@ def _grok_row(
cached,
cursor.cwd,
cursor.label,
+ cost_usd,
)
@@ -1123,7 +1128,7 @@ def _agy_context(path: Path) -> tuple[str, str, str]:
@dataclass(slots=True)
class _FileScan:
- rows: list[_Row]
+ rows: list[_Row | _PricedRow]
offset: int
cursor: _Cursor
bytes_read: int
@@ -1347,7 +1352,7 @@ def _scan_antigravity(cand: _Candidate, start: int) -> _FileScan:
with a space would stay at $0 forever.
"""
del start
- rows: list[_Row] = []
+ rows: list[_Row | _PricedRow] = []
session_id = cand.path.stem
cwd = ""
model = ""
@@ -1416,7 +1421,7 @@ def _scan_antigravity(cand: _Candidate, start: int) -> _FileScan:
finally:
conn.close()
return _FileScan(
- rows=list(rows), # type: ignore[arg-type]
+ rows=rows,
offset=0 if failed else cand.size,
cursor=_Cursor(
session_id=session_id,
@@ -1435,7 +1440,7 @@ def _scan_opencode(cand: _Candidate, start: int) -> _FileScan:
indexed (the "offset" column holds a timestamp for this agent), so a run
reads only what arrived since. A store that shrank (vacuum) re-reads from
zero and the message-id key keeps every turn counted once."""
- rows: list[_PricedRow] = []
+ rows: list[_Row | _PricedRow] = []
newest = start
failed = False
try:
@@ -1514,7 +1519,7 @@ def _scan(cand: _Candidate, start: int, cursor: _Cursor, deadline: float) -> _Fi
return _scan_opencode(cand, start)
if cand.agent == AGENT_AGY:
return _scan_antigravity(cand, start)
- rows: list[_Row] = []
+ rows: list[_Row | _PricedRow] = []
reader = _LineReader(None, start)
if cand.agent == AGENT_KIMI and not cursor.session_id:
cursor.session_id, cursor.cwd, cursor.label = _agy_context(cand.path)
@@ -1568,7 +1573,7 @@ def _wanted(agent: str, raw: bytes) -> bool:
def _row_for(
agent: str, record: Mapping[str, Any], offset: int, cand: _Candidate, cursor: _Cursor
-) -> _Row | None:
+) -> _Row | _PricedRow | None:
if agent == AGENT_CLAUDE:
return _claude_row(record, cand, cursor)
if agent == AGENT_CODEX:
diff --git a/jarvis/costs/ledger.py b/jarvis/costs/ledger.py
new file mode 100644
index 0000000000..0b3b580df9
--- /dev/null
+++ b/jarvis/costs/ledger.py
@@ -0,0 +1,317 @@
+"""The one place every model call's usage is written down.
+
+The Costs section used to learn about spend from the surfaces that happened
+to record it — a voice turn's ``BrainTurnCompleted``, a chat's
+``turn_finished``, a mission's draft. Twenty-odd callers of the brain
+protocol never told anyone: dictation polish, the wiki curator, awareness
+digests, the mission critic, computer-use planning, skill authoring, board
+profiles. Their OpenRouter and Gemini bills were real and invisible
+(maintainer, 2026-08-25: "I have spent money on OpenRouter, I know it").
+
+So the ledger sits UNDER the surfaces: every provider instance is wrapped at
+construction (:mod:`jarvis.brain.usage_meter`) and every usage block a
+plugin reports lands here, tagged with the *caller* that asked. Surfaces that
+already keep their own richer record (a voice turn knows realtime vs tool
+role; a chat turn knows its runner) tag their calls so the read model does
+not count them twice — see ``COVERED_ELSEWHERE`` in ``sources.py``.
+
+AP-9: nothing here touches the hot path. ``record_usage`` appends to an
+in-memory queue and returns; a daemon thread owns the SQLite file. A failure
+to write is logged once and never raised into a caller.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import logging
+import queue
+import sqlite3
+import threading
+import time
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+DB_NAME = "llm_usage.db"
+
+#: Who is asking, for the call currently being made. Set by the surface that
+#: owns the call (``usage_context("dictation")``); empty means "some
+#: background job" and is reported as such.
+usage_caller: contextvars.ContextVar[str] = contextvars.ContextVar(
+ "jarvis_usage_caller", default=""
+)
+
+
+def usage_context(caller: str) -> Iterator[None]:
+ """Tag every model call made inside the block with *caller*."""
+ token = usage_caller.set(caller)
+ try:
+ yield
+ finally:
+ usage_caller.reset(token)
+
+
+def current_caller() -> str:
+ return usage_caller.get()
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS llm_usage (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ ts_ms INTEGER NOT NULL,
+ provider TEXT NOT NULL DEFAULT '',
+ model TEXT NOT NULL DEFAULT '',
+ tokens_in INTEGER NOT NULL DEFAULT 0,
+ tokens_out INTEGER NOT NULL DEFAULT 0,
+ tokens_cached INTEGER NOT NULL DEFAULT 0,
+ cost_usd REAL NOT NULL DEFAULT 0,
+ caller TEXT NOT NULL DEFAULT '',
+ label TEXT NOT NULL DEFAULT ''
+);
+CREATE INDEX IF NOT EXISTS idx_llm_usage_ts ON llm_usage (ts_ms);
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class UsageRow:
+ ts_ms: int
+ provider: str
+ model: str
+ tokens_in: int
+ tokens_out: int
+ tokens_cached: int
+ cost_usd: float
+ caller: str
+ label: str
+
+
+class _Writer:
+ """One daemon thread, one connection, one queue. Drops nothing it can help."""
+
+ def __init__(self) -> None:
+ self._queue: queue.Queue[tuple[Any, ...] | None] = queue.Queue(maxsize=10_000)
+ self._thread: threading.Thread | None = None
+ self._lock = threading.Lock()
+ self._path: Path | None = None
+ self._warned = False
+ self._queued = 0
+ self._done = 0
+ self._done_cv = threading.Condition()
+
+ def path(self) -> Path:
+ with self._lock:
+ if self._path is None:
+ from jarvis.core import config as cfg
+
+ self._path = Path(cfg.DATA_DIR) / DB_NAME
+ return self._path
+
+ def set_path(self, path: Path | None) -> None:
+ """Test hook — point the ledger somewhere else (or back to default).
+
+ The writer thread holds a connection to the OLD file; it is stopped
+ first so nothing queued afterwards lands in the wrong place.
+ """
+ self._stop_thread()
+ with self._lock:
+ self._path = Path(path) if path is not None else None
+
+ def put(self, row: tuple[Any, ...]) -> None:
+ try:
+ self._queue.put_nowait(row)
+ except queue.Full:
+ if not self._warned:
+ self._warned = True
+ log.warning("usage ledger: queue full, dropping usage rows")
+ return
+ with self._done_cv:
+ self._queued += 1
+ self._ensure_thread()
+
+ def _ensure_thread(self) -> None:
+ with self._lock:
+ if self._thread is not None and self._thread.is_alive():
+ return
+ self._thread = threading.Thread(
+ target=self._run, name="jarvis-usage-ledger", daemon=True
+ )
+ self._thread.start()
+
+ def _stop_thread(self) -> None:
+ with self._lock:
+ thread = self._thread
+ if thread is None or not thread.is_alive():
+ return
+ self._queue.put(None)
+ thread.join(timeout=5.0)
+
+ def flush(self, timeout_s: float = 2.0) -> None:
+ """Wait until everything queued so far is on disk (tests, shutdown)."""
+ with self._done_cv:
+ target = self._queued
+ deadline = time.monotonic() + timeout_s
+ while self._done < target:
+ remaining = deadline - time.monotonic()
+ if remaining <= 0:
+ break
+ self._done_cv.wait(remaining)
+
+ def _mark_done(self) -> None:
+ with self._done_cv:
+ self._done += 1
+ self._done_cv.notify_all()
+
+ def _run(self) -> None:
+ conn: sqlite3.Connection | None = None
+ try:
+ while True:
+ try:
+ item = self._queue.get(timeout=5.0)
+ except queue.Empty:
+ # Idle: release the file so a report can read it freely and
+ # the thread can be re-armed by the next record.
+ break
+ if item is None:
+ break
+ try:
+ if conn is None:
+ conn = self._open()
+ if conn is not None:
+ conn.execute(
+ "INSERT INTO llm_usage (ts_ms, provider, model, tokens_in,"
+ " tokens_out, tokens_cached, cost_usd, caller, label)"
+ " VALUES (?,?,?,?,?,?,?,?,?)",
+ item,
+ )
+ conn.commit()
+ except sqlite3.Error as exc:
+ if not self._warned:
+ self._warned = True
+ log.warning("usage ledger: write failed (%s); further rows are lost", exc)
+ finally:
+ self._mark_done()
+ finally:
+ if conn is not None:
+ conn.close()
+
+ def _open(self) -> sqlite3.Connection | None:
+ path = self.path()
+ try:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ conn = sqlite3.connect(path, timeout=5.0)
+ conn.execute("PRAGMA journal_mode=WAL")
+ conn.execute("PRAGMA synchronous=NORMAL")
+ conn.executescript(_SCHEMA)
+ conn.commit()
+ return conn
+ except (OSError, sqlite3.Error) as exc:
+ if not self._warned:
+ self._warned = True
+ log.warning("usage ledger: %s not writable (%s)", path, exc)
+ return None
+
+
+_writer = _Writer()
+
+
+def record_usage(
+ *,
+ provider: str,
+ model: str,
+ tokens_in: int,
+ tokens_out: int,
+ tokens_cached: int = 0,
+ cost_usd: float = 0.0,
+ caller: str | None = None,
+ label: str = "",
+ ts_ms: int | None = None,
+) -> None:
+ """Write one model call down. Never raises, never blocks the caller.
+
+ ``caller`` defaults to the current :func:`usage_context`; ``cost_usd`` is
+ what the provider itself reported, when it did — the report re-prices
+ anything left at 0.0 from the rate tables.
+ """
+ try:
+ total = max(0, int(tokens_in)) + max(0, int(tokens_out)) + max(0, int(tokens_cached))
+ if total <= 0 and float(cost_usd) <= 0:
+ return
+ _writer.put(
+ (
+ int(ts_ms if ts_ms is not None else time.time() * 1000),
+ str(provider or ""),
+ str(model or ""),
+ max(0, int(tokens_in)),
+ max(0, int(tokens_out)),
+ max(0, int(tokens_cached)),
+ float(cost_usd or 0.0),
+ str(caller if caller is not None else current_caller()),
+ str(label or "")[:120],
+ )
+ )
+ except Exception: # noqa: BLE001 — accounting must never cost a call
+ log.debug("usage ledger: record failed", exc_info=True)
+
+
+def flush(timeout_s: float = 2.0) -> None:
+ _writer.flush(timeout_s)
+
+
+def set_ledger_path(path: Path | None) -> None:
+ _writer.set_path(path)
+
+
+def ledger_path() -> Path:
+ return _writer.path()
+
+
+def read_usage(path: Path, since_ms: int, until_ms: int) -> Iterator[UsageRow]:
+ """Rows in the window, oldest first. A missing file yields nothing."""
+ if not path.exists():
+ return
+ try:
+ conn = sqlite3.connect(f"file:{path.as_posix()}?mode=ro", uri=True, timeout=5.0)
+ except sqlite3.Error as exc:
+ log.warning("usage ledger: %s not readable (%s)", path, exc)
+ return
+ try:
+ conn.row_factory = sqlite3.Row
+ for row in conn.execute(
+ "SELECT ts_ms, provider, model, tokens_in, tokens_out, tokens_cached, cost_usd,"
+ " caller, label FROM llm_usage WHERE ts_ms BETWEEN ? AND ? ORDER BY ts_ms",
+ (since_ms, until_ms),
+ ):
+ yield UsageRow(
+ ts_ms=int(row["ts_ms"] or 0),
+ provider=str(row["provider"] or ""),
+ model=str(row["model"] or ""),
+ tokens_in=int(row["tokens_in"] or 0),
+ tokens_out=int(row["tokens_out"] or 0),
+ tokens_cached=int(row["tokens_cached"] or 0),
+ cost_usd=float(row["cost_usd"] or 0.0),
+ caller=str(row["caller"] or ""),
+ label=str(row["label"] or ""),
+ )
+ except sqlite3.Error as exc:
+ log.warning("usage ledger: read failed (%s)", exc)
+ finally:
+ conn.close()
+
+
+__all__ = [
+ "DB_NAME",
+ "UsageRow",
+ "current_caller",
+ "flush",
+ "ledger_path",
+ "read_usage",
+ "record_usage",
+ "set_ledger_path",
+ "usage_caller",
+ "usage_context",
+]
diff --git a/jarvis/costs/model.py b/jarvis/costs/model.py
index 057f5b9a15..b2426a66ea 100644
--- a/jarvis/costs/model.py
+++ b/jarvis/costs/model.py
@@ -41,6 +41,10 @@ SURFACE_MISSION = "mission"
SURFACE_JARVIS_VOICE = "jarvis-voice"
#: Coding agents driven by a vendor CLI, indexed from their session logs.
SURFACE_AGENTIC_IDE = "agentic-ide"
+#: Every model call no surface above claims: dictation polish, the wiki
+#: curator, awareness digests, the mission critic, computer-use planning,
+#: skill authoring … — read from the usage ledger (:mod:`jarvis.costs.ledger`).
+SURFACE_BACKGROUND = "background"
ROLE_REALTIME = "realtime"
"""Speech-to-speech model — audio tokens, billed per Live/Realtime API rates."""
@@ -55,9 +59,11 @@ ROLE_AGENT = "agent"
"""A coding-agent turn (Claude Code, Codex, …) run from the chat surface."""
ROLE_WORKER = "worker"
+"""An autonomous mission worker."""
ROLE_STT = "stt"
ROLE_TTS = "tts"
-"""An autonomous mission worker."""
+ROLE_BACKGROUND = "background"
+"""A model call made by a background job; the entry's label names the job."""
# Every role and surface the read model can emit, in the order a report
# should offer them. A value missing here is invisible in the facets, which
@@ -71,6 +77,7 @@ ROLES: tuple[str, ...] = (
ROLE_WORKER,
ROLE_STT,
ROLE_TTS,
+ ROLE_BACKGROUND,
)
SURFACES: tuple[str, ...] = (
SURFACE_VOICE,
@@ -78,6 +85,7 @@ SURFACES: tuple[str, ...] = (
SURFACE_MISSION,
SURFACE_AGENTIC_IDE,
SURFACE_JARVIS_VOICE,
+ SURFACE_BACKGROUND,
)
# Runners whose usage object follows the OpenAI convention: ``input_tokens``
@@ -130,7 +138,8 @@ SUBSCRIPTION_RUNNERS: frozenset[str] = frozenset(
"codex-cli",
"agy-cli",
"kimi-cli",
- "grok-cli",
+ # NOT grok-cli: Grok Build runs on the user's xAI key and records what
+ # it billed per turn (costUsdTicks) — money that moved, not a seat.
}
)
diff --git a/jarvis/costs/sources.py b/jarvis/costs/sources.py
index cb93231e3e..13fa5520a5 100644
--- a/jarvis/costs/sources.py
+++ b/jarvis/costs/sources.py
@@ -18,10 +18,13 @@ from dataclasses import dataclass
from pathlib import Path
from typing import Any
+from .ledger import DB_NAME as LEDGER_DB_NAME
+from .ledger import read_usage
from .model import (
MISSION_SUBSCRIPTION_CLIS,
OPENAI_CONVENTION_RUNNERS,
ROLE_AGENT,
+ ROLE_BACKGROUND,
ROLE_PIPELINE,
ROLE_REALTIME,
ROLE_STT,
@@ -31,6 +34,7 @@ from .model import (
SUBSCRIPTION_RUNNERS,
SURFACE_AGENT_CHAT,
SURFACE_AGENTIC_IDE,
+ SURFACE_BACKGROUND,
SURFACE_JARVIS_VOICE,
SURFACE_MISSION,
SURFACE_VOICE,
@@ -63,9 +67,11 @@ class CostSources:
#: a test with its own fixtures, above all — does not silently get this
#: machine's.
cli_index_dir: Path | None = None
+ #: The usage ledger every metered provider writes to.
+ ledger_db: Path | None = None
def existing(self) -> list[Path]:
- candidates = [self.sessions_db, self.missions_db, self.agent_chat_db]
+ candidates = [self.sessions_db, self.missions_db, self.agent_chat_db, self.ledger_db]
if self.cli_index_dir is not None:
# The index is a source like the others: a refresh that adds
# thousands of CLI turns must invalidate a cached report.
@@ -103,6 +109,7 @@ def default_sources(data_dir: Path | None = None) -> CostSources:
missions_db=root / "missions.db",
agent_chat_db=root / "agent_chat.db",
cli_index_dir=root,
+ ledger_db=root / LEDGER_DB_NAME,
)
@@ -687,6 +694,44 @@ def _cli_entries(
)
+# Callers whose spend a richer source already reports. Their ledger rows are
+# the audit trail, not a second bill: a voice turn is on BrainTurnCompleted
+# with its role split, a chat turn on turn_finished, a mission worker on its
+# draft.
+COVERED_ELSEWHERE: frozenset[str] = frozenset({"voice-turn", "agent-chat", "mission-worker"})
+
+
+def _ledger_entries(path: Path | None, since_ms: int, until_ms: int) -> Iterator[CostEntry]:
+ """Every model call no surface claims, as the ledger recorded it."""
+ if path is None:
+ return
+ for row in read_usage(path, since_ms, until_ms):
+ if row.caller in COVERED_ELSEWHERE:
+ continue
+ cost, source = price_entry(
+ provider=row.provider,
+ model=row.model,
+ tokens_in=row.tokens_in,
+ tokens_out=row.tokens_out,
+ recorded_usd=row.cost_usd,
+ tokens_cached=row.tokens_cached,
+ )
+ yield CostEntry(
+ ts_ms=row.ts_ms,
+ surface=SURFACE_BACKGROUND,
+ role=ROLE_BACKGROUND,
+ provider=row.provider or "unknown",
+ model=row.model,
+ tokens_in=row.tokens_in,
+ tokens_out=row.tokens_out,
+ tokens_cached=row.tokens_cached,
+ cost_usd=cost,
+ price_source=source,
+ ref_id="",
+ label=_clip(row.label or row.caller or "background"),
+ )
+
+
def collect_entries(
sources: CostSources,
*,
@@ -703,5 +748,6 @@ def collect_entries(
entries.extend(
_cli_entries(sources.cli_index_dir, since_ms, until_ms, bucket_ms)
)
+ entries.extend(_ledger_entries(sources.ledger_db, since_ms, until_ms))
entries.sort(key=lambda e: e.ts_ms)
return entries
diff --git a/jarvis/cu/brain_call.py b/jarvis/cu/brain_call.py
index 61fa323192..eece6dd5be 100644
--- a/jarvis/cu/brain_call.py
+++ b/jarvis/cu/brain_call.py
@@ -26,6 +26,7 @@ from dataclasses import dataclass
from typing import Any
from jarvis.core.protocols import BrainMessage, BrainRequest, ImageBlock
+from jarvis.costs.ledger import usage_context
logger = logging.getLogger(__name__)
@@ -347,7 +348,9 @@ async def call_vision_brain(
# step died "unterminated JSON", thoughts=304 of 320).
reasoning_effort="none",
)
- return await agg(brain.complete(req))
+ with usage_context("computer-use"):
+ _stream = brain.complete(req)
+ return await agg(_stream)
start_tokens = _starting_tokens(
provider, model, max_tokens, early_stop_json=early_stop_json,
diff --git a/jarvis/dictation/polish_client.py b/jarvis/dictation/polish_client.py
index e5aadc7ba7..8c64dfdb9b 100644
--- a/jarvis/dictation/polish_client.py
+++ b/jarvis/dictation/polish_client.py
@@ -815,6 +815,7 @@ class OpenAIChatPolishClient:
"reasoning_effort": "low",
}
data = await self._post(payload, timeout_s=timeout_s)
+ _record_openai_usage(self._family.id, self._model, data.get("usage"))
choices = data.get("choices") or []
if not choices:
return None
@@ -978,10 +979,53 @@ class GeminiPolishClient:
raise PolishProviderError(
f"{self._family.label} polish request failed: {exc}"
) from exc
+ _record_gemini_usage(
+ self._family.id, self._model, getattr(response, "usage_metadata", None)
+ )
text = str(getattr(response, "text", "") or "").strip()
return text or None
+def _record_openai_usage(provider: str, model: str, usage: Any) -> None:
+ """OpenAI-shaped usage: ``prompt_tokens`` INCLUDES the cached share."""
+ if not isinstance(usage, dict):
+ return
+ from jarvis.costs.ledger import record_usage
+
+ details = usage.get("prompt_tokens_details")
+ cached = int((details or {}).get("cached_tokens") or 0) if isinstance(details, dict) else 0
+ prompt = int(usage.get("prompt_tokens") or 0)
+ record_usage(
+ provider=provider,
+ model=model,
+ tokens_in=max(0, prompt - cached),
+ tokens_out=int(usage.get("completion_tokens") or 0),
+ tokens_cached=cached,
+ caller="dictation",
+ )
+
+
+def _record_gemini_usage(provider: str, model: str, meta: Any) -> None:
+ """google-genai ``usage_metadata``: prompt count includes cached content."""
+ if meta is None:
+ return
+ from jarvis.costs.ledger import record_usage
+
+ prompt = int(getattr(meta, "prompt_token_count", 0) or 0)
+ cached = int(getattr(meta, "cached_content_token_count", 0) or 0)
+ out = int(getattr(meta, "candidates_token_count", 0) or 0) + int(
+ getattr(meta, "thoughts_token_count", 0) or 0
+ )
+ record_usage(
+ provider=provider,
+ model=model,
+ tokens_in=max(0, prompt - cached),
+ tokens_out=out,
+ tokens_cached=cached,
+ caller="dictation",
+ )
+
+
def build_polish_client(family: PolishFamily, *, model: str) -> PolishClient | None:
"""Construct the adapter for *family*, or ``None`` when it is unusable.
diff --git a/jarvis/memory/wiki/provider_chain.py b/jarvis/memory/wiki/provider_chain.py
index b07965e4c9..310354877d 100644
--- a/jarvis/memory/wiki/provider_chain.py
+++ b/jarvis/memory/wiki/provider_chain.py
@@ -31,6 +31,7 @@ from collections.abc import Callable, Mapping
from typing import Any
from jarvis.core.redact import safe_preview
+from jarvis.costs.ledger import usage_context
from jarvis.memory.wiki.telemetry import telemetry
log = logging.getLogger(__name__)
@@ -348,7 +349,8 @@ async def complete_with_fallback(
failure_summaries.append(f"{provider} unavailable")
continue
try:
- stream = brain.complete(request)
+ with usage_context("wiki"):
+ stream = brain.complete(request)
except Exception as exc: # noqa: BLE001 — synchronous provider failure
detail = _exception_summary(exc)
log.warning(
diff --git a/jarvis/missions/critic/runner.py b/jarvis/missions/critic/runner.py
index b1e880c6c8..e8c5f23160 100644
--- a/jarvis/missions/critic/runner.py
+++ b/jarvis/missions/critic/runner.py
@@ -33,6 +33,8 @@ from typing import Any, Final
from pydantic import ValidationError
+from jarvis.costs.ledger import usage_context
+
from ..stream_evidence import (
capability_refusal_answer,
diff_has_action_evidence,
@@ -1929,7 +1931,9 @@ class CriticRunner:
parts: list[str] = []
async with asyncio.timeout(self._timeout):
with override_provider_secrets({provider: worker_key}):
- async for delta in brain.complete(req):
+ with usage_context("mission-critic"):
+ _stream = brain.complete(req)
+ async for delta in _stream:
chunk = getattr(delta, "content", None)
if chunk:
parts.append(chunk)
diff --git a/jarvis/missions/workers/api_agent_worker.py b/jarvis/missions/workers/api_agent_worker.py
index 252ca6dbe8..87b653ca1d 100644
--- a/jarvis/missions/workers/api_agent_worker.py
+++ b/jarvis/missions/workers/api_agent_worker.py
@@ -40,6 +40,7 @@ from pathlib import Path
from typing import Any, Literal
from jarvis.core.protocols import BrainMessage, BrainRequest
+from jarvis.costs.ledger import usage_context
from .api_agent_tools import WORKER_TOOL_SPECS, execute_worker_tool_async
from .capabilities import WorkerCapabilityInventory
@@ -432,7 +433,9 @@ class ApiAgentWorker:
# call. ContextVar isolation keeps concurrent Brain and
# Jarvis-Agent tasks from observing one another's keys.
with override_provider_secrets({self.provider: worker_key}):
- async for delta in brain.complete(req):
+ with usage_context("mission-worker"):
+ _stream = brain.complete(req)
+ async for delta in _stream:
if delta.content:
text_parts.append(delta.content)
if delta.tool_call:
diff --git a/jarvis/ui/web/costs_routes.py b/jarvis/ui/web/costs_routes.py
index 4f490edcf4..08b5344f9c 100644
--- a/jarvis/ui/web/costs_routes.py
+++ b/jarvis/ui/web/costs_routes.py
@@ -163,6 +163,7 @@ class CostSummary(BaseModel):
series: list[Bucket]
top_refs: list[RefBucket]
models: list[ModelRow]
+ refs_total: int = 0
facets: Facets
currency: Currency
sources_present: list[str]
@@ -527,6 +528,7 @@ def get_summary(
role: Annotated[list[str] | None, Query()] = None,
surface: Annotated[list[str] | None, Query()] = None,
ref: Annotated[list[str] | None, Query()] = None,
+ billing: Annotated[str, Query(pattern="^(all|billed|subscription)$")] = "all",
search: str = "",
top: Annotated[int, Query(ge=1, le=100)] = 12,
) -> CostSummary:
@@ -546,6 +548,7 @@ def get_summary(
surfaces=_split(surface),
refs=_split(ref),
search=search,
+ billing=billing,
)
report = build_report(selected, since_ms=start, until_ms=end, top_n=top)
payload = report.to_dict()
@@ -574,6 +577,7 @@ def get_daily(
role: Annotated[list[str] | None, Query()] = None,
surface: Annotated[list[str] | None, Query()] = None,
ref: Annotated[list[str] | None, Query()] = None,
+ billing: Annotated[str, Query(pattern="^(all|billed|subscription)$")] = "all",
search: str = "",
) -> DailyLedger:
"""The daily ledger: one entry per day, newest first.
@@ -596,6 +600,7 @@ def get_daily(
surfaces=_split(surface),
refs=_split(ref),
search=search,
+ billing=billing,
)
rows: list[DayRow] = []
for key, day_entries in group_by_day(entries):
@@ -639,6 +644,7 @@ def get_entries(
role: Annotated[list[str] | None, Query()] = None,
surface: Annotated[list[str] | None, Query()] = None,
ref: Annotated[list[str] | None, Query()] = None,
+ billing: Annotated[str, Query(pattern="^(all|billed|subscription)$")] = "all",
search: str = "",
sort: Annotated[str, Query(pattern="^(recent|cost|tokens)$")] = "recent",
limit: Annotated[int, Query(ge=1, le=500)] = 100,
@@ -655,6 +661,7 @@ def get_entries(
surfaces=_split(surface),
refs=_split(ref),
search=search,
+ billing=billing,
)
if sort == "cost":
entries = sorted(entries, key=lambda e: -e.cost_usd)
diff --git a/jarvis/ui/web/frontend/src/components/costs/costFormat.ts b/jarvis/ui/web/frontend/src/components/costs/costFormat.ts
index 88ae356360..5476f9f200 100644
--- a/jarvis/ui/web/frontend/src/components/costs/costFormat.ts
+++ b/jarvis/ui/web/frontend/src/components/costs/costFormat.ts
@@ -11,12 +11,13 @@ import type { CostRole, CostSurface, PriceSource } from "@/hooks/useCosts";
/** One hue per role — the chart stack, the legend and the tables share it. */
export const ROLE_COLORS: Record<CostRole, string> = {
realtime: "hsl(199 90% 62%)", // sky — the voice you talk to
- tool: "hsl(50 100% 52%)", // signal yellow — the app's primary
+ tool: "hsl(var(--primary))", // signal yellow — the app's primary
pipeline: "hsl(268 72% 68%)", // violet — the classic brain path
agent: "hsl(152 58% 52%)", // green — coding agents
worker: "hsl(18 88% 62%)", // orange — autonomous missions
stt: "hsl(340 75% 65%)", // rose — the ear
tts: "hsl(30 90% 60%)", // amber — the voice
+ background: "hsl(210 12% 60%)", // slate — work nobody watched
};
export const ROLE_ORDER: CostRole[] = [
@@ -27,6 +28,7 @@ export const ROLE_ORDER: CostRole[] = [
"worker",
"stt",
"tts",
+ "background",
];
/** Fallback for a bucket key that is not a role (provider, model, day). */
@@ -232,6 +234,7 @@ export const ALL_SURFACES: CostSurface[] = [
"mission",
"agentic-ide",
"jarvis-voice",
+ "background",
];
/**
@@ -259,8 +262,8 @@ export const SURFACE_GROUPS: SurfaceGroup[] = [
// named after it (maintainer decision 2026-08-24).
{
id: "jarvis",
- surfaces: ["voice", "agent-chat", "mission"],
- roles: ["realtime", "tool", "pipeline", "agent", "worker"],
+ surfaces: ["voice", "agent-chat", "mission", "background"],
+ roles: ["realtime", "tool", "pipeline", "agent", "worker", "background"],
},
// The assistant's voice — the speech layer built around the brain: the
// ears (speech to text) and the mouth (text to speech). Bills by audio
diff --git a/jarvis/ui/web/frontend/src/hooks/useCosts.ts b/jarvis/ui/web/frontend/src/hooks/useCosts.ts
index e3c299ef4c..c8f35c6616 100644
--- a/jarvis/ui/web/frontend/src/hooks/useCosts.ts
+++ b/jarvis/ui/web/frontend/src/hooks/useCosts.ts
@@ -21,7 +21,9 @@ export type CostRole =
// The speech layer bills by audio second and by character, not by token —
// its own two roles rather than a shape forced onto the token vocabulary.
| "stt"
- | "tts";
+ | "tts"
+ // A model call made by a background job (wiki, awareness, dictation …).
+ | "background";
/** Which part of the app it was spent in. */
export type CostSurface =
@@ -29,7 +31,8 @@ export type CostSurface =
| "agent-chat"
| "mission"
| "agentic-ide"
- | "jarvis-voice";
+ | "jarvis-voice"
+ | "background";
/**
* How confident the price is.
@@ -122,6 +125,8 @@ export interface CostSummary {
series: CostBucket[];
top_refs: CostRefBucket[];
models: CostModelRow[];
+ /** Every conversation/mission/session in the window; `top_refs` is a slice. */
+ refs_total: number;
facets: CostFacets;
currency: CostCurrency;
sources_present: string[];
@@ -214,6 +219,7 @@ export interface CostPricing {
// Query state shared by the summary and the line items
// ---------------------------------------------------------------------------
+export type CostBilling = "all" | "billed" | "subscription";
export interface CostFilters {
/** Rolling window in days; `0` means everything ever recorded. */
@@ -225,6 +231,8 @@ export interface CostFilters {
/** Session / mission ids — set by clicking a row in "Where it went". */
refs: string[];
search: string;
+ /** "all" · "billed" (an API key paid) · "subscription" (seat quotes only). */
+ billing: CostBilling;
/**
* An explicit window, in epoch ms. When set it wins over `days` — the
* daily report drills into ONE day and everything it shows (the hourly
@@ -242,6 +250,7 @@ export const EMPTY_FILTERS: CostFilters = {
roles: [],
surfaces: [],
refs: [],
+ billing: "all",
search: "",
};
@@ -270,6 +279,7 @@ function toParams(f: CostFilters): URLSearchParams {
for (const r of f.roles) params.append("role", r);
for (const s of f.surfaces) params.append("surface", s);
for (const r of f.refs) params.append("ref", r);
+ if (f.billing !== "all") params.set("billing", f.billing);
if (f.search.trim()) params.set("search", f.search.trim());
return params;
}
diff --git a/jarvis/ui/web/frontend/src/views/CostsView.tsx b/jarvis/ui/web/frontend/src/views/CostsView.tsx
index 4c2e63cb3b..67e4e7e6ee 100644
--- a/jarvis/ui/web/frontend/src/views/CostsView.tsx
+++ b/jarvis/ui/web/frontend/src/views/CostsView.tsx
@@ -86,6 +86,7 @@ import {
useCostSummary,
type CostBucket,
type CostDayRow,
+ type CostBilling,
type CostFilters,
type CostRole,
type CostSurface,
@@ -261,6 +262,16 @@ export function CostsView() {
--------------------------------------------------------------- */}
<div className="flex flex-wrap items-center gap-x-2 gap-y-2">
<AreaSwitch value={area?.id ?? null} onChange={pickArea} />
+ <SegmentedFilter<CostBilling>
+ label={t("costs_view.billing_label")}
+ value={filters.billing}
+ onChange={(billing) => setFilters((f) => ({ ...f, billing }))}
+ options={[
+ { id: "all", label: t("costs_view.billing.all") },
+ { id: "billed", label: t("costs_view.billing.billed") },
+ { id: "subscription", label: t("costs_view.billing.subscription") },
+ ]}
+ />
<RoleFilters
roles={(area ?? SURFACE_GROUPS[0]).roles}
available={data?.facets.roles ?? []}
@@ -524,7 +535,17 @@ export function CostsView() {
<div className="px-4 pt-4">
<PanelHeader
title={t("costs_view.top_refs_title")}
- subtitle={t("costs_view.top_refs_subtitle")}
+ subtitle={
+ data && data.refs_total > 0
+ ? fill(t("costs_view.top_refs_subtitle_counted"), {
+ shown: String(data.top_refs.length),
+ total: formatExact(data.refs_total),
+ share: formatShare(
+ data.top_refs.reduce((sum, r) => sum + r.cost_share, 0),
+ ),
+ })
+ : t("costs_view.top_refs_subtitle")
+ }
/>
</div>
<div className="mt-3">
diff --git a/tests/unit/costs/test_usage_ledger.py b/tests/unit/costs/test_usage_ledger.py
new file mode 100644
index 0000000000..9b2f0d5f2c
--- /dev/null
+++ b/tests/unit/costs/test_usage_ledger.py
@@ -0,0 +1,140 @@
+"""The usage ledger and the metered brain: every model call is written down,
+tagged with who asked, and the report reads it back without double counting."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import pytest
+
+from jarvis.brain.usage_meter import MeteredBrain, meter_brain
+from jarvis.core.protocols import BrainDelta, BrainRequest
+from jarvis.costs import CostSources, collect_entries, ledger
+from jarvis.costs.aggregate import filter_entries
+from jarvis.costs.model import CostEntry
+
+
+class FakeBrain:
+ name = "fake"
+ model = "gpt-5.5"
+
+ def __init__(self) -> None:
+ self.calls = 0
+
+ async def complete(self, req: BrainRequest) -> AsyncIterator[BrainDelta]:
+ self.calls += 1
+ yield BrainDelta(content="hel")
+ yield BrainDelta(content="lo")
+ yield BrainDelta(
+ finish_reason="stop",
+ usage={"input_tokens": 120, "output_tokens": 7, "cache_hit_tokens": 900},
+ )
+
+ def estimate_cost(self, req: BrainRequest) -> float:
+ return 0.5
+
+
+def ledger_path(tmp_path: Path):
+ path = tmp_path / "llm_usage.db"
+ ledger.set_ledger_path(path)
+ try:
+ yield path
+ finally:
+ ledger.flush()
+ ledger.set_ledger_path(None)
+
+
+def _request() -> BrainRequest:
+ return BrainRequest(messages=[])
+
+
+async def _drain(stream: AsyncIterator[BrainDelta]) -> str:
+ parts = [d.content or "" async for d in stream]
+ return "".join(parts)
+
+
+def test_a_metered_brain_writes_the_call_with_its_caller(ledger_path: Path) -> None:
+ brain = meter_brain(FakeBrain(), "openrouter")
+ assert isinstance(brain, MeteredBrain)
+
+ async def run() -> str:
+ with ledger.usage_context("wiki"):
+ stream = brain.complete(_request())
+ return await _drain(stream)
+
+ assert asyncio.run(run()) == "hello"
+ ledger.flush()
+ rows = list(ledger.read_usage(ledger_path, 0, 2**62))
+ assert len(rows) == 1
+ row = rows[0]
+ assert (row.provider, row.model, row.caller) == ("openrouter", "gpt-5.5", "wiki")
+ assert (row.tokens_in, row.tokens_out, row.tokens_cached) == (120, 7, 900)
+
+
+def test_the_caller_is_read_when_complete_is_called_not_when_consumed(
+ ledger_path: Path,
+) -> None:
+ brain = meter_brain(FakeBrain(), "gemini")
+
+ async def run() -> None:
+ with ledger.usage_context("dictation"):
+ stream = brain.complete(_request())
+ await _drain(stream)
+
+ asyncio.run(run())
+ ledger.flush()
+ assert [r.caller for r in ledger.read_usage(ledger_path, 0, 2**62)] == ["dictation"]
+
+
+def test_wrapping_twice_is_wrapping_once() -> None:
+ inner = FakeBrain()
+ once = meter_brain(inner, "x")
+ assert meter_brain(once, "x") is once
+ assert once.unwrapped is inner
+ assert once.name == "fake" and once.estimate_cost(_request()) == 0.5
+
+
+def test_the_report_counts_background_calls_and_skips_covered_ones(ledger_path: Path) -> None:
+ for caller in ("wiki", "voice-turn", "agent-chat", "mission-worker", ""):
+ ledger.record_usage(
+ provider="openrouter",
+ model="google/gemini-3.5-flash",
+ tokens_in=1_000,
+ tokens_out=100,
+ caller=caller,
+ ts_ms=1_700_000_000_000,
+ )
+ ledger.flush()
+
+ rows = collect_entries(CostSources(ledger_db=ledger_path))
+ assert len(rows) == 2
+ assert {e.surface for e in rows} == {"background"}
+ assert {e.role for e in rows} == {"background"}
+ assert {e.label for e in rows} == {"wiki", "background"}
+ assert all(e.cost_usd > 0 for e in rows)
+
+
+def test_a_zero_usage_call_is_not_written(ledger_path: Path) -> None:
+ ledger.record_usage(provider="x", model="y", tokens_in=0, tokens_out=0)
+ ledger.flush()
+ assert list(ledger.read_usage(ledger_path, 0, 2**62)) == []
+
+
+def _entry(source: str) -> CostEntry:
+ return CostEntry(
+ ts_ms=1, surface="voice", role="tool", provider="p", model="m",
+ tokens_in=1, tokens_out=1, tokens_cached=0, cost_usd=1.0,
+ price_source=source, ref_id="", label="", # type: ignore[arg-type]
+ )
+
+
+def test_billing_filter_splits_seat_quotes_from_key_spend() -> None:
+ rows = [_entry("recorded"), _entry("subscription"), _entry("derived")]
+ assert len(filter_entries(rows, billing="all")) == 3
+ billed = [e.price_source for e in filter_entries(rows, billing="billed")]
+ assert billed == ["recorded", "derived"]
+ seats = [e.price_source for e in filter_entries(rows, billing="subscription")]
+ assert seats == ["subscription"]