opencode-rag-plugin 1.18.0 → 1.18.1

package/dist/opencode/system-guidance.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Single source of truth for the mandatory OpenCodeRAG tool-usage guidance
+ * that is injected into both the runtime system prompt (via plugin.ts) and the AGENTS.md
+ * directive (via init-helpers.ts).
+ */
+/** Sentinel marker that opens the managed section. */
+export const BEGIN_MARKER = "<!-- BEGIN opencode-rag -->";
+/** Sentinel marker that closes the managed section. */
+export const END_MARKER = "<!-- END opencode-rag -->";
+/**
+ * The always-on mandatory guidance lines — tool list, decision tree,
+ * proactive triggers, and anti-patterns. Used verbatim by the runtime
+ * system prompt injector.
+ */
+export const MANDATORY_GUIDANCE_LINES = [
+    "MANDATORY: OpenCodeRAG tools MUST be used before any code task:",
+    "- `search_semantic(query)`: retrieve relevant code chunks. Call BEFORE planning, editing, or answering. Accepts `pathHints` and `languageHints`.",
+    "- `get_file_skeleton(filePath)`: structural overview of a file. Call BEFORE reading any file.",
+    "- `find_usages(symbolName)`: find all references. Call BEFORE editing any function, class, or variable.",
+    "- `describe_image(filePath)`: describe an image file using a vision model. Call when user refers to a screenshot, diagram, or image.",
+    "- `recall_quirks(query)`: query experiential quirk memory (gotchas, preferences, decisions). Call when you hit an error or need to recall known pitfalls.",
+    "- `add_quirk(content)`: store a new experiential memory. Call when you discover a non-obvious fact, gotcha, or coding convention.",
+    "",
+    "Decision tree — ALWAYS follow this order:",
+    "1. User mentions code behavior/architecture → `search_semantic(query)`",
+    "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
+    "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
+    "4. User asks a code question → `search_semantic` to gather context before answering",
+    "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
+    "6. You encounter an error or need to recall a known pitfall → `recall_quirks(query)`",
+    "7. You discover a non-obvious fact or workaround → `add_quirk(content)` to persist it for future sessions",
+    "",
+    "Proactive triggers — you MUST call these tools when:",
+    "- User asks about code behavior, architecture, or implementation details",
+    "- User asks to edit, refactor, or fix code — call `find_usages` first",
+    "- User references files or functions you haven't read yet",
+    "- User says \"find\", \"search\", \"look up\", \"where is\", \"how does\"",
+    "- User refers to an image, screenshot, diagram, or visual asset",
+    "- Before answering ANY code-related question, retrieve context first",
+    "- Before reading ANY file, call `get_file_skeleton` to orient first",
+    "",
+    "Anti-patterns — NEVER do these:",
+    "- Reading full files without calling `get_file_skeleton` first (wastes tokens)",
+    "- Editing a function without calling `find_usages` first (breaks call sites)",
+    "- Answering code questions without calling `search_semantic` first (you guess at behavior)",
+    "- Using `grep`/`glob` when `search_semantic` would find the answer faster",
+    "- Treating image files as text — use `describe_image` instead of reading raw bytes",
+    "- Using `npx opencode-rag quirk` shell commands instead of the built-in `add_quirk` / `recall_quirks` tools (the tools are faster, already loaded in-process, and go through the trust monitor)",
+];
+/**
+ * The conditional quirk-capture enforcement lines. Only included when
+ * `memory.promptEnforcement` is true.
+ */
+export const QUIRK_ENFORCEMENT_LINES = [
+    "",
+    "MANDATORY quirk capture rules — you MUST call `add_quirk` when:",
+    "- A build, test, or type-check command fails and you resolve it",
+    "- You discover an undocumented library constraint, peer dep, or workaround",
+    "- You learn an environment-specific requirement (OS, tool version, etc.)",
+    "- You make a design decision that future sessions should remember",
+    "- You resolve a gotcha that cost more than one attempt",
+    "",
+    "Anti-pattern — NEVER finish a coding session without adding quirks for resolved errors.",
+];
+/**
+ * Build the flat guidance lines array for the runtime system-prompt injector.
+ * Returns a new array each call.
+ */
+export function buildSystemGuidanceLines(opts) {
+    const lines = [...MANDATORY_GUIDANCE_LINES];
+    if (opts.promptEnforcement) {
+        lines.push(...QUIRK_ENFORCEMENT_LINES);
+    }
+    return lines;
+}
+/**
+ * Build the markdown-formatted AGENTS.md directive section, wrapped in sentinel
+ * markers so `mergeAgentsMdContent` can replace it in place on re-runs.
+ */
+export function buildAgentsMdDirective(opts) {
+    const lines = [
+        BEGIN_MARKER,
+        "## Code Navigation",
+        "",
+        "ALWAYS use OpenCodeRAG tools before reading or editing:",
+        "- **Search first** — `search_semantic(query)` instead of grep/glob",
+        "- **Skeleton before read** — `get_file_skeleton(filePath)` then read specific lines",
+        "- **Usages before edit** — `find_usages(symbolName)` before modifying any symbol",
+        "- **Images via describe** — `describe_image(filePath)` — never read raw bytes",
+        "- **Recall quirks** — `recall_quirks(query)` when you hit a known pitfall",
+        "- **Add quirks** — `add_quirk(content)` when you discover a non-obvious fact",
+        "",
+        "If no results, run `opencode-rag index`.",
+        "",
+        "### Decision tree — ALWAYS follow this order",
+        "1. User mentions code behavior/architecture → `search_semantic(query)`",
+        "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
+        "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
+        "4. User asks a code question → `search_semantic` to gather context before answering",
+        "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
+        "6. You encounter an error or need to recall a known pitfall → `recall_quirks(query)`",
+        "7. You discover a non-obvious fact or workaround → `add_quirk(content)` to persist it for future sessions",
+        "",
+        "### Proactive triggers — you MUST call these tools when",
+        "- User asks about code behavior, architecture, or implementation details",
+        "- User asks to edit, refactor, or fix code — call `find_usages` first",
+        "- User references files or functions you haven't read yet",
+        "- User says \"find\", \"search\", \"look up\", \"where is\", \"how does\"",
+        "- User refers to an image, screenshot, diagram, or visual asset",
+        "- Before answering ANY code-related question, retrieve context first",
+        "- Before reading ANY file, call `get_file_skeleton` to orient first",
+        "",
+        "### Anti-patterns — NEVER do these",
+        "- Reading full files without calling `get_file_skeleton` first (wastes tokens)",
+        "- Editing a function without calling `find_usages` first (breaks call sites)",
+        "- Answering code questions without calling `search_semantic` first (you guess at behavior)",
+        "- Using `grep`/`glob` when `search_semantic` would find the answer faster",
+        "- Treating image files as text — use `describe_image` instead of reading raw bytes",
+        "- Using `npx opencode-rag quirk` shell commands instead of the built-in `add_quirk` / `recall_quirks` tools (the tools are faster, already loaded in-process, and go through the trust monitor)",
+    ];
+    if (opts.promptEnforcement) {
+        lines.push("", "### MANDATORY quirk capture rules — you MUST call `add_quirk` when", "- A build, test, or type-check command fails and you resolve it", "- You discover an undocumented library constraint, peer dep, or workaround", "- You learn an environment-specific requirement (OS, tool version, etc.)", "- You make a design decision that future sessions should remember", "- You resolve a gotcha that cost more than one attempt", "- NEVER finish a coding session without adding quirks for resolved errors.");
+    }
+    lines.push(END_MARKER);
+    return lines.join("\n");
+}
+//# sourceMappingURL=system-guidance.js.map

package/dist/plugin.js

@@ -26,6 +26,8 @@ import { checkForUpdate, getCurrentVersion, installLatestUpdate } from "./core/v
 import { loadAutoUpdateState, saveAutoUpdateState, shouldAttemptInstall } from "./core/auto-update-state.js";
 import { destroyAllPooledConnections } from "./embedder/http.js";
 import { listQuirks, lintQuirks, recallQuirks } from "./quirks/quirk-store.js";
+import { autoCaptureQuirks } from "./quirks/auto-capture.js";
+import { buildSystemGuidanceLines } from "./opencode/system-guidance.js";
 import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -434,6 +436,10 @@ export function createRagHooks(options) {
     // Track the current assistant message text per session for 2-message search queries.
     const sessionAssistantMessageId = new Map();
     const sessionAssistantText = new Map();
+    // Auto-capture maps: previous user request per session, tool results, and full transcript
+    const sessionPrevUserReq = new Map();
+    const sessionToolResults = new Map();
+    const sessionTranscript = new Map();
     // Evaluation session logger — captures OpenCode events for analysis
     const sessionLogger = createSessionLogger(options.storePath);
     appendDebugLog(options.logFilePath, {
@@ -686,8 +692,40 @@ export function createRagHooks(options) {
             catch {
                 // Non-critical — must never throw
             }
+            // Session-end extraction: when we see a non-message lifecycle event,
+            // attempt to extract quirks from the full transcript.
+            try {
+                if (!event.type.startsWith("message.")) {
+                    const sessionID = event.sessionID;
+                    if (sessionID) {
+                        const transcript = sessionTranscript.get(sessionID);
+                        if (transcript && transcript.length > 0) {
+                            const effCfg = getEffectiveCfg();
+                            const memCfg = effCfg.memory;
+                            if (memCfg?.sessionEndExtraction && options.descriptionProvider) {
+                                const qDeps = { embedder, store, keywordIndex: keywordIndex, cfg: effCfg, storePath: options.storePath };
+                                void autoCaptureQuirks(qDeps, options.descriptionProvider, transcript, effCfg, { captureAll: true }).catch(() => { });
+                            }
+                            boundedSet(sessionTranscript, sessionID, [], MAX_SESSION_MAP_SIZE);
+                        }
+                    }
+                }
+            }
+            catch {
+                // Non-critical — must never throw
+            }
         },
         tool: tools,
+        async "tool.execute.after"(input, output) {
+            try {
+                const results = sessionToolResults.get(input.sessionID) ?? [];
+                results.push({ tool: input.tool, output: output.output ?? "" });
+                boundedSet(sessionToolResults, input.sessionID, results, MAX_SESSION_MAP_SIZE);
+            }
+            catch {
+                // Non-critical — must never throw
+            }
+        },
         async "experimental.chat.system.transform"(_input, output) {
             appendDebugLog(options.logFilePath, {
                 scope: "experimental.chat.system.transform",
@@ -695,40 +733,7 @@ export function createRagHooks(options) {
             });
             const cfg = getEffectiveCfg();
             if (cfg.openCode.injectSystemPrompt !== false) {
-                const guidance = [
-                    "MANDATORY: OpenCodeRAG tools MUST be used before any code task:",
-                    "- `search_semantic(query)`: retrieve relevant code chunks. Call BEFORE planning, editing, or answering. Accepts `pathHints` and `languageHints`.",
-                    "- `get_file_skeleton(filePath)`: structural overview of a file. Call BEFORE reading any file.",
-                    "- `find_usages(symbolName)`: find all references. Call BEFORE editing any function, class, or variable.",
-                    "- `describe_image(filePath)`: describe an image file using a vision model. Call when user refers to a screenshot, diagram, or image.",
-                    "- `recall_quirks(query)`: query experiential quirk memory (gotchas, preferences, decisions). Call when you hit an error or need to recall known pitfalls.",
-                    "- `add_quirk(content)`: store a new experiential memory. Call when you discover a non-obvious fact, gotcha, or coding convention.",
-                    "",
-                    "Decision tree — ALWAYS follow this order:",
-                    "1. User mentions code behavior/architecture → `search_semantic(query)`",
-                    "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
-                    "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
-                    "4. User asks a code question → `search_semantic` to gather context before answering",
-                    "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
-                    "6. You encounter an error or need to recall a known pitfall → `recall_quirks(query)`",
-                    "7. You discover a non-obvious fact or workaround → `add_quirk(content)` to persist it for future sessions",
-                    "",
-                    "Proactive triggers — you MUST call these tools when:",
-                    "- User asks about code behavior, architecture, or implementation details",
-                    "- User asks to edit, refactor, or fix code — call `find_usages` first",
-                    "- User references files or functions you haven't read yet",
-                    "- User says \"find\", \"search\", \"look up\", \"where is\", \"how does\"",
-                    "- User refers to an image, screenshot, diagram, or visual asset",
-                    "- Before answering ANY code-related question, retrieve context first",
-                    "- Before reading ANY file, call `get_file_skeleton` to orient first",
-                    "",
-                    "Anti-patterns — NEVER do these:",
-                    "- Reading full files without calling `get_file_skeleton` first (wastes tokens)",
-                    "- Editing a function without calling `find_usages` first (breaks call sites)",
-                    "- Answering code questions without calling `search_semantic` first (you guess at behavior)",
-                    "- Using `grep`/`glob` when `search_semantic` would find the answer faster",
-                    "- Treating image files as text — use `describe_image` instead of reading raw bytes",
-                ];
+                const guidance = buildSystemGuidanceLines({ promptEnforcement: !!cfg.memory?.promptEnforcement });
                 output.system.unshift(guidance.join("\n"));
             }
             // Inject a one-time update prompt so the agent asks the user to install.
@@ -778,6 +783,30 @@ export function createRagHooks(options) {
                 });
                 if (text.length === 0)
                     return;
+                // Passive capture: process the completed exchange before overwriting session state
+                const prevUserReq = sessionPrevUserReq.get(input.sessionID) ?? "";
+                if (prevUserReq) {
+                    const effCfg = getEffectiveCfg();
+                    const memCfg = effCfg.memory;
+                    if (options.descriptionProvider) {
+                        const assistantText = sessionAssistantText.get(input.sessionID) ?? "";
+                        const toolResults = sessionToolResults.get(input.sessionID) ?? [];
+                        if (assistantText) {
+                            const qDeps = { embedder, store, keywordIndex: keywordIndex, cfg: effCfg, storePath: options.storePath };
+                            const exchange = { userReq: prevUserReq, assistantText, toolResults };
+                            if (memCfg?.passiveCapture) {
+                                void autoCaptureQuirks(qDeps, options.descriptionProvider, [exchange], effCfg).catch(() => { });
+                            }
+                            if (memCfg?.sessionEndExtraction) {
+                                const t = sessionTranscript.get(input.sessionID) ?? [];
+                                t.push(exchange);
+                                boundedSet(sessionTranscript, input.sessionID, t, MAX_SESSION_MAP_SIZE);
+                            }
+                        }
+                    }
+                }
+                sessionPrevUserReq.set(input.sessionID, text);
+                sessionToolResults.set(input.sessionID, []);
                 boundedSet(sessionLastMessage, input.sessionID, text, MAX_SESSION_MAP_SIZE);
                 // Handle /doc slash command
                 if (text.startsWith("/doc")) {
@@ -969,8 +998,18 @@ export function createRagHooks(options) {
                                 const tags = q.tags.length > 0 ? ` _(${q.tags.join(", ")})_` : "";
                                 lines.push(`- ${badge}${q.content.slice(0, 100)}${tags}  `);
                             }
-                            lines.push("", "Commands:", "- `/quirk` — show this status", "- `/quirk lint` — health-check quirks", "- `/quirk add <text>` — instructions to use the add_quirk tool");
                         }
+                        const memCfg = getEffectiveCfg().memory;
+                        const flags = [
+                            memCfg?.autoInject ? "auto-inject" : "",
+                            memCfg?.passiveCapture ? "passive-capture" : "",
+                            memCfg?.promptEnforcement ? "prompt-enforce" : "",
+                            memCfg?.sessionEndExtraction ? "session-end" : "",
+                        ].filter(Boolean);
+                        if (flags.length > 0) {
+                            lines.push(`Flags: ${flags.join(", ")}`);
+                        }
+                        lines.push("", "Commands:", "- `/quirk` — show this status", "- `/quirk lint` — health-check quirks", "- `/quirk add <text>` — instructions to use the add_quirk tool");
                     }
                     const quirkMsg = lines.join("\n");
                     const parts = output?.parts ?? output?.message?.parts;

package/dist/quirks/auto-capture.d.ts

@@ -0,0 +1,14 @@
+import type { DescriptionProvider } from "../core/interfaces.js";
+import type { RagConfig } from "../core/config.js";
+import { type QuirkStoreDeps } from "./quirk-store.js";
+export interface CaptureExchange {
+    userReq: string;
+    assistantText: string;
+    toolResults: {
+        tool: string;
+        output: string;
+    }[];
+}
+export declare function autoCaptureQuirks(deps: QuirkStoreDeps, descriptionProvider: DescriptionProvider, exchanges: CaptureExchange[], cfg: RagConfig, opts?: {
+    captureAll?: boolean;
+}): Promise<void>;

package/dist/quirks/auto-capture.js

@@ -0,0 +1,112 @@
+import { addQuirk, recallQuirks, lexicalSimilarity } from "./quirk-store.js";
+import { isQuirkAllowed } from "./monitor.js";
+import { MEMORY_CAPTURE_SYSTEM_PROMPT } from "./prompts.js";
+const ERROR_SIGNAL_RE = /(error|failure|fail|failed|err(?:or)?\s*:|stack\s*trace|exit\s+code\s*[1-9]|npm\s+ERR|build\s+failed|test\s+fail|cannot\s+find\s+module|command\s+failed|unresolved|conflict|peer.dep|not\s+found|enoent|eaccess|econnrefused)/i;
+function detectErrorSignal(text) {
+    return ERROR_SIGNAL_RE.test(text);
+}
+function buildExchangeText(exchanges) {
+    const lines = [];
+    for (const ex of exchanges) {
+        lines.push("=== User ===");
+        lines.push(ex.userReq);
+        if (ex.toolResults.length > 0) {
+            for (const tr of ex.toolResults) {
+                lines.push(`--- Tool: ${tr.tool} ---`);
+                lines.push(tr.output.slice(0, 500));
+            }
+        }
+        lines.push("=== Assistant ===");
+        lines.push(ex.assistantText);
+    }
+    return lines.join("\n");
+}
+function parseExtractionOutput(text) {
+    const results = [];
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed === "NOTHING")
+            continue;
+        const pipeIdx = trimmed.indexOf("|");
+        if (pipeIdx <= 0)
+            continue;
+        const quirkType = trimmed.slice(0, pipeIdx).trim();
+        const content = trimmed.slice(pipeIdx + 1).trim();
+        if (!quirkType || !content || content.length > 200)
+            continue;
+        results.push({ quirkType, content });
+    }
+    return results;
+}
+async function extractQuirksFromText(provider, exchangeText) {
+    const raw = await provider.generateText(MEMORY_CAPTURE_SYSTEM_PROMPT, exchangeText);
+    return parseExtractionOutput(raw);
+}
+async function dedupCandidates(deps, exchangeHead, candidates, threshold) {
+    const existing = await recallQuirks(deps, exchangeHead, { topK: 5 });
+    if (existing.length === 0)
+        return candidates;
+    const existingContent = existing.map((r) => r.chunk.content);
+    return candidates.filter((c) => {
+        for (const ec of existingContent) {
+            if (lexicalSimilarity(c.content, ec) >= threshold) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+export async function autoCaptureQuirks(deps, descriptionProvider, exchanges, cfg, opts) {
+    const memoryCfg = cfg.memory;
+    if (!memoryCfg)
+        return;
+    const maxPerTurn = memoryCfg.autoCaptureMaxPerTurn ?? 2;
+    const dedupThreshold = memoryCfg.autoCaptureDedupThreshold ?? 0.85;
+    const captureAll = opts?.captureAll ?? false;
+    if (!captureAll) {
+        const combined = exchanges.map((e) => e.userReq + "\n" + e.assistantText + "\n" + e.toolResults.map((t) => t.output).join("\n")).join("\n");
+        if (!detectErrorSignal(combined))
+            return;
+    }
+    const exchangeText = buildExchangeText(exchanges);
+    if (!exchangeText.trim())
+        return;
+    let candidates;
+    try {
+        candidates = await extractQuirksFromText(descriptionProvider, exchangeText);
+    }
+    catch {
+        return;
+    }
+    if (candidates.length === 0)
+        return;
+    const exchangeHead = exchanges.map((e) => e.userReq).join(" ");
+    let deduped;
+    try {
+        deduped = await dedupCandidates(deps, exchangeHead, candidates, dedupThreshold);
+    }
+    catch {
+        deduped = candidates;
+    }
+    let added = 0;
+    for (const c of deduped) {
+        if (added >= maxPerTurn)
+            break;
+        const allowed = isQuirkAllowed(c.content);
+        if (!allowed.ok)
+            continue;
+        try {
+            await addQuirk(deps, {
+                content: c.content,
+                quirkType: c.quirkType,
+                tags: ["auto-captured"],
+                confidence: 0.7,
+            });
+            added++;
+        }
+        catch {
+            // skip individual failures
+        }
+    }
+}
+//# sourceMappingURL=auto-capture.js.map

package/dist/quirks/prompts.d.ts

@@ -0,0 +1 @@
+export declare const MEMORY_CAPTURE_SYSTEM_PROMPT: string;

package/dist/quirks/prompts.js

@@ -0,0 +1,13 @@
+export const MEMORY_CAPTURE_SYSTEM_PROMPT = "You are a quirk-extraction assistant. Given a transcript excerpt of an AI agent resolving a " +
+    "coding problem, extract concise experiential quirks that are worth remembering.\n\n" +
+    "Rules:\n" +
+    "- Output exactly one line per quirk in the format: TYPE|content\n" +
+    "- TYPE must be one of: gotcha, preference, decision, environment-constraint\n" +
+    "- content is a single short sentence (max 200 chars)\n" +
+    "- If no quirks are present, output exactly: NOTHING\n" +
+    "- Do not include explanations, numbering, or markdown\n\n" +
+    "Examples:\n" +
+    "gotcha|npm install needs --legacy-peer-deps due to LanceDB peer dep conflicts\n" +
+    "preference|Use tsx over ts-node for running TypeScript scripts\n" +
+    "NOTHING";
+//# sourceMappingURL=prompts.js.map

package/dist/quirks/quirk-store.d.ts

@@ -23,3 +23,5 @@ export declare function recallQuirks(deps: QuirkStoreDeps, query: string, option
 }): Promise<SearchResult[]>;
 /** Lint quirks for low confidence, staleness, duplicates, and orphan source refs. */
 export declare function lintQuirks(deps: QuirkStoreDeps): Promise<string[]>;
+/** Simple Jaccard-based lexical similarity (word overlap). */
+export declare function lexicalSimilarity(a: string, b: string): number;

package/dist/quirks/quirk-store.js

@@ -207,7 +207,7 @@ export async function lintQuirks(deps) {
     return issues;
 }
 /** Simple Jaccard-based lexical similarity (word overlap). */
-function lexicalSimilarity(a, b) {
+export function lexicalSimilarity(a, b) {
     const wordsA = new Set(a.toLowerCase().split(/\W+/).filter(Boolean));
     const wordsB = new Set(b.toLowerCase().split(/\W+/).filter(Boolean));
     const intersection = new Set([...wordsA].filter((w) => wordsB.has(w)));

package/dist/vectorstore/lancedb.d.ts

@@ -100,9 +100,18 @@ export declare class LanceDbStore implements VectorStore {
     private searchInternal;
     /**
      * Return the total number of chunks stored in the table.
-     * @returns The chunk count, or 0 if the table does not exist.
+     * Guarded by a 30s timeout — returns 0 if the store is unresponsive
+     * (e.g. corrupted version-manifest accumulation) so the pipeline can
+     * proceed with a fresh index instead of hanging forever.
+     * @returns The chunk count, or 0 if the table does not exist or times out.
      */
     count(): Promise<number>;
+    /**
+     * Compact fragments and prune old version manifests to prevent the
+     * version-manifest accumulation that causes countRows() to hang.
+     * Should be called at the end of a successful index pass.
+     */
+    optimize(): Promise<void>;
     /**
      * Return all unique file paths currently stored in the index.
      * @returns An array of normalized file paths.

package/dist/vectorstore/lancedb.js

@@ -513,7 +513,10 @@ export class LanceDbStore {
     }
     /**
      * Return the total number of chunks stored in the table.
-     * @returns The chunk count, or 0 if the table does not exist.
+     * Guarded by a 30s timeout — returns 0 if the store is unresponsive
+     * (e.g. corrupted version-manifest accumulation) so the pipeline can
+     * proceed with a fresh index instead of hanging forever.
+     * @returns The chunk count, or 0 if the table does not exist or times out.
      */
     async count() {
         try {
@@ -522,12 +525,35 @@ export class LanceDbStore {
             if (!tableNames.includes(TABLE_NAME))
                 return 0;
             const table = await this.getTable();
-            return await table.countRows();
+            const COUNT_TIMEOUT_MS = 30_000;
+            const result = await Promise.race([
+                table.countRows(),
+                new Promise((resolve) => setTimeout(() => resolve(null), COUNT_TIMEOUT_MS)),
+            ]);
+            if (result === null) {
+                console.warn(`[lancedb] count() timed out after ${COUNT_TIMEOUT_MS / 1000}s — treating store as empty.`);
+                return 0;
+            }
+            return result;
         }
         catch {
             return 0;
         }
     }
+    /**
+     * Compact fragments and prune old version manifests to prevent the
+     * version-manifest accumulation that causes countRows() to hang.
+     * Should be called at the end of a successful index pass.
+     */
+    async optimize() {
+        try {
+            const table = await this.getTable();
+            await table.optimize({ cleanupOlderThan: new Date(), deleteUnverified: false });
+        }
+        catch {
+            // Optimize is best-effort — must not break indexing.
+        }
+    }
     /**
      * Return all unique file paths currently stored in the index.
      * @returns An array of normalized file paths.

package/dist/vectorstore/memory.d.ts

@@ -21,4 +21,6 @@ export declare class InMemoryVectorStore implements VectorStore {
     getChunksByFilePath(filePath: string): Promise<Chunk[]>;
     /** Release any held resources. No-op for the in-memory store. */
     close(): Promise<void>;
+    /** No-op for the in-memory store. */
+    optimize(): Promise<void>;
 }

package/dist/vectorstore/memory.js

@@ -73,6 +73,9 @@ export class InMemoryVectorStore {
     /** Release any held resources. No-op for the in-memory store. */
     async close() {
     }
+    /** No-op for the in-memory store. */
+    async optimize() {
+    }
 }
 /**
  * Compute the cosine similarity between two equal-length vectors.

package/dist/web/api.d.ts

@@ -4,6 +4,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { LanceDbStore } from "../vectorstore/lancedb.js";
 import { KeywordIndex } from "../retriever/keyword-index.js";
+import type { RagConfig } from "../core/config.js";
 /** Internal shape for a JSON API response: an HTTP status code and a serialisable body. */
 interface ApiResponse {
     status: number;
@@ -23,9 +24,10 @@ interface ApiResponse {
  * @param keywordIndex - The keyword-index instance for text search.
  * @param storePath    - Filesystem path to the store directory (used by eval endpoints).
  * @param cwd          - Optional workspace root for resolving file paths.
+ * @param cfg          - Active RAG configuration (used by quirk endpoints).
  * @returns An async handler that returns `true` when a route matched or `false` otherwise.
  */
-export declare function createApiHandler(store: LanceDbStore, keywordIndex: KeywordIndex, storePath: string, cwd?: string): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+export declare function createApiHandler(store: LanceDbStore, keywordIndex: KeywordIndex, storePath: string, cwd?: string, cfg?: RagConfig): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
 /**
  * Perform token-usage analysis for a single evaluation session.
  *

package/dist/web/api.js

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { extname, resolve as resolvePathModule } from "node:path";
 import { listSessions, getSession, deleteSession, compareSessions, validateSessionID } from "../eval/storage.js";
 import { analyzeTokenUsage, compareTokenAnalyses, projectTokenSavings } from "../eval/token-analysis.js";
+import { listQuirks, lintQuirks, removeQuirk } from "../quirks/quirk-store.js";
 const FILE_MIME_TYPES = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -11,6 +12,13 @@ const FILE_MIME_TYPES = {
     ".bmp": "image/bmp",
     ".svg": "image/svg+xml",
 };
+/** No-op embedder used by quirk endpoints that never need to embed text in the read-only UI context. */
+const stubEmbedder = {
+    name: "stub",
+    embed: async () => {
+        throw new Error("Embedder is not available in the Web UI context");
+    },
+};
 /** Split a raw URL into its pathname and parsed query-string parameters. */
 function parseQuery(url) {
     const [path, queryString] = url.split("?");
@@ -43,13 +51,22 @@ function sendJson(res, response) {
  * @param keywordIndex - The keyword-index instance for text search.
  * @param storePath    - Filesystem path to the store directory (used by eval endpoints).
  * @param cwd          - Optional workspace root for resolving file paths.
+ * @param cfg          - Active RAG configuration (used by quirk endpoints).
  * @returns An async handler that returns `true` when a route matched or `false` otherwise.
  */
-export function createApiHandler(store, keywordIndex, storePath, cwd) {
+export function createApiHandler(store, keywordIndex, storePath, cwd, cfg) {
     return async (req, res) => {
         const url = req.url ?? "/";
         const method = req.method ?? "GET";
         const { path, params } = parseQuery(url);
+        // Quirk store dependencies (embedder is a no-op stub for the read-only UI context).
+        const quirkDeps = {
+            embedder: stubEmbedder,
+            store,
+            keywordIndex,
+            cfg: cfg ?? {},
+            storePath,
+        };
         // CORS preflight
         if (method === "OPTIONS") {
             res.writeHead(204, {
@@ -143,6 +160,22 @@ export function createApiHandler(store, keywordIndex, storePath, cwd) {
                 const body = await readBody(req);
                 response = handleEvalProjectSavings(body);
             }
+            // Quirk memory endpoints
+            else if (path === "/api/quirks" && method === "GET") {
+                response = await handleQuirks(quirkDeps);
+            }
+            else if (path === "/api/quirks/lint" && method === "GET") {
+                response = await handleQuirkLint(quirkDeps);
+            }
+            else if (path.startsWith("/api/quirks/") && method === "DELETE") {
+                const id = path.slice("/api/quirks/".length);
+                if (!id) {
+                    response = { status: 400, body: { error: "Missing quirk ID" } };
+                }
+                else {
+                    response = await handleQuirkDelete(quirkDeps, id);
+                }
+            }
             else {
                 return false;
             }
@@ -181,6 +214,22 @@ async function handleFiles(store) {
     const files = await store.listFiles();
     return { status: 200, body: files };
 }
+// ── Quirk Memory API ─────────────────────────────────────────────────
+/** Respond with all stored quirks, sorted by last-observed time (most recent first). */
+async function handleQuirks(deps) {
+    const quirks = await listQuirks(deps);
+    return { status: 200, body: { quirks } };
+}
+/** Respond with the health-check issues for the quirk store (confidence, staleness, duplicates). */
+async function handleQuirkLint(deps) {
+    const issues = await lintQuirks(deps);
+    return { status: 200, body: { issues } };
+}
+/** Delete a single quirk by its ID from the store, index, and audit log. */
+async function handleQuirkDelete(deps, id) {
+    await removeQuirk(deps, id);
+    return { status: 200, body: { deleted: true, id } };
+}
 /**
  * Respond with a paginated, optionally filtered list of chunks.
  *