@agent-finops/core 0.8.1 → 0.9.1

package/dist/runtimeCommands.js

@@ -0,0 +1,50 @@
+/**
+ * Distribution truth for the guided action loop.
+ *
+ * Release gate: change this single value to `published` only in the exact,
+ * coordinated new-version release candidate. Its packed-install gate must
+ * prove every generated handoff uses the new package command before publish;
+ * the clean public-registry smoke then verifies that same exact commit. Until
+ * that release candidate exists, handoffs execute the already-built checkout
+ * and must not let `npx` download the older public package.
+ */
+export const AIBILL_IMPROVE_DELIVERY_V0 = "published";
+/**
+ * Build a command for capabilities that exist only in the current source
+ * preview. Keep every generated handoff on the checkout until the coordinated
+ * npm release containing those capabilities has passed its registry smoke.
+ */
+export function aibillCommandV0(args, delivery = AIBILL_IMPROVE_DELIVERY_V0) {
+    const commandArgs = args.trim();
+    return delivery === "source_preview"
+        ? `node packages/cli/dist/index.js${commandArgs.length > 0 ? ` ${commandArgs}` : ""}`
+        : `npx aibill${commandArgs.length > 0 ? ` ${commandArgs}` : ""}`;
+}
+/** One privacy-safe command shared by terminal, MCP, and Glance. */
+export function aibillImproveCommandV0(delivery = AIBILL_IMPROVE_DELIVERY_V0) {
+    return aibillCommandV0(delivery === "source_preview" ? "improve --path ." : "improve", delivery);
+}
+/** Published semver shape a composed pin must have (charset-safe by regex). */
+const pinnableVersionPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/**
+ * Version-pinned command for machine-composed lines (M4c): a command an AI
+ * client relays to a human must be reproducible and must not silently
+ * resolve to a different release, so `draft_improve_command` pins to the
+ * composing package's own version (`npx aibill@<version> …`). A version
+ * that is not a plain semver falls back to the unpinned published command
+ * rather than composing an unrunnable line. In source-preview builds the
+ * checkout command needs no pin.
+ *
+ * Release gate (n2): the coordinated release must also prove the pinned
+ * version EXISTS on the public registry and supports the composed flags —
+ * the packed-install gate described on AIBILL_IMPROVE_DELIVERY_V0 is the
+ * natural home for that check; QA 24 asserts only that the pin is present.
+ */
+export function aibillPinnedCommandV0(args, version, delivery = AIBILL_IMPROVE_DELIVERY_V0) {
+    const commandArgs = args.trim();
+    if (delivery === "source_preview" || !pinnableVersionPattern.test(version)) {
+        return aibillCommandV0(commandArgs, delivery);
+    }
+    return `npx aibill@${version}${commandArgs.length > 0 ? ` ${commandArgs}` : ""}`;
+}
+//# sourceMappingURL=runtimeCommands.js.map

package/dist/scanGuard.d.ts

@@ -33,7 +33,9 @@ export declare function resolveSafeStateDirectory(rootPath: string, options?: {
  * inside a cloned repository, so validating only the parent directory is not
  * enough: a committed child symlink must never expose an arbitrary local file.
  */
-export declare function readSafeStateText(stateDir: string, fileName: string): Promise<string>;
+export declare function readSafeStateText(stateDir: string, fileName: string, options?: {
+    maxBytes?: number;
+}): Promise<string>;
 /**
  * Atomically replace one regular child file. The temporary file is created
  * exclusively with mode 0600, and rename replaces a last-moment symlink

package/dist/scanGuard.js

@@ -1,8 +1,10 @@
 import { homedir } from "node:os";
 import { constants, realpathSync } from "node:fs";
+import { execFile as execFileCallback } from "node:child_process";
 import { chmod, lstat, mkdir, open, realpath, rename, stat, unlink } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { basename, join, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
 /**
  * Shared unsafe-scan-root policy for EVERY scan entrypoint (CLI `scan`, MCP
  * `scan_ai_spend`, and any future surface). Scanning the home directory, the
@@ -29,6 +31,7 @@ const systemRootDirectories = new Set([
     "/sys",
     "/dev"
 ]);
+const execFile = promisify(execFileCallback);
 export class UnsafeScanRootError extends Error {
     rootPath;
     constructor(rootPath, reason) {
@@ -127,9 +130,11 @@ export async function resolveSafeStateDirectory(rootPath, options = {}) {
             return undefined;
         throw error;
     });
+    let createdStateDirectory = false;
     if (!stateInfo && options.create) {
         try {
             await mkdir(statePath, { mode: 0o700 });
+            createdStateDirectory = true;
         }
         catch (error) {
             // A concurrent creator is safe only after the same lstat checks below.
@@ -153,17 +158,145 @@ export async function resolveSafeStateDirectory(rootPath, options = {}) {
     if (canonicalState !== statePath) {
         throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent does not resolve directly inside the approved root");
     }
-    if (options.create) {
+    // Project state can contain private receipts and experiment evidence. A
+    // repository-authored marker or tracked state is not a trust boundary: the
+    // exact marker, private permissions, untracked status, and effective Git
+    // ignore rule must all be proven before either reads or writes proceed.
+    await assertPrivateStateGitBoundary(canonicalRoot, canonicalState, options.create === true);
+    const directoryMode = stateInfo.mode & 0o777;
+    if ((directoryMode & 0o077) !== 0) {
+        if (options.create !== true) {
+            throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent permissions expose private state metadata to other users");
+        }
+        // Explicit create/write calls may safely migrate a legacy aibill-owned
+        // directory only after the Git privacy boundary above proved that neither
+        // it nor a child is tracked and that the exact private marker is effective.
+        // Read-only callers never change permissions implicitly.
+        await chmod(statePath, 0o700);
+        const securedInfo = await lstat(statePath);
+        if (!securedInfo.isDirectory() || securedInfo.isSymbolicLink() ||
+            securedInfo.dev !== stateInfo.dev || securedInfo.ino !== stateInfo.ino ||
+            (securedInfo.mode & 0o077) !== 0) {
+            throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent permissions could not be secured without changing directory identity");
+        }
+        stateInfo = securedInfo;
+    }
+    else if (options.create && createdStateDirectory && directoryMode !== 0o700) {
+        // An unusually restrictive umask is still normalized for stable private
+        // access only on the directory this call created.
         await chmod(statePath, 0o700);
     }
     return statePath;
 }
+async function assertPrivateStateGitBoundary(canonicalRoot, statePath, create) {
+    const gitEntryRoot = await findEnclosingGitEntryRoot(canonicalRoot);
+    const gitRoot = await resolveGitRoot(canonicalRoot, gitEntryRoot);
+    // Outside a Git worktree, the state files' own 0600 permissions and safe
+    // no-follow I/O are the privacy boundary. The ignore marker is specifically
+    // a repository-leak guard and is required only when Git can see this root.
+    if (!gitRoot)
+        return;
+    const relativeState = relative(gitRoot, statePath);
+    if (!relativeState || relativeState === ".." || relativeState.startsWith(`..${sep}`) ||
+        isAbsolute(relativeState)) {
+        throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent is outside the resolved Git worktree");
+    }
+    const tracked = await execFile("git", ["-C", gitRoot, "ls-files", "--", relativeState], { encoding: "utf8", maxBuffer: 64 * 1024 }).then(({ stdout }) => stdout.trim()).catch(() => {
+        throw new UnsafeStateDirectoryError(statePath, "Git tracking status for .ai-spend-agent could not be verified");
+    });
+    if (tracked) {
+        throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent or one of its children is already tracked by Git");
+    }
+    const markerPath = join(statePath, ".gitignore");
+    let handle;
+    try {
+        handle = await open(markerPath, constants.O_RDONLY | noFollowFlag());
+    }
+    catch (error) {
+        if (!isNodeError(error, "ENOENT") || !create) {
+            if (isNodeError(error, "ELOOP")) {
+                throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent/.gitignore is a symbolic link");
+            }
+            throw error;
+        }
+        let writer;
+        try {
+            writer = await open(markerPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollowFlag(), 0o600);
+            await writer.writeFile("*\n", "utf8");
+            await writer.sync();
+        }
+        catch (createError) {
+            if (isNodeError(createError, "ELOOP")) {
+                throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent/.gitignore is a symbolic link");
+            }
+            if (!isNodeError(createError, "EEXIST"))
+                throw createError;
+        }
+        finally {
+            await writer?.close().catch(() => undefined);
+        }
+        handle = await open(markerPath, constants.O_RDONLY | noFollowFlag());
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || (info.mode & 0o077) !== 0 || info.size !== 2) {
+            throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent/.gitignore is not the private aibill marker");
+        }
+        const bytes = Buffer.alloc(2);
+        const { bytesRead } = await handle.read(bytes, 0, 2, 0);
+        if (bytesRead !== 2 || bytes.toString("utf8") !== "*\n") {
+            throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent/.gitignore is not the exact private aibill marker");
+        }
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+    const relativeProbe = join(relativeState, "privacy-probe.json");
+    const ignored = await execFile("git", ["-C", gitRoot, "check-ignore", "--quiet", "--no-index", "--", relativeProbe], { maxBuffer: 64 * 1024 }).then(() => true).catch(() => false);
+    if (!ignored) {
+        throw new UnsafeStateDirectoryError(statePath, ".ai-spend-agent is not proven ignored by Git");
+    }
+}
+async function findEnclosingGitEntryRoot(path) {
+    let current = resolve(path);
+    while (true) {
+        const entry = await lstat(join(current, ".git")).catch((error) => {
+            if (isNodeError(error, "ENOENT") || isNodeError(error, "ENOTDIR"))
+                return undefined;
+            throw error;
+        });
+        if (entry)
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+async function resolveGitRoot(canonicalRoot, gitEntryRoot) {
+    try {
+        const { stdout } = await execFile("git", ["-C", canonicalRoot, "rev-parse", "--show-toplevel"], { encoding: "utf8", maxBuffer: 64 * 1024 });
+        const reported = stdout.trim();
+        if (!reported || !isAbsolute(reported)) {
+            throw new UnsafeStateDirectoryError(canonicalRoot, "Git returned an invalid worktree root");
+        }
+        return await realpath(reported);
+    }
+    catch (error) {
+        if (error instanceof UnsafeStateDirectoryError)
+            throw error;
+        if (gitEntryRoot) {
+            throw new UnsafeStateDirectoryError(canonicalRoot, "the enclosing Git worktree could not be verified");
+        }
+        return undefined;
+    }
+}
 /**
  * Read one regular child file without following a symbolic link. State can sit
  * inside a cloned repository, so validating only the parent directory is not
  * enough: a committed child symlink must never expose an arbitrary local file.
  */
-export async function readSafeStateText(stateDir, fileName) {
+export async function readSafeStateText(stateDir, fileName, options = {}) {
     const filePath = await resolveSafeStateChild(stateDir, fileName, false);
     let handle;
     try {
@@ -172,7 +305,34 @@ export async function readSafeStateText(stateDir, fileName) {
         if (!info.isFile()) {
             throw new UnsafeStateFileError(filePath, "the state entry is not a regular file");
         }
-        return await handle.readFile("utf8");
+        const maxBytes = options.maxBytes;
+        if (maxBytes === undefined)
+            return await handle.readFile("utf8");
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+            throw new RangeError("maxBytes must be a non-negative safe integer");
+        }
+        if (info.size > maxBytes) {
+            throw new UnsafeStateFileError(filePath, `the state entry exceeds ${maxBytes} bytes`);
+        }
+        // Never use readFile for attacker-authored bounded state: a same-inode
+        // growth race could otherwise allocate the new whole size after fstat.
+        const buffer = Buffer.alloc(Math.min(maxBytes + 1, Math.max(1, info.size + 1)));
+        let offset = 0;
+        while (offset < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        const after = await handle.stat();
+        if (offset > maxBytes || after.size > maxBytes) {
+            throw new UnsafeStateFileError(filePath, `the state entry exceeds ${maxBytes} bytes`);
+        }
+        if (after.size !== info.size || after.mtimeMs !== info.mtimeMs ||
+            after.ctimeMs !== info.ctimeMs) {
+            throw new UnsafeStateFileError(filePath, "the state entry changed while it was read");
+        }
+        return buffer.subarray(0, offset).toString("utf8");
     }
     catch (error) {
         if (isNodeError(error, "ELOOP")) {

package/dist/schema.d.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
 export declare const costConfidenceValues: readonly ["verified", "estimated", "detected_unverified", "missing"];
 export declare const costConfidenceSchema: z.ZodEnum<{
-    verified: "verified";
     estimated: "estimated";
+    verified: "verified";
     detected_unverified: "detected_unverified";
     missing: "missing";
 }>;
@@ -12,12 +12,13 @@ export declare const spendSourceSchema: z.ZodObject<{
     name: z.ZodString;
     provider: z.ZodString;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
     observedFrom: z.ZodString;
+    account: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SpendSource = z.infer<typeof spendSourceSchema>;
 /**
@@ -30,9 +31,9 @@ export type SpendSource = z.infer<typeof spendSourceSchema>;
  */
 export declare const usageGranularityValues: readonly ["call", "invocation", "session", "daily_aggregate", "usage_bucket", "billing_bucket", "seat", "user_aggregate"];
 export declare const usageGranularitySchema: z.ZodEnum<{
+    session: "session";
     call: "call";
     invocation: "invocation";
-    session: "session";
     daily_aggregate: "daily_aggregate";
     usage_bucket: "usage_bucket";
     billing_bucket: "billing_bucket";
@@ -59,12 +60,13 @@ export declare const usageRecordSchema: z.ZodObject<{
         name: z.ZodString;
         provider: z.ZodString;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
         observedFrom: z.ZodString;
+        account: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     model: z.ZodString;
     inputTokens: z.ZodNumber;
@@ -89,8 +91,8 @@ export declare const usageRecordSchema: z.ZodObject<{
     sourceVersions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     amountUsd: z.ZodNullable<z.ZodNumber>;
     costConfidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -104,9 +106,9 @@ export declare const usageRecordSchema: z.ZodObject<{
     agentId: z.ZodOptional<z.ZodString>;
     operation: z.ZodOptional<z.ZodString>;
     usageGranularity: z.ZodOptional<z.ZodEnum<{
+        session: "session";
         call: "call";
         invocation: "invocation";
-        session: "session";
         daily_aggregate: "daily_aggregate";
         usage_bucket: "usage_bucket";
         billing_bucket: "billing_bucket";
@@ -152,10 +154,10 @@ export declare function downgradeSampleUsageEvidence(records: UsageRecord[]): Us
 export declare function spendComparisonKey(record: UsageRecord): string | undefined;
 export declare const attributionCandidateSchema: z.ZodObject<{
     entityType: z.ZodEnum<{
-        client: "client";
+        user: "user";
         project: "project";
         agent: "agent";
-        user: "user";
+        client: "client";
         workspace: "workspace";
         api_key: "api_key";
     }>;
@@ -168,10 +170,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
     usageRecordId: z.ZodString;
     candidates: z.ZodArray<z.ZodObject<{
         entityType: z.ZodEnum<{
-            client: "client";
+            user: "user";
             project: "project";
             agent: "agent";
-            user: "user";
+            client: "client";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -181,10 +183,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
     }, z.core.$strip>>;
     selected: z.ZodOptional<z.ZodObject<{
         entityType: z.ZodEnum<{
-            client: "client";
+            user: "user";
             project: "project";
             agent: "agent";
-            user: "user";
+            client: "client";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -206,8 +208,8 @@ export declare const spendBreakdownEntrySchema: z.ZodObject<{
     amountUsd: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -224,8 +226,8 @@ export declare const spendAnomalySchema: z.ZodObject<{
     currentAmountUsd: z.ZodNumber;
     multiplier: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -241,8 +243,8 @@ export declare const workflowWatchEntrySchema: z.ZodObject<{
     shareOfSpend: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -266,8 +268,8 @@ export declare const recommendationSchema: z.ZodObject<{
     }>;
     estimatedImpactUsd: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -311,8 +313,8 @@ export declare const spendInsightSchema: z.ZodObject<{
     affectedModels: z.ZodArray<z.ZodString>;
     estimatedImpactUsd: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -324,14 +326,14 @@ export declare const spendSummarySchema: z.ZodObject<{
     totalUsd: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
     confidenceBreakdown: z.ZodRecord<z.ZodEnum<{
-        verified: "verified";
         estimated: "estimated";
+        verified: "verified";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>, z.ZodNumber>;
@@ -340,8 +342,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -351,8 +353,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -362,8 +364,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -373,8 +375,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -384,8 +386,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -395,8 +397,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -406,8 +408,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -417,8 +419,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -433,8 +435,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         shareOfSpend: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -455,8 +457,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         currentAmountUsd: z.ZodNumber;
         multiplier: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -474,8 +476,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         }>;
         estimatedImpactUsd: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -512,8 +514,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         affectedModels: z.ZodArray<z.ZodString>;
         estimatedImpactUsd: z.ZodNumber;
         confidence: z.ZodEnum<{
-            verified: "verified";
             estimated: "estimated";
+            verified: "verified";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;

package/dist/schema.js

@@ -11,7 +11,15 @@ export const spendSourceSchema = z.object({
     name: z.string().min(1),
     provider: z.string().min(1),
     confidence: costConfidenceSchema,
-    observedFrom: z.string().min(1)
+    observedFrom: z.string().min(1),
+    /**
+     * Stable per-account identity within one provider (an organization, team,
+     * or enterprise slice). Derived from the user-chosen credential reference
+     * or an explicit --org/--enterprise/--account-id flag — never from secret
+     * material. Absent on local-agent records and on provider records synced
+     * before multi-account support (treated as one unnamed legacy slice).
+     */
+    account: z.string().min(1).optional()
 });
 /**
  * What one normalized usage record represents.