@agent-finops/core 0.7.3 → 0.8.1

package/dist/glance.js

@@ -1,5 +1,5 @@
 import { dedupeCumulativeSessionCalls, sanitizeLocalActivityText } from "./localAgentLogs.js";
-import { estimateTokenCostUsd, PRICING_TABLE_AS_OF } from "./modelPricing.js";
+import { canPriceTokenUsageAtScope, estimateTokenCostUsd, PRICING_TABLE_AS_OF } from "./modelPricing.js";
 import { subscriptionPlans } from "./planMath.js";
 import { buildContextHealth } from "./contextHealth.js";
 import { localAgentFormatDescriptors, localAgentFormatSupports } from "./localAgentFormats/registry.js";
@@ -45,7 +45,7 @@ export function buildUsageGlance(calls, options = {}) {
         : null;
     const limitCalls = sanitizeStringMetadata(options.limitCalls ?? safeCalls)
         .filter((call) => localAgentFormatSupports(call.agent, "rateLimits"));
-    const limits = latestLimits(limitCalls, now).map(({ agent, window, observedAt }) => toGlanceLimit(agent, window, observedAt));
+    const limits = latestLimits(limitCalls, now).map(({ agent, window, observedAt }) => toGlanceLimit(agent, window, observedAt, now));
     const windowStart = now.getTime() - focusWindowDays * DAY_MS;
     const windowCalls = safeCalls.filter((call) => Date.parse(call.timestamp) >= windowStart);
     const windowSessions = groupSessions(windowCalls);
@@ -68,7 +68,8 @@ export function buildUsageGlance(calls, options = {}) {
     });
     const detectedAgents = (options.detectedAgents ?? uniqueAgents(safeCalls))
         .filter((agent) => localAgentFormatSupports(agent, "glance"));
-    const agentsWithLimits = new Set(limits.map((limit) => limit.agent));
+    const agentsWithCurrentLimits = new Set(limits.filter((limit) => limit.freshness === "current").map((limit) => limit.agent));
+    const agentsWithStaleLimits = new Set(limits.filter((limit) => limit.freshness === "stale").map((limit) => limit.agent));
     const limitAgents = uniqueAgents(limitCalls.filter((call) => call.rateLimits));
     const reportedWindows = (agent) => ([...new Set(limits
             .filter((limit) => limit.agent === agent)
@@ -77,6 +78,7 @@ export function buildUsageGlance(calls, options = {}) {
         "Session value is an API-equivalent estimate from transcript token counts, not an invoice or subscription charge.",
         "A detected monthly subscription changes the interpretation, not the token math: the API-equivalent amount is usage priced at list rates, not incremental spend or business outcome value.",
         "Exhaustion time is a pace projection; remaining percentage and reset time are provider-reported only when embedded in a transcript.",
+        "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.",
         "Claude Code transcripts do not report plan headroom. Missing limits remain unavailable instead of being inferred.",
@@ -92,7 +94,9 @@ export function buildUsageGlance(calls, options = {}) {
             rateLimitMetadata: supportedFormats.map((descriptor) => ({
                 agent: descriptor.id,
                 status: descriptor.capabilities.rateLimits
-                    ? agentsWithLimits.has(descriptor.id) ? "reported" : "not_seen"
+                    ? agentsWithCurrentLimits.has(descriptor.id)
+                        ? "reported"
+                        : agentsWithStaleLimits.has(descriptor.id) ? "stale" : "not_seen"
                     : "not_reported_by_transcript",
                 windowsReported: reportedWindows(descriptor.id)
             })),
@@ -267,8 +271,11 @@ function latestLimits(calls, now) {
     return [...byWindow.values()].sort((left, right) => (order[left.window.kind] - order[right.window.kind] ||
         left.agent.localeCompare(right.agent)));
 }
-function toGlanceLimit(agent, window, observedAt) {
-    const projection = projectExhaustion(window, observedAt);
+function toGlanceLimit(agent, window, observedAt, now) {
+    const freshness = limitEvidenceFreshness(window, observedAt, now);
+    const projection = freshness === "current"
+        ? projectExhaustion(window, observedAt, now)
+        : { at: null, beforeReset: false };
     return {
         agent,
         kind: window.kind,
@@ -279,12 +286,13 @@ function toGlanceLimit(agent, window, observedAt) {
         observedAt,
         resetsAt: window.resetsAt,
         source: "transcript_reported",
+        freshness,
         projectedExhaustionAt: projection.at,
         projectedToExhaustBeforeReset: projection.beforeReset,
         projectionConfidence: "estimated"
     };
 }
-function projectExhaustion(window, observedAt) {
+function projectExhaustion(window, observedAt, now) {
     const observedMs = Date.parse(observedAt);
     const resetMs = Date.parse(window.resetsAt);
     const windowStartMs = resetMs - window.windowMinutes * 60_000;
@@ -296,15 +304,27 @@ function projectExhaustion(window, observedAt) {
         window.usedPercent <= 0) {
         return { at: null, beforeReset: false };
     }
-    if (window.usedPercent >= 100) {
-        return { at: observedAt, beforeReset: true };
-    }
+    // A current report at the limit is an observed exhausted state, not a
+    // forecast. Keep the projection empty so downstream copy cannot describe an
+    // already-exhausted window as something that merely "may" exhaust.
+    if (window.usedPercent >= 100)
+        return { at: null, beforeReset: false };
     const remainingMs = elapsedMs * ((100 - window.usedPercent) / window.usedPercent);
     const exhaustionMs = observedMs + remainingMs;
-    return exhaustionMs < resetMs
+    return exhaustionMs > now.getTime() && exhaustionMs < resetMs
         ? { at: new Date(exhaustionMs).toISOString(), beforeReset: true }
         : { at: null, beforeReset: false };
 }
+function limitEvidenceFreshness(window, observedAt, now) {
+    const observedMs = Date.parse(observedAt);
+    const ageMs = now.getTime() - observedMs;
+    const windowMs = window.windowMinutes * 60_000;
+    const maximumAgeMs = Math.min(windowMs, DAY_MS);
+    return Number.isFinite(observedMs) && Number.isFinite(windowMs) && windowMs > 0 &&
+        ageMs >= 0 && ageMs <= maximumAgeMs
+        ? "current"
+        : "stale";
+}
 function buildMainFocus(sessions, windowDays, now) {
     const candidates = sessions.map((session) => {
         const rawActivity = session.activity ?? fallbackActivity(session);
@@ -449,8 +469,17 @@ function buildPrimaryAction(input) {
     const project = safeActionMetadata(preferredProject, 80);
     const focus = safeActionMetadata(input.focus?.summary, 120);
     const focalFile = safeActionMetadata(input.focus?.file, 100);
+    const generatedAtMs = Date.parse(input.generatedAt);
+    const exhaustedLimit = input.limits
+        .filter((limit) => (limit.freshness === "current" &&
+        limit.usedPercent >= 100 &&
+        Date.parse(limit.resetsAt) > generatedAtMs))
+        .sort((left, right) => Date.parse(left.resetsAt) - Date.parse(right.resetsAt))[0];
     const urgentLimit = input.limits
-        .filter((limit) => limit.projectedToExhaustBeforeReset)
+        .filter((limit) => (limit.freshness === "current" &&
+        limit.projectedToExhaustBeforeReset &&
+        limit.projectedExhaustionAt !== null &&
+        Date.parse(limit.projectedExhaustionAt) > Date.parse(input.generatedAt)))
         .sort((left, right) => left.remainingPercent - right.remainingPercent)[0];
     const projectSuffix = project ? ` · ${project}` : "";
     let intent;
@@ -458,68 +487,81 @@ function buildPrimaryAction(input) {
     let detail;
     let instruction;
     let confidence = input.sessionHealth.confidence;
-    switch (input.sessionHealth.recommendation) {
-        case "start_fresh":
-            intent = "start_fresh";
-            label = `Start fresh${projectSuffix}`;
-            detail = focus
-                ? `Carry “${focus}” into a clean session`
-                : "Carry only the concrete state you still need";
-            instruction = "Start a clean session and continue the observed focus after verifying the current repository state.";
-            break;
-        case "review_hooks":
-            intent = "review_context";
-            label = `Review context${projectSuffix}`;
-            detail = focus
-                ? `Protect “${focus}” from unnecessary hook context`
-                : "Inspect configured hooks before removing anything";
-            instruction = "Review installed hook sources that affect this work. Do not remove or edit configuration without explicit user approval.";
-            break;
-        case "trim_dead_context":
-            intent = "trim_context";
-            label = `Trim context${projectSuffix}`;
-            detail = focus
-                ? `Keep only context useful to “${focus}”`
-                : "Inspect unused loaded context before changing it";
-            instruction = "Identify loaded context that is unrelated to the observed focus. Recommend scoped changes, but do not remove anything without explicit user approval.";
-            break;
-        default:
-            if (urgentLimit) {
-                intent = "protect_runway";
-                label = `Checkpoint${projectSuffix}`;
-                detail = `${limitActionName(urgentLimit)} may exhaust before reset`;
-                instruction = "Create a concise checkpoint for the observed focus and prioritize the smallest verifiable next step before the reported plan window may be exhausted.";
-                confidence = "medium";
-            }
-            else if (focus &&
-                input.focus?.confidence !== "low" &&
-                input.currentSession?.status === "active") {
-                intent = "continue_focus";
-                label = `Continue${projectSuffix}`;
-                detail = focus;
-                instruction = "Continue the observed focus with the smallest verifiable next step.";
-                confidence = input.focus?.confidence ?? input.sessionHealth.confidence;
-            }
-            else if (focus && input.focus?.confidence !== "low") {
-                intent = "resume_focus";
-                label = `Resume${projectSuffix}`;
-                detail = focus;
-                instruction = "Resume the observed focus after checking what changed since the last local activity.";
-                confidence = input.focus?.confidence ?? input.sessionHealth.confidence;
-            }
-            else {
-                intent = "inspect_current_work";
-                label = `Inspect current work${projectSuffix}`;
-                detail = "Verify the active task before making changes";
-                instruction = "Inspect the current repository and ask for the intended task if it cannot be established from local evidence.";
-                confidence = "low";
-            }
+    if (exhaustedLimit) {
+        intent = "protect_runway";
+        label = `Checkpoint${projectSuffix}`;
+        detail = `${limitActionName(exhaustedLimit)} is exhausted until reset`;
+        instruction = "Create a concise checkpoint for the observed focus and wait for the provider-reported reset before resuming work that requires this plan window.";
+        confidence = "high";
     }
-    const runway = urgentLimit
-        ? `${limitActionName(urgentLimit)}: ${roundPercent(urgentLimit.remainingPercent)}% remaining; locally projected exhaustion=${urgentLimit.projectedExhaustionAt ?? "unavailable"}; provider-reported reset=${urgentLimit.resetsAt}.`
-        : input.limits.length > 0
-            ? "No transcript-reported plan window is currently projected to exhaust before reset."
-            : "Not available; no plan window was reported in the local transcript.";
+    else {
+        switch (input.sessionHealth.recommendation) {
+            case "start_fresh":
+                intent = "start_fresh";
+                label = `Start fresh${projectSuffix}`;
+                detail = focus
+                    ? `Carry “${focus}” into a clean session`
+                    : "Carry only the concrete state you still need";
+                instruction = "Start a clean session and continue the observed focus after verifying the current repository state.";
+                break;
+            case "review_hooks":
+                intent = "review_context";
+                label = `Review context${projectSuffix}`;
+                detail = focus
+                    ? `Protect “${focus}” from unnecessary hook context`
+                    : "Inspect configured hooks before removing anything";
+                instruction = "Review installed hook sources that affect this work. Do not remove or edit configuration without explicit user approval.";
+                break;
+            case "trim_dead_context":
+                intent = "trim_context";
+                label = `Trim context${projectSuffix}`;
+                detail = focus
+                    ? `Keep only context useful to “${focus}”`
+                    : "Inspect unused loaded context before changing it";
+                instruction = "Identify loaded context that is unrelated to the observed focus. Recommend scoped changes, but do not remove anything without explicit user approval.";
+                break;
+            default:
+                if (urgentLimit) {
+                    intent = "protect_runway";
+                    label = `Checkpoint${projectSuffix}`;
+                    detail = `${limitActionName(urgentLimit)} may exhaust before reset`;
+                    instruction = "Create a concise checkpoint for the observed focus and prioritize the smallest verifiable next step before the reported plan window may be exhausted.";
+                    confidence = "medium";
+                }
+                else if (focus &&
+                    input.focus?.confidence !== "low" &&
+                    input.currentSession?.status === "active") {
+                    intent = "continue_focus";
+                    label = `Continue${projectSuffix}`;
+                    detail = focus;
+                    instruction = "Continue the observed focus with the smallest verifiable next step.";
+                    confidence = input.focus?.confidence ?? input.sessionHealth.confidence;
+                }
+                else if (focus && input.focus?.confidence !== "low") {
+                    intent = "resume_focus";
+                    label = `Resume${projectSuffix}`;
+                    detail = focus;
+                    instruction = "Resume the observed focus after checking what changed since the last local activity.";
+                    confidence = input.focus?.confidence ?? input.sessionHealth.confidence;
+                }
+                else {
+                    intent = "inspect_current_work";
+                    label = `Inspect current work${projectSuffix}`;
+                    detail = "Verify the active task before making changes";
+                    instruction = "Inspect the current repository and ask for the intended task if it cannot be established from local evidence.";
+                    confidence = "low";
+                }
+        }
+    }
+    const runway = exhaustedLimit
+        ? `${limitActionName(exhaustedLimit)}: exhausted (0% remaining); provider-reported reset=${exhaustedLimit.resetsAt}; observed=${exhaustedLimit.observedAt}.`
+        : urgentLimit
+            ? `${limitActionName(urgentLimit)}: ${roundPercent(urgentLimit.remainingPercent)}% remaining; locally projected exhaustion=${urgentLimit.projectedExhaustionAt ?? "unavailable"}; provider-reported reset=${urgentLimit.resetsAt}.`
+            : input.limits.some((limit) => limit.freshness === "current")
+                ? "No transcript-reported plan window is currently projected to exhaust before reset."
+                : input.limits.some((limit) => limit.freshness === "stale")
+                    ? "Stale; the last transcript-reported plan window is too old to use as current runway. Refresh the agent limit before acting."
+                    : "Not available; no plan window was reported in the local transcript.";
     const reportedTotalEvidence = input.currentSession?.reportedTotalTokens === undefined
         ? ""
         : `; provider-reported total tokens=${input.currentSession.reportedTotalTokens.toLocaleString("en-US")}; input/output breakdown unavailable`;
@@ -612,6 +654,8 @@ function limitActionName(limit) {
 function callCost(call) {
     if (call.usageSupport === "unsupported_token_shape")
         return undefined;
+    if (!canPriceTokenUsageAtScope(call.model, call.usage, call.usageScope === "turn" ? "request" : "aggregate"))
+        return undefined;
     return estimateTokenCostUsd(call.model, call.usage);
 }
 function inputSideTokens(call) {

package/dist/insights.js

@@ -178,6 +178,8 @@ function combinedConfidence(confidences) {
     return confidences.reduce((lowest, current) => confidenceRank[current] > confidenceRank[lowest] ? current : lowest);
 }
 function formatUsd(value) {
+    if (value > 0 && value < 0.01)
+        return "<$0.01";
     return `$${value.toFixed(2)}`;
 }
 function formatMultiplier(value) {
@@ -201,6 +203,6 @@ function stableSuffix(value) {
     return (hash >>> 0).toString(36);
 }
 function roundMoney(value) {
-    return Math.round(value * 100) / 100;
+    return Math.round(value * 10_000) / 10_000;
 }
 //# sourceMappingURL=insights.js.map

package/dist/localAgentFormats/gemini.d.ts

@@ -0,0 +1,55 @@
+import type { TokenUsage } from "../modelPricing.js";
+export type GeminiCacheAccounting = "included" | "none" | "unknown";
+export type GeminiTokenEvidence = {
+    /** Raw provider fields. Invalid or absent fields remain absent. */
+    readonly input?: number;
+    readonly output?: number;
+    readonly cached?: number;
+    readonly thoughts?: number;
+    readonly tool?: number;
+    readonly total?: number;
+    /** Whether the reported input count includes the cached count. */
+    readonly cacheAccounting: GeminiCacheAccounting;
+};
+/**
+ * Structural call type that can be wired into LocalAgentCall once the Gemini
+ * registry descriptor is enabled. It deliberately exposes no prompt content
+ * or raw project hash.
+ */
+export type GeminiParsedCall = {
+    readonly agent: "gemini-cli";
+    readonly callId: string;
+    readonly model: string;
+    readonly timestamp: string;
+    readonly startedAt?: string;
+    readonly project?: string;
+    readonly workingDirectory?: string;
+    readonly sessionId?: string;
+    readonly usageScope: "turn";
+    readonly usageSupport: "complete" | "unsupported_token_shape";
+    readonly reportedTotalTokens?: number;
+    readonly sourceVersion?: string;
+    readonly usage: TokenUsage;
+    readonly geminiTokenEvidence: GeminiTokenEvidence;
+};
+export type GeminiParseDiagnosticCode = "malformed_json" | "malformed_jsonl" | "unsupported_token_shape" | "missing_timestamp";
+export type GeminiParseDiagnostic = {
+    readonly code: GeminiParseDiagnosticCode;
+    readonly count: number;
+};
+export type GeminiParseOptions = {
+    /** Caller-supplied path, including recursive chats/subagent paths. */
+    readonly filePath: string;
+    readonly sinceMs?: number;
+};
+export type GeminiParseResult = {
+    readonly calls: GeminiParsedCall[];
+    readonly diagnostics: GeminiParseDiagnostic[];
+};
+/** Parse a Gemini chat file according to its caller-supplied extension. */
+export declare function parseGeminiSession(content: string, options: GeminiParseOptions): GeminiParseResult;
+/** Parse the legacy whole-conversation JSON representation. */
+export declare function parseGeminiJsonSession(content: string, options: GeminiParseOptions): GeminiParseResult;
+/** Parse the append-only current JSONL message representation. */
+export declare function parseGeminiJsonlSession(content: string, options: GeminiParseOptions): GeminiParseResult;
+//# sourceMappingURL=gemini.d.ts.map