@winspan/claude-forge 8.54.4 → 9.2.0

package/dist/core/storage/knowledge.d.ts

@@ -0,0 +1,106 @@
+/**
+ * KnowledgeOperations — KB telemetry tables (v9.5).
+ *
+ * Two append-only tables:
+ *   kb_query_log — every queryKnowledge call (when daemon supplies storage).
+ *   kb_build_log — every BuildManager.start (one row per build_id, updated to done/error).
+ *
+ * Reading helpers:
+ *   queryKbStats(project_path)    — aggregates for /api/knowledge/stats
+ *   queryLastKbBuild(project_path)— most recent build row for /api/knowledge/stats
+ *   listKnownProjectPaths()       — distinct project_path values in sessions
+ *
+ * All writes/reads are best-effort; callers are responsible for fail-silent
+ * wrapping (the v9.5 spec mandates: telemetry MUST NEVER break the user's
+ * query/build main path).
+ */
+import type Database from 'better-sqlite3';
+export interface KbQueryLogEntry {
+    ts: number;
+    project_path: string;
+    query: string;
+    result_count: number;
+    /** Number of AI calls made during this query (0 for keyword path; kept for future telemetry). */
+    ai_call_count?: number;
+    ai_input_tokens?: number | null;
+    ai_output_tokens?: number | null;
+    duration_ms: number;
+}
+export interface KbStatsRow {
+    total_queries: number;
+    total_ai_calls: number;
+    total_ai_input_tokens: number;
+    total_ai_output_tokens: number;
+}
+export interface KbBuildLogEntry {
+    build_id: string;
+    ts: number;
+    project_path: string;
+    options_json: string;
+    status: 'running' | 'done' | 'error';
+    stats_json?: string;
+    duration_ms?: number;
+    error_message?: string;
+}
+export interface KbBuildLogRow {
+    build_id: string;
+    ts: number;
+    project_path: string;
+    options_json: string;
+    stats_json: string | null;
+    duration_ms: number | null;
+    status: 'running' | 'done' | 'error';
+    error_message: string | null;
+}
+export declare class KnowledgeOperations {
+    private db;
+    constructor(db: Database.Database);
+    writeKbQueryLog(entry: KbQueryLogEntry): void;
+    queryKbStats(projectPath: string): KbStatsRow;
+    /**
+     * Upsert on conflict(build_id) — if the same build_id is started twice
+     * (test-only / replays), overwrite the previous row.
+     */
+    writeKbBuildLog(entry: KbBuildLogEntry): void;
+    /**
+     * Dynamic partial update — only patches fields the caller actually supplied.
+     */
+    updateKbBuildLog(buildId: string, updates: {
+        status?: 'running' | 'done' | 'error';
+        stats_json?: string | null;
+        duration_ms?: number | null;
+        error_message?: string | null;
+    }): void;
+    queryLastKbBuild(projectPath: string): KbBuildLogRow | null;
+    /**
+     * Distinct project_path values observed in the sessions table. Used by
+     * /api/knowledge/projects and the project-param allowlist guard.
+     *
+     * Empty/NULL paths are filtered out (sessions sometimes carries '' before
+     * project resolution lands).
+     */
+    listKnownProjectPaths(): string[];
+    /**
+     * Map of project_path → most recent `sessions.last_event_time` (ISO string)
+     * or `null` if a project has no sessions with a non-null timestamp.
+     *
+     * Used by /api/knowledge/projects to render "last active" per project.
+     * Returns one row per distinct project_path; callers should iterate the
+     * map directly (Map.get returns undefined for unknown paths — treat as null).
+     */
+    queryLastEventAtPerProject(): Map<string, string | null>;
+    /**
+     * Query KB tool usage statistics from events table.
+     * Returns aggregated stats for the specified project and time window.
+     *
+     * @param projectPath - Project root path
+     * @param days - Number of days to look back (default: 7)
+     */
+    queryKbUsageStats(projectPath: string, days?: number): {
+        total: number;
+        byTool: Record<string, number>;
+        recentSessions: string[];
+        lastUsedAt: string | null;
+    };
+}
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/core/storage/knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../../src/core/storage/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAM3C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,qBAAa,mBAAmB;IAClB,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,QAAQ,CAAC,QAAQ;IAIzC,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAqB7C,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU;IA8B7C;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IA6B7C;;OAEG;IACH,gBAAgB,CACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;QACtC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,GACA,IAAI;IA+BP,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAe3D;;;;;;OAMG;IACH,qBAAqB,IAAI,MAAM,EAAE;IAWjC;;;;;;;OAOG;IACH,0BAA0B,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAcxD;;;;;;OAMG;IACH,iBAAiB,CACf,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,MAAU,GACf;QACD,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B;CA+DF"}

package/dist/core/storage/knowledge.js

@@ -0,0 +1,202 @@
+/**
+ * KnowledgeOperations — KB telemetry tables (v9.5).
+ *
+ * Two append-only tables:
+ *   kb_query_log — every queryKnowledge call (when daemon supplies storage).
+ *   kb_build_log — every BuildManager.start (one row per build_id, updated to done/error).
+ *
+ * Reading helpers:
+ *   queryKbStats(project_path)    — aggregates for /api/knowledge/stats
+ *   queryLastKbBuild(project_path)— most recent build row for /api/knowledge/stats
+ *   listKnownProjectPaths()       — distinct project_path values in sessions
+ *
+ * All writes/reads are best-effort; callers are responsible for fail-silent
+ * wrapping (the v9.5 spec mandates: telemetry MUST NEVER break the user's
+ * query/build main path).
+ */
+export class KnowledgeOperations {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ── kb_query_log ─────────────────────────────────────────────────────────
+    writeKbQueryLog(entry) {
+        this.db
+            .prepare(`INSERT INTO kb_query_log (
+          ts, project_path, query, result_count,
+          ai_call_count, ai_input_tokens, ai_output_tokens,
+          duration_ms
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(entry.ts, entry.project_path, entry.query, entry.result_count, entry.ai_call_count ?? 0, entry.ai_input_tokens ?? null, entry.ai_output_tokens ?? null, entry.duration_ms);
+    }
+    queryKbStats(projectPath) {
+        const row = this.db
+            .prepare(`SELECT
+          COUNT(*) AS total_queries,
+          SUM(COALESCE(ai_call_count,0)) AS total_ai_calls,
+          SUM(COALESCE(ai_input_tokens,0)) AS total_ai_input_tokens,
+          SUM(COALESCE(ai_output_tokens,0)) AS total_ai_output_tokens
+         FROM kb_query_log
+         WHERE project_path = ?`)
+            .get(projectPath);
+        return {
+            total_queries: row?.total_queries ?? 0,
+            total_ai_calls: row?.total_ai_calls ?? 0,
+            total_ai_input_tokens: row?.total_ai_input_tokens ?? 0,
+            total_ai_output_tokens: row?.total_ai_output_tokens ?? 0,
+        };
+    }
+    // ── kb_build_log ─────────────────────────────────────────────────────────
+    /**
+     * Upsert on conflict(build_id) — if the same build_id is started twice
+     * (test-only / replays), overwrite the previous row.
+     */
+    writeKbBuildLog(entry) {
+        this.db
+            .prepare(`INSERT INTO kb_build_log (
+          build_id, ts, project_path, options_json, stats_json,
+          duration_ms, status, error_message
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(build_id) DO UPDATE SET
+          ts = excluded.ts,
+          project_path = excluded.project_path,
+          options_json = excluded.options_json,
+          stats_json = excluded.stats_json,
+          duration_ms = excluded.duration_ms,
+          status = excluded.status,
+          error_message = excluded.error_message,
+          updated_at = datetime('now')`)
+            .run(entry.build_id, entry.ts, entry.project_path, entry.options_json, entry.stats_json ?? null, entry.duration_ms ?? null, entry.status, entry.error_message ?? null);
+    }
+    /**
+     * Dynamic partial update — only patches fields the caller actually supplied.
+     */
+    updateKbBuildLog(buildId, updates) {
+        const setClauses = [];
+        const params = [];
+        if (updates.status !== undefined) {
+            setClauses.push('status = ?');
+            params.push(updates.status);
+        }
+        if (updates.stats_json !== undefined) {
+            setClauses.push('stats_json = ?');
+            params.push(updates.stats_json);
+        }
+        if (updates.duration_ms !== undefined) {
+            setClauses.push('duration_ms = ?');
+            params.push(updates.duration_ms);
+        }
+        if (updates.error_message !== undefined) {
+            setClauses.push('error_message = ?');
+            params.push(updates.error_message);
+        }
+        if (setClauses.length === 0)
+            return;
+        setClauses.push("updated_at = datetime('now')");
+        params.push(buildId);
+        this.db
+            .prepare(`UPDATE kb_build_log SET ${setClauses.join(', ')} WHERE build_id = ?`)
+            .run(...params);
+    }
+    queryLastKbBuild(projectPath) {
+        const row = this.db
+            .prepare(`SELECT build_id, ts, project_path, options_json, stats_json,
+                duration_ms, status, error_message
+         FROM kb_build_log
+         WHERE project_path = ?
+         ORDER BY ts DESC LIMIT 1`)
+            .get(projectPath);
+        return row ?? null;
+    }
+    // ── sessions-derived helpers ─────────────────────────────────────────────
+    /**
+     * Distinct project_path values observed in the sessions table. Used by
+     * /api/knowledge/projects and the project-param allowlist guard.
+     *
+     * Empty/NULL paths are filtered out (sessions sometimes carries '' before
+     * project resolution lands).
+     */
+    listKnownProjectPaths() {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT project_path FROM sessions
+         WHERE project_path IS NOT NULL AND project_path != ''
+         ORDER BY project_path`)
+            .all();
+        return rows.map((r) => r.project_path);
+    }
+    /**
+     * Map of project_path → most recent `sessions.last_event_time` (ISO string)
+     * or `null` if a project has no sessions with a non-null timestamp.
+     *
+     * Used by /api/knowledge/projects to render "last active" per project.
+     * Returns one row per distinct project_path; callers should iterate the
+     * map directly (Map.get returns undefined for unknown paths — treat as null).
+     */
+    queryLastEventAtPerProject() {
+        const rows = this.db
+            .prepare(`SELECT project_path, MAX(last_event_time) AS last_event_at
+         FROM sessions
+         WHERE project_path IS NOT NULL AND project_path != ''
+         GROUP BY project_path`)
+            .all();
+        return new Map(rows.map((r) => [r.project_path, r.last_event_at]));
+    }
+    // ── KB usage stats (from events table) ──────────────────────────────────
+    /**
+     * Query KB tool usage statistics from events table.
+     * Returns aggregated stats for the specified project and time window.
+     *
+     * @param projectPath - Project root path
+     * @param days - Number of days to look back (default: 7)
+     */
+    queryKbUsageStats(projectPath, days = 7) {
+        const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+        // Total KB tool calls in the time window
+        const totalRow = this.db
+            .prepare(`SELECT COUNT(*) as count
+         FROM events
+         WHERE project_path = ?
+           AND tool_name LIKE 'mcp__claude-forge__knowledge%'
+           AND timestamp > ?`)
+            .get(projectPath, cutoff);
+        // Group by tool name
+        const byToolRows = this.db
+            .prepare(`SELECT tool_name, COUNT(*) as count
+         FROM events
+         WHERE project_path = ?
+           AND tool_name LIKE 'mcp__claude-forge__knowledge%'
+           AND timestamp > ?
+         GROUP BY tool_name`)
+            .all(projectPath, cutoff);
+        const byTool = {};
+        for (const row of byToolRows) {
+            // Strip 'mcp__claude-forge__' prefix for cleaner display
+            const shortName = row.tool_name.replace('mcp__claude-forge__', '');
+            byTool[shortName] = row.count;
+        }
+        // Recent sessions that used KB tools
+        const sessionRows = this.db
+            .prepare(`SELECT DISTINCT session_id
+         FROM events
+         WHERE project_path = ?
+           AND tool_name LIKE 'mcp__claude-forge__knowledge%'
+           AND timestamp > ?
+         ORDER BY timestamp DESC
+         LIMIT 5`)
+            .all(projectPath, cutoff);
+        // Last usage timestamp (all-time, not limited by days)
+        const lastUsedRow = this.db
+            .prepare(`SELECT MAX(timestamp) as last_used
+         FROM events
+         WHERE project_path = ?
+           AND tool_name LIKE 'mcp__claude-forge__knowledge%'`)
+            .get(projectPath);
+        return {
+            total: totalRow?.count ?? 0,
+            byTool,
+            recentSessions: sessionRows.map((r) => r.session_id),
+            lastUsedAt: lastUsedRow?.last_used ?? null,
+        };
+    }
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/core/storage/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../../src/core/storage/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAiDH,MAAM,OAAO,mBAAmB;IACV;IAApB,YAAoB,EAAqB;QAArB,OAAE,GAAF,EAAE,CAAmB;IAAG,CAAC;IAE7C,4EAA4E;IAE5E,eAAe,CAAC,KAAsB;QACpC,IAAI,CAAC,EAAE;aACJ,OAAO,CACN;;;;0CAIkC,CACnC;aACA,GAAG,CACF,KAAK,CAAC,EAAE,EACR,KAAK,CAAC,YAAY,EAClB,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,YAAY,EAClB,KAAK,CAAC,aAAa,IAAI,CAAC,EACxB,KAAK,CAAC,eAAe,IAAI,IAAI,EAC7B,KAAK,CAAC,gBAAgB,IAAI,IAAI,EAC9B,KAAK,CAAC,WAAW,CAClB,CAAC;IACN,CAAC;IAED,YAAY,CAAC,WAAmB;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE;aAChB,OAAO,CACN;;;;;;gCAMwB,CACzB;aACA,GAAG,CAAC,WAAW,CAOL,CAAC;QAEd,OAAO;YACL,aAAa,EAAE,GAAG,EAAE,aAAa,IAAI,CAAC;YACtC,cAAc,EAAE,GAAG,EAAE,cAAc,IAAI,CAAC;YACxC,qBAAqB,EAAE,GAAG,EAAE,qBAAqB,IAAI,CAAC;YACtD,sBAAsB,EAAE,GAAG,EAAE,sBAAsB,IAAI,CAAC;SACzD,CAAC;IACJ,CAAC;IAED,4EAA4E;IAE5E;;;OAGG;IACH,eAAe,CAAC,KAAsB;QACpC,IAAI,CAAC,EAAE;aACJ,OAAO,CACN;;;;;;;;;;;;uCAY+B,CAChC;aACA,GAAG,CACF,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,EAAE,EACR,KAAK,CAAC,YAAY,EAClB,KAAK,CAAC,YAAY,EAClB,KAAK,CAAC,UAAU,IAAI,IAAI,EACxB,KAAK,CAAC,WAAW,IAAI,IAAI,EACzB,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,aAAa,IAAI,IAAI,CAC5B,CAAC;IACN,CAAC;IAED;;OAEG;IACH,gBAAgB,CACd,OAAe,EACf,OAKC;QAED,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,MAAM,MAAM,GAAc,EAAE,CAAC;QAE7B,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACrC,UAAU,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACtC,UAAU,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YACnC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACxC,UAAU,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YACrC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACrC,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAEpC,UAAU,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;QAChD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAErB,IAAI,CAAC,EAAE;aACJ,OAAO,CAAC,2BAA2B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC;aAC9E,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IACpB,CAAC;IAED,gBAAgB,CAAC,WAAmB;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE;aAChB,OAAO,CACN;;;;kCAI0B,CAC3B;aACA,GAAG,CAAC,WAAW,CAA8B,CAAC;QACjD,OAAO,GAAG,IAAI,IAAI,CAAC;IACrB,CAAC;IAED,4EAA4E;IAE5E;;;;;;OAMG;IACH,qBAAqB;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CACN;;+BAEuB,CACxB;aACA,GAAG,EAAqC,CAAC;QAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;OAOG;IACH,0BAA0B;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CACN;;;+BAGuB,CACxB;aACA,GAAG,EAAmE,CAAC;QAC1E,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IACrE,CAAC;IAED,2EAA2E;IAE3E;;;;;;OAMG;IACH,iBAAiB,CACf,WAAmB,EACnB,OAAe,CAAC;QAOhB,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAE/E,yCAAyC;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,EAAE;aACrB,OAAO,CACN;;;;6BAIqB,CACtB;aACA,GAAG,CAAC,WAAW,EAAE,MAAM,CAAkC,CAAC;QAE7D,qBAAqB;QACrB,MAAM,UAAU,GAAG,IAAI,CAAC,EAAE;aACvB,OAAO,CACN;;;;;4BAKoB,CACrB;aACA,GAAG,CAAC,WAAW,EAAE,MAAM,CAAgD,CAAC;QAE3E,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,yDAAyD;YACzD,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;YACnE,MAAM,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;QAChC,CAAC;QAED,qCAAqC;QACrC,MAAM,WAAW,GAAG,IAAI,CAAC,EAAE;aACxB,OAAO,CACN;;;;;;iBAMS,CACV;aACA,GAAG,CAAC,WAAW,EAAE,MAAM,CAAkC,CAAC;QAE7D,uDAAuD;QACvD,MAAM,WAAW,GAAG,IAAI,CAAC,EAAE;aACxB,OAAO,CACN;;;8DAGsD,CACvD;aACA,GAAG,CAAC,WAAW,CAA6C,CAAC;QAEhE,OAAO;YACL,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI,CAAC;YAC3B,MAAM;YACN,cAAc,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;YACpD,UAAU,EAAE,WAAW,EAAE,SAAS,IAAI,IAAI;SAC3C,CAAC;IACJ,CAAC;CACF"}

package/dist/core/storage/maintenance.d.ts

@@ -9,7 +9,12 @@ export interface CleanOldDataResult {
     events: number;
     routing: number;
     skills: number;
-    tokens: number;
+    /**
+     * task_events: 关联表（无自身 timestamp）。清理基于 events 表删除时
+     * 的孤儿行（event_id 已不存在于 events 表）。SQLite 默认未开启
+     * `PRAGMA foreign_keys`，CASCADE 不会自动触发，因此这里显式 DELETE。
+     */
+    taskEvents: number;
 }
 export declare class MaintenanceOperations {
     private db;
@@ -20,24 +25,46 @@ export declare class MaintenanceOperations {
      *
      * 范围：
      *   - events            (timestamp TEXT, ISO)
+     *   - task_events       （关联表 — 删除指向已被清理 events 的行）
      *   - routing_events    (ts INTEGER, unix ms)
      *   - skill_invocations (timestamp INTEGER, unix ms)
-     *   - token_usage       (timestamp INTEGER, unix ms)
      *
-     * **不删** `sessions` 和 `tasks`：它们是用户可见的"会话历史 / 任务列表"，
-     * 删除会破坏 UI 体验。它们的体积也远小于事实表。
+     * **不删** 的表（按设计保留）：
+     *   - sessions / tasks       — 用户可见的"会话历史 / 任务列表"，
+     *                              删除会破坏 UI 体验；它们的体积也远小于
+     *                              事实表。
+     *   - kb_build_log           — 知识库构建审计日志，按 build_id 持久化，
+     *                              是审计 / 回溯依据。
+     *   - kb_query_log           — 知识库查询遥测，体积小且按需采样。
+     *                              如未来体量过大可单独窗口清理。
+     *   - injections             — 与 events 一一对应的注入审计；
+     *                              schema 已声明 ON DELETE CASCADE，但
+     *                              SQLite 默认未启用 `PRAGMA foreign_keys`，
+     *                              当前依赖体积自然衰减。如需主动清，
+     *                              再走与 task_events 同样的孤儿删除模式。
+     *
+     * **执行顺序**：先删 task_events 中指向 *将被* 删除 events 的行，
+     * 再删 events。否则 events 删完后 task_events 已经是孤儿，仍可清，
+     * 但顺序反过来会让 SQL 的 IN 子查询少一次范围。
      *
      * @param daysToKeep 保留最近多少天（默认 30）
      * @returns 各表删除行数（结构化以便上层做监控/日志）
      */
     cleanOldData(daysToKeep?: number): CleanOldDataResult;
-    /**
-     * @deprecated 仅清 events 表的窄接口。新代码请用 `cleanOldData(days)`。
-     * 保留是为了向后兼容现有 daemon / 测试，下个大版本删除。
-     */
-    cleanOldEvents(daysToKeep?: number): number;
     runMaintenance(maxSizeMb: number): void;
     vacuum(): void;
+    /**
+     * Reclaim free pages from the auto_vacuum=INCREMENTAL freelist back to the
+     * OS. Returns the number of pages reclaimed (0 if auto_vacuum is not
+     * INCREMENTAL or the freelist is empty).
+     *
+     * Each page is 4 KB (see base.ts page_size), so reclaiming 1000 pages frees
+     * about 4 MB. Bounded by `maxPages` to keep the writer-lock window short.
+     *
+     * Safe to call when auto_vacuum != INCREMENTAL — SQLite silently no-ops and
+     * we return 0.
+     */
+    incrementalVacuum(maxPages?: number): number;
     getDbSizeMb(): number;
 }
 //# sourceMappingURL=maintenance.d.ts.map

package/dist/core/storage/maintenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../src/core/storage/maintenance.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAI3C,4BAA4B;AAC5B,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,MAAM;gBADN,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,MAAM;IAGxB;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,UAAU,GAAE,MAAW,GAAG,kBAAkB;IAoBzD;;;OAGG;IACH,cAAc,CAAC,UAAU,GAAE,MAAW,GAAG,MAAM;IAgB/C,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAavC,MAAM,IAAI,IAAI;IAId,WAAW,IAAI,MAAM;CAItB"}
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../src/core/storage/maintenance.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAI3C,4BAA4B;AAC5B,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,MAAM;gBADN,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,MAAM;IAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,YAAY,CAAC,UAAU,GAAE,MAAW,GAAG,kBAAkB;IA+BzD,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAavC,MAAM,IAAI,IAAI;IAId;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,QAAQ,GAAE,MAAa,GAAG,MAAM;IAgBlD,WAAW,IAAI,MAAM;CAItB"}

package/dist/core/storage/maintenance.js

@@ -17,12 +17,27 @@ export class MaintenanceOperations {
      *
      * 范围：
      *   - events            (timestamp TEXT, ISO)
+     *   - task_events       （关联表 — 删除指向已被清理 events 的行）
      *   - routing_events    (ts INTEGER, unix ms)
      *   - skill_invocations (timestamp INTEGER, unix ms)
-     *   - token_usage       (timestamp INTEGER, unix ms)
      *
-     * **不删** `sessions` 和 `tasks`：它们是用户可见的"会话历史 / 任务列表"，
-     * 删除会破坏 UI 体验。它们的体积也远小于事实表。
+     * **不删** 的表（按设计保留）：
+     *   - sessions / tasks       — 用户可见的"会话历史 / 任务列表"，
+     *                              删除会破坏 UI 体验；它们的体积也远小于
+     *                              事实表。
+     *   - kb_build_log           — 知识库构建审计日志，按 build_id 持久化，
+     *                              是审计 / 回溯依据。
+     *   - kb_query_log           — 知识库查询遥测，体积小且按需采样。
+     *                              如未来体量过大可单独窗口清理。
+     *   - injections             — 与 events 一一对应的注入审计；
+     *                              schema 已声明 ON DELETE CASCADE，但
+     *                              SQLite 默认未启用 `PRAGMA foreign_keys`，
+     *                              当前依赖体积自然衰减。如需主动清，
+     *                              再走与 task_events 同样的孤儿删除模式。
+     *
+     * **执行顺序**：先删 task_events 中指向 *将被* 删除 events 的行，
+     * 再删 events。否则 events 删完后 task_events 已经是孤儿，仍可清，
+     * 但顺序反过来会让 SQL 的 IN 子查询少一次范围。
      *
      * @param daysToKeep 保留最近多少天（默认 30）
      * @returns 各表删除行数（结构化以便上层做监控/日志）
@@ -32,32 +47,22 @@ export class MaintenanceOperations {
         cutoffDate.setDate(cutoffDate.getDate() - daysToKeep);
         const cutoffIso = cutoffDate.toISOString();
         const cutoffMs = cutoffDate.getTime();
+        // 1. task_events 先删 —— 用即将被删 events 的 event_id 做范围。
+        //    无自身 timestamp，必须借 events.timestamp 反向定位。
+        const taskEvents = this.db
+            .prepare(`DELETE FROM task_events
+         WHERE event_id IN (SELECT event_id FROM events WHERE timestamp < ?)`)
+            .run(cutoffIso).changes;
+        // 2. events
         const events = this.db.prepare(`DELETE FROM events WHERE timestamp < ?`).run(cutoffIso).changes;
+        // 3. 其它独立时间序列表
         const routing = this.db.prepare(`DELETE FROM routing_events WHERE ts < ?`).run(cutoffMs).changes;
         const skills = this.db.prepare(`DELETE FROM skill_invocations WHERE timestamp < ?`).run(cutoffMs).changes;
-        const tokens = this.db.prepare(`DELETE FROM token_usage WHERE timestamp < ?`).run(cutoffMs).changes;
-        const total = events + routing + skills + tokens;
+        const total = events + taskEvents + routing + skills;
         if (total > 0) {
-            logger.info(`[Storage] cleanOldData(${daysToKeep}d): events=${events}, routing=${routing}, skills=${skills}, tokens=${tokens}`);
-        }
-        return { events, routing, skills, tokens };
-    }
-    /**
-     * @deprecated 仅清 events 表的窄接口。新代码请用 `cleanOldData(days)`。
-     * 保留是为了向后兼容现有 daemon / 测试，下个大版本删除。
-     */
-    cleanOldEvents(daysToKeep = 30) {
-        const cutoffDate = new Date();
-        cutoffDate.setDate(cutoffDate.getDate() - daysToKeep);
-        const cutoff = cutoffDate.toISOString();
-        const result = this.db.prepare(`
-      DELETE FROM events WHERE timestamp < ?
-    `).run(cutoff);
-        const deleted = result.changes;
-        if (deleted > 0) {
-            logger.info(`[Storage] Cleaned ${deleted} events older than ${daysToKeep} days`);
+            logger.info(`[Storage] cleanOldData(${daysToKeep}d): events=${events}, taskEvents=${taskEvents}, routing=${routing}, skills=${skills}`);
         }
-        return deleted;
+        return { events, routing, skills, taskEvents };
     }
     runMaintenance(maxSizeMb) {
         const sizeMb = this.getDbSizeMb();
@@ -72,6 +77,33 @@ export class MaintenanceOperations {
     vacuum() {
         this.db.exec('VACUUM');
     }
+    /**
+     * Reclaim free pages from the auto_vacuum=INCREMENTAL freelist back to the
+     * OS. Returns the number of pages reclaimed (0 if auto_vacuum is not
+     * INCREMENTAL or the freelist is empty).
+     *
+     * Each page is 4 KB (see base.ts page_size), so reclaiming 1000 pages frees
+     * about 4 MB. Bounded by `maxPages` to keep the writer-lock window short.
+     *
+     * Safe to call when auto_vacuum != INCREMENTAL — SQLite silently no-ops and
+     * we return 0.
+     */
+    incrementalVacuum(maxPages = 1000) {
+        const before = this.db.pragma('freelist_count', { simple: true });
+        try {
+            this.db.exec(`PRAGMA incremental_vacuum(${Math.max(0, Math.floor(maxPages))})`);
+        }
+        catch (err) {
+            logger.warn(`[Storage] incremental_vacuum(${maxPages}) failed: ${err}`);
+            return 0;
+        }
+        const after = this.db.pragma('freelist_count', { simple: true });
+        const reclaimed = Math.max(0, Number(before) - Number(after));
+        if (reclaimed > 0) {
+            logger.info(`[Storage] incremental_vacuum reclaimed ${reclaimed} pages (~${(reclaimed * 4 / 1024).toFixed(1)} MB)`);
+        }
+        return reclaimed;
+    }
     getDbSizeMb() {
         if (!existsSync(this.dbPath))
             return 0;

package/dist/core/storage/maintenance.js.map

@@ -1 +1 @@
-{"version":3,"file":"maintenance.js","sourceRoot":"","sources":["../../../src/core/storage/maintenance.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"maintenance.js","sourceRoot":"","sources":["../../../src/core/storage/maintenance.ts"],"names":[],"mappings":"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"}

package/dist/core/storage/pipeline-rollup.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Pipeline rollup — Phase 2d real-time orchestration link view.
+ *
+ * Given the most recent N UserPromptSubmit events, this module produces one
+ * `PipelineRow` per prompt with 5 status dots:
+ *
+ *   ① 接收     events.hook_type='UserPromptSubmit'
+ *   ② 意图     injections.source_handler='UserPromptSubmitHandler:intent'
+ *               (or :intent_fallback:L1/L2/L3 — see Phase 2a)
+ *   ③ KB+Skill  injections.source_handler='UserPromptSubmitHandler:kb' /
+ *                                          :workflow_rec
+ *   ④ Spec      decisions row (kind='spec') keyed by approval_token
+ *   ⑤ 执行     tool_intercepts.decision + routing_events.routed_to_name
+ *
+ * Each dot is one of 4 states (P1 fix from doc-reviewer 2026-05-22):
+ *   - 'ok'      green — the step ran and produced a usable result
+ *   - 'fail'    red   — the step ran but the outcome was a refusal / failure
+ *   - 'skipped' light gray — the step was intentionally skipped by design
+ *                            (e.g. workflow_type='explore' does not generate
+ *                            a spec; KB miss is "skipped" not "missing")
+ *   - 'missing' dark gray  — the step should have produced data but didn't
+ *                            (possible bug or new module not wired up yet)
+ *
+ * The output is consumed by `src/web/routes/pipeline.ts` and rendered as
+ * 4-coloured circles in `web/src/pages/InsightsPipeline.tsx`.
+ *
+ * Performance note: we do 1 query for prompts + 5 batch queries for the rest,
+ * then assemble rows in memory. P95 stays < 50ms for 50 prompts on the dev
+ * dataset (988 prompts total). No SQL JOIN — see spec § 3.1 rationale.
+ */
+import type { SQLiteStorage } from './sqlite.js';
+export type DotStatus = 'ok' | 'fail' | 'skipped' | 'missing';
+export interface PipelineRow {
+    session_id: string;
+    /**
+     * task_id reverse-resolved via task_events. Null when the prompt has not
+     * been linked to a task yet (TaskSegmenter race / very old data).
+     *
+     * Added 2026-05-25 so the InsightsPipeline click handler can open the task
+     * drawer (TaskDetailContent — "what did this task actually do") instead of
+     * the noisy SessionDetailContent (entire session event firehose). The user
+     * complaint: "我想看的是任务的详细执行内容，你给我加载会话有什么用？"
+     */
+    task_id: string | null;
+    prompt_event_id: string | null;
+    prompt: string;
+    received_at: string;
+    project_path: string;
+    intent: {
+        workflow_type: string | null;
+        confidence: number | null;
+        suggested_agent: string | null;
+        fallback: boolean;
+        fallback_layer: number | null;
+    } | null;
+    kb: {
+        pages: Array<{
+            name: string;
+            score: number;
+        }>;
+        workflow_rec: {
+            recommended_agent_type: string;
+            recommended_workflow: string;
+            rec_outcome: string | null;
+        } | null;
+    } | null;
+    spec: {
+        spec_path: string;
+        token: string;
+        status: string;
+    } | null;
+    exec: {
+        spawned_agent: string | null;
+        first_tool: string | null;
+        intercept_decision: 'allow' | 'deny' | 'warn' | 'bypass' | 'dry_run';
+        intercept_outcome: string | null;
+        routing_obeyed: number | null;
+    } | null;
+    status_dots: [DotStatus, DotStatus, DotStatus, DotStatus, DotStatus];
+}
+/**
+ * 4-state status dot computation.
+ *
+ * The semantics distinguish "no data because nothing should have run" from
+ * "no data because something should have run but didn't" — important when
+ * the user is diagnosing whether a step is broken vs not applicable.
+ *
+ * @internal exported for testing.
+ */
+export declare function computeDots(row: {
+    intent: PipelineRow['intent'];
+    kb: PipelineRow['kb'];
+    spec: PipelineRow['spec'];
+    exec: PipelineRow['exec'];
+}): PipelineRow['status_dots'];
+export interface QueryPipelineRowsOpts {
+    /** How many recent prompts to return. Clamped 1..200. */
+    limit: number;
+    /** Optional project filter (exact match against events.project_path). */
+    projectPath?: string;
+    /**
+     * Single-prompt mode (DetailDrawer `?event_id=<id>`). When set, the rollup
+     * returns AT MOST one row — the pipeline link for exactly this prompt's
+     * UserPromptSubmit event — bypassing the `limit`/`projectPath` recent-N
+     * window. This is required because the drawer can open an arbitrarily-old
+     * prompt that would otherwise fall outside the default limit=50 set and
+     * silently 404 / come back empty. Returns `[]` when the id is unknown or the
+     * event is not a UserPromptSubmit.
+     */
+    eventId?: string;
+}
+/**
+ * Build the pipeline view: most-recent-N UserPromptSubmit events joined
+ * in-memory with the 5 downstream signal streams.
+ */
+export declare function queryPipelineRows(storage: SQLiteStorage, opts: QueryPipelineRowsOpts): PipelineRow[];
+//# sourceMappingURL=pipeline-rollup.d.ts.map

package/dist/core/storage/pipeline-rollup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-rollup.d.ts","sourceRoot":"","sources":["../../../src/core/storage/pipeline-rollup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAcjD,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IAErB,MAAM,EAAE;QACN,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,QAAQ,EAAE,OAAO,CAAC;QAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,GAAG,IAAI,CAAC;IAET,EAAE,EAAE;QACF,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC9C,YAAY,EAAE;YACZ,sBAAsB,EAAE,MAAM,CAAC;YAC/B,oBAAoB,EAAE,MAAM,CAAC;YAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;SAC5B,GAAG,IAAI,CAAC;KACV,GAAG,IAAI,CAAC;IAET,IAAI,EAAE;QACJ,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,GAAG,IAAI,CAAC;IAET,IAAI,EAAE;QACJ,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,kBAAkB,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;QACrE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,GAAG,IAAI,CAAC;IAET,WAAW,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;CACtE;AA2MD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE;IAC/B,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,EAAE,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC3B,GAAG,WAAW,CAAC,aAAa,CAAC,CAkF7B;AAED,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,qBAAqB,GAC1B,WAAW,EAAE,CAmFf"}