@agent-finops/core 0.2.2 → 0.4.0

package/dist/planDetection.d.ts

@@ -27,6 +27,12 @@ export type DetectedPlan = {
     /** Human-readable plan label; falls back to the raw local identifier. */
     planLabel: string;
     billing: "subscription" | "api_key" | "unknown";
+    /**
+     * Evidence of plan-limit pressure found in the agent's local config —
+     * e.g. Claude Code records when extra-usage credits ran out. This is the
+     * difference between "you might hit limits" and "you ARE hitting limits".
+     */
+    limitSignal?: string;
     /** Where the detection came from (file or "--plan override"). */
     source: string;
 };

package/dist/planDetection.js

@@ -46,12 +46,20 @@ async function detectClaudePlan(configPath) {
     else {
         planLabel = organizationType ?? rateLimitTier ?? "unknown";
     }
+    // Claude Code records why extra usage is unavailable; "out_of_credits"
+    // means the user already exhausted their overage pool — hard evidence of
+    // limit pressure, not a guess.
+    const extraUsageReason = isRecord(config) ? stringOf(config.cachedExtraUsageDisabledReason) : undefined;
+    const limitSignal = extraUsageReason === "out_of_credits"
+        ? "extra-usage credits exhausted"
+        : undefined;
     return {
         agent: "claude-code",
         provider: "anthropic",
         planId,
         planLabel,
         billing: billingType === "stripe_subscription" ? "subscription" : billingType ? "unknown" : "unknown",
+        limitSignal,
         source: configPath
     };
 }

package/dist/planMath.js

@@ -59,10 +59,17 @@ export function computePlanChecks(records, detectedPlans = []) {
                     (effectiveSavings ? `, ~$${effectiveSavings.toFixed(2)}/mo cheaper than paying per token.` : `.`);
             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.
+                const evidence = detected?.limitSignal
+                    ? `your local config shows ${detected.limitSignal} — you ARE hitting your plan's limits`
+                    : `if you're hitting rate limits`;
                 upgradeHint = nextTier
-                    ? `usage runs past what ${detectedKnown.name} typically covers (~$${detectedKnown.coversUpToUsd}/mo) — if you're hitting rate limits, ${nextTier.name} ($${nextTier.monthlyUsd}/mo) is the next tier; trimming context (below) buys headroom without upgrading.`
+                    ? `usage runs past what ${detectedKnown.name} typically covers (~$${detectedKnown.coversUpToUsd}/mo); ${evidence}: ${nextTier.name} ($${nextTier.monthlyUsd}/mo) is the next tier; trimming context (below) buys headroom without upgrading.`
                     : `usage runs past what ${detectedKnown.name} typically covers (~$${detectedKnown.coversUpToUsd}/mo) — trimming context (below) is the main headroom lever.`;
             }
+            else if (detected?.limitSignal) {
+                upgradeHint = `your local config shows ${detected.limitSignal} — you're hitting your plan's limits; trimming context (below) buys headroom without upgrading.`;
+            }
         }
         else if (detected) {
             // Detected a plan we can't price (e.g. an unrecognized tier): state the

package/package.json

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