aiworkhub_task_cost_ledger
Summarize repository-bound AI task costs and cache usage by provider, model, day, runner, and topic, with bounded rows and optional task-level detail.
Instructions
READ-ONLY: bounded cost summary, with opt-in detailed dimensions.
Default mode retains cost/cache truth plus provider, model and day
aggregates, and stays bounded as usage history grows. by_model,
cost_per_accepted_outcome.routes and model_outcomes.models
each return at most _COST_LEDGER_SUMMARY_TOP_N rows. by_day
is bounded as two independent groups -- up to
_COST_LEDGER_SUMMARY_TOP_N most-recent dated buckets beside up to
_COST_LEDGER_SUMMARY_TOP_N undated ones -- so its exact ceiling is
2 * _COST_LEDGER_SUMMARY_TOP_N rows, not N; undated spend is
retained rather than made to compete with real days for one shared
bound. Every bounded dimension carries explicit total_count/
returned_count/truncated/ranked_by metadata under
summary_row_bounds, so no row is dropped silently. The two
model-keyed dimensions rank by observed dollars rather than tokens; a
bucket whose provider reported no price ranks on its activity instead
of being cut as though it were free, and a partially priced bucket
ranks in both orders so one cheap priced record cannot hide the
magnitude whose dollars are still unknown. Per-runner and per-topic
maps are available with full=true; task rows remain independently
opt-in through include_tasks.
Kept rows are also narrower than full=true. Each kept model's
cost_per_accepted_outcome.routes adapter folds its family/risk
partitions into one total row, re-derived from summed counters so an
UNKNOWN partition keeps it UNKNOWN; the fold is receipted under
summary_row_bounds. by_day rows keep records,
total_tokens, cost_usd, cost_unknown_records and
cache_hit_ratio. full=true returns both exactly as built.
The repository binding is what makes those aggregates answerable.
build_cost_ledger reads canonical usage events only when it is given a
root; without one it parses the human-readable usage report, whose lines
carry no model, provider or timestamp, so every dimension this docstring
promises collapsed to unknown. Measured 2026-09-02 on this repository:
unbound 590 rows / 1 model / 1 provider / 1 day / 0 usage-observed / 0
cache-observed / 0 routes; bound 3,509 rows / 28 models / 8 providers / 36
days / 2,267 usage-observed / 1,869 cache-observed / 13 routes. Every
other caller (dashboard, manager tools, evidence instruments) already
passed a root; this tool -- the manager's own cost surface -- did not, so
routing by cost and difficulty had no measurement to steer by
(NF-2026-00542).
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "aiworkhub_task_cost_ledger"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | Return the full snapshot exactly as built, including the per-runner and per-topic maps, instead of the bounded summary; default false. | |
| topic | No | Only count usage for this topic; omit for all topics. | |
| runner | No | Only count usage by this runner; omit for all runners. | |
| status | No | Only count usage recorded with this task status; omit for all statuses. | |
| include_tasks | No | Include one row per task as well as the aggregates; default false. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||