@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/core/storage/injections.js

@@ -4,18 +4,143 @@
  * 拆分自 sqlite.ts。
  */
 import { randomUUID } from 'node:crypto';
+// TODO (storage-perf follow-up, 2026-05-26): un-cached this.db.prepare(...)
+// callsites in InjectionOperations — promote to constructor Statement fields
+// in a future sweep. Hot path (writeInjection) is cached.
+//
+//   - countBySession                (lines ~60, ~67)
+//   - queryBySessions               (line ~87)
+//   - queryInjections / list*       (line ~127)
+//
+// Cached now: writeInjectionStmt (fires per system-msg injection).
 export class InjectionOperations {
     db;
+    writeInjectionStmt;
     constructor(db) {
         this.db = db;
+        this.writeInjectionStmt = db.prepare(`
+      INSERT INTO injections (id, event_id, session_id, timestamp, source_handler, injection_type, content, metadata_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
     }
     writeInjection(injection) {
         const id = injection.id || randomUUID();
-        const stmt = this.db.prepare(`
-      INSERT INTO injections (id, event_id, session_id, timestamp, source_handler, injection_type, content)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-    `);
-        stmt.run(id, injection.event_id ?? null, injection.session_id, injection.timestamp, injection.source_handler, injection.injection_type, injection.content);
+        this.writeInjectionStmt.run(id, injection.event_id ?? null, injection.session_id, injection.timestamp, injection.source_handler, injection.injection_type, injection.content, injection.metadata_json ?? null);
+    }
+    /**
+     * KB 采纳 telemetry（decision 148f7a0a）：把同一 session 中所有 KB 注入行
+     * （source_handler LIKE '%:kb'）里尚未标记的（adopted_at IS NULL）盖上
+     * 采纳时间戳。由 PostToolUse handler 在观察到主动 KB MCP 调用
+     * （tool_name 以 'mcp__claude-forge__knowledge' 开头）时调用。
+     *
+     * 只标记未标记行 —— 同会话第二次 KB 调用不会覆盖首次采纳时间。
+     * 返回受影响行数（0 = 该会话无待标记的 KB 注入）。
+     */
+    writeKbInjectionAdoption(session_id, adopted_at) {
+        const result = this.db
+            .prepare(`UPDATE injections
+         SET adopted_at = ?
+         WHERE session_id = ?
+           AND source_handler LIKE '%:kb'
+           AND adopted_at IS NULL`)
+            .run(adopted_at, session_id);
+        return result.changes;
+    }
+    /**
+     * KB 采纳率读路径（decision 148f7a0a）：近 N 天 KB 注入总数 vs 已被采纳
+     * （adopted_at 非 NULL）条数。`cf stats` 用它输出一行采纳率。
+     */
+    countKbAdoption(sinceIso) {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS total,
+                SUM(CASE WHEN adopted_at IS NOT NULL THEN 1 ELSE 0 END) AS adopted
+         FROM injections
+         WHERE source_handler LIKE '%:kb' AND timestamp >= ?`)
+            .get(sinceIso);
+        return { total: row?.total ?? 0, adopted: row?.adopted ?? 0 };
+    }
+    /**
+     * LOOP HINT 采纳 telemetry（decision e7d13697, 2026-06-11, Option C）：
+     * 把同一 session 中所有 `[LOOP HINT]` 注入行（source_handler =
+     * 'UserPromptSubmitHandler:loop-hint'）里尚未标记的（adopted_at IS NULL）
+     * 盖上采纳时间戳。由 PostToolUse handler 在观察到本会话实际运行
+     * `cf loop run`（Bash 工具调用，命令含 'loop run'）时调用——这是「主线程
+     * 采纳了 loop 建议」的可观测信号。
+     *
+     * 完全复用 KB 采纳的 `injections` + `adopted_at` 机制（decision 148f7a0a），
+     * 只换 source_handler 前缀。只标记未标记行——同会话第二次 `cf loop run` 不会
+     * 覆盖首次采纳时间。返回受影响行数（0 = 该会话无待标记的 loop-hint 注入）。
+     */
+    writeLoopHintAdoption(session_id, adopted_at) {
+        const result = this.db
+            .prepare(`UPDATE injections
+         SET adopted_at = ?
+         WHERE session_id = ?
+           AND source_handler = 'UserPromptSubmitHandler:loop-hint'
+           AND adopted_at IS NULL`)
+            .run(adopted_at, session_id);
+        return result.changes;
+    }
+    /**
+     * LOOP HINT 采纳率读路径（decision e7d13697）：近 N 天 loop-hint 注入总数 vs
+     * 已被采纳（adopted_at 非 NULL）条数。让我们日后据真实采纳率判 keep-vs-remove
+     * （Option C 之所以选过 D 的全部理由）。镜像 countKbAdoption。
+     */
+    countLoopHintAdoption(sinceIso) {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS total,
+                SUM(CASE WHEN adopted_at IS NOT NULL THEN 1 ELSE 0 END) AS adopted
+         FROM injections
+         WHERE source_handler = 'UserPromptSubmitHandler:loop-hint'
+           AND timestamp >= ?`)
+            .get(sinceIso);
+        return { total: row?.total ?? 0, adopted: row?.adopted ?? 0 };
+    }
+    /**
+     * Phase 2 metrics rollup: count injection rows for one session, optionally
+     * scoped to a specific source_handler (e.g. 'UserPromptSubmitHandler:kb' to
+     * count just MVP1 KB injects).
+     *
+     * Used by Stop handler to back-fill sessions.kb_inject_count.
+     */
+    countBySession(session_id, source_handler) {
+        if (source_handler) {
+            const row = this.db
+                .prepare(`SELECT COUNT(*) AS c FROM injections WHERE session_id = ? AND source_handler = ?`)
+                .get(session_id, source_handler);
+            return row?.c ?? 0;
+        }
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS c FROM injections WHERE session_id = ?`)
+            .get(session_id);
+        return row?.c ?? 0;
+    }
+    /**
+     * Phase 2d pipeline-view batch helper. Pulls every injection row for the
+     * given session IDs in a single `IN (?,?,...)` query so the rollup layer
+     * doesn't have to do N round-trips for N prompts.
+     *
+     * Returns rows ASC by timestamp so callers can scan forward when matching
+     * injections to a prompt.
+     */
+    queryBySessions(sessionIds) {
+        if (sessionIds.length === 0)
+            return [];
+        const placeholders = sessionIds.map(() => '?').join(',');
+        const sql = `SELECT * FROM injections
+                 WHERE session_id IN (${placeholders})
+                 ORDER BY timestamp ASC`;
+        const rows = this.db.prepare(sql).all(...sessionIds);
+        return rows.map(r => ({
+            id: r.id,
+            event_id: r.event_id || undefined,
+            session_id: r.session_id,
+            timestamp: r.timestamp,
+            source_handler: r.source_handler,
+            injection_type: r.injection_type,
+            content: r.content,
+            metadata_json: r.metadata_json || undefined,
+        }));
     }
     queryInjections(filter = {}) {
         const conditions = [];
@@ -45,6 +170,7 @@ export class InjectionOperations {
             source_handler: r.source_handler,
             injection_type: r.injection_type,
             content: r.content,
+            metadata_json: r.metadata_json || undefined,
         }));
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"injections.js","sourceRoot":"","sources":["../../../src/core/storage/injections.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAYzC,MAAM,OAAO,mBAAmB;IACV;IAApB,YAAoB,EAAqB;QAArB,OAAE,GAAF,EAAE,CAAmB;IAAG,CAAC;IAE7C,cAAc,CAAC,SAAoB;QACjC,MAAM,EAAE,GAAG,SAAS,CAAC,EAAE,IAAI,UAAU,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;;KAG5B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CACN,EAAE,EACF,SAAS,CAAC,QAAQ,IAAI,IAAI,EAC1B,SAAS,CAAC,UAAU,EACpB,SAAS,CAAC,SAAS,EACnB,SAAS,CAAC,cAAc,EACxB,SAAS,CAAC,cAAc,EACxB,SAAS,CAAC,OAAO,CAClB,CAAC;IACJ,CAAC;IAED,eAAe,CAAC,SAKZ,EAAE;QACJ,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,MAAM,MAAM,GAAc,EAAE,CAAC;QAE7B,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACtB,UAAU,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACjC,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAChC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QACD,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YAC1B,UAAU,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;YACtC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QACrC,CAAC;QAED,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,GAAG,CAAC;QAClC,MAAM,GAAG,GAAG,4BAA4B,KAAK,kCAAkC,CAAC;QAEhF,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAmC,CAAC;QACnF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACpB,EAAE,EAAE,CAAC,CAAC,EAAY;YAClB,QAAQ,EAAG,CAAC,CAAC,QAAmB,IAAI,SAAS;YAC7C,UAAU,EAAE,CAAC,CAAC,UAAoB;YAClC,SAAS,EAAE,CAAC,CAAC,SAAmB;YAChC,cAAc,EAAE,CAAC,CAAC,cAAwB;YAC1C,cAAc,EAAE,CAAC,CAAC,cAA6C;YAC/D,OAAO,EAAE,CAAC,CAAC,OAAiB;SAC7B,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}
+{"version":3,"file":"injections.js","sourceRoot":"","sources":["../../../src/core/storage/injections.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,332 @@
+/**
+ * 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;
+    /**
+     * Attribution columns (decision d24cd3a2 Task B) — mirror skill_invocations.
+     * All nullable; legacy / daemon-auto rows leave them NULL.
+     *   reason   — verbatim caller-supplied reason (e.g. "coder/executing-plans"),
+     *              so `reason LIKE 'coder/%'` follow-through SQL works.
+     *   source   — 'cli' (deliberate agent/operator pull) | 'daemon-probe'
+     *              (automatic per-prompt kb-injector probe) | null (legacy).
+     *   agent_id — session / agent id resolved by the CLI (sentinel fallback).
+     *   workflow/phase — parseWorkflowMeta(reason) output for aggregation.
+     */
+    reason?: string | null;
+    source?: string | null;
+    agent_id?: string | null;
+    workflow?: string | null;
+    phase?: string | null;
+}
+export interface KbQueryLogRow {
+    id: number;
+    ts: number;
+    project_path: string;
+    query: string;
+    result_count: number;
+    ai_call_count: number | null;
+    ai_input_tokens: number | null;
+    ai_output_tokens: number | null;
+    duration_ms: number;
+    reason: string | null;
+    source: string | null;
+    agent_id: string | null;
+    workflow: string | null;
+    phase: string | null;
+    /** Post-use usefulness self-assessment (decision 096309e4 ①), nullable. */
+    usefulness: string | null;
+    usefulness_note: string | null;
+}
+/** Per-workflow KB usefulness aggregation (decision 096309e4 ①). */
+export interface KbUsefulnessRow {
+    /** Grouping key — the pulling workflow (coder/verify/...), 'unknown' if NULL. */
+    workflow: string;
+    total_rated: number;
+    helped: number;
+    partial: number;
+    not_actionable: number;
+    pending: number;
+    /** helped / total_rated (STRICT helped-only); 0 when nothing rated. */
+    actionable_rate: 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;
+    /**
+     * Read raw kb_query_log rows (decision d24cd3a2 Task B) — used by attribution
+     * analytics + tests to prove a deliberate `cf knowledge query` pull recorded
+     * its reason/source. Filterable by project_path; newest first.
+     */
+    queryKbQueryLog(filter?: {
+        project_path?: string;
+        source?: string;
+        limit?: number;
+    }): KbQueryLogRow[];
+    /**
+     * Stamp `usefulness` + `usefulness_note` onto the SINGLE most-recent un-rated
+     * kb_query_log row matching `project_path` (+ optional `source`/`reason` filters
+     * and `agent_id`). Deterministic target rule: `ORDER BY ts DESC, id DESC LIMIT 1`
+     * inside a subquery so exactly one row is updated. Idempotent: only `usefulness
+     * IS NULL` rows are eligible, so re-running stamps the next-older un-rated pull
+     * (or affects 0 once all are rated). Returns rows-affected (0 = soft no-op,
+     * caller never treats it as an error).
+     *
+     * Default scoping is to deliberate agent pulls (`source='cli'`) so a feedback
+     * call never accidentally stamps a daemon-probe row; pass source=undefined to
+     * widen.
+     */
+    writeKbUsefulness(args: {
+        project_path: string;
+        usefulness: string;
+        note?: string | null;
+        source?: string | null;
+        agent_id?: string | null;
+        reasonPrefix?: string | null;
+        sinceMs?: number;
+    }): number;
+    /**
+     * Per-workflow KB usefulness aggregation — answers "is the KB content agents
+     * pull actually helping, and for which roles?". GROUP BY workflow over rows
+     * that HAVE a usefulness rating. `actionable_rate = helped / total_rated`
+     * (STRICT helped-only). Un-rated pulls counted as `pending` (NOT in rate
+     * denominator). Sorted worst actionable_rate FIRST (least-useful surface for
+     * refinement); ties broken by higher total_rated. ts is INTEGER ms.
+     */
+    aggregateKbUsefulness(filter?: {
+        project_path?: string;
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): KbUsefulnessRow[];
+    /**
+     * Per-agent KB usefulness aggregation — Agent 体检 input (decision 234f1ad4,
+     * Phase 1 / P1-1). Mirrors aggregateKbUsefulness but the grouping key is the
+     * `reason` workflow PREFIX (`substr(reason,1,instr(reason,'/')-1)`), i.e. the
+     * proxy agent key (coder/verify/...), since `kb_query_log.agent_id` is not a
+     * reliable per-agent signal for CLI pulls (subagents have zero MCP). Only
+     * source='agent-pull' rows with a parseable `<x>/<y>` reason are attributed;
+     * reasons without `/` go to `<unknown>`. `ts` is INTEGER ms.
+     * `actionable_rate = helped / total_rated` (STRICT helped-only).
+     */
+    aggregateKbUsefulnessByAgent(filter?: {
+        project_path?: string;
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): Array<{
+        agent: string;
+        total_rated: number;
+        helped: number;
+        partial: number;
+        not_actionable: number;
+        pending: number;
+        pulls: number;
+        actionable_rate: number;
+    }>;
+    /**
+     * Aggregate deliberate agent/operator KB pulls (decision a33a9b3d) — the
+     * consumer for the /context「agent 主动 pull」block. Reads kb_query_log rows
+     * with source='cli' (verbatim `cf knowledge query --reason` pulls), in a
+     * trailing time window. Returns three slices so the UI can show "who pulled,
+     * what, and how the three telemetry paths split":
+     *   - byWorkflow: GROUP BY workflow (role: coder/decision/verify/...), count desc.
+     *   - recent:     newest N raw cli rows (query is a plaintext topic column —
+     *                 NOT gzip — safe to surface verbatim).
+     *   - sourceDistribution: cli vs daemon-probe vs legacy(NULL) counts, so the
+     *                 user understands the per-page cited table reads a different
+     *                 (injection/push) path than this pull view.
+     *
+     * ts is INTEGER ms (kb_query_log landmine); the window bound is computed in ms.
+     * project_path optional — omit to aggregate across all known projects.
+     *
+     * Test-probe exclusion (decision 2d6d59b0): `cf knowledge query foo` smoke /
+     * manual probes land as source='cli' with the sentinel agent_id
+     * 'cli-no-session' (no real session) — they are NOT deliberate agent pulls and
+     * were inflating the cli bucket 85% (192→29 real over 7d). Every aggregate
+     * below excludes that sentinel with the NULL-safe predicate
+     * `(agent_id IS NULL OR agent_id != 'cli-no-session')`. NULL-safe matters for
+     * the source_distribution query: legacy(NULL source) user-prompt rows carry a
+     * NULL agent_id, and a bare `agent_id != …` would silently drop them (SQL NULL
+     * comparison is not-true) — wiping the legacy bucket. Real agent pulls carry a
+     * UUID agent_id + reason and are never touched.
+     */
+    queryAgentKbPulls(filter?: {
+        project_path?: string;
+        days?: number;
+        recentLimit?: number;
+    }): {
+        window_days: number;
+        by_workflow: Array<{
+            workflow: string;
+            count: number;
+        }>;
+        recent: Array<{
+            ts: number;
+            query: string;
+            reason: string | null;
+            workflow: string | null;
+            phase: string | null;
+            result_count: number;
+            agent_id: string | null;
+        }>;
+        source_distribution: Array<{
+            source: string;
+            count: number;
+        }>;
+        total_cli_pulls: number;
+    };
+    /**
+     * Count GENUINE agent KB pulls in a trailing window (decision 64d37b1d) —
+     * the「KB 调用」workplace KPI that replaces the passive「KB 注入」number.
+     *
+     * 口径 (reconciled against the live DB =46 for `reason LIKE '%kb-precedent%'`):
+     *   - counts rows whose `reason LIKE '%kb-precedent%'` — the
+     *     coder/verify/safetynet/decision pull-reason convention that marks a
+     *     deliberate `cf knowledge query|fetch --reason "<wf>/kb-precedent"` pull,
+     *   - EXCLUDES the foo-probe sentinel `agent_id='cli-no-session'`
+     *     (decision 2d6d59b0), NULL-safe so real pulls with a NULL agent_id are
+     *     kept,
+     *   - filters by `kb_query_log.project_path` directly (this table HAS its own
+     *     project_path column — no sessions JOIN, unlike countKbInjections),
+     *   - window is INTEGER ms (kb_query_log.ts landmine): cutoff computed in ms.
+     *
+     * Omitting projectPath → aggregate across all projects (__all__ on the UI).
+     */
+    countAgentKbPulls(filter?: {
+        windowDays?: number;
+        projectPath?: string;
+    }): number;
+    /**
+     * Per-page KB *cited* counts for the /context「📚 KB 命中」table's
+     * "cited (7d)" column (decision aba3cae7).
+     *
+     * BUG it fixes: the per-page cited map used to be derived from
+     * /api/insights/agent-board, whose query LIMITs to the 40 most-recent
+     * user-tasks for kanban pagination. KB-bearing tasks ranked outside that 40
+     * were silently dropped → every page showed cited=0. This reads the raw
+     * INJECTION (push) path directly, bypassing that LIMIT entirely.
+     *
+     * Source of truth: `injections WHERE source_handler =
+     * 'UserPromptSubmitHandler:kb'`, joined to `sessions` for project scope.
+     *
+     * Landmines /口径 (intentional, do NOT "normalise"):
+     *   - injections.timestamp is **ISO TEXT** (schema: `timestamp TEXT NOT NULL`),
+     *     NOT integer-ms. The window bound is a TEXT comparison via
+     *     datetime('now', '-N days'); do NOT compute an integer-ms cutoff here
+     *     (that口径 belongs to kb_query_log / skill_invocations, different table).
+     *   - project scope is a JOIN on sessions.project_path (injections has no
+     *     project_path column).
+     *   - NO task_kind filter: we aggregate injections directly, which naturally
+     *     includes both user prompts and agent-callback prompts. Semantically
+     *     "how many times was this page pulled by the AI" SHOULD include both.
+     *   - NO adopted_at gate: this is a raw injection-event count, NOT an
+     *     adoption-rate. adopted_at is a separate telemetry (decision 148f7a0a).
+     *   - metadata_json is a plaintext JSON array `[{name,score,refs}, ...]`
+     *     (NOT gzip) — parsed in JS and each `[].name` accumulated.
+     *
+     * @param filter.project_path — scope to one project (omit = all projects).
+     * @param filter.days — trailing window in days (default 7).
+     * @returns map of page_name → cited_count (raw injection-event count).
+     */
+    queryKbCitedPages(filter?: {
+        project_path?: string;
+        days?: number;
+    }): Record<string, number>;
+    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":"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"}