opencode-rag-plugin 1.15.1 → 1.17.0

package/dist/mcp/handlers.js

@@ -4,7 +4,26 @@ import { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "../retriever/cont
 import { Parser } from "web-tree-sitter";
 import { initParser, loadLanguage, walkTree } from "../chunker/grammar.js";
 import { readFileSync } from "node:fs";
-import { resolve, isAbsolute } from "node:path";
+import { resolve, isAbsolute, relative } from "node:path";
+/**
+ * Resolve a user-supplied file path against the worktree root, refusing to
+ * escape the worktree. Absolute paths are accepted only if they already reside
+ * under the worktree; relative paths are joined to the worktree and any `..`
+ * segments that would escape are rejected.
+ *
+ * @throws {Error} if the resolved path lies outside `worktree`.
+ */
+export function resolveFilePath(filePath, worktree) {
+    const root = resolve(worktree);
+    const candidate = isAbsolute(filePath) ? resolve(filePath) : resolve(root, filePath);
+    const rel = relative(root, candidate);
+    if (rel === "")
+        return root;
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`Path "${filePath}" escapes worktree root "${root}" — access denied.`);
+    }
+    return candidate;
+}
 const SKELETON_CONFIGS = {
     ".ts": { grammarName: "typescript", nodeTypes: ["function_declaration", "method_definition", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration"] },
     ".tsx": { grammarName: "typescript", nodeTypes: ["function_declaration", "method_definition", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration", "arrow_function"] },
@@ -45,11 +64,6 @@ function getExtension(filePath) {
     const dot = filePath.lastIndexOf(".");
     return dot >= 0 ? filePath.slice(dot).toLowerCase() : "";
 }
-function resolveFilePath(filePath, worktree) {
-    if (isAbsolute(filePath))
-        return filePath;
-    return resolve(worktree, filePath);
-}
 async function extractSkeleton(content, ext) {
     const config = SKELETON_CONFIGS[ext];
     if (!config) {
@@ -86,6 +100,8 @@ async function extractSkeleton(content, ext) {
         return [];
     const nodeTypes = new Set(config.nodeTypes);
     const astNodes = walkTree(tree.rootNode, nodeTypes, content, 15);
+    tree.delete();
+    parser.delete();
     return astNodes.map((node) => ({
         type: node.type,
         name: extractNodeName(node.text, node.type),
@@ -160,6 +176,7 @@ export async function handleSearchSemantic(params, embedder, store, cfg, keyword
         minScore: cfg.retrieval.minScore,
         keywordIndex,
         keywordWeight: cfg.retrieval.hybridSearch?.keywordWeight,
+        hybridEnabled: cfg.retrieval.hybridSearch?.enabled,
         queryPrefix: cfg.embedding.queryPrefix,
     };
     const rawResults = await retrieveFn_(query, embedder, store, retrieveOpts);

package/dist/mcp/server.js

@@ -95,6 +95,8 @@ export async function createMcpServer(options) {
         server,
         close: async () => {
             await server.close();
+            await ctx.store.close();
+            ctx.keywordIndex.close();
         },
     };
 }

package/dist/opencode/create-read-tool.d.ts

@@ -24,6 +24,8 @@ export interface RagReadToolOptions {
     }>;
     /** Optional keyword index for hybrid search. */
     keywordIndex?: KeywordIndex;
+    /** Maximum number of sessions to retain in the retrieval cache. */
+    maxSessionCacheSize?: number;
 }
 /**
  * Create the RAG-backed read tool for OpenCode plugin registration.

package/dist/opencode/create-read-tool.js

@@ -63,7 +63,13 @@ export function createRagReadTool(options) {
                             }
                             else {
                                 const retrievalQuery = buildSessionQuery(messageText, resolvedPath, normalized);
-                                rawResults = await retrieve(retrievalQuery, embedder, store, { topK: retrievalTopK, keywordIndex, queryPrefix: config.embedding.queryPrefix });
+                                rawResults = await retrieve(retrievalQuery, embedder, store, { topK: retrievalTopK, keywordIndex, hybridEnabled: config.retrieval.hybridSearch?.enabled, queryPrefix: config.embedding.queryPrefix });
+                                const maxSize = options.maxSessionCacheSize ?? 50;
+                                if (!sessionRetrievalCache.has(sessionID) && sessionRetrievalCache.size >= maxSize) {
+                                    const oldest = sessionRetrievalCache.keys().next().value;
+                                    if (oldest !== undefined)
+                                        sessionRetrievalCache.delete(oldest);
+                                }
                                 sessionRetrievalCache.set(sessionID, { messageText, rawResults });
                             }
                         }
@@ -74,7 +80,7 @@ export function createRagReadTool(options) {
                                 startLine: normalized.startLine,
                                 endLine: normalized.endLine,
                             });
-                            rawResults = await retrieve(retrievalQuery, embedder, store, { topK: retrievalTopK, keywordIndex, queryPrefix: config.embedding.queryPrefix });
+                            rawResults = await retrieve(retrievalQuery, embedder, store, { topK: retrievalTopK, keywordIndex, hybridEnabled: config.retrieval.hybridSearch?.enabled, queryPrefix: config.embedding.queryPrefix });
                         }
                         // Collect related files from raw results (before filtering)
                         relatedFiles = collectRelatedFiles(rawResults, resolvedPath, readRelatedFilesMax);

package/dist/opencode/read-fallback.d.ts

@@ -1,12 +1,8 @@
 /**
  * @fileoverview Provides fallback error messages and no-results behavior dispatch for the read tool.
  */
-import type { ReadNoResultsBehavior } from "../core/config.js";
 /**
  * Error message wrapper for retrieval failures.
  */
 export declare function retrievalErrorMessage(shortError: string): string;
-/**
- * Dispatch to the correct fallback message based on behavior config.
- */
-export declare function getNoResultsMessage(behavior: ReadNoResultsBehavior, filePath?: string): string;
+/** No results fallback messages are handled inline in create-read-tool.ts. */

package/dist/opencode/read-fallback.js

@@ -12,22 +12,5 @@ export function retrievalErrorMessage(shortError) {
         shortError,
     ].join("\n");
 }
-/**
- * Dispatch to the correct fallback message based on behavior config.
- */
-export function getNoResultsMessage(behavior, filePath) {
-    switch (behavior) {
-        case "error":
-            throw new Error("OpenCodeRAG read: no indexed chunks found." +
-                (filePath ? ` File: ${filePath}` : ""));
-        case "empty":
-            return "No indexed chunks found.";
-        case "hint":
-        default:
-            if (filePath) {
-                return `No indexed chunks found for ${filePath}.`;
-            }
-            return "No relevant chunks found.";
-    }
-}
+/** No results fallback messages are handled inline in create-read-tool.ts. */
 //# sourceMappingURL=read-fallback.js.map

package/dist/opencode/read-format.js

@@ -124,9 +124,11 @@ function formatChunk(index, result) {
     lines.push(`Score: ${score.toFixed(4)}`);
     lines.push("");
     lines.push("```" + language);
-    lines.push(chunk.content);
-    if (!chunk.content.endsWith("\n")) {
-        // Ensure code block closes on its own line
+    if (chunk.content.endsWith("\n")) {
+        lines.push(chunk.content.slice(0, -1));
+    }
+    else {
+        lines.push(chunk.content);
     }
     lines.push("```");
     return lines.join("\n");

package/dist/opencode/tools.js

@@ -19,7 +19,7 @@ import { retrieve } from "../retriever/retriever.js";
 import { Parser } from "web-tree-sitter";
 import { initParser, loadLanguage, walkTree } from "../chunker/grammar.js";
 import { readFileSync } from "node:fs";
-import { resolve, isAbsolute } from "node:path";
+import { resolveWorkspacePath } from "./tool-args.js";
 const SKELETON_CONFIGS = {
     ".ts": { grammarName: "typescript", nodeTypes: ["function_declaration", "method_definition", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration"] },
     ".tsx": { grammarName: "typescript", nodeTypes: ["function_declaration", "method_definition", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration", "arrow_function"] },
@@ -68,9 +68,7 @@ function getExtension(filePath) {
  * Resolve a file path relative to the workspace root.
  */
 function resolveFilePath(filePath, worktree) {
-    if (isAbsolute(filePath))
-        return filePath;
-    return resolve(worktree, filePath);
+    return resolveWorkspacePath(worktree, filePath);
 }
 /**
  * Extract structural outline from source code using tree-sitter.
@@ -116,6 +114,8 @@ async function extractSkeleton(content, ext) {
         return [];
     const nodeTypes = new Set(config.nodeTypes);
     const astNodes = walkTree(tree.rootNode, nodeTypes, content, 15);
+    tree.delete();
+    parser.delete();
     return astNodes.map((node) => ({
         type: node.type,
         name: extractNodeName(node.text, node.type),
@@ -262,9 +262,7 @@ export function createDescribeImageTool(options) {
             try {
                 const { existsSync, readFileSync } = await import("node:fs");
                 const path = await import("node:path");
-                const resolvedPath = isAbsolute(args.filePath)
-                    ? args.filePath
-                    : resolve(worktree, args.filePath);
+                const resolvedPath = resolveWorkspacePath(worktree, args.filePath);
                 if (!existsSync(resolvedPath)) {
                     return {
                         title: "Describe image",

package/dist/plugin.js

@@ -4,7 +4,7 @@
  * automatic context injection and documentation mode.
  */
 import { tool } from "@opencode-ai/plugin/tool";
-import { loadConfig, findConfigFile, DEFAULT_CONFIG, resolveLogConfig } from "./core/config.js";
+import { loadConfig, findConfigFile, DEFAULT_CONFIG, resolveLogConfig, persistProbedDimension } from "./core/config.js";
 import { createEmbedder } from "./embedder/factory.js";
 import { createDescriptionProvider } from "./describer/factory.js";
 import { createVectorStore } from "./vectorstore/factory.js";
@@ -22,12 +22,15 @@ import { loadDocProgress, markSubdirectoryDocumented } from "./core/doc-progress
 import { loadManifest } from "./core/manifest.js";
 import { createSessionLogger } from "./eval/session-logger.js";
 import { countTokens } from "./eval/token-counter.js";
-import { checkForUpdate } from "./updater.js";
+import { checkForUpdate } from "./core/version-check.js";
+import { destroyAllPooledConnections } from "./embedder/http.js";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, execSync } from "node:child_process";
 import { tmpdir } from "node:os";
+/** Maximum entries per session map before oldest entries are evicted. */
+const MAX_SESSION_MAP_SIZE = 50;
 /** Cache of loaded RAG configurations keyed by workspace directory. */
 const configCache = new Map();
 /** Active background indexer instances keyed by workspace directory. */
@@ -36,6 +39,52 @@ const backgroundIndexers = new Map();
 const mcpServers = new Map();
 /** Pending update notifications keyed by workspace directory. */
 const pendingUpdateInfo = new Map();
+/** Guard flag to prevent re-entrant shutdown. */
+let shutdownRegistered = false;
+/** Close all active background indexers and MCP servers, then destroy idle sockets. */
+async function shutdownPluginResources() {
+    for (const [dir, indexer] of backgroundIndexers) {
+        try {
+            await indexer.close();
+        }
+        catch { /* best-effort */ }
+        backgroundIndexers.delete(dir);
+    }
+    for (const [dir, server] of mcpServers) {
+        try {
+            await server.close();
+        }
+        catch { /* best-effort */ }
+        mcpServers.delete(dir);
+    }
+    configCache.clear();
+    pendingUpdateInfo.clear();
+    destroyAllPooledConnections();
+}
+/** Register a process.beforeExit handler so that resources are cleaned up
+ *  when the OpenCode process exits (rather than only on plugin reload). */
+function registerShutdownHandler() {
+    if (shutdownRegistered)
+        return;
+    shutdownRegistered = true;
+    process.once("beforeExit", () => {
+        void shutdownPluginResources();
+    });
+}
+registerShutdownHandler();
+/** Set a bounded Map entry, evicting the oldest key if the map exceeds maximum size. */
+function boundedSet(map, key, value, maxSize) {
+    if (map.has(key)) {
+        map.set(key, value);
+        return;
+    }
+    if (map.size >= maxSize) {
+        const oldest = map.keys().next().value;
+        if (oldest !== undefined)
+            map.delete(oldest);
+    }
+    map.set(key, value);
+}
 /** Name of the semantic search tool as exposed to the LLM. */
 const CONTEXT_TOOL_NAME = "search_semantic";
 /** Marker string injected into context output to identify RAG-sourced content. */
@@ -230,10 +279,10 @@ function buildRetrievalQuery(hints) {
  * Perform a retrieval query against the vector store with the given parameters.
  * Returns an empty array for blank queries.
  */
-async function retrieveContext(query, embedder, store, topK, retrieveFn = retrieve, minScore = 0, keywordIndex, keywordWeight, queryPrefix, explain = false) {
+async function retrieveContext(query, embedder, store, topK, retrieveFn = retrieve, minScore = 0, keywordIndex, keywordWeight, queryPrefix, explain = false, hybridEnabled) {
     if (query.trim().length === 0)
         return [];
-    return retrieveFn(query, embedder, store, { topK, minScore, keywordIndex, keywordWeight, queryPrefix, explain });
+    return retrieveFn(query, embedder, store, { topK, minScore, keywordIndex, keywordWeight, hybridEnabled, queryPrefix, explain });
 }
 /**
  * Load results from one or two queries (primary + optional extra), optimize
@@ -243,9 +292,10 @@ async function retrieveContext(query, embedder, store, topK, retrieveFn = retrie
 async function loadRetrievedResults(query, embedder, store, cfg, retrieveFn = retrieve, topK = cfg.retrieval.topK, extraQuery, keywordIndex, queryPrefix, explain = false) {
     const minScore = cfg.retrieval.minScore;
     const kw = cfg.retrieval.hybridSearch?.keywordWeight;
-    const primaryResults = await retrieveContext(query, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain);
+    const hybridEnabled = cfg.retrieval.hybridSearch?.enabled;
+    const primaryResults = await retrieveContext(query, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain, hybridEnabled);
     const extraResults = extraQuery
-        ? await retrieveContext(extraQuery, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain)
+        ? await retrieveContext(extraQuery, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain, hybridEnabled)
         : [];
     const optCfg = cfg.retrieval.contextOptimization ?? DEFAULT_CONTEXT_OPTIMIZATION;
     return optimizeContext([...primaryResults, ...extraResults], { topK, config: optCfg })
@@ -355,12 +405,20 @@ export function createRagHooks(options) {
     let cachedOverrides = loadRuntimeOverrides(options.storePath);
     let overridesLastCheck = 0;
     const OVERRIDES_TTL_MS = Number(process.env.OPENCODE_RAG_OVERRIDES_TTL_MS) || 3600000;
+    let lastEffectiveCfg = null;
+    let lastEffectiveCfgTime = 0;
     function getEffectiveCfg() {
         if (Date.now() - overridesLastCheck > OVERRIDES_TTL_MS) {
             cachedOverrides = loadRuntimeOverrides(options.storePath);
             overridesLastCheck = Date.now();
+            lastEffectiveCfg = null;
+        }
+        if (lastEffectiveCfg && Date.now() - lastEffectiveCfgTime < 1000) {
+            return lastEffectiveCfg;
         }
-        return applyRuntimeOverrides(options.cfg, cachedOverrides);
+        lastEffectiveCfg = applyRuntimeOverrides(options.cfg, cachedOverrides);
+        lastEffectiveCfgTime = Date.now();
+        return lastEffectiveCfg;
     }
     // Session-level caches for lazy retrieval
     const sessionLastMessage = new Map();
@@ -538,6 +596,7 @@ export function createRagHooks(options) {
             sessionLastMessage,
             sessionRetrievalCache,
             keywordIndex,
+            maxSessionCacheSize: MAX_SESSION_MAP_SIZE,
         });
         tools["read"] = readTool;
         appendDebugLog(options.logFilePath, {
@@ -562,8 +621,8 @@ export function createRagHooks(options) {
                     if (msgInfo?.role === "assistant" &&
                         typeof msgInfo.sessionID === "string" &&
                         typeof msgInfo.id === "string") {
-                        sessionAssistantMessageId.set(msgInfo.sessionID, msgInfo.id);
-                        sessionAssistantText.set(msgInfo.sessionID, "");
+                        boundedSet(sessionAssistantMessageId, msgInfo.sessionID, msgInfo.id, MAX_SESSION_MAP_SIZE);
+                        boundedSet(sessionAssistantText, msgInfo.sessionID, "", MAX_SESSION_MAP_SIZE);
                     }
                 }
                 else if (event.type === "message.part.updated") {
@@ -577,7 +636,7 @@ export function createRagHooks(options) {
                         const assistantMsgId = sessionAssistantMessageId.get(part.sessionID);
                         if (assistantMsgId && part.messageID === assistantMsgId) {
                             const existing = sessionAssistantText.get(part.sessionID) ?? "";
-                            sessionAssistantText.set(part.sessionID, existing + delta);
+                            boundedSet(sessionAssistantText, part.sessionID, existing + delta, MAX_SESSION_MAP_SIZE);
                         }
                     }
                 }
@@ -592,42 +651,45 @@ export function createRagHooks(options) {
                 scope: "experimental.chat.system.transform",
                 message: "system guidance injected",
             });
-            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",
-            ];
-            output.system.unshift(guidance.join("\n"));
+            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",
+                ];
+                output.system.unshift(guidance.join("\n"));
+            }
             // Inject update notification if available
             const updateInfo = pendingUpdateInfo.get(options.worktree);
             if (updateInfo) {
                 output.system.unshift(`OpenCodeRAG update available: ${updateInfo.currentVersion} → ${updateInfo.latestVersion}. ` +
-                    `Run \`opencode-rag update\` to install.`);
+                    `Run \`npm update -g opencode-rag-plugin && opencode-rag setup\` to install.`);
             }
             // Inject documentation mode system prompt if enabled
             const docMode = getEffectiveCfg().documentationMode;
@@ -650,7 +712,7 @@ export function createRagHooks(options) {
                 });
                 if (text.length === 0)
                     return;
-                sessionLastMessage.set(input.sessionID, text);
+                boundedSet(sessionLastMessage, input.sessionID, text, MAX_SESSION_MAP_SIZE);
                 // Handle /doc slash command
                 if (text.startsWith("/doc")) {
                     const docMode = getEffectiveCfg().documentationMode;
@@ -1025,29 +1087,51 @@ export const ragPlugin = async (input, _options) => {
         }
         mcpServers.delete(input.directory);
     }
+    // Clean up stale config cache and pending update info for this directory
+    configCache.delete(input.directory);
+    pendingUpdateInfo.delete(input.directory);
+    // Clean up idle HTTP sockets from previous provider connections
+    destroyAllPooledConnections();
     appendDebugLog(logFilePath, {
         scope: "plugin",
         message: `OpenCode plugin enabled for ${input.directory}`,
     }, logLevel);
-    // Probe vector dimension and create store with correct dimension
+    // Use cached dimension from config if available (avoids blocking startup with an API call)
+    // If not set, probe the embedding provider once and persist the result.
     const embedder = createEmbedder(effectiveCfg);
-    let vectorDimension = 384;
-    try {
-        const probe = await embedder.embed(["dimension-probe"], "query");
-        if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
-            vectorDimension = probe[0].length;
-        }
+    let vectorDimension = effectiveCfg.embedding.vectorDimension;
+    if (vectorDimension && vectorDimension > 0) {
         appendDebugLog(logFilePath, {
             scope: "plugin",
-            message: `Vector dimension: ${vectorDimension}`,
+            message: `Vector dimension: ${vectorDimension} (cached in config)`,
         }, logLevel);
     }
-    catch (err) {
-        appendDebugLog(logFilePath, {
-            scope: "plugin",
-            message: `Dimension probe failed, falling back to ${vectorDimension}`,
-            error: err,
-        }, logLevel);
+    else {
+        vectorDimension = 384;
+        try {
+            const probe = await embedder.embed(["dimension-probe"], "query");
+            if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
+                vectorDimension = probe[0].length;
+                const configPath = findConfigFile(input.directory);
+                if (configPath) {
+                    try {
+                        persistProbedDimension(configPath, vectorDimension);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+            appendDebugLog(logFilePath, {
+                scope: "plugin",
+                message: `Vector dimension: ${vectorDimension}`,
+            }, logLevel);
+        }
+        catch (err) {
+            appendDebugLog(logFilePath, {
+                scope: "plugin",
+                message: `Dimension probe failed, falling back to ${vectorDimension}`,
+                error: err,
+            }, logLevel);
+        }
     }
     const store = createVectorStore(effectiveCfg, storePath, vectorDimension);
     // Load or create keyword index for hybrid search

package/dist/retriever/keyword-index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview In-memory inverted keyword index with stemming, tokenization, and optional serialization.
  */
-import type { Chunk, SearchResult } from "../core/interfaces.js";
+import type { Chunk, SearchResult, MetadataFilter } from "../core/interfaces.js";
 /**
  * Tokenize text into normalized tokens including stems, camelCase parts, and snake_case parts.
  *
@@ -22,7 +22,8 @@ export declare class KeywordIndex {
     addChunks(chunks: Chunk[]): void;
     getMatchedTerms(query: string, chunkId: string): string[];
     removeByFilePath(filePath: string): void;
-    search(query: string, topK: number): SearchResult[];
+    search(query: string, topK: number, filter?: MetadataFilter): SearchResult[];
+    close(): void;
     clear(): void;
     count(): number;
     save(storePath?: string): Promise<void>;

package/dist/retriever/keyword-index.js

@@ -124,7 +124,7 @@ export class KeywordIndex {
             }
         }
     }
-    search(query, topK) {
+    search(query, topK, filter) {
         if (this.chunkMap.size === 0)
             return [];
         const queryTokens = tokenize(query);
@@ -144,6 +144,7 @@ export class KeywordIndex {
             }
         }
         const sorted = [...scores.entries()]
+            .filter(([id]) => matchesFilter(this.chunkMap.get(id), filter))
             .sort((a, b) => b[1] - a[1])
             .slice(0, topK);
         return sorted.map(([chunkId, score]) => {
@@ -151,6 +152,10 @@ export class KeywordIndex {
             return { chunk, score };
         });
     }
+    close() {
+        this.invertedIndex.clear();
+        this.chunkMap.clear();
+    }
     clear() {
         this.invertedIndex.clear();
         this.chunkMap.clear();
@@ -232,4 +237,23 @@ export class KeywordIndex {
         await writeFile(targetPath, JSON.stringify({ version: INDEX_VERSION, tokens: [], chunkMap: {} }), "utf-8");
     }
 }
+function globMatch(pattern, filePath) {
+    const GLOBSTAR = "\x00GS\x00";
+    let re = pattern.replace(/\*\*/g, GLOBSTAR);
+    re = re.replace(/([.+^${}()|[\]\\])/g, "\\$1");
+    re = re.replace(new RegExp(GLOBSTAR, "g"), ".*");
+    re = re.replace(/\*/g, "[^/]*");
+    re = re.replace(/\?/g, ".");
+    return new RegExp("^" + re + "$").test(filePath);
+}
+function matchesFilter(chunk, filter) {
+    if (!filter)
+        return true;
+    if (filter.languages?.length && !filter.languages.includes(chunk.metadata.language))
+        return false;
+    if (filter.pathPatterns?.length) {
+        return filter.pathPatterns.some((p) => globMatch(p, chunk.metadata.filePath));
+    }
+    return true;
+}
 //# sourceMappingURL=keyword-index.js.map

package/dist/retriever/retriever.d.ts

@@ -1,15 +1,18 @@
 /**
  * @fileoverview Performs hybrid vector-keyword retrieval with configurable scoring and explanation.
  */
-import type { EmbeddingProvider, KeywordIndex, VectorStore, SearchResult } from "../core/interfaces.js";
+import type { EmbeddingProvider, KeywordIndex, VectorStore, SearchResult, MetadataFilter } from "../core/interfaces.js";
 /** Options controlling the retrieval behavior. */
 export interface RetrieveOptions {
     topK?: number;
     minScore?: number;
     keywordIndex?: KeywordIndex;
     keywordWeight?: number;
+    /** Whether hybrid search is enabled. When false, keyword index is ignored. */
+    hybridEnabled?: boolean;
     queryPrefix?: string;
     explain?: boolean;
+    filter?: MetadataFilter;
 }
 /**
  * Perform hybrid vector-keyword retrieval with configurable scoring.