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.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
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.pyindex 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.pyindex 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 asyncioimport loggingimport 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.pyindex 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.pynew file mode 100644index 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.pyindex 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 = 0def 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 Falseif 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 Falseif needle and needle not in f"{e.model} {e.provider} {e.label}".casefold():return Falsereturn 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.pyindex 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")) / 1e10return (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: intcursor: _Cursorbytes_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.stemcwd = ""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 runreads only what arrived since. A store that shrank (vacuum) re-reads fromzero and the message-id key keeps every turn counted once."""- rows: list[_PricedRow] = []+ rows: list[_Row | _PricedRow] = []newest = startfailed = Falsetry:@@ -1514,7 +1519,7 @@ def _scan(cand: _Candidate, start: int, cursor: _Cursor, deadline: float) -> _Fireturn _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.pynew file mode 100644index 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.pyindex 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.pyindex cb93231e3e..13fa5520a5 100644--- a/jarvis/costs/sources.py+++ b/jarvis/costs/sources.py@@ -18,10 +18,13 @@ from dataclasses import dataclassfrom pathlib import Pathfrom typing import Any+from .ledger import DB_NAME as LEDGER_DB_NAME+from .ledger import read_usagefrom .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 = Nonedef 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 entriesdiff --git a/jarvis/cu/brain_call.py b/jarvis/cu/brain_call.pyindex 61fa323192..eece6dd5be 100644--- a/jarvis/cu/brain_call.py+++ b/jarvis/cu/brain_call.py@@ -26,6 +26,7 @@ from dataclasses import dataclassfrom typing import Anyfrom jarvis.core.protocols import BrainMessage, BrainRequest, ImageBlock+from jarvis.costs.ledger import usage_contextlogger = 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.pyindex 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.pyindex 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, Mappingfrom typing import Anyfrom jarvis.core.redact import safe_preview+from jarvis.costs.ledger import usage_contextfrom jarvis.memory.wiki.telemetry import telemetrylog = logging.getLogger(__name__)@@ -348,7 +349,8 @@ async def complete_with_fallback(failure_summaries.append(f"{provider} unavailable")continuetry:- stream = brain.complete(request)+ with usage_context("wiki"):+ stream = brain.complete(request)except Exception as exc: # noqa: BLE001 — synchronous provider failuredetail = _exception_summary(exc)log.warning(diff --git a/jarvis/missions/critic/runner.py b/jarvis/missions/critic/runner.pyindex b1e880c6c8..e8c5f23160 100644--- a/jarvis/missions/critic/runner.py+++ b/jarvis/missions/critic/runner.py@@ -33,6 +33,8 @@ from typing import Any, Finalfrom 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.pyindex 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 Pathfrom typing import Any, Literalfrom jarvis.core.protocols import BrainMessage, BrainRequest+from jarvis.costs.ledger import usage_contextfrom .api_agent_tools import WORKER_TOOL_SPECS, execute_worker_tool_asyncfrom .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.pyindex 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 = 0facets: Facetscurrency: Currencysources_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.tsindex 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 primarypipeline: "hsl(268 72% 68%)", // violet — the classic brain pathagent: "hsl(152 58% 52%)", // green — coding agentsworker: "hsl(18 88% 62%)", // orange — autonomous missionsstt: "hsl(340 75% 65%)", // rose — the eartts: "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 audiodiff --git a/jarvis/ui/web/frontend/src/hooks/useCosts.ts b/jarvis/ui/web/frontend/src/hooks/useCosts.tsindex 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.tsxindex 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") },+ ]}+ /><RoleFiltersroles={(area ?? SURFACE_GROUPS[0]).roles}available={data?.facets.roles ?? []}@@ -524,7 +535,17 @@ export function CostsView() {<div className="px-4 pt-4"><PanelHeadertitle={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.pynew file mode 100644index 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"]