Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <go|go-plus>` 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 <name>` (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.
Expand Down
54 changes: 54 additions & 0 deletions cmduse/src/arkuse/render.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> {
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()
);
}
}
38 changes: 38 additions & 0 deletions cmduse/src/ocuse/render.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> {
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()
);
}
}
52 changes: 52 additions & 0 deletions cmduse/src/render_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> {
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()
);
}
16 changes: 16 additions & 0 deletions cmduse/src/report_render.rs
Original file line number Diff line number Diff line change
@@ -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)]
Expand Down
Loading