@agent-finops/core 0.8.1 → 0.9.1

package/dist/qualitativeIndexCache.d.ts

@@ -0,0 +1,494 @@
+import { z } from "zod";
+import type { LocalAgentQualitativeIndexAdapter, LocalAgentQualitativeIndexValue } from "./localAgentLogs.js";
+export declare const qualitativeIndexCacheEnvironmentVariable = "AIBILL_CACHE_DIR";
+export declare const qualitativeIndexCacheFileName = "qualitative-index-v1.json";
+export declare const qualitativeIndexCacheLockFileName = ".qualitative-index-v1.lock";
+export declare const qualitativeIndexCacheMaxBytes: number;
+export declare const qualitativeIndexCacheMaxEntryBytes: number;
+export declare const qualitativeIndexCacheMaxEntries = 256;
+/**
+ * Storage options for the private warm index. The limit overrides exist for
+ * tests and constrained embeddings and can only make the fixed production
+ * bounds smaller.
+ */
+export type QualitativeIndexCacheOptions = {
+    cacheDirectory?: string;
+    homeDirectory?: string;
+    lockTimeoutMs?: number;
+    maxBytes?: number;
+    maxEntryBytes?: number;
+    maxEntries?: number;
+};
+export declare class QualitativeIndexCacheError extends Error {
+    readonly code: "unsafe_directory" | "unsafe_file" | "oversized" | "malformed" | "unsupported_version" | "permission" | "lock_timeout" | "invalid_key" | "invalid_value" | "io";
+    constructor(code: QualitativeIndexCacheError["code"], message: string);
+}
+declare const keySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    parserVersion: z.ZodLiteral<4>;
+    agent: z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+    }>;
+    pathHash: z.ZodString;
+    fileIdentity: z.ZodString;
+    sinceIso: z.ZodNullable<z.ZodString>;
+    collectInvocationEvidence: z.ZodBoolean;
+}, z.core.$strict>;
+declare const valueSchema: z.ZodObject<{
+    calls: z.ZodArray<z.ZodObject<{
+        agent: z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+        }>;
+        callId: z.ZodOptional<z.ZodString>;
+        model: z.ZodString;
+        timestamp: z.ZodString;
+        startedAt: z.ZodOptional<z.ZodString>;
+        project: z.ZodOptional<z.ZodString>;
+        workingDirectoryRef: z.ZodOptional<z.ZodString>;
+        latestTurnUsage: z.ZodOptional<z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+            cacheWrite5mTokens: z.ZodOptional<z.ZodNumber>;
+            cacheWrite1hTokens: z.ZodOptional<z.ZodNumber>;
+            thoughtTokens: z.ZodOptional<z.ZodNumber>;
+            toolTokens: z.ZodOptional<z.ZodNumber>;
+            contextTokens: z.ZodNumber;
+            totalTokens: z.ZodNumber;
+            source: z.ZodEnum<{
+                assistant_message_usage: "assistant_message_usage";
+                transcript_last_token_usage: "transcript_last_token_usage";
+                call_usage: "call_usage";
+            }>;
+        }, z.core.$strict>>;
+        usageScope: z.ZodOptional<z.ZodEnum<{
+            turn: "turn";
+            session_cumulative: "session_cumulative";
+        }>>;
+        usageSupport: z.ZodOptional<z.ZodEnum<{
+            complete: "complete";
+            unsupported_token_shape: "unsupported_token_shape";
+        }>>;
+        reportedTotalTokens: z.ZodOptional<z.ZodNumber>;
+        tokenComponentEvidence: z.ZodOptional<z.ZodObject<{
+            inputTokens: z.ZodLiteral<"observed">;
+            outputTokens: z.ZodLiteral<"observed">;
+            cacheReadTokens: z.ZodEnum<{
+                observed: "observed";
+                not_separately_reported: "not_separately_reported";
+            }>;
+            cacheWriteTokens: z.ZodEnum<{
+                observed: "observed";
+                not_separately_reported: "not_separately_reported";
+                partial: "partial";
+            }>;
+            thoughtTokens: z.ZodEnum<{
+                observed: "observed";
+                not_separately_reported: "not_separately_reported";
+            }>;
+            toolTokens: z.ZodEnum<{
+                observed: "observed";
+                not_separately_reported: "not_separately_reported";
+            }>;
+            calculatedTotalTokens: z.ZodEnum<{
+                calculated_complete: "calculated_complete";
+                calculated_partial: "calculated_partial";
+            }>;
+            reportedTotalTokens: z.ZodEnum<{
+                provider_reported: "provider_reported";
+                not_reported: "not_reported";
+            }>;
+        }, z.core.$strict>>;
+        sourceVersion: z.ZodOptional<z.ZodString>;
+        completion: z.ZodOptional<z.ZodObject<{
+            status: z.ZodLiteral<"completed">;
+            evidence: z.ZodEnum<{
+                claude_turn_duration: "claude_turn_duration";
+                codex_task_complete: "codex_task_complete";
+            }>;
+            observedAt: z.ZodString;
+        }, z.core.$strict>>;
+        geminiTokenEvidence: z.ZodOptional<z.ZodObject<{
+            input: z.ZodOptional<z.ZodNumber>;
+            output: z.ZodOptional<z.ZodNumber>;
+            cached: z.ZodOptional<z.ZodNumber>;
+            thoughts: z.ZodOptional<z.ZodNumber>;
+            tool: z.ZodOptional<z.ZodNumber>;
+            total: z.ZodOptional<z.ZodNumber>;
+            cacheAccounting: z.ZodEnum<{
+                unknown: "unknown";
+                included: "included";
+                none: "none";
+            }>;
+        }, z.core.$strict>>;
+        usage: z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+            cacheWrite5mTokens: z.ZodOptional<z.ZodNumber>;
+            cacheWrite1hTokens: z.ZodOptional<z.ZodNumber>;
+            thoughtTokens: z.ZodOptional<z.ZodNumber>;
+            toolTokens: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        subagentId: z.ZodOptional<z.ZodString>;
+        subagentCompletions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            subagentId: z.ZodString;
+            observedAt: z.ZodString;
+        }, z.core.$strict>>>;
+        rateLimits: z.ZodOptional<z.ZodObject<{
+            observedAt: z.ZodString;
+            limitId: z.ZodOptional<z.ZodString>;
+            planType: z.ZodOptional<z.ZodString>;
+            windows: z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    custom: "custom";
+                    "five-hour": "five-hour";
+                    weekly: "weekly";
+                }>;
+                name: z.ZodString;
+                usedPercent: z.ZodNumber;
+                windowMinutes: z.ZodNumber;
+                resetsAt: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        activity: z.ZodOptional<z.ZodObject<{
+            summary: z.ZodString;
+            kind: z.ZodEnum<{
+                project: "project";
+                agent: "agent";
+                file: "file";
+                task: "task";
+                automation: "automation";
+            }>;
+            action: z.ZodEnum<{
+                building: "building";
+                refining: "refining";
+                fixing: "fixing";
+                testing: "testing";
+                auditing: "auditing";
+                researching: "researching";
+                configuring: "configuring";
+                publishing: "publishing";
+                running: "running";
+                working: "working";
+            }>;
+            source: z.ZodEnum<{
+                project: "project";
+                agent_title: "agent_title";
+                user_prompts: "user_prompts";
+                file_activity: "file_activity";
+            }>;
+            promptCount: z.ZodNumber;
+            toolCallCount: z.ZodNumber;
+            files: z.ZodArray<z.ZodString>;
+            isSubagent: z.ZodBoolean;
+            parentSessionId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    invocationFile: z.ZodOptional<z.ZodObject<{
+        invocations: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$strict>>;
+        invokedMcpTools: z.ZodArray<z.ZodString>;
+        invokedSkills: z.ZodArray<z.ZodString>;
+        invokedSubagents: z.ZodArray<z.ZodString>;
+        invokedCommands: z.ZodArray<z.ZodString>;
+        assistantTurns: z.ZodNumber;
+        contextSignal: z.ZodObject<{
+            agent: z.ZodEnum<{
+                "claude-code": "claude-code";
+                codex: "codex";
+            }>;
+            sessionId: z.ZodOptional<z.ZodString>;
+            lastActivityAt: z.ZodOptional<z.ZodString>;
+            compactionEvents: z.ZodNumber;
+            fileReads: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                count: z.ZodNumber;
+            }, z.core.$strict>>;
+            repeatedFileReads: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                count: z.ZodNumber;
+            }, z.core.$strict>>;
+            isSubagent: z.ZodBoolean;
+            parentSessionId: z.ZodOptional<z.ZodString>;
+            nestedSessions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                sessionId: z.ZodOptional<z.ZodString>;
+                isSubagent: z.ZodBoolean;
+                parentSessionId: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+            readCoverage: z.ZodLiteral<"explicit_read_tools_only">;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    invocationWindowProof: z.ZodOptional<z.ZodObject<{
+        earliestCountedAt: z.ZodOptional<z.ZodString>;
+        allCountedEventsTimestamped: z.ZodBoolean;
+    }, z.core.$strict>>;
+    diagnostics: z.ZodArray<z.ZodObject<{
+        code: z.ZodEnum<{
+            unsupported_token_shape: "unsupported_token_shape";
+            malformed_jsonl: "malformed_jsonl";
+            malformed_session_file: "malformed_session_file";
+        }>;
+        count: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PersistedQualitativeKey = z.infer<typeof keySchema>;
+export type PersistedQualitativeValue = z.infer<typeof valueSchema>;
+type PersistedKey = PersistedQualitativeKey;
+type PersistedValue = PersistedQualitativeValue;
+/**
+ * Strict v1 entry contracts, exported for the v2 sharded project-index store.
+ * The v2 store persists the same privacy-reduced shapes under a different
+ * layout; sharing the schemas keeps the two stores provably consistent.
+ */
+export declare const qualitativeEntryKeySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    parserVersion: z.ZodLiteral<4>;
+    agent: z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+    }>;
+    pathHash: z.ZodString;
+    fileIdentity: z.ZodString;
+    sinceIso: z.ZodNullable<z.ZodString>;
+    collectInvocationEvidence: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const qualitativeEntryValueSchema: z.ZodObject<{
+    calls: z.ZodArray<z.ZodObject<{
+        agent: z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+        }>;
+        callId: z.ZodOptional<z.ZodString>;
+        model: z.ZodString;
+        timestamp: z.ZodString;
+        startedAt: z.ZodOptional<z.ZodString>;
+        project: z.ZodOptional<z.ZodString>;
+        workingDirectoryRef: z.ZodOptional<z.ZodString>;
+        latestTurnUsage: z.ZodOptional<z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+            cacheWrite5mTokens: z.ZodOptional<z.ZodNumber>;
+            cacheWrite1hTokens: z.ZodOptional<z.ZodNumber>;
+            thoughtTokens: z.ZodOptional<z.ZodNumber>;
+            toolTokens: z.ZodOptional<z.ZodNumber>;
+            contextTokens: z.ZodNumber;
+            totalTokens: z.ZodNumber;
+            source: z.ZodEnum<{
+                assistant_message_usage: "assistant_message_usage";
+                transcript_last_token_usage: "transcript_last_token_usage";
+                call_usage: "call_usage";
+            }>;
+        }, z.core.$strict>>;
+        usageScope: z.ZodOptional<z.ZodEnum<{
+            turn: "turn";
+            session_cumulative: "session_cumulative";
+        }>>;
+        usageSupport: z.ZodOptional<z.ZodEnum<{
+            complete: "complete";
+            unsupported_token_shape: "unsupported_token_shape";
+        }>>;
+        reportedTotalTokens: z.ZodOptional<z.ZodNumber>;
+        tokenComponentEvidence: z.ZodOptional<z.ZodObject<{
+            inputTokens: z.ZodLiteral<"observed">;
+            outputTokens: z.ZodLiteral<"observed">;
+            cacheReadTokens: z.ZodEnum<{
+                observed: "observed";
+                not_separately_reported: "not_separately_reported";
+            }>;
+            cacheWriteTokens: z.ZodEnum<{
+                observed: "observed";
+                not_separately_reported: "not_separately_reported";
+                partial: "partial";
+            }>;
+            thoughtTokens: z.ZodEnum<{
+                observed: "observed";
+                not_separately_reported: "not_separately_reported";
+            }>;
+            toolTokens: z.ZodEnum<{
+                observed: "observed";
+                not_separately_reported: "not_separately_reported";
+            }>;
+            calculatedTotalTokens: z.ZodEnum<{
+                calculated_complete: "calculated_complete";
+                calculated_partial: "calculated_partial";
+            }>;
+            reportedTotalTokens: z.ZodEnum<{
+                provider_reported: "provider_reported";
+                not_reported: "not_reported";
+            }>;
+        }, z.core.$strict>>;
+        sourceVersion: z.ZodOptional<z.ZodString>;
+        completion: z.ZodOptional<z.ZodObject<{
+            status: z.ZodLiteral<"completed">;
+            evidence: z.ZodEnum<{
+                claude_turn_duration: "claude_turn_duration";
+                codex_task_complete: "codex_task_complete";
+            }>;
+            observedAt: z.ZodString;
+        }, z.core.$strict>>;
+        geminiTokenEvidence: z.ZodOptional<z.ZodObject<{
+            input: z.ZodOptional<z.ZodNumber>;
+            output: z.ZodOptional<z.ZodNumber>;
+            cached: z.ZodOptional<z.ZodNumber>;
+            thoughts: z.ZodOptional<z.ZodNumber>;
+            tool: z.ZodOptional<z.ZodNumber>;
+            total: z.ZodOptional<z.ZodNumber>;
+            cacheAccounting: z.ZodEnum<{
+                unknown: "unknown";
+                included: "included";
+                none: "none";
+            }>;
+        }, z.core.$strict>>;
+        usage: z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+            cacheWrite5mTokens: z.ZodOptional<z.ZodNumber>;
+            cacheWrite1hTokens: z.ZodOptional<z.ZodNumber>;
+            thoughtTokens: z.ZodOptional<z.ZodNumber>;
+            toolTokens: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        subagentId: z.ZodOptional<z.ZodString>;
+        subagentCompletions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            subagentId: z.ZodString;
+            observedAt: z.ZodString;
+        }, z.core.$strict>>>;
+        rateLimits: z.ZodOptional<z.ZodObject<{
+            observedAt: z.ZodString;
+            limitId: z.ZodOptional<z.ZodString>;
+            planType: z.ZodOptional<z.ZodString>;
+            windows: z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    custom: "custom";
+                    "five-hour": "five-hour";
+                    weekly: "weekly";
+                }>;
+                name: z.ZodString;
+                usedPercent: z.ZodNumber;
+                windowMinutes: z.ZodNumber;
+                resetsAt: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        activity: z.ZodOptional<z.ZodObject<{
+            summary: z.ZodString;
+            kind: z.ZodEnum<{
+                project: "project";
+                agent: "agent";
+                file: "file";
+                task: "task";
+                automation: "automation";
+            }>;
+            action: z.ZodEnum<{
+                building: "building";
+                refining: "refining";
+                fixing: "fixing";
+                testing: "testing";
+                auditing: "auditing";
+                researching: "researching";
+                configuring: "configuring";
+                publishing: "publishing";
+                running: "running";
+                working: "working";
+            }>;
+            source: z.ZodEnum<{
+                project: "project";
+                agent_title: "agent_title";
+                user_prompts: "user_prompts";
+                file_activity: "file_activity";
+            }>;
+            promptCount: z.ZodNumber;
+            toolCallCount: z.ZodNumber;
+            files: z.ZodArray<z.ZodString>;
+            isSubagent: z.ZodBoolean;
+            parentSessionId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    invocationFile: z.ZodOptional<z.ZodObject<{
+        invocations: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$strict>>;
+        invokedMcpTools: z.ZodArray<z.ZodString>;
+        invokedSkills: z.ZodArray<z.ZodString>;
+        invokedSubagents: z.ZodArray<z.ZodString>;
+        invokedCommands: z.ZodArray<z.ZodString>;
+        assistantTurns: z.ZodNumber;
+        contextSignal: z.ZodObject<{
+            agent: z.ZodEnum<{
+                "claude-code": "claude-code";
+                codex: "codex";
+            }>;
+            sessionId: z.ZodOptional<z.ZodString>;
+            lastActivityAt: z.ZodOptional<z.ZodString>;
+            compactionEvents: z.ZodNumber;
+            fileReads: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                count: z.ZodNumber;
+            }, z.core.$strict>>;
+            repeatedFileReads: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                count: z.ZodNumber;
+            }, z.core.$strict>>;
+            isSubagent: z.ZodBoolean;
+            parentSessionId: z.ZodOptional<z.ZodString>;
+            nestedSessions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                sessionId: z.ZodOptional<z.ZodString>;
+                isSubagent: z.ZodBoolean;
+                parentSessionId: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+            readCoverage: z.ZodLiteral<"explicit_read_tools_only">;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    invocationWindowProof: z.ZodOptional<z.ZodObject<{
+        earliestCountedAt: z.ZodOptional<z.ZodString>;
+        allCountedEventsTimestamped: z.ZodBoolean;
+    }, z.core.$strict>>;
+    diagnostics: z.ZodArray<z.ZodObject<{
+        code: z.ZodEnum<{
+            unsupported_token_shape: "unsupported_token_shape";
+            malformed_jsonl: "malformed_jsonl";
+            malformed_session_file: "malformed_session_file";
+        }>;
+        count: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Resolve the fixed warm-index path without trusting or creating it. */
+export declare function qualitativeIndexCachePath(options?: QualitativeIndexCacheOptions): string;
+/**
+ * Build the adapter consumed by `loadLocalAgentUsage({ qualitativeIndex })`.
+ * Reads fail closed and writes are serialized, atomic, private, and bounded.
+ */
+export declare function createQualitativeIndexCacheAdapter(options?: QualitativeIndexCacheOptions): LocalAgentQualitativeIndexAdapter;
+export declare function withWriterLock<T>(options: QualitativeIndexCacheOptions, operation: (directory: string) => Promise<T>, lockFileName?: string): Promise<T>;
+export declare function resolveCacheDirectory(create: boolean, options: QualitativeIndexCacheOptions): Promise<string>;
+export declare function syncDirectory(directory: string): Promise<void>;
+export declare function stripRawPaths(value: Readonly<LocalAgentQualitativeIndexValue>): unknown;
+export declare function qualitativeKeyFingerprint(key: PersistedQualitativeKey): string;
+export declare function sameQualitativeFileKey(left: PersistedKey, right: PersistedKey): boolean;
+/** Whether the cached parser window is an exact superset of the request. */
+export declare function cachedWindowCoversRequest(cachedSinceIso: string | null, requestedSinceIso: string | null): boolean;
+/**
+ * Calls remain exact after the loader's timestamp filter. Aggregated Codex
+ * invocation evidence cannot generally be subtracted at a later cutoff, so a
+ * cross-window hit is allowed only when the root session started inside the
+ * requested window (all counted root events are therefore in-window), or the
+ * wider cached window observed no countable invocation evidence at all.
+ */
+export declare function invocationWindowCanBeNarrowedExactly(cachedKey: PersistedKey, value: PersistedValue, requestedKey: PersistedKey): boolean;
+export declare function noFollowFlag(): number;
+export declare function hasPrivatePermissions(mode: number): boolean;
+export declare function isNodeError(error: unknown, code: string): error is NodeJS.ErrnoException;
+export {};
+//# sourceMappingURL=qualitativeIndexCache.d.ts.map