ai-spend-agent 0.6.1 → 0.7.0

package/README.md

@@ -4,6 +4,7 @@ The full [aibill](https://github.com/futurastudio/ai-spend-agent) CLI.
 
 ```bash
 npx aibill init
+npx aibill statusline install # optional Claude Code cache-only status line
 npx ai-spend-agent
 # short alias
 npx aibill
@@ -15,6 +16,13 @@ aggregate cache under `~/.aibill/cache/`. Init never replaces missing personal
 evidence with the bundled sample and never overwrites existing connected
 source or audit state.
 
+The optional status line is explicit and reversible. It installs a standalone
+Node-builtins-only runner at Claude user scope, rereads only the private
+aggregate cache, and never scans transcripts or contacts a provider from the
+hook. Subscription runway appears only when it was transcript-reported; `~`
+means API-equivalent value, and untilded `billed` money requires verified
+provider evidence. Remove it with `npx aibill statusline uninstall`.
+
 It reads local Claude Code and Codex metadata, labels API-equivalent estimates,
 and can optionally add official OpenAI or Anthropic provider-reported cost
 through an environment-variable reference. No product telemetry is sent.

package/dist/index.d.ts

@@ -4,7 +4,16 @@ export type CliResult = {
     stdout: string;
     stderr: string;
 };
-export declare function runCli(argv?: string[]): Promise<CliResult>;
+export type CliRuntimeOptions = {
+    /** Test/embedding override. Production always defaults to the OS home. */
+    homeDirectory?: string;
+    /** Test/embedding override. Packed production reads the built runtime asset. */
+    statuslineRunnerContents?: string | Uint8Array;
+    statuslineNow?: Date;
+    statuslineColumns?: number;
+    statuslineTimeZone?: string;
+};
+export declare function runCli(argv?: string[], runtime?: CliRuntimeOptions): Promise<CliResult>;
 /**
  * Full bin entrypoint (node guard, spinner, error voice, exit code).
  * Exported so the thin alias packages (`aispend`, `aireceipt`) run the EXACT

package/dist/index.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
 import { mkdir, readFile, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { analyzeSpend, attributeUsageRecords, buildUsageGlance, buildActivitySnapshot, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, invalidateConnectedSpendTrustReceipt, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, writeSafeStateText, verifyConnectedSpendTrustReceipt, verifyConnectedSourceRegistryTrustReceipt, writeConnectedSpendTrustReceipt, loadDeadContext, sampleDeadContext, latestObservedWorkingDirectory, downgradeSampleUsageEvidence, isBundledSampleUsage, loadLocalAgentUsage, loadLocalAgentFinancialUsage, loadSampleUsageData, parseUsageRecord, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProviderConnectorStub, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, normalizeSourceRegistry, downgradeUntrustedSourceRegistryClaims, buildSourceStatuses, slugifySourceId, financialEvidenceForRecords, formatSourceStatuses, readActivitySnapshot, recordActivitySnapshotRefreshFailure, sourceStatusDefinitions, writeActivitySnapshot } from "@agent-finops/core";
+import { StatuslineInstallerError, installClaudeStatusline, uninstallClaudeStatusline } from "./statuslineInstaller.js";
+import { readStatuslineCache, renderStatusline } from "./statuslineRuntime.js";
 import { generateActionPlanMarkdown, generateApplyArtifactMarkdown, generateDemoPackageMarkdown, generateHtmlReport, generateMarkdownReport, generatePlainEnglishSummary, generatePolicyConfigDraftMarkdown, generateReportCardCaption, generateReportCardSvg, generateVerificationPlanMarkdown, groupByDimensions } from "@agent-finops/report";
-export async function runCli(argv = process.argv.slice(2)) {
+export async function runCli(argv = process.argv.slice(2), runtime = {}) {
     if (argv.includes("--version") || argv.includes("-v")) {
         return ok(await cliVersion());
     }
@@ -34,7 +37,10 @@ export async function runCli(argv = process.argv.slice(2)) {
         return resetCommand(args);
     }
     if (args.command === "init") {
-        return initCommand(args);
+        return initCommand(args, runtime);
+    }
+    if (args.command === "statusline") {
+        return statuslineCommand(args, runtime);
     }
     if (args.command === "scan") {
         return scanCommand(args);
@@ -998,7 +1004,105 @@ async function resetCommand(args) {
         "next run will re-read your real local agent logs (or demo sample if none)."
     ].join("\n"));
 }
-async function initCommand(args) {
+async function statuslineCommand(args, runtime) {
+    const action = args.statuslineAction;
+    if (action === undefined) {
+        const cache = await readStatuslineCache({
+            cacheDirectory: process.env.AIBILL_CACHE_DIR,
+            homeDirectory: runtime.homeDirectory
+        });
+        return ok(renderStatusline(cache, {
+            now: runtime.statuslineNow,
+            columns: runtime.statuslineColumns,
+            timeZone: runtime.statuslineTimeZone
+        }));
+    }
+    if (action === "install")
+        return installStatuslineCommand(args, runtime);
+    if (action === "uninstall")
+        return uninstallStatuslineCommand(runtime);
+    if (action === "refresh")
+        return refreshStatuslineCommand(args, runtime);
+    return {
+        exitCode: 1,
+        stdout: "",
+        stderr: `Unknown statusline action: ${sanitizeSecretishError(action)}\n` +
+            "Use: aibill statusline [refresh|install|uninstall]"
+    };
+}
+async function packagedStatuslineRunner(runtime) {
+    if (runtime.statuslineRunnerContents !== undefined) {
+        return runtime.statuslineRunnerContents;
+    }
+    return readFile(fileURLToPath(new URL("./statuslineRuntime.js", import.meta.url)));
+}
+async function installStatuslineCommand(args, runtime) {
+    try {
+        const result = await installClaudeStatusline({
+            homeDir: runtime.homeDirectory ?? homedir(),
+            cwd: resolve(args.path),
+            runnerContents: await packagedStatuslineRunner(runtime),
+            replace: args.replaceStatusline
+        });
+        return ok([
+            result.action === "unchanged"
+                ? "aibill statusline is already installed in Claude user settings."
+                : "aibill statusline installed in Claude user settings.",
+            "Claude Code: run /status to verify the active setting and every managed source.",
+            "The renderer reads only the private aibill cache; it never reads Claude's session stdin as financial evidence."
+        ].join("\n"));
+    }
+    catch (error) {
+        return statuslineInstallerFailure("install", error);
+    }
+}
+async function uninstallStatuslineCommand(runtime) {
+    try {
+        const result = await uninstallClaudeStatusline({
+            homeDir: runtime.homeDirectory ?? homedir(),
+            cwd: process.cwd()
+        });
+        return ok([
+            result.statusLineAction === "restored-prior"
+                ? "aibill statusline was removed and the prior Claude user statusLine was restored."
+                : "aibill statusline was removed from Claude user settings.",
+            {
+                removed: "The owned standalone runner was removed.",
+                restored: "The exact pre-installation runner was restored.",
+                "preserved-modified": "The modified runner was preserved because it was no longer owned.",
+                "already-missing": "The owned runner was already missing; no runner file was removed."
+            }[result.runnerAction],
+            ...result.warnings
+        ].join("\n"));
+    }
+    catch (error) {
+        return statuslineInstallerFailure("uninstall", error);
+    }
+}
+function statuslineInstallerFailure(action, error) {
+    const installerError = error instanceof StatuslineInstallerError
+        ? error
+        : new StatuslineInstallerError("unsafe-settings-file", `The local filesystem operation failed safely${safeFileSystemErrorCode(error)}; no successful settings change was claimed.`);
+    const replacement = installerError.code === "statusline-conflict"
+        ? "\nTo replace an existing status line explicitly: aibill statusline install --replace"
+        : "";
+    return {
+        exitCode: 1,
+        stdout: "",
+        stderr: [
+            `aibill statusline ${action} stopped safely: ${sanitizeSecretishError(installerError.message)}`,
+            "No successful settings change was claimed. Resolve the conflict, then verify active sources with /status in Claude Code.",
+            replacement.trim()
+        ].filter(Boolean).join("\n")
+    };
+}
+function safeFileSystemErrorCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return "";
+    const code = String(error.code ?? "");
+    return /^[A-Z][A-Z0-9_]{1,31}$/.test(code) ? ` (${code})` : "";
+}
+async function initCommand(args, runtime = {}) {
     if (args.sample) {
         return {
             exitCode: 1,
@@ -1050,20 +1154,56 @@ async function initCommand(args) {
     if (existingRegistry)
         normalizeSourceRegistry(existingRegistry);
     validateInitAuditLog(existingAuditLog);
-    // Capture one attempt anchor immediately before the concurrent detection /
-    // backfill reads. Snapshot windows, refresh ordering, and the manifest all
-    // refer to this same moment.
+    const refresh = await collectAndPublishActivitySnapshot({
+        rootPath,
+        cacheDirectory,
+        detectedPlanOverride
+    });
+    const { asOf, activitySnapshot, logs, detectedPlans, trustedProviderRecords, persisted, scanError, cacheStatus } = refresh;
+    if (!stateDirectoryExists) {
+        stateDir = await resolveSafeStateDirectory(rootPath, { create: true });
+    }
+    await preserveOrCreateInitRegistry(stateDir, rootPath, statePreparedAt, existingRegistry);
+    await preserveOrCreateInitAuditLog(stateDir, rootPath, statePreparedAt, existingAuditLog);
+    const manifest = buildInitManifest(existingManifest, asOf);
+    await writeSafeStateText(stateDir, "manifest.json", `${JSON.stringify(manifest, null, 2)}\n`);
+    const receipt = formatInitReceipt({
+        rootPath,
+        asOf,
+        activitySnapshot,
+        logs,
+        detectedPlans,
+        trustedProviderRecords,
+        providerCoverage: persisted?.providerCoverage,
+        trustedProviderState: persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === true,
+        untrustedProviderState: persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted !== true,
+        scanError,
+        cacheStatus
+    });
+    if (!args.statusline) {
+        return ok(`${receipt}\noptional Claude Code status line: npx aibill statusline install`);
+    }
+    const installation = await installStatuslineCommand(args, runtime);
+    return installation.exitCode === 0
+        ? ok(`${receipt}\n${installation.stdout}`)
+        : {
+            exitCode: installation.exitCode,
+            stdout: receipt,
+            stderr: installation.stderr
+        };
+}
+async function collectAndPublishActivitySnapshot(input) {
+    // One attempt anchor binds every rolling window and cache ordering decision.
     const asOf = new Date();
-    const planPromise = detectedPlanOverride
-        ? Promise.resolve(detectedPlanOverride)
+    const planPromise = input.detectedPlanOverride
+        ? Promise.resolve(input.detectedPlanOverride)
         : detectLocalPlans({
             claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
             codexAuthPath: process.env.AI_SPEND_CODEX_AUTH
         }).catch(() => []);
-    // Attach the rejection handler now. A malformed spend file can fail before
-    // the bounded transcript scan completes; leaving that promise unattended
-    // during the scan would create an unhandled rejection.
-    const persistedPromise = readPersistedSpend(rootPath, { strict: true }).then((persisted) => ({ persisted }), (error) => ({ error }));
+    // Attach the rejection handler immediately so a failed transcript scan can
+    // never leave an unhandled persisted-state rejection behind.
+    const persistedPromise = readPersistedSpend(input.rootPath, { strict: true }).then((persisted) => ({ persisted }), (error) => ({ error }));
     let logs;
     let scanError;
     try {
@@ -1080,7 +1220,8 @@ async function initCommand(args) {
     if ("error" in persistedResult)
         throw persistedResult.error;
     const persisted = persistedResult.persisted;
-    const trustedProviderRecords = persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === true
+    const trustedProviderRecords = persisted?.mode === "connected_provider" &&
+        persisted.connectedTrust?.trusted === true
         ? selectProviderFinancialHeadlineRecords(persisted.records)
         : [];
     let activitySnapshot;
@@ -1091,10 +1232,9 @@ async function initCommand(args) {
     if (logs && !structuredSourceFailure) {
         let refreshErrorCode = "invalid_evidence";
         try {
-            const generatedAt = new Date().toISOString();
             activitySnapshot = buildActivitySnapshot({
                 asOf: asOf.toISOString(),
-                generatedAt,
+                generatedAt: new Date().toISOString(),
                 records: [...logs.records, ...trustedProviderRecords],
                 calls: logs.calls,
                 detectedPlans,
@@ -1113,43 +1253,102 @@ async function initCommand(args) {
                 sampleData: false
             });
             refreshErrorCode = "cache_write_failed";
-            const written = await writeActivitySnapshot(activitySnapshot, { cacheDirectory });
+            const written = await writeActivitySnapshot(activitySnapshot, {
+                cacheDirectory: input.cacheDirectory
+            });
             cacheStatus = written.status === "written" ? "refreshed" : "kept newer snapshot";
         }
         catch {
             scanError = refreshErrorCode === "invalid_evidence"
                 ? "the observed evidence could not produce a valid activity snapshot"
                 : "the private activity cache could not be updated";
-            const failed = await recordActivitySnapshotRefreshFailure(asOf.toISOString(), refreshErrorCode, { cacheDirectory });
+            const failed = await recordActivitySnapshotRefreshFailure(asOf.toISOString(), refreshErrorCode, { cacheDirectory: input.cacheDirectory });
             activitySnapshot = failed.snapshot;
             cacheStatus = "refresh failed";
         }
     }
     else {
-        const failed = await recordActivitySnapshotRefreshFailure(asOf.toISOString(), structuredSourceFailure ? "source_unreadable" : "scan_failed", { cacheDirectory });
+        const failed = await recordActivitySnapshotRefreshFailure(asOf.toISOString(), structuredSourceFailure ? "source_unreadable" : "scan_failed", { cacheDirectory: input.cacheDirectory });
         activitySnapshot = failed.snapshot;
         cacheStatus = "refresh failed";
     }
-    if (!stateDirectoryExists) {
-        stateDir = await resolveSafeStateDirectory(rootPath, { create: true });
-    }
-    await preserveOrCreateInitRegistry(stateDir, rootPath, statePreparedAt, existingRegistry);
-    await preserveOrCreateInitAuditLog(stateDir, rootPath, statePreparedAt, existingAuditLog);
-    const manifest = buildInitManifest(existingManifest, asOf);
-    await writeSafeStateText(stateDir, "manifest.json", `${JSON.stringify(manifest, null, 2)}\n`);
-    return ok(formatInitReceipt({
-        rootPath,
+    return {
         asOf,
         activitySnapshot,
         logs,
         detectedPlans,
         trustedProviderRecords,
-        providerCoverage: persisted?.providerCoverage,
-        trustedProviderState: persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === true,
-        untrustedProviderState: persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted !== true,
+        persisted,
         scanError,
         cacheStatus
-    }));
+    };
+}
+async function refreshStatuslineCommand(args, runtime) {
+    if (args.sample) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "aibill statusline refresh only uses real local evidence; --sample was rejected and the cache was not changed."
+        };
+    }
+    let detectedPlanOverride;
+    if (args.plan) {
+        const override = planOverrideFromFlag(args.plan);
+        if (!override) {
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: `Unknown --plan "${args.plan}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+            };
+        }
+        detectedPlanOverride = [override];
+    }
+    const rootPath = await resolveSafeScanRoot(args.path);
+    const cacheDirectory = process.env.AIBILL_CACHE_DIR;
+    await preflightInitCache(cacheDirectory);
+    let refresh;
+    try {
+        refresh = await collectAndPublishActivitySnapshot({
+            rootPath,
+            cacheDirectory,
+            detectedPlanOverride
+        });
+    }
+    catch (error) {
+        const attemptedAt = new Date().toISOString();
+        await recordActivitySnapshotRefreshFailure(attemptedAt, "invalid_evidence", {
+            cacheDirectory
+        }).catch(() => undefined);
+        const cache = await readStatuslineCache({
+            cacheDirectory,
+            homeDirectory: runtime.homeDirectory
+        });
+        return {
+            exitCode: 1,
+            stdout: renderStatusline(cache, {
+                now: runtime.statuslineNow,
+                columns: runtime.statuslineColumns,
+                timeZone: runtime.statuslineTimeZone
+            }),
+            stderr: `aibill statusline refresh failed safely: ${sanitizeSecretishError(error instanceof Error ? error.message : String(error))}`
+        };
+    }
+    const cache = await readStatuslineCache({
+        cacheDirectory,
+        homeDirectory: runtime.homeDirectory
+    });
+    const line = renderStatusline(cache, {
+        now: runtime.statuslineNow,
+        columns: runtime.statuslineColumns,
+        timeZone: runtime.statuslineTimeZone
+    });
+    return refresh.cacheStatus === "refresh failed"
+        ? {
+            exitCode: 1,
+            stdout: line,
+            stderr: `aibill statusline refresh failed safely: ${refresh.scanError ?? "local evidence was unavailable"}`
+        }
+        : ok(line);
 }
 async function preflightInitCache(cacheDirectory) {
     const existing = await readActivitySnapshot({ cacheDirectory });
@@ -2546,6 +2745,9 @@ function parseArgs(argv) {
         sample: false,
         path: process.cwd()
     };
+    if (command === "statusline" && rest[0] && !rest[0].startsWith("--")) {
+        parsed.statuslineAction = rest.shift();
+    }
     if (command === "connect" && rest[0] && !rest[0].startsWith("--")) {
         parsed.provider = rest[0];
         rest.shift();
@@ -2568,6 +2770,14 @@ function parseArgs(argv) {
             parsed.sources = true;
             continue;
         }
+        if (arg === "--statusline") {
+            parsed.statusline = true;
+            continue;
+        }
+        if (arg === "--replace") {
+            parsed.replaceStatusline = true;
+            continue;
+        }
         if (arg === "--ignore-state") {
             parsed.ignoreState = true;
             continue;
@@ -2942,6 +3152,12 @@ function helpText() {
         "Other commands:",
         "  --version, -v           Print the package version without reading local data",
         "  init [--path <dir>]     Backfill 30 days machine-wide, print the first evidence-labeled receipt, and cache a private snapshot",
+        "    [--statusline]        Explicitly install the Claude Code status line after a successful init",
+        "  statusline              Render one plan-aware line from the private cache (no scan or network)",
+        "  statusline refresh      Foreground refresh from real local evidence, then render the cache",
+        "  statusline install      Reversibly add the standalone runner to Claude user settings",
+        "    [--replace]           Explicitly replace an existing statusLine while preserving it for uninstall",
+        "  statusline uninstall    Remove only the owned setting and restore its preserved predecessor",
         "  doctor [--sources]      Launch diagnostics; --sources shows validation, evidence, freshness, and errors",
         "  reset [--path <dir>]    Clear persisted spend state (so sample state can't mask real logs)",
         "  --ignore-state          On the default/quickstart run, ignore persisted spend.json for this run",

package/dist/statuslineInstaller.d.ts

@@ -0,0 +1,80 @@
+export declare const aibillStatuslineRefreshIntervalSeconds = 30;
+export type StatuslinePlatform = "darwin" | "linux" | "win32";
+export type StatuslinePaths = {
+    settingsPath: string;
+    runnerPath: string;
+    receiptPath: string;
+    backupDirectory: string;
+    lockPath: string;
+    projectSettingsPath: string;
+    localSettingsPath: string;
+    managedSettingsPath: string;
+    managedDropInDirectory: string;
+};
+export type AibillStatusLineSetting = {
+    type: "command";
+    command: string;
+    refreshInterval: 30;
+};
+type InstallerTestHooks = {
+    /** Runs only after every replacement file has been fully prepared and checked. */
+    afterPrepare?: () => void | Promise<void>;
+    /** Backward-compatible name used by the first installer fixtures. */
+    beforeSettingsCommit?: () => void | Promise<void>;
+    /** Tests can exercise a race between ordered transaction commit points. */
+    afterMutationCommit?: (path: string, index: number) => void | Promise<void>;
+};
+export type InstallStatuslineOptions = InstallerTestHooks & {
+    homeDir: string;
+    cwd: string;
+    /** Integration can pass a packaged asset path without importing renderer code. */
+    runnerSourcePath?: string;
+    /** Or pass the exact standalone runner bytes produced by the renderer lane. */
+    runnerContents?: string | Uint8Array;
+    platform?: StatuslinePlatform;
+    replace?: boolean;
+    now?: Date;
+    /** Windows only: the locally visible Program Files root. */
+    programFilesDir?: string;
+    /** Narrow fixture/embedding overrides; unspecified paths keep platform defaults. */
+    pathOverrides?: Partial<StatuslinePaths>;
+    /** Tests and embedding callers can supply explicit locally visible managed files. */
+    managedSettingsPaths?: string[];
+};
+export type UninstallStatuslineOptions = InstallerTestHooks & {
+    homeDir: string;
+    cwd: string;
+    platform?: StatuslinePlatform;
+    programFilesDir?: string;
+    pathOverrides?: Partial<StatuslinePaths>;
+};
+export type StatuslineInstallResult = {
+    action: "installed" | "unchanged";
+    settingsPath: string;
+    runnerPath: string;
+    receiptPath: string;
+    backupPath?: string;
+};
+export type StatuslineUninstallResult = {
+    action: "uninstalled";
+    settingsPath: string;
+    runnerPath: string;
+    runnerRemoved: boolean;
+    runnerAction: "removed" | "restored" | "preserved-modified" | "already-missing";
+    statusLineAction: "removed" | "restored-prior";
+    warnings: string[];
+};
+export type StatuslineInstallerErrorCode = "concurrent-edit" | "hooks-disabled" | "installer-busy" | "invalid-receipt" | "invalid-settings-json" | "missing-ownership" | "ownership-mismatch" | "settings-shadowed" | "statusline-conflict" | "unsafe-runner-source" | "unsafe-settings-file";
+export declare class StatuslineInstallerError extends Error {
+    readonly code: StatuslineInstallerErrorCode;
+    constructor(code: StatuslineInstallerErrorCode, message: string);
+}
+export declare function resolveStatuslinePaths(homeDir: string, cwd: string, platform?: StatuslinePlatform, options?: {
+    programFilesDir?: string;
+}): StatuslinePaths;
+export declare function buildAibillStatusLineSetting(_platform?: StatuslinePlatform): AibillStatusLineSetting;
+export declare function manualStatuslineConfigSnippet(platform?: StatuslinePlatform): string;
+export declare function installClaudeStatusline(options: InstallStatuslineOptions): Promise<StatuslineInstallResult>;
+export declare function uninstallClaudeStatusline(options: UninstallStatuslineOptions): Promise<StatuslineUninstallResult>;
+export {};
+//# sourceMappingURL=statuslineInstaller.d.ts.map