[WRONG BRANCH] Add ocx usage compare for previous-window usage totals

docs-site/src/content/docs/reference/cli/agents.md

@@ -416,6 +416,7 @@ Inspect proxy requests, usage, storage, memory, and debug data. The direct alias
 | --- | --- |
 | `ocx logs [filters] [--follow] [--json|--jsonl|--events]` | `ocx observe logs` |
 | `ocx usage [--range <today|1d|7d|30d|all>] [--since <timestamp> --until <timestamp>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--json]` | `ocx observe usage` |
+| `ocx usage compare [--range <today|1d|7d|30d>] [--json]` | `ocx observe usage compare` |
 | `ocx storage [--json]` | `ocx observe storage` |
 | `ocx memory [--json]` | `ocx observe memory` |
 
@@ -450,6 +451,23 @@ Any displayed totals reflect readable records only. If a filter has no readable
 the warning and guidance instead of total lines; skipped records may contain matches.
 `--json` preserves the response-level `usageIncomplete` diagnostic and reason.
 
+### Compare a range with the previous equal window
+
+```bash
+ocx usage compare --range today --json
+ocx usage compare --range 7d --provider xai
+```
+
+`ocx observe usage compare` is the equivalent family form. The command reads `GET /api/usage`
+twice: the named range ending now, then the same range evaluated one equal window earlier
+(one local day for `today`/`1d`, seven for `7d`, thirty for `30d`). Default range is `30d`.
+`--range all` is refused because open history has no previous equal window. `--since` and
+`--until` are not accepted; the windows are derived. Surface, provider, model, and API-key
+filters apply to both reads. Human output prints current, previous, signed delta, and percent
+change. `--json` is `{schemaVersion,range,current,previous,delta,change,incomplete}`. The two
+reads are sequential, not an atomic snapshot. Custom `since`/`until` on each response must
+match the requested window.
+
 ### Filter a bounded log snapshot
 
 ```bash

scripts/test-layout/layout.json

@@ -22,7 +22,7 @@
     "management-sidecar-anthropic-instance.test.ts": "server", "anthropic2-usage-attribution.test.ts": "usage", "vision-anthropic-instance-sidecar.test.ts": "vision", "web-search-anthropic-instance.test.ts": "web-search",
     "provider-anthropic-instance.test.ts": "providers", "config-anthropic-instance-pool.test.ts": "config", "oauth-anthropic-instance-registration.test.ts": "oauth", "oauth-anthropic-instance-refresh.test.ts": "oauth",
     "claude-picker-upload.test.ts": "claude-integration", "claude-picker-linger.test.ts": "claude-integration", "messages-native-scope.test.ts": "claude-integration", "catalog-auto-review-row.test.ts": "codex-integration",
-    "cli-log-view-filter.test.ts": "cli", "cli-usage-model-search.test.ts": "cli", "cli-companion-usage.test.ts": "cli", "cli-account-key-quota.test.ts": "cli",
+    "cli-log-view-filter.test.ts": "cli", "cli-usage-compare.test.ts": "cli", "cli-usage-model-search.test.ts": "cli", "cli-companion-usage.test.ts": "cli", "cli-account-key-quota.test.ts": "cli",
     "cli-observe-snapshot.test.ts": "cli", "cli-access-data-plane.test.ts": "cli", "cli-access-key-guard.test.ts": "cli", "cli-access-rename.test.ts": "cli",
     "cli-access-audio.test.ts": "cli", "cli-access-audio-live.test.ts": "cli", "cli-log-follow.test.ts": "cli", "cli-injection-follow.test.ts": "cli",
     "cli-usage-scope.test.ts": "cli", "cli-system-health.test.ts": "cli", "cli-companion-timeline.test.ts": "cli", "server-cli-key-probe-admission.test.ts": "server",

skills/ocx/references/01_management_surface.md

@@ -30,7 +30,7 @@ These answer in the CLI head and never reach the proxy, so they work with nothin
 | [accounts](01_surface_accounts.md) | 40 |
 | [agents-routing](01_surface_agents-routing.md) | 51 |
 | [integrations](01_surface_integrations.md) | 41 |
-| [observe-system](01_surface_observe-system.md) | 92 |
+| [observe-system](01_surface_observe-system.md) | 93 |
 | [access-remote](01_surface_access-remote.md) | 32 |
 | [lab](01_surface_lab.md) | 21 |
 
@@ -939,6 +939,10 @@ Original invocation order. These headings preserve links to the previous single-
 
 [Read-oriented task](01_surface_observe-system.md#ocx-observe-usage)
 
+### `ocx usage compare`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-usage-compare)
+
 ### `ocx observe storage`
 
 [Read-oriented task](01_surface_observe-system.md#ocx-observe-storage)
@@ -1393,6 +1397,6 @@ Original invocation order. These headings preserve links to the previous single-
 
 ## Counts
 
-- declared capabilities: 336
+- declared capabilities: 337
 - of those, state-changing: 205
 - head-resolved invocations: 2

skills/ocx/references/01_surface_observe-system.md

@@ -8,7 +8,7 @@
 Use these declarations to choose a task, then check its flags and authority before execution.
 Non-mutating probes may still contact providers, consume quota or refresh caches.
 
-Declared capabilities: 92.
+Declared capabilities: 93.
 
 ### `ocx companion`
 
@@ -62,6 +62,7 @@ JSON mode: `payload`.
 - Alias of observe usage. Connected clients read only their enrolled-key Hub report through /v1/usage; caller --api-key-id is refused before key read/transport and never grants management authority.
 - Nonclient --api-key-id uses /api/usage and requires matching filter acknowledgment. An unknown acknowledged key is empty/matched:false, not404. Custom-window acknowledgment remains required.
 - --search filters only returned model rows after scope acknowledgment. Blank search selects the top100 model rows; modelView reports match/return counts without recomputing totals.
+- Nested compare reads the named range and the previous equal window; --range all is refused.
 
 ### `ocx logs`
 
@@ -654,6 +655,32 @@ JSON mode: `payload`.
 - Nonclient --api-key-id uses /api/usage and requires matching filter acknowledgment. An unknown acknowledged key is empty/matched:false, not404. Custom-window acknowledgment remains required.
 - --search filters only returned model rows after scope acknowledgment. Blank search selects the top100 model rows; modelView reports match/return counts without recomputing totals.
 
+### `ocx usage compare`
+
+Usage: `ocx usage compare [--range <today|1d|7d|30d>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--json]`
+
+Compare a usage range with the previous equal window.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/usage` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--range` | string | today \| 1d \| 7d \| 30d; default 30d. all is refused. |
+| `--surface` | string | all \| codex \| claude \| grok; default all. |
+| `--provider` | string | Filter provider. |
+| `--model` | string | Filter model. |
+| `--api-key-id` | string | Exact nonblank management key scope; connected clients refuse this. |
+| `--json` | boolean | Emit current, previous, delta and change percentages. |
+
+JSON mode: `envelope`.
+
+- Two sequential GET /api/usage reads: the named range at now, then the same range shifted back one equal window. Custom since/until must be acknowledged on both. --range all is refused.
+- Also accepted after observe usage. Default range is 30d. This is not an atomic snapshot.
+
 ### `ocx observe storage`
 
 Usage: `ocx observe storage [--limit <n>] [--json]`

skills/ocx/references/02_json_shapes.md

@@ -86,6 +86,13 @@ Two honesty markers to respect:
 - Under `--provider` or `--model`, per-account rows are **withheld** rather than filtered, because
   account totals cannot be honestly re-partitioned by provider.
 
+## `ocx usage compare --json`
+
+CLI envelope `schemaVersion: 1` with `range`, `days`, `filter`, then `current` and `previous`
+(`since`, `until`, `summary`, `usageIncomplete`), plus `delta`, `change` (percent, or `null` when
+the previous value is zero and the current value is not), and `incomplete`. Totals are request,
+token and estimated-cost fields only; use `ocx usage --json` for provider/model/account rows.
+
 ## `ocx account list <provider> --json`
 
 `accounts[]` with `id`, `email`, `plan`, `paused`, `selected`, `priority`, and `needsReauth`. Quota

skills/ocx/references/03_recipes.md

@@ -88,8 +88,12 @@ actually served it, not only the one requested.
 
 ```bash
 ocx usage --range 7d --json
+ocx usage compare --range 7d --json
 ```
 
+`ocx usage compare` reads the named range and the previous equal window. `--range all` is refused.
+`--json` carries `delta` and `change` (percent). The two reads are sequential.
+
 Read `accounts[]`. Two things to respect:
 
 - A row with `ambiguous: true` (label `legacy-ambiguous`) aggregates several accounts from before

src/cli/capabilities-base.ts

@@ -326,7 +326,7 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [{"name":"--range","value":"string","summary":"today | 1d | 7d | 30d | all; default 30d."},{"name":"--surface","value":"string","summary":"all | codex | claude | grok; default all."},{"name":"--since","value":"string","summary":"Inclusive epoch milliseconds or ISO datetime with timezone; requires --until."},{"name":"--until","value":"string","summary":"Inclusive end; requires --since. Custom bounds override --range."},{"name":"--provider","value":"string","summary":"Filter provider."},{"name":"--model","value":"string","summary":"Filter model."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."},{"name":"--api-key-id","value":"string","summary":"Exact nonblank management key scope; connected clients refuse this before reading their enrolled key."},{"name":"--search","value":"string","summary":"Model-row substring view over model/provider/resolvedModel; top100 by tokens. Whole-report totals stay unchanged."}],
     mutates: false,
     json: "payload",
-    details: ["Alias of observe usage. Connected clients read only their enrolled-key Hub report through /v1/usage; caller --api-key-id is refused before key read/transport and never grants management authority.","Nonclient --api-key-id uses /api/usage and requires matching filter acknowledgment. An unknown acknowledged key is empty/matched:false, not404. Custom-window acknowledgment remains required.","--search filters only returned model rows after scope acknowledgment. Blank search selects the top100 model rows; modelView reports match/return counts without recomputing totals."],
+    details: ["Alias of observe usage. Connected clients read only their enrolled-key Hub report through /v1/usage; caller --api-key-id is refused before key read/transport and never grants management authority.","Nonclient --api-key-id uses /api/usage and requires matching filter acknowledgment. An unknown acknowledged key is empty/matched:false, not404. Custom-window acknowledgment remains required.","--search filters only returned model rows after scope acknowledgment. Blank search selects the top100 model rows; modelView reports match/return counts without recomputing totals.","Nested compare reads the named range and the previous equal window; --range all is refused."],
     usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--since <epoch-ms|ISO-datetime>] [--until <epoch-ms|ISO-datetime>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--json]",
   },
   {

src/cli/capabilities-observe-system.ts

@@ -50,6 +50,25 @@ export const OBSERVE_SYSTEM_CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: ["Also available as ocx usage. Connected clients read only their enrolled-key Hub report through /v1/usage; caller --api-key-id is refused before key read/transport and never grants management authority.","Nonclient --api-key-id uses /api/usage and requires matching filter acknowledgment. An unknown acknowledged key is empty/matched:false, not404. Custom-window acknowledgment remains required.","--search filters only returned model rows after scope acknowledgment. Blank search selects the top100 model rows; modelView reports match/return counts without recomputing totals."],
   },
+  {
+    command: ["usage", "compare"],
+    summary: "Compare a usage range with the previous equal window.",
+    usage: "ocx usage compare [--range <today|1d|7d|30d>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--json]",
+    routes: [{"method": "GET", "path": "/api/usage"}],
+    flags: [
+      {"name": "--range", "value": "string", "summary": "today | 1d | 7d | 30d; default 30d. all is refused."},
+      {"name": "--surface", "value": "string", "summary": "all | codex | claude | grok; default all."},
+      {"name": "--provider", "value": "string", "summary": "Filter provider."},
+      {"name": "--model", "value": "string", "summary": "Filter model."},
+      {"name": "--api-key-id", "value": "string", "summary": "Exact nonblank management key scope; connected clients refuse this."},
+      {"name": "--json", "value": "boolean", "summary": "Emit current, previous, delta and change percentages."},
+    ],
+    mutates: false, json: "envelope",
+    details: [
+      "Two sequential GET /api/usage reads: the named range at now, then the same range shifted back one equal window. Custom since/until must be acknowledged on both. --range all is refused.",
+      "Also accepted after observe usage. Default range is 30d. This is not an atomic snapshot.",
+    ],
+  },
   {
     command: ["observe", "storage"], summary: "Read storage diagnostics.",
     usage: "ocx observe storage [--limit <n>] [--json]",

src/cli/observe-stream.ts

@@ -14,6 +14,8 @@ export interface ObserveStreamDeps extends RuntimeApiDeps {
   /** Reduced timings for isolated tests only; never command-line options. */
   pollIntervalMs?: number;
   requestTimeoutMs?: number;
+  /** Frozen clock for usage-compare tests; never a command-line option. */
+  now?: () => number;
 }
 
 export class ObservationError extends Error {}

src/cli/observe.ts

@@ -17,6 +17,7 @@ import { handleLogFilterCommand } from "./log-view-filter";
 import { followInjection } from "./injection-follow";
 import type { ObserveStreamDeps } from "./observe-stream";
 import { formatUsageReport } from "./usage-report";
+import { handleUsageCompareCommand } from "./usage-compare";
 import { selectUsageModelView, takeUsageSearchOption } from "./usage-model-search";
 import { USAGE_RANGES, USAGE_SURFACES, type UsageSummary, type UsageFilterEcho } from "../usage/summary";
 import { parseUsageTimeWindow, type UsageTimeWindow } from "../usage/time-range";
@@ -36,6 +37,8 @@ const USAGE = `Usage:
   ocx observe usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>]
       [--since <epoch-ms|ISO-datetime>] [--until <epoch-ms|ISO-datetime>]
       [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--json]
+  ocx usage compare [--range <today|1d|7d|30d>] [--surface <all|codex|claude|grok>]
+      [--provider <name>] [--model <id>] [--api-key-id <id>] [--json]
   ocx observe storage [codex-logs [status|protect|unprotect|repair|compact] [--mode <compat|quiet>]] [--json]
   ocx observe memory [--json]
   ocx observe debug [--json]
@@ -325,7 +328,10 @@ export async function handleObserveCommand(argv: string[], deps: ObserveStreamDe
       else if (action === "index-status") await indexStatus(rest.slice(1), deps);
       else streamExit = await logs(rest, deps);
     }
-    else if (sub === "usage") await usage(rest, deps);
+    else if (sub === "usage") {
+      if (rest[0] === "compare") await handleUsageCompareCommand(rest.slice(1), deps);
+      else await usage(rest, deps);
+    }
     else if (sub === "storage") await storage(rest, deps);
     else if (sub === "memory") await simple("/api/system/memory", rest, deps);
     else if (sub === "debug") await simple("/api/debug", rest, deps);

src/cli/registry.ts

@@ -447,8 +447,11 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl|--events]", summary: "Read or follow request logs." },
   {
     name: "usage",
-    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--json]",
+    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--json]; ocx usage compare [--range <today|1d|7d|30d>] [--json]",
     summary: "Report token usage and estimated cost (alias of ocx observe usage).",
+    details: [
+      "`compare` reads the current named range and the previous equal window; `--range all` is refused.",
+    ],
   },
   {
     name: "storage",