opencode-rag-plugin 1.17.3 → 1.18.1

package/dist/plugin.js

@@ -15,7 +15,7 @@ import { appendDebugLog } from "./core/fileLogger.js";
 import { loadRuntimeOverrides, applyRuntimeOverrides } from "./core/runtime-overrides.js";
 import { createBackgroundIndexer } from "./watcher.js";
 import { createRagReadTool } from "./opencode/create-read-tool.js";
-import { createFileSkeletonTool, createFindUsagesTool, createDescribeImageTool, } from "./opencode/tools.js";
+import { createFileSkeletonTool, createFindUsagesTool, createDescribeImageTool, createRecallQuirksTool, createAddQuirkTool, } from "./opencode/tools.js";
 import { resolveApiKey } from "./core/resolve-api-key.js";
 import { consumePendingRagInjection } from "./core/rag-injection-flag.js";
 import { loadDocProgress, markSubdirectoryDocumented } from "./core/doc-progress.js";
@@ -25,6 +25,9 @@ import { countTokens } from "./eval/token-counter.js";
 import { checkForUpdate, getCurrentVersion, installLatestUpdate } from "./core/version-check.js";
 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";
@@ -433,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, {
@@ -593,6 +600,40 @@ export function createRagHooks(options) {
             error: err,
         });
     }
+    try {
+        const recallQuirksTool = createRecallQuirksTool({
+            store,
+            embedder,
+            cfg: effectiveCfg,
+            keywordIndex: keywordIndex,
+            storePath: options.storePath,
+        });
+        tools["recall_quirks"] = recallQuirksTool;
+    }
+    catch (err) {
+        appendDebugLog(options.logFilePath, {
+            scope: "plugin",
+            message: "Failed to register recall_quirks tool",
+            error: err,
+        });
+    }
+    try {
+        const addQuirkTool = createAddQuirkTool({
+            store,
+            embedder,
+            cfg: effectiveCfg,
+            keywordIndex: keywordIndex,
+            storePath: options.storePath,
+        });
+        tools["add_quirk"] = addQuirkTool;
+    }
+    catch (err) {
+        appendDebugLog(options.logFilePath, {
+            scope: "plugin",
+            message: "Failed to register add_quirk tool",
+            error: err,
+        });
+    }
     if (readOverride) {
         const readTool = createRagReadTool({
             worktree: options.worktree,
@@ -651,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",
@@ -660,36 +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.",
-                    "",
-                    "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",
-                    "",
-                    "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.
@@ -739,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")) {
@@ -882,6 +950,77 @@ export function createRagHooks(options) {
                     }
                     return;
                 }
+                // Handle /quirk slash command
+                if (text.startsWith("/quirk")) {
+                    const memoryCfg = getEffectiveCfg().memory;
+                    if (!memoryCfg?.enabled) {
+                        const parts = output?.parts ?? output?.message?.parts;
+                        if (Array.isArray(parts) && parts.length > 0) {
+                            const first = parts[0];
+                            if (typeof first.text === "string") {
+                                parts[0] = { ...first, text: "Quirk memory is not enabled. Set `memory.enabled` to `true` in opencode-rag.json." };
+                            }
+                        }
+                        return;
+                    }
+                    const arg = text.slice(6).trim().toLowerCase();
+                    const lines = [];
+                    if (arg === "lint") {
+                        const deps = { embedder, store, keywordIndex: keywordIndex, cfg: getEffectiveCfg(), storePath: options.storePath };
+                        const issues = await lintQuirks(deps);
+                        lines.push("## Quirk Lint", "");
+                        if (issues.length === 0) {
+                            lines.push("No issues found. All quirks look healthy.");
+                        }
+                        else {
+                            lines.push(`Found ${issues.length} issue(s):\n`);
+                            for (const issue of issues) {
+                                lines.push(`- ${issue}`);
+                            }
+                            lines.push("", "Fix the issues and consider updating or removing the flagged quirks.");
+                        }
+                    }
+                    else if (arg.startsWith("add ")) {
+                        lines.push("## Add Quirk", "", "Use the `add_quirk` tool to store a new experiential memory entry. Example:", "", '`content`: "npm install needs --legacy-peer-deps due to LanceDB peer dep conflicts"', '`quirkType`: "gotcha"', "`tags`: [\"npm\", \"lancedb\", \"installation\"]");
+                    }
+                    else {
+                        // Status / list
+                        const deps = { embedder, store, keywordIndex: keywordIndex, cfg: getEffectiveCfg(), storePath: options.storePath };
+                        const quirks = await listQuirks(deps);
+                        lines.push("## Quirk Memory", "");
+                        if (quirks.length === 0) {
+                            lines.push("No quirks stored yet.");
+                        }
+                        else {
+                            lines.push(`${quirks.length} quirk(s) stored:\n`);
+                            for (const q of quirks) {
+                                const badge = q.quirkType ? `[\`${q.quirkType}\`] ` : "";
+                                const tags = q.tags.length > 0 ? ` _(${q.tags.join(", ")})_` : "";
+                                lines.push(`- ${badge}${q.content.slice(0, 100)}${tags}  `);
+                            }
+                        }
+                        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;
+                    if (Array.isArray(parts) && parts.length > 0) {
+                        const first = parts[0];
+                        if (typeof first.text === "string") {
+                            parts[0] = { ...first, text: quirkMsg };
+                        }
+                    }
+                    return;
+                }
                 // Handle hotkey-triggered RAG injection (Ctrl+Enter / Ctrl+Alt+Enter)
                 const pendingInjection = consumePendingRagInjection(options.storePath);
                 if (pendingInjection) {
@@ -938,6 +1077,40 @@ export function createRagHooks(options) {
                                 });
                             }
                         }
+                        // Auto-inject quirks when memory.autoInject is enabled
+                        const memoryCfg = effectiveCfg.memory;
+                        if (memoryCfg?.autoInject) {
+                            try {
+                                const quirkDeps = { embedder, store, keywordIndex: keywordIndex, cfg: effectiveCfg, storePath: options.storePath };
+                                const quirkResults = await recallQuirks(quirkDeps, searchQuery, { topK: 3 });
+                                if (quirkResults.length > 0) {
+                                    const quirkLines = ["", "---", "⚠ **Quirk memory**", ""];
+                                    for (const qr of quirkResults) {
+                                        const m = qr.chunk.metadata;
+                                        const badge = m.quirkType ? `[\`${m.quirkType}\`] ` : "";
+                                        quirkLines.push(`- ${badge}${qr.chunk.content.slice(0, 200)}`);
+                                    }
+                                    const quirkBlock = quirkLines.join("\n");
+                                    const parts = output?.parts ?? output?.message?.parts;
+                                    if (Array.isArray(parts) && parts.length > 0) {
+                                        const first = parts[0];
+                                        if (typeof first.text === "string") {
+                                            parts[0] = { ...first, text: first.text + "\n\n" + quirkBlock };
+                                        }
+                                        const msgParts = output?.message?.parts;
+                                        if (Array.isArray(msgParts) && msgParts !== parts) {
+                                            const mfirst = msgParts[0];
+                                            if (typeof mfirst.text === "string") {
+                                                msgParts[0] = { ...mfirst, text: mfirst.text + "\n\n" + quirkBlock };
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                            catch {
+                                // Non-critical — must never throw
+                            }
+                        }
                     }
                     appendDebugLog(options.logFilePath, {
                         scope: "chat.message",

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/monitor.d.ts

@@ -0,0 +1,5 @@
+/** Check whether quirk content is allowed within the immutable environment boundary. */
+export declare function isQuirkAllowed(content: string): {
+    ok: boolean;
+    reason?: string;
+};

package/dist/quirks/monitor.js

@@ -0,0 +1,23 @@
+/** Patterns that are never allowed in quirk memory — the immutable trust boundary. */
+const BLOCKED_PATTERNS = [
+    /\bskip\s+(?:\S+\s+)*?tests?\b/i,
+    /\bdisable\s+(lint|typecheck|strict)/i,
+    /\bignore\s+(all\s+)?errors/i,
+    /\brm\s+-rf\b/,
+    /\bforce\s+push\b/,
+    /\bgit\s+push\s+--force\b/,
+    /\bdelete\s+.+\.git/i,
+    /\btouch\s+(?:\.env|withheld)/i,
+    /\bbypass\s+(?:security|review|check)/i,
+];
+/** Check whether quirk content is allowed within the immutable environment boundary. */
+export function isQuirkAllowed(content) {
+    for (const pattern of BLOCKED_PATTERNS) {
+        const match = content.match(pattern);
+        if (match) {
+            return { ok: false, reason: `Content matches blocked pattern: "${match[0]}"` };
+        }
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=monitor.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

@@ -0,0 +1,27 @@
+import type { EmbeddingProvider, VectorStore, KeywordIndex, SearchResult } from "../core/interfaces.js";
+import type { RagConfig } from "../core/config.js";
+import type { Quirk, QuirkInput } from "./types.js";
+/** Dependencies required by all quirk-store operations. */
+export interface QuirkStoreDeps {
+    embedder: EmbeddingProvider;
+    store: VectorStore;
+    keywordIndex: KeywordIndex;
+    cfg: RagConfig;
+    storePath: string;
+}
+/** Add a new quirk to the vector store, keyword index, and audit log. */
+export declare function addQuirk(deps: QuirkStoreDeps, input: QuirkInput): Promise<Quirk>;
+/** Remove a quirk by its ID. */
+export declare function removeQuirk(deps: QuirkStoreDeps, id: string): Promise<void>;
+/** List all quirks sorted by lastObserved descending. */
+export declare function listQuirks(deps: QuirkStoreDeps): Promise<Quirk[]>;
+/** Recall quirks matching a query, with confidence re-weighting. */
+export declare function recallQuirks(deps: QuirkStoreDeps, query: string, options?: {
+    topK?: number;
+    quirkType?: string;
+    tags?: string[];
+}): 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;