---
name: tau-qodq
description: >
  Extract and chart canonical provider quota observations and terminal token usage
  as offline, privacy-aware CSV, SVG, and summary artifacts.
---

# Tau QODQ: offline quota and token-usage diagnostics

Use `extract_quota.rs` for bounded historical diagnostics from canonical Tau
events. This native Cargo single-file script writes redacted CSV, gnuplot SVG/PNG,
summary, artifact README, and reproducible `.gnuplot` programs. The Nix runner
supplies the nightly toolchain already pinned through Flakebox/Fenix in
`flake.lock`, gnuplot, and a linker, without changing the workspace toolchain.
First use can download/build these tools and script dependencies.
It is an offline aid, not a Tau command;
do not change provider, journal, or runtime semantics for it.

## Run

Select each configured subscription explicitly. `LABEL` is presentation-only;
`PROVIDER` exactly selects canonical quota `payload.provider` and the
`PROVIDER/` prefix of canonical token-usage `usage.model`. This checked-in
extractor invocation is the generator template. By default it includes the
current day through the UTC instant captured once when generation starts.

```bash
cd "$(jj workspace root)"
skill_dir=.agents/skills/tau-qodq
nix shell .#diagnostics -c tau-diagnostics-cargo "$skill_dir/extract_quota.rs" \
  --sessions-root "$HOME/.local/state/tau/sessions" \
  --profile chatgpt=chatgpt \
  --profile chatgpt-fedi=chatgpt-fedi \
  --out tmp/tau-qodq-chatgpt-chatgpt-fedi
```

The exact range is `[since, until)` in UTC, with millisecond precision.
The default is the trailing fourteen days ending at the current UTC instant,
not the previous midnight. “Last two weeks” includes today's partial day and
current partial bucket; do not round the endpoint down to midnight. The
`tau-agent-performance` workflow follows the same current-moment convention.
The endpoint is fixed before scanning, so a long scan
does not move it. For reproducible bounded historical diagnostics, pass explicit
`--since` and `--until` RFC3339 instants; neither needs to be a day boundary.
An omitted `--since` means fourteen days before the selected endpoint.
Token buckets remain UTC-aligned at 00:00/06:00/12:00/18:00 and both charts guide
every UTC midnight in range, including when the endpoints fall within a day.
Ranges over 366 days are rejected. The
compatibility `--provider NAME` selection remains equivalent to
`--profile NAME=NAME`; prefer repeatable `--profile`.

Keep the generated `README.md`, `summary.txt`, `quota.csv`, `quota.svg`,
`tokens.csv`, `tokens.svg`, both PNG previews, and both `.gnuplot` programs
together. Programs contain aggregate chart evidence only; re-render them with
`gnuplot quota.gnuplot` and `gnuplot tokens.gnuplot` in the artifact directory.
New artifact directories are owner-only. Inspect PNGs before sharing.
Do not commit artifacts or session
data. The extractor scans selected `events.jsonl` files without an index, so
time bounds constrain output but may not reduce bytes scanned. Cargo build
outputs and script lockfiles live in `$XDG_CACHE_HOME/tau-diagnostics/target`
(default `$HOME/.cache/tau-diagnostics/target`), not in the source tree. Direct
dependencies are exact-version pinned in the embedded manifest; transitive
resolution persists in Cargo's cached script lockfile, not the repository.
This pins the toolchain, not a fully vendored/offline script build. From the
repository root, the executable `.rs` shebang uses the same Nix runner.
Do not use unrelated third-party `cargo-script` or `rust-script` tools.

## Inputs and privacy boundary

Select only these exact nested canonical published events:

* `harness.provider_quota_changed` provides accepted full quota snapshots.
  Do not substitute provider `_reported` quota events.
* `provider.response_finished` provides accepted terminal
  `usage.model`, `prompt_sent_tokens`, `prompt_cached_tokens`, and
  `response_received_tokens`.

The extractor reads no provider capture files and never exports credentials,
prompts, response/output items, routes beyond the quota snapshot's normalized
route metadata, or raw event records. A canonical response terminal can contain
output items, but the extractor deliberately reads only the listed identity,
time, model-selection, and usage fields.

`provider.response_finished` does not carry a quota profile epoch. Token rows
therefore identify the selected configured provider/model prefix and human
label, not an account or credential. Quota rows retain `profile_epoch`, which
is opaque process-lifetime evidence, **not** an account identity. Never infer
that selected names, profile epochs, or separate sessions prove a shared or
different account.

The extractor structurally skips unselected JSON values before decoding any
terminal fields. In particular, it does not materialize `output_items`, error
details, prompts, or provider content while selecting terminal usage.

## Chart and CSV semantics

`quota.svg` shows one line for each selected subscription. It explicitly selects
the canonical default `codex/primary` series: the Codex adapter maps an official
nameless rate-limit observation to the canonical default `codex` pool, and
`primary` is the provider-normalized primary window. It retains the maximum actual
`remaining_percent` observation per subscription and UTC hour, breaking the line
for every missing hour. This display-only reduction never averages, interpolates,
predicts, or alters CSV evidence. Ties retain the latest `(observation time,
sequence, profile epoch)`.
`quota.csv` still retains every pool, window, and process epoch. The SVG legend
contains only the supplied subscription labels; it exposes no pool/window or
epoch IDs. Its values are `remaining_percent = 100 - used_basis_points / 100`.
It guides and labels every UTC day boundary.

`tokens.csv` retains selected canonical terminals in UTC-aligned half-open
one-hour rows `[HH:00, HH+1:00)`, selected by the terminal's
`recorded_at_micros`. `tokens.svg` reduces those rows to UTC-aligned six-hour
buckets starting at 00:00, 06:00, 12:00, and 18:00, with connected lines only
across consecutive buckets. It renders all three six-hour measurements on one
shared logarithmic `log1p` Y axis:

```text
Cache hits    = Σ prompt_cached_tokens / 21,600 tokens/s
Cache misses  = Σ (prompt_sent_tokens - prompt_cached_tokens) / 21,600 tokens/s
Output tokens = Σ response_received_tokens / 21,600 tokens/s
```

Those denominators apply to full buckets. At either range boundary, hourly CSV
and six-hour display rates divide by the seconds in the bucket's intersection
with `[since, until)`, not by a full hour/six hours or the span between observations.
CSV `interval_start`, `interval_end`, `elapsed_seconds`, and `partial_bucket`
label partial hourly rows; the SVG labels boundary normalization and the exact
range, and `summary.txt` counts partial hourly/six-hour rows. Bucket points use
the clipped interval midpoint, so current partial buckets stay within the axis.
The axis reaches the selected endpoint; the charts do not fabricate observations
there, extend evidence to it, or connect across missing evidence.

Subscription color identifies the selected profile; line style identifies the
metric. The chart contains exactly those six profile/metric lines. Its
zero-preserving transform is
`log(1 + six-hour tokens/s) / log(1 + largest displayed six-hour tokens/s)`: an
observed zero remains at the baseline, rather than being dropped or replaced
with a positive value. Y ticks label actual tokens/s values, not transformed
coordinates.

The SVG never invents a six-hour bucket for absent evidence and never connects
across a missing UTC six-hour bucket. Missing hourly rows are unknown/missing
evidence, not zero use. An absent
`usage` record is unavailable usage. An old canonical record lacking the
serialized `prompt_cached_tokens` field is also unavailable for this chart:
the extractor does **not** reinterpret it as Cache hits zero, and excludes
that terminal's three categories. A present zero is used because the current
canonical schema serializes the field as a non-optional count.

For token replay/catch-up deduplication, one terminal identity is
`(selected profile label, agent_id, agent_prompt_id, provider_attempt)`.
Repeated identities retain the earliest `(recorded_at_micros, selected file
path, line number)` record **before** the time filter; a replay inside a range
does not turn an original terminal outside it into new consumption. Conflicting
complete-usage counts are reported once per terminal identity, not summed. If
the retained earliest copy lacks `prompt_cached_tokens`, later explicit-zero
replays cannot replace it and that terminal remains omitted. This is intentionally separate from quota
plotting: quota is snapshot evidence, not additive consumption.

## Summary and interpretation

`summary.txt` reports selected profiles/files/bytes, candidate and validated
canonical events, malformed data, missing usage/cache fields, out-of-range and
unselected-model terminals, duplicate/conflicting token identities, retained
quota rows, omitted unchanged quota rows, hourly token rows, rendered values,
and elapsed time. Report these exact values, the exact selection/range, and
the artifact paths with any conclusion.

Remember:

* A quota plateau is repeated observed state, not continuous metering.
* A rise in remaining quota or reset shift can be reset/reconciliation, not
  negative consumption.
* Gaps, empty snapshots, missing terminal usage, and absent hourly rows are
  unknown, not zero.
* Token timestamps are canonical log-admission/accepted-terminal times, not
  provider metering instants.

Run the focused oracle after changing the generator:

```bash
nix shell .#diagnostics -c tau-diagnostics-cargo test \
  --manifest-path .agents/skills/tau-qodq/extract_quota.rs
```