@agent-finops/core 0.8.1 → 0.9.1

package/dist/toolInvocations.d.ts

@@ -100,6 +100,11 @@ export type ParsedInvocationFile = {
     assistantTurns: number;
     contextSignal: SessionContextSignal;
 };
+/** Private-index proof used to narrow one aggregated Codex window exactly. */
+export type ParsedInvocationWindowProof = {
+    earliestCountedAt?: string;
+    allCountedEventsTimestamped: boolean;
+};
 export type ToolInvocationOptions = {
     /** default: join(homedir(), ".claude", "projects") */
     claudeProjectsDir?: string;
@@ -118,13 +123,47 @@ export type ToolInvocationOptions = {
 export declare function parseClaudeCodeInvocations(content: string, sinceMs?: number): ParsedInvocationFile;
 /** Parse ONE Codex rollout's tool/skill/subagent invocations. */
 export declare function parseCodexInvocations(content: string, sinceMs?: number): ParsedInvocationFile;
+/**
+ * Serializable snapshot of one Codex invocation collector, used by the
+ * checkpointed streaming path to carry aggregation across bounded runs. It
+ * contains only what the finished summary itself persists — tool/skill/
+ * command names, file basenames, opaque session ids, counters and window
+ * proof timestamps — never raw transcript text or absolute paths.
+ */
+export type CodexInvocationCollectorSnapshot = {
+    counts: Array<[string, number]>;
+    mcpTools: string[];
+    skills: string[];
+    subagents: string[];
+    commands: string[];
+    fileReads: Array<[string, number]>;
+    assistantTurns: number;
+    sessionId?: string;
+    rootSessionMetaSeen: boolean;
+    rootStartedAtMs?: number;
+    rootTaskStarted: boolean;
+    lastActivityAt?: string;
+    compactionEvents: number;
+    isSubagent: boolean;
+    parentSessionId?: string;
+    nestedSessions: Array<[string, NestedSessionMetadata]>;
+    earliestCountedMs?: number;
+    allCountedEventsTimestamped: boolean;
+};
+/** Fail-closed structural check for a restored collector snapshot. */
+export declare function isCodexInvocationCollectorSnapshot(value: unknown): value is CodexInvocationCollectorSnapshot;
 /**
  * Stateful Codex invocation parser used to share localAgentLogs' JSONL pass.
  * One collector is created per rollout file and discarded after `finish()`.
+ * A checkpointed stream restores a prior run's snapshot; the window (sinceMs)
+ * must be the one the snapshot was created under — the caller pins it in the
+ * checkpoint envelope.
  */
-export declare function createCodexInvocationCollector(sinceMs?: number): {
+export declare function createCodexInvocationCollector(sinceMs?: number, restored?: CodexInvocationCollectorSnapshot): {
     consume: (entry: Record<string, unknown>) => void;
     finish: () => ParsedInvocationFile;
+    windowProof: () => ParsedInvocationWindowProof;
+    snapshot: () => CodexInvocationCollectorSnapshot;
 };
 /** Scan this machine's Claude Code + Codex transcripts and aggregate invocations. */
 export declare function loadToolInvocations(options?: ToolInvocationOptions): Promise<InvocationSummary>;

package/dist/toolInvocations.js

@@ -132,27 +132,64 @@ export function parseCodexInvocations(content, sinceMs) {
     }
     return collector.finish();
 }
+/** Fail-closed structural check for a restored collector snapshot. */
+export function isCodexInvocationCollectorSnapshot(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    const stringNumberPairs = (input) => (Array.isArray(input) && input.every((pair) => (Array.isArray(pair) && pair.length === 2 &&
+        typeof pair[0] === "string" &&
+        Number.isSafeInteger(pair[1]) && Number(pair[1]) >= 0)));
+    const stringArray = (input) => (Array.isArray(input) && input.every((item) => typeof item === "string"));
+    const optionalString = (input) => (input === undefined || typeof input === "string");
+    const optionalFinite = (input) => (input === undefined || typeof input === "number" && Number.isFinite(input));
+    return stringNumberPairs(record.counts) &&
+        stringArray(record.mcpTools) &&
+        stringArray(record.skills) &&
+        stringArray(record.subagents) &&
+        stringArray(record.commands) &&
+        stringNumberPairs(record.fileReads) &&
+        Number.isSafeInteger(record.assistantTurns) && Number(record.assistantTurns) >= 0 &&
+        optionalString(record.sessionId) &&
+        typeof record.rootSessionMetaSeen === "boolean" &&
+        optionalFinite(record.rootStartedAtMs) &&
+        typeof record.rootTaskStarted === "boolean" &&
+        optionalString(record.lastActivityAt) &&
+        Number.isSafeInteger(record.compactionEvents) && Number(record.compactionEvents) >= 0 &&
+        typeof record.isSubagent === "boolean" &&
+        optionalString(record.parentSessionId) &&
+        Array.isArray(record.nestedSessions) && record.nestedSessions.every((pair) => (Array.isArray(pair) && pair.length === 2 && typeof pair[0] === "string" &&
+        typeof pair[1] === "object" && pair[1] !== null &&
+        typeof pair[1].isSubagent === "boolean")) &&
+        optionalFinite(record.earliestCountedMs) &&
+        typeof record.allCountedEventsTimestamped === "boolean";
+}
 /**
  * Stateful Codex invocation parser used to share localAgentLogs' JSONL pass.
  * One collector is created per rollout file and discarded after `finish()`.
+ * A checkpointed stream restores a prior run's snapshot; the window (sinceMs)
+ * must be the one the snapshot was created under — the caller pins it in the
+ * checkpoint envelope.
  */
-export function createCodexInvocationCollector(sinceMs) {
-    const counts = new Map();
-    const mcpTools = new Set();
-    const skills = new Set();
-    const subagents = new Set();
-    const commands = new Set();
-    const fileReads = new Map();
-    let assistantTurns = 0;
-    let sessionId;
-    let rootSessionMetaSeen = false;
-    let rootStartedAtMs;
-    let rootTaskStarted = false;
-    let lastActivityAt;
-    let compactionEvents = 0;
-    let isSubagent = false;
-    let parentSessionId;
-    const nestedSessions = new Map();
+export function createCodexInvocationCollector(sinceMs, restored) {
+    const counts = new Map(restored?.counts ?? []);
+    const mcpTools = new Set(restored?.mcpTools ?? []);
+    const skills = new Set(restored?.skills ?? []);
+    const subagents = new Set(restored?.subagents ?? []);
+    const commands = new Set(restored?.commands ?? []);
+    const fileReads = new Map(restored?.fileReads ?? []);
+    let assistantTurns = restored?.assistantTurns ?? 0;
+    let sessionId = restored?.sessionId;
+    let rootSessionMetaSeen = restored?.rootSessionMetaSeen ?? false;
+    let rootStartedAtMs = restored?.rootStartedAtMs;
+    let rootTaskStarted = restored?.rootTaskStarted ?? false;
+    let lastActivityAt = restored?.lastActivityAt;
+    let compactionEvents = restored?.compactionEvents ?? 0;
+    let isSubagent = restored?.isSubagent ?? false;
+    let parentSessionId = restored?.parentSessionId;
+    const nestedSessions = new Map(restored?.nestedSessions ?? []);
+    let earliestCountedMs = restored?.earliestCountedMs;
+    let allCountedEventsTimestamped = restored?.allCountedEventsTimestamped ?? true;
     const resetObservedEvidence = () => {
         counts.clear();
         mcpTools.clear();
@@ -162,6 +199,18 @@ export function createCodexInvocationCollector(sinceMs) {
         fileReads.clear();
         assistantTurns = 0;
         compactionEvents = 0;
+        earliestCountedMs = undefined;
+        allCountedEventsTimestamped = true;
+    };
+    const recordCountedTimestamp = (entry) => {
+        const timestamp = Date.parse(stringOf(entry.timestamp) ?? "");
+        if (!Number.isFinite(timestamp)) {
+            allCountedEventsTimestamped = false;
+            return;
+        }
+        earliestCountedMs = earliestCountedMs === undefined
+            ? timestamp
+            : Math.min(earliestCountedMs, timestamp);
     };
     const consume = (entry) => {
         const payload = isRecord(entry.payload) ? entry.payload : undefined;
@@ -211,18 +260,23 @@ export function createCodexInvocationCollector(sinceMs) {
             return;
         // Codex writes both a top-level `compacted` entry and a separate
         // `context_compacted` event for one compaction. Count only the former.
-        if (entry.type === "compacted")
+        if (entry.type === "compacted") {
             compactionEvents += 1;
+            recordCountedTimestamp(entry);
+        }
         // Codex emits one turn_context per model turn.
         if (entry.type === "turn_context") {
             assistantTurns += 1;
+            recordCountedTimestamp(entry);
             return;
         }
         if (payload.type === "message" && payload.role === "user") {
             for (const text of codexTextValues(payload.content)) {
                 const command = /^\s*\/([A-Za-z0-9:_-]+)/.exec(text)?.[1];
-                if (command)
+                if (command) {
                     commands.add(command);
+                    recordCountedTimestamp(entry);
+                }
             }
             return;
         }
@@ -233,6 +287,7 @@ export function createCodexInvocationCollector(sinceMs) {
         if (!name)
             return;
         counts.set(name, (counts.get(name) ?? 0) + 1);
+        recordCountedTimestamp(entry);
         const input = codexToolInput(payload);
         if (name.startsWith("mcp__")) {
             mcpTools.add(name);
@@ -280,7 +335,33 @@ export function createCodexInvocationCollector(sinceMs) {
             })
         };
     };
-    return { consume, finish };
+    const windowProof = () => ({
+        ...(earliestCountedMs === undefined
+            ? {}
+            : { earliestCountedAt: new Date(earliestCountedMs).toISOString() }),
+        allCountedEventsTimestamped
+    });
+    const snapshot = () => ({
+        counts: [...counts.entries()],
+        mcpTools: [...mcpTools],
+        skills: [...skills],
+        subagents: [...subagents],
+        commands: [...commands],
+        fileReads: [...fileReads.entries()],
+        assistantTurns,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        rootSessionMetaSeen,
+        ...(rootStartedAtMs !== undefined ? { rootStartedAtMs } : {}),
+        rootTaskStarted,
+        ...(lastActivityAt !== undefined ? { lastActivityAt } : {}),
+        compactionEvents,
+        isSubagent,
+        ...(parentSessionId !== undefined ? { parentSessionId } : {}),
+        nestedSessions: [...nestedSessions.entries()],
+        ...(earliestCountedMs !== undefined ? { earliestCountedMs } : {}),
+        allCountedEventsTimestamped
+    });
+    return { consume, finish, windowProof, snapshot };
 }
 /** Scan this machine's Claude Code + Codex transcripts and aggregate invocations. */
 export async function loadToolInvocations(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-finops/core",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",