ai-spend-agent 0.5.2 → 0.5.3

package/dist/index.js

@@ -10,6 +10,13 @@ export async function runCli(argv = process.argv.slice(2)) {
         return ok(helpText());
     }
     const args = parseArgs(argv);
+    if (args.groupByInvalid) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `--group-by needs a dimension: ${groupByDimensions.join("|")}\nexample: npx aibill --group-by project`
+        };
+    }
     // Zero-key instant demo is the DEFAULT first run. Running `ai-spend-agent`
     // with no subcommand (or `npx ai-spend-agent`), or with only flags such as
     // `--group-by agent`, lands the wow immediately on sample / auto-detected
@@ -167,7 +174,11 @@ async function loadInstantReadData(args) {
     const persisted = args.ignoreState ? undefined : await readPersistedSpend(resolve(args.path));
     // Only real connected/synced provider state is authoritative enough to serve
     // directly. Sample or legacy persisted state must NEVER mask real local logs.
-    if (persisted && persisted.records.length > 0 && persisted.mode === "connected_provider") {
+    // Defense in depth: "connected" is only believed if the records actually
+    // came from a provider — local-log records mislabeled connected (a past bug)
+    // must never be served as billing data.
+    const looksConnected = (persisted?.records ?? []).some((record) => record.providerCostType !== "local_agent_logs");
+    if (persisted && persisted.records.length > 0 && persisted.mode === "connected_provider" && looksConnected) {
         return { records: persisted.records, mode: "connected", warnings };
     }
     // Real local agent logs (Claude Code / Codex) beat any sample/legacy state.
@@ -448,12 +459,16 @@ async function watchCommand(args) {
     let iteration = 0;
     while (unbounded || iteration < cycles) {
         const previous = await readOptionalJson(join(stateDir, "watch-latest.json"), null);
-        const { summary, snapshot, records } = await runWatchCycle(stateDir, args);
+        const { summary, snapshot, records, mode } = await runWatchCycle(stateDir, args);
         const deltaHeadline = buildDeltaHeadline(previous, snapshot);
+        // Watch's job is DELTAS: render the compact breakdown view per cycle, not
+        // the whole diagnose→verify readout again (the quickstart owns that).
         const plainEnglish = generatePlainEnglishSummary(summary, {
             records,
             groupBy: args.groupBy ?? "model",
-            color: args.noColor ? false : undefined
+            color: args.noColor ? false : undefined,
+            mode: mode === "sample" ? "demo" : mode === "connected_provider" ? "connected" : "local-logs",
+            view: "breakdown"
         });
         const stamped = [
             `=== watch cycle @ ${snapshot.capturedAt} ===`,
@@ -482,6 +497,10 @@ async function watchCommand(args) {
     return ok(collected.join("\n\n"));
 }
 async function runWatchCycle(stateDir, args) {
+    // The persisted mode must describe where the records ACTUALLY came from.
+    // A previous version stamped everything "connected_provider", which made
+    // later quickstarts serve stale local-log data as "connected billing" and
+    // routed apply/report to the agency artifacts. Never label by assumption.
     let records;
     let mode;
     if (args.sample) {
@@ -489,13 +508,26 @@ async function runWatchCycle(stateDir, args) {
         mode = "sample";
     }
     else {
-        records = await loadLiveRecords(stateDir);
-        if (records.length > 0) {
+        const providerState = await readOptionalJson(join(stateDir, "provider-records.json"), { records: [] });
+        if (providerState.records.length > 0) {
+            records = providerState.records;
             mode = "connected_provider";
         }
         else {
-            records = await loadSampleUsageData();
-            mode = "sample";
+            // Same freshness rule as quickstart/report: re-read local logs live,
+            // never serve a stale snapshot.
+            const logs = await loadLocalAgentUsage({
+                claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
+                codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR
+            }).catch(() => undefined);
+            if (logs && logs.records.length > 0) {
+                records = logs.records;
+                mode = "local_logs";
+            }
+            else {
+                records = await loadSampleUsageData();
+                mode = "sample";
+            }
         }
     }
     const summary = analyzeSpend(records);
@@ -517,7 +549,7 @@ async function runWatchCycle(stateDir, args) {
         sourceId: "watch",
         detail: `Watch cycle captured ${snapshot.recordCount} records totaling $${snapshot.totalUsd.toFixed(2)}.`
     });
-    return { summary, snapshot, records };
+    return { summary, snapshot, records, mode };
 }
 function buildDeltaHeadline(previous, current) {
     if (!previous) {
@@ -554,14 +586,6 @@ function buildDeltaHeadline(previous, current) {
     }
     return lines.join(" ");
 }
-async function loadLiveRecords(stateDir) {
-    const providerState = await readOptionalJson(join(stateDir, "provider-records.json"), { records: [] });
-    if (providerState.records.length > 0) {
-        return providerState.records;
-    }
-    const spendState = await readOptionalJson(join(stateDir, "spend.json"), {});
-    return spendState.records ?? [];
-}
 function sleep(milliseconds) {
     return new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds));
 }
@@ -726,7 +750,15 @@ async function syncProviderCommand(args) {
     const rootPath = resolve(args.path);
     const stateDir = join(rootPath, ".ai-spend-agent");
     if (!args.provider || !args.authReference || !args.startTime) {
-        return { exitCode: 1, stdout: "", stderr: "sync-provider requires --provider, --auth-reference env:NAME, and --start-time" };
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                "sync-provider requires --provider, --auth-reference env:NAME, and --start-time <unix seconds>.",
+                "example:",
+                "  npx aibill sync-provider --provider anthropic --auth-reference env:ANTHROPIC_ADMIN_KEY --start-time 1750000000"
+            ].join("\n")
+        };
     }
     try {
         const result = await fetchProviderUsageRecords({
@@ -927,7 +959,14 @@ async function buildReportInput(stateDir, rootPath) {
     // re-reads the logs fresh, so report/apply must too — otherwise yesterday's
     // persisted snapshot makes the artifact's numbers disagree with the screen.
     // Persisted state stays authoritative only for connected/sample data.
-    const needsFreshLogs = !spendState?.summary || !spendState.records || spendState.records.length === 0 || spendState.mode === "local_logs";
+    const persistedLooksConnected = (spendState?.records ?? []).some((record) => record.providerCostType !== "local_agent_logs");
+    const needsFreshLogs = !spendState?.summary ||
+        !spendState.records ||
+        spendState.records.length === 0 ||
+        spendState.mode === "local_logs" ||
+        // Mislabeled state (local-log records stamped connected by a past bug)
+        // must be superseded by a fresh read, not trusted.
+        (spendState.mode === "connected_provider" && !persistedLooksConnected);
     if (needsFreshLogs) {
         const logs = await loadLocalAgentUsage({
             claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
@@ -1061,6 +1100,18 @@ function parseArgs(argv) {
                 parsed.groupBy = next;
                 index += 1;
             }
+            else {
+                // Missing/invalid dimension: surface an error instead of silently
+                // rendering the full readout the user didn't ask for. A following
+                // flag is NOT the dimension — don't consume it.
+                if (next && !next.startsWith("--")) {
+                    parsed.groupByInvalid = next;
+                    index += 1;
+                }
+                else {
+                    parsed.groupByInvalid = "(missing)";
+                }
+            }
             continue;
         }
         if (arg === "--path") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spend-agent",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Your AI spend in one view, in 90 seconds — local-first CLI for OpenAI, Anthropic, Cursor, Copilot + Claude Code/Codex session logs, with a ranked savings cut list, and flags the tools your agent loads but never uses (dead context).",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,8 +49,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@agent-finops/core": "0.5.2",
-    "@agent-finops/report": "0.5.2",
+    "@agent-finops/core": "0.5.3",
+    "@agent-finops/report": "0.5.3",
     "yocto-spinner": "^1.2.0"
   }
 }