No way to see what an agent spent outside the TUI #3943

Overview

Token and cost figures are only reachable from the interactive TUI (pkg/tui/dialog/cost.go) and
from OpenTelemetry. There is no CLI command for them: nothing in cmd/root/ reports usage.

That leaves every non-interactive path blind:

• docker agent run --exec in CI — no way to answer "what did that cost?"
• the API server and MCP/A2A modes — same
• retrospective questions of any kind ("what did we spend last week?", "which agent is expensive?")

It also makes the existing budget feature hard to configure. BudgetConfig caps spend with
max_cost / max_tokens / max_time, but there is no way to see actual historical spend, so the
cap has to be guessed at.

Motivation

This is an aggregation and presentation gap, not a data gap:

No schema change is needed for a first version.

Use cases

No response

Proposed solution

docker agent usage — read the session store and report what was spent.

$ docker agent usage --since 24h
SESSION   CREATED           INPUT   CACHED  OUTPUT  COST    TITLE
a1b2c3d4  2026-08-06 12:04  128.4K  96.2K   4.1K    $0.42   fix the failing cache test
…
3 session(s)                412.7K  310.1K  11.9K   $1.28

MODEL                    CALLS  INPUT   CACHED  OUTPUT
anthropic/claude-opus-5     41   380.2K  295.0K  10.4K

TOOL             CALLS
read_file           58
shell               21

• --json for CI use, so it can drive a budget check
• --session <id> for one session, --since <dur> for a window
• a per-tool breakdown, which does not exist anywhere today and is usually where the cost
  actually goes

Alternatives

No response

Related issues

No response

Additional context

A model missing from the pricing catalogue records $0 against real token usage — the runtime logs
Model is missing from the pricing catalogue; recording $0 cost despite token usage, and it happens
routinely (every test/* model in the test suite hits it).

A report that silently shows $0.00 for those is worse than no report. Sessions that moved tokens
but recorded no cost must be flagged, and the total marked as a lower bound.

Scope note

Cost is persisted per session and per non-message item, never per message, so per-model cost
cannot be attributed within a session without a schema change. Tokens can. A first version should
report tokens per model and cost per session, and say so plainly rather than inventing an
attribution.