@agent-finops/core 0.5.8 → 0.6.0

package/dist/contextHealth.js

@@ -8,8 +8,10 @@ const DEFAULT_WINDOW_DAYS = 30;
  * this contract so their recommendation and provenance cannot drift.
  */
 export async function loadContextHealth(calls, options = {}) {
-    const inventory = options.inventory ?? await loadAgentInventory(options);
-    const invocations = options.invocations ?? await loadToolInvocations(options);
+    const [inventory, invocations] = await Promise.all([
+        options.inventory ?? loadAgentInventory(options),
+        options.invocations ?? loadToolInvocations(options)
+    ]);
     const windowDays = options.windowDays ?? DEFAULT_WINDOW_DAYS;
     const deadContext = computeDeadContext(inventory.items, invocations, {
         windowDays,
@@ -46,11 +48,17 @@ export function buildContextHealth(input = {}) {
     if (currentSession) {
         evidence.push({
             kind: "session_history",
-            summary: currentSession.ratioToMedian === null
-                ? `${currentSession.totalTokens.toLocaleString("en-US")} local transcript tokens; no same-agent baseline yet.`
-                : `${currentSession.totalTokens.toLocaleString("en-US")} local transcript tokens, ${currentSession.ratioToMedian}× the median of ${currentSession.comparisonSessions} prior same-agent session${currentSession.comparisonSessions === 1 ? "" : "s"}.`,
-            source: `${currentSession.agent} local transcripts`,
-            confidence: currentSession.ratioToMedian === null ? "observed" : "derived"
+            summary: currentSession.usageSource === "not_available"
+                ? "Latest-turn context usage was not present in this transcript format; cumulative session usage was excluded from Context Health comparison."
+                : currentSession.ratioToMedian === null
+                    ? `${currentSession.contextTokens.toLocaleString("en-US")} input context tokens in the latest observed turn; no comparable baseline yet.`
+                    : `${currentSession.contextTokens.toLocaleString("en-US")} input context tokens in the latest observed turn, ${currentSession.ratioCapped ? "at least " : ""}${currentSession.ratioToMedian}× the median of ${currentSession.comparisonSessions} comparable prior session${currentSession.comparisonSessions === 1 ? "" : "s"}.`,
+            source: `${currentSession.agent} local transcript latest-turn usage`,
+            confidence: currentSession.usageSource === "not_available"
+                ? "unmeasured"
+                : currentSession.ratioToMedian === null
+                    ? "observed"
+                    : "derived"
         });
     }
     if ((contextChurn.compactionEvents ?? 0) > 0) {
@@ -86,8 +94,8 @@ export function buildContextHealth(input = {}) {
     for (const hook of hookItems.slice(0, 3)) {
         evidence.push({
             kind: "hook_config",
-            summary: `${hook.group ?? hook.name} is configured on ${hook.event ?? "a lifecycle event"} for ${hostLabel(hook.host)}.`,
-            source: hook.path ?? "installed plugin metadata",
+            summary: `${safeHookCategory(hook)} is configured for ${hostLabel(hook.host)}.`,
+            source: safeHookProvenance(hook),
             confidence: "unmeasured"
         });
     }
@@ -102,7 +110,7 @@ export function buildContextHealth(input = {}) {
     if (deadContext.deadCount > 0) {
         evidence.push({
             kind: "inventory_usage",
-            summary: `${deadContext.deadCount} of ${deadContext.loadedCount} discoverable/schema-loaded item${deadContext.loadedCount === 1 ? "" : "s"} were not invoked in the parsed window.`,
+            summary: `${deadContext.deadCount} of ${deadContext.loadedCount} configured item${deadContext.loadedCount === 1 ? "" : "s"} had no matching invocation in the parsed window; configuration alone does not prove their definitions were loaded every turn.`,
             source: "local inventory compared with local transcript invocations",
             confidence: deadContext.unmeasuredDeadCount > 0 ? "unmeasured" : "derived"
         });
@@ -110,7 +118,7 @@ export function buildContextHealth(input = {}) {
     if (activation.invocationUnobservableItems > 0) {
         evidence.push({
             kind: "inventory_usage",
-            summary: `${activation.invocationUnobservableItems} configured item${activation.invocationUnobservableItems === 1 ? "" : "s"} cannot be matched to an explicit invocation in the available transcript format and were excluded from never-invoked counts.`,
+            summary: `${activation.invocationUnobservableItems} configured item${activation.invocationUnobservableItems === 1 ? "" : "s"} cannot be matched reliably to an explicit invocation or one concrete configuration scope in the available transcript format and were excluded from never-invoked counts.`,
             source: "local inventory and transcript capability metadata",
             confidence: "unmeasured"
         });
@@ -145,9 +153,9 @@ export function buildContextHealth(input = {}) {
         },
         caveats: [
             "Hook commands are never run by aibill. Configuration proves activation, but runtime output and token size remain unmeasured.",
-            "A session comparison uses local transcript token totals from the same coding agent; it is not a provider charge or a universal context-window measurement.",
-            "Never-invoked means no matching invocation was observed in the selected local transcript window, not that an item has no future value.",
-            "Items whose host transcript does not expose explicit invocation evidence are excluded from never-invoked counts.",
+            "A Context Health comparison uses latest-turn input context from comparable local sessions, never cumulative session lifetime usage. It is not a provider charge or a universal context-window measurement.",
+            "No matching invocation means none was observed in the selected local transcript window. Configuration alone does not prove an item was loaded every turn or that it has no future value.",
+            "Items whose host transcript does not expose explicit invocation evidence, or whose evidence cannot be attributed to one concrete configuration scope, are excluded from never-invoked counts.",
             "Repeated-read evidence includes only explicit file-read tools and returns basenames only. Shell commands are not guessed to be reads.",
             "Compaction counts come from explicit transcript markers; absence means not observed in the parsed format, not proof that compaction never occurred.",
             "No per-session savings claim is made without an observed counterfactual baseline."
@@ -155,16 +163,8 @@ export function buildContextHealth(input = {}) {
     };
 }
 function contextDecision(input) {
-    const ratio = input.currentSession?.ratioToMedian;
-    if (ratio !== null && ratio !== undefined && ratio >= 1.5) {
-        return {
-            status: "start_fresh",
-            recommendation: "start_fresh",
-            headline: `This session is ${ratio}× your same-agent token median.`,
-            action: "Start fresh before a new task; keep this session only while its existing context is directly useful.",
-            confidence: input.currentSession.comparisonSessions >= 3 ? "high" : "medium"
-        };
-    }
+    // Explicit compaction markers are direct evidence and outrank any ratio
+    // derived from a comparison cohort.
     if ((input.contextChurn.compactionEvents ?? 0) >= 2) {
         const count = input.contextChurn.compactionEvents;
         return {
@@ -175,6 +175,22 @@ function contextDecision(input) {
             confidence: "high"
         };
     }
+    const ratio = input.currentSession?.ratioToMedian;
+    if (ratio !== null && ratio !== undefined && ratio >= 1.5) {
+        const ratioLabel = input.currentSession?.ratioCapped ? `at least ${ratio}` : `${ratio}`;
+        const exactComparisons = input.currentSession?.comparisonBasis === "same_project_and_session_type";
+        return {
+            status: "start_fresh",
+            recommendation: "start_fresh",
+            headline: `This turn's context load is ${ratioLabel}× your comparable same-agent token median.`,
+            action: "Start fresh before a new task; keep this session only while its existing context is directly useful.",
+            confidence: exactComparisons &&
+                !input.currentSession?.ratioCapped &&
+                input.currentSession.comparisonSessions >= 3
+                ? "high"
+                : "medium"
+        };
+    }
     if (input.hookInjectedItems > 0) {
         return {
             status: "watch",
@@ -188,8 +204,8 @@ function contextDecision(input) {
         return {
             status: "watch",
             recommendation: "trim_dead_context",
-            headline: `${input.deadContext.deadCount} loaded item${input.deadContext.deadCount === 1 ? "" : "s"} were not invoked in this window.`,
-            action: "Lazy-load or remove only the items you do not expect to need, then re-run Context Health.",
+            headline: `${input.deadContext.deadCount} configured item${input.deadContext.deadCount === 1 ? "" : "s"} had no matching invocation in this window.`,
+            action: "First verify how each host makes the item available; then lazy-load or remove only items you confirm you do not need, and re-run Context Health.",
             confidence: input.deadContext.unmeasuredDeadCount > 0 ? "medium" : "high"
         };
     }
@@ -210,28 +226,59 @@ function contextDecision(input) {
         confidence: "low"
     };
 }
+const MIN_EXACT_COMPARISONS = 2;
+const MIN_SESSION_TYPE_COMPARISONS = 2;
+const MAX_DISPLAY_RATIO = 20;
 function buildCurrentSession(sessions, now, activeWithinMinutes) {
     const latest = latestContextSession(sessions);
     if (!latest)
         return null;
-    const comparisons = sessions.filter((session) => (session.key !== latest.key &&
+    const eligible = sessions.filter((session) => (session.key !== latest.key &&
         session.agent === latest.agent &&
-        session.totalTokens > 0));
-    const baseline = median(comparisons.map((session) => session.totalTokens));
+        session.contextTokens > 0));
+    const sameProjectAndType = eligible.filter((session) => (Boolean(latest.project) &&
+        session.project === latest.project &&
+        session.sessionType === latest.sessionType));
+    const sameType = eligible.filter((session) => (latest.sessionType !== "unknown" &&
+        session.sessionType === latest.sessionType));
+    const comparisons = sameProjectAndType.length > 0
+        ? sameProjectAndType
+        : sameType.length > 0
+            ? sameType
+            : [];
+    const comparisonBasis = comparisons === sameProjectAndType
+        ? "same_project_and_session_type"
+        : comparisons === sameType
+            ? "same_session_type"
+            : "not_available";
+    const minimumComparisons = comparisonBasis === "same_project_and_session_type"
+        ? MIN_EXACT_COMPARISONS
+        : MIN_SESSION_TYPE_COMPARISONS;
+    const baseline = comparisons.length >= minimumComparisons
+        ? median(comparisons.map((session) => session.contextTokens))
+        : null;
     const cacheWriteBaseline = median(comparisons
         .map((session) => session.cacheWriteTokens)
         .filter((tokens) => tokens > 0));
-    const ratio = baseline && baseline > 0
-        ? roundRatio(latest.totalTokens / baseline)
+    const rawRatio = baseline && baseline > 0 && latest.contextTokens > 0
+        ? latest.contextTokens / baseline
         : null;
+    const ratioCapped = rawRatio !== null && rawRatio > MAX_DISPLAY_RATIO;
+    const ratio = rawRatio === null
+        ? null
+        : roundRatio(Math.min(rawRatio, MAX_DISPLAY_RATIO));
     const ageMs = Math.max(0, now.getTime() - Date.parse(latest.lastActivityAt));
     return {
         status: ageMs <= activeWithinMinutes * 60_000 ? "active" : "recent",
         agent: latest.agent,
         project: latest.project,
         totalTokens: latest.totalTokens,
+        contextTokens: latest.contextTokens,
+        usageSource: latest.usageSource,
         ratioToMedian: ratio,
+        ratioCapped,
         comparisonSessions: comparisons.length,
+        comparisonBasis,
         cacheWriteTokens: latest.cacheWriteTokens,
         cacheWriteRatioToMedian: cacheWriteBaseline && latest.cacheWriteTokens > 0
             ? roundRatio(latest.cacheWriteTokens / cacheWriteBaseline)
@@ -249,28 +296,53 @@ function contextSessions(calls) {
     return [...groups.entries()].map(([key, grouped]) => {
         const ordered = grouped.slice().sort((left, right) => left.timestamp.localeCompare(right.timestamp));
         const latest = ordered[ordered.length - 1];
+        const latestWithTurnUsage = ordered
+            .slice()
+            .reverse()
+            .find((call) => call.latestTurnUsage || call.usageScope !== "session_cumulative");
+        const turnUsage = latestWithTurnUsage
+            ? latestWithTurnUsage.latestTurnUsage ?? turnUsageFromCall(latestWithTurnUsage)
+            : undefined;
         return {
             key,
             agent: latest.agent,
             project: latest.project ?? ordered[0]?.project,
             lastActivityAt: latest.timestamp,
-            totalTokens: ordered.reduce((total, call) => total + (call.usage.inputTokens +
-                call.usage.outputTokens +
-                (call.usage.cacheReadTokens ?? 0) +
-                (call.usage.cacheWrite5mTokens ?? 0) +
-                (call.usage.cacheWrite1hTokens ?? 0)), 0),
-            cacheWriteTokens: ordered.reduce((total, call) => total + ((call.usage.cacheWrite5mTokens ?? 0) +
-                (call.usage.cacheWrite1hTokens ?? 0)), 0)
+            totalTokens: turnUsage?.totalTokens ?? 0,
+            contextTokens: turnUsage?.contextTokens ?? 0,
+            usageSource: turnUsage?.source ?? "not_available",
+            cacheWriteTokens: turnUsage
+                ? (turnUsage.cacheWrite5mTokens ?? 0) + (turnUsage.cacheWrite1hTokens ?? 0)
+                : 0,
+            sessionType: latest.activity?.isSubagent === true
+                ? "subagent"
+                : latest.activity?.isSubagent === false
+                    ? "parent"
+                    : "unknown"
         };
     });
 }
+function turnUsageFromCall(call) {
+    if (call.usageScope === "session_cumulative")
+        return undefined;
+    const contextTokens = call.usage.inputTokens +
+        (call.usage.cacheReadTokens ?? 0) +
+        (call.usage.cacheWrite5mTokens ?? 0) +
+        (call.usage.cacheWrite1hTokens ?? 0);
+    return {
+        ...call.usage,
+        contextTokens,
+        totalTokens: contextTokens + call.usage.outputTokens,
+        source: call.agent === "claude-code" ? "assistant_message_usage" : "call_usage"
+    };
+}
 function latestContextSession(sessions) {
     return sessions
         .slice()
         .sort((left, right) => right.lastActivityAt.localeCompare(left.lastActivityAt))[0];
 }
 function buildContextChurn(latest, invocations) {
-    const signals = invocations.sessionSignals ?? [];
+    const signals = mergeSessionSignals(invocations.sessionSignals ?? []);
     const currentSignal = latest
         ? signals.find((signal) => (signal.agent === latest.agent &&
             signal.sessionId &&
@@ -304,12 +376,109 @@ function buildContextChurn(latest, invocations) {
         observedSubagentSessions: signals.filter((signal) => signal.isSubagent).length
     };
 }
+function mergeSessionSignals(signals) {
+    const keyed = new Map();
+    const anonymous = [];
+    for (const signal of signals) {
+        if (!signal.sessionId) {
+            anonymous.push(signal);
+            continue;
+        }
+        const key = `${signal.agent}:${signal.sessionId}`;
+        keyed.set(key, [...(keyed.get(key) ?? []), signal]);
+    }
+    const merged = [...keyed.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([, group]) => mergeSignalGroup(group));
+    const sortedAnonymous = anonymous.slice().sort(compareSessionSignals);
+    return [...merged, ...sortedAnonymous];
+}
+function mergeSignalGroup(group) {
+    const ordered = group.slice().sort(compareSessionSignals);
+    const preferred = ordered[0];
+    const fileReadCounts = new Map();
+    for (const signal of group) {
+        for (const file of signal.fileReads) {
+            fileReadCounts.set(file.name, Math.max(fileReadCounts.get(file.name) ?? 0, file.count));
+        }
+    }
+    const fileReads = [...fileReadCounts.entries()]
+        .map(([name, count]) => ({ name, count }))
+        .sort((left, right) => right.count - left.count || left.name.localeCompare(right.name));
+    return {
+        ...preferred,
+        lastActivityAt: group
+            .map((signal) => signal.lastActivityAt)
+            .filter((value) => Boolean(value))
+            .sort((left, right) => right.localeCompare(left))[0],
+        compactionEvents: Math.max(...group.map((signal) => signal.compactionEvents)),
+        fileReads,
+        repeatedFileReads: fileReads.filter((file) => file.count > 1)
+    };
+}
+function compareSessionSignals(left, right) {
+    return (right.lastActivityAt ?? "").localeCompare(left.lastActivityAt ?? "") ||
+        right.compactionEvents - left.compactionEvents ||
+        totalFileReads(right) - totalFileReads(left) ||
+        sessionSignalSignature(left).localeCompare(sessionSignalSignature(right));
+}
+function totalFileReads(signal) {
+    return signal.fileReads.reduce((total, file) => total + file.count, 0);
+}
+function sessionSignalSignature(signal) {
+    return JSON.stringify({
+        agent: signal.agent,
+        sessionId: signal.sessionId,
+        isSubagent: signal.isSubagent,
+        parentSessionId: signal.parentSessionId,
+        files: signal.fileReads
+            .map((file) => [file.name, file.count])
+            .sort(([left], [right]) => String(left).localeCompare(String(right)))
+    });
+}
+function safeHookCategory(hook) {
+    if (hook.event === "SessionStart")
+        return "Session-start context hook";
+    if (hook.event === "UserPromptSubmit")
+        return "Prompt-submit context hook";
+    if (hook.event === "SubagentStart")
+        return "Subagent-start context hook";
+    if (hook.activation === "hook_injected")
+        return "Context-injecting lifecycle hook";
+    return "Lifecycle hook";
+}
+function safeHookProvenance(hook) {
+    if (hook.path === "Claude user settings")
+        return "Claude user settings";
+    if (hook.path === "Claude project settings")
+        return "Claude project settings";
+    if (hook.path === "Claude project-local settings")
+        return "Claude project-local settings";
+    const normalized = hook.path?.replace(/\\/g, "/");
+    if (normalized?.endsWith("/.claude/settings.local.json")) {
+        return ".claude/settings.local.json";
+    }
+    if (normalized?.endsWith("/.claude/settings.json")) {
+        return ".claude/settings.json";
+    }
+    if (normalized?.endsWith("/hooks/hooks.json")) {
+        return "installed plugin hooks/hooks.json";
+    }
+    const scope = hook.scope === "user"
+        ? "user"
+        : hook.scope === "local"
+            ? "project-local"
+            : "project";
+    return `${hostLabel(hook.host)} ${scope} hook configuration`;
+}
 function activationSummary(items, invocations) {
     return {
         discoverableItems: items.filter((item) => item.activation === "discoverable").length,
         explicitlyInvokedItems: items.filter((item) => itemWasInvoked(item, invocations)).length,
         hookInjectedItems: items.filter((item) => item.activation === "hook_injected").length,
         lifecycleHooks: items.filter((item) => item.activation === "lifecycle_hook").length,
+        mcpConfiguredItems: items.filter((item) => item.activation === "mcp_configured").length,
+        mcpAlwaysLoadedItems: items.filter((item) => item.activation === "mcp_always_loaded").length,
         mcpSchemaLoadedItems: items.filter((item) => item.activation === "mcp_schema_loaded").length,
         unmeasuredItems: items.filter((item) => item.weightConfidence !== "estimated").length,
         invocationUnobservableItems: items.filter((item) => item.kind !== "hook" && item.invocationTracking === "not_observable").length
@@ -318,17 +487,20 @@ function activationSummary(items, invocations) {
 function itemWasInvoked(item, invocations) {
     if (item.invocationTracking === "not_observable")
         return false;
+    const evidence = item.host && invocations.byHost
+        ? invocations.byHost[item.host]
+        : invocations;
     switch (item.kind) {
         case "skill":
-            return invocations.invokedSkills.includes(item.name);
+            return evidence.invokedSkills.includes(item.name);
         case "subagent":
-            return invocations.invokedSubagents.includes(item.name);
+            return evidence.invokedSubagents.includes(item.name);
         case "command":
-            return invocations.invokedCommands.includes(item.name);
+            return evidence.invokedCommands.includes(item.name);
         case "mcp_tool":
-            return invocations.invokedMcpTools.includes(item.name);
+            return evidence.invokedMcpTools.includes(item.name);
         case "mcp_server":
-            return invocations.invokedMcpTools.some((tool) => tool.split("__")[1] === item.name);
+            return evidence.invokedMcpTools.some((tool) => tool.split("__")[1] === item.name);
         case "hook":
             return false;
     }

package/dist/cutList.d.ts

@@ -1,4 +1,4 @@
-import type { CostConfidence, UsageRecord } from "./schema.js";
+import { type CostConfidence, type UsageRecord } from "./schema.js";
 /**
  * Actionable, dollar-specific "cut" suggestions.
  *
@@ -13,7 +13,11 @@ export type CutAction = {
     title: string;
     /** One-line, copy-pasteable instruction with the exact target. */
     action: string;
-    /** Estimated monthly savings in USD for this single action. */
+    /**
+     * Estimated monthly savings in USD for this single action. Zero means the
+     * evidence identifies value worth investigating but contains no observed
+     * counterfactual from which a savings amount can be earned.
+     */
     estimatedMonthlySavingsUsd: number;
     /** Spend (in the analyzed window) this action touches. */
     affectedSpendUsd: number;
@@ -24,7 +28,9 @@ export type CutAction = {
      * 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";
+    recordUnit: "calls" | "daily-aggregates" | "tools";
+    /** Whether the number is an intervention model or only observed exposure. */
+    impactBasis: "modeled_savings" | "observed_value_no_counterfactual";
     /** Lowest confidence of the underlying records (drives how we caveat $). */
     confidence: CostConfidence;
     kind: "model_downgrade" | "context_trim" | "cache" | "batch";