From a127703e8e83d4835ab212bcd723918b3c1a187f Mon Sep 17 00:00:00 2001 From: miqui Date: Thu, 19 Nov 2026 12:25:53 -0500 Subject: [PATCH 1/3] Add commands to list and summarize metered usage `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 --- docs/api-coverage.md | 5 +- docs/cli-reference.md | 33 ++++ skills/adapt/SKILL.md | 5 +- src/cli.rs | 61 ++++++++ src/commands.rs | 357 ++++++++++++++++++++++++++++++++++++++++-- src/output.rs | 18 ++- tests/cli.rs | 1 + tests/usage/mod.rs | 142 +++++++++++++++++ 8 files changed, 597 insertions(+), 25 deletions(-) create mode 100644 tests/usage/mod.rs diff --git a/docs/api-coverage.md b/docs/api-coverage.md index 722684b..4cf7578 100644 --- a/docs/api-coverage.md +++ b/docs/api-coverage.md @@ -3,7 +3,8 @@ Based on the resource OpenAPI document from `../platform` at `f20ded3`, plus its dashboard auth integrations. The `query` filter on `GET /v1/sandboxes` and the `name` and `status` filters on `GET /v1/images` come from platform `2396647`. `GET /v1/sandboxes/{id}/usage` -comes from platform `d3b6c77`. +comes from platform `d3b6c77`. `GET /v1/usage` and `GET /v1/usage/summary` come from +platform `8af1e3e`, and their model usage from `1ae5640`. Every resource operation has a named command. `adapt api METHOD PATH` also exposes same-origin JSON requests for less common account operations. @@ -22,6 +23,8 @@ one from the CLI, or reuse the UUID supplied with `--idempotency-key`. | `GET /v1/sandboxes` | `sandbox list [--query TEXT]` | | `GET /v1/sandboxes/{id}` | `sandbox get ID` | | `GET /v1/sandboxes/{id}/usage` | `sandbox usage ID [--hours 1\|24]` | +| `GET /v1/usage` | `usage list [--kind sandbox\|model] [--days 7\|30\|90] [--user ID] [--sandbox ID]` | +| `GET /v1/usage/summary` | `usage summary [--kind sandbox\|model] [--days 7\|30\|90] [--user ID]` | | `DELETE /v1/sandboxes/{id}` | `sandbox delete ID` | | `POST /v1/sandboxes/{id}/start` | `sandbox start ID` | | `POST /v1/sandboxes/{id}/stop` | `sandbox stop ID` | diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 13c946a..2aaed36 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -45,6 +45,7 @@ For example, use `adapt org members ls` or `adapt sandbox ls --all`. | `keys` | `list`, `create`, `delete` | | `sessions` | `list`, `revoke`, `revoke-others` | | `mcp` | `list`, `revoke`, `tools` | +| `usage` | `list`, `summary` | | `events` | Show organization changes, or personal changes with `--personal` | | `health` | Test API availability, or database readiness with `--ready` | | `profiles` | Show saved API URLs, organizations, and credential status | @@ -390,6 +391,37 @@ Create a sandbox with the image and variable set: adapt sandbox create --image-id IMAGE_ID --variable-set VARIABLE_SET_ID --wait ``` +## Metered usage + +```sh +adapt usage list +adapt usage list --kind model --days 7 +adapt usage list --sandbox SANDBOX_ID --all --json +adapt usage summary +adapt usage summary --kind model --days 90 --user USER_ID +``` + +These commands show metered sandbox runs and model calls. +They are not an audit log of user activity. +Members see only their own usage. +Owners, admins, and API keys see the whole organization and can select one member with `--user`. + +`usage list` shows records newest first, one row per sandbox run or model call. +Use `--kind model` for model calls; the default is `sandbox`. +`--days` accepts `7`, `30`, or `90` and counts UTC days, including today. +Without `--days`, the list includes all history. +Sandbox runs count if they finished in that time or are still running. +`--sandbox` accepts a full UUID or an ID prefix of a sandbox that still exists, and only works with sandbox usage. + +`usage summary` totals usage per member over the last 30 UTC days, or over `--days`. +The table adds a total row. +A dash means nothing was measured, not zero usage. +Notes under the table count intervals that Platform estimated from allocated resources, and model calls that reported no token counts. +Model token totals include calls made with your organization's own provider keys. +To separate them, use `usage list --kind model --json` and check each call's `details.credentialSource`. + +Use `--json` for exact totals, daily rows, and per-model breakdowns. + ## Resource IDs These resources accept full UUIDs or unique ID prefixes: @@ -469,6 +501,7 @@ adapt sandbox list --limit 50 --cursor CURSOR adapt sandbox list --query web --all --json adapt images list --status ready adapt images list --name ubuntu --all +adapt usage list --kind model --days 30 --all --json ``` `sandbox list --query TEXT` matches names that contain TEXT, without case sensitivity. diff --git a/skills/adapt/SKILL.md b/skills/adapt/SKILL.md index 1bfc05d..e20a236 100644 --- a/skills/adapt/SKILL.md +++ b/skills/adapt/SKILL.md @@ -2,7 +2,8 @@ name: adapt description: >- Use the adapt CLI to manage Adapt Platform sandboxes, run remote commands, - transfer files, and discover or execute tools from connected MCP servers. + transfer files, check metered usage, and discover or execute tools from + connected MCP servers. Use when the user asks to work with Platform resources or their connected tools. --- @@ -52,6 +53,8 @@ adapt sandbox sh --image ubuntu:24.04 -- uname -a adapt sandbox sh --image-id IMAGE_ID --cpu 2 --memory 2048 -- /bin/sh -lc 'echo hello; uname -a' adapt sandbox create --image-id IMAGE_ID --wait adapt sandbox usage SANDBOX_ID --hours 24 --json +adapt usage summary --kind model --days 7 --json +adapt usage list --kind sandbox --days 30 --all --json adapt exec SANDBOX_ID --cwd /app -- /bin/sh -lc 'npm test' ``` diff --git a/src/cli.rs b/src/cli.rs index 61b7597..e3484ff 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -84,6 +84,9 @@ pub enum Command { /// Inspect connected MCP clients and the tools the Platform MCP server provides #[command(subcommand)] Mcp(McpCommand), + /// Show metered sandbox and model usage (not an audit log) + #[command(subcommand)] + Usage(UsageCommand), /// Watch resource changes as newline-delimited JSON Events { #[arg(long)] @@ -725,6 +728,64 @@ pub enum SessionCommand { RevokeOthers, } +#[derive(Subcommand)] +#[command( + after_help = "This is metered usage, not an audit log.\nMembers see only their own usage; owners, admins, and API keys see the whole organization." +)] +pub enum UsageCommand { + /// List metered sandbox runs or model calls, newest first + #[command( + visible_alias = "ls", + after_help = "This is metered usage, not an audit log." + )] + List(UsageList), + /// Total metered usage per member over the last 7, 30, or 90 UTC days + #[command( + after_help = "This is metered usage, not an audit log.\nModel token totals include calls made with your organization's own provider keys.\nTo separate them, use `usage list --kind model --json` and check each call's details.credentialSource." + )] + Summary(UsageSummary), +} + +#[derive(Args)] +pub struct UsageScope { + /// Kind of usage + #[arg(long, value_enum, default_value = "sandbox")] + pub kind: UsageKind, + /// Show one member's usage (owners, admins, and API keys only) + #[arg(long, value_name = "USER_ID")] + pub user: Option, +} + +#[derive(Clone, Copy, ValueEnum)] +pub enum UsageKind { + Sandbox, + Model, +} + +#[derive(Args)] +pub struct UsageList { + #[command(flatten)] + pub scope: UsageScope, + /// Limit to the last N UTC days, including today; omit for all history. + /// Sandbox runs count if they finished in that time or are still running + #[arg(long, value_parser = ["7", "30", "90"])] + pub days: Option, + /// Show runs of one existing sandbox (full UUID or unambiguous ID prefix) + #[arg(long)] + pub sandbox: Option, + #[command(flatten)] + pub page: Page, +} + +#[derive(Args)] +pub struct UsageSummary { + #[command(flatten)] + pub scope: UsageScope, + /// Number of UTC days to total, including today + #[arg(long, default_value = "30", value_parser = ["7", "30", "90"])] + pub days: String, +} + #[derive(Subcommand)] pub enum McpCommand { /// List MCP clients you have authorized diff --git a/src/commands.rs b/src/commands.rs index 4b3f66b..1dfac60 100644 --- a/src/commands.rs +++ b/src/commands.rs @@ -205,6 +205,8 @@ pub async fn run(cli: Cli) -> Result { McpCommand::List => api.get("/v1/auth/mcp/connections").await?, McpCommand::Revoke { id } => api.post("/v1/auth/mcp/revoke", &json!({"id":id.to_string()})).await?, }, + Command::Usage(UsageCommand::List(args)) => return list_usage(&api, args, cli.json).await, + Command::Usage(UsageCommand::Summary(args)) => return usage_summary(&api, args, cli.json).await, Command::Events { personal } => return stream::events(&api, personal).await, Command::Health { ready } => api.get(if ready { "/ready" } else { "/health" }).await?, Command::Api(args) => api.json(args.method.parse()?, &args.path, args.data.as_deref().map(input::json).transpose()?.as_ref(), &args.query, args.idempotency_key.as_ref().map(|id| id.to_string()).as_deref()).await?, @@ -398,11 +400,16 @@ const USAGE_COLUMNS: [&str; 7] = [ "avg memory", ]; -/// Writes one table row, then a note when the totals include migrated allocation -/// estimates, which would otherwise look the same as measurements. +/// Writes one table row, then notes any migrated allocation estimates. fn write_usage(out: &mut impl Write, usage: &Value, hours: &str) -> io::Result<()> { output::table(out, &USAGE_COLUMNS, &[usage_row(usage, hours)])?; - match usage["totals"]["estimatedIntervals"].as_u64() { + estimated_note(out, &usage["totals"]) +} + +/// Notes totals that include migrated allocation estimates, which would otherwise +/// look the same as measurements. +fn estimated_note(out: &mut impl Write, totals: &Value) -> io::Result<()> { + match totals["estimatedIntervals"].as_u64() { None | Some(0) => Ok(()), Some(n) => { let plural = if n == 1 { "" } else { "s" }; @@ -414,33 +421,55 @@ fn write_usage(out: &mut impl Write, usage: &Value, hours: &str) -> io::Result<( } } -/// Converts exact usage totals to readable units. Values without any observed -/// time are null (shown as —), because zero coverage is not evidence of idling. +const GIB: f64 = (1u64 << 30) as f64; + +/// Reads one of Platform's exact decimal totals; f64 precision suffices for display. +fn exact(totals: &Value, key: &str) -> f64 { + totals[key] + .as_str() + .and_then(|text| text.parse::().ok()) + .unwrap_or(0.0) +} + +/// CPU-hours, or None (shown as —) without observed time, because zero coverage +/// is not evidence of idling. +fn cpu_hours(totals: &Value) -> Option { + (totals["observedMs"].as_f64().unwrap_or(0.0) > 0.0) + .then(|| format!("{:.2} CPU-h", exact(totals, "cpuNanoseconds") / 3.6e12)) +} + +/// Resident GiB-hours, or None (shown as —) without observed memory time. +fn memory_hours(totals: &Value) -> Option { + (totals["memoryObservedMs"].as_f64().unwrap_or(0.0) > 0.0).then(|| { + format!( + "{:.2} GiB-h", + exact(totals, "residentByteMilliseconds") / (GIB * 3.6e6) + ) + }) +} + +/// Converts exact usage totals to readable units. fn usage_row(usage: &Value, hours: &str) -> Value { let totals = &usage["totals"]; - let exact = |key: &str| { - totals[key] - .as_str() - .and_then(|text| text.parse::().ok()) - .unwrap_or(0.0) - }; - let (cpu, ram) = (exact("cpuNanoseconds"), exact("residentByteMilliseconds")); + let (cpu, ram) = ( + exact(totals, "cpuNanoseconds"), + exact(totals, "residentByteMilliseconds"), + ); let observed = totals["observedMs"].as_f64().unwrap_or(0.0); let ram_observed = totals["memoryObservedMs"].as_f64().unwrap_or(0.0); - let gib = f64::from(1u32 << 30); json!({ "status": usage["status"], "cpu observed": format!("{} of {hours}h", duration(observed)), - "cpu": (observed > 0.0).then(|| format!("{:.2} CPU-h", cpu / 3.6e12)), + "cpu": cpu_hours(totals), "avg cpu": (observed > 0.0).then(|| format!("{:.2} vCPU", cpu / (observed * 1e6))), "memory observed": format!("{} of {hours}h", duration(ram_observed)), - "memory": (ram_observed > 0.0).then(|| format!("{:.2} GiB-h", ram / (gib * 3.6e6))), + "memory": memory_hours(totals), "avg memory": (ram_observed > 0.0).then(|| { let bytes = ram / ram_observed; - if bytes < gib { + if bytes < GIB { format!("{:.0} MiB", bytes / f64::from(1u32 << 20)) } else { - format!("{:.1} GiB", bytes / gib) + format!("{:.1} GiB", bytes / GIB) } }), }) @@ -456,6 +485,168 @@ fn duration(ms: f64) -> String { } } +async fn list_usage(api: &Api, args: UsageList, json: bool) -> Result { + let mut filters = usage_scope(&args.scope); + if let Some(days) = args.days { + filters.push(("days".into(), days)); + } + if let Some(sandbox) = args.sandbox { + filters.push(("sandboxId".into(), sandbox.to_string())); + } + let result = api + .list("/v1/usage", "events", &args.page, true, &filters) + .await?; + if output::tables(json) { + write_usage_events(&mut io::stdout().lock(), &result)?; + } else { + output::print(&result, json)?; + } + Ok(0) +} + +async fn usage_summary(api: &Api, args: UsageSummary, json: bool) -> Result { + let mut query = usage_scope(&args.scope); + query.push(("days".into(), args.days)); + let summary = api + .json(Method::GET, "/v1/usage/summary", None, &query, None) + .await?; + if output::tables(json) { + write_usage_summary(&mut io::stdout().lock(), &summary)?; + } else { + output::print(&summary, json)?; + } + Ok(0) +} + +/// Query parameters shared by usage lists and summaries. +fn usage_scope(scope: &UsageScope) -> Vec<(String, String)> { + let mut query = vec![("kind".to_owned(), choice(scope.kind))]; + if let Some(user) = scope.user { + query.push(("userId".into(), user.to_string())); + } + query +} + +/// Writes one row per sandbox run or model call; missing measurements show as —. +fn write_usage_events(out: &mut impl Write, result: &Value) -> io::Result<()> { + let events = result["events"] + .as_array() + .map(Vec::as_slice) + .unwrap_or_default(); + let Some(first) = events.first() else { + return writeln!(out, "No usage."); + }; + let took = |event: &Value| event["usage"]["durationMs"].as_f64().map(duration); + if first["kind"] == "model" { + let rows: Vec = events + .iter() + .map(|event| { + json!({ + "created (utc)": minute(&event["createdAt"]), + "model": event["details"]["model"], + "credentials": event["details"]["credentialSource"], + "status": event["details"]["status"], + "duration": took(event), + "input tokens": event["usage"]["inputTokens"], + "output tokens": event["usage"]["outputTokens"], + }) + }) + .collect(); + let keys = [ + "created (utc)", + "model", + "credentials", + "status", + "duration", + "input tokens", + "output tokens", + ]; + output::table(out, &keys, &rows)?; + } else { + let rows: Vec = events + .iter() + .map(|event| { + json!({ + "created (utc)": minute(&event["createdAt"]), + "sandbox": event["sandboxId"], + "status": event["status"], + "duration": took(event), + "cpu": cpu_hours(&event["usage"]), + "memory": memory_hours(&event["usage"]), + }) + }) + .collect(); + let keys = [ + "created (utc)", + "sandbox", + "status", + "duration", + "cpu", + "memory", + ]; + output::table(out, &keys, &rows)?; + } + output::next_page(out, result) +} + +/// Writes one row per member plus a total row, then notes incomplete data. +fn write_usage_summary(out: &mut impl Write, summary: &Value) -> io::Result<()> { + let members = summary["members"] + .as_array() + .map(Vec::as_slice) + .unwrap_or_default(); + let named = members + .iter() + .map(|member| (member["name"].clone(), member)) + .chain([(json!("Total"), &summary["totals"])]); + if summary["kind"] == "model" { + let rows: Vec = named + .map(|(name, m)| { + json!({ + "member": name, + "calls": m["calls"], + "input tokens": m["inputTokens"], + "output tokens": m["outputTokens"], + }) + }) + .collect(); + output::table( + out, + &["member", "calls", "input tokens", "output tokens"], + &rows, + )?; + match summary["missingTokenCalls"].as_u64() { + None | Some(0) => Ok(()), + Some(n) => { + let plural = if n == 1 { "" } else { "s" }; + writeln!( + out, + "\n{n} call{plural} did not report input or output token counts." + ) + } + } + } else { + let rows: Vec = named + .map(|(name, m)| { + json!({ + "member": name, + "runs": m["runs"], + "cpu": cpu_hours(m), + "memory": memory_hours(m), + }) + }) + .collect(); + output::table(out, &["member", "runs", "cpu", "memory"], &rows)?; + estimated_note(out, &summary["totals"]) + } +} + +/// Shortens an ISO timestamp to the minute, e.g. 2026-11-18 14:02. +fn minute(at: &Value) -> Option { + let at = at.as_str()?; + Some(format!("{} {}", at.get(..10)?, at.get(11..16)?)) +} + pub(crate) async fn create_sandbox(api: &Api, args: SandboxCreate) -> Result { let mut body = input::object(args.data.as_deref())?; if args.image.is_some() { @@ -1084,4 +1275,136 @@ mod tests { ) ); } + + fn written(write: fn(&mut Vec, &Value) -> io::Result<()>, value: Value) -> String { + let mut out = Vec::new(); + write(&mut out, &value).unwrap(); + String::from_utf8(out).unwrap() + } + + /// Splits table lines into cells; column padding is covered by the output tests. + fn cells(rendered: &str) -> Vec> { + rendered + .lines() + .map(|line| { + line.split(" ") + .map(str::trim) + .filter(|cell| !cell.is_empty()) + .collect() + }) + .collect() + } + + const ID: &str = "11111111-1111-4111-8111-111111111111"; + + #[test] + fn usage_list_shows_one_row_per_run_and_the_next_page() { + let events = json!({"events":[ + {"kind":"sandbox","createdAt":"2026-11-18T14:02:11.000Z","sandboxId":ID,"status":"finished", + "usage":{"durationMs":3600000,"cpuNanoseconds":"1834000000000", + "residentByteMilliseconds":"3865470566400000","observedMs":3600000,"memoryObservedMs":3600000}}, + {"kind":"sandbox","createdAt":"2026-11-19T16:18:00.000Z","sandboxId":ID,"status":"running", + "usage":{"durationMs":120000,"cpuNanoseconds":"0","residentByteMilliseconds":"0", + "observedMs":0,"memoryObservedMs":0}} + ],"nextCursor":"33333333-3333-4333-8333-333333333333"}); + let out = written(write_usage_events, events); + assert_eq!( + cells(&out), + [ + vec![ + "CREATED (UTC)", + "SANDBOX", + "STATUS", + "DURATION", + "CPU", + "MEMORY" + ], + vec![ + "2026-11-18 14:02", + ID, + "finished", + "1h", + "0.51 CPU-h", + "1.00 GiB-h" + ], + vec!["2026-11-19 16:18", ID, "running", "2m", "—", "—"], + vec![], + vec![ + "Next page: rerun with --cursor 33333333-3333-4333-8333-333333333333 (or use --all)" + ], + ] + ); + } + + #[test] + fn usage_list_shows_model_tokens_and_empty_results() { + let events = json!({"events":[ + {"kind":"model","createdAt":"2026-11-18T14:05:00.000Z", + "details":{"model":"claude-sonnet-5-5","credentialSource":"adapt","status":"succeeded"}, + "usage":{"durationMs":4210,"inputTokens":1830,"outputTokens":null}} + ],"nextCursor":null}); + let out = written(write_usage_events, events); + assert_eq!( + cells(&out), + [ + vec![ + "CREATED (UTC)", + "MODEL", + "CREDENTIALS", + "STATUS", + "DURATION", + "INPUT TOKENS", + "OUTPUT TOKENS" + ], + vec![ + "2026-11-18 14:05", + "claude-sonnet-5-5", + "adapt", + "succeeded", + "4s", + "1830", + "—" + ], + ] + ); + let empty = json!({"events":[],"nextCursor":null}); + assert_eq!(written(write_usage_events, empty), "No usage.\n"); + } + + #[test] + fn usage_summary_adds_a_total_row_and_notes_incomplete_data() { + let sandbox = json!({"kind":"sandbox","members":[ + {"name":"Ada Lovelace","runs":3,"cpuNanoseconds":"1834000000000", + "residentByteMilliseconds":"3865470566400000","observedMs":3600000,"memoryObservedMs":3600000}, + {"name":"API keys","runs":1,"cpuNanoseconds":"0","residentByteMilliseconds":"0", + "observedMs":0,"memoryObservedMs":0} + ],"totals":{"runs":4,"cpuNanoseconds":"1834000000000","residentByteMilliseconds":"3865470566400000", + "observedMs":3600000,"memoryObservedMs":3600000,"estimatedIntervals":2}}); + let out = written(write_usage_summary, sandbox); + assert_eq!( + cells(&out), + [ + vec!["MEMBER", "RUNS", "CPU", "MEMORY"], + vec!["Ada Lovelace", "3", "0.51 CPU-h", "1.00 GiB-h"], + vec!["API keys", "1", "—", "—"], + vec!["Total", "4", "0.51 CPU-h", "1.00 GiB-h"], + vec![], + vec!["Includes 2 intervals estimated from allocated resources, not measured."], + ] + ); + let model = json!({"kind":"model","members":[ + {"name":"Ada Lovelace","calls":120,"inputTokens":219600,"outputTokens":null} + ],"totals":{"calls":120,"inputTokens":219600,"outputTokens":null},"missingTokenCalls":1}); + let out = written(write_usage_summary, model); + assert_eq!( + cells(&out), + [ + vec!["MEMBER", "CALLS", "INPUT TOKENS", "OUTPUT TOKENS"], + vec!["Ada Lovelace", "120", "219600", "—"], + vec!["Total", "120", "219600", "—"], + vec![], + vec!["1 call did not report input or output token counts."], + ] + ); + } } diff --git a/src/output.rs b/src/output.rs index fa3102f..6222cc0 100644 --- a/src/output.rs +++ b/src/output.rs @@ -55,12 +55,7 @@ pub fn print(value: &Value, json: bool) -> Result<()> { .collect(); if !keys.is_empty() { table(&mut out, &keys, rows)?; - if let Some(cursor) = value["nextCursor"].as_str() { - writeln!( - out, - "\nNext page: rerun with --cursor {cursor} (or use --all)" - )?; - } + next_page(&mut out, value)?; return Ok(()); } } @@ -69,6 +64,17 @@ pub fn print(value: &Value, json: bool) -> Result<()> { Ok(()) } +/// Tells table readers how to get the next page of a cursor-paginated list. +pub fn next_page(out: &mut impl Write, value: &Value) -> io::Result<()> { + match value["nextCursor"].as_str() { + Some(cursor) => writeln!( + out, + "\nNext page: rerun with --cursor {cursor} (or use --all)" + ), + None => Ok(()), + } +} + /// Writes `keys` of each row as left-aligned columns under uppercase headings. /// Cells are sanitized and cut at 80 characters; missing values show as —. pub fn table(out: &mut impl Write, keys: &[&str], rows: &[Value]) -> io::Result<()> { diff --git a/tests/cli.rs b/tests/cli.rs index b573335..493d4c3 100644 --- a/tests/cli.rs +++ b/tests/cli.rs @@ -12,6 +12,7 @@ mod sandbox_list; mod sandbox_prefixes; mod sandbox_sh; mod sandbox_usage; +mod usage; #[test] fn help_and_argument_validation() { diff --git a/tests/usage/mod.rs b/tests/usage/mod.rs new file mode 100644 index 0000000..8dfb43c --- /dev/null +++ b/tests/usage/mod.rs @@ -0,0 +1,142 @@ +use crate::support::*; +use serde_json::json; + +// Platform enforces permissions and applies the filters (see the platform API's usage routes). +// These tests verify that the CLI sends the filters unchanged and passes JSON through. + +#[test] +fn list_forwards_filters() { + let events = json!({"events":[{"id":ID,"kind":"sandbox"}],"asOf":"2026-11-19T16:20:00.000Z","nextCursor":null}); + let server = Server::start(vec![ + step( + "GET", + "/v1/usage?limit=50&kind=sandbox".into(), + None, + events.clone(), + ), + step( + "GET", + format!("/v1/usage?limit=50&kind=sandbox&userId={KEY}&days=7&sandboxId=1111abcd"), + None, + events.clone(), + ), + step( + "GET", + "/v1/usage?limit=50&kind=model&days=90".into(), + None, + events.clone(), + ), + ]); + let dir = tempfile::tempdir().unwrap(); + for args in [ + vec!["usage", "list"], + vec![ + "usage", + "ls", + "--user", + KEY, + "--days", + "7", + "--sandbox", + "1111ABCD", + ], + vec!["usage", "list", "--kind", "model", "--days", "90", "--json"], + ] { + assert_eq!(success(&run(dir.path(), &server.url, &args)), events); + } + server.finish(); +} + +#[test] +fn summary_defaults_to_30_days_and_forwards_filters() { + let summary = json!({"kind":"sandbox","members":[],"totals":{"runs":0}}); + let server = Server::start(vec![ + step( + "GET", + "/v1/usage/summary?kind=sandbox&days=30".into(), + None, + summary.clone(), + ), + step( + "GET", + format!("/v1/usage/summary?kind=model&userId={KEY}&days=7"), + None, + summary.clone(), + ), + ]); + let dir = tempfile::tempdir().unwrap(); + for args in [ + vec!["usage", "summary"], + vec![ + "usage", "summary", "--kind", "model", "--user", KEY, "--days", "7", + ], + ] { + assert_eq!(success(&run(dir.path(), &server.url, &args)), summary); + } + server.finish(); +} + +#[test] +fn list_all_follows_every_page_with_the_same_filters() { + let server = Server::start(vec![ + step( + "GET", + "/v1/usage?limit=1&kind=model&days=30".into(), + None, + json!({"events":[{"id":ID}],"asOf":"2026-11-19T16:20:00.000Z","nextCursor":KEY}), + ), + step( + "GET", + format!("/v1/usage?limit=1&kind=model&days=30&cursor={KEY}"), + None, + json!({"events":[{"id":ORG}],"asOf":"2026-11-19T16:20:01.000Z","nextCursor":null}), + ), + ]); + let dir = tempfile::tempdir().unwrap(); + let all = success(&run( + dir.path(), + &server.url, + &[ + "usage", "list", "--kind", "model", "--days", "30", "--limit", "1", "--all", + ], + )); + assert_eq!( + all, + json!({"events":[{"id":ID},{"id":ORG}],"asOf":"2026-11-19T16:20:00.000Z","nextCursor":null}) + ); + server.finish(); +} + +#[test] +fn empty_usage_keeps_the_json_envelope() { + let empty = json!({"events":[],"asOf":"2026-11-19T16:20:00.000Z","nextCursor":null}); + let server = Server::start(vec![step( + "GET", + "/v1/usage?limit=50&kind=sandbox&days=7".into(), + None, + empty.clone(), + )]); + let dir = tempfile::tempdir().unwrap(); + let output = run(dir.path(), &server.url, &["usage", "list", "--days", "7"]); + assert_eq!(success(&output), empty); + assert!(output.stderr.is_empty()); + server.finish(); +} + +#[test] +fn invalid_options_are_rejected_locally() { + let dir = tempfile::tempdir().unwrap(); + for args in [ + // Platform supports only these fixed windows, so ranges cannot be invalid or reversed. + vec!["usage", "list", "--days", "14"], + vec!["usage", "summary", "--days", "1"], + vec!["usage", "list", "--kind", "audit"], + vec!["usage", "summary", "--user", "alice@example.com"], + vec!["usage", "list", "--sandbox", "not-an-id"], + vec!["usage", "list", "--limit", "101"], + vec!["usage", "summary", "--all"], + ] { + let output = run(dir.path(), "http://localhost:1", &args); + assert_eq!(output.status.code(), Some(2), "{args:?}"); + } +} From 35973e9d03fa1ebc0988fc428038c79f03241b69 Mon Sep 17 00:00:00 2001 From: miqui Date: Thu, 19 Nov 2026 12:26:47 -0500 Subject: [PATCH 2/3] Show short resource totals in seconds 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 --- docs/cli-reference.md | 2 ++ src/commands.rs | 50 +++++++++++++++++++++++++++++++------------ 2 files changed, 38 insertions(+), 14 deletions(-) diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 2aaed36..2adf22f 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -243,6 +243,7 @@ Shows measured CPU and resident memory for the last hour (default) or 24 hours. Each can be shorter than the requested window, and memory coverage can differ from CPU coverage. For example, one hour of CPU data and six minutes of memory data show `1h of 1h` and `6m of 1h`, respectively. A dash means nothing was measured, not zero usage. +Totals under 0.01 hours show in seconds, for example `19.5 CPU-s`, so short runs don't round to zero. A note under the table counts intervals that Platform estimated from allocated resources instead of measuring. Use `--json` for the exact Platform totals and chart points. @@ -416,6 +417,7 @@ Sandbox runs count if they finished in that time or are still running. `usage summary` totals usage per member over the last 30 UTC days, or over `--days`. The table adds a total row. A dash means nothing was measured, not zero usage. +As with `sandbox usage`, totals under 0.01 hours show in seconds. Notes under the table count intervals that Platform estimated from allocated resources, and model calls that reported no token counts. Model token totals include calls made with your organization's own provider keys. To separate them, use `usage list --kind model --json` and check each call's `details.credentialSource`. diff --git a/src/commands.rs b/src/commands.rs index 1dfac60..623c635 100644 --- a/src/commands.rs +++ b/src/commands.rs @@ -431,23 +431,33 @@ fn exact(totals: &Value, key: &str) -> f64 { .unwrap_or(0.0) } -/// CPU-hours, or None (shown as —) without observed time, because zero coverage +/// CPU time, or None (shown as —) without observed time, because zero coverage /// is not evidence of idling. -fn cpu_hours(totals: &Value) -> Option { +fn cpu_time(totals: &Value) -> Option { (totals["observedMs"].as_f64().unwrap_or(0.0) > 0.0) - .then(|| format!("{:.2} CPU-h", exact(totals, "cpuNanoseconds") / 3.6e12)) + .then(|| resource_time(exact(totals, "cpuNanoseconds") / 1e9, "CPU")) } -/// Resident GiB-hours, or None (shown as —) without observed memory time. -fn memory_hours(totals: &Value) -> Option { +/// Resident memory time, or None (shown as —) without observed memory time. +fn memory_time(totals: &Value) -> Option { (totals["memoryObservedMs"].as_f64().unwrap_or(0.0) > 0.0).then(|| { - format!( - "{:.2} GiB-h", - exact(totals, "residentByteMilliseconds") / (GIB * 3.6e6) + resource_time( + exact(totals, "residentByteMilliseconds") / (GIB * 1e3), + "GiB", ) }) } +/// Formats resource-seconds in hours, or in seconds below 0.01 hours so short +/// runs don't round to zero, e.g. 1.25 CPU-h or 19.5 CPU-s. +fn resource_time(seconds: f64, unit: &str) -> String { + if seconds >= 36.0 { + format!("{:.2} {unit}-h", seconds / 3600.0) + } else { + format!("{seconds:.1} {unit}-s") + } +} + /// Converts exact usage totals to readable units. fn usage_row(usage: &Value, hours: &str) -> Value { let totals = &usage["totals"]; @@ -460,10 +470,10 @@ fn usage_row(usage: &Value, hours: &str) -> Value { json!({ "status": usage["status"], "cpu observed": format!("{} of {hours}h", duration(observed)), - "cpu": cpu_hours(totals), + "cpu": cpu_time(totals), "avg cpu": (observed > 0.0).then(|| format!("{:.2} vCPU", cpu / (observed * 1e6))), "memory observed": format!("{} of {hours}h", duration(ram_observed)), - "memory": memory_hours(totals), + "memory": memory_time(totals), "avg memory": (ram_observed > 0.0).then(|| { let bytes = ram / ram_observed; if bytes < GIB { @@ -571,8 +581,8 @@ fn write_usage_events(out: &mut impl Write, result: &Value) -> io::Result<()> { "sandbox": event["sandboxId"], "status": event["status"], "duration": took(event), - "cpu": cpu_hours(&event["usage"]), - "memory": memory_hours(&event["usage"]), + "cpu": cpu_time(&event["usage"]), + "memory": memory_time(&event["usage"]), }) }) .collect(); @@ -631,8 +641,8 @@ fn write_usage_summary(out: &mut impl Write, summary: &Value) -> io::Result<()> json!({ "member": name, "runs": m["runs"], - "cpu": cpu_hours(m), - "memory": memory_hours(m), + "cpu": cpu_time(m), + "memory": memory_time(m), }) }) .collect(); @@ -1297,6 +1307,18 @@ mod tests { const ID: &str = "11111111-1111-4111-8111-111111111111"; + #[test] + fn short_totals_show_seconds_instead_of_rounding_to_zero() { + assert_eq!(resource_time(0.54, "CPU"), "0.5 CPU-s"); + assert_eq!(resource_time(35.9, "GiB"), "35.9 GiB-s"); + assert_eq!(resource_time(36.0, "CPU"), "0.01 CPU-h"); + // A measured run of a 1 GiB sandbox for 2.2 CPU-seconds and 20 seconds. + let usage = json!({"observedMs":20000,"memoryObservedMs":20000, + "cpuNanoseconds":"2210000000","residentByteMilliseconds":"21474836480000"}); + assert_eq!(cpu_time(&usage).as_deref(), Some("2.2 CPU-s")); + assert_eq!(memory_time(&usage).as_deref(), Some("20.0 GiB-s")); + } + #[test] fn usage_list_shows_one_row_per_run_and_the_next_page() { let events = json!({"events":[ From f0a6ed2cbc3249cb0c49f678cb76e01c8125590a Mon Sep 17 00:00:00 2001 From: miqui Date: Thu, 19 Nov 2026 13:49:46 -0500 Subject: [PATCH 3/3] Note list estimates and clarify which sandbox IDs find deleted history 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 --- docs/cli-reference.md | 4 +++- src/cli.rs | 3 ++- src/commands.rs | 47 ++++++++++++++++++++++++++++++++++++++++ tests/usage/mod.rs | 50 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 102 insertions(+), 2 deletions(-) diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 2adf22f..8bebf3e 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -408,11 +408,13 @@ Members see only their own usage. Owners, admins, and API keys see the whole organization and can select one member with `--user`. `usage list` shows records newest first, one row per sandbox run or model call. +For sandbox runs, a note under the table counts intervals in the displayed records that Platform estimated from allocated resources instead of measuring. Use `--kind model` for model calls; the default is `sandbox`. `--days` accepts `7`, `30`, or `90` and counts UTC days, including today. Without `--days`, the list includes all history. Sandbox runs count if they finished in that time or are still running. -`--sandbox` accepts a full UUID or an ID prefix of a sandbox that still exists, and only works with sandbox usage. +`--sandbox` accepts a full UUID or an unambiguous ID prefix, and only works with sandbox usage. +Full UUIDs can filter historical events for deleted sandboxes; only prefixes require a non-deleted sandbox. `usage summary` totals usage per member over the last 30 UTC days, or over `--days`. The table adds a total row. diff --git a/src/cli.rs b/src/cli.rs index e3484ff..be9271b 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -770,7 +770,8 @@ pub struct UsageList { /// Sandbox runs count if they finished in that time or are still running #[arg(long, value_parser = ["7", "30", "90"])] pub days: Option, - /// Show runs of one existing sandbox (full UUID or unambiguous ID prefix) + /// Show runs of one sandbox (full UUID or unambiguous ID prefix). + /// Full UUIDs include deleted-sandbox history; prefixes require a non-deleted sandbox #[arg(long)] pub sandbox: Option, #[command(flatten)] diff --git a/src/commands.rs b/src/commands.rs index 623c635..f92a6dc 100644 --- a/src/commands.rs +++ b/src/commands.rs @@ -595,6 +595,11 @@ fn write_usage_events(out: &mut impl Write, result: &Value) -> io::Result<()> { "memory", ]; output::table(out, &keys, &rows)?; + let estimated: u64 = events + .iter() + .filter_map(|event| event["usage"]["estimatedIntervals"].as_u64()) + .sum(); + estimated_note(out, &json!({"estimatedIntervals": estimated}))?; } output::next_page(out, result) } @@ -1358,6 +1363,48 @@ mod tests { ); } + #[test] + fn usage_list_flags_allocation_estimates_under_the_table() { + let mut events = json!({"events":[ + {"kind":"sandbox","createdAt":"2026-11-18T14:02:11.000Z","sandboxId":ID,"status":"finished", + "usage":{"durationMs":3600000,"cpuNanoseconds":"1834000000000", + "residentByteMilliseconds":"3865470566400000","observedMs":3600000, + "memoryObservedMs":3600000,"estimatedIntervals":0}} + ],"nextCursor":null}); + let measured = written(write_usage_events, events.clone()); + assert_eq!(measured.lines().count(), 2); + for (count, intervals) in [(1, "1 interval"), (3, "3 intervals")] { + events["events"][0]["usage"]["estimatedIntervals"] = json!(count); + assert_eq!( + written(write_usage_events, events.clone()), + format!( + "{measured}\nIncludes {intervals} estimated from allocated resources, not measured.\n" + ) + ); + } + events["events"][0]["usage"] + .as_object_mut() + .unwrap() + .remove("estimatedIntervals"); + assert_eq!(written(write_usage_events, events), measured); + } + + #[test] + fn usage_list_counts_estimates_across_rows_before_the_next_page() { + let events = json!({"events":[ + {"kind":"sandbox","usage":{"estimatedIntervals":0}}, + {"kind":"sandbox","usage":{"estimatedIntervals":3}}, + {"kind":"sandbox","usage":{}}, + {"kind":"sandbox","usage":{"estimatedIntervals":1}} + ],"nextCursor":ID}); + let out = written(write_usage_events, events); + assert_eq!(out.matches("estimated from allocated resources").count(), 1); + assert!(out.ends_with(&format!( + "\nIncludes 4 intervals estimated from allocated resources, not measured.\n\ + \nNext page: rerun with --cursor {ID} (or use --all)\n" + ))); + } + #[test] fn usage_list_shows_model_tokens_and_empty_results() { let events = json!({"events":[ diff --git a/tests/usage/mod.rs b/tests/usage/mod.rs index 8dfb43c..7d28092 100644 --- a/tests/usage/mod.rs +++ b/tests/usage/mod.rs @@ -4,6 +4,22 @@ use serde_json::json; // Platform enforces permissions and applies the filters (see the platform API's usage routes). // These tests verify that the CLI sends the filters unchanged and passes JSON through. +#[test] +fn list_help_distinguishes_full_sandbox_uuids_from_prefixes() { + let dir = tempfile::tempdir().unwrap(); + for flag in ["-h", "--help"] { + let output = run(dir.path(), "http://localhost:1", &["usage", "list", flag]); + assert!(output.status.success()); + let help = String::from_utf8_lossy(&output.stdout) + .split_whitespace() + .collect::>() + .join(" "); + assert!(help.contains("Full UUIDs include deleted-sandbox history")); + assert!(help.contains("prefixes require a non-deleted sandbox")); + assert!(!help.contains("one existing sandbox")); + } +} + #[test] fn list_forwards_filters() { let events = json!({"events":[{"id":ID,"kind":"sandbox"}],"asOf":"2026-11-19T16:20:00.000Z","nextCursor":null}); @@ -20,6 +36,12 @@ fn list_forwards_filters() { None, events.clone(), ), + step( + "GET", + format!("/v1/usage?limit=50&kind=sandbox&sandboxId={ID}"), + None, + events.clone(), + ), step( "GET", "/v1/usage?limit=50&kind=model&days=90".into(), @@ -40,6 +62,7 @@ fn list_forwards_filters() { "--sandbox", "1111ABCD", ], + vec!["usage", "list", "--sandbox", ID], vec!["usage", "list", "--kind", "model", "--days", "90", "--json"], ] { assert_eq!(success(&run(dir.path(), &server.url, &args)), events); @@ -47,6 +70,33 @@ fn list_forwards_filters() { server.finish(); } +#[test] +fn list_passes_allocation_estimates_through_as_json_without_notes() { + let events = json!({"events":[{"id":ID,"kind":"sandbox","usage":{ + "cpuNanoseconds":"1834000000000","residentByteMilliseconds":"3865470566400000", + "observedMs":3600000,"memoryObservedMs":3600000,"estimatedIntervals":3 + }}],"nextCursor":null}); + let server = Server::start( + (0..2) + .map(|_| { + step( + "GET", + "/v1/usage?limit=50&kind=sandbox".into(), + None, + events.clone(), + ) + }) + .collect(), + ); + let dir = tempfile::tempdir().unwrap(); + for args in [vec!["usage", "list"], vec!["usage", "list", "--json"]] { + let output = run(dir.path(), &server.url, &args); + assert_eq!(success(&output), events); + assert!(output.stderr.is_empty()); + } + server.finish(); +} + #[test] fn summary_defaults_to_30_days_and_forwards_filters() { let summary = json!({"kind":"sandbox","members":[],"totals":{"runs":0}});