@agent-finops/core 0.1.3 → 0.1.4

package/dist/analyze.js

@@ -165,7 +165,11 @@ export function generateRecommendations(records) {
             relatedKeys: unique(highInputTokenRecords.map((record) => record.model))
         });
     }
-    const repeatedOperations = repeatedValues(records.map((record) => record.operation).filter(isPresent));
+    // Session aggregates from local agent logs share one operation label per
+    // agent — that's aggregation, not repetition, and a result cache is not a
+    // real lever for interactive coding sessions. Exclude them here.
+    const cacheableRecords = records.filter((record) => record.providerCostType !== "local_agent_logs");
+    const repeatedOperations = repeatedValues(cacheableRecords.map((record) => record.operation).filter(isPresent));
     if (repeatedOperations.length > 0) {
         recommendations.push({
             id: "caching",
@@ -174,8 +178,8 @@ export function generateRecommendations(records) {
             whyItMatters: "Repeated AI calls are the easiest spend to defend cutting because they usually do not change the customer experience.",
             nextAction: "Add a local cache or memoization policy for repeated operation labels before expanding this workflow to more clients.",
             priority: "medium",
-            estimatedImpactUsd: roundMoney(sumRecords(records.filter((record) => repeatedOperations.includes(record.operation ?? ""))) * impactRatios.caching),
-            confidence: combinedConfidence(records.map((record) => record.costConfidence)),
+            estimatedImpactUsd: roundMoney(sumRecords(cacheableRecords.filter((record) => repeatedOperations.includes(record.operation ?? ""))) * impactRatios.caching),
+            confidence: combinedConfidence(cacheableRecords.map((record) => record.costConfidence)),
             relatedKeys: repeatedOperations
         });
     }

package/dist/cutList.d.ts

@@ -19,6 +19,12 @@ export type CutAction = {
     affectedSpendUsd: number;
     /** How many usage records this action is grounded in. */
     recordCount: number;
+    /**
+     * What one record represents, for honest grounding lines. Local agent logs
+     * aggregate a day of sessions into one record, so calling those "calls"
+     * overstates precision to the exact audience that will check.
+     */
+    recordUnit: "calls" | "session-days" | "tools";
     /** Lowest confidence of the underlying records (drives how we caveat $). */
     confidence: CostConfidence;
     kind: "model_downgrade" | "context_trim" | "cache" | "batch";

package/dist/cutList.js

@@ -111,6 +111,7 @@ function modelDowngradeActions(records) {
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
+            recordUnit: groupRecords.every(isLocalAgentRecord) ? "session-days" : "calls",
             recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "model_downgrade"
@@ -136,13 +137,22 @@ function contextTrimActions(records) {
         // input-token cost on these large calls.
         const windowSavings = affectedSpendUsd * 0.25;
         const monthlySavings = roundMoney(toMonthly(windowSavings, window));
+        const sessionAggregates = groupRecords.every(isLocalAgentRecord);
+        const count = groupRecords.length;
         actions.push({
             id: `trim-${slug(operation)}`,
-            title: `Trim oversized context on ${operation}`,
-            action: `Cap retrieval/prompt size on ${groupRecords.length} large ${operation} call${groupRecords.length === 1 ? "" : "s"} (>=100k input tokens) before they fan out.`,
+            title: sessionAggregates
+                ? `Trim heavy context in ${operation}`
+                : `Trim oversized context on ${operation}`,
+            // Coding-agent sessions are aggregated per day — the honest levers are
+            // the context loaded every turn, not "prompt size" on a single call.
+            action: sessionAggregates
+                ? `${count} session-day${count === 1 ? "" : "s"} averaged >=100k input tokens per record. Cut dead context first (unused MCP servers/skills — see above), keep CLAUDE.md/AGENTS.md lean, and avoid pulling whole directories into context.`
+                : `Cap retrieval/prompt size on ${count} large ${operation} call${count === 1 ? "" : "s"} (>=100k input tokens) before they fan out.`,
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
-            recordCount: groupRecords.length,
+            recordCount: count,
+            recordUnit: sessionAggregates ? "session-days" : "calls",
             recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "context_trim"
@@ -157,6 +167,13 @@ function cacheActions(records) {
         if (!record.operation) {
             continue;
         }
+        // Local agent logs aggregate interactive sessions under one operation
+        // label ("claude-code sessions"). Those are NOT repeated identical calls —
+        // a result cache is not a real lever there (prompt caching already applies
+        // and is priced into the estimate), so recommending one would be wrong.
+        if (isLocalAgentRecord(record)) {
+            continue;
+        }
         counts.set(record.operation, [...(counts.get(record.operation) ?? []), record]);
     }
     const actions = [];
@@ -175,6 +192,7 @@ function cacheActions(records) {
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
+            recordUnit: "calls",
             recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "cache"
@@ -206,6 +224,7 @@ function batchActions(records) {
             estimatedMonthlySavingsUsd: monthlySavings,
             affectedSpendUsd,
             recordCount: groupRecords.length,
+            recordUnit: "calls",
             recordIds: groupRecords.map((record) => record.id),
             confidence: combinedConfidence(groupRecords.map((record) => record.costConfidence)),
             kind: "batch"
@@ -213,6 +232,10 @@ function batchActions(records) {
     }
     return actions;
 }
+/** Records ingested from local agent transcripts (day-level session aggregates). */
+function isLocalAgentRecord(record) {
+    return record.providerCostType === "local_agent_logs";
+}
 /** Number of distinct calendar days the records span (min 1). */
 function windowDays(records) {
     const days = new Set(records.map((record) => record.timestamp.slice(0, 10)));

package/dist/deadContext.js

@@ -135,6 +135,7 @@ export function deadContextCutAction(result) {
         estimatedMonthlySavingsUsd: result.monthlyUsd,
         affectedSpendUsd: result.monthlyUsd,
         recordCount: result.deadCount,
+        recordUnit: "tools",
         // Dead-context savings come from inventory, not priced usage records, so
         // there are no record IDs to dedupe against the spend-based cut actions.
         recordIds: [],

package/dist/planMath.js

@@ -31,15 +31,19 @@ export function computePlanChecks(records) {
         const candidates = subscriptionPlans.filter((plan) => plan.agent === agent);
         const suggested = candidates.find((plan) => monthly <= plan.coversUpToUsd) ?? candidates[candidates.length - 1];
         const savings = suggested ? roundMoney(monthly - suggested.monthlyUsd) : undefined;
+        // Always state the projection basis: this number divides by ACTIVE days
+        // (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"}`;
         let headline;
         if (!suggested) {
-            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates.`;
+            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}).`;
         }
         else if (typeof savings === "number" && savings > 0) {
-            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates — ${suggested.name} ($${suggested.monthlyUsd}/mo) likely covers this, ~$${savings.toFixed(2)}/mo cheaper than paying per token.`;
+            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates (${basis}) — ${suggested.name} ($${suggested.monthlyUsd}/mo) likely covers this, ~$${savings.toFixed(2)}/mo cheaper than paying per token.`;
         }
         else {
-            headline = `${agent}: ~$${monthly.toFixed(2)}/mo at API rates — within ${suggested.name} ($${suggested.monthlyUsd}/mo); pay-as-you-go API could be cheaper if you drop the subscription.`;
+            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,

package/package.json

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