@agent-finops/core 0.8.0 → 0.8.1

package/dist/glance.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";
+    }
+    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 = 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.";
+    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`;

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/modelPricing.d.ts

@@ -7,7 +7,7 @@
  * matched top-down; first match wins. Unknown models return undefined so
  * callers can label the record "missing" instead of inventing a number.
  */
-export declare const PRICING_TABLE_AS_OF = "2026-08-13";
+export declare const PRICING_TABLE_AS_OF = "2026-08-14";
 export type TokenUsage = {
     /** Billable, uncached input tokens. */
     inputTokens: number;

package/dist/modelPricing.js

@@ -7,10 +7,13 @@
  * matched top-down; first match wins. Unknown models return undefined so
  * callers can label the record "missing" instead of inventing a number.
  */
-export const PRICING_TABLE_AS_OF = "2026-08-13";
+export const PRICING_TABLE_AS_OF = "2026-08-14";
 const pricingRules = [
     // Anthropic
     { match: /^claude-fable-5/i, inputPerM: 10, outputPerM: 50 },
+    { match: /^claude-mythos-5/i, inputPerM: 10, outputPerM: 50 },
+    { match: /^claude-opus-5/i, inputPerM: 5, outputPerM: 25 },
+    { match: /^claude-sonnet-5/i, inputPerM: 2, outputPerM: 10 },
     { match: /^claude-opus-4-[5-9]/i, inputPerM: 5, outputPerM: 25 },
     { match: /^claude-opus-4(-[01])?$/i, inputPerM: 15, outputPerM: 75 },
     { match: /^claude-sonnet-4/i, inputPerM: 3, outputPerM: 15 },

package/dist/planMath.js

@@ -54,9 +54,9 @@ export function computePlanChecks(records, detectedPlans = []) {
             const savingsVsApi = roundMoney(monthly - detectedKnown.monthlyUsd);
             effectiveSavings = savingsVsApi > 0 ? savingsVsApi : undefined;
             headline =
-                `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — compared with ${detectedKnown.name} ` +
+                `${agent}: ~${formatUsd(monthly)}/mo at API rates (${basis}) — compared with ${detectedKnown.name} ` +
                     `($${detectedKnown.monthlyUsd}/mo; label detected locally): ~${valueMultiple}× the plan price in API-equivalent usage` +
-                    (effectiveSavings ? `, a ~$${effectiveSavings.toFixed(2)}/mo value difference to investigate.` : `.`);
+                    (effectiveSavings ? `, a ~${formatUsd(effectiveSavings)}/mo value difference to investigate.` : `.`);
             if (monthly > detectedKnown.coversUpToUsd) {
                 const nextTier = subscriptionPlans.find((plan) => plan.agent === agent && plan.coversUpToUsd > detectedKnown.coversUpToUsd);
                 // A local limit signal upgrades "might hit limits" to hard evidence.
@@ -75,7 +75,7 @@ export function computePlanChecks(records, detectedPlans = []) {
             // Detected a plan we can't price (e.g. an unrecognized tier): state the
             // fact, then fall back to suggestion math without pretending certainty.
             headline =
-                `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — compared with ${detected.planLabel} ` +
+                `${agent}: ~${formatUsd(monthly)}/mo at API rates (${basis}) — compared with ${detected.planLabel} ` +
                     `(label detected locally; price not in our table)` +
                     (suggested ? `; reference listed plan: ${suggested.name} ($${suggested.monthlyUsd}/mo).` : `.`);
         }
@@ -84,13 +84,13 @@ export function computePlanChecks(records, detectedPlans = []) {
             valueMultiple = covered ? Math.round((monthly / suggested.monthlyUsd) * 10) / 10 : undefined;
             effectiveSavings = covered ? savings : undefined;
             if (!suggested) {
-                headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}).`;
+                headline = `${agent}: ~${formatUsd(monthly)}/mo at API rates (${basis}).`;
             }
             else if (covered) {
-                headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — ${suggested.name} is a $${suggested.monthlyUsd}/mo reference point. That is ~${valueMultiple}× the plan price in API-equivalent usage, a ~$${savings.toFixed(2)}/mo value difference to investigate; it does not prove plan coverage.`;
+                headline = `${agent}: ~${formatUsd(monthly)}/mo at API rates (${basis}) — ${suggested.name} is a $${suggested.monthlyUsd}/mo reference point. That is ~${valueMultiple}× the plan price in API-equivalent usage, a ~${formatUsd(savings)}/mo value difference to investigate; it does not prove plan coverage.`;
             }
             else {
-                headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — below the $${suggested.monthlyUsd}/mo price of ${suggested.name}; compare account benefits and provider-reported charges before changing plans.`;
+                headline = `${agent}: ~${formatUsd(monthly)}/mo at API rates (${basis}) — below the $${suggested.monthlyUsd}/mo price of ${suggested.name}; compare account benefits and provider-reported charges before changing plans.`;
             }
         }
         checks.push({
@@ -108,6 +108,11 @@ export function computePlanChecks(records, detectedPlans = []) {
     return checks.sort((left, right) => right.apiEquivalentMonthlyUsd - left.apiEquivalentMonthlyUsd);
 }
 function roundMoney(value) {
-    return Math.round(value * 100) / 100;
+    return Math.round(value * 10_000) / 10_000;
+}
+function formatUsd(value) {
+    if (value > 0 && value < 0.01)
+        return "<$0.01";
+    return `$${value.toFixed(2)}`;
 }
 //# sourceMappingURL=planMath.js.map

package/dist/providerConnectors.js

@@ -1591,16 +1591,32 @@ export function createProviderConnection(input) {
     const source = createProviderConnectorStub(input.provider, "provider_api", input.fetchedAt);
     const total = input.totalUsd === null ? "an unavailable financial headline" : formatProviderUsd(input.totalUsd);
     const financialEvidence = input.completeness ?? "verified";
+    const fulfilledBySuccessfulSync = new Set(providerConnectionPrerequisiteFields[input.provider] ?? [
+        "approved account/API/export source"
+    ]);
+    const fieldsMissing = source.fieldsMissing.filter((field) => !fulfilledBySuccessfulSync.has(field));
+    if (financialEvidence === "missing" || input.totalUsd === null) {
+        fieldsMissing.push("provider financial headline");
+    }
     return {
         ...source,
         id: input.sourceId ?? source.id,
         validationCoverage: validationCoverageForCompletedProviderSync(input.provider),
         financialEvidence,
         authReference: input.authReference,
-        fieldsMissing: financialEvidence === "missing" ? ["provider financial headline"] : [],
+        // A successful request satisfies credentials/setup, not permanent product
+        // coverage gaps such as invoice settlement or unsupported usage families.
+        fieldsMissing: Array.from(new Set(fieldsMissing)),
         scope: `${source.scope} Last successful pull produced ${input.verifiedRecordCount} record(s); financial evidence: ${financialEvidence}; financial headline: ${total}.`
     };
 }
+const providerConnectionPrerequisiteFields = {
+    openai: ["OpenAI Admin API key reference"],
+    anthropic: ["Anthropic Admin API key reference"],
+    cursor: ["Cursor team Admin API key reference"],
+    "github-copilot": ["GitHub admin token reference and organization or enterprise slug"],
+    codex: ["OpenAI Admin API key reference"]
+};
 function validationCoverageForCompletedProviderSync(provider) {
     if (provider === "openai" || provider === "anthropic")
         return "live_verified";