@agent-finops/core 0.5.5 → 0.5.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Futura Studio LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @agent-finops/core
+
+The canonical local-first data and decision engine for
+[aibill](https://github.com/futurastudio/ai-spend-agent): Claude Code/Codex
+activity ingestion, provider cost semantics, attribution, provenance, runway,
+Context Health, and the shared Glance contract.
+
+Most users should run `npx aibill`. This package is for integrations that
+need the same evidence-labeled calculations as the CLI and MCP server.
+
+Local API-equivalent estimates, subscription context, and official
+provider-reported cost are separate concepts and must not be added together.
+
+MIT licensed. See the repository
+[README](https://github.com/futurastudio/ai-spend-agent#readme) and
+[public roadmap](https://github.com/futurastudio/ai-spend-agent/blob/main/ROADMAP.md).

package/dist/agentInventory.d.ts

@@ -1,18 +1,18 @@
 /**
- * Agent context inventory: enumerate the Claude Code "inventory" that gets
- * loaded into an agent's always-on context (skills, subagents, slash commands,
- * MCP servers + their tools) and estimate how many tokens each item adds.
+ * Agent context inventory: enumerate configured Claude Code and Codex skills,
+ * subagents, slash commands, MCP servers, and installed lifecycle hooks.
  *
  * This feeds a later "dead-context cost" feature that prices loaded-but-never-
- * invoked tools. Every read here is read-only and missing dirs/files never throw.
+ * invoked tools. Every read here is read-only, hook commands are never run,
+ * and missing dirs/files never throw.
  *
  * CRITICAL token-weight rules (these drive the honesty of the final $ number):
  *  - Skills use *progressive disclosure*: only the YAML frontmatter (`name` +
  *    `description`) is always loaded — the body loads only when invoked. So a
  *    skill's alwaysLoadedTokens reflects ONLY name + description, never the body.
  *  - MCP tools: the FULL tool definition (name + description + JSON input schema)
- *    is always loaded — the heavy weight. Config (~/.claude.json) almost never
- *    carries tool schemas, so MCP enumeration is usually limited to server names;
+ *    is always loaded — the heavy weight. Local host config almost never carries
+ *    tool schemas, so MCP enumeration is usually limited to server names;
  *    those items are flagged "estimated_understated" because the real weight is
  *    larger than what we can see.
  *  - Subagents / slash commands: estimate from their description/frontmatter line
@@ -20,7 +20,9 @@
  *  - Built-in tools (Read/Edit/Bash/Glob/Grep/etc.) are EXCLUDED entirely: always
  *    loaded, not prunable, not "waste."
  */
-export type InventoryKind = "skill" | "subagent" | "command" | "mcp_tool" | "mcp_server";
+export type InventoryKind = "skill" | "subagent" | "command" | "mcp_tool" | "mcp_server" | "hook";
+export type InventoryActivation = "discoverable" | "mcp_schema_loaded" | "hook_injected" | "lifecycle_hook";
+export type InventoryHost = "claude-code" | "codex";
 export type InventoryItem = {
     kind: InventoryKind;
     /**
@@ -31,9 +33,17 @@ export type InventoryItem = {
     scope: "user" | "project";
     /** e.g. mcp server name for an mcp_tool, plugin name for a plugin skill. */
     group?: string;
+    /** How the host makes this item available to the model/runtime. */
+    activation: InventoryActivation;
+    /** Host that owns an installed lifecycle hook. */
+    host?: InventoryHost;
+    /** Lifecycle event for hook items, for example SessionStart. */
+    event?: string;
+    /** Whether local transcripts can prove this item was explicitly invoked. */
+    invocationTracking: "observable" | "not_observable";
     alwaysLoadedTokens: number;
-    /** "estimated_understated" when an MCP tool schema is unavailable. */
-    weightConfidence: "estimated" | "estimated_understated";
+    /** "unmeasured" means config proves activation but not runtime payload size. */
+    weightConfidence: "estimated" | "estimated_understated" | "unmeasured";
     path?: string;
     /** For project-scoped MCP servers: the project dirs that load this server. */
     ownerDirs?: string[];
@@ -43,8 +53,22 @@ export type AgentInventoryOptions = {
     claudeHomeDir?: string;
     /** Default: ~/.claude.json */
     claudeConfigPath?: string;
+    /** Default: <claudeHomeDir>/settings.json */
+    claudeSettingsPath?: string;
     /** Default: process.cwd(); scans <projectDir>/.claude/**. */
     projectDir?: string;
+    /** Default: ~/.codex. Used to locate enabled Codex plugins. */
+    codexHomeDir?: string;
+    /**
+     * Explicit installed plugin roots. Primarily useful for deterministic audits
+     * and tests; default discovery reads Claude's installed_plugins.json and
+     * Codex's enabled plugin list.
+     */
+    pluginRoots?: Array<{
+        root: string;
+        host: InventoryHost;
+        scope?: "user" | "project";
+    }>;
     /**
      * Include MCP servers from EVERY project in the config (not just projectDir).
      * Used for the global "across your whole setup" dead-context view so the
@@ -60,6 +84,8 @@ export type AgentInventoryResult = {
         commands: number;
         mcpServers: number;
         mcpTools: number;
+        hooks: number;
+        hookManifests: number;
     };
 };
 /** Token estimate: Math.ceil(chars / 4). Exported so the parent reuses it. */

package/dist/agentInventory.js

@@ -1,5 +1,5 @@
 import { readdir, readFile, stat } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 /** Token estimate: Math.ceil(chars / 4). Exported so the parent reuses it. */
 export function estimateTokensFromText(text) {
@@ -17,17 +17,64 @@ export const MCP_SERVER_TOKEN_FLOOR = 700;
 export async function loadAgentInventory(options = {}) {
     const home = homedir();
     const claudeHome = options.claudeHomeDir ?? join(home, ".claude");
+    const codexHome = options.codexHomeDir ?? join(home, ".codex");
     const configPath = options.claudeConfigPath ?? join(home, ".claude.json");
+    const settingsPath = options.claudeSettingsPath ?? join(claudeHome, "settings.json");
     const projectDir = options.projectDir ?? process.cwd();
     const projectClaude = join(projectDir, ".claude");
+    const projectClaudeRoots = resolve(projectClaude) === resolve(claudeHome)
+        ? []
+        : [{ dir: projectClaude, scope: "project" }];
     const items = [];
-    const scanned = { skills: 0, subagents: 0, commands: 0, mcpServers: 0, mcpTools: 0 };
+    const pluginRoots = options.pluginRoots ?? await configuredPluginRoots(claudeHome, codexHome);
+    const seenSkills = new Set();
+    const scanned = {
+        skills: 0,
+        subagents: 0,
+        commands: 0,
+        mcpServers: 0,
+        mcpTools: 0,
+        hooks: 0,
+        hookManifests: 0
+    };
     // --- Skills (user + project) ---
-    for (const { dir, scope } of [
-        { dir: join(claudeHome, "skills"), scope: "user" },
-        { dir: join(projectClaude, "skills"), scope: "project" }
+    for (const { dir, scope, host, invocationTracking } of [
+        {
+            dir: join(claudeHome, "skills"),
+            scope: "user",
+            host: "claude-code",
+            invocationTracking: "observable"
+        },
+        {
+            dir: join(codexHome, "skills"),
+            scope: "user",
+            host: "codex",
+            invocationTracking: "not_observable"
+        },
+        ...projectClaudeRoots.map((entry) => ({
+            dir: join(entry.dir, "skills"),
+            scope: entry.scope,
+            host: "claude-code",
+            invocationTracking: "observable"
+        })),
+        {
+            dir: join(projectDir, ".agents", "skills"),
+            scope: "project",
+            host: "codex",
+            invocationTracking: "not_observable"
+        },
+        {
+            dir: join(projectDir, ".codex", "skills"),
+            scope: "project",
+            host: "codex",
+            invocationTracking: "not_observable"
+        }
     ]) {
         for (const file of await findFiles(dir, (name) => name === "SKILL.md")) {
+            const skillKey = `${host}:${resolve(file)}`;
+            if (seenSkills.has(skillKey))
+                continue;
+            seenSkills.add(skillKey);
             const content = await readFile(file, "utf8").catch(() => "");
             if (!content)
                 continue;
@@ -46,6 +93,9 @@ export async function loadAgentInventory(options = {}) {
                 name,
                 scope,
                 group: pluginGroupFromPath(file, dir),
+                activation: "discoverable",
+                host,
+                invocationTracking,
                 alwaysLoadedTokens: estimateTokensFromText(loadedText),
                 weightConfidence: "estimated",
                 path: file
@@ -55,7 +105,10 @@ export async function loadAgentInventory(options = {}) {
     // --- Subagents (user + project) ---
     for (const { dir, scope } of [
         { dir: join(claudeHome, "agents"), scope: "user" },
-        { dir: join(projectClaude, "agents"), scope: "project" }
+        ...projectClaudeRoots.map((entry) => ({
+            dir: join(entry.dir, "agents"),
+            scope: entry.scope
+        }))
     ]) {
         for (const file of await findFiles(dir, (name) => name.endsWith(".md"))) {
             const content = await readFile(file, "utf8").catch(() => "");
@@ -75,6 +128,9 @@ export async function loadAgentInventory(options = {}) {
                 kind: "subagent",
                 name,
                 scope,
+                activation: "discoverable",
+                host: "claude-code",
+                invocationTracking: "observable",
                 alwaysLoadedTokens: estimateTokensFromText(loadedText),
                 weightConfidence: "estimated",
                 path: file
@@ -84,7 +140,10 @@ export async function loadAgentInventory(options = {}) {
     // --- Slash commands (user + project) ---
     for (const { dir, scope } of [
         { dir: join(claudeHome, "commands"), scope: "user" },
-        { dir: join(projectClaude, "commands"), scope: "project" }
+        ...projectClaudeRoots.map((entry) => ({
+            dir: join(entry.dir, "commands"),
+            scope: entry.scope
+        }))
     ]) {
         for (const file of await findFiles(dir, (name) => name.endsWith(".md"))) {
             const content = await readFile(file, "utf8").catch(() => "");
@@ -104,6 +163,9 @@ export async function loadAgentInventory(options = {}) {
                 kind: "command",
                 name,
                 scope,
+                activation: "discoverable",
+                host: "claude-code",
+                invocationTracking: "observable",
                 alwaysLoadedTokens: estimateTokensFromText(loadedText),
                 weightConfidence: "estimated",
                 path: file
@@ -111,9 +173,38 @@ export async function loadAgentInventory(options = {}) {
         }
     }
     // --- MCP servers (from ~/.claude.json: top-level + per-project map) ---
-    const config = await readJson(configPath);
-    const serverScopes = collectMcpServers(config, projectDir, options.includeAllProjectMcp ?? false);
-    for (const { id, scope, ownerDirs } of serverScopes) {
+    const serverScopes = new Map();
+    for (const sourcePath of [...new Set([configPath, settingsPath])]) {
+        const config = await readJson(sourcePath);
+        for (const server of collectMcpServers(config, projectDir, options.includeAllProjectMcp ?? false)) {
+            const key = `claude-code:${server.scope}:${server.id}`;
+            const prior = serverScopes.get(key);
+            if (prior) {
+                for (const ownerDir of server.ownerDirs) {
+                    if (!prior.ownerDirs.includes(ownerDir))
+                        prior.ownerDirs.push(ownerDir);
+                }
+            }
+            else {
+                serverScopes.set(key, { ...server, path: sourcePath, host: "claude-code" });
+            }
+        }
+    }
+    const codexConfigPath = join(codexHome, "config.toml");
+    const codexConfigText = await readFile(codexConfigPath, "utf8").catch(() => "");
+    for (const id of enabledCodexMcpServerNames(codexConfigText)) {
+        const key = `codex:user:${id}`;
+        if (!serverScopes.has(key)) {
+            serverScopes.set(key, {
+                id,
+                scope: "user",
+                ownerDirs: [],
+                path: codexConfigPath,
+                host: "codex"
+            });
+        }
+    }
+    for (const { id, scope, ownerDirs, path, host } of serverScopes.values()) {
         scanned.mcpServers += 1;
         // We almost never have tool schemas from config, so we can't measure the
         // real weight (full tool definitions). Use a conservative published-typical
@@ -126,14 +217,221 @@ export async function loadAgentInventory(options = {}) {
             name: id,
             scope,
             group: id,
+            activation: "mcp_schema_loaded",
+            host,
+            invocationTracking: host === "claude-code" ? "observable" : "not_observable",
             alwaysLoadedTokens: MCP_SERVER_TOKEN_FLOOR,
             weightConfidence: "estimated_understated",
-            path: configPath,
+            path,
             ownerDirs
         });
     }
+    // --- Installed lifecycle hooks (metadata only; commands are NEVER run) ---
+    const seenHooks = new Set();
+    for (const pluginRoot of pluginRoots) {
+        for (const manifestPath of await pluginManifestPaths(pluginRoot.root)) {
+            const manifest = await readJson(manifestPath);
+            if (!isRecord(manifest))
+                continue;
+            const pluginName = stringValue(manifest.name) ?? basename(dirname(dirname(manifestPath)));
+            const skillsPath = stringValue(manifest.skills)
+                ? resolve(dirname(dirname(manifestPath)), stringValue(manifest.skills))
+                : join(pluginRoot.root, "skills");
+            if (isWithinRoot(skillsPath, pluginRoot.root)) {
+                for (const file of await findFiles(skillsPath, (name) => name === "SKILL.md")) {
+                    const skillKey = `${pluginRoot.host}:${resolve(file)}`;
+                    if (seenSkills.has(skillKey))
+                        continue;
+                    seenSkills.add(skillKey);
+                    const content = await readFile(file, "utf8").catch(() => "");
+                    if (!content)
+                        continue;
+                    const fm = parseFrontmatter(content);
+                    const name = fm.name ?? skillNameFromPath(file, skillsPath);
+                    const loadedText = [
+                        `name: ${name}`,
+                        fm.description ? `description: ${fm.description}` : ""
+                    ].filter(Boolean).join("\n");
+                    scanned.skills += 1;
+                    items.push({
+                        kind: "skill",
+                        name,
+                        scope: pluginRoot.scope ?? "user",
+                        group: pluginName,
+                        activation: "discoverable",
+                        host: pluginRoot.host,
+                        invocationTracking: pluginRoot.host === "claude-code"
+                            ? "observable"
+                            : "not_observable",
+                        alwaysLoadedTokens: estimateTokensFromText(loadedText),
+                        weightConfidence: "estimated",
+                        path: file
+                    });
+                }
+            }
+            const configuredHookPath = stringValue(manifest.hooks);
+            const hookPath = configuredHookPath
+                ? resolve(dirname(dirname(manifestPath)), configuredHookPath)
+                : join(dirname(dirname(manifestPath)), "hooks", "hooks.json");
+            if (!isWithinRoot(hookPath, pluginRoot.root))
+                continue;
+            const hookConfig = await readJson(hookPath);
+            if (!isRecord(hookConfig) || !isRecord(hookConfig.hooks))
+                continue;
+            scanned.hookManifests += 1;
+            for (const [event, registrations] of Object.entries(hookConfig.hooks)) {
+                if (!Array.isArray(registrations) || registrations.length === 0)
+                    continue;
+                const activation = contextInjectingEvent(event)
+                    ? "hook_injected"
+                    : "lifecycle_hook";
+                const key = `${pluginRoot.host}:${pluginName}:${event}:${hookPath}`;
+                if (seenHooks.has(key))
+                    continue;
+                seenHooks.add(key);
+                scanned.hooks += 1;
+                items.push({
+                    kind: "hook",
+                    name: `${pluginName}:${event}`,
+                    scope: pluginRoot.scope ?? "user",
+                    group: pluginName,
+                    activation,
+                    host: pluginRoot.host,
+                    event,
+                    invocationTracking: "not_observable",
+                    // Hook config proves the event exists, not what its command emits at
+                    // runtime. Assigning tokens or dollars here would be fabricated.
+                    alwaysLoadedTokens: 0,
+                    weightConfidence: "unmeasured",
+                    path: hookPath
+                });
+            }
+        }
+    }
     return { items, scanned };
 }
+function enabledCodexMcpServerNames(configText) {
+    const servers = new Map();
+    let current;
+    for (const rawLine of configText.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        const section = /^\[mcp_servers\.(?:"([^"]+)"|([A-Za-z0-9_-]+))\]\s*$/.exec(line);
+        if (section) {
+            current = section[1] ?? section[2];
+            if (current)
+                servers.set(current, true);
+            continue;
+        }
+        if (/^\[/.test(line)) {
+            current = undefined;
+            continue;
+        }
+        if (current && /^enabled\s*=\s*false\s*(?:#.*)?$/.test(line)) {
+            servers.set(current, false);
+        }
+    }
+    return [...servers.entries()]
+        .filter(([, enabled]) => enabled)
+        .map(([name]) => name)
+        .sort();
+}
+async function configuredPluginRoots(claudeHome, codexHome) {
+    const roots = [];
+    // Claude records actual install paths. Marketplace checkouts alone are not
+    // treated as active, avoiding a false positive for every available plugin.
+    const installed = await readJson(join(claudeHome, "plugins", "installed_plugins.json"));
+    for (const installPath of collectStringFields(installed, "installPath")) {
+        roots.push({ root: installPath, host: "claude-code", scope: "user" });
+    }
+    // Codex records enabled plugin ids in config.toml. Match those ids to cached
+    // manifests by declared plugin name; disabled/cache-only plugins stay out.
+    const configText = await readFile(join(codexHome, "config.toml"), "utf8").catch(() => "");
+    const enabledNames = enabledCodexPluginNames(configText);
+    if (enabledNames.size > 0) {
+        for (const manifestPath of await findFiles(join(codexHome, "plugins", "cache"), (name) => name === "plugin.json")) {
+            if (!/\/\.codex-plugin\/plugin\.json$/.test(manifestPath.replace(/\\/g, "/")))
+                continue;
+            const manifest = await readJson(manifestPath);
+            const name = isRecord(manifest) ? stringValue(manifest.name) : undefined;
+            if (name && enabledNames.has(name)) {
+                roots.push({
+                    root: dirname(dirname(manifestPath)),
+                    host: "codex",
+                    scope: "user"
+                });
+            }
+        }
+    }
+    return dedupePluginRoots(roots);
+}
+function enabledCodexPluginNames(configText) {
+    const names = new Set();
+    let current;
+    for (const line of configText.split(/\r?\n/)) {
+        const section = /^\[plugins\."([^"]+)"\]\s*$/.exec(line.trim());
+        if (section) {
+            current = section[1]?.split("@")[0];
+            continue;
+        }
+        if (/^\[/.test(line.trim())) {
+            current = undefined;
+            continue;
+        }
+        if (current && /^enabled\s*=\s*true\s*(?:#.*)?$/.test(line.trim())) {
+            names.add(current);
+        }
+    }
+    return names;
+}
+function collectStringFields(value, field) {
+    if (Array.isArray(value)) {
+        return value.flatMap((entry) => collectStringFields(entry, field));
+    }
+    if (!isRecord(value))
+        return [];
+    const direct = stringValue(value[field]);
+    return [
+        ...(direct ? [direct] : []),
+        ...Object.values(value).flatMap((entry) => collectStringFields(entry, field))
+    ];
+}
+function dedupePluginRoots(roots) {
+    const seen = new Set();
+    return roots.filter((entry) => {
+        const key = `${entry.host}:${resolve(entry.root)}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+async function pluginManifestPaths(root) {
+    const directCodex = join(root, ".codex-plugin", "plugin.json");
+    const directClaude = join(root, ".claude-plugin", "plugin.json");
+    const out = [];
+    if (await stat(directCodex).then((value) => value.isFile()).catch(() => false)) {
+        out.push(directCodex);
+    }
+    if (await stat(directClaude).then((value) => value.isFile()).catch(() => false)) {
+        out.push(directClaude);
+    }
+    return out;
+}
+function contextInjectingEvent(event) {
+    return event === "SessionStart" ||
+        event === "UserPromptSubmit" ||
+        event === "SubagentStart";
+}
+function isWithinRoot(path, root) {
+    const resolvedPath = resolve(path);
+    const resolvedRoot = resolve(root);
+    return resolvedPath === resolvedRoot || resolvedPath.startsWith(`${resolvedRoot}/`);
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
 // --------------------------------------------------------------------------
 // MCP config extraction
 // --------------------------------------------------------------------------

package/dist/analyze.js

@@ -107,8 +107,12 @@ export function generateWorkflowWatch(records) {
     return [...groups.entries()]
         .map(([key, groupRecords]) => {
         const [clientId, projectId, workflowKey, agentId] = key.split("::");
-        const amountUsd = roundMoney(sumRecords(groupRecords));
-        const shareOfSpend = roundRatio(amountUsd / totalUsd);
+        const rawAmountUsd = sumRecords(groupRecords);
+        const amountUsd = roundMoney(rawAmountUsd);
+        // Compute the ratio from unrounded amounts. A tiny single-record total
+        // such as $0.0075 rounds to $0.01 for display; dividing that rounded
+        // value by the raw total produced 1.3333 and failed the [0, 1] schema.
+        const shareOfSpend = roundRatio(Math.min(1, rawAmountUsd / totalUsd));
         const estimatedSavingsUsd = roundMoney(amountUsd * impactRatios.workflowSavings);
         const estimatedMarginRiskUsd = roundMoney(amountUsd * impactRatios.workflowMarginRisk);
         const confidence = combinedConfidence(groupRecords.map((record) => record.costConfidence));

package/dist/contextHealth.d.ts

@@ -0,0 +1,101 @@
+import { type AgentInventoryOptions, type AgentInventoryResult, type InventoryItem } from "./agentInventory.js";
+import { type DeadContextResult } from "./deadContext.js";
+import type { LocalAgentCall } from "./localAgentLogs.js";
+import { type InvocationSummary, type ToolInvocationOptions } from "./toolInvocations.js";
+export type ContextHealthStatus = "healthy" | "watch" | "start_fresh" | "insufficient_data";
+export type ContextHealthRecommendation = "continue" | "start_fresh" | "review_hooks" | "trim_dead_context" | "collect_more_history";
+export type ContextHealthEvidence = {
+    kind: "session_history" | "context_churn" | "hook_config" | "inventory_usage";
+    summary: string;
+    source: string;
+    confidence: "observed" | "derived" | "unmeasured";
+};
+export type ContextHealthResult = {
+    schemaVersion: 1;
+    generatedAt: string;
+    status: ContextHealthStatus;
+    recommendation: ContextHealthRecommendation;
+    headline: string;
+    action: string;
+    confidence: "high" | "medium" | "low";
+    currentSession: {
+        status: "active" | "recent";
+        agent: LocalAgentCall["agent"];
+        project?: string;
+        totalTokens: number;
+        ratioToMedian: number | null;
+        comparisonSessions: number;
+        cacheWriteTokens: number;
+        cacheWriteRatioToMedian: number | null;
+        source: "local_transcript_metadata";
+    } | null;
+    activation: {
+        discoverableItems: number;
+        explicitlyInvokedItems: number;
+        hookInjectedItems: number;
+        lifecycleHooks: number;
+        mcpSchemaLoadedItems: number;
+        unmeasuredItems: number;
+        invocationUnobservableItems: number;
+    };
+    deadContext: {
+        loadedItems: number;
+        neverInvokedItems: number;
+        measuredNeverInvokedItems: number;
+        unmeasuredNeverInvokedItems: number;
+        windowDays: number;
+    };
+    contextChurn: {
+        currentSessionEvidence: "matched" | "not_matched" | "no_current_session";
+        compactionEvents: number | null;
+        explicitFileReads: number | null;
+        repeatedReadEvents: number | null;
+        repeatedFiles: Array<{
+            file: string;
+            readCount: number;
+        }>;
+        readCoverage: "explicit_read_tools_only" | "not_available";
+        currentSessionScope: "parent" | "subagent" | "unknown" | null;
+        observedParentSessions: number;
+        observedSubagentSessions: number;
+    };
+    evidence: ContextHealthEvidence[];
+    provenance: {
+        inventory: "local_agent_configuration";
+        invocations: "local_claude_code_and_codex_transcripts";
+        session: "local_transcript_metadata";
+        hookPayload: "not_executed_or_inferred";
+        uploaded: false;
+    };
+    caveats: string[];
+};
+export type BuildContextHealthInput = {
+    calls?: LocalAgentCall[];
+    inventory?: AgentInventoryResult | {
+        items: InventoryItem[];
+    };
+    invocations?: InvocationSummary;
+    deadContext?: DeadContextResult;
+    now?: Date;
+    activeWithinMinutes?: number;
+    windowDays?: number;
+};
+export type LoadContextHealthOptions = AgentInventoryOptions & ToolInvocationOptions & {
+    now?: Date;
+    activeWithinMinutes?: number;
+    windowDays?: number;
+    pricingModel?: string;
+    inventory?: AgentInventoryResult;
+    invocations?: InvocationSummary;
+};
+/**
+ * Load one canonical Context Health snapshot. CLI, MCP, and Glance all consume
+ * this contract so their recommendation and provenance cannot drift.
+ */
+export declare function loadContextHealth(calls: LocalAgentCall[], options?: LoadContextHealthOptions): Promise<ContextHealthResult>;
+/** Pure Context Health contract builder for deterministic tests and adapters. */
+export declare function buildContextHealth(input?: BuildContextHealthInput): ContextHealthResult;
+/** Exposed for deterministic benchmark fixtures. */
+export declare const CONTEXT_HEALTH_DEFAULT_WINDOW_DAYS = 30;
+export declare const CONTEXT_HEALTH_DAY_MS: number;
+//# sourceMappingURL=contextHealth.d.ts.map