diff --git a/AGENTS.md b/AGENTS.md index be0468c..7108559 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,6 +70,7 @@ opencode-plugin/ @jeffreyjyz/opencode-command-code (dual opencode v1 (server() - **`ocuse` + `arkuse` stay at feature parity with `cmduse`, same pace, ALWAYS** — any user-facing thing one gains (subcommand, flag, `--json`/`--csv`, config key, update check, notify, statusline, validation) lands in all three in the same commit; a capability only one has is a **defect, not a backlog item**. Only what the _source_ forces may differ: `--local` (cmduse's account-vs-logs daily), `--db`/`--no-api`/`--window`/`--period-start`/`--infer-anniversary` (a local store has cuts to choose, an account API hands them back), `--plan` (ocuse's Go plan / arkuse's tier, which their sources cannot report), `--profile` (arkcli). Everything else is shared, including `--rows` (`0` = all; table-only — `--json`/`--csv` always carry every row, and a trimmed table ends `… N more`) and the 5s default refresh (`config default_for`; per-binary intervals were drift). - **MCP parity is pinned on both axes.** `cmduse mcp` + `ocuse mcp` + `arkuse mcp` expose the same seven tools — `usage`, `plans`, `models`, `daily`, `hourly`, `session`, `model` — with the same arguments per tool, asserted by a sorted-set test in each binary through the shared `mcp_tests::tool_params`. `models` takes `gated`; `daily`/`hourly` take `tz`; `session`/`model` take `since`/`days`/`rows`, plus `tz` on cmduse (its local store needs an offset; ocuse/arkuse rows already carry one); `model` also takes `id` (absent = the table). `rows` is the canonical cap (`limit` stays an alias on ocuse/arkuse), and no cap means every row. - **The machine-readable surfaces use one set of names where the concept is the same**, so a consumer never branches per binary: every `-1 --json` carries `source`, the period bounds (`periodStart`/`periodStartAt`/`periodEndAt` as epoch ms, plus the display date `periodEnd`) and a `summary` of the period (`ocuse`'s is an alias of `totals.month` — the same object, so the keys cannot disagree). `statusline --json` uses `fiveHourSpent`/`fiveHourCap`, `weeklySpent`/`weeklyCap`, `monthSpent`/`monthCap` on all three; `cmduse`'s month is a credit pool, so its spent half is `cap − remaining` clamped at zero, and its older `fiveHourUsed`/`weeklyUsed`/`monthlyRemaining` remain as aliases. `plans --json` stays two shapes on purpose — `cmduse` prints a subscription array (mpc consumes it), `ocuse`/`arkuse` print a model catalogue object. **Reports sort by spend, biggest first, name as tiebreak** (`by_spend`), never `BTreeMap` order. Calendar formatting is `cmduse_core::dates::civil_from_days` everywhere. +- **The four report envelopes carry the same keys on all three binaries** — `daily`/`hourly` emit `{scope, source, total, days|hours}`, `model` emits `{scope, source, since, sinceMs, models}`, `session` carries **both** `sessions` and `projects` with identical rows (cmduse spelled it `projects` first); `source` names where the rows came from (`command-code`, `opencode`, or `local`), so a consumer never branches on binary. - **`ocuse` measures OpenCode Go/Zen spend from `opencode.db`** (providers `opencode-go` + `opencode`; `command-code-openai` is a different plan and excluded by design), prices each turn itself from the documented peak/off-peak sheet (`reasoning` at the output rate), and takes limits/rates from `core/zen.json`. It reads the `pi` and `dsh` session logs too (`src/stores.rs`: plain JSONL for pi, zstd for dsh, `PI_SESSIONS_DIR`/`DSH_SESSIONS_DIR` override), keeping only rows on those same providers, because both harnesses spend the same allowance — the header and `--json`'s `clients` name every source read. Which Go plan is active is **not discoverable**, so `--plan ` is told, default `go`. - **`arkuse` measures a Volcengine ARK Agent Plan in AFP, never dollars.** `1 AFP = ¥0.002`, `AFP = (input + cache_read + output) × coef / 10,000` (cache-read counts; `reasoning` is already inside `output`, so never add it again). Two sources: `arkcli usage plan --profile ` (the plan's own 5h/daily/weekly/monthly meters — the only view of every machine and harness) and the local stores filtered to provider `agent-plan` — `opencode.db` plus the `pi`/`dsh` logs through the same `src/stores.rs` reader (per-model attribution + a local estimate). The meter wins and the local AFP prints beside it labelled `local`; with no answer the rows fall back to the published split (10/50/35/100 % of monthly AFP) labelled `(est.)` with the reason. Server windows are not reproducible — 5h is a block, the week is Monday 00:00, the month is the subscription anniversary — so cut at `reset − window` and print in the server offset, never `now − window`. A text-only workload has no daily window. `--plan` = tier, `--profile` = arkcli profile, `--no-api` skips arkcli. Notify fires per **window** (ARK limits the plan, not a model). `arkcli` prints its error envelope on stderr — parse the message, not the first `{`. - **`cmduse`'s local reports read `pi` and `dsh` too** — `model`, `session`, `daily --local` and `hourly --local` append their turns on a `command-code*` provider (`CC_PROVIDERS` in `reports.rs`), carrying the client's own `costUsd` rather than re-pricing; all three binaries share `src/stores.rs` and apply their own provider filter. diff --git a/Cargo.lock b/Cargo.lock index 961e9aa..2cbcf22 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -46,7 +46,7 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" [[package]] name = "cmd-usage" -version = "0.7.32" +version = "0.7.33" dependencies = [ "cmduse-core", "lexopt", diff --git a/cmduse/Cargo.toml b/cmduse/Cargo.toml index 211f1bc..a341539 100644 --- a/cmduse/Cargo.toml +++ b/cmduse/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "cmd-usage" -version = "0.7.32" +version = "0.7.33" edition = "2021" # Two bins (`cmduse` + the `cmdusedev` twin), so `cargo run -p cmd-usage` needs # an explicit default: CI's `-V` smoke test, and humans typing it. diff --git a/cmduse/src/arkuse/render.rs b/cmduse/src/arkuse/render.rs index 37d5763..7956324 100644 --- a/cmduse/src/arkuse/render.rs +++ b/cmduse/src/arkuse/render.rs @@ -1314,7 +1314,10 @@ pub fn model_report(report: &Report, id: Option<&str>, fmt: Fmt) -> String { serde_json::json!({ "scope": "local", "source": "opencode", + // `sinceMs` is native here; `since` is the ISO spelling cmduse and + // mpc use, so one name serves both readers. "sinceMs": report.since_ms, + "since": cmduse_core::dates::iso_instant((report.since_ms.max(0) / 1000) as u64), "models": map, }) .to_string() @@ -1599,7 +1602,10 @@ pub fn session_text( serde_json::json!({ "scope": "local", "source": "opencode", - "sessions": keyed, + "sessions": keyed.clone(), + // cmduse spells this collection `projects`; both names carry the same + // rows so a consumer reads either without branching. + "projects": keyed, }) .to_string() } diff --git a/cmduse/src/ocuse/render.rs b/cmduse/src/ocuse/render.rs index bdc33dd..8a2f224 100644 --- a/cmduse/src/ocuse/render.rs +++ b/cmduse/src/ocuse/render.rs @@ -1228,7 +1228,10 @@ pub fn model_report(report: &Report, id: Option<&str>, fmt: Fmt) -> String { serde_json::json!({ "scope": "local", "source": "opencode", + // `sinceMs` is this binary's native form; `since` is the ISO spelling + // cmduse and mpc use, so one name serves both readers. "sinceMs": report.since_ms, + "since": cmduse_core::dates::iso_instant((report.since_ms.max(0) / 1000) as u64), "models": map, }) .to_string() @@ -1412,7 +1415,10 @@ pub fn session_text( serde_json::json!({ "scope": "local", "source": "opencode", - "sessions": keyed, + "sessions": keyed.clone(), + // cmduse has always spelled this collection `projects`; both names + // carry the same rows so a consumer reads either. + "projects": keyed, }) .to_string() } diff --git a/cmduse/src/report_render.rs b/cmduse/src/report_render.rs index b6f29cd..f4ab266 100644 --- a/cmduse/src/report_render.rs +++ b/cmduse/src/report_render.rs @@ -207,6 +207,9 @@ pub fn table( match fmt { Fmt::Json => serde_json::json!({ "scope": scope, + // Same key every binary carries, so a consumer never branches on + // which binary produced the report: the account API or this machine. + "source": if scope == "account" { "command-code" } else { "local" }, "total": totals_json(total), "days": totals_map(by_day.iter()), }) @@ -268,12 +271,21 @@ pub fn hourly_table( colors: bool, ) -> String { match fmt { - Fmt::Json => serde_json::json!({ - "scope": "hourly", - "source": source.replace(' ', "-"), - "hours": totals_map(rows.iter().map(|(h, t)| (h, t))), - }) - .to_string(), + Fmt::Json => { + // Same envelope as the day table and as ocuse/arkuse: `total` sums the + // buckets, so a consumer reads one shape on every binary. + let mut total = crate::reports::Totals::default(); + for (_, t) in rows { + total.merge(t); + } + serde_json::json!({ + "scope": "hourly", + "source": source.replace(' ', "-"), + "total": totals_json(&total), + "hours": totals_map(rows.iter().map(|(h, t)| (h, t))), + }) + .to_string() + } Fmt::Csv => { let mut o = String::from("hour,requests,tokens_in,tokens_out,cost_usd\n"); for (h, t) in rows { @@ -338,7 +350,18 @@ pub fn project_table( rows: usize, ) -> String { match fmt { - Fmt::Json => serde_json::json!({ "projects": totals_map(by_project.iter()) }).to_string(), + Fmt::Json => { + // `sessions` is the shared key (ocuse/arkuse emit it); `projects` stays + // as the alias this binary has always written. + let rows = totals_map(by_project.iter()); + serde_json::json!({ + "scope": "local", + "source": "local", + "sessions": rows.clone(), + "projects": rows, + }) + .to_string() + } Fmt::Csv => { let mut o = String::from("project,requests,tokens,cost_usd\n"); for (p, t) in by_spend(by_project) { @@ -387,7 +410,11 @@ pub fn model_table( match fmt { Fmt::Json => serde_json::json!({ "source": "local", + "scope": "local", "since": since, + // Epoch ms beside the ISO string: ocuse/arkuse carry `sinceMs` only, and + // one name per concept is the parity rule. `since` stays for mpc. + "sinceMs": since.and_then(cmduse_core::dates::parse_iso_utc), "models": totals_map(by_model.iter()), }) .to_string(),