Skip to content

feat(runs): add --json output and a usage report over run history - #114

Open
dagoaie wants to merge 1 commit into
Inakitajes:mainfrom
dagoaie:feat/run-history-report-pr
Open

dagoaie wants to merge 1 commit into
Inakitajes:mainfrom
dagoaie:feat/run-history-report-pr

Conversation

@dagoaie

@dagoaie dagoaie commented Sep 13, 2026

Copy link
Copy Markdown

Why

convoy runs is the only reader of the run history and it is interactive: there is no way to ask "what did this pipeline cost this week" or "which step fails most" without opening the browser or parsing metadata.json by hand. Subscription-billed models record cost: 0, so a cost-only view answers nothing for them — tokens are the figure that varies.

Summary

  • convoy runs --json prints the history as a JSON array of durable facts (RunEntry field names; no live/waiting/serverUrl/dir), newest first; workspace-less run records stay with phases: [].
  • convoy runs stats [--group-by pipeline|model|step|day] [--json] aggregates phase usage (tokens by kind, cost, advisor cost, duration, distinct runs, outcomes) into a table with a total row or raw JSON rows.
  • --since <n>d|<n>h|YYYY-MM-DD and --pipeline <name> apply to both, validated before any I/O.
  • Pure modules src/run-history-report.ts (filter + aggregation) and src/run-history-render.ts; RunPhaseInfo gains tokens/logicalModel/startedAt/endedAt; browser and plain listing unchanged.
  • OpenSpec change run-history-report archived with the design. A CSV export and a stats view in the browser are natural follow-ups, as is a probe-free loader for the report modes (listRuns() still probes liveness before the filter applies).

Verification

  • bun run typecheck, bun test (3215 pass), openspec validate run-history-report --strict.
  • Against a real history: stats --since 7d totals equal the sum of --json phase tokens (70 415 154 for implement-gpt), and a single run's figures equal its metadata.json.
  • Ran a two-step OpenRouter/DeepSeek pipeline to check a billed run: its $0.1245 is the exact sum of its phases' recorded cost and shows up by pipeline, model and step next to $0.0000 subscription runs.
  • Implemented with convoy -p implement-gpt and reviewed twice with review-gpt; its findings drove the usage-message contract on invalid --since/--group-by, the \uXXXX escaping of C1/bidi characters in JSON output and the rejection of dash-prefixed option values.

🤖 Generated with Claude Code

https://claude.ai/code/session_0187tW4PcQWpmyDk3Wf6S8p2

`convoy runs --json` prints the run history as a JSON array of durable
facts (no liveness probe results, no workspace paths), and `convoy runs
stats` aggregates the phases' recorded usage by pipeline, model, step or
day as a table or as JSON rows. Both accept `--since <n>d|<n>h|YYYY-MM-DD`
and `--pipeline <name>`; tokens are first-class since subscription models
record a cost of 0.

- change run-history-report
- fix(runs): address review findings on the history report
- fix(runs): harden run history report after adversarial review
- cover run history reporting behavior
- neutralize terminal controls in run usage tables
- align run history reporting with repository patterns

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0187tW4PcQWpmyDk3Wf6S8p2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant