diff --git a/AGENTS.md b/AGENTS.md index 7108559..f05f320 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,7 +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. +- **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. `REPORT_*_KEYS` in `report_render.rs` are the single source, and each binary's `report_json_envelopes_are_the_shared_contract` test asserts its own emitter against them — dropping a key from either side fails all three tests (verified by mutation on 2026-11-13). - **`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/cmduse/src/arkuse/render.rs b/cmduse/src/arkuse/render.rs index 7956324..1a4791e 100644 --- a/cmduse/src/arkuse/render.rs +++ b/cmduse/src/arkuse/render.rs @@ -1971,4 +1971,58 @@ mod tests { parsed["monthly"]["cacheRead"] ); } + + #[test] + fn report_json_envelopes_are_the_shared_contract() { + // Same constants cmduse and ocuse assert: one envelope per report. + use crate::report_render::{ + REPORT_DAILY_KEYS, REPORT_HOURLY_KEYS, REPORT_MODEL_KEYS, REPORT_SESSION_KEYS, + }; + let keys = |body: String| -> Vec { + let v: serde_json::Value = serde_json::from_str(&body).unwrap(); + v.as_object().unwrap().keys().cloned().collect() + }; + let now = 1_800_000_000_000; + let day = 86_400_000; + assert_eq!( + keys(bucket_text( + &[], + &crate::arkuse::ark::catalog(), + now, + 2 * day, + day, + 0, + false, + Fmt::Json + )), + REPORT_DAILY_KEYS.to_vec() + ); + assert_eq!( + keys(bucket_text( + &[], + &crate::arkuse::ark::catalog(), + now, + 2 * 3_600_000, + 3_600_000, + 0, + false, + Fmt::Json + )), + REPORT_HOURLY_KEYS.to_vec() + ); + assert_eq!( + keys(model_report(&report(), None, Fmt::Json)), + REPORT_MODEL_KEYS.to_vec() + ); + assert_eq!( + keys(session_text( + &[], + &crate::arkuse::ark::catalog(), + 5, + false, + Fmt::Json + )), + REPORT_SESSION_KEYS.to_vec() + ); + } } diff --git a/cmduse/src/ocuse/render.rs b/cmduse/src/ocuse/render.rs index 8a2f224..6dcbbe6 100644 --- a/cmduse/src/ocuse/render.rs +++ b/cmduse/src/ocuse/render.rs @@ -2504,4 +2504,42 @@ mod tests { assert!(!compact_line(&report(), &[], false).contains('\x1b')); assert!(compact_line(&report(), &[], true).contains(crate::render::BOLD)); } + + #[test] + fn report_json_envelopes_are_the_shared_contract() { + // Same constants cmduse asserts: one envelope per report on all three. + use crate::report_render::{ + REPORT_DAILY_KEYS, REPORT_HOURLY_KEYS, REPORT_MODEL_KEYS, REPORT_SESSION_KEYS, + }; + let keys = |body: String| -> Vec { + let v: serde_json::Value = serde_json::from_str(&body).unwrap(); + v.as_object().unwrap().keys().cloned().collect() + }; + let now = 1_800_000_000_000; + let day = 86_400_000; + assert_eq!( + keys(bucket_text(&[], now, 2 * day, day, 0, false, Fmt::Json)), + REPORT_DAILY_KEYS.to_vec() + ); + assert_eq!( + keys(bucket_text( + &[], + now, + 2 * 3_600_000, + 3_600_000, + 0, + false, + Fmt::Json + )), + REPORT_HOURLY_KEYS.to_vec() + ); + assert_eq!( + keys(model_report(&report(), None, Fmt::Json)), + REPORT_MODEL_KEYS.to_vec() + ); + assert_eq!( + keys(session_text(&[], 5, false, Fmt::Json)), + REPORT_SESSION_KEYS.to_vec() + ); + } } diff --git a/cmduse/src/render_tests.rs b/cmduse/src/render_tests.rs index beee6fe..a232f90 100644 --- a/cmduse/src/render_tests.rs +++ b/cmduse/src/render_tests.rs @@ -544,3 +544,55 @@ fn update_box_borders_align_and_wraps() { assert_eq!(colored.lines().count(), 3, "{colored}"); assert!(colored.contains("\x1b[33m") && colored.contains("update available")); } + +#[test] +fn report_json_envelopes_are_the_shared_contract() { + // Parity is enforced, not eyeballed: the three binaries emit one envelope per + // report, and each asserts its own emitter against the core constants. + use crate::report_render::{hourly_table, model_table, project_table, table, Fmt}; + use crate::report_render::{ + REPORT_DAILY_KEYS, REPORT_HOURLY_KEYS, REPORT_MODEL_KEYS, REPORT_SESSION_KEYS, + }; + use crate::reports::{ByDay, ByModel, ByProject, Totals}; + + let keys = |body: String| -> Vec { + let v: serde_json::Value = serde_json::from_str(&body).unwrap(); + v.as_object().unwrap().keys().cloned().collect() + }; + + let empty_day = ByDay::new(); + let empty_model = ByModel::new(); + let empty_project = ByProject::new(); + let total = Totals::default(); + + assert_eq!( + keys(table( + "local", + "", + &empty_day, + &total, + None, + Fmt::Json, + false + )), + REPORT_DAILY_KEYS.to_vec() + ); + assert_eq!( + keys(hourly_table(&[], Fmt::Json, "local", false)), + REPORT_HOURLY_KEYS.to_vec() + ); + assert_eq!( + keys(model_table( + &empty_model, + Fmt::Json, + false, + None, + usize::MAX + )), + REPORT_MODEL_KEYS.to_vec() + ); + assert_eq!( + keys(project_table(&empty_project, Fmt::Json, false, usize::MAX)), + REPORT_SESSION_KEYS.to_vec() + ); +} diff --git a/cmduse/src/report_render.rs b/cmduse/src/report_render.rs index f4ab266..c92afc2 100644 --- a/cmduse/src/report_render.rs +++ b/cmduse/src/report_render.rs @@ -1,5 +1,21 @@ use crate::render::{color_for, compact, money, BOLD, CYAN, DIM, RESET}; +/// JSON envelope keys for the four report commands. All three binaries live in +/// this crate and each asserts its own emitter against these in a unit test, so +/// the envelopes cannot drift apart the way they did on 2026-11-13 (`cmduse` said +/// `projects` where the others said `sessions`, and had no `source` on `daily`). +/// Sorted, so a test can compare directly against a map's key order. +/// Test-only on purpose: production code must not read the contract back and +/// assert itself, or a wrong emitter would agree with a wrong constant. +#[cfg(test)] +pub const REPORT_DAILY_KEYS: [&str; 4] = ["days", "scope", "source", "total"]; +#[cfg(test)] +pub const REPORT_HOURLY_KEYS: [&str; 4] = ["hours", "scope", "source", "total"]; +#[cfg(test)] +pub const REPORT_MODEL_KEYS: [&str; 5] = ["models", "scope", "since", "sinceMs", "source"]; +#[cfg(test)] +pub const REPORT_SESSION_KEYS: [&str; 4] = ["projects", "scope", "sessions", "source"]; + /// Output format for the report tables. JSON and CSV are machine-readable /// (never colored); `Table` honors the caller's color decision. #[derive(Clone, Copy, PartialEq, Eq, Debug)]