usagemax 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UsageMax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# UsageMax CLI
+
+Connect aggregate coding-agent usage from your computer to a private UsageMax workspace.
+
+## Quick start
+
+1. Sign in at [usagemax.com/account](https://usagemax.com/account).
+2. Choose **Link a computer** and copy the one-time command.
+3. Run it locally:
+
+```bash
+bunx usagemax link UMX-XXXX-XXXX-XXXX-XXXX
+```
+
+The link code expires after ten minutes and can be used once. The CLI stores the resulting collector key in a user-only config file, then runs a one-shot sync.
+
+## Commands
+
+```bash
+bunx usagemax              # sync changed usage
+bunx usagemax sync         # same as above
+bunx usagemax sync --full  # inspect all available local history
+bunx usagemax link UMX-… --no-sync # link without uploading yet
+bunx usagemax status       # show link and last-sync state
+bunx usagemax doctor       # metadata-only source check; does not parse logs
+bunx usagemax doctor --deep # opt into a full local parser check
+bunx usagemax report       # open ccusage's local daily report
+bunx usagemax report session --breakdown
+bunx usagemax unlink       # remove the local collector key
+```
+
+UsageMax uses [ccusage](https://github.com/ccusage/ccusage) for local source detection, responsive reports, cached pricing, model breakdowns, date handling, and support for popular coding-agent CLIs. `report` passes its remaining arguments to ccusage.
+
+## Privacy and load
+
+- The sync payload contains aggregate token counts, model/provider names, costs, source names, and dates.
+- It does not upload prompts, completions, source code, file contents, project paths, or provider credentials.
+- Sync is one-shot. There is no resident scanner or high-frequency polling loop.
+- After the first import, normal syncs inspect only the current and previous local day; use `sync --full` to reconcile older history.
+- The collector key is written with user-only permissions where the operating system supports them.
+
+Use `USAGEMAX_CONFIG_DIR` to select another config directory. Development/self-hosted installations may set `USAGEMAX_LINK_ENDPOINT` before linking.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "usagemax",
+  "version": "0.1.0",
+  "description": "Link local coding-agent usage to your UsageMax profile",
+  "license": "MIT",
+  "author": "UsageMax",
+  "homepage": "https://usagemax.com",
+  "bugs": {
+    "url": "https://github.com/SYMBaiEX/usagemax/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SYMBaiEX/usagemax.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "usagemax": "./src/cli.js"
+  },
+  "files": [
+    "src/cli.js",
+    "src/core.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test src/*.test.js",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "ccusage": "20.0.20"
+  }
+}

package/src/cli.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+
+import { execFile, spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { homedir, platform } from "node:os";
+import { delimiter, dirname, extname, join } from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+
+import { batchId, buildDeltaPlan, normalizeLinkCode, sourceSummary, validHttpsUrl } from "./core.js";
+
+const require = createRequire(import.meta.url);
+const executeFile = promisify(execFile);
+const VERSION = "0.1.0";
+const DEFAULT_LINK_ENDPOINT = "https://terrific-bobcat-522.convex.site/v1/devices/link";
+const CONFIG_FILE = "config.json";
+const MAX_REPORT_BYTES = 100 * 1024 * 1024;
+const MAX_FINGERPRINT_FILES = 50_000;
+const USAGE_EXTENSIONS = new Set([".db", ".json", ".jsonl", ".sqlite", ".sqlite3"]);
+
+function configDirectory() {
+  if (process.env.USAGEMAX_CONFIG_DIR) return process.env.USAGEMAX_CONFIG_DIR;
+  if (platform() === "win32") return join(process.env.APPDATA || join(homedir(), "AppData", "Roaming"), "UsageMax");
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "usagemax");
+}
+
+function configPath() {
+  return join(configDirectory(), CONFIG_FILE);
+}
+
+async function readConfig() {
+  try {
+    const parsed = JSON.parse(await readFile(configPath(), "utf8"));
+    if (!parsed || parsed.version !== 1 || !/^umx_[a-f0-9]{64}$/.test(parsed.token || "")) return null;
+    if (!validHttpsUrl(parsed.ingestUrl, { allowLocalhost: true })) return null;
+    if (typeof parsed.deviceId !== "string" || !parsed.deviceId) return null;
+    parsed.snapshots = parsed.snapshots && typeof parsed.snapshots === "object" ? parsed.snapshots : {};
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+async function writeConfig(config) {
+  const path = configPath();
+  const directory = dirname(path);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const temporary = join(directory, `.config.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await rename(temporary, path);
+    if (platform() !== "win32") await chmod(path, 0o600);
+  } catch (error) {
+    await unlink(temporary).catch(() => undefined);
+    throw error;
+  }
+}
+
+function option(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function deviceLabel() {
+  if (platform() === "darwin") return "Mac";
+  if (platform() === "win32") return "Windows PC";
+  if (platform() === "linux") return "Linux computer";
+  return "Computer";
+}
+
+function help() {
+  process.stdout.write(`UsageMax ${VERSION}\n\n`);
+  process.stdout.write("Link aggregate coding-agent usage to your UsageMax profile.\n\n");
+  process.stdout.write("Commands:\n");
+  process.stdout.write("  usagemax                         Sync changed local usage\n");
+  process.stdout.write("  usagemax link <one-use-code>     Link and sync this computer\n");
+  process.stdout.write("           [--no-sync] [--name <name>]\n");
+  process.stdout.write("  usagemax sync [--full] [--json] Sync usage once, then exit\n");
+  process.stdout.write("  usagemax status                  Show local link status\n");
+  process.stdout.write("  usagemax doctor [--deep]         Check sources without parsing logs\n");
+  process.stdout.write("  usagemax report [...args]        Run a local ccusage report\n");
+  process.stdout.write("  usagemax unlink                  Remove the local collector key\n");
+}
+
+function ccusageCliPath() {
+  return join(dirname(require.resolve("ccusage/package.json")), "src", "cli.js");
+}
+
+function configuredPaths(variable, fallbacks) {
+  const configured = process.env[variable];
+  return configured
+    ? configured.split(",").flatMap((group) => group.split(delimiter)).map((value) => value.trim()).filter(Boolean)
+    : fallbacks;
+}
+
+function usageRoots() {
+  const home = homedir();
+  return [
+    ["claude", configuredPaths("CLAUDE_CONFIG_DIR", [join(home, ".config", "claude", "projects"), join(home, ".claude", "projects")])],
+    ["codex", configuredPaths("CODEX_HOME", [join(home, ".codex", "sessions"), join(home, ".codex", "archived_sessions")])],
+    ["opencode", configuredPaths("OPENCODE_DATA_DIR", [join(home, ".local", "share", "opencode")])],
+    ["hermes", configuredPaths("HERMES_HOME", [join(home, ".hermes", "sessions")])],
+    ["pi", configuredPaths("PI_AGENT_DIR", [join(home, ".pi", "agent", "sessions")])],
+    ["copilot", configuredPaths("COPILOT_HOME", [join(home, ".copilot")])],
+    ["gemini", configuredPaths("GEMINI_DATA_DIR", [join(home, ".gemini", "tmp")])],
+  ].flatMap(([source, paths]) => paths.map((path) => ({ source, path })));
+}
+
+async function sourceInventory() {
+  const hash = createHash("sha256");
+  const sources = new Set();
+  const roots = usageRoots();
+  let files = 0;
+  let truncated = false;
+  for (const root of roots) {
+    try {
+      const rootStat = await stat(root.path);
+      if (!rootStat.isDirectory() && !rootStat.isFile()) continue;
+      sources.add(root.source);
+    } catch {
+      continue;
+    }
+    const stack = [root.path];
+    while (stack.length && files < MAX_FINGERPRINT_FILES) {
+      const current = stack.pop();
+      let entries;
+      try {
+        entries = await readdir(current, { withFileTypes: true });
+      } catch {
+        try {
+          const metadata = await stat(current);
+          if (metadata.isFile() && USAGE_EXTENSIONS.has(extname(current).toLowerCase())) {
+            hash.update(`${root.source}\u0000${current}\u0000${metadata.size}\u0000${metadata.mtimeMs}\n`);
+            files += 1;
+          }
+        } catch {}
+        continue;
+      }
+      for (const entry of entries) {
+        const path = join(current, entry.name);
+        if (entry.isDirectory()) {
+          if (!["node_modules", ".git", "cache", "tmp"].includes(entry.name)) stack.push(path);
+          continue;
+        }
+        if (!entry.isFile() || !USAGE_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue;
+        try {
+          const metadata = await stat(path);
+          hash.update(`${root.source}\u0000${path}\u0000${metadata.size}\u0000${metadata.mtimeMs}\n`);
+          files += 1;
+        } catch {}
+        if (files >= MAX_FINGERPRINT_FILES) {
+          truncated = true;
+          break;
+        }
+      }
+    }
+  }
+  return { fingerprint: hash.digest("hex"), sources: [...sources].sort(), files, truncated };
+}
+
+async function ccusageJson(config, { full = false } = {}) {
+  const args = [ccusageCliPath(), "daily", "--json", "--offline", "--by-agent", "--order", "asc"];
+  // Reconcile yesterday once after the UTC date changes. All other incremental
+  // scans parse only today; a metadata fingerprint avoids invoking ccusage when
+  // no supported local source changed at all.
+  if (!full && config?.lastSyncAt) {
+    const today = new Date().toISOString().slice(0, 10);
+    args.push("--last", config.lastReconciledDay === today ? "1" : "2");
+  }
+  const { stdout } = await executeFile(process.execPath, args, {
+    encoding: "utf8",
+    maxBuffer: MAX_REPORT_BYTES,
+    env: { ...process.env, NO_COLOR: "1" },
+  });
+  return JSON.parse(stdout);
+}
+
+async function link(args) {
+  const code = normalizeLinkCode(args[0]);
+  if (!code) throw new Error("Paste the one-use UMX link code shown at usagemax.com/account.");
+  const configuredEndpoint = process.env.USAGEMAX_LINK_ENDPOINT || DEFAULT_LINK_ENDPOINT;
+  const endpoint = validHttpsUrl(configuredEndpoint, { allowLocalhost: true });
+  if (!endpoint) throw new Error("USAGEMAX_LINK_ENDPOINT must use HTTPS, except for localhost development.");
+  const name = (option(args, "--name") || deviceLabel()).trim().slice(0, 80);
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ code, name, platform: platform(), cliVersion: VERSION }),
+    signal: AbortSignal.timeout(15_000),
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(body?.error === "invalid_or_expired_link_code" ? "That link code is invalid, expired, or already used." : "UsageMax could not link this computer.");
+  const ingestUrl = validHttpsUrl(body.ingestUrl, { allowLocalhost: true });
+  if (!/^umx_[a-f0-9]{64}$/.test(body.token || "") || !ingestUrl) throw new Error("UsageMax returned an invalid link response.");
+  const config = {
+    version: 1,
+    token: body.token,
+    ingestUrl,
+    profileUrl: validHttpsUrl(body.profileUrl) || "https://usagemax.com/account",
+    profileHandle: typeof body.profileHandle === "string" ? body.profileHandle : undefined,
+    deviceId: randomUUID(),
+    deviceName: name,
+    linkedAt: new Date().toISOString(),
+    snapshots: {},
+  };
+  await writeConfig(config);
+  process.stdout.write(`Linked ${name} to ${config.profileHandle ? `@${config.profileHandle}` : "UsageMax"}.\n`);
+  if (args.includes("--no-sync")) {
+    process.stdout.write("No usage was uploaded. Run `bunx usagemax sync --full` when you are ready.\n");
+    return;
+  }
+  process.stdout.write("Running the first one-shot sync…\n");
+  await sync(["--full"], config);
+}
+
+async function sync(args, suppliedConfig) {
+  const config = suppliedConfig || await readConfig();
+  if (!config) throw new Error("This computer is not linked. Open https://usagemax.com/account and create a link code.");
+  const full = args.includes("--full");
+  const inventory = await sourceInventory();
+  const today = new Date().toISOString().slice(0, 10);
+  if (!full && config.lastReconciledDay === today && config.sourceFingerprint === inventory.fingerprint) {
+    const result = { accepted: 0, changedRows: 0, sources: inventory.sources, regressions: 0, scanned: false };
+    if (args.includes("--json")) process.stdout.write(`${JSON.stringify(result)}\n`);
+    else process.stdout.write("Already up to date. Local usage files have not changed; no logs were parsed or uploaded.\n");
+    return;
+  }
+  const report = await ccusageJson(config, { full });
+  const { plan, regressions } = buildDeltaPlan(report, config.snapshots, config.deviceId, "ccusage@20.0.20");
+  let accepted = 0;
+  for (let offset = 0; offset < plan.length; offset += 100) {
+    const batch = plan.slice(offset, offset + 100);
+    const events = batch.map((item) => item.event);
+    const response = await fetch(config.ingestUrl, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${config.token}`,
+        "content-type": "application/json",
+        "idempotency-key": batchId(config.deviceId, events),
+      },
+      body: JSON.stringify({ events }),
+      signal: AbortSignal.timeout(30_000),
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) throw new Error(body?.error === "unauthorized" ? "This collector key is no longer valid. Link the computer again." : `UsageMax rejected a sync batch (${response.status}).`);
+    accepted += Number(body.accepted || 0);
+    for (const item of batch) config.snapshots[item.snapshotKey] = item.snapshot;
+    config.lastSyncAt = new Date().toISOString();
+    config.lastReconciledDay = today;
+    config.sourceFingerprint = inventory.fingerprint;
+    await writeConfig(config);
+  }
+  if (!plan.length) {
+    config.lastSyncAt = new Date().toISOString();
+    config.lastReconciledDay = today;
+    config.sourceFingerprint = inventory.fingerprint;
+    await writeConfig(config);
+  }
+  const result = { accepted, changedRows: plan.length, sources: sourceSummary(report), regressions: regressions.length, scanned: true };
+  if (args.includes("--json")) process.stdout.write(`${JSON.stringify(result)}\n`);
+  else {
+    process.stdout.write(plan.length ? `Synced ${accepted} changed usage rows from ${result.sources.join(", ") || "local agents"}.\n` : "Already up to date. No usage rows were uploaded.\n");
+    if (regressions.length) process.stdout.write(`${regressions.length} local row(s) moved backward; UsageMax kept the prior high-water mark to prevent double counting.\n`);
+  }
+}
+
+async function status() {
+  const config = await readConfig();
+  if (!config) {
+    process.stdout.write("Not linked. Open https://usagemax.com/account to connect this computer.\n");
+    return;
+  }
+  process.stdout.write(`Linked: ${config.deviceName || deviceLabel()}${config.profileHandle ? ` → @${config.profileHandle}` : ""}\n`);
+  process.stdout.write(`Last sync: ${config.lastSyncAt || "never"}\n`);
+  process.stdout.write(`Profile: ${config.profileUrl || "https://usagemax.com/account"}\n`);
+}
+
+async function doctor(args = []) {
+  const config = await readConfig();
+  const inventory = await sourceInventory();
+  process.stdout.write(`Collector: ${config ? "linked" : "not linked"}\n`);
+  process.stdout.write(`Detected sources: ${inventory.sources.join(", ") || "none"} (${inventory.files}${inventory.truncated ? "+" : ""} data files)\n`);
+  if (args.includes("--deep")) {
+    const report = await ccusageJson(config, { full: false });
+    process.stdout.write(`Parsed sources: ${sourceSummary(report).join(", ") || "none"}\n`);
+  }
+  process.stdout.write(`Mode: one-shot, metadata no-op check, ${args.includes("--deep") ? "deep local parse" : "no log parsing"}\n`);
+}
+
+async function report(args) {
+  const forwarded = args.length ? args : ["daily"];
+  const child = spawn(process.execPath, [ccusageCliPath(), ...forwarded], { stdio: "inherit", env: process.env });
+  const code = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (status) => resolve(status ?? 1));
+  });
+  if (code !== 0) process.exitCode = code;
+}
+
+async function removeLink() {
+  const path = configPath();
+  const config = await readConfig();
+  if (!config) {
+    process.stdout.write("This computer is not linked.\n");
+    return;
+  }
+  await unlink(path);
+  process.stdout.write("Removed the local UsageMax collector key. Revoke the collector in your account if this computer is no longer trusted.\n");
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || "sync";
+  if (["--help", "-h", "help"].includes(command)) return help();
+  if (["--version", "-v"].includes(command)) return process.stdout.write(`${VERSION}\n`);
+  if (command === "link") return link(args.slice(1));
+  if (command === "sync") return sync(args.slice(1));
+  if (command === "status") return status();
+  if (command === "doctor") return doctor(args.slice(1));
+  if (command === "report") return report(args.slice(1));
+  if (command === "unlink") return removeLink();
+  throw new Error(`Unknown command: ${command}. Run usagemax --help.`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`UsageMax: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/src/core.js

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+
+const MAX_SAFE_COUNTER = 1_000_000_000_000;
+const MAX_SAFE_COST_MICROS = 1_000_000_000_000_000;
+
+function number(value, maximum = MAX_SAFE_COUNTER) {
+  return typeof value === "number" && Number.isFinite(value)
+    ? Math.min(maximum, Math.max(0, Math.round(value)))
+    : 0;
+}
+
+function moneyMicros(value) {
+  return typeof value === "number" && Number.isFinite(value)
+    ? Math.min(MAX_SAFE_COST_MICROS, Math.max(0, Math.round(value * 1_000_000)))
+    : 0;
+}
+
+function text(value, fallback, maximum = 120) {
+  if (typeof value !== "string") return fallback;
+  const clean = value.trim().replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, maximum);
+  return clean || fallback;
+}
+
+function providerFor(model, source) {
+  const name = model.toLowerCase();
+  if (name.includes("claude")) return "anthropic";
+  if (/^(?:gpt|o[1345]|codex)/.test(name) || name.includes("openai")) return "openai";
+  if (name.includes("gemini")) return "google";
+  if (name.includes("grok")) return "xai";
+  if (name.includes("deepseek")) return "deepseek";
+  return source;
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function normalizeLinkCode(value) {
+  const compact = text(value, "", 64).toUpperCase().replace(/\s+/g, "-");
+  return /^UMX-[A-HJ-NP-Z2-9]{4}(?:-[A-HJ-NP-Z2-9]{4}){3}$/.test(compact) ? compact : null;
+}
+
+export function validHttpsUrl(value, { allowLocalhost = false } = {}) {
+  try {
+    const url = new URL(value);
+    if (url.protocol === "https:") return url.toString();
+    if (allowLocalhost && url.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(url.hostname)) {
+      return url.toString();
+    }
+  } catch {}
+  return null;
+}
+
+function currentRows(report) {
+  if (!report || typeof report !== "object" || !Array.isArray(report.daily)) {
+    throw new Error("ccusage returned an unsupported report shape");
+  }
+  const rows = [];
+  for (const rawRow of report.daily) {
+    if (!rawRow || typeof rawRow !== "object") continue;
+    const period = text(rawRow.period, "", 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(period)) continue;
+    const agentRows = Array.isArray(rawRow.agents) && rawRow.agents.length ? rawRow.agents : [rawRow];
+    for (const rawAgent of agentRows) {
+      if (!rawAgent || typeof rawAgent !== "object") continue;
+      const source = text(rawAgent.agent, "unknown", 60).toLowerCase();
+      const breakdowns = Array.isArray(rawAgent.modelBreakdowns) && rawAgent.modelBreakdowns.length
+        ? rawAgent.modelBreakdowns
+        : [{
+            modelName: Array.isArray(rawAgent.modelsUsed) && rawAgent.modelsUsed.length === 1 ? rawAgent.modelsUsed[0] : "mixed",
+            inputTokens: rawAgent.inputTokens,
+            outputTokens: rawAgent.outputTokens,
+            cacheCreationTokens: rawAgent.cacheCreationTokens,
+            cacheReadTokens: rawAgent.cacheReadTokens,
+            cost: rawAgent.totalCost,
+          }];
+      for (const rawBreakdown of breakdowns) {
+        if (!rawBreakdown || typeof rawBreakdown !== "object") continue;
+        const model = text(rawBreakdown.modelName, "unknown", 120);
+        const inputTokens = number(rawBreakdown.inputTokens);
+        const outputTokens = number(rawBreakdown.outputTokens);
+        const cacheWriteTokens = number(rawBreakdown.cacheCreationTokens);
+        const cacheReadTokens = number(rawBreakdown.cacheReadTokens);
+        const costMicros = moneyMicros(rawBreakdown.cost);
+        rows.push({
+          key: `${source}\u001f${period}\u001f${model}`,
+          source,
+          period,
+          model,
+          current: {
+            inputTokens,
+            outputTokens,
+            cacheReadTokens,
+            cacheWriteTokens,
+            totalTokens: inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens,
+            costMicros,
+          },
+        });
+      }
+    }
+  }
+  return rows;
+}
+
+export function buildDeltaPlan(report, priorSnapshots, deviceId, pricingVersion = "ccusage") {
+  const snapshots = priorSnapshots && typeof priorSnapshots === "object" ? priorSnapshots : {};
+  const plan = [];
+  const regressions = [];
+  for (const row of currentRows(report)) {
+    const prior = snapshots[row.key] && typeof snapshots[row.key] === "object" ? snapshots[row.key] : {};
+    const delta = {
+      inputTokens: Math.max(0, row.current.inputTokens - number(prior.inputTokens)),
+      outputTokens: Math.max(0, row.current.outputTokens - number(prior.outputTokens)),
+      cacheReadTokens: Math.max(0, row.current.cacheReadTokens - number(prior.cacheReadTokens)),
+      cacheWriteTokens: Math.max(0, row.current.cacheWriteTokens - number(prior.cacheWriteTokens)),
+      totalTokens: Math.max(0, row.current.totalTokens - number(prior.totalTokens)),
+      costMicros: Math.max(0, row.current.costMicros - number(prior.costMicros, MAX_SAFE_COST_MICROS)),
+    };
+    if (Object.keys(delta).some((key) => row.current[key] < number(prior[key], key === "costMicros" ? MAX_SAFE_COST_MICROS : MAX_SAFE_COUNTER))) {
+      regressions.push(row.key);
+    }
+    if (delta.totalTokens === 0 && delta.costMicros === 0) continue;
+    const snapshot = Object.fromEntries(Object.keys(row.current).map((key) => [
+      key,
+      Math.max(
+        row.current[key],
+        number(prior[key], key === "costMicros" ? MAX_SAFE_COST_MICROS : MAX_SAFE_COUNTER),
+      ),
+    ]));
+    const version = sha256(`${row.key}\u001f${JSON.stringify(snapshot)}`).slice(0, 24);
+    plan.push({
+      snapshotKey: row.key,
+      snapshot,
+      event: {
+        eventKey: `ccusage-v1:${deviceId}:${version}`,
+        agentId: `${deviceId}:${row.source}`,
+        agentName: row.source,
+        eventType: "model_request",
+        source: row.source,
+        provider: providerFor(row.model, row.source),
+        model: row.model,
+        inputTokens: delta.inputTokens,
+        outputTokens: delta.outputTokens,
+        cacheReadTokens: delta.cacheReadTokens,
+        cacheWriteTokens: delta.cacheWriteTokens,
+        totalTokens: delta.totalTokens,
+        costMicros: delta.costMicros,
+        costBasis: "estimated",
+        pricingSource: "ccusage / LiteLLM",
+        pricingVersion,
+        status: "ok",
+        state: "synced",
+        occurredAt: `${row.period}T12:00:00.000Z`,
+        completeness: "estimated",
+      },
+    });
+  }
+  plan.sort((left, right) => left.event.occurredAt.localeCompare(right.event.occurredAt));
+  return { plan, regressions };
+}
+
+export function batchId(deviceId, events) {
+  const identity = events.map((event) => event.eventKey).join("\u001f");
+  return `cli:${deviceId}:${sha256(identity).slice(0, 32)}`;
+}
+
+export function sourceSummary(report) {
+  if (!report || typeof report !== "object" || !Array.isArray(report.daily)) return [];
+  const sources = report.daily.flatMap((row) => {
+    const agentRows = Array.isArray(row?.agents) && row.agents.length ? row.agents : [row];
+    return agentRows.map((agent) => text(agent?.agent, "", 60).toLowerCase()).filter(Boolean);
+  });
+  return [...new Set(sources)].sort();
+}