@agent-finops/core 0.8.1 → 0.9.0

package/dist/localAgentLogs.d.ts

@@ -1,6 +1,6 @@
 import { type TokenUsage } from "./modelPricing.js";
 import type { UsageRecord } from "./schema.js";
-import type { ParsedInvocationFile } from "./toolInvocations.js";
+import { type ParsedInvocationFile, type ParsedInvocationWindowProof } from "./toolInvocations.js";
 import type { LocalAgentFormatDescriptor, LocalAgentFormatFinancialFileContext, LocalAgentFormatId, LocalAgentFormatRuntime } from "./localAgentFormats/types.js";
 /**
  * Local agent-session log ingestion: turns the transcript files that coding
@@ -35,6 +35,11 @@ export type LocalAgentCall = {
      * reads to the same repository as the active session.
      */
     workingDirectory?: string;
+    /**
+     * Stable privacy-safe identity for `workingDirectory`. Warm indexes retain
+     * this opaque reference while deliberately omitting the absolute path.
+     */
+    workingDirectoryRef?: string;
     /**
      * Numeric-only usage for the latest observed model turn. Codex reports this
      * separately from cumulative `total_token_usage`; Claude assistant-message
@@ -52,8 +57,21 @@ export type LocalAgentCall = {
     usageSupport?: "complete" | "unsupported_token_shape";
     /** Provider-reported total retained when component fields are unavailable. */
     reportedTotalTokens?: number;
+    /**
+     * Parser evidence for whether each disjoint token component was actually
+     * present in the source. Numeric zeroes alone cannot distinguish a reported
+     * zero from a field that the parser had to omit/default.
+     */
+    tokenComponentEvidence?: LocalAgentTokenComponentEvidence;
     /** Optional parser/source version when the evolving session format reports it. */
     sourceVersion?: string;
+    /**
+     * Explicit host completion evidence for the current session snapshot. This proves only that the
+     * latest observed Claude turn or Codex task reached its host completion
+     * marker; it does not claim that a resumable transcript is permanently
+     * closed.
+     */
+    completion?: LocalAgentCompletionEvidence;
     /** Raw Gemini token split retained for evidence/debugging, never prompt content. */
     geminiTokenEvidence?: {
         input?: number;
@@ -66,6 +84,24 @@ export type LocalAgentCall = {
     };
     usage: TokenUsage;
     sessionId?: string;
+    /**
+     * Distinct subagent-run identity when the host shares one `sessionId`
+     * across transcript files. Claude Code stores each subagent transcript
+     * under `<sessionId>/subagents/agent-<agentId>.jsonl` with the parent's
+     * `sessionId` on every line; without this identity a parent session and
+     * all of its subagent runs would collapse into one untruthful session row.
+     * Codex subagent rollouts carry their own sessionId and never set this.
+     */
+    subagentId?: string;
+    /**
+     * Host-recorded completions of subagent runs owned by this session, taken
+     * from the parent transcript's Task tool results (`toolUseResult.agentId`
+     * with `status: "completed"`). Subagent transcript files carry no
+     * completion marker of their own, so this is the only explicit completion
+     * evidence for a subagent run. Attached to one call per session; the
+     * session-vitals join reads it across transcript files.
+     */
+    subagentCompletions?: LocalAgentSubagentCompletion[];
     /** Provider-reported plan windows embedded in the transcript, when present. */
     rateLimits?: LocalAgentRateLimitSnapshot;
     /**
@@ -74,6 +110,27 @@ export type LocalAgentCall = {
      */
     activity?: LocalAgentActivity;
 };
+export type LocalAgentTokenComponentEvidence = {
+    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";
+    /** Complete means the parser can form a disjoint source-faithful total. */
+    calculatedTotalTokens: "calculated_complete" | "calculated_partial";
+    reportedTotalTokens: "provider_reported" | "not_reported";
+};
+export type LocalAgentCompletionEvidence = {
+    status: "completed";
+    evidence: "claude_turn_duration" | "codex_task_complete";
+    observedAt: string;
+};
+/** One host-recorded subagent completion (see LocalAgentCall.subagentCompletions). */
+export type LocalAgentSubagentCompletion = {
+    subagentId: string;
+    observedAt: string;
+};
 /**
  * Resolve the repository root most recently observed in transcript metadata.
  *
@@ -127,14 +184,224 @@ export type LocalAgentLogOptions = {
     sinceIso?: string;
     /** Collect privacy-safe Codex invocation summaries during the same JSON pass. */
     collectCodexInvocationEvidence?: boolean;
+    /**
+     * Optional fail-closed limits for qualitative/action reads. The financial
+     * loader has its own proof-based fast path; these limits protect the richer
+     * prompt/tool/activity pass from multi-gigabyte transcript histories.
+     *
+     * Files are considered newest-first within each source. A file is parsed
+     * only when it fits both limits in full. Skipped files never contribute
+     * calls, findings, invocation evidence, or zero-valued placeholders, and
+     * the returned source scan is explicitly marked partial.
+     */
+    qualitativeScan?: LocalAgentQualitativeScanPolicy;
+    /**
+     * Optional trusted private index backing warm qualitative scans. The adapter
+     * owns storage permissions/validation; keys contain a path hash and file
+     * identity, never a raw local path or transcript content.
+     */
+    qualitativeIndex?: LocalAgentQualitativeIndexAdapter;
+    /**
+     * Optional per-file cache for financial parse results. Unchanged files skip
+     * their full financial re-read; the newest file per source always parses
+     * fresh so the active session's evidence (including its raw working
+     * directory for context inference) is never served stale from a cache.
+     */
+    financialIndex?: LocalAgentFinancialIndexAdapter;
+    /**
+     * Optional ownership section of the private project index. When present,
+     * budget-skipped Codex files receive a bounded first-line header probe whose
+     * proven/unknown attribution is persisted and feeds the per-project coverage
+     * ledger. Claude transcripts get no header shortcut: their cwd is per-entry
+     * and can change mid-file.
+     */
+    ownershipIndex?: LocalAgentOwnershipIndexAdapter;
+    /**
+     * Optional checkpoint section of the private project index. When present
+     * together with `qualitativeIndex`, oversized Codex rollouts are parsed in
+     * bounded resumable slices instead of being skipped outright: each run
+     * advances at least one slice, and the file joins the index (and the
+     * per-project ledger) once its stream completes. Absent, oversized files
+     * keep today's skip-plus-header-pass behavior.
+     */
+    streamCheckpoints?: LocalAgentStreamCheckpointAdapter;
+    /**
+     * Requested project ref (`avref_…`) for the per-project coverage ledger.
+     * Only files proven to belong to a DIFFERENT ref are excluded from the
+     * blocking set; a file proven to belong to this exact ref keeps blocking
+     * until indexed — it is the oversized relevant transcript. Absent or
+     * malformed refs disable proven-foreign exclusion entirely (fail closed).
+     */
+    coverageProjectRef?: string;
+};
+export type LocalAgentQualitativeScanPolicy = {
+    /** Maximum UTF-8 bytes allowed for one qualitative transcript file. */
+    maxFileBytes: number;
+    /** Maximum UTF-8 bytes parsed per registered source in one scan. */
+    maxSourceBytes: number;
+    /**
+     * Byte allowance for the checkpointed streaming pass over oversized Codex
+     * rollouts in one run (default 512 MiB, roughly 4-5 s at measured
+     * throughput). Deliberately byte-metered rather than wall-clock so runs
+     * and tests are deterministic; the first scheduled file always advances by
+     * at least one complete line even at a smaller remaining allowance, which
+     * guarantees convergence.
+     */
+    maxStreamedBytesPerRun?: number;
+};
+export type LocalAgentQualitativeIndexKey = {
+    schemaVersion: 1;
+    parserVersion: typeof localAgentQualitativeParserVersion;
+    agent: LocalAgentFormatId;
+    /** SHA-256 of the normalized private path; the path itself is never stored. */
+    pathHash: string;
+    /** Opaque stat identity including ctime so in-place edits invalidate a hit. */
+    fileIdentity: string;
+    sinceIso: string | null;
+    collectInvocationEvidence: boolean;
+};
+export type LocalAgentQualitativeIndexValue = {
+    calls: LocalAgentCall[];
+    invocationFile?: ParsedInvocationFile;
+    /** Exact narrowing proof for cached aggregated invocation evidence. */
+    invocationWindowProof?: ParsedInvocationWindowProof;
+    diagnostics: Array<{
+        code: "malformed_jsonl" | "malformed_session_file" | "unsupported_token_shape";
+        count: number;
+    }>;
+};
+export type LocalAgentQualitativeIndexAdapter = {
+    read: (key: Readonly<LocalAgentQualitativeIndexKey>) => Promise<LocalAgentQualitativeIndexValue | undefined>;
+    write: (key: Readonly<LocalAgentQualitativeIndexKey>, value: Readonly<LocalAgentQualitativeIndexValue>) => Promise<void>;
+};
+export type LocalAgentFinancialIndexKey = {
+    schemaVersion: 2;
+    section: "financial";
+    agent: LocalAgentFormatId;
+    pathHash: string;
+    fileIdentity: string;
+    financialParserVersion: number;
+};
+/**
+ * Per-file cache for financial parse results. The stored value reuses the
+ * privacy-reduced qualitative value contract (calls + parse diagnostics; no
+ * invocation evidence). An entry's existence means the file had financial
+ * content under this exact identity and parser version.
+ */
+export type LocalAgentFinancialIndexAdapter = {
+    read: (key: Readonly<LocalAgentFinancialIndexKey>) => Promise<LocalAgentQualitativeIndexValue | undefined>;
+    write: (key: Readonly<LocalAgentFinancialIndexKey>, value: Readonly<LocalAgentQualitativeIndexValue>) => Promise<void>;
+};
+/**
+ * Ownership evidence for one transcript file in the private project index.
+ * "unknown" is a first-class state: ownership is never guessed from hashes,
+ * basenames, or absence. Structurally identical to the project-index store's
+ * ownership document (the loader cannot import the store without a cycle).
+ */
+export type LocalAgentOwnershipRecord = {
+    /** Body-derived ownership; header-only records stay "unknown". */
+    status: "resolved" | "no_calls" | "unknown";
+    /** Ownership binds to one exact file identity; rotation supersedes it. */
+    fileIdentity: string;
+    /** Distinct `avref_…` refs observed in parsed calls (empty until parsed). */
+    projectRefs: string[];
+    /**
+     * Bounded Codex header-pass attribution. "proven" is asserted only when the
+     * header cwd would short-circuit `dominantCodexCwd` exactly as a full parse
+     * would; every other header stays "unknown" and is never assumed foreign.
+     */
+    headerAttribution?: {
+        status: "proven" | "unknown";
+        projectRef?: string;
+        /**
+         * Subagent marker from the same bounded header read — reused to order
+         * the streaming schedule without re-probing. A scheduling hint only,
+         * never ownership evidence.
+         */
+        isSubagent?: boolean;
+    };
 };
+/**
+ * Ownership section of the private project index. `createProjectIndexAdapters`
+ * satisfies this structurally; the adapter owns storage validation and
+ * rotation-superseding semantics.
+ */
+export type LocalAgentOwnershipIndexAdapter = {
+    readOwnership: (agent: LocalAgentFormatId, pathHash: string) => Promise<LocalAgentOwnershipRecord | undefined>;
+    writeOwnership: (agent: LocalAgentFormatId, pathHash: string, ownership: Readonly<LocalAgentOwnershipRecord>) => Promise<void>;
+};
+/**
+ * Resumable stream checkpoint for one oversized transcript (design section
+ * e). The identity pin is deliberately append-tolerant (dev/ino/birthtime
+ * survive appends); truncation, rotation, edits inside the 64 KiB prefix
+ * probe window, and parser contract changes all fail the resume proof and
+ * force a restart. Documented residual (QA-confirmed): an in-place edit of
+ * bytes BEFORE the probe window on the same inode is indistinguishable from
+ * untouched history and resumes — the same local trust extended to the
+ * source files themselves (design section e). The reducer/collector payloads
+ * are opaque to the store and re-validated by the loader on every resume
+ * (fail closed: invalid state is discarded, never partially reused).
+ */
+export type LocalAgentStreamCheckpointRecord = {
+    /** Append-tolerant identity pin for the checkpointed inode. */
+    pin: {
+        dev: number;
+        ino: number;
+        birthtimeMs: number;
+    };
+    parserVersion: number;
+    collectInvocationEvidence: boolean;
+    /** Window the stream's invocation collector was created with. */
+    sinceIso: string | null;
+    /** Bytes consumed through the end of the last complete line. */
+    offset: number;
+    /** Content proof over the up-to-64 KiB immediately before `offset`. */
+    prefixProbe: {
+        bytes: number;
+        sha256: string;
+    };
+    /** Privacy-reduced Codex reducer state; raw paths and prompt text never appear. */
+    reducerState: unknown;
+    /** Invocation collector snapshot when evidence collection was requested. */
+    collectorState?: unknown;
+};
+/**
+ * Checkpoint section of the private project index; structurally satisfied by
+ * `createProjectIndexAdapters`.
+ */
+export type LocalAgentStreamCheckpointAdapter = {
+    readStreamCheckpoint: (agent: LocalAgentFormatId, pathHash: string) => Promise<LocalAgentStreamCheckpointRecord | undefined>;
+    writeStreamCheckpoint: (agent: LocalAgentFormatId, pathHash: string, checkpoint: Readonly<LocalAgentStreamCheckpointRecord>) => Promise<void>;
+    deleteStreamCheckpoint: (agent: LocalAgentFormatId, pathHash: string) => Promise<void>;
+};
+export declare const localAgentFinancialParserVersion = 1;
+/**
+ * Qualitative parser contract version. Bumped to 2 with the checkpointed
+ * streaming path (A4b): entries and checkpoints written by the pre-streaming
+ * parser are never reinterpreted — a version mismatch is a miss (entries) or
+ * a discard (checkpoints), and the store schema pins this exact literal so
+ * both sides fail closed together. Bumped to 4 when Claude Code subagent
+ * transcripts gained their own session identity (`subagentId`) and
+ * cross-file completion evidence (`subagentCompletions`, from both Task tool
+ * results and background task-notifications): entries persisted by the
+ * collapsing parser must re-parse rather than silently keep merging subagent
+ * runs into their parent session.
+ */
+export declare const localAgentQualitativeParserVersion = 4;
+/**
+ * Conservative launch defaults for action-capable qualitative evidence.
+ * Callers must still inspect `qualitativeCoverage` before deriving a finding:
+ * the limits protect responsiveness; they do not turn a partial scan into a
+ * representative sample.
+ */
+export declare const SAFE_QUALITATIVE_SCAN_POLICY: Readonly<LocalAgentQualitativeScanPolicy>;
 /**
  * Options accepted by the financial-only loader. Invocation collection is
  * intentionally unavailable: this path reads only the evidence needed for a
  * financial snapshot and transcript-reported plan limits.
  */
-export type LocalAgentFinancialLogOptions = Omit<LocalAgentLogOptions, "collectCodexInvocationEvidence">;
-export type LocalAgentLogDiagnosticCode = "directory_missing" | "directory_unreadable" | "file_unreadable" | "malformed_jsonl" | "malformed_session_file" | "unsupported_token_shape";
+export type LocalAgentFinancialLogOptions = Omit<LocalAgentLogOptions, "collectCodexInvocationEvidence" | "qualitativeScan" | "qualitativeIndex" | "ownershipIndex" | "coverageProjectRef">;
+export type LocalAgentLogDiagnosticCode = "directory_missing" | "directory_unreadable" | "file_unreadable" | "malformed_jsonl" | "malformed_session_file" | "unsupported_token_shape" | "qualitative_scan_incomplete" | "qualitative_index_error";
 export type LocalAgentLogDiagnostic = {
     agent: LocalAgentCall["agent"];
     code: LocalAgentLogDiagnosticCode;
@@ -166,6 +433,62 @@ export type LocalAgentSourceScan = {
     nonFinancialBytesPrefiltered?: number;
     /** Whether JSON syntax was checked for every line or financial events only. */
     jsonlValidationCoverage?: "complete" | "financial_events_only";
+    /**
+     * Coverage for an explicitly bounded qualitative/action scan. Omitted for
+     * the legacy unbounded loader and for the financial-only loader.
+     */
+    qualitativeCoverage?: "complete" | "partial";
+    /** Files inside the requested time window considered by the bounded scan. */
+    qualitativeFilesEligible?: number;
+    /** Eligible files omitted because a configured byte limit would be crossed. */
+    qualitativeFilesSkippedForBudget?: number;
+    /** Eligible files selected for a complete bounded read. */
+    qualitativeFilesSelected?: number;
+    /** Selected files that were read and parsed completely. */
+    qualitativeFilesReadCompletely?: number;
+    /** Eligible files whose evidence is present in the private index (hit or fresh parse). */
+    qualitativeFilesIndexed?: number;
+    /**
+     * Eligible files proven by a bounded header pass to belong to a project
+     * other than the requested `coverageProjectRef`. Always zero when no ref
+     * was requested: proven ownership never unblocks an unnamed project.
+     */
+    qualitativeFilesForeignProven?: number;
+    /**
+     * Eligible files that still block the requested project: not indexed and
+     * not proven foreign. A file proven to belong to the requested project
+     * itself stays in this count until indexed — it is exactly the oversized
+     * relevant transcript that must be parsed, never excluded.
+     */
+    qualitativeFilesOwnershipUnknown?: number;
+    /**
+     * Per-project qualitative coverage for the requested project. "indexing"
+     * whenever any eligible file's ownership is unknown, any scan-level failure
+     * occurred, or a file proven to belong to the requested project is not yet
+     * indexed — the honest no-claim state while the index converges.
+     */
+    qualitativeProjectCoverage?: "complete" | "indexing";
+    /** Sum of eligible regular-file sizes observed before reading. */
+    qualitativeBytesEligible?: number;
+    /** Sum of metadata sizes reserved for selected complete-file reads. */
+    qualitativeBytesSelected?: number;
+    /** Bytes actually accepted into full-file qualitative parsing. */
+    qualitativeBytesRead?: number;
+    /** Selected bytes reused from a trusted warm index instead of reread. */
+    qualitativeBytesReused?: number;
+    /** Bytes consumed by the checkpointed streaming pass this run. */
+    qualitativeBytesStreamed?: number;
+    /** Oversized files with an in-progress (unconverged) stream this run. */
+    qualitativeFilesStreaming?: number;
+    qualitativeIndexHits?: number;
+    /** Index read/write failures; source parsing falls back to disk. */
+    qualitativeIndexErrors?: number;
+    /**
+     * Emitted calls always come from complete files, even when global source
+     * coverage is partial. This lets cohort experiments use exact selected
+     * evidence while global/main-driver claims remain gated on coverage.
+     */
+    qualitativeSelectedEvidence?: "complete_files_only";
 };
 export type LocalAgentLogResult = {
     records: UsageRecord[];
@@ -181,6 +504,20 @@ export type LocalAgentLogResult = {
     /** Present only when requested; contains counts/basenames, never raw text. */
     codexInvocationFiles?: ParsedInvocationFile[];
 };
+/**
+ * True only when every requested source was scanned under an explicit bounded
+ * policy without omitting an eligible file. Legacy unbounded results return
+ * false so an action caller cannot accidentally treat unknown coverage as a
+ * complete launch-safe scan.
+ */
+export declare function hasCompleteQualitativeCoverage(result: Pick<LocalAgentLogResult, "sourceScans">, agents?: readonly LocalAgentFormatId[]): boolean;
+/**
+ * Whether a bounded result contains exact calls from at least one completely
+ * parsed selected file for every requested source. This is deliberately
+ * weaker than global coverage: it can support a clearly scoped experiment,
+ * never a claim about the source's overall/main driver.
+ */
+export declare function hasExactSelectedQualitativeEvidence(result: Pick<LocalAgentLogResult, "calls" | "sourceScans">, agents?: readonly LocalAgentFormatId[]): boolean;
 type TranscriptParseDiagnostic = {
     code: "malformed_jsonl" | "malformed_session_file" | "unsupported_token_shape";
     count: number;
@@ -200,6 +537,15 @@ export declare function parseClaudeCodeTranscript(content: string, filePath?: st
 export declare function parseCodexRollout(content: string, onEntry?: (entry: Record<string, unknown>) => void, onDiagnostic?: TranscriptParseDiagnosticHandler): LocalAgentCall[];
 /** Scan this machine's agent logs and return aggregated UsageRecords. */
 export declare function loadLocalAgentUsage(options?: LocalAgentLogOptions): Promise<LocalAgentLogResult>;
+/**
+ * Read only formats whose registry contract supports action planning.
+ *
+ * The launch action loop currently has truthful session/completion semantics
+ * for Claude Code and Codex. Keeping this entrypoint registry-driven avoids an
+ * unnecessary Gemini history walk and prevents presence-only/experimental
+ * formats from silently entering a matched token experiment.
+ */
+export declare function loadLocalAgentActionEvidence(options?: LocalAgentLogOptions): Promise<LocalAgentLogResult>;
 /**
  * Registry-driven ingestion engine. Exported from this module for registry
  * contract tests and format modules, but intentionally omitted from the
@@ -225,6 +571,19 @@ export declare function readClaudeCodeFinancialFileForRegistry(context: LocalAge
 export declare function readCodexFinancialFileForRegistry(context: LocalAgentFormatFinancialFileContext): Promise<LocalAgentCall[]>;
 /** @internal Runtime hook owned by the Gemini CLI registry entry. */
 export declare function readGeminiFinancialFileForRegistry(context: LocalAgentFormatFinancialFileContext): Promise<LocalAgentCall[]>;
+/**
+ * Fresh bounded header reads allowed per scan. Files beyond the cap simply
+ * stay ownership-unknown ("indexing") this run — never claimed either way —
+ * and are reached on a later run once earlier probes persist their results.
+ */
+export declare const codexHeaderProbesPerScan = 64;
+/**
+ * Default per-run byte allowance for the streaming pass. Sized from measured
+ * end-to-end throughput (~99 MB/s on the reference machine, QA probe8): 512
+ * MiB keeps one slice at roughly 4-5 seconds of wall clock inside the cold
+ * budget. Callers with different budgets tune `maxStreamedBytesPerRun`.
+ */
+export declare const defaultStreamedBytesPerRun: number;
 /** Aggregate per-call usage into one UsageRecord per day+agent+model+project. */
 export declare function aggregateCalls(calls: LocalAgentCall[]): UsageRecord[];
 /** @internal Registry-aware aggregation used by the extensible ingestion engine. */