clementine-agent 1.1.7 → 1.1.9

package/dist/agent/assistant.d.ts

@@ -271,7 +271,7 @@ export declare class PersonalAssistant {
      * so follow-up conversation has context.
      */
     injectContext(sessionKey: string, userText: string, assistantText: string): void;
-    getRecentActivity(sinceIso: string): Array<{
+    getRecentActivity(sinceIso: string, maxEntries?: number): Array<{
         sessionKey: string;
         role: string;
         content: string;

package/dist/agent/assistant.js

@@ -1506,6 +1506,33 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             }
             catch { /* non-fatal */ }
         }
+        // Conversational context — same signals the insight engine surfaces
+        // proactively (Phase 10), but injected directly into the agent's prompt
+        // so it can adjust its own approach. Scoped to chat sessions because
+        // cron/heartbeat don't have a "user feeling frustrated" axis to react to,
+        // and inflating their prompt doesn't help. Only injected when at least
+        // one signal fires — keeps the prompt clean during normal sessions.
+        if (!isAutonomous) {
+            try {
+                const { detectFrustrationSignals, detectRepeatedTopics } = require('./insight-engine.js');
+                const since24h = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+                const since7d = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+                const recent = this.getRecentActivity(since24h, 50);
+                const week = this.getRecentActivity(since7d, 200);
+                const frustration = detectFrustrationSignals(recent);
+                const topics = detectRepeatedTopics(week);
+                const allSignals = [...frustration, ...topics];
+                if (allSignals.length > 0) {
+                    const guidance = frustration.length > 0
+                        ? '\n\n**Adjust your approach:** When friction signals are present, lead with a clarifying question instead of assuming. Acknowledge the prior misunderstanding briefly without over-apologizing. Confirm understanding before acting.'
+                        : '\n\n**Use this context naturally:** Recurring topics may indicate an unresolved thread — if relevant, offer to close the loop or summarize current state. Do not force callbacks if not directly applicable.';
+                    volatileParts.push(`## Conversational Context\n\nSignals from recent sessions:\n` +
+                        allSignals.map(s => `- ${s}`).join('\n') +
+                        guidance);
+                }
+            }
+            catch { /* non-fatal — insight-engine optional */ }
+        }
         // Current context — date/time changes every minute, so it's volatile.
         const channel = deriveChannel({ sessionKey, isAutonomous, cronTier });
         const resolvedModel = resolveModel(model) ?? MODEL;
@@ -3786,6 +3813,12 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
     }
     async runCronJob(jobName, jobPrompt, tier = 1, maxTurns, model, workDir, timeoutMs, successCriteria, agentSlug) {
         setInteractionSource('autonomous');
+        // Tag every tool_use audit event with the cron job name + agent so
+        // analytics tool-usage can show "Bash×893 driven by market-leader-followup"
+        // instead of "driven by: unknown". Cleared on next setInteractionSource
+        // (cron/heartbeat boundary or interactive chat takeover).
+        const { setActiveQueryContext } = await import('./hooks.js');
+        setActiveQueryContext({ job: jobName, source: 'cron', agentSlug });
         const cronProfile = agentSlug && agentSlug !== 'clementine'
             ? this.profileManager.get(agentSlug)
             : null;
@@ -4274,6 +4307,10 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             logger.info(`Unleashed task ${jobName}: starting phase ${phase}`);
             // Re-assert autonomous source — a chat message may have changed it between phases
             setInteractionSource('autonomous');
+            // Tag tool_use audit events with the unleashed job name (Phase 11).
+            // Re-asserted each phase since setInteractionSource clears the context.
+            const { setActiveQueryContext: _setActiveQueryContext } = await import('./hooks.js');
+            _setActiveQueryContext({ job: jobName, source: 'unleashed', agentSlug });
             // Unleashed phases run side-effect-heavy work; same logic as cron mode.
             const phaseGuard = new StallGuard('unleashed');
             const sdkOptions = this.buildOptions({
@@ -4828,11 +4865,11 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             }
         }
     }
-    getRecentActivity(sinceIso) {
+    getRecentActivity(sinceIso, maxEntries) {
         if (!this.memoryStore)
             return [];
         try {
-            return this.memoryStore.getRecentActivity(sinceIso);
+            return this.memoryStore.getRecentActivity(sinceIso, maxEntries);
         }
         catch {
             return [];

package/dist/agent/hooks.d.ts

@@ -62,6 +62,12 @@ export declare function getInteractionSource(): 'owner-dm' | 'owner-channel' | '
 export declare function getProfileTier(): number | null;
 export declare function getAuditLog(): string[];
 export declare function clearAuditLog(): void;
+export declare function setActiveQueryContext(ctx: {
+    job?: string | null;
+    source?: string | null;
+    agentSlug?: string | null;
+}): void;
+export declare function clearActiveQueryContext(): void;
 export declare function logToolUse(toolName: string, toolInput: Record<string, unknown>): void;
 export declare function getHeartbeatDisallowedTools(): string[];
 export declare const PRIVATE_URL_PATTERNS: RegExp[];

package/dist/agent/hooks.js

@@ -141,6 +141,11 @@ export function setSendPolicyChecker(checker) {
 }
 export function setInteractionSource(source) {
     interactionSource = source;
+    // Clear any leftover query attribution context. Cron / unleashed paths
+    // immediately call setActiveQueryContext after this; interactive chat
+    // doesn't, so anything still set from a prior cron run gets reset.
+    activeJob = null;
+    activeSource = null;
 }
 export function getInteractionSource() {
     return interactionSource;
@@ -154,6 +159,25 @@ export function getAuditLog() {
 export function clearAuditLog() {
     auditLog.length = 0;
 }
+// Ambient job/source context so audit tool_use events carry attribution.
+// Set by the assistant before running a query; cleared after. Without this
+// the analytics view shows everything as "driven by: unknown". The
+// activeAgentSlug field is already declared above (line ~27) for the
+// existing send-policy infrastructure — we read but don't redeclare it.
+let activeJob = null;
+let activeSource = null;
+export function setActiveQueryContext(ctx) {
+    activeJob = ctx.job ?? null;
+    activeSource = ctx.source ?? null;
+    if (ctx.agentSlug !== undefined)
+        activeAgentSlug = ctx.agentSlug;
+}
+export function clearActiveQueryContext() {
+    activeJob = null;
+    activeSource = null;
+    // Don't clear activeAgentSlug — it's owned by the send-policy path,
+    // not by us. setInteractionSource resets it in the relevant transitions.
+}
 export function logToolUse(toolName, toolInput) {
     const timestamp = new Date().toLocaleTimeString('en-US', { hour12: false });
     const summary = summarizeToolCall(toolName, toolInput);
@@ -164,6 +188,9 @@ export function logToolUse(toolName, toolInput) {
         event_type: 'tool_use',
         tool_name: toolName,
         summary,
+        ...(activeJob ? { job: activeJob } : {}),
+        ...(activeSource ? { source: activeSource } : {}),
+        ...(activeAgentSlug ? { agent_slug: activeAgentSlug } : {}),
     });
 }
 // ── Heartbeat tool restrictions ─────────────────────────────────────

package/dist/agent/insight-engine.d.ts

@@ -47,13 +47,25 @@ export declare function maybeIncreaseCooldown(state: InsightState): void;
  * Returns structured event summaries that can be passed to an LLM for urgency rating.
  */
 export declare function gatherInsightSignals(gateway: {
-    getRecentActivity: (since: string) => Array<{
+    getRecentActivity: (since: string, maxEntries?: number) => Array<{
         sessionKey: string;
         role: string;
         content: string;
         createdAt: string;
     }>;
 }): string[];
+export declare function detectFrustrationSignals(activity: Array<{
+    sessionKey: string;
+    role: string;
+    content: string;
+    createdAt: string;
+}>): string[];
+export declare function detectRepeatedTopics(activity: Array<{
+    sessionKey: string;
+    role: string;
+    content: string;
+    createdAt: string;
+}>): string[];
 /**
  * Build a prompt for urgency rating (to be sent to a lightweight LLM).
  * Returns null if there are no signals worth evaluating.

package/dist/agent/insight-engine.js

@@ -189,7 +189,27 @@ export function gatherInsightSignals(gateway) {
     catch (err) {
         logger.debug({ err }, 'Failed to pull broken-jobs signals');
     }
-    // 6. Claim tracker — failed claims in the last N hours erode trust.
+    // 6. Conversational signals derived from recent transcripts.
+    //    Surfaces patterns IN the conversation itself, not just system events:
+    //    user frustration markers, repeating topics, etc. These are early
+    //    warning signs that the agent's responses may be off-track.
+    try {
+        const since24h = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+        const since7d = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+        // 24h frustration scan — 50 entries plenty to count corrections in a day.
+        const recent = gateway.getRecentActivity(since24h, 50);
+        for (const s of detectFrustrationSignals(recent))
+            signals.push(s);
+        // 7d repeat-topic scan — pull more entries since topics span sessions.
+        // Cap at 200 to keep keyword extraction cheap.
+        const week = gateway.getRecentActivity(since7d, 200);
+        for (const s of detectRepeatedTopics(week))
+            signals.push(s);
+    }
+    catch (err) {
+        logger.debug({ err }, 'Failed to pull conversational signals');
+    }
+    // 7. Claim tracker — failed claims in the last N hours erode trust.
     //    Surface them so the owner sees "Clementine said she'd do X; she
     //    didn't" instead of silently swallowing the miss.
     try {
@@ -214,6 +234,95 @@ export function gatherInsightSignals(gateway) {
     }
     return signals;
 }
+// ── Conversational signal detectors ─────────────────────────────────
+//
+// Pure functions over recent transcript activity. Exported so the insight
+// dashboard / debug commands can run them independently of the full
+// gatherInsightSignals path.
+/**
+ * Markers that suggest the user is correcting or frustrated with the
+ * agent's last response. Tuned to start-of-message tokens since
+ * mid-message "no" or "actually" is often just normal narrative.
+ */
+const CORRECTION_PATTERNS = [
+    /^(no|nope|not\b)/i,
+    /^(actually|wait)\b/i,
+    /^(that['’]?s| that is) (wrong|not|incorrect|backwards|opposite)/i,
+    /^I (meant|said|wanted|asked)\b/i,
+    /^you (didn['’]?t|misunderstood|got it wrong|missed)/i,
+    /^(stop|cancel|undo|nevermind|never mind)\b/i,
+];
+export function detectFrustrationSignals(activity) {
+    const signals = [];
+    let count = 0;
+    const sessionsAffected = new Set();
+    for (const entry of activity) {
+        if (entry.role !== 'user')
+            continue;
+        const trimmed = entry.content.trim();
+        for (const re of CORRECTION_PATTERNS) {
+            if (re.test(trimmed)) {
+                count++;
+                sessionsAffected.add(entry.sessionKey);
+                break;
+            }
+        }
+    }
+    if (count >= 3) {
+        signals.push(`Conversation friction: ${count} user correction(s) across ${sessionsAffected.size} session(s) in the last 24h — recent agent responses may be off-track`);
+    }
+    return signals;
+}
+/**
+ * Words too generic to count as a topic — would otherwise dominate the
+ * "recurring topic" signal with noise like "thanks", "okay", "please".
+ */
+const TOPIC_STOPWORDS = new Set([
+    'about', 'after', 'again', 'against', 'because', 'before', 'being', 'between',
+    'could', 'doing', 'don’t', 'down', 'during', 'each', 'from', 'further',
+    'going', 'gonna', 'have', 'having', 'here', 'into', 'just', 'know', 'like',
+    'maybe', 'might', 'more', 'most', 'much', 'need', 'okay', 'only', 'other',
+    'over', 'please', 'really', 'said', 'same', 'some', 'still', 'such', 'than',
+    'that', 'them', 'then', 'there', 'these', 'they', 'thing', 'think', 'this',
+    'those', 'through', 'thanks', 'time', 'told', 'under', 'until', 'using', 'very',
+    'want', 'wanted', 'wants', 'were', 'what', 'when', 'where', 'which', 'while',
+    'will', 'with', 'would', 'your', 'yours', 'yeah', 'yes',
+    'tonight', 'today', 'tomorrow', 'morning', 'evening', 'session', 'work',
+    'doing', 'made', 'make', 'making', 'sure', 'right', 'wrong', 'good', 'bad',
+    'much', 'many', 'lots',
+]);
+export function detectRepeatedTopics(activity) {
+    // Build a (keyword → set of session IDs) map. A keyword that shows up in
+    // 3+ DISTINCT sessions across the window is "recurring" — could be an
+    // unresolved thread, a project the user is grinding on, or a question
+    // they've asked multiple ways.
+    const sessionsForKeyword = new Map();
+    for (const entry of activity) {
+        if (entry.role !== 'user')
+            continue;
+        const text = entry.content.toLowerCase();
+        // Word extraction: 5+ chars, alpha-only (no numbers/punctuation).
+        const matches = text.match(/[a-z][a-z’]{4,15}/g) ?? [];
+        const seenInThisMessage = new Set();
+        for (const w of matches) {
+            if (TOPIC_STOPWORDS.has(w))
+                continue;
+            if (seenInThisMessage.has(w))
+                continue; // dedupe within a single message
+            seenInThisMessage.add(w);
+            if (!sessionsForKeyword.has(w))
+                sessionsForKeyword.set(w, new Set());
+            sessionsForKeyword.get(w).add(entry.sessionKey);
+        }
+    }
+    // Rank by session-spread; surface the top 2 to avoid flooding insight
+    // notifications with too many topic mentions.
+    const ranked = [...sessionsForKeyword.entries()]
+        .filter(([, sessions]) => sessions.size >= 3)
+        .sort((a, b) => b[1].size - a[1].size)
+        .slice(0, 2);
+    return ranked.map(([keyword, sessions]) => `Recurring topic "${keyword}" came up across ${sessions.size} sessions this week — possible ongoing thread`);
+}
 /**
  * Build a prompt for urgency rating (to be sent to a lightweight LLM).
  * Returns null if there are no signals worth evaluating.

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

@@ -0,0 +1,56 @@
+/**
+ * Tool-usage analytics.
+ *
+ * Reads ~/.clementine/logs/audit.jsonl and aggregates tool_use events by
+ * family + name + source so a CLI report can answer:
+ *
+ *   - "What is the agent spending its tool calls on?"
+ *   - "Which integration (mcp__ family) is hottest?"
+ *   - "Which job/source is the biggest tool consumer?"
+ *
+ * Pure file read + in-memory aggregation — no daemon access required.
+ * Designed to run on multi-MB audit logs without buffering everything;
+ * we stream line-by-line.
+ */
+export interface ToolFamilyStats {
+    /** Family label — collapses mcp__ subnames into one bucket per server. */
+    family: string;
+    totalCalls: number;
+    /** Per-tool breakdown within the family, sorted by count desc. */
+    byTool: Array<{
+        tool: string;
+        count: number;
+    }>;
+    /** Per-source breakdown — which job/context drives this family. */
+    bySource: Array<{
+        source: string;
+        count: number;
+    }>;
+}
+export interface ToolUsageReport {
+    windowStart: string;
+    windowEnd: string;
+    totalToolCalls: number;
+    totalQueries: number;
+    families: ToolFamilyStats[];
+    /** Total cost (sum of query_complete events) over the window — context for tool counts. */
+    totalCostUsd: number;
+}
+/**
+ * Family normalization. Built-in SDK tools keep their name; MCP tools are
+ * grouped by server (mcp__<server>__<tool> → "mcp:<server>"). Anything
+ * else falls into "other".
+ */
+export declare function classifyToolFamily(toolName: string): string;
+/**
+ * Aggregate tool_use + query_complete events from audit.jsonl over the
+ * given window. Window bounds are ISO strings; entries outside are ignored.
+ *
+ * The function is forgiving: malformed lines are skipped, missing fields
+ * default to 'unknown'. Audit logs are append-only so we never need to
+ * worry about ordering.
+ */
+export declare function buildToolUsageReport(auditLogPath: string, windowStart: string, windowEnd: string): ToolUsageReport;
+/** Default audit log path — passed-through for CLI default + tests. */
+export declare function defaultAuditLogPath(baseDir: string): string;
+//# sourceMappingURL=tool-usage.d.ts.map

package/dist/analytics/tool-usage.js

@@ -0,0 +1,129 @@
+/**
+ * Tool-usage analytics.
+ *
+ * Reads ~/.clementine/logs/audit.jsonl and aggregates tool_use events by
+ * family + name + source so a CLI report can answer:
+ *
+ *   - "What is the agent spending its tool calls on?"
+ *   - "Which integration (mcp__ family) is hottest?"
+ *   - "Which job/source is the biggest tool consumer?"
+ *
+ * Pure file read + in-memory aggregation — no daemon access required.
+ * Designed to run on multi-MB audit logs without buffering everything;
+ * we stream line-by-line.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Family normalization. Built-in SDK tools keep their name; MCP tools are
+ * grouped by server (mcp__<server>__<tool> → "mcp:<server>"). Anything
+ * else falls into "other".
+ */
+export function classifyToolFamily(toolName) {
+    if (!toolName)
+        return 'other';
+    // mcp__server-name__tool_name → mcp:server-name
+    const mcpMatch = toolName.match(/^mcp__([^_]+(?:[-_][^_]+)*)__/);
+    if (mcpMatch)
+        return `mcp:${mcpMatch[1]}`;
+    // Built-ins kept as their own families
+    const BUILTIN_FAMILIES = {
+        Bash: 'shell',
+        Read: 'fs-read',
+        Glob: 'fs-read',
+        Grep: 'fs-read',
+        Edit: 'fs-write',
+        Write: 'fs-write',
+        NotebookEdit: 'fs-write',
+        WebFetch: 'web',
+        WebSearch: 'web',
+        Agent: 'subagent',
+        Task: 'subagent',
+    };
+    return BUILTIN_FAMILIES[toolName] ?? toolName;
+}
+/**
+ * Aggregate tool_use + query_complete events from audit.jsonl over the
+ * given window. Window bounds are ISO strings; entries outside are ignored.
+ *
+ * The function is forgiving: malformed lines are skipped, missing fields
+ * default to 'unknown'. Audit logs are append-only so we never need to
+ * worry about ordering.
+ */
+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> }
+    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 };
+    }
+    // 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');
+    for (const line of raw.split('\n')) {
+        if (!line)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!entry.ts)
+            continue;
+        const tsMs = Date.parse(entry.ts);
+        if (Number.isNaN(tsMs))
+            continue;
+        if (tsMs < startMs || tsMs > endMs)
+            continue;
+        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);
+            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 familyStats = [...families.entries()]
+        .map(([family, b]) => ({
+        family,
+        totalCalls: b.totalCalls,
+        byTool: [...b.perTool.entries()]
+            .map(([tool, count]) => ({ tool, count }))
+            .sort((a, c) => c.count - a.count),
+        bySource: [...b.perSource.entries()]
+            .map(([source, count]) => ({ source, count }))
+            .sort((a, c) => c.count - a.count),
+    }))
+        .sort((a, b) => b.totalCalls - a.totalCalls);
+    return {
+        windowStart,
+        windowEnd,
+        totalToolCalls,
+        totalQueries,
+        families: familyStats,
+        totalCostUsd: Number(totalCost.toFixed(4)),
+    };
+}
+/** Default audit log path — passed-through for CLI default + tests. */
+export function defaultAuditLogPath(baseDir) {
+    return path.join(baseDir, 'logs', 'audit.jsonl');
+}
+//# sourceMappingURL=tool-usage.js.map

package/dist/cli/index.js

@@ -1270,6 +1270,58 @@ async function cmdConfigKeychainFixAcl(opts) {
     }
     console.log();
 }
+// ── Analytics ────────────────────────────────────────────────────────
+async function cmdAnalyticsToolUsage(opts) {
+    const { buildToolUsageReport, defaultAuditLogPath } = await import('../analytics/tool-usage.js');
+    const hours = Math.max(1, parseInt(opts.hours ?? '24', 10) || 24);
+    const limit = Math.max(1, parseInt(opts.limit ?? '10', 10) || 10);
+    const end = new Date();
+    const start = new Date(end.getTime() - hours * 60 * 60 * 1000);
+    const report = buildToolUsageReport(defaultAuditLogPath(BASE_DIR), start.toISOString(), end.toISOString());
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    const DIM = '\x1b[0;90m';
+    const BOLD = '\x1b[1m';
+    const CYAN = '\x1b[0;36m';
+    const GREEN = '\x1b[0;32m';
+    const YELLOW = '\x1b[0;33m';
+    const RESET = '\x1b[0m';
+    console.log();
+    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();
+    if (report.families.length === 0) {
+        console.log(`  ${DIM}No tool_use events in window.${RESET}`);
+        console.log();
+        return;
+    }
+    const top = report.families.slice(0, limit);
+    const maxCalls = Math.max(...top.map(f => f.totalCalls));
+    const familyWidth = Math.max(...top.map(f => f.family.length), 12);
+    console.log(`  ${BOLD}Top ${top.length} tool families${RESET}`);
+    for (const f of top) {
+        const pct = report.totalToolCalls > 0
+            ? ((f.totalCalls / report.totalToolCalls) * 100).toFixed(1)
+            : '0.0';
+        const barLen = Math.round((f.totalCalls / maxCalls) * 28);
+        const bar = '█'.repeat(barLen).padEnd(28);
+        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
+        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) {
+            console.log(`      ${DIM}driven by: ${topSource.source} (${topSource.count} calls)${RESET}`);
+        }
+    }
+    console.log();
+}
 // ── Advisor commands ────────────────────────────────────────────────
 const ADVISOR_MODES = ['off', 'shadow', 'primary'];
 function readAdvisorMode() {
@@ -1817,6 +1869,18 @@ advisorCmd
     .command('rules')
     .description('List loaded advisor rules')
     .action(cmdAdvisorRules);
+const analyticsCmd = program
+    .command('analytics')
+    .description('Production telemetry: tool usage, cost breakdowns');
+analyticsCmd
+    .command('tool-usage')
+    .description('Show which tool families are firing most over a time window')
+    .option('-h, --hours <n>', 'Window size in hours (default 24)', '24')
+    .option('--json', 'Emit machine-readable JSON')
+    .option('-l, --limit <n>', 'Show top N families (default 10)', '10')
+    .action(async (opts) => {
+    await cmdAnalyticsToolUsage(opts);
+});
 const dashCmd = program
     .command('dashboard')
     .description('Launch local command center')

package/dist/gateway/router.d.ts

@@ -170,7 +170,7 @@ export declare class Gateway {
      * Get recent transcript activity across all sessions.
      * Used by heartbeat to know what happened since the last check.
      */
-    getRecentActivity(sinceIso: string): Array<{
+    getRecentActivity(sinceIso: string, maxEntries?: number): Array<{
         sessionKey: string;
         role: string;
         content: string;

package/dist/gateway/router.js

@@ -1447,8 +1447,8 @@ export class Gateway {
      * Get recent transcript activity across all sessions.
      * Used by heartbeat to know what happened since the last check.
      */
-    getRecentActivity(sinceIso) {
-        return this.assistant.getRecentActivity(sinceIso);
+    getRecentActivity(sinceIso, maxEntries) {
+        return this.assistant.getRecentActivity(sinceIso, maxEntries);
     }
     /**
      * Search memory (FTS5) for context relevant to a query.

package/package.json

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