Files
pipelines/internal/protocol/stats.go
T
alan 3f5c11b7bf Record and expose per-run model usage (tokens, split, cost)
Carry the usage a model stage already measures for its budget
(stage.Budget.Snapshot()) onto the step as typed evidence and total it in
one pass, rather than a second harness read, a transcript parse or an
output-length estimate. A shared budget across stage revisits records only
the visit's increment, and a revisit that observes no new report records no
usage instead of a fabricated known zero.

- protocol: StageUsage/RunUsage/TotalUsage and UsageTotals.
- pipeline: step_usage table + migration, COALESCEd into the one step
  projection, FinishStep persistence, one json_extract history aggregate,
  retention removes the rows with their run.
- server: stageUsage maps the budget snapshot, stamping per-stage model and
  usage for every model stage (including failures).
- cli: inspect/stats human and JSON output.
- budget/pi: retain the reported in/out split, mark a total-only (Pi) report
  split-unknown, and keep an unreported cost unknown (never zero).

Evidence and docs updated in the packaged skill references and docs/cli.md;
the live database has no step_usage rows yet (all history predates this), so
per-run figures are reported as unavailable, not zero.
2026-10-17 20:40:56 +01:00

50 lines
1.9 KiB
Go

package protocol
type RunCounts struct {
Total int `json:"total"`
Succeeded int `json:"succeeded"`
Failed int `json:"failed"`
Canceled int `json:"canceled"`
Interrupted int `json:"interrupted"`
Active int `json:"active"`
AverageSeconds float64 `json:"average_seconds"`
}
type PipelineUsage struct {
PipelineID int64 `json:"pipeline_id"`
Name string `json:"name"`
RunCounts
}
type DailyUsage struct {
Date string `json:"date"`
Runs int `json:"runs"`
}
// UsageTotals is the summed reported model usage over all stored run history. It
// is summed from the same per-step usage rows the per-run figures use, so the
// history-wide totals equal the sum of the per-run totals. A stage that reported
// no cost counts in CostUnknownStages and contributes no fabricated or zero cost;
// a stage that reported only a total (Pi) contributes to TokensTotal but not to
// the in/out split, and SplitKnown is true only when every token-reporting stage
// reported a split.
type UsageTotals struct {
TokensTotal int64 `json:"tokens_total"`
TokensIn int64 `json:"tokens_in,omitempty"`
TokensOut int64 `json:"tokens_out,omitempty"`
SplitKnown bool `json:"split_known"`
CostUSD float64 `json:"cost_usd,omitempty"`
Stages int `json:"stages"`
TokensKnownStages int `json:"tokens_known_stages"`
SplitUnknownStages int `json:"split_unknown_stages,omitempty"`
CostKnownStages int `json:"cost_known_stages"`
CostUnknownStages int `json:"cost_unknown_stages,omitempty"`
}
type UsageStats struct {
RunCounts
Pipelines []PipelineUsage `json:"pipelines"`
Days []DailyUsage `json:"days"`
// Usage is the history-wide sum of the per-run reported usage. It is absent
// for a database with no recorded model usage (including a pre-upgrade one).
Usage *UsageTotals `json:"usage,omitempty"`
}