@agent-finops/core 0.5.5 → 0.5.7

package/dist/schema.d.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
 export declare const costConfidenceValues: readonly ["verified", "estimated", "detected_unverified", "missing"];
 export declare const costConfidenceSchema: z.ZodEnum<{
-    estimated: "estimated";
     verified: "verified";
+    estimated: "estimated";
     detected_unverified: "detected_unverified";
     missing: "missing";
 }>;
@@ -12,8 +12,8 @@ export declare const spendSourceSchema: z.ZodObject<{
     name: z.ZodString;
     provider: z.ZodString;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -28,8 +28,8 @@ export declare const usageRecordSchema: z.ZodObject<{
         name: z.ZodString;
         provider: z.ZodString;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -40,8 +40,8 @@ export declare const usageRecordSchema: z.ZodObject<{
     outputTokens: z.ZodNumber;
     amountUsd: z.ZodNullable<z.ZodNumber>;
     costConfidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -99,10 +99,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
         evidence: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
     status: z.ZodEnum<{
+        unmapped: "unmapped";
         auto_mapped: "auto_mapped";
         needs_confirmation: "needs_confirmation";
         needs_question: "needs_question";
-        unmapped: "unmapped";
     }>;
     evidence: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
@@ -112,8 +112,8 @@ export declare const spendBreakdownEntrySchema: z.ZodObject<{
     amountUsd: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -129,8 +129,8 @@ export declare const spendAnomalySchema: z.ZodObject<{
     currentAmountUsd: z.ZodNumber;
     multiplier: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -146,8 +146,8 @@ export declare const workflowWatchEntrySchema: z.ZodObject<{
     shareOfSpend: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -171,8 +171,8 @@ export declare const recommendationSchema: z.ZodObject<{
     }>;
     estimatedImpactUsd: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -216,8 +216,8 @@ export declare const spendInsightSchema: z.ZodObject<{
     affectedModels: z.ZodArray<z.ZodString>;
     estimatedImpactUsd: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -229,14 +229,14 @@ export declare const spendSummarySchema: z.ZodObject<{
     totalUsd: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
     confidenceBreakdown: z.ZodRecord<z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>, z.ZodNumber>;
@@ -245,8 +245,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -256,8 +256,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -267,8 +267,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -278,8 +278,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -289,8 +289,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -300,8 +300,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -311,8 +311,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -322,8 +322,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -338,8 +338,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         shareOfSpend: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -359,8 +359,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         currentAmountUsd: z.ZodNumber;
         multiplier: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -378,8 +378,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         }>;
         estimatedImpactUsd: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -416,8 +416,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         affectedModels: z.ZodArray<z.ZodString>;
         estimatedImpactUsd: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;

package/dist/sourceRegistry.js

@@ -350,7 +350,7 @@ function defaultScopeForSource(type) {
         return "Read-only Browser Account UI source. User logs in locally; agent never sees passwords; 2FA/CAPTCHA handoff; audit all page reads/downloads.";
     }
     if (type === "local_tool_detection") {
-        return "Read-only local CLI/tool detection path. Detection is not verified spend until account/API/export source is connected.";
+        return "Read-only local CLI/tool detection path. Detection is not official provider-reported cost; connect an account API or export to add that evidence.";
     }
     if (type === "mcp_tool" || type === "internal_system") {
         return "Read-only approved MCP/internal-system source. No writes, sends, deletes, or production changes without approval.";

package/dist/toolInvocations.d.ts

@@ -23,6 +23,27 @@ export type ToolInvocationCount = {
     name: string;
     count: number;
 };
+export type SessionContextSignal = {
+    agent: "claude-code" | "codex";
+    sessionId?: string;
+    lastActivityAt?: string;
+    /** Explicit compaction markers observed in this transcript. */
+    compactionEvents: number;
+    /**
+     * Explicit file-read tool calls, reduced to basenames so raw local paths
+     * never enter the Context Health contract.
+     */
+    fileReads: ToolInvocationCount[];
+    repeatedFileReads: ToolInvocationCount[];
+    /** Whether this transcript is a Claude sidechain/subagent transcript. */
+    isSubagent: boolean;
+    parentSessionId?: string;
+    /**
+     * Coverage is intentionally narrow. Shell commands are not parsed as file
+     * reads because doing so would turn arbitrary command text into a heuristic.
+     */
+    readCoverage: "explicit_read_tools_only";
+};
 export type InvocationSummary = {
     /** aggregated counts by raw tool name across all parsed transcripts */
     invocations: ToolInvocationCount[];
@@ -40,10 +61,19 @@ export type InvocationSummary = {
     totalAssistantTurns: number;
     /** assistant-turn count per session, for cache-read pricing */
     sessionTurnCounts: number[];
+    /** Transcript coverage by host. Optional for backwards-compatible fixtures. */
+    sourceSessions?: {
+        claudeCode: number;
+        codex: number;
+    };
+    /** Per-transcript compaction/read evidence used by Context Health. */
+    sessionSignals?: SessionContextSignal[];
 };
 export type ToolInvocationOptions = {
     /** default: join(homedir(), ".claude", "projects") */
     claudeProjectsDir?: string;
+    /** default: join(homedir(), ".codex", "sessions") */
+    codexSessionsDir?: string;
     /** optional: only count turns at/after this time */
     sinceIso?: string;
 };
@@ -55,7 +85,18 @@ export declare function parseClaudeCodeInvocations(content: string, sinceMs?: nu
     invokedSubagents: string[];
     invokedCommands: string[];
     assistantTurns: number;
+    contextSignal: SessionContextSignal;
+};
+/** Parse ONE Codex rollout's tool/skill/subagent invocations. */
+export declare function parseCodexInvocations(content: string, sinceMs?: number): {
+    invocations: ToolInvocationCount[];
+    invokedMcpTools: string[];
+    invokedSkills: string[];
+    invokedSubagents: string[];
+    invokedCommands: string[];
+    assistantTurns: number;
+    contextSignal: SessionContextSignal;
 };
-/** Scan this machine's Claude Code transcripts and aggregate tool invocations. */
+/** Scan this machine's Claude Code + Codex transcripts and aggregate invocations. */
 export declare function loadToolInvocations(options?: ToolInvocationOptions): Promise<InvocationSummary>;
 //# sourceMappingURL=toolInvocations.d.ts.map

package/dist/toolInvocations.js

@@ -1,5 +1,5 @@
 import { readdir, readFile, stat } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { homedir } from "node:os";
 /** Parse ONE transcript's content. Exported for tests. Returns the per-file pieces the aggregator needs. */
 export function parseClaudeCodeInvocations(content, sinceMs) {
@@ -8,8 +8,14 @@ export function parseClaudeCodeInvocations(content, sinceMs) {
     const skills = new Set();
     const subagents = new Set();
     const commands = new Set();
+    const fileReads = new Map();
     const seen = new Set();
     let assistantTurns = 0;
+    let sessionId;
+    let lastActivityAt;
+    let compactionEvents = 0;
+    let isSubagent = false;
+    let parentSessionId;
     for (const line of content.split("\n")) {
         if (!line.trim())
             continue;
@@ -22,12 +28,22 @@ export function parseClaudeCodeInvocations(content, sinceMs) {
         }
         if (!isRecord(entry))
             continue;
+        sessionId = stringOf(entry.sessionId) ?? sessionId;
+        if (entry.isSidechain === true)
+            isSubagent = true;
+        parentSessionId = stringOf(entry.parentSessionId) ?? parentSessionId;
+        const timestamp = stringOf(entry.timestamp);
+        if (timestamp && (!lastActivityAt || timestamp > lastActivityAt)) {
+            lastActivityAt = timestamp;
+        }
         // sinceIso filter: skip lines older than the cutoff when a timestamp exists.
         if (typeof sinceMs === "number") {
             const ts = Date.parse(stringOf(entry.timestamp) ?? "");
             if (Number.isFinite(ts) && ts < sinceMs)
                 continue;
         }
+        if (isClaudeCompactionEntry(entry))
+            compactionEvents += 1;
         // Slash commands surface in user lines as "<command-name>/foo</command-name>".
         if (entry.type === "user") {
             for (const cmd of slashCommandsFrom(entry))
@@ -70,6 +86,9 @@ export function parseClaudeCodeInvocations(content, sinceMs) {
                 if (sub)
                     subagents.add(sub);
             }
+            const file = input && explicitReadFile(name, input);
+            if (file)
+                fileReads.set(file, (fileReads.get(file) ?? 0) + 1);
         }
     }
     const invocations = [...counts.entries()]
@@ -81,12 +100,124 @@ export function parseClaudeCodeInvocations(content, sinceMs) {
         invokedSkills: [...skills].sort(),
         invokedSubagents: [...subagents].sort(),
         invokedCommands: [...commands].sort(),
-        assistantTurns
+        assistantTurns,
+        contextSignal: buildSessionContextSignal({
+            agent: "claude-code",
+            sessionId,
+            lastActivityAt,
+            compactionEvents,
+            fileReads,
+            isSubagent,
+            parentSessionId
+        })
     };
 }
-/** Scan this machine's Claude Code transcripts and aggregate tool invocations. */
+/** Parse ONE Codex rollout's tool/skill/subagent invocations. */
+export function parseCodexInvocations(content, sinceMs) {
+    const counts = new Map();
+    const mcpTools = new Set();
+    const skills = new Set();
+    const subagents = new Set();
+    const commands = new Set();
+    const fileReads = new Map();
+    let assistantTurns = 0;
+    let sessionId;
+    let lastActivityAt;
+    let compactionEvents = 0;
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(entry))
+            continue;
+        const timestampValue = stringOf(entry.timestamp);
+        if (timestampValue && (!lastActivityAt || timestampValue > lastActivityAt)) {
+            lastActivityAt = timestampValue;
+        }
+        if (typeof sinceMs === "number") {
+            const timestamp = Date.parse(stringOf(entry.timestamp) ?? "");
+            if (Number.isFinite(timestamp) && timestamp < sinceMs)
+                continue;
+        }
+        const payload = isRecord(entry.payload) ? entry.payload : undefined;
+        if (!payload)
+            continue;
+        if (entry.type === "session_meta") {
+            sessionId = stringOf(payload.id) ?? sessionId;
+        }
+        // Codex writes both a top-level `compacted` entry and a separate
+        // `context_compacted` event for one compaction. Count only the former.
+        if (entry.type === "compacted")
+            compactionEvents += 1;
+        // Codex emits one turn_context per model turn.
+        if (entry.type === "turn_context") {
+            assistantTurns += 1;
+            continue;
+        }
+        if (payload.type === "message" && payload.role === "user") {
+            for (const text of codexTextValues(payload.content)) {
+                const command = /^\s*\/([A-Za-z0-9:_-]+)/.exec(text)?.[1];
+                if (command)
+                    commands.add(command);
+            }
+            continue;
+        }
+        if (payload.type !== "function_call" && payload.type !== "custom_tool_call") {
+            continue;
+        }
+        const name = stringOf(payload.name);
+        if (!name)
+            continue;
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+        const input = codexToolInput(payload);
+        if (name.startsWith("mcp__")) {
+            mcpTools.add(name);
+        }
+        else if (name === "Skill") {
+            const skill = input && stringOf(input.skill);
+            if (skill)
+                skills.add(skill);
+        }
+        else if (name === "Task" || name === "Agent" || name === "spawn_agent") {
+            const subagent = input && (stringOf(input.subagent_type) ??
+                stringOf(input.task_name) ??
+                stringOf(input.agent));
+            if (subagent)
+                subagents.add(subagent);
+        }
+        const file = input && explicitReadFile(name, input);
+        if (file)
+            fileReads.set(file, (fileReads.get(file) ?? 0) + 1);
+    }
+    return {
+        invocations: [...counts.entries()]
+            .map(([name, count]) => ({ name, count }))
+            .sort((left, right) => right.count - left.count || left.name.localeCompare(right.name)),
+        invokedMcpTools: [...mcpTools].sort(),
+        invokedSkills: [...skills].sort(),
+        invokedSubagents: [...subagents].sort(),
+        invokedCommands: [...commands].sort(),
+        assistantTurns,
+        contextSignal: buildSessionContextSignal({
+            agent: "codex",
+            sessionId,
+            lastActivityAt,
+            compactionEvents,
+            fileReads,
+            isSubagent: false
+        })
+    };
+}
+/** Scan this machine's Claude Code + Codex transcripts and aggregate invocations. */
 export async function loadToolInvocations(options = {}) {
     const claudeDir = options.claudeProjectsDir ?? join(homedir(), ".claude", "projects");
+    const codexDir = options.codexSessionsDir ?? join(homedir(), ".codex", "sessions");
     const since = options.sinceIso ? Date.parse(options.sinceIso) : undefined;
     const sinceMs = typeof since === "number" && Number.isFinite(since) ? since : undefined;
     const counts = new Map();
@@ -95,14 +226,42 @@ export async function loadToolInvocations(options = {}) {
     const subagents = new Set();
     const commands = new Set();
     const sessionTurnCounts = [];
+    const sessionSignals = [];
     let sessions = 0;
+    let claudeCodeSessions = 0;
+    let codexSessions = 0;
     for (const file of await listJsonlFiles(claudeDir)) {
         const content = await readFile(file, "utf8").catch(() => "");
         if (!content)
             continue;
         sessions += 1;
+        claudeCodeSessions += 1;
         const parsed = parseClaudeCodeInvocations(content, sinceMs);
         sessionTurnCounts.push(parsed.assistantTurns);
+        sessionSignals.push(parsed.contextSignal);
+        for (const { name, count } of parsed.invocations) {
+            counts.set(name, (counts.get(name) ?? 0) + count);
+        }
+        for (const t of parsed.invokedMcpTools)
+            mcpTools.add(t);
+        for (const s of parsed.invokedSkills)
+            skills.add(s);
+        for (const s of parsed.invokedSubagents)
+            subagents.add(s);
+        for (const c of parsed.invokedCommands)
+            commands.add(c);
+    }
+    for (const file of await listJsonlFiles(codexDir)) {
+        if (!file.split(/[\\/]/).pop()?.startsWith("rollout-"))
+            continue;
+        const content = await readFile(file, "utf8").catch(() => "");
+        if (!content)
+            continue;
+        sessions += 1;
+        codexSessions += 1;
+        const parsed = parseCodexInvocations(content, sinceMs);
+        sessionTurnCounts.push(parsed.assistantTurns);
+        sessionSignals.push(parsed.contextSignal);
         for (const { name, count } of parsed.invocations) {
             counts.set(name, (counts.get(name) ?? 0) + count);
         }
@@ -126,7 +285,12 @@ export async function loadToolInvocations(options = {}) {
         invokedCommands: [...commands].sort(),
         sessions,
         totalAssistantTurns: sessionTurnCounts.reduce((sum, n) => sum + n, 0),
-        sessionTurnCounts
+        sessionTurnCounts,
+        sourceSessions: {
+            claudeCode: claudeCodeSessions,
+            codex: codexSessions
+        },
+        sessionSignals
     };
 }
 /** Extract "/foo" slash-command names from a user entry's content. */
@@ -180,6 +344,82 @@ async function listJsonlFiles(root) {
 function stringOf(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+function codexToolInput(payload) {
+    const direct = isRecord(payload.input) ? payload.input : undefined;
+    if (direct)
+        return direct;
+    for (const value of [payload.arguments, payload.input]) {
+        if (typeof value !== "string")
+            continue;
+        try {
+            const parsed = JSON.parse(value);
+            if (isRecord(parsed))
+                return parsed;
+        }
+        catch {
+            // Custom tool payloads are often free-form patches, not JSON.
+        }
+    }
+    return undefined;
+}
+function codexTextValues(value) {
+    if (typeof value === "string")
+        return [value];
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry === "string")
+            out.push(entry);
+        else if (isRecord(entry)) {
+            const text = stringOf(entry.text);
+            if (text)
+                out.push(text);
+        }
+    }
+    return out;
+}
+function isClaudeCompactionEntry(entry) {
+    if (entry.type !== "system")
+        return false;
+    const subtype = stringOf(entry.subtype)?.toLowerCase();
+    return subtype === "compact_boundary" ||
+        subtype === "compacted" ||
+        subtype === "context_compacted";
+}
+function explicitReadFile(toolName, input) {
+    const normalized = toolName.toLowerCase();
+    if (![
+        "read",
+        "read_file",
+        "readfile",
+        "view_image"
+    ].includes(normalized))
+        return undefined;
+    const raw = stringOf(input.file_path) ??
+        stringOf(input.path) ??
+        stringOf(input.file);
+    if (!raw)
+        return undefined;
+    const name = basename(raw);
+    return name && name !== "." && name !== "/" ? name : undefined;
+}
+function buildSessionContextSignal(input) {
+    const fileReads = [...input.fileReads.entries()]
+        .map(([name, count]) => ({ name, count }))
+        .sort((left, right) => right.count - left.count || left.name.localeCompare(right.name));
+    return {
+        agent: input.agent,
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(input.lastActivityAt ? { lastActivityAt: input.lastActivityAt } : {}),
+        compactionEvents: input.compactionEvents,
+        fileReads,
+        repeatedFileReads: fileReads.filter((file) => file.count > 1),
+        isSubagent: input.isSubagent,
+        ...(input.parentSessionId ? { parentSessionId: input.parentSessionId } : {}),
+        readCoverage: "explicit_read_tools_only"
+    };
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-finops/core",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,12 +20,25 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "license": "MIT",
-  "description": "Core engine for ai-spend-agent: provider billing connectors, local agent-log ingestion, attribution, cut list, plan math.",
+  "description": "Canonical aibill engine for local agent activity, billing semantics, attribution, provenance, runway, and Context Health.",
+  "keywords": [
+    "ai",
+    "finops",
+    "agent-economics",
+    "claude-code",
+    "codex",
+    "billing",
+    "provenance"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/futurastudio/ai-spend-agent.git",
     "directory": "packages/core"
   },
+  "homepage": "https://github.com/futurastudio/ai-spend-agent#readme",
+  "bugs": {
+    "url": "https://github.com/futurastudio/ai-spend-agent/issues"
+  },
   "engines": {
     "node": ">=22"
   }