@agent-finops/core 0.8.1 → 0.9.0

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,8 +12,8 @@ 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";
     }>;
@@ -30,9 +30,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,8 +59,8 @@ 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";
         }>;
@@ -89,8 +89,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 +104,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 +152,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 +168,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 +181,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 +206,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 +224,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 +241,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 +266,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 +311,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 +324,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 +340,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 +351,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 +362,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 +373,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 +384,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 +395,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 +406,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 +417,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 +433,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 +455,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 +474,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 +512,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/sessionVitals.d.ts

@@ -0,0 +1,145 @@
+import { type LocalAgentActivity, type LocalAgentCall, type LocalAgentRateLimitWindow, type LocalAgentTurnUsage } from "./localAgentLogs.js";
+/**
+ * Additive, privacy-reduced session evidence for future before/after tests.
+ *
+ * V0 deliberately accepts already-parsed LocalAgentCall values rather than
+ * reading transcripts itself. It never carries prompts, responses, absolute
+ * paths, filenames, or raw provider session identifiers.
+ */
+export type SessionVitalsAgentV0 = "claude-code" | "codex";
+export type SessionVitalsTokenEvidenceV0 = {
+    status: "observed";
+    basis: "turn_sum" | "session_cumulative";
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWrite5mTokens?: number;
+    cacheWrite1hTokens?: number;
+    thoughtTokens?: number;
+    toolTokens?: number;
+    componentTotalTokens: number;
+    reportedTotalTokens?: number;
+    componentEvidence: {
+        inputTokens: "observed";
+        outputTokens: "observed";
+        cacheReadTokens: "observed" | "not_separately_reported";
+        cacheWriteTokens: "observed" | "partial" | "not_separately_reported";
+        thoughtTokens: "observed" | "not_separately_reported";
+        toolTokens: "observed" | "not_separately_reported";
+        componentTotalTokens: "calculated_complete" | "calculated_partial";
+        reportedTotalTokens: "provider_reported" | "not_reported";
+    };
+} | {
+    status: "missing";
+    reason: "unsupported_token_shape" | "mixed_usage_scope" | "invalid_token_evidence";
+};
+export type SessionVitalsLatestTurnV0 = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWrite5mTokens?: number;
+    cacheWrite1hTokens?: number;
+    thoughtTokens?: number;
+    toolTokens?: number;
+    contextTokens: number;
+    totalTokens: number;
+    source: LocalAgentTurnUsage["source"];
+};
+export type SessionVitalsRateLimitWindowV0 = {
+    kind: LocalAgentRateLimitWindow["kind"];
+    name: string;
+    usedPercent: number;
+    windowMinutes: number;
+    resetsAt: string;
+};
+export type SessionVitalsCompletionV0 = {
+    status: "completed";
+    /**
+     * A completed session snapshot, not permanent transcript closure.
+     * `claude_task_result` is the host-recorded Task tool result
+     * (`status: "completed"`) written into the owning transcript when a
+     * subagent run finishes — the only explicit completion marker Claude
+     * Code produces for subagent transcript files.
+     */
+    evidence: "claude_turn_duration" | "codex_task_complete" | "claude_task_result";
+    observedAt: string;
+} | {
+    status: "missing";
+    evidence: "missing";
+    reason: "completion_marker_not_observed" | "inconsistent_completion_evidence";
+};
+export type SessionVitalV0 = {
+    /** Stable AV-compatible pseudonym. The raw transcript session id is never returned. */
+    sessionRef: string;
+    /**
+     * Pseudonym of the owning parent session, present only on rows split out of
+     * a shared-sessionId subagent transcript. Matches the parent row's
+     * `sessionRef`; raw identifiers are never returned.
+     */
+    parentSessionRef?: string;
+    agent: SessionVitalsAgentV0;
+    /** Unknown remains ineligible for automatic before/after cohort matching. */
+    sessionType: "parent" | "subagent" | "unknown";
+    /** Existing privacy-reduced project label; paths and suspicious values are omitted. */
+    project?: string;
+    /** Stable opaque identity derived from one consistent native working directory. */
+    projectRef?: string;
+    models: string[];
+    /** Empty means the parser did not report a safe version; never inferred. */
+    sourceVersions: string[];
+    observedFrom: string;
+    observedTo: string;
+    /** Omitted unless a distinct, valid start and end are present. */
+    observedDurationMs?: number;
+    /** Explicit host completion boundary for this snapshot; inactivity is never treated as completion. */
+    completion: SessionVitalsCompletionV0;
+    tokenEvidence: SessionVitalsTokenEvidenceV0;
+    latestTurn?: SessionVitalsLatestTurnV0;
+    activity?: {
+        kind: LocalAgentActivity["kind"];
+        action: LocalAgentActivity["action"];
+        promptCount: number;
+        toolCallCount: number;
+    };
+    rateLimits?: {
+        observedAt: string;
+        planType?: string;
+        windows: SessionVitalsRateLimitWindowV0[];
+    };
+    provenance: {
+        source: "parsed_local_agent_calls";
+        confidence: "observed";
+        uploaded: false;
+    };
+};
+export type SessionVitalsV0 = {
+    schemaVersion: 0;
+    sessions: SessionVitalV0[];
+    coverage: {
+        inputCalls: number;
+        deduplicatedCalls: number;
+        eligibleCalls: number;
+        emittedSessions: number;
+        sessionsWithObservedTokens: number;
+        sessionsWithMissingTokens: number;
+        excludedCalls: {
+            unsupportedAgent: number;
+            missingSessionIdentity: number;
+            invalidTimestamp: number;
+        };
+    };
+    privacy: {
+        rawSessionIds: false;
+        promptOrResponseText: false;
+        absolutePaths: false;
+        uploaded: false;
+    };
+};
+/**
+ * Build one deterministic V0 row per Claude Code or Codex session.
+ *
+ * Token evidence fails closed at the session boundary: one unsupported,
+ * invalid, or mixed-scope call prevents a partial sum from looking complete.
+ */
+export declare function extractSessionVitalsV0(calls: readonly LocalAgentCall[]): SessionVitalsV0;
+//# sourceMappingURL=sessionVitals.d.ts.map