context-mode 1.0.65 → 1.0.67

package/build/session/analytics.d.ts

@@ -0,0 +1,381 @@
+/**
+ * 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);
+ */
+/** Database adapter — anything with a prepare() method (better-sqlite3, bun:sqlite, etc.) */
+export interface DatabaseAdapter {
+    prepare(sql: string): {
+        run(...params: unknown[]): unknown;
+        get(...params: unknown[]): unknown;
+        all(...params: unknown[]): unknown[];
+    };
+}
+/** Weekly trend data point */
+export interface WeeklyTrendRow {
+    day: string;
+    sessions: number;
+}
+/** Category distribution row */
+export interface ContinuityRow {
+    category: string;
+    count: number;
+}
+/** Hourly productivity row */
+export interface HourlyRow {
+    hour: string;
+    count: number;
+}
+/** Project distribution row */
+export interface ProjectRow {
+    project_dir: string;
+    sessions: number;
+}
+/** CLAUDE.md freshness row */
+export interface FreshnessRow {
+    data: string;
+    last_updated: string;
+}
+/** Rework rate row */
+export interface ReworkRow {
+    data: string;
+    edits: number;
+}
+/** Subagent usage row */
+export interface SubagentRow {
+    data: string;
+    total: number;
+}
+/** Skill usage row */
+export interface SkillRow {
+    data: string;
+    invocations: number;
+}
+/** Context savings result (#1) */
+export interface ContextSavings {
+    rawBytes: number;
+    contextBytes: number;
+    savedBytes: number;
+    savedPercent: number;
+}
+/** Think in code comparison result (#2) */
+export interface ThinkInCodeComparison {
+    fileBytes: number;
+    outputBytes: number;
+    ratio: number;
+}
+/** Tool-level savings result (#3) */
+export interface ToolSavingsRow {
+    tool: string;
+    rawBytes: number;
+    contextBytes: number;
+    savedBytes: number;
+}
+/** Sandbox I/O result (#19) */
+export interface SandboxIO {
+    inputBytes: number;
+    outputBytes: number;
+}
+/** Pattern insight result (#6) */
+export interface PatternInsight {
+    pattern: string;
+    confidence: number;
+}
+/** Runtime stats tracked by server.ts during a live session. */
+export interface RuntimeStats {
+    bytesReturned: Record<string, number>;
+    bytesIndexed: number;
+    bytesSandboxed: number;
+    calls: Record<string, number>;
+    sessionStart: number;
+    cacheHits: number;
+    cacheBytesSaved: number;
+}
+/** Unified report combining runtime stats, DB analytics, and continuity data. */
+export interface FullReport {
+    /** Runtime context savings (passed in, not from DB) */
+    savings: {
+        processed_kb: number;
+        entered_kb: number;
+        saved_kb: number;
+        pct: number;
+        savings_ratio: number;
+        by_tool: Array<{
+            tool: string;
+            calls: number;
+            context_kb: number;
+            tokens: number;
+        }>;
+        total_calls: number;
+        total_bytes_returned: number;
+        kept_out: number;
+        total_processed: number;
+    };
+    cache?: {
+        hits: number;
+        bytes_saved: number;
+        ttl_hours_left: number;
+        total_with_cache: number;
+        total_savings_ratio: number;
+    };
+    /** Session metadata from SessionDB */
+    session: {
+        id: string;
+        duration_min: number | null;
+        tool_calls: number;
+        uptime_min: string;
+    };
+    /** Activity metrics */
+    activity: {
+        commits: number;
+        errors: number;
+        error_rate_pct: number;
+        tool_diversity: number;
+        efficiency_score: number;
+        commits_per_session_avg: number;
+        session_outcome: string;
+        productive_pct: number;
+        exploratory_pct: number;
+    };
+    /** Pattern metrics */
+    patterns: {
+        hourly_commits: number[];
+        weekly_trend: Array<{
+            day: string;
+            sessions: number;
+        }>;
+        iteration_cycles: number;
+        rework: Array<{
+            file: string;
+            edits: number;
+        }>;
+    };
+    /** Health metrics */
+    health: {
+        claude_md_freshness: Array<{
+            project: string;
+            days_ago: number | null;
+        }>;
+        compactions_this_week: number;
+        weekly_sessions: number;
+        permission_denials: number;
+    };
+    /** Agent metrics */
+    agents: {
+        subagents: Array<{
+            type: string;
+            count: number;
+        }>;
+        skills: Array<{
+            name: string;
+            count: number;
+        }>;
+    };
+    /** Session continuity data */
+    continuity: {
+        total_events: number;
+        by_category: Array<{
+            category: string;
+            count: number;
+            label: string;
+            preview: string;
+            why: string;
+        }>;
+        compact_count: number;
+        resume_ready: boolean;
+    };
+}
+/** Human-readable labels for event categories. */
+export declare const categoryLabels: Record<string, string>;
+/** Explains why each category matters for continuity. */
+export declare const categoryHints: Record<string, string>;
+export declare class AnalyticsEngine {
+    private readonly 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: DatabaseAdapter);
+    /**
+     * #5 Weekly Trend — sessions started per day over the last 7 days.
+     * Returns an array of { day, sessions } sorted by day.
+     */
+    weeklyTrend(): WeeklyTrendRow[];
+    /**
+     * #7 Session Continuity — event category distribution for a session.
+     * Shows what the session focused on (file ops, git, errors, etc.).
+     */
+    sessionContinuity(sessionId: string): ContinuityRow[];
+    /**
+     * #8 Commit Count — number of git commits made during a session.
+     * Matches events where category='git' and data contains 'commit'.
+     */
+    commitCount(sessionId: string): number;
+    /**
+     * #9 Error Count — total error events in a session.
+     */
+    errorCount(sessionId: string): number;
+    /**
+     * #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: string): number | 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: string): number;
+    /**
+     * #12 Tool Diversity — number of distinct MCP tools used in a session.
+     * Higher diversity suggests more sophisticated tool usage.
+     */
+    toolDiversity(sessionId: string): number;
+    /**
+     * #14 Hourly Productivity — event distribution by hour of day.
+     * Optionally scoped to a session; omit sessionId for all sessions.
+     */
+    hourlyProductivity(sessionId?: string): HourlyRow[];
+    /**
+     * #15 Project Distribution — session count per project directory.
+     * Sorted descending by session count.
+     */
+    projectDistribution(): ProjectRow[];
+    /**
+     * #16 Compaction Count — number of snapshot compactions for a session.
+     * Higher counts indicate longer/more active sessions.
+     */
+    compactionCount(sessionId: string): number;
+    /**
+     * #17 Weekly Session Count — total sessions started in the last 7 days.
+     */
+    weeklySessionCount(): number;
+    /**
+     * #18 Commits Per Session — average commits across all sessions.
+     * Returns 0 when no sessions exist (NULLIF prevents division by zero).
+     */
+    commitsPerSession(): number;
+    /**
+     * #22 CLAUDE.md Freshness — last update timestamp for each rule file.
+     * Helps identify stale configuration files.
+     */
+    claudeMdFreshness(): FreshnessRow[];
+    /**
+     * #24 Rework Rate — files edited more than once (indicates iteration/rework).
+     * Sorted descending by edit count.
+     */
+    reworkRate(sessionId?: string): ReworkRow[];
+    /**
+     * #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: string): "productive" | "exploratory";
+    /**
+     * #26 Subagent Usage — subagent spawn counts grouped by type/purpose.
+     */
+    subagentUsage(sessionId: string): SubagentRow[];
+    /**
+     * #27 Skill Usage — skill/slash-command invocation frequency.
+     * Sorted descending by invocation count.
+     */
+    skillUsage(sessionId: string): SkillRow[];
+    /**
+     * #4 Session Mix — percentage of sessions classified as productive.
+     * Iterates all sessions and uses #25 (sessionOutcome) to classify each.
+     */
+    sessionMix(): {
+        productive: number;
+        exploratory: number;
+    };
+    /**
+     * #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: string): number;
+    /**
+     * #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: string): number;
+    /**
+     * #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: number, contextBytes: number): ContextSavings;
+    /**
+     * #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: number, outputBytes: number): ThinkInCodeComparison;
+    /**
+     * #3 Tool Savings — per-tool breakdown of context savings.
+     *
+     * Stub: requires per-tool accumulators in server.ts.
+     */
+    static toolSavings(tools: Array<{
+        tool: string;
+        rawBytes: number;
+        contextBytes: number;
+    }>): ToolSavingsRow[];
+    /**
+     * #19 Sandbox I/O — total input/output bytes processed by the sandbox.
+     *
+     * Stub: requires PolyglotExecutor byte counters.
+     */
+    static sandboxIO(inputBytes: number, outputBytes: number): SandboxIO;
+    /**
+     * #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: string): string;
+    /**
+     * #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: string): number;
+    /**
+     * 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: RuntimeStats): FullReport;
+}
+/**
+ * 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 declare function formatReport(report: FullReport): string;