@agent-finops/core 0.8.1 → 0.9.0

package/dist/glance.js

@@ -3,6 +3,7 @@ import { canPriceTokenUsageAtScope, estimateTokenCostUsd, PRICING_TABLE_AS_OF }
 import { subscriptionPlans } from "./planMath.js";
 import { buildContextHealth } from "./contextHealth.js";
 import { localAgentFormatDescriptors, localAgentFormatSupports } from "./localAgentFormats/registry.js";
+import { aibillImproveCommandV0 } from "./runtimeCommands.js";
 const HOUR_MS = 60 * 60 * 1_000;
 const DAY_MS = 24 * HOUR_MS;
 /**
@@ -55,17 +56,37 @@ export function buildUsageGlance(calls, options = {}) {
     const focusSessions = latest?.project && !isGenericProject(latest.project)
         ? windowSessions.filter((session) => session.project === latest.project)
         : windowSessions;
-    const focus = buildMainFocus(focusSessions, focusWindowDays, now);
-    const sessionHealth = suppliedContextHealth ?? buildContextHealth({ calls: safeCalls, now });
-    const anomaly = anomalyFromContextHealth(sessionHealth);
-    const primaryAction = buildPrimaryAction({
-        currentSession,
-        focus,
-        limits,
-        sessionHealth,
-        generatedAt: now.toISOString(),
-        filesParsed: options.filesParsed ?? 0
-    });
+    const qualitativeCoverage = options.qualitativeCoverage ?? {
+        status: "complete",
+        selectedFiles: options.filesParsed ?? 0,
+        readCompletely: options.filesParsed ?? 0,
+        skippedForBudget: 0
+    };
+    const qualitativeComplete = qualitativeCoverage.status === "complete";
+    const focus = qualitativeComplete
+        ? buildMainFocus(focusSessions, focusWindowDays, now)
+        : null;
+    const baseSessionHealth = suppliedContextHealth ?? buildContextHealth({ calls: safeCalls, now });
+    const sessionHealth = {
+        ...baseSessionHealth,
+        qualitativeCoverage
+    };
+    const anomaly = qualitativeComplete ? anomalyFromContextHealth(sessionHealth) : null;
+    const primaryAction = qualitativeComplete
+        ? buildPrimaryAction({
+            currentSession,
+            focus,
+            limits,
+            sessionHealth,
+            generatedAt: now.toISOString(),
+            filesParsed: options.filesParsed ?? 0
+        })
+        : buildCoverageLimitedPrimaryAction({
+            currentSession,
+            sessionHealth,
+            coverage: qualitativeCoverage
+        });
+    const tokenExperiment = sanitizeActionVerificationProjection(options.actionVerificationProjection);
     const detectedAgents = (options.detectedAgents ?? uniqueAgents(safeCalls))
         .filter((agent) => localAgentFormatSupports(agent, "glance"));
     const agentsWithCurrentLimits = new Set(limits.filter((limit) => limit.freshness === "current").map((limit) => limit.agent));
@@ -81,14 +102,19 @@ export function buildUsageGlance(calls, options = {}) {
         "A five-hour percentage is current for at most five hours after observation; a weekly percentage is current for at most 24 hours. Older transcript evidence is labeled stale and never drives an action.",
         "Main focus is a local summary of observed human prompts and tool activity, not elapsed time or spend; raw prompts are not returned.",
         "The primary action combines Context Health, Main focus, and reported runway locally. It only provides a copyable handoff prompt and never runs an agent automatically.",
+        "A token-test percentage compares matched local session cohorts guarded by explicit quality evidence; it is not certified savings, verified outcome ROI, or a provider bill.",
         "Claude Code transcripts do not report plan headroom. Missing limits remain unavailable instead of being inferred.",
-        "Cursor and GitHub Copilot require their provider connections because their local chat stores are not treated as authoritative billing transcripts."
+        "Cursor and GitHub Copilot require their provider connections because their local chat stores are not treated as authoritative billing transcripts.",
+        ...(qualitativeComplete ? [] : [
+            "Main focus, anomaly, and context-change handoff are unavailable because the bounded qualitative index is incomplete; no global driver was inferred from a selected subset."
+        ])
     ];
     return {
         dataMode: "local_transcripts",
         generatedAt: now.toISOString(),
         coverage: {
             filesParsed: options.filesParsed ?? 0,
+            qualitative: qualitativeCoverage,
             supportedTranscriptAgents: supportedFormats.map((descriptor) => descriptor.id),
             detectedAgents,
             rateLimitMetadata: supportedFormats.map((descriptor) => ({
@@ -146,6 +172,14 @@ export function buildUsageGlance(calls, options = {}) {
                 execution: "copy_prompt",
                 automaticExecution: false
             },
+            tokenExperiment: {
+                source: tokenExperiment
+                    ? "canonical_action_verification_projection"
+                    : "not_available",
+                calculation: "core_experiment_evaluator",
+                cohort: "matched_local_sessions",
+                automaticExecution: false
+            },
             network: {
                 uploaded: false
             }
@@ -157,9 +191,114 @@ export function buildUsageGlance(calls, options = {}) {
         anomaly,
         sessionHealth,
         primaryAction,
+        ...(tokenExperiment ? { tokenExperiment } : {}),
         caveats
     };
 }
+function buildCoverageLimitedPrimaryAction(input) {
+    const project = safeActionMetadata(input.currentSession?.project, 80);
+    const status = input.coverage.status === "partial" ? "partial" : "not available";
+    return {
+        kind: "session_handoff",
+        intent: "inspect_current_work",
+        label: project ? `Refresh evidence · ${project}` : "Refresh evidence",
+        detail: `Main focus unavailable · qualitative index ${status}`,
+        ...(project ? { project } : {}),
+        agentPrompt: [
+            "aibill's bounded qualitative evidence is incomplete.",
+            "Do not infer a global main focus, waste cause, or context change from the selected subset.",
+            `Run \`${aibillImproveCommandV0()}\` from the exact project root to refresh the private index, then review the new evidence before editing.`
+        ].join("\n"),
+        source: "context_health_focus_and_reported_runway",
+        confidence: "low",
+        execution: "copy_prompt",
+        requiresUserConfirmation: true,
+        evidenceWindowDays: input.sessionHealth.deadContext.windowDays
+    };
+}
+const actionVerificationStates = new Set([
+    "collect_baseline",
+    "approve_one_change",
+    "collect_post_change",
+    "review_measured_result",
+    "rollback",
+    "resolve_evidence",
+    "rolled_back",
+    "cancelled"
+]);
+const actionVerificationTones = new Set([
+    "neutral",
+    "attention",
+    "positive",
+    "negative"
+]);
+const actionVerificationEvidenceLabels = new Set([
+    "calculated",
+    "missing"
+]);
+const actionVerificationQualityLabels = new Set([
+    "held",
+    "regressed",
+    "insufficient"
+]);
+const actionVerificationQualityEvidence = new Set([
+    "verified",
+    "observed",
+    "user_declared",
+    "missing"
+]);
+const experimentIdPattern = /^tre_v0_[a-f0-9]{64}$/;
+const findingIdPattern = /^wf_v0_[a-f0-9]{64}$/;
+const candidateKeyPattern = /^wfc_v0_[a-f0-9]{64}$/;
+/**
+ * Treat the optional adapter input as untrusted at runtime. A malformed or
+ * internally inconsistent projection is omitted instead of becoming a stale
+ * or invented Glance claim. This function deliberately does not derive any
+ * experiment result.
+ */
+function sanitizeActionVerificationProjection(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const safe = sanitizeStringMetadata(input);
+    if (safe.schemaVersion !== 0 ||
+        !experimentIdPattern.test(safe.experimentId) ||
+        !findingIdPattern.test(safe.findingId) ||
+        !candidateKeyPattern.test(safe.candidateKey) ||
+        !actionVerificationStates.has(safe.state) ||
+        !actionVerificationTones.has(safe.tone) ||
+        !actionVerificationEvidenceLabels.has(safe.evidenceLabel) ||
+        !actionVerificationQualityLabels.has(safe.qualityLabel) ||
+        !actionVerificationQualityEvidence.has(safe.qualityEvidence) ||
+        !isSafeExperimentCount(safe.baselineSessions) ||
+        !isSafeExperimentCount(safe.postChangeSessions) ||
+        !isSafeExperimentCount(safe.minimumSessions) ||
+        safe.minimumSessions < 1 ||
+        (safe.reductionPercent !== null && (!Number.isFinite(safe.reductionPercent) ||
+            safe.reductionPercent > 100 ||
+            safe.reductionPercent < -1_000_000))) {
+        return undefined;
+    }
+    const measured = safe.state === "review_measured_result";
+    const claimQualityEvidence = safe.qualityEvidence === "verified" ||
+        safe.qualityEvidence === "observed" ||
+        safe.qualityEvidence === "user_declared";
+    if (safe.reductionPercent !== null) {
+        const claimEvidenceIsComplete = safe.evidenceLabel === "calculated" &&
+            safe.qualityLabel === "held" &&
+            claimQualityEvidence;
+        const signMatchesState = (measured && safe.reductionPercent >= 0) ||
+            (safe.state === "rollback" && safe.reductionPercent < 0);
+        if (!claimEvidenceIsComplete || !signMatchesState)
+            return undefined;
+    }
+    else if (measured) {
+        return undefined;
+    }
+    return safe;
+}
+function isSafeExperimentCount(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
 function toGlancePlan(agent, detectedPlans) {
     const detected = detectedPlans.find((plan) => plan.agent === agent);
     if (!detected)

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./analyze.js";
+export * from "./actionPlanner.js";
+export * from "./actionVerification.js";
 export * from "./agentInventory.js";
 export * from "./agentEconomicsReceipt.js";
 export * from "./activitySnapshot.js";
@@ -12,16 +14,23 @@ export * from "./discovery.js";
 export * from "./glance.js";
 export * from "./toolInvocations.js";
 export * from "./insights.js";
-export { aggregateCalls, dedupeCumulativeSessionCalls, latestObservedWorkingDirectory, loadLocalAgentFinancialUsage, loadLocalAgentUsage, parseClaudeCodeTranscript, parseCodexRollout, sanitizeLocalActivityText } from "./localAgentLogs.js";
-export type { LocalAgentActivity, LocalAgentCall, LocalAgentFinancialLogOptions, LocalAgentLogDiagnostic, LocalAgentLogDiagnosticCode, LocalAgentLogOptions, LocalAgentLogResult, LocalAgentRateLimitSnapshot, LocalAgentRateLimitWindow, LocalAgentSourceScan, LocalAgentTurnUsage } from "./localAgentLogs.js";
+export { aggregateCalls, codexHeaderProbesPerScan, dedupeCumulativeSessionCalls, defaultStreamedBytesPerRun, hasCompleteQualitativeCoverage, hasExactSelectedQualitativeEvidence, latestObservedWorkingDirectory, loadLocalAgentActionEvidence, loadLocalAgentFinancialUsage, loadLocalAgentUsage, localAgentQualitativeParserVersion, parseClaudeCodeTranscript, parseCodexRollout, SAFE_QUALITATIVE_SCAN_POLICY, sanitizeLocalActivityText } from "./localAgentLogs.js";
+export type { LocalAgentActivity, LocalAgentCall, LocalAgentCompletionEvidence, LocalAgentFinancialLogOptions, LocalAgentOwnershipIndexAdapter, LocalAgentOwnershipRecord, LocalAgentQualitativeIndexAdapter, LocalAgentQualitativeIndexKey, LocalAgentQualitativeIndexValue, LocalAgentQualitativeScanPolicy, LocalAgentStreamCheckpointAdapter, LocalAgentStreamCheckpointRecord, LocalAgentLogDiagnostic, LocalAgentLogDiagnosticCode, LocalAgentLogOptions, LocalAgentLogResult, LocalAgentRateLimitSnapshot, LocalAgentRateLimitWindow, LocalAgentSourceScan, LocalAgentTokenComponentEvidence, LocalAgentTurnUsage } from "./localAgentLogs.js";
 export * from "./localAgentFormats/registry.js";
 export type * from "./localAgentFormats/types.js";
 export * from "./modelPricing.js";
 export * from "./planDetection.js";
 export * from "./planMath.js";
+export * from "./projectEconomics.js";
+export * from "./resultCard.js";
+export * from "./projectEconomicsBuilder.js";
+export * from "./qualitativeIndexCache.js";
+export * from "./projectIndexStore.js";
+export * from "./runtimeCommands.js";
 export * from "./sampleData.js";
 export * from "./scanGuard.js";
 export * from "./schema.js";
+export * from "./sessionVitals.js";
 export * from "./sourceRegistry.js";
 export * from "./sourceStatus.js";
 export * from "./stateTrust.js";

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from "./analyze.js";
+export * from "./actionPlanner.js";
+export * from "./actionVerification.js";
 export * from "./agentInventory.js";
 export * from "./agentEconomicsReceipt.js";
 export * from "./activitySnapshot.js";
@@ -12,14 +14,21 @@ export * from "./discovery.js";
 export * from "./glance.js";
 export * from "./toolInvocations.js";
 export * from "./insights.js";
-export { aggregateCalls, dedupeCumulativeSessionCalls, latestObservedWorkingDirectory, loadLocalAgentFinancialUsage, loadLocalAgentUsage, parseClaudeCodeTranscript, parseCodexRollout, sanitizeLocalActivityText } from "./localAgentLogs.js";
+export { aggregateCalls, codexHeaderProbesPerScan, dedupeCumulativeSessionCalls, defaultStreamedBytesPerRun, hasCompleteQualitativeCoverage, hasExactSelectedQualitativeEvidence, latestObservedWorkingDirectory, loadLocalAgentActionEvidence, loadLocalAgentFinancialUsage, loadLocalAgentUsage, localAgentQualitativeParserVersion, parseClaudeCodeTranscript, parseCodexRollout, SAFE_QUALITATIVE_SCAN_POLICY, sanitizeLocalActivityText } from "./localAgentLogs.js";
 export * from "./localAgentFormats/registry.js";
 export * from "./modelPricing.js";
 export * from "./planDetection.js";
 export * from "./planMath.js";
+export * from "./projectEconomics.js";
+export * from "./resultCard.js";
+export * from "./projectEconomicsBuilder.js";
+export * from "./qualitativeIndexCache.js";
+export * from "./projectIndexStore.js";
+export * from "./runtimeCommands.js";
 export * from "./sampleData.js";
 export * from "./scanGuard.js";
 export * from "./schema.js";
+export * from "./sessionVitals.js";
 export * from "./sourceRegistry.js";
 export * from "./sourceStatus.js";
 export * from "./stateTrust.js";

package/dist/localAgentFormats/gemini.js

@@ -176,8 +176,8 @@ function processMessage(message, state) {
         state.diagnostics.add("missing_timestamp");
         return;
     }
-    if (state.sinceMs !== undefined && Date.parse(timestamp) < state.sinceMs)
-        return;
+    // Window-blind on purpose (financial cache correctness): the loader's
+    // final timestamp filter performs all narrowing.
     const parsedTokens = parseTokens(message.tokens);
     const metadata = mergeMetadata(state.metadata, message);
     const attribution = explicitAttribution(message, metadata) ??

package/dist/localAgentFormats/registry.js

@@ -46,6 +46,7 @@ const descriptors = [
             fieldsRead: [
                 "timestamp, model, and token-usage components",
                 "session and working-directory metadata for local deduplication and attribution",
+                "explicit system/turn_duration work-unit completion markers and transcript version strings when present",
                 "human-prompt and tool metadata for privacy-reduced local activity summaries"
             ],
             verified: [
@@ -65,7 +66,8 @@ const descriptors = [
             ],
             limitations: [
                 "Malformed lines are skipped and reported.",
-                "Incomplete token shapes remain unpriced with missing financial evidence instead of becoming $0."
+                "Incomplete token shapes remain unpriced with missing financial evidence instead of becoming $0.",
+                "A system/turn_duration marker proves only that the latest observed turn completed; it does not prove permanent transcript closure, and missing or inconsistent completion evidence stays ineligible for automatic before/after cohorts."
             ]
         },
         fixtures: ["claude-code-v1"]
@@ -115,6 +117,7 @@ const descriptors = [
             ],
             fieldsRead: [
                 "session metadata, timestamps, model, and cumulative/last-turn token usage",
+                "explicit event_msg/task_complete work-unit completion markers and session_meta cli_version strings when present",
                 "transcript-reported rate-limit windows when present",
                 "tool-call metadata for local attribution and optional privacy-safe invocation counts"
             ],
@@ -135,7 +138,8 @@ const descriptors = [
             ],
             limitations: [
                 "Only rollout-*.jsonl files are parsed as Codex sessions.",
-                "Incomplete, regressing, or total-only token shapes remain unpriced with missing financial evidence."
+                "Incomplete, regressing, or total-only token shapes remain unpriced with missing financial evidence.",
+                "An event_msg/task_complete marker proves only that the latest observed task completed; it does not prove permanent transcript closure, and missing or inconsistent completion evidence stays ineligible for automatic before/after cohorts."
             ]
         },
         fixtures: ["codex-v1"]

package/dist/localAgentFormats/runtimeRegistry.js

@@ -24,9 +24,12 @@ const runtimes = [
             const collector = collectInvocationEvidence
                 ? createCodexInvocationCollector(sinceMs)
                 : undefined;
+            const calls = parseCodexRollout(content, collector?.consume, onDiagnostic);
+            const invocationFile = collector?.finish();
             return {
-                calls: parseCodexRollout(content, collector?.consume, onDiagnostic),
-                ...(collector ? { invocationFile: collector.finish() } : {})
+                calls,
+                ...(invocationFile ? { invocationFile } : {}),
+                ...(collector ? { invocationWindowProof: collector.windowProof() } : {})
             };
         },
         parseFinancialFile: readCodexFinancialFileForRegistry

package/dist/localAgentFormats/types.d.ts

@@ -1,5 +1,5 @@
 import type { LocalAgentCall, LocalAgentLogDiagnostic, LocalAgentSourceScan } from "../localAgentLogs.js";
-import type { ParsedInvocationFile } from "../toolInvocations.js";
+import type { ParsedInvocationFile, ParsedInvocationWindowProof } from "../toolInvocations.js";
 /**
  * Public format identity contract. Add future parser IDs here as part of the
  * registry-owned change so existing exhaustive consumers do not see an
@@ -78,6 +78,7 @@ export type LocalAgentFormatParseContext = {
 export type LocalAgentFormatParseResult = {
     calls: LocalAgentCall[];
     invocationFile?: ParsedInvocationFile;
+    invocationWindowProof?: ParsedInvocationWindowProof;
 };
 export type LocalAgentFormatFinancialFileContext = {
     filePath: string;