@agent-finops/core 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from "./toolInvocations.js";
 export * from "./insights.js";
 export * from "./localAgentLogs.js";
 export * from "./modelPricing.js";
+export * from "./planDetection.js";
 export * from "./planMath.js";
 export * from "./sampleData.js";
 export * from "./scanGuard.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./toolInvocations.js";
 export * from "./insights.js";
 export * from "./localAgentLogs.js";
 export * from "./modelPricing.js";
+export * from "./planDetection.js";
 export * from "./planMath.js";
 export * from "./sampleData.js";
 export * from "./scanGuard.js";

package/dist/planDetection.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Local subscription-plan detection — the zero-friction, fully legitimate
+ * path to "the tool knows who it's talking to".
+ *
+ * Consumer subscriptions (Claude Max/Pro, ChatGPT Plus/Pro) have NO billing
+ * API, so there is nothing to OAuth against. But the coding agents already
+ * did their own OAuth and persist what they learned on disk, right next to
+ * the transcripts we already read:
+ *
+ *  - Claude Code: `~/.claude.json` -> `oauthAccount.organizationType`
+ *    ("claude_max" | "claude_pro" | ...), `organizationRateLimitTier`
+ *    ("default_claude_max_5x" | "default_claude_max_20x" | ...), and
+ *    `billingType` ("stripe_subscription" | ...).
+ *  - Codex CLI: `~/.codex/auth.json` -> `auth_mode` ("chatgpt" | "apikey");
+ *    in chatgpt mode the locally stored id_token's claims carry
+ *    `chatgpt_plan_type` ("plus" | "pro" | ...).
+ *
+ * Privacy contract: this module reads ONLY the whitelisted plan/billing
+ * fields above. Token values are never read into results, never returned,
+ * never logged. Everything is local; no network calls.
+ */
+export type DetectedPlan = {
+    agent: "claude-code" | "codex";
+    provider: "anthropic" | "openai";
+    /** Matches a `subscriptionPlans` id when the plan is one we can price. */
+    planId?: string;
+    /** Human-readable plan label; falls back to the raw local identifier. */
+    planLabel: string;
+    billing: "subscription" | "api_key" | "unknown";
+    /** Where the detection came from (file or "--plan override"). */
+    source: string;
+};
+export type PlanDetectionOptions = {
+    /** Default: ~/.claude.json (Claude Code's top-level config). */
+    claudeConfigPath?: string;
+    /** Default: ~/.codex/auth.json. */
+    codexAuthPath?: string;
+};
+/** Detect the plans this machine's coding agents are signed in with. */
+export declare function detectLocalPlans(options?: PlanDetectionOptions): Promise<DetectedPlan[]>;
+//# sourceMappingURL=planDetection.d.ts.map

package/dist/planDetection.js

@@ -0,0 +1,139 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Detect the plans this machine's coding agents are signed in with. */
+export async function detectLocalPlans(options = {}) {
+    const home = homedir();
+    const claudeConfigPath = options.claudeConfigPath ?? join(home, ".claude.json");
+    const codexAuthPath = options.codexAuthPath ?? join(home, ".codex", "auth.json");
+    const plans = [];
+    const claude = await detectClaudePlan(claudeConfigPath);
+    if (claude)
+        plans.push(claude);
+    const codex = await detectCodexPlan(codexAuthPath);
+    if (codex)
+        plans.push(codex);
+    return plans;
+}
+async function detectClaudePlan(configPath) {
+    const config = await readJsonQuietly(configPath);
+    const account = isRecord(config) && isRecord(config.oauthAccount) ? config.oauthAccount : undefined;
+    if (!account)
+        return undefined;
+    const organizationType = stringOf(account.organizationType);
+    const rateLimitTier = stringOf(account.organizationRateLimitTier) ?? stringOf(account.userRateLimitTier);
+    const billingType = stringOf(account.billingType);
+    if (!organizationType && !rateLimitTier)
+        return undefined;
+    let planId;
+    let planLabel;
+    if (rateLimitTier && /max_20x/i.test(rateLimitTier)) {
+        planId = "claude-max-20x";
+        planLabel = "Claude Max 20x";
+    }
+    else if (rateLimitTier && /max_5x/i.test(rateLimitTier)) {
+        planId = "claude-max-5x";
+        planLabel = "Claude Max 5x";
+    }
+    else if (organizationType === "claude_pro" || (rateLimitTier && /pro/i.test(rateLimitTier))) {
+        planId = "claude-pro";
+        planLabel = "Claude Pro";
+    }
+    else if (organizationType === "claude_max") {
+        // Max org but an unrecognized tier string: say what we know, price nothing.
+        planLabel = `Claude Max (tier: ${rateLimitTier ?? "unknown"})`;
+    }
+    else {
+        planLabel = organizationType ?? rateLimitTier ?? "unknown";
+    }
+    return {
+        agent: "claude-code",
+        provider: "anthropic",
+        planId,
+        planLabel,
+        billing: billingType === "stripe_subscription" ? "subscription" : billingType ? "unknown" : "unknown",
+        source: configPath
+    };
+}
+async function detectCodexPlan(authPath) {
+    const auth = await readJsonQuietly(authPath);
+    if (!isRecord(auth))
+        return undefined;
+    const authMode = stringOf(auth.auth_mode);
+    if (authMode === "apikey") {
+        return {
+            agent: "codex",
+            provider: "openai",
+            planLabel: "API key (pay per token)",
+            billing: "api_key",
+            source: authPath
+        };
+    }
+    const tokens = isRecord(auth.tokens) ? auth.tokens : undefined;
+    const idToken = tokens ? stringOf(tokens.id_token) : undefined;
+    const claims = idToken ? decodeJwtClaims(idToken) : undefined;
+    const authClaims = claims && isRecord(claims["https://api.openai.com/auth"])
+        ? claims["https://api.openai.com/auth"]
+        : undefined;
+    const planType = authClaims ? stringOf(authClaims.chatgpt_plan_type) : undefined;
+    if (!planType && authMode !== "chatgpt")
+        return undefined;
+    let planId;
+    let planLabel;
+    if (planType === "plus") {
+        planId = "chatgpt-plus";
+        planLabel = "ChatGPT Plus";
+    }
+    else if (planType === "pro") {
+        planId = "chatgpt-pro";
+        planLabel = "ChatGPT Pro";
+    }
+    else if (planType) {
+        // e.g. "team", "prolite": name it honestly, don't guess a price.
+        planLabel = `ChatGPT (plan: ${planType})`;
+    }
+    else {
+        planLabel = "ChatGPT (plan unknown)";
+    }
+    return {
+        agent: "codex",
+        provider: "openai",
+        planId,
+        planLabel,
+        billing: "subscription",
+        source: authPath
+    };
+}
+/**
+ * Decode a JWT's claims segment locally (base64url JSON). No verification —
+ * we are reading our own user's already-trusted local file for display
+ * metadata, not authenticating anything.
+ */
+function decodeJwtClaims(jwt) {
+    const segment = jwt.split(".")[1];
+    if (!segment)
+        return undefined;
+    try {
+        const json = Buffer.from(segment, "base64url").toString("utf8");
+        const parsed = JSON.parse(json);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readJsonQuietly(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function stringOf(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=planDetection.js.map

package/dist/planMath.d.ts

@@ -1,3 +1,4 @@
+import type { DetectedPlan } from "./planDetection.js";
 import type { UsageRecord } from "./schema.js";
 /**
  * Plan-price math: compares API-equivalent usage (from local agent logs)
@@ -36,6 +37,10 @@ export type PlanCheck = {
      * money's worth? Present only when a plan covers the usage.
      */
     valueMultiple?: number;
+    /** The plan actually detected on this machine (or --plan override), if any. */
+    detectedPlan?: DetectedPlan;
+    /** Set when projected usage exceeds what the detected tier typically covers. */
+    upgradeHint?: string;
     /** One-line, render-ready verdict. */
     headline: string;
 };
@@ -43,6 +48,11 @@ export type PlanCheck = {
  * Compute per-agent plan checks from usage records. Only records that came
  * from local agent logs participate (billing-API records already have real
  * prices and a real plan behind them).
+ *
+ * When `detectedPlans` carries a locally detected plan (or --plan override)
+ * for an agent, the check speaks in facts ("you're on Claude Max 5x") instead
+ * of guesses ("Max 20x likely covers this") — and warns when projected usage
+ * exceeds what the detected tier typically covers.
  */
-export declare function computePlanChecks(records: UsageRecord[]): PlanCheck[];
+export declare function computePlanChecks(records: UsageRecord[], detectedPlans?: DetectedPlan[]): PlanCheck[];
 //# sourceMappingURL=planMath.d.ts.map

package/dist/planMath.js

@@ -10,8 +10,13 @@ const localLogCostType = "local_agent_logs";
  * Compute per-agent plan checks from usage records. Only records that came
  * from local agent logs participate (billing-API records already have real
  * prices and a real plan behind them).
+ *
+ * When `detectedPlans` carries a locally detected plan (or --plan override)
+ * for an agent, the check speaks in facts ("you're on Claude Max 5x") instead
+ * of guesses ("Max 20x likely covers this") — and warns when projected usage
+ * exceeds what the detected tier typically covers.
  */
-export function computePlanChecks(records) {
+export function computePlanChecks(records, detectedPlans = []) {
     const localRecords = records.filter((record) => record.providerCostType === localLogCostType &&
         (record.agentId === "claude-code" || record.agentId === "codex") &&
         typeof record.amountUsd === "number");
@@ -35,25 +40,61 @@ export function computePlanChecks(records) {
         // (days with usage), which can differ from the calendar window shown
         // elsewhere on the readout — a technical reader will divide and check.
         const basis = `projected from ${windowDays} active day${windowDays === 1 ? "" : "s"}`;
-        const covered = suggested && typeof savings === "number" && savings > 0;
-        const valueMultiple = covered ? Math.round((monthly / suggested.monthlyUsd) * 10) / 10 : undefined;
+        const detected = detectedPlans.find((plan) => plan.agent === agent);
+        const detectedKnown = detected?.planId
+            ? subscriptionPlans.find((plan) => plan.id === detected.planId)
+            : undefined;
         let headline;
-        if (!suggested) {
-            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}).`;
+        let valueMultiple;
+        let upgradeHint;
+        let effectiveSavings;
+        if (detectedKnown) {
+            // FACT mode: we know the user's actual plan from local agent config.
+            valueMultiple = Math.round((monthly / detectedKnown.monthlyUsd) * 10) / 10;
+            const savingsVsApi = roundMoney(monthly - detectedKnown.monthlyUsd);
+            effectiveSavings = savingsVsApi > 0 ? savingsVsApi : undefined;
+            headline =
+                `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — you're on ${detectedKnown.name} ` +
+                    `($${detectedKnown.monthlyUsd}/mo, detected locally): ~${valueMultiple}× the plan price in usage` +
+                    (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);
+                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) — trimming context (below) is the main headroom lever.`;
+            }
         }
-        else if (covered) {
-            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — ${suggested.name} ($${suggested.monthlyUsd}/mo) likely covers this. You're getting ~${valueMultiple}× the plan price in usage, ~$${savings.toFixed(2)}/mo cheaper than paying per token.`;
+        else if (detected) {
+            // 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}) — you're on ${detected.planLabel} ` +
+                    `(detected locally; price not in our table)` +
+                    (suggested ? `; closest known plan: ${suggested.name} ($${suggested.monthlyUsd}/mo).` : `.`);
         }
         else {
-            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — within ${suggested.name} ($${suggested.monthlyUsd}/mo); pay-as-you-go API could be cheaper if you drop the subscription.`;
+            const covered = suggested && typeof savings === "number" && savings > 0;
+            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}).`;
+            }
+            else if (covered) {
+                headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — ${suggested.name} ($${suggested.monthlyUsd}/mo) likely covers this. You're getting ~${valueMultiple}× the plan price in usage, ~$${savings.toFixed(2)}/mo cheaper than paying per token.`;
+            }
+            else {
+                headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — within ${suggested.name} ($${suggested.monthlyUsd}/mo); pay-as-you-go API could be cheaper if you drop the subscription.`;
+            }
         }
         checks.push({
             agent,
             apiEquivalentMonthlyUsd: monthly,
             windowDays,
-            suggestedPlan: suggested,
-            monthlySavingsVsApiUsd: covered ? savings : undefined,
+            suggestedPlan: detectedKnown ?? suggested,
+            monthlySavingsVsApiUsd: effectiveSavings,
             valueMultiple,
+            detectedPlan: detected,
+            upgradeHint,
             headline
         });
     }

package/package.json

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