context-mode 1.0.65 → 1.0.67

package/build/session/analytics.js

@@ -0,0 +1,708 @@
+/**
+ * AnalyticsEngine — All 27 metrics from SessionDB.
+ *
+ * Computes session-level and cross-session analytics using SQL queries
+ * and JavaScript post-processing. Groups:
+ *
+ *  Group 1 (SQL Direct):    17 metrics — direct SQL against session tables
+ *  Group 2 (JS Computed):    3 metrics — SQL + JS post-processing
+ *  Group 3 (Runtime):        4 metrics — stubs for server.ts tracking
+ *  Group 4 (New Extractor):  3 metrics — stubs for future extractors
+ *
+ * Usage:
+ *   const engine = new AnalyticsEngine(sessionDb);
+ *   const report = engine.queryAll(runtimeStats);
+ */
+// ─────────────────────────────────────────────────────────
+// Category labels and hints for session continuity display
+// ─────────────────────────────────────────────────────────
+/** Human-readable labels for event categories. */
+export const categoryLabels = {
+    file: "Files tracked",
+    rule: "Project rules (CLAUDE.md)",
+    prompt: "Your requests saved",
+    mcp: "Plugin tools used",
+    git: "Git operations",
+    env: "Environment setup",
+    error: "Errors caught",
+    task: "Tasks in progress",
+    decision: "Your decisions",
+    cwd: "Working directory",
+    skill: "Skills used",
+    subagent: "Delegated work",
+    intent: "Session mode",
+    data: "Data references",
+    role: "Behavioral directives",
+};
+/** Explains why each category matters for continuity. */
+export const categoryHints = {
+    file: "Restored after compact \u2014 no need to re-read",
+    rule: "Your project instructions survive context resets",
+    prompt: "Continues exactly where you left off",
+    decision: "Applied automatically \u2014 won\u2019t ask again",
+    task: "Picks up from where it stopped",
+    error: "Tracked and monitored across compacts",
+    git: "Branch, commit, and repo state preserved",
+    env: "Runtime config carried forward",
+    mcp: "Tool usage patterns remembered",
+    subagent: "Delegation history preserved",
+    skill: "Skill invocations tracked",
+};
+// ─────────────────────────────────────────────────────────
+// AnalyticsEngine
+// ─────────────────────────────────────────────────────────
+export class AnalyticsEngine {
+    db;
+    /**
+     * Create an AnalyticsEngine.
+     *
+     * Accepts either a SessionDB instance (extracts internal db via
+     * the protected getter — use the static fromDB helper for raw adapters)
+     * or any object with a prepare() method for direct usage.
+     */
+    constructor(db) {
+        this.db = db;
+    }
+    // ═══════════════════════════════════════════════════════
+    // GROUP 1 — SQL Direct (17 metrics)
+    // ═══════════════════════════════════════════════════════
+    /**
+     * #5 Weekly Trend — sessions started per day over the last 7 days.
+     * Returns an array of { day, sessions } sorted by day.
+     */
+    weeklyTrend() {
+        return this.db.prepare(`SELECT date(started_at) as day, COUNT(*) as sessions
+       FROM session_meta
+       WHERE started_at > datetime('now', '-7 days')
+       GROUP BY day`).all();
+    }
+    /**
+     * #7 Session Continuity — event category distribution for a session.
+     * Shows what the session focused on (file ops, git, errors, etc.).
+     */
+    sessionContinuity(sessionId) {
+        return this.db.prepare(`SELECT category, COUNT(*) as count
+       FROM session_events
+       WHERE session_id = ?
+       GROUP BY category`).all(sessionId);
+    }
+    /**
+     * #8 Commit Count — number of git commits made during a session.
+     * Matches events where category='git' and data contains 'commit'.
+     */
+    commitCount(sessionId) {
+        const row = this.db.prepare(`SELECT COUNT(*) as cnt
+       FROM session_events
+       WHERE session_id = ? AND category = 'git' AND data LIKE '%commit%'`).get(sessionId);
+        return row.cnt;
+    }
+    /**
+     * #9 Error Count — total error events in a session.
+     */
+    errorCount(sessionId) {
+        const row = this.db.prepare(`SELECT COUNT(*) as cnt
+       FROM session_events
+       WHERE session_id = ? AND category = 'error'`).get(sessionId);
+        return row.cnt;
+    }
+    /**
+     * #10 Session Duration — elapsed minutes from session start to last event.
+     * Returns null if last_event_at is not set (session still initializing).
+     */
+    sessionDuration(sessionId) {
+        const row = this.db.prepare(`SELECT (julianday(last_event_at) - julianday(started_at)) * 24 * 60 as minutes
+       FROM session_meta
+       WHERE session_id = ?`).get(sessionId);
+        return row?.minutes ?? null;
+    }
+    /**
+     * #11 Error Rate — percentage of events that are errors in a session.
+     * Returns 0 for sessions with no events (division by zero protection).
+     */
+    errorRate(sessionId) {
+        const row = this.db.prepare(`SELECT ROUND(100.0 * SUM(CASE WHEN category='error' THEN 1 ELSE 0 END) / COUNT(*), 1) as rate
+       FROM session_events
+       WHERE session_id = ?`).get(sessionId);
+        return row.rate ?? 0;
+    }
+    /**
+     * #12 Tool Diversity — number of distinct MCP tools used in a session.
+     * Higher diversity suggests more sophisticated tool usage.
+     */
+    toolDiversity(sessionId) {
+        const row = this.db.prepare(`SELECT COUNT(DISTINCT data) as cnt
+       FROM session_events
+       WHERE session_id = ? AND category = 'mcp'`).get(sessionId);
+        return row.cnt;
+    }
+    /**
+     * #14 Hourly Productivity — event distribution by hour of day.
+     * Optionally scoped to a session; omit sessionId for all sessions.
+     */
+    hourlyProductivity(sessionId) {
+        if (sessionId) {
+            return this.db.prepare(`SELECT strftime('%H', created_at) as hour, COUNT(*) as count
+         FROM session_events
+         WHERE session_id = ?
+         GROUP BY hour`).all(sessionId);
+        }
+        return this.db.prepare(`SELECT strftime('%H', created_at) as hour, COUNT(*) as count
+       FROM session_events
+       GROUP BY hour`).all();
+    }
+    /**
+     * #15 Project Distribution — session count per project directory.
+     * Sorted descending by session count.
+     */
+    projectDistribution() {
+        return this.db.prepare(`SELECT project_dir, COUNT(*) as sessions
+       FROM session_meta
+       GROUP BY project_dir
+       ORDER BY sessions DESC`).all();
+    }
+    /**
+     * #16 Compaction Count — number of snapshot compactions for a session.
+     * Higher counts indicate longer/more active sessions.
+     */
+    compactionCount(sessionId) {
+        const row = this.db.prepare(`SELECT compact_count
+       FROM session_meta
+       WHERE session_id = ?`).get(sessionId);
+        return row?.compact_count ?? 0;
+    }
+    /**
+     * #17 Weekly Session Count — total sessions started in the last 7 days.
+     */
+    weeklySessionCount() {
+        const row = this.db.prepare(`SELECT COUNT(*) as cnt
+       FROM session_meta
+       WHERE started_at > datetime('now', '-7 days')`).get();
+        return row.cnt;
+    }
+    /**
+     * #18 Commits Per Session — average commits across all sessions.
+     * Returns 0 when no sessions exist (NULLIF prevents division by zero).
+     */
+    commitsPerSession() {
+        const row = this.db.prepare(`SELECT ROUND(1.0 * (SELECT COUNT(*) FROM session_events WHERE category='git' AND data LIKE '%commit%')
+        / NULLIF((SELECT COUNT(DISTINCT session_id) FROM session_meta), 0), 1) as avg`).get();
+        return row.avg ?? 0;
+    }
+    /**
+     * #22 CLAUDE.md Freshness — last update timestamp for each rule file.
+     * Helps identify stale configuration files.
+     */
+    claudeMdFreshness() {
+        return this.db.prepare(`SELECT data, MAX(created_at) as last_updated
+       FROM session_events
+       WHERE category = 'rule'
+       GROUP BY data`).all();
+    }
+    /**
+     * #24 Rework Rate — files edited more than once (indicates iteration/rework).
+     * Sorted descending by edit count.
+     */
+    reworkRate(sessionId) {
+        if (sessionId) {
+            return this.db.prepare(`SELECT data, COUNT(*) as edits
+         FROM session_events
+         WHERE session_id = ? AND category = 'file'
+         GROUP BY data
+         HAVING edits > 1
+         ORDER BY edits DESC`).all(sessionId);
+        }
+        return this.db.prepare(`SELECT data, COUNT(*) as edits
+       FROM session_events
+       WHERE category = 'file'
+       GROUP BY data
+       HAVING edits > 1
+       ORDER BY edits DESC`).all();
+    }
+    /**
+     * #25 Session Outcome — classify a session as 'productive' or 'exploratory'.
+     * Productive: has at least one commit AND last event is not an error.
+     */
+    sessionOutcome(sessionId) {
+        const row = this.db.prepare(`
+      SELECT CASE
+        WHEN EXISTS(SELECT 1 FROM session_events WHERE session_id=? AND category='git' AND data LIKE '%commit%')
+         AND NOT EXISTS(SELECT 1 FROM session_events WHERE session_id=?
+             AND category='error' AND id=(SELECT MAX(id) FROM session_events WHERE session_id=?))
+        THEN 'productive'
+        ELSE 'exploratory'
+      END as outcome
+    `).get(sessionId, sessionId, sessionId);
+        return row.outcome;
+    }
+    /**
+     * #26 Subagent Usage — subagent spawn counts grouped by type/purpose.
+     */
+    subagentUsage(sessionId) {
+        return this.db.prepare(`SELECT COUNT(*) as total, data
+       FROM session_events
+       WHERE session_id = ? AND category = 'subagent'
+       GROUP BY data`).all(sessionId);
+    }
+    /**
+     * #27 Skill Usage — skill/slash-command invocation frequency.
+     * Sorted descending by invocation count.
+     */
+    skillUsage(sessionId) {
+        return this.db.prepare(`SELECT data, COUNT(*) as invocations
+       FROM session_events
+       WHERE session_id = ? AND category = 'skill'
+       GROUP BY data
+       ORDER BY invocations DESC`).all(sessionId);
+    }
+    // ═══════════════════════════════════════════════════════
+    // GROUP 2 — JS Computed (3 metrics)
+    // ═══════════════════════════════════════════════════════
+    /**
+     * #4 Session Mix — percentage of sessions classified as productive.
+     * Iterates all sessions and uses #25 (sessionOutcome) to classify each.
+     */
+    sessionMix() {
+        const sessions = this.db.prepare(`SELECT session_id FROM session_meta`).all();
+        if (sessions.length === 0) {
+            return { productive: 0, exploratory: 0 };
+        }
+        let productiveCount = 0;
+        for (const s of sessions) {
+            if (this.sessionOutcome(s.session_id) === "productive") {
+                productiveCount++;
+            }
+        }
+        const productivePct = Math.round((100 * productiveCount) / sessions.length);
+        return {
+            productive: productivePct,
+            exploratory: 100 - productivePct,
+        };
+    }
+    /**
+     * #13 / #20 Efficiency Score — composite score (0-100) measuring session productivity.
+     *
+     * Components:
+     *  - Error rate (lower = better): weight 30%
+     *  - Tool diversity (higher = better): weight 20%
+     *  - Commit presence (boolean bonus): weight 25%
+     *  - Rework rate (lower = better): weight 15%
+     *  - Session duration efficiency (moderate = better): weight 10%
+     *
+     * Formula: score = 100 - errorPenalty + diversityBonus + commitBonus - reworkPenalty + durationBonus - 40
+     * The -40 baseline prevents empty sessions from scoring 100.
+     */
+    efficiencyScore(sessionId) {
+        const errRate = this.errorRate(sessionId);
+        const diversity = this.toolDiversity(sessionId);
+        const commits = this.commitCount(sessionId);
+        const totalEvents = this.db.prepare(`SELECT COUNT(*) as cnt FROM session_events WHERE session_id = ?`).get(sessionId).cnt;
+        const fileEvents = this.db.prepare(`SELECT COUNT(*) as cnt FROM session_events WHERE session_id = ? AND category = 'file'`).get(sessionId).cnt;
+        // Rework: files edited more than once in this session
+        const reworkFiles = this.db.prepare(`SELECT COUNT(*) as cnt FROM (SELECT data, COUNT(*) as edits FROM session_events WHERE session_id = ? AND category = 'file' GROUP BY data HAVING edits > 1)`).get(sessionId);
+        const reworkRatio = fileEvents > 0 ? reworkFiles.cnt / fileEvents : 0;
+        // Duration in minutes
+        const duration = this.sessionDuration(sessionId) ?? 0;
+        // Score components
+        const errorPenalty = Math.min(errRate * 0.3, 30);
+        const diversityBonus = Math.min(diversity * 4, 20);
+        const commitBonus = commits > 0 ? 25 : 0;
+        const reworkPenalty = Math.min(reworkRatio * 15, 15);
+        const durationBonus = duration > 5 && duration < 60 ? 10 : duration >= 60 ? 5 : 0;
+        const score = Math.round(Math.max(0, Math.min(100, 100 - errorPenalty + diversityBonus + commitBonus - reworkPenalty + durationBonus - 40)));
+        return score;
+    }
+    /**
+     * #23 Iteration Cycles — counts edit-error-fix sequences in a session.
+     *
+     * Walks events chronologically and detects patterns where a file event
+     * is followed by an error event, then another file event.
+     */
+    iterationCycles(sessionId) {
+        const events = this.db.prepare(`SELECT category, data FROM session_events WHERE session_id = ? ORDER BY id ASC`).all(sessionId);
+        let cycles = 0;
+        for (let i = 0; i < events.length - 2; i++) {
+            if (events[i].category === "file" &&
+                events[i + 1].category === "error" &&
+                events[i + 2].category === "file") {
+                cycles++;
+                i += 2; // Skip past this cycle
+            }
+        }
+        return cycles;
+    }
+    // ═══════════════════════════════════════════════════════
+    // GROUP 3 — Runtime (4 metrics, stubs)
+    // ═══════════════════════════════════════════════════════
+    /**
+     * #1 Context Savings Total — bytes kept out of context window.
+     *
+     * Stub: requires server.ts to accumulate rawBytes and contextBytes
+     * during a live session. Call with tracked values.
+     */
+    static contextSavingsTotal(rawBytes, contextBytes) {
+        const savedBytes = rawBytes - contextBytes;
+        const savedPercent = rawBytes > 0
+            ? Math.round((savedBytes / rawBytes) * 1000) / 10
+            : 0;
+        return { rawBytes, contextBytes, savedBytes, savedPercent };
+    }
+    /**
+     * #2 Think in Code Comparison — ratio of file size to sandbox output size.
+     *
+     * Stub: requires server.ts tracking of execute/execute_file calls.
+     */
+    static thinkInCodeComparison(fileBytes, outputBytes) {
+        const ratio = outputBytes > 0
+            ? Math.round((fileBytes / outputBytes) * 10) / 10
+            : 0;
+        return { fileBytes, outputBytes, ratio };
+    }
+    /**
+     * #3 Tool Savings — per-tool breakdown of context savings.
+     *
+     * Stub: requires per-tool accumulators in server.ts.
+     */
+    static toolSavings(tools) {
+        return tools.map((t) => ({
+            ...t,
+            savedBytes: t.rawBytes - t.contextBytes,
+        }));
+    }
+    /**
+     * #19 Sandbox I/O — total input/output bytes processed by the sandbox.
+     *
+     * Stub: requires PolyglotExecutor byte counters.
+     */
+    static sandboxIO(inputBytes, outputBytes) {
+        return { inputBytes, outputBytes };
+    }
+    // ═══════════════════════════════════════════════════════
+    // GROUP 4 — New Extractor Needed (3 metrics)
+    // ═══════════════════════════════════════════════════════
+    /**
+     * #6 Pattern Detected — identifies recurring patterns in a session.
+     *
+     * Analyzes category distribution and detects dominant patterns
+     * (>60% threshold). Falls back to combination detection and
+     * "balanced" for evenly distributed sessions.
+     */
+    patternDetected(sessionId) {
+        const categories = this.sessionContinuity(sessionId);
+        const total = categories.reduce((sum, c) => sum + c.count, 0);
+        if (total === 0)
+            return "no activity";
+        // Sort by count descending
+        categories.sort((a, b) => b.count - a.count);
+        const dominant = categories[0];
+        const ratio = dominant.count / total;
+        if (ratio > 0.6) {
+            const patterns = {
+                file: "heavy file editor",
+                git: "git-focused",
+                mcp: "tool-heavy",
+                error: "debugging session",
+                plan: "planning session",
+                subagent: "delegation-heavy",
+                rule: "configuration session",
+                task: "task management",
+            };
+            return patterns[dominant.category] ?? `${dominant.category}-focused`;
+        }
+        // Check for common combinations
+        if (categories.find((c) => c.category === "git") &&
+            categories.find((c) => c.category === "file")) {
+            return "build and commit";
+        }
+        return "balanced";
+    }
+    /**
+     * #21 Permission Denials — count of tool calls blocked by security rules.
+     *
+     * Filters error events containing "denied", "blocked", or "permission".
+     * Stub: ideally requires a dedicated extractor in extract.ts.
+     */
+    permissionDenials(sessionId) {
+        const row = this.db.prepare(`SELECT COUNT(*) as cnt
+       FROM session_events
+       WHERE session_id = ? AND category = 'error'
+         AND (data LIKE '%denied%' OR data LIKE '%blocked%' OR data LIKE '%permission%')`).get(sessionId);
+        return row.cnt;
+    }
+    // ═══════════════════════════════════════════════════════
+    // queryAll — single unified report from ONE source
+    // ═══════════════════════════════════════════════════════
+    /**
+     * Build a complete FullReport by merging runtime stats (passed in)
+     * with all 27 DB-backed metrics and continuity data.
+     *
+     * This is the ONE call that ctx_stats should use.
+     */
+    queryAll(runtimeStats) {
+        // ── Resolve latest session ID ──
+        const latestSession = this.db.prepare("SELECT session_id FROM session_meta ORDER BY started_at DESC LIMIT 1").get();
+        const sid = latestSession?.session_id ?? "";
+        // ── Runtime savings ──
+        const totalBytesReturned = Object.values(runtimeStats.bytesReturned).reduce((sum, b) => sum + b, 0);
+        const totalCalls = Object.values(runtimeStats.calls).reduce((sum, c) => sum + c, 0);
+        const keptOut = runtimeStats.bytesIndexed + runtimeStats.bytesSandboxed;
+        const totalProcessed = keptOut + totalBytesReturned;
+        const savingsRatio = totalProcessed / Math.max(totalBytesReturned, 1);
+        const reductionPct = totalProcessed > 0
+            ? Math.round((1 - totalBytesReturned / totalProcessed) * 100)
+            : 0;
+        const toolNames = new Set([
+            ...Object.keys(runtimeStats.calls),
+            ...Object.keys(runtimeStats.bytesReturned),
+        ]);
+        const byTool = Array.from(toolNames).sort().map((tool) => ({
+            tool,
+            calls: runtimeStats.calls[tool] || 0,
+            context_kb: Math.round((runtimeStats.bytesReturned[tool] || 0) / 1024 * 10) / 10,
+            tokens: Math.round((runtimeStats.bytesReturned[tool] || 0) / 4),
+        }));
+        const uptimeMs = Date.now() - runtimeStats.sessionStart;
+        const uptimeMin = (uptimeMs / 60_000).toFixed(1);
+        // ── Cache ──
+        let cache;
+        if (runtimeStats.cacheHits > 0 || runtimeStats.cacheBytesSaved > 0) {
+            const totalWithCache = totalProcessed + runtimeStats.cacheBytesSaved;
+            const totalSavingsRatio = totalWithCache / Math.max(totalBytesReturned, 1);
+            const ttlHoursLeft = Math.max(0, 24 - Math.floor((Date.now() - runtimeStats.sessionStart) / (60 * 60 * 1000)));
+            cache = {
+                hits: runtimeStats.cacheHits,
+                bytes_saved: runtimeStats.cacheBytesSaved,
+                ttl_hours_left: ttlHoursLeft,
+                total_with_cache: totalWithCache,
+                total_savings_ratio: totalSavingsRatio,
+            };
+        }
+        // ── Session metrics ──
+        const durationMin = sid ? this.sessionDuration(sid) : null;
+        const toolCallsDb = sid ? this.db.prepare("SELECT COUNT(*) as cnt FROM session_events WHERE session_id = ? AND category = 'mcp'").get(sid).cnt : 0;
+        // ── Activity metrics ──
+        const commits = sid ? this.commitCount(sid) : 0;
+        const errors = sid ? this.errorCount(sid) : 0;
+        const errorRatePct = sid ? this.errorRate(sid) : 0;
+        const toolDiversity = sid ? this.toolDiversity(sid) : 0;
+        const effScore = sid ? this.efficiencyScore(sid) : 0;
+        const commitsPerSessionAvg = this.commitsPerSession();
+        const sessionOutcome = sid ? this.sessionOutcome(sid) : "exploratory";
+        const mix = this.sessionMix();
+        // ── Pattern metrics ──
+        const hourlyRaw = this.hourlyProductivity(sid || undefined);
+        const hourlyCommits = Array.from({ length: 24 }, (_, i) => {
+            const h = String(i).padStart(2, "0");
+            return hourlyRaw.find((r) => r.hour === h)?.count ?? 0;
+        });
+        const weeklyTrend = this.weeklyTrend();
+        const iterCycles = sid ? this.iterationCycles(sid) : 0;
+        const rework = sid ? this.reworkRate(sid) : this.reworkRate();
+        // ── Health metrics ──
+        const claudeMdFreshness = this.claudeMdFreshness().map((r) => {
+            const daysAgo = r.last_updated
+                ? Math.round((Date.now() - new Date(r.last_updated).getTime()) / 86_400_000)
+                : null;
+            return { project: r.data, days_ago: daysAgo };
+        });
+        const compactionsThisWeek = sid ? this.compactionCount(sid) : 0;
+        const weeklySessions = this.weeklySessionCount();
+        const permDenials = sid ? this.permissionDenials(sid) : 0;
+        // ── Agent metrics ──
+        const subagents = sid
+            ? this.subagentUsage(sid).map((r) => ({ type: r.data, count: r.total }))
+            : [];
+        const skills = sid
+            ? this.skillUsage(sid).map((r) => ({ name: r.data, count: r.invocations }))
+            : [];
+        // ── Continuity data ──
+        const eventTotal = this.db.prepare("SELECT COUNT(*) as cnt FROM session_events").get().cnt;
+        const byCategory = this.db.prepare("SELECT category, COUNT(*) as cnt FROM session_events GROUP BY category ORDER BY cnt DESC").all();
+        const meta = this.db.prepare("SELECT compact_count FROM session_meta ORDER BY started_at DESC LIMIT 1").get();
+        const compactCount = meta?.compact_count ?? 0;
+        const resume = this.db.prepare("SELECT event_count, consumed FROM session_resume ORDER BY created_at DESC LIMIT 1").get();
+        const resumeReady = resume ? !resume.consumed : false;
+        // Build category previews
+        const previewRows = this.db.prepare("SELECT category, type, data FROM session_events ORDER BY id DESC").all();
+        const previews = new Map();
+        for (const row of previewRows) {
+            if (!previews.has(row.category))
+                previews.set(row.category, new Set());
+            const set = previews.get(row.category);
+            if (set.size < 5) {
+                let display = row.data;
+                if (row.category === "file") {
+                    display = row.data.split("/").pop() || row.data;
+                }
+                else if (row.category === "prompt") {
+                    display = display.length > 50 ? display.slice(0, 47) + "..." : display;
+                }
+                if (display.length > 40)
+                    display = display.slice(0, 37) + "...";
+                set.add(display);
+            }
+        }
+        const continuityByCategory = byCategory.map((row) => ({
+            category: row.category,
+            count: row.cnt,
+            label: categoryLabels[row.category] || row.category,
+            preview: previews.get(row.category)
+                ? Array.from(previews.get(row.category)).join(", ")
+                : "",
+            why: categoryHints[row.category] || "Survives context resets",
+        }));
+        return {
+            savings: {
+                processed_kb: Math.round(totalProcessed / 1024 * 10) / 10,
+                entered_kb: Math.round(totalBytesReturned / 1024 * 10) / 10,
+                saved_kb: Math.round(keptOut / 1024 * 10) / 10,
+                pct: reductionPct,
+                savings_ratio: Math.round(savingsRatio * 10) / 10,
+                by_tool: byTool,
+                total_calls: totalCalls,
+                total_bytes_returned: totalBytesReturned,
+                kept_out: keptOut,
+                total_processed: totalProcessed,
+            },
+            cache,
+            session: {
+                id: sid,
+                duration_min: durationMin !== null ? Math.round(durationMin * 10) / 10 : null,
+                tool_calls: toolCallsDb,
+                uptime_min: uptimeMin,
+            },
+            activity: {
+                commits,
+                errors,
+                error_rate_pct: errorRatePct,
+                tool_diversity: toolDiversity,
+                efficiency_score: effScore,
+                commits_per_session_avg: commitsPerSessionAvg,
+                session_outcome: sessionOutcome,
+                productive_pct: mix.productive,
+                exploratory_pct: mix.exploratory,
+            },
+            patterns: {
+                hourly_commits: hourlyCommits,
+                weekly_trend: weeklyTrend,
+                iteration_cycles: iterCycles,
+                rework: rework.map((r) => ({ file: r.data, edits: r.edits })),
+            },
+            health: {
+                claude_md_freshness: claudeMdFreshness,
+                compactions_this_week: compactionsThisWeek,
+                weekly_sessions: weeklySessions,
+                permission_denials: permDenials,
+            },
+            agents: { subagents, skills },
+            continuity: {
+                total_events: eventTotal,
+                by_category: continuityByCategory,
+                compact_count: compactCount,
+                resume_ready: resumeReady,
+            },
+        };
+    }
+}
+// ─────────────────────────────────────────────────────────
+// formatReport — renders FullReport as markdown
+// ─────────────────────────────────────────────────────────
+/** Format bytes as human-readable KB or MB. */
+function kb(b) {
+    if (b >= 1024 * 1024)
+        return `${(b / 1024 / 1024).toFixed(1)}MB`;
+    return `${(b / 1024).toFixed(1)}KB`;
+}
+/**
+ * Render a FullReport as the same markdown output ctx_stats has always produced.
+ *
+ * Preserves the exact output format: Context Window Protection table,
+ * TTL Cache section, Session Continuity table, and Analytics JSON block.
+ */
+export function formatReport(report) {
+    const lines = [
+        `## context-mode \u2014 Session Report (${report.session.uptime_min} min)`,
+    ];
+    // ── Feature 1: Context Window Protection ──
+    lines.push("", `### Context Window Protection`, "");
+    if (report.savings.total_calls === 0) {
+        lines.push(`No context-mode tool calls yet. Use \`batch_execute\`, \`execute\`, or \`fetch_and_index\` to keep raw output out of your context window.`);
+    }
+    else {
+        lines.push(`| Metric | Value |`, `|--------|------:|`, `| Total data processed | **${kb(report.savings.total_processed)}** |`, `| Kept in sandbox (never entered context) | **${kb(report.savings.kept_out)}** |`, `| Entered context | ${kb(report.savings.total_bytes_returned)} |`, `| Estimated tokens saved | ~${Math.round(report.savings.kept_out / 4).toLocaleString()} |`, `| **Context savings** | **${report.savings.savings_ratio.toFixed(1)}x (${report.savings.pct}% reduction)** |`);
+        // Per-tool breakdown
+        if (report.savings.by_tool.length > 0) {
+            lines.push("", `| Tool | Calls | Context | Tokens |`, `|------|------:|--------:|-------:|`);
+            for (const t of report.savings.by_tool) {
+                lines.push(`| ${t.tool} | ${t.calls} | ${kb(t.calls > 0 ? (t.tokens * 4) : 0)} | ~${t.tokens.toLocaleString()} |`);
+            }
+            lines.push(`| **Total** | **${report.savings.total_calls}** | **${kb(report.savings.total_bytes_returned)}** | **~${Math.round(report.savings.total_bytes_returned / 4).toLocaleString()}** |`);
+        }
+        if (report.savings.kept_out > 0) {
+            lines.push("", `Without context-mode, **${kb(report.savings.total_processed)}** of raw output would flood your context window. Instead, **${report.savings.pct}%** stayed in sandbox.`);
+        }
+        // Cache savings section
+        if (report.cache) {
+            lines.push("", `### TTL Cache`, "", `| Metric | Value |`, `|--------|------:|`, `| Cache hits | **${report.cache.hits}** |`, `| Data avoided by cache | **${kb(report.cache.bytes_saved)}** |`, `| Network requests saved | **${report.cache.hits}** |`, `| TTL remaining | **~${report.cache.ttl_hours_left}h** |`, "", `Content was already indexed in the knowledge base \u2014 ${report.cache.hits} fetch${report.cache.hits > 1 ? "es" : ""} skipped entirely. **${kb(report.cache.bytes_saved)}** of network I/O avoided. Search results served directly from local FTS5 index.`);
+            if (report.cache.total_savings_ratio > report.savings.savings_ratio) {
+                lines.push("", `**Total context savings (sandbox + cache): ${report.cache.total_savings_ratio.toFixed(1)}x** \u2014 ${kb(report.cache.total_with_cache)} processed, only ${kb(report.savings.total_bytes_returned)} entered context.`);
+            }
+        }
+    }
+    // ── Session Continuity ──
+    if (report.continuity.total_events > 0) {
+        lines.push("", "### Session Continuity", "", "| What's preserved | Count | I remember... | Why it matters |", "|------------------|------:|---------------|----------------|");
+        for (const row of report.continuity.by_category) {
+            lines.push(`| ${row.label} | ${row.count} | ${row.preview} | ${row.why} |`);
+        }
+        lines.push(`| **Total** | **${report.continuity.total_events}** | | **Zero knowledge lost on compact** |`);
+        lines.push("");
+        if (report.continuity.compact_count > 0) {
+            lines.push(`Context has been compacted **${report.continuity.compact_count} time(s)** \u2014 session knowledge was preserved each time.`);
+        }
+        else {
+            lines.push(`When your context compacts, all of this will restore Claude's awareness \u2014 no starting from scratch.`);
+        }
+        if (report.continuity.resume_ready) {
+            lines.push(`Resume snapshot ready for the next compaction.`);
+        }
+        lines.push("");
+        lines.push(`> **Note:** Previous session data is loaded when you start a new session. Without \`--continue\`, old session history is cleaned up to keep the database lean.`);
+    }
+    // ── Analytics JSON ──
+    const analyticsJson = {
+        session: {
+            duration_min: report.session.duration_min,
+            tool_calls: report.session.tool_calls,
+        },
+        activity: {
+            commits: report.activity.commits,
+            errors: report.activity.errors,
+            error_rate_pct: report.activity.error_rate_pct,
+            tool_diversity: report.activity.tool_diversity,
+            efficiency_score: report.activity.efficiency_score,
+            commits_per_session_avg: report.activity.commits_per_session_avg,
+            session_outcome: report.activity.session_outcome,
+        },
+        patterns: {
+            hourly_commits: report.patterns.hourly_commits,
+            weekly_trend: report.patterns.weekly_trend,
+            iteration_cycles: report.patterns.iteration_cycles,
+            rework: report.patterns.rework,
+        },
+        health: {
+            claude_md_freshness: report.health.claude_md_freshness,
+            compactions_this_week: report.health.compactions_this_week,
+            weekly_sessions: report.health.weekly_sessions,
+            permission_denials: report.health.permission_denials,
+        },
+        agents: {
+            subagents: report.agents.subagents,
+            skills: report.agents.skills,
+        },
+        continuity: { total_events: report.continuity.total_events },
+    };
+    lines.push("", "### Analytics (27 metrics)", "", "```json", JSON.stringify(analyticsJson, null, 2), "```");
+    // Formatting directive
+    lines.push("", "---", "_Display this entire report as-is in your response. Do NOT summarize, collapse, or paraphrase any section._");
+    return lines.join("\n");
+}