Expenditure Tracking (spec 037)
The extension tracks every hosted gpt-realtime-2.1 response’s cost: a live meter in the page overlay, per-response JSONL records persisted to your own S3 bucket, session summaries, and an optional tracking-error readout comparing our estimates against what OpenAI actually charged.
The live meter
A chip appears bottom-left on claimed tabs after the first hosted-agent response:
● session $0.42 · last $0.0031 · today $1.50
- session — running estimated cost of the current hosted session.
- last — the most recent response’s estimated cost.
- today — a this-browser day total (local counter, resets at midnight; sessions on other machines are not included).
- The dot — green when caching looks healthy; pulsing red when a response fires the cache-miss drain signature (zero cached input tokens on a context ≥ 4k tokens — the pattern that drains credit fastest). If it pulses red repeatedly, something is busting the prompt cache; that is worth investigating immediately.
The meter works with no storage configured. Only persistence needs setup.
S3 setup (options page)
Open the extension’s options (chrome://extensions → actions.json → Extension options):
- Fill bucket, region, key prefix (default
actions-json), access key id, secret. - Click Test write — it round-trips a probe object and shows the S3 error verbatim on failure.
- Use a scoped IAM key. Minimal policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:PutObject"],
"Resource": "arn:aws:s3:::YOUR_BUCKET/actions-json/*"
},
{
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": "arn:aws:s3:::YOUR_BUCKET",
"Condition": { "StringLike": { "s3:prefix": "actions-json/*" } }
}
]
}
The key lives in extension local storage on this machine — scope it accordingly.
Records spool locally (IndexedDB) and flush every minute in batched part objects, so offline periods and service-worker restarts lose nothing. Keys look like:
actions-json/expenditure/2026-07-04/<session_id>/part-<ts>-<rand>.jsonl
Record schema
One JSON object per line. kind: "realtime_response_usage":
| field | meaning |
|---|---|
ts, response_id, session_id, model | provenance |
input_text/audio/image | fresh (uncached) input tokens per modality |
cached_text/audio/image | cached input tokens per modality |
output_text/audio, total_tokens | output + total |
estimated_cost_usd | per-modality priced estimate |
pricing_version | pricing table the estimate used |
cache_hit | cached ≥ 50% of input |
usage_observed | false ⇒ zero-usage payload, zero-cost record |
kind: "realtime_session_summary" (one per session): responses, cache_hits, cache_hit_rate, total_tokens, total_cost_usd, duration_ms, first/last response ids. kind: "reconciliation" (daily, optional): estimatedUsd, actualUsd, errorPct.
Analyzing the JSONL
Day total:
cat part-*.jsonl | jq -s 'map(select(.kind=="realtime_response_usage").estimated_cost_usd) | add'
Cache-hit rate:
cat part-*.jsonl | jq -s '[.[] | select(.kind=="realtime_response_usage")] | (map(select(.cache_hit)) | length) / length'
Most expensive responses:
cat part-*.jsonl | jq -s '[.[] | select(.kind=="realtime_response_usage")] | sort_by(-.estimated_cost_usd) | .[0:5] | .[] | {response_id, estimated_cost_usd, cache_hit}'
Tracking error (optional)
Paste a restricted OpenAI admin key with only the api.usage.read scope into the options page (the runtime project key cannot read usage). Every ~6 hours the extension reconciles the previous completed UTC day: our summed estimates vs the Costs API actual, written as a reconciliation record and kept in actionsJsonTrackingError. A persistent error beyond ±10% means pricing drift, an estimator bug, or another consumer on the project — all worth knowing. Without the key, no OpenAI usage calls are ever made.
Pricing drift protection
Pricing constants are bundled (src/agent/realtime-cost.mjs) with a PRICING_CONFIRMED_ON date. A unit test fails the suite when that date is older than 60 days, so a release cannot ship unconfirmed prices: re-check https://openai.com/api/pricing, bump the date, and bump the constants + PRICING_VERSION if prices changed. Historical records stay auditable because every record carries the pricing_version it was priced with.