Skip to content

Add a command to show sandbox CPU and memory usage - #30

Merged
miqui merged 3 commits into
mainfrom
sandbox-usage
Nov 18, 2026
Merged

miqui merged 3 commits into
mainfrom
sandbox-usage

Conversation

@miqui

@miqui miqui commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Closes #11

Summary

adapt sandbox usage ID [--hours 1|24] reads GET /v1/sandboxes/{id}/usage, added in platform d3b6c77. It shows measured CPU and resident memory for the last hour (the default) or 24 hours.

In a terminal it prints one table row:

STATUS    CPU OBSERVED  CPU         AVG CPU    MEMORY OBSERVED  MEMORY      AVG MEMORY
complete  1h of 1h      1.00 CPU-h  1.00 vCPU  6m of 1h         0.10 GiB-h  1.0 GiB
  • CPU / MEMORY are the totals billing will use (CPU-hours and GiB-hours).
  • AVG CPU / AVG MEMORY divide those totals by the measured time, so they can be compared directly with --cpu and --memory. Platform sums observedMs and memoryObservedMs over the same intervals as the totals (usage/intervals.ts).
  • CPU OBSERVED / MEMORY OBSERVED are the time each total covers. Either can be shorter than the window, and memory coverage can differ from CPU coverage.
  • A value with no observed time shows as —, not 0, separately for CPU and memory. The platform docs note that zero coverage is not evidence of idle usage.
  • When totals.estimatedIntervals is above zero, a note under the table says how many intervals Platform estimated from allocated resources rather than measured. Only platform migration 0046_usage_reports.sql creates these, and they can reach these windows only during the 24 hours after it runs.

Piped output and --json print the API response unchanged, including the exact decimal-string totals and the 240 chart points.

--hours accepts only 1 or 24. Anything else fails in clap with exit code 2. An unknown sandbox goes through the existing API error path.

Docs

  • docs/api-coverage.md: new row for the route.
  • docs/cli-reference.md: listed in the commands table, plus a short "Sandbox usage" section.
  • skills/adapt/SKILL.md: one example line.

Testing

  • Unit tests in src/commands.rs check the exact rendered table for a measured sandbox, an empty one, one with CPU measured but no memory, one with an hour of CPU but six minutes of memory, and the estimate note (singular, plural, and absent at zero).
  • tests/sandbox_usage/mod.rs uses the mock Platform to check that both windows send hours=1 / hours=24 and that JSON comes back unchanged. It also checks that a 404 reports the API error.
  • --hours 6 is added to the existing argument-error test.
  • cargo fmt --check, cargo clippy --all-targets -D warnings and cargo test pass locally.
  • Not run against a live Platform. The terminal table is covered only by the unit tests, because the integration tests pipe stdout.

🤖 Generated with Claude Code

`adapt sandbox usage ID [--hours 1|24]` reads GET /v1/sandboxes/{id}/usage.
A terminal gets one table row: status, observed time, CPU-hours, average
vCPUs, GiB-hours and average resident memory. Piped output and --json pass
the API response through unchanged, keeping exact decimal-string totals.

Values with no observed time show as a dash rather than zero, separately for
CPU and memory, because zero coverage is not evidence of idle 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: 5/5

Summary

Adds sandbox usage tables and JSON output; both previously reported display defects are resolved, with no remaining actionable findings. Local fmt/clippy, 118 tests, and targeted PTY/JSON checks passed; live Platform integration was not tested.

Deployed verification not applicable: adapt/platform-cli is outside the adapt/adapt and adapt/platform pilot; its workflows configure no PR preview deployment. No webhook sent.

Important Files Changed

File Changes
src/cli.rs Defines usage command, resource selector, and supported measurement windows.
src/commands.rs Renders usage totals, independent coverage, and allocation-estimate notes; includes formatting regression tests.
tests/sandbox_usage/mod.rs Tests window queries, JSON preservation with unequal coverage, and missing-sandbox errors.
tests/cli.rs Registers usage integration tests and rejects unsupported windows.
docs/api-coverage.md Maps the usage API route to its new CLI command.
docs/cli-reference.md Documents usage windows, independent coverage, estimate notes, and JSON output.
skills/adapt/SKILL.md Adds a machine-readable sandbox usage example.

Run info

Field ID
Agent 0d6ccd7e-b62f-4075-a561-199d1a7b1bf0
Automation ec14e69d-634f-4af0-a6dd-27aa06a1f6b3
Run d06d7cbf-bd24-4bc1-af3d-370d3aebaac5

Reviewed: ff76bfb-a190c22 · ↻ Re-run review

Comment thread src/commands.rs Resolved
Comment thread src/commands.rs
json!({
"status": usage["status"],
"observed": format!("{} of {hours}h", duration(observed)),
"cpu": (observed > 0.0).then(|| format!("{:.2} CPU-h", cpu / 3.6e12)),

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[P2] Distinguish allocation estimates from measured utilization

Must fix: Platform includes estimated intervals in totals. estimatedIntervals>0 renders identically to measurements, misrepresenting migrated allocations as utilization. Label estimated/mixed results and add a regression test.

Memory sampling can cover less time than CPU, so a single OBSERVED column
misdescribed the memory totals. The table now shows CPU OBSERVED and
MEMORY OBSERVED, each from its own coverage total.

A new unit test covers an hour of CPU with six minutes of memory. The
integration test also passes --json explicitly for one window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread src/commands.rs
json!({
"status": usage["status"],
"cpu observed": format!("{} of {hours}h", duration(observed)),
"cpu": (observed > 0.0).then(|| format!("{:.2} CPU-h", cpu / 3.6e12)),

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[P2] Distinguish allocation estimates from measured utilization

Must fix: After allocation migration, estimatedIntervals>0 can enter the 24-hour window. Ignoring it presents reserved capacity as measured utilization. Label estimated/mixed totals and add a regression test.

Platform counts migrated allocation estimates (basis "allocated") in usage
totals and reports them only through estimatedIntervals. Without a mark,
reserved capacity read as measured utilization. When estimatedIntervals is
above zero, the terminal view now adds a note under the table with the
count. JSON output already includes the field and is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@miqui
miqui requested a review from scsmithr November 18, 2026 21:37
@miqui
miqui merged commit 5815fcc into main Nov 18, 2026
8 checks passed
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.

Add sandbox CPU and memory usage command

2 participants