Skip to content

Add commands to list and summarize metered usage - #33

Open
miqui wants to merge 4 commits into
mainfrom
usage-history
Open

miqui wants to merge 4 commits into
mainfrom
usage-history

Conversation

@miqui

@miqui miqui commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Implements #14.

Summary

Adds two commands for Platform's metered usage, covering both sandbox runs and model calls:

adapt usage list    [--kind sandbox|model] [--days 7|30|90] [--user USER_ID] [--sandbox SANDBOX] [--limit N] [--cursor CURSOR] [--all]
adapt usage summary [--kind sandbox|model] [--days 7|30|90] [--user USER_ID]
  • usage list calls GET /v1/usage. Without --days it returns all history. --all uses the shared cursor pagination to export every page as one JSON document.
  • usage summary calls GET /v1/usage/summary and defaults to 30 days.
  • Tables (terminal only): one row per run or call for lists; one row per member plus a total row for summaries. Notes flag intervals estimated from allocations, and model calls that reported no token counts. Missing measurements show as —, never 0.
  • JSON: piped output and --json print the API response unchanged.
  • Short totals: CPU and memory totals under 0.01 hours now show in seconds (for example 19.5 CPU-s) instead of rounding to 0.00. This also applies to sandbox usage.

Scope notes (as reviewed on #14)

  • Time ranges: Platform only accepts 7, 30 or 90 UTC days, so the CLI validates --days against those values. Ranges can't be invalid or reversed, and custom dates would need a backend change.
  • Permissions: Platform enforces them. Members only see their own usage; owners, admins and API keys can select a member with --user. Platform also rejects --sandbox for model usage. A full UUID finds the history of a deleted sandbox; an ID prefix needs a sandbox that hasn't been deleted.
  • Help and docs say this is metered usage, not an audit log. They also say model token totals include calls made with the organization's own provider keys, which aren't billed. Only the list's details.credentialSource can separate those calls.

Testing

  • cargo fmt --check, cargo clippy -D warnings and cargo test pass.
  • New integration tests (tests/usage/mod.rs): filters sent unchanged, summary defaults, --all across pages with filters kept, empty results, and invalid options rejected before any request.
  • New unit tests: list and summary tables, and the seconds cutoff.
  • Live run on a staging organization (read-only): list, --limit 5 --all (3 pages, same 14 runs, no duplicates), the model kind with no calls, summaries for both kinds, --user, the server's error for --sandbox with --kind model, and --sandbox for a deleted sandbox (its full UUID returned its run; its prefix returned a 404, as documented). The list's estimate note counted the same 7 intervals as the summary.

Docs

  • docs/cli-reference.md: a new "Metered usage" section, plus the command table and list examples.
  • docs/api-coverage.md: the two routes and the platform commits they come from.
  • skills/adapt/SKILL.md: examples, and usage added to the skill description.

🤖 Generated with Claude Code

miqui and others added 2 commits November 19, 2026 12:25
`adapt usage list` and `adapt usage summary` cover GET /v1/usage and
GET /v1/usage/summary for sandbox runs and model calls. Lists reuse the
shared cursor pagination, so --all exports every page as one JSON document.
Tables show one row per run or call, and per member with a total row for
summaries; JSON passes through unchanged.

Days are limited to the 7, 30, and 90 day windows Platform supports, so
ranges cannot be invalid or reversed. Platform enforces permissions and
rejects --sandbox for model usage. Help and docs say this is metered usage,
not an audit log, and that model token totals include calls made with the
organization's own provider keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CPU and memory totals under 0.01 hours rounded to 0.00 CPU-h or GiB-h, which
read as no usage even though usage was measured. On a staging organization,
most short sandbox runs showed zero. Totals under 36 seconds now show in
resource-seconds, such as 19.5 CPU-s, in both `usage` and `sandbox usage`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@the-adaptile the-adaptile Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confidence Score: 4/5

Summary

Adds read-only usage listing, summaries, and resource-time formatting; both earlier findings are resolved. Formatting, Clippy, 133 tests, and focused mock-terminal checks passed locally; no remaining actionable issues found, but live API behavior was not tested.

Deployed verification not applicable: adapt/platform-cli is outside the adapt/adapt and adapt/platform pilot. Its CI builds CLI artifacts but configures no PR preview. No webhook was sent.

Important Files Changed

File Changes
src/cli.rs Usage subcommands, validated windows, member filters, and corrected historical sandbox selector help.
src/commands.rs Usage requests, terminal tables, aggregated estimate notes, and shared resource-time formatting.
src/output.rs Shared pagination hint for terminal tables.
tests/usage/mod.rs Filters, summary defaults, pagination, JSON provenance, help semantics, and invalid arguments.
tests/cli.rs Registers the usage integration tests.
docs/cli-reference.md Documents metering semantics, estimate notes, historical sandbox filtering, and output units.
docs/api-coverage.md Maps usage endpoints to CLI commands and Platform revisions.
skills/adapt/SKILL.md Adds metered-usage discovery and command examples.

Run info

Field ID
Agent 0d6ccd7e-b62f-4075-a561-199d1a7b1bf0
Automation ec14e69d-634f-4af0-a6dd-27aa06a1f6b3
Run 3673c3b5-e701-4689-af8c-c700af14ea5b

Reviewed: 9f5e86c-b6ef411 · ↻ Re-run review

Comment thread src/commands.rs Resolved
Comment thread docs/cli-reference.md Resolved
miqui and others added 2 commits November 19, 2026 13:49
Sandbox usage lists now note intervals that Platform estimated from
allocated resources across the displayed records, as summaries and
`sandbox usage` already do. JSON output is unchanged.

Platform returns full sandbox UUIDs without a lookup, so they filter the
history of deleted sandboxes; only ID prefixes need a sandbox that hasn't
been deleted. Help and docs now say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolves conflicts with the model catalog commands (#32) by keeping both
sides: the usage and model command definitions, both reference sections,
and both platform provenance notes in the API coverage doc.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@miqui
miqui requested a review from scsmithr November 19, 2026 19:04

This branch has not been deployed

No deployments
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