clementine-agent 1.1.9 → 1.1.10

package/dist/analytics/tool-usage.d.ts

@@ -16,6 +16,8 @@ export interface ToolFamilyStats {
     /** Family label — collapses mcp__ subnames into one bucket per server. */
     family: string;
     totalCalls: number;
+    /** Estimated cost attributed to this family (USD). Heuristic — see attributeCostsToToolUses. */
+    estimatedCostUsd: number;
     /** Per-tool breakdown within the family, sorted by count desc. */
     byTool: Array<{
         tool: string;
@@ -35,6 +37,9 @@ export interface ToolUsageReport {
     families: ToolFamilyStats[];
     /** Total cost (sum of query_complete events) over the window — context for tool counts. */
     totalCostUsd: number;
+    /** Sum of cost attributed to tool calls (≤ totalCostUsd). The gap is the cost of
+     *  query_completes whose tool calls fell outside the window or weren't logged. */
+    attributedCostUsd: number;
 }
 /**
  * Family normalization. Built-in SDK tools keep their name; MCP tools are

package/dist/analytics/tool-usage.js

@@ -42,6 +42,45 @@ export function classifyToolFamily(toolName) {
     };
     return BUILTIN_FAMILIES[toolName] ?? toolName;
 }
+/**
+ * Time-proximity cost attribution. Audit events don't carry an explicit
+ * query_id linking tool_use to query_complete, so we group by a sliding
+ * window: tool_use events that occur AFTER the previous query_complete
+ * (or the window start) and AT-OR-BEFORE the next query_complete are
+ * attributed to that query. The query's cost is then divided evenly
+ * across the tool calls in its window.
+ *
+ * Caveats:
+ * - Concurrent queries (e.g. cron + chat in the same window) will mix.
+ *   Best-effort heuristic, not exact accounting.
+ * - Tool calls without a closing query_complete in the window get
+ *   attributed nothing — captured in the gap between totalCostUsd
+ *   and attributedCostUsd in the report.
+ * - The even-distribution assumption ignores per-call cost variance
+ *   (a single Bash that consumed 50k tokens vs a Read that consumed
+ *   200). For our purposes (aggregate "where is my budget going?")
+ *   this is good enough — actionable to within ~15% per family.
+ */
+function attributeCostsToToolUses(events) {
+    const perToolCost = new Map();
+    let pendingToolIndices = [];
+    for (const e of events) {
+        if (!e.isQueryComplete) {
+            if (e.toolEntryIndex !== undefined)
+                pendingToolIndices.push(e.toolEntryIndex);
+            continue;
+        }
+        // Query closed — distribute cost.
+        if (pendingToolIndices.length > 0 && typeof e.cost_usd === 'number' && Number.isFinite(e.cost_usd)) {
+            const perCall = e.cost_usd / pendingToolIndices.length;
+            for (const idx of pendingToolIndices) {
+                perToolCost.set(idx, (perToolCost.get(idx) ?? 0) + perCall);
+            }
+        }
+        pendingToolIndices = [];
+    }
+    return perToolCost;
+}
 /**
  * Aggregate tool_use + query_complete events from audit.jsonl over the
  * given window. Window bounds are ISO strings; entries outside are ignored.
@@ -53,17 +92,20 @@ export function classifyToolFamily(toolName) {
 export function buildToolUsageReport(auditLogPath, windowStart, windowEnd) {
     const startMs = Date.parse(windowStart);
     const endMs = Date.parse(windowEnd);
-    // family → { totalCalls, perTool: Map<string,count>, perSource: Map<string,count> }
+    // family → { totalCalls, totalCost, perTool, perSource }
     const families = new Map();
     let totalToolCalls = 0;
     let totalQueries = 0;
     let totalCost = 0;
     if (!existsSync(auditLogPath)) {
-        return { windowStart, windowEnd, totalToolCalls: 0, totalQueries: 0, families: [], totalCostUsd: 0 };
+        return {
+            windowStart, windowEnd, totalToolCalls: 0, totalQueries: 0,
+            families: [], totalCostUsd: 0, attributedCostUsd: 0,
+        };
     }
-    // Stream-friendly read — each line is independent JSON. Audit logs are
-    // typically a few MB; readFileSync is fine at that scale.
     const raw = readFileSync(auditLogPath, 'utf-8');
+    const toolEntries = [];
+    const sequence = [];
     for (const line of raw.split('\n')) {
         if (!line)
             continue;
@@ -84,27 +126,40 @@ export function buildToolUsageReport(auditLogPath, windowStart, windowEnd) {
         if (entry.event_type === 'tool_use' && entry.tool_name) {
             const family = classifyToolFamily(entry.tool_name);
             const source = entry.job || entry.source || 'unknown';
-            let bucket = families.get(family);
-            if (!bucket) {
-                bucket = { totalCalls: 0, perTool: new Map(), perSource: new Map() };
-                families.set(family, bucket);
-            }
-            bucket.totalCalls++;
-            bucket.perTool.set(entry.tool_name, (bucket.perTool.get(entry.tool_name) ?? 0) + 1);
-            bucket.perSource.set(source, (bucket.perSource.get(source) ?? 0) + 1);
+            toolEntries.push({ family, source, toolName: entry.tool_name });
+            sequence.push({ ts: tsMs, isQueryComplete: false, toolEntryIndex: toolEntries.length - 1 });
             totalToolCalls++;
         }
         else if (entry.event_type === 'query_complete') {
             totalQueries++;
-            if (typeof entry.cost_usd === 'number' && Number.isFinite(entry.cost_usd)) {
-                totalCost += entry.cost_usd;
-            }
+            const cost = typeof entry.cost_usd === 'number' && Number.isFinite(entry.cost_usd) ? entry.cost_usd : 0;
+            totalCost += cost;
+            sequence.push({ ts: tsMs, isQueryComplete: true, cost_usd: cost });
+        }
+    }
+    // Second pass: attribute each query's cost across its preceding tool_use events.
+    const perToolCost = attributeCostsToToolUses(sequence);
+    let attributedCost = 0;
+    // Third pass: bucket toolEntries into family stats, summing attributed cost.
+    for (let i = 0; i < toolEntries.length; i++) {
+        const t = toolEntries[i];
+        const cost = perToolCost.get(i) ?? 0;
+        attributedCost += cost;
+        let bucket = families.get(t.family);
+        if (!bucket) {
+            bucket = { totalCalls: 0, totalCost: 0, perTool: new Map(), perSource: new Map() };
+            families.set(t.family, bucket);
         }
+        bucket.totalCalls++;
+        bucket.totalCost += cost;
+        bucket.perTool.set(t.toolName, (bucket.perTool.get(t.toolName) ?? 0) + 1);
+        bucket.perSource.set(t.source, (bucket.perSource.get(t.source) ?? 0) + 1);
     }
     const familyStats = [...families.entries()]
         .map(([family, b]) => ({
         family,
         totalCalls: b.totalCalls,
+        estimatedCostUsd: Number(b.totalCost.toFixed(4)),
         byTool: [...b.perTool.entries()]
             .map(([tool, count]) => ({ tool, count }))
             .sort((a, c) => c.count - a.count),
@@ -112,7 +167,8 @@ export function buildToolUsageReport(auditLogPath, windowStart, windowEnd) {
             .map(([source, count]) => ({ source, count }))
             .sort((a, c) => c.count - a.count),
     }))
-        .sort((a, b) => b.totalCalls - a.totalCalls);
+        // Sort by cost first (the actionable signal); fall back to call count.
+        .sort((a, b) => b.estimatedCostUsd - a.estimatedCostUsd || b.totalCalls - a.totalCalls);
     return {
         windowStart,
         windowEnd,
@@ -120,6 +176,7 @@ export function buildToolUsageReport(auditLogPath, windowStart, windowEnd) {
         totalQueries,
         families: familyStats,
         totalCostUsd: Number(totalCost.toFixed(4)),
+        attributedCostUsd: Number(attributedCost.toFixed(4)),
     };
 }
 /** Default audit log path — passed-through for CLI default + tests. */

package/dist/cli/index.js

@@ -1292,7 +1292,7 @@ async function cmdAnalyticsToolUsage(opts) {
     console.log(`  ${BOLD}Window:${RESET} last ${hours}h ${DIM}(${start.toISOString()} → ${end.toISOString()})${RESET}`);
     console.log(`  ${BOLD}Total tool calls:${RESET} ${report.totalToolCalls.toLocaleString()}`);
     console.log(`  ${BOLD}Total queries:${RESET}    ${report.totalQueries.toLocaleString()}`);
-    console.log(`  ${BOLD}Total cost:${RESET}       ${GREEN}$${report.totalCostUsd.toFixed(4)}${RESET}`);
+    console.log(`  ${BOLD}Total cost:${RESET}       ${GREEN}$${report.totalCostUsd.toFixed(4)}${RESET} ${DIM}(attributed to tools: $${report.attributedCostUsd.toFixed(4)})${RESET}`);
     console.log();
     if (report.families.length === 0) {
         console.log(`  ${DIM}No tool_use events in window.${RESET}`);
@@ -1300,23 +1300,24 @@ async function cmdAnalyticsToolUsage(opts) {
         return;
     }
     const top = report.families.slice(0, limit);
-    const maxCalls = Math.max(...top.map(f => f.totalCalls));
+    const maxCost = Math.max(...top.map(f => f.estimatedCostUsd), 0.0001);
     const familyWidth = Math.max(...top.map(f => f.family.length), 12);
-    console.log(`  ${BOLD}Top ${top.length} tool families${RESET}`);
+    console.log(`  ${BOLD}Top ${top.length} tool families ${DIM}(ranked by attributed cost)${RESET}`);
     for (const f of top) {
-        const pct = report.totalToolCalls > 0
-            ? ((f.totalCalls / report.totalToolCalls) * 100).toFixed(1)
+        const pct = report.attributedCostUsd > 0
+            ? ((f.estimatedCostUsd / report.attributedCostUsd) * 100).toFixed(1)
             : '0.0';
-        const barLen = Math.round((f.totalCalls / maxCalls) * 28);
-        const bar = '█'.repeat(barLen).padEnd(28);
+        const barLen = Math.round((f.estimatedCostUsd / maxCost) * 24);
+        const bar = '█'.repeat(barLen).padEnd(24);
         console.log(`    ${CYAN}${f.family.padEnd(familyWidth)}${RESET}  ` +
-            `${String(f.totalCalls).padStart(5)} ${DIM}calls${RESET}  ` +
-            `${pct.padStart(5)}%  ${YELLOW}${bar}${RESET}`);
-        // Top 2 individual tools within each family + top source
+            `${GREEN}$${f.estimatedCostUsd.toFixed(2).padStart(7)}${RESET} ` +
+            `${pct.padStart(5)}%  ` +
+            `${DIM}${String(f.totalCalls).padStart(5)} calls${RESET}  ` +
+            `${YELLOW}${bar}${RESET}`);
         const topTools = f.byTool.slice(0, 2).map(t => `${t.tool}×${t.count}`).join(', ');
         const topSource = f.bySource[0];
         console.log(`      ${DIM}top tools: ${topTools}${RESET}`);
-        if (topSource) {
+        if (topSource && topSource.source !== 'unknown') {
             console.log(`      ${DIM}driven by: ${topSource.source} (${topSource.count} calls)${RESET}`);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",