Token/cost usage tracking end-to-end + tray usage UI

[AbirAbbas]

Summary

Makes token/cost tracking actually work end-to-end (SDK capture → control-plane storage → aggregation API → UI) across all three SDKs (Python, Go, TypeScript), and gives the macOS tray a usage glance surface plus a lifecycle status badge.

Wire contract (shared by all three SDKs)

• Per-execution tracker serialized as {total_cost_usd, total_input_tokens, total_output_tokens, total_tokens, entries[]}; each entry carries source/provider/model/harness/reasoner, token counts (incl. cache read/creation), nullable cost_usd, and cost_source.
• Async status callback: usage travels as a typed top-level usage field beside result in the SDK-controlled callback envelope.
• Sync-200 results: usage is merged into object-shaped results under the reserved namespaced key __agentfield_usage__, which the control plane extracts and strips. A user result that legitimately returns its own usage key is payload and passes through byte-for-byte untouched (addresses the blocking review finding; regression tests pin this on both sides). Non-object sync results report via the async path.
• Cross-language golden tests pin the verbatim serialized payload of each SDK against the Go parser.

Python SDK — capture & transport

• Fixes the OpenRouter tracking bug: tokens are now recorded even when litellm.completion_cost() can't price the model (previously both were silently discarded). OpenRouter requests opt into native cost accounting (usage: {include: true}).
• Handles both OpenAI-style (prompt_tokens) and Anthropic-native (input_tokens) usage shapes, including cache read/creation tokens.
• Claude Code harness runs capture full token usage (previously cost only).
• Per-execution CostTracker bound via contextvar (concurrency-safe).

Go SDK — capture & transport

• CostTracker bound per execution via context.Context at every handler entrypoint (execute, reasoner sync/async, skill).
• LLM capture at the Agent.AI / AIWithTools / AIStream chokepoints; ai.Usage extended with cache read/creation tokens (OpenAI prompt_tokens_details and Anthropic-native shapes) and provider-reported cost; OpenRouter requests opt into native cost accounting; tool-call loops capture per-turn usage.
• Harness runs record tokens + cost (token fields threaded through harness.Metrics/Result, populated from already-parsed claude-code/codex/opencode output).
• Fixes a pre-existing SSE decoder bug that dropped bytes returned alongside io.EOF (exactly where a terminal usage-accounting chunk arrives).

TypeScript SDK — capture & transport

• CostTracker on the ExecutionContext (AsyncLocalStorage-isolated per execution; local agent.call() rolls child usage into the parent tracker).
• LLM capture in AIClient generate paths (AI SDK v6 usage incl. cache token details) and across ToolCalling loop turns; OpenRouter requests opt into native cost accounting via a fetch wrapper, cost read from the provider's raw usage. stream() usage intentionally not captured (draining the usage promise would consume abandoned streams).
• Claude Code harness runs record tokens + provider-reported cost.

Control plane — storage & API

• New execution_usage table: goose migration 034 (Postgres) + GORM auto-migrate (SQLite).
• Tolerant ingestion of the usage envelope on both result paths; never fails the execution; strips only the reserved __agentfield_usage__ key so it can't leak into stored results.
• New GET /api/ui/v1/usage/stats?window=1h|24h|7d|30d|all with totals and by-model / by-provider / by-agent / by-harness aggregation; optional zero-filled bucket timeseries (&buckets=N) and per-model series (&series_by=model). Dialect-portable SQL (SQLite + Postgres).
• Existing execution-details responses now include cost / total_tokens — the web UI's dormant cost columns render without frontend changes.

Tray (macOS)

• Menu-bar item: af badge + lifecycle glyph (green dot running / rotating orange arc starting / gray ring stopped), driven by health checks + process detection.
• Usage submenu (glance-only): 48-bucket token histogram stacked per model, top-3 model rows with proportional bars on a uniform-slot grid, Claude 5h/7d subscription quota gauges (read-only, via the user's existing Claude Code Keychain OAuth token; degrades silently), last-updated footer. Full detail intentionally lives in the dashboard.
• Success row gains a live sparkline icon; avg response latency is humanized ("2m 43s" not "162867 ms").
• Vendors fyne.io/systray v1.12.2 as third_party/systray with two additive patches (SetImage, SetStatusImage) lifting the stock 16×16 menu-image clamp — documented in third_party/systray/PATCHES.md.

Verification

• Control plane: full go test ./... green; golden contract tests cover all three SDK payloads plus the sync-body strip/preserve behavior; GOOS=linux build clean.
• Python: ruff check clean; full suite green (includes 37 usage-transport tests + a regression test that a user-owned usage key survives the sync round-trip).
• Go SDK: go mod tidy no-drift, go build/go vet/go test ./... green (28 new usage tests), -race clean on the new paths.
• TypeScript SDK: npm ci, tsc --noEmit, 730/730 vitest tests, tsup build all green on Node 20 (44 new usage tests).
• Live end-to-end (all three SDKs): real Python, Go, and TypeScript agents → control plane → /usage/stats verified with correct by-provider/by-agent aggregations, null-cost token counting, a user-owned usage key surviving the round-trip untouched, and no envelope leakage into results.
• The live Go/TS run surfaced a real bug in the stats API: on a non-UTC control plane, every bounded window (1h/24h/…) returned zeros because SQLite compares timestamp text lexicographically across mixed UTC offsets. Fixed by routing all window filters through the dialect-portable epoch expression; regression test pins it with offset-zoned rows (it fails on the old code even on UTC CI runners).
• All tray graphics visually verified via offscreen renders (dark + light appearances); menu geometry (uniform slot widths) is unit-test enforced.

Notes for reviewers

• The sync-200 path can only carry usage for object-shaped results; non-object results report via the async callback (the production path).
• __agentfield_-prefixed keys are reserved for SDK↔control-plane transport; user payloads are otherwise never inspected or modified.
• Gemini harness runs don't report tokens (its providers parse no events today); codex/opencode report what their parsed events already expose.
• usage-e2e demo rows may exist in local dev DBs from testing; they are data, not code.

🤖 Generated with Claude Code

[github-actions]

Performance

SDK	Memory	Δ	Latency	Δ	Tests	Status
Python	9.5 KB	+5%	0.32 µs	-9%	✓	✓
Go	207 B	-26%	0.54 µs	-46%	✓	✓
TS	435 B	+24%	1.42 µs	-29%	✓	⚠

⚠ Regression detected:

• TypeScript memory: 350 B → 435 B (+24%)

[github-actions]

📊 Coverage gate

Thresholds from .coverage-gate.toml: per-surface ≥ 84%, aggregate ≥ 85%, max per-surface regression ≤ 1.0 pp, max aggregate regression ≤ 0.50 pp.

Surface	Current	Baseline	Δ
control-plane	86.90%	87.40%	↓ -0.50 pp	🟡
sdk-go	92.40%	92.00%	↑ +0.40 pp	🟢
sdk-python	93.82%	93.73%	↑ +0.09 pp	🟢
sdk-typescript	91.00%	90.42%	↑ +0.58 pp	🟢
web-ui	84.75%	84.79%	↓ -0.04 pp	🟡
aggregate	85.54%	85.75%	↓ -0.21 pp	🟡

✅ Gate passed

No surface regressed past the allowed threshold and the aggregate stayed above the floor.

[github-actions]

📐 Patch coverage gate

Threshold: 80% on lines this PR touches vs origin/main (from .coverage-gate.toml:thresholds.min_patch).

Surface	Touched lines	Patch coverage	Status
control-plane	1481	83.00%	✅
sdk-go	445	90.00%	✅
sdk-python	0	—	➖ no changes
sdk-typescript	137	100.00%	✅
web-ui	0	—	➖ no changes

✅ Patch gate passed

Every surface whose lines were touched by this PR has patch coverage at or above the threshold.

[santoshkumarradha]

Thanks for pushing this through end to end. I found one blocking compatibility issue inline: the sync result path now reserves a top-level usage key and relies on the control plane to strip it back out, which silently mutates user payloads that already return that key. Given the repo’s API stability bar, I think that needs to be fixed before merge.

[santoshkumarradha]

@AbirAbbas also how are we planning to deal with go and tsx on this?

[AbirAbbas]

ound one blocking compatibility issue inline: the sync result path now reserves a top-level usage key and

will implement it in this PR

[AbirAbbas]

also how are we planning to deal with go and tsx on this?

Both landed in this PR — Go in 21c4762, TypeScript in 555e0b3. Each SDK captures per-execution usage (AI-client tokens incl. cache details, OpenRouter native cost accounting via usage: {include: true}, tool-loop turns, and coding-agent harness runs) and transports it over the same wire contract as Python: a typed usage field on the async status callback, and the reserved __agentfield_usage__ sibling key on object-shaped sync-200 results. The control-plane golden test now pins all three SDKs' verbatim serialized payloads against the parser (e91337c), so the contract can't drift silently.

Two intentional gaps: TS stream() usage isn't captured (awaiting the AI SDK's usage promise force-consumes streams the caller may abandon), and gemini harness runs report no tokens yet (that provider doesn't parse events). Also picked up along the way: the Go SDK's SSE decoder was dropping bytes returned alongside io.EOF — exactly where a terminal usage chunk arrives — fixed in the same commit.