opencode-rag-plugin 1.15.0 → 1.17.0

package/dist/cli/commands/init-helpers.js

@@ -8,6 +8,7 @@
 import path from "node:path";
 import os from "node:os";
 import { existsSync, mkdirSync, rmSync, symlinkSync, } from "node:fs";
+import { execSync } from "node:child_process";
 import { DEFAULT_CONFIG } from "../../core/config.js";
 import { c } from "../format.js";
 import { getStringRecord, readJsonObject, writeJsonFile, } from "../helpers.js";
@@ -61,7 +62,7 @@ export function buildOpencodeConfig(existing) {
     // Plugin is loaded via .opencode/plugins/rag-plugin.js auto-discovery,
     // not via npm package resolution. Stale "plugin" entries from older
     // init versions would trigger npm install (which fails due to native
-    // dependencies like canvas) and produce "Plugin export is not a function".
+    // dependencies like sharp) and produce "Plugin export is not a function".
     delete next.plugin;
     return next;
 }
@@ -247,6 +248,48 @@ export function mergeGitignoreContent(existingContent) {
     merged.push("# OpenCodeRAG workspace state", ...missing, "");
     return merged.join("\n");
 }
+const BEGIN_MARKER = "<!-- BEGIN opencode-rag -->";
+const END_MARKER = "<!-- END opencode-rag -->";
+const AGENTS_MD_SECTION = [
+    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",
+    "",
+    "If no results, run `opencode-rag index`.",
+    END_MARKER,
+].join("\n");
+/**
+ * Merge the OpenCodeRAG directive section into an existing `AGENTS.md`.
+ *
+ * The directive is wrapped in sentinel markers so re-runs replace the
+ * section in place rather than appending duplicates. Existing content
+ * outside the markers is always preserved. If no existing content is
+ * provided, the section alone is returned as a new file.
+ *
+ * @param existingContent - The current `AGENTS.md` content, or `undefined` if absent.
+ * @returns The merged `AGENTS.md` content with a trailing newline.
+ */
+export function mergeAgentsMdContent(existingContent) {
+    if (!existingContent) {
+        return `${AGENTS_MD_SECTION}\n`;
+    }
+    const beginIdx = existingContent.indexOf(BEGIN_MARKER);
+    const endIdx = existingContent.indexOf(END_MARKER);
+    if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+        const before = existingContent.slice(0, beginIdx);
+        const after = existingContent.slice(endIdx + END_MARKER.length);
+        const merged = `${before}${AGENTS_MD_SECTION}${after}`;
+        return merged.endsWith("\n") ? merged : `${merged}\n`;
+    }
+    const trimmed = existingContent.trimEnd();
+    const separator = trimmed.endsWith(BEGIN_MARKER) ? "" : "\n\n";
+    return `${trimmed}${separator}${AGENTS_MD_SECTION}\n`;
+}
 /**
  * Get the runtime directory path (`~/.opencode`).
  *
@@ -290,8 +333,47 @@ export async function installPluginFromGlobal(opencodeDir, packageName, skipInst
     const globalPluginDir = path.join(runtimeDir, "node_modules", packageName);
     const workspaceTarget = path.join(opencodeDir, "node_modules", packageName);
     if (!existsSync(globalPluginDir)) {
+        // Fallback: try the global npm prefix
+        let globalRoot;
+        try {
+            globalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 10_000 }).trim();
+        }
+        catch {
+            throw new Error(`Global plugin cache not found at ${globalPluginDir}. ` +
+                "Run 'opencode-rag setup' or install globally with 'npm install -g opencode-rag-plugin' first.");
+        }
+        const globalNpmPluginDir = path.join(globalRoot, packageName);
+        if (existsSync(globalNpmPluginDir) && existsSync(path.join(globalNpmPluginDir, "dist", "cli.js"))) {
+            console.log(`  ${c.created("Found:")} ${packageName} in global npm prefix, linking...`);
+            if (existsSync(workspaceTarget)) {
+                rmSync(workspaceTarget, { recursive: true, force: true });
+            }
+            mkdirSync(path.dirname(workspaceTarget), { recursive: true });
+            createJunction(globalNpmPluginDir, workspaceTarget);
+            const cliEntry = path.join(workspaceTarget, "dist", "cli.js");
+            if (existsSync(cliEntry)) {
+                console.log(`  ${c.success("Linked:")} ${packageName} from global npm`);
+                // Also link @opencode-ai/plugin from global npm
+                const globalSdkDir = path.join(globalRoot, "@opencode-ai", "plugin");
+                const workspaceSdkDir = path.join(opencodeDir, "node_modules", "@opencode-ai", "plugin");
+                if (existsSync(globalSdkDir) && !existsSync(workspaceSdkDir)) {
+                    mkdirSync(path.dirname(workspaceSdkDir), { recursive: true });
+                    try {
+                        createJunction(globalSdkDir, workspaceSdkDir);
+                    }
+                    catch {
+                        const { cpSync } = await import("node:fs");
+                        cpSync(globalSdkDir, workspaceSdkDir, { recursive: true });
+                    }
+                }
+                console.log(`  ${c.success("Linked:")} @opencode-ai/plugin from global npm`);
+                return;
+            }
+            // Junction failed or incomplete — fall through to error
+            rmSync(workspaceTarget, { recursive: true, force: true });
+        }
         throw new Error(`Global plugin cache not found at ${globalPluginDir}. ` +
-            "Run 'install.sh compile' / 'install.ps1 compile' first.");
+            "Run 'opencode-rag setup' or install globally with 'npm install -g opencode-rag-plugin' first.");
     }
     // Remove any stale copy (e.g. from a previous 'npm install' run)
     if (existsSync(workspaceTarget)) {

package/dist/cli/commands/init.js

@@ -10,13 +10,13 @@
  * installation.
  */
 import path from "node:path";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
 import { loadConfig } from "../../core/config.js";
 import { checkProviderHealth, pullOllamaModels } from "../../embedder/health.js";
 import { destroyAllPooledConnections } from "../../embedder/http.js";
 import { c } from "../format.js";
 import { getPackageMetadata, readJsonObject, writeJsonFile } from "../helpers.js";
-import { buildOpencodeConfig, buildWorkspacePackageJson, generateDefaultConfigJson, generateSkillFile, generateWorkspacePluginFile, generateWorkspaceTuiPluginFile, installPluginFromGlobal, mergeGitignoreContent, } from "./init-helpers.js";
+import { buildOpencodeConfig, buildWorkspacePackageJson, generateDefaultConfigJson, generateSkillFile, generateWorkspacePluginFile, generateWorkspaceTuiPluginFile, installPluginFromGlobal, mergeAgentsMdContent, mergeGitignoreContent, } from "./init-helpers.js";
 /**
  * Register the `init` command on the given Commander program.
  *
@@ -142,6 +142,20 @@ export function registerInitCommand(program) {
             else {
                 console.log(`  ${c.exists("Exists:")}   .opencode/skills/opencode-rag/SKILL.md`);
             }
+            const agentsMdPath = path.join(cwd, "AGENTS.md");
+            const agentsMdExists = existsSync(agentsMdPath);
+            const nextAgentsMd = mergeAgentsMdContent(agentsMdExists ? readFileSync(agentsMdPath, "utf-8") : undefined);
+            if (!agentsMdExists || options.force) {
+                writeFileSync(agentsMdPath, nextAgentsMd, "utf-8");
+                console.log(`  ${agentsMdExists ? c.updated("Updated:") : c.created("Created:")} AGENTS.md`);
+            }
+            else if (readFileSync(agentsMdPath, "utf-8") !== nextAgentsMd) {
+                writeFileSync(agentsMdPath, nextAgentsMd, "utf-8");
+                console.log(`  ${c.updated("Updated:")}  AGENTS.md`);
+            }
+            else {
+                console.log(`  ${c.exists("Exists:")}   AGENTS.md`);
+            }
             const workspacePackageExists = existsSync(opencodePackagePath);
             const nextWorkspacePackage = buildWorkspacePackageJson(readJsonObject(opencodePackagePath), packageMetadata);
             if (!workspacePackageExists || options.force) {
@@ -157,6 +171,10 @@ export function registerInitCommand(program) {
             }
             const configExists = existsSync(configPath);
             if (!configExists || options.force) {
+                if (configExists && options.force) {
+                    copyFileSync(configPath, configPath + ".bak");
+                    console.log(`  ${c.dim("Backup:")}        ${configPath}.bak`);
+                }
                 writeFileSync(configPath, generateDefaultConfigJson(), "utf-8");
                 console.log(`  ${configExists ? c.updated("Updated:") : c.created("Created:")} opencode-rag.json`);
             }

package/dist/cli/commands/query.js

@@ -51,6 +51,7 @@ export function registerQueryCommand(program) {
                 minScore,
                 keywordIndex,
                 keywordWeight: hybridCfg?.keywordWeight,
+                hybridEnabled: hybridCfg?.enabled,
                 queryPrefix: config.embedding.queryPrefix,
                 explain: options.explain ?? false,
             });

package/dist/cli/commands/setup.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerSetupCommand(program: Command): void;

package/dist/cli/commands/setup.js

@@ -0,0 +1,113 @@
+import path from "node:path";
+import { existsSync, lstatSync, rmSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { c } from "../format.js";
+import { getPackageMetadata } from "../helpers.js";
+import { getRuntimeDir, getVersionFile, readVersionFile, setupRuntime, } from "../../core/setup-runtime.js";
+const PLUGIN_NAME = "opencode-rag-plugin";
+function removeIfExists(targetPath) {
+    if (existsSync(targetPath)) {
+        rmSync(targetPath, { recursive: true, force: true });
+    }
+}
+function checkOpenCodeRunning() {
+    try {
+        const pids = execSync("pgrep -x opencode 2>/dev/null || (Get-Process -Name opencode -ErrorAction SilentlyContinue 2>nul | ForEach-Object { $_.Id })", {
+            encoding: "utf-8",
+            timeout: 3_000,
+        }).trim();
+        if (pids) {
+            console.log(`\n  ${c.warn("OpenCode is currently running.")} Restart it to load the updated plugin.`);
+        }
+    }
+    catch {
+        // pgrep/Get-Process aren't available or succeeded silently
+    }
+}
+export function registerSetupCommand(program) {
+    program
+        .command("setup")
+        .description("Set up the OpenCodeRAG runtime (~/.opencode/) for OpenCode plugin discovery")
+        .option("--uninstall", "remove the runtime and cleanup")
+        .option("-f, --force", "force re-setup even if up-to-date")
+        .option("--check", "check whether the runtime is correctly installed")
+        .action(async (options) => {
+        const pkg = getPackageMetadata();
+        const pluginVersion = pkg.version;
+        const runtimeDir = getRuntimeDir();
+        const versionFile = getVersionFile(runtimeDir);
+        const runtimePluginDir = path.join(runtimeDir, "node_modules", PLUGIN_NAME);
+        const runtimeSdkDir = path.join(runtimeDir, "node_modules", "@opencode-ai");
+        const runtimeSdkPluginDir = path.join(runtimeSdkDir, "plugin");
+        // --- check status ---
+        if (options.check) {
+            console.log(`\n${c.heading("OpenCodeRAG Runtime Status")}\n`);
+            const runtimeDist = path.join(runtimePluginDir, "dist");
+            if (existsSync(runtimeDist)) {
+                console.log(`  ${c.label("Runtime:")}    ${c.success("installed")} at ${c.file(runtimeDir)}`);
+                const installedVersion = readVersionFile(versionFile);
+                console.log(`  ${c.label("Installed:")}  ${c.value(installedVersion ?? "?")}`);
+                if (installedVersion !== pluginVersion) {
+                    console.log(`  ${c.label("Published:")}  ${c.value(pluginVersion)} ${c.warn("(update available — run `opencode-rag setup` to sync)")}`);
+                }
+                console.log(`  ${c.label("Plugin:")}    ${existsSync(runtimePluginDir) ? (() => {
+                    try {
+                        const stat = lstatSync(runtimePluginDir);
+                        return stat.isSymbolicLink() ? "junction" : "directory";
+                    }
+                    catch {
+                        return "?";
+                    }
+                })() : "missing"}`);
+                console.log(`  ${c.label("SDK:")}       ${existsSync(runtimeSdkPluginDir) ? "present" : "missing"}`);
+            }
+            else {
+                console.log(`  ${c.label("Runtime:")}    ${c.warn("not installed")}`);
+                console.log(`  ${c.label("Run:")}       ${c.file("opencode-rag setup")} to install`);
+            }
+            console.log();
+            return;
+        }
+        // --- uninstall ---
+        if (options.uninstall) {
+            console.log(`\n${c.heading("Removing OpenCodeRAG runtime...")}\n`);
+            removeIfExists(runtimePluginDir);
+            removeIfExists(runtimeSdkDir);
+            removeIfExists(versionFile);
+            console.log(`  ${c.updated("Removed:")} ${c.file(runtimeDir)}`);
+            console.log(`\n  ${c.success("Done.")} Run ${c.file("npm uninstall -g opencode-rag-plugin")} to remove the global package.\n`);
+            return;
+        }
+        // --- install ---
+        console.log(`\n${c.heading("Setting up OpenCodeRAG runtime...")}\n`);
+        // Check if already installed and up-to-date
+        const installedVersion = readVersionFile(versionFile);
+        const runtimeDist = path.join(runtimePluginDir, "dist");
+        const alreadyInstalled = existsSync(runtimeDist);
+        if (alreadyInstalled && installedVersion === pluginVersion && !options.force) {
+            console.log(`  ${c.success("Already up-to-date.")} (${c.value(pluginVersion)}) at ${c.file(runtimeDir)}\n`);
+            console.log(`  ${c.dim("Run `opencode-rag setup --force` to re-install.")}\n`);
+            return;
+        }
+        const result = await setupRuntime({ force: options.force, version: pluginVersion });
+        if (result.success) {
+            console.log(`  ${c.created("Updated:")} runtime at ${c.file(runtimeDir)}`);
+            console.log(`  ${c.created("Version:")} ${c.value(pluginVersion)}`);
+            console.log(`\n${c.success("Setup complete.")}`);
+            console.log(`\n  ${c.dim("Next steps:")}`);
+            console.log(`  ${c.dim("  1. Restart OpenCode if it is running")}`);
+            console.log(`  ${c.dim("  2. Run `opencode-rag init` in each workspace")}`);
+            console.log(`  ${c.dim("  3. Run `opencode-rag index` to build the search index")}`);
+        }
+        else {
+            for (const err of result.errors) {
+                console.error(`  ${c.error("✗")} ${err}`);
+            }
+            console.error(`\n  ${c.error("Setup failed. Please check the errors above or run with --force.\n")}`);
+            process.exit(1);
+        }
+        checkOpenCodeRunning();
+        console.log();
+    });
+}
+//# sourceMappingURL=setup.js.map

package/dist/cli/commands/status.js

@@ -5,9 +5,12 @@
  * `status` command — shows index statistics, store health, and configuration summary.
  */
 import path from "node:path";
+import os from "node:os";
 import fs from "node:fs";
 import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo, formatTimestamp } from "../format.js";
 import { getIndexStatusSummary } from "../../indexer.js";
+import { getPackageMetadata } from "../helpers.js";
+import { checkForUpdate } from "../../core/version-check.js";
 /**
  * Check for a stale index.lock file and clean it up if the owning process is dead.
  *
@@ -62,7 +65,7 @@ export function registerStatusCommand(program) {
         try {
             const cwd = process.cwd();
             let logFilePath = path.resolve(cwd, ".opencode", "opencode-rag.log");
-            const ctx = await resolveCliContext(options, logFilePath, { skipProbe: true, skipKeywordIndex: true });
+            const ctx = await resolveCliContext(options, logFilePath, { skipProbe: true });
             const { config, store, storePath, keywordIndex } = ctx;
             logFilePath = ctx.logFilePath;
             checkStaleLock(storePath, logFilePath);
@@ -83,7 +86,34 @@ export function registerStatusCommand(program) {
             logCliInfo(logFilePath, "status", `${c.label("Pending files:")}     ${c.num(summary.pendingFiles)}`);
             logCliInfo(logFilePath, "status", `${c.label("Indexed chunks:")}    ${c.num(summary.storeChunkCount)}`);
             logCliInfo(logFilePath, "status", `${c.label("Expected chunks:")}   ${c.num(summary.manifestExpectedChunks)}`);
-            logCliInfo(logFilePath, "status", `${c.label("Watch mode:")}        ${c.dim("off")}`);
+            // Read watcher status from the background auto-indexer
+            const watcherStatusPath = path.join(storePath, "watcher-status.json");
+            let watchModeDisplay;
+            if (fs.existsSync(watcherStatusPath)) {
+                try {
+                    const raw = fs.readFileSync(watcherStatusPath, "utf-8");
+                    const ws = JSON.parse(raw);
+                    if (ws.lastRunAt) {
+                        const lastRun = formatTimestamp(ws.lastRunAt);
+                        watchModeDisplay = ws.running
+                            ? c.enabled("active") + c.dim(" (last run: " + lastRun + ")")
+                            : c.enabled("on") + c.dim(" (last run: " + lastRun + ")");
+                    }
+                    else {
+                        watchModeDisplay = c.enabled("on");
+                    }
+                }
+                catch {
+                    watchModeDisplay = c.enabled("on") + c.dim(" (status unknown)");
+                }
+            }
+            else if (config.openCode.autoIndex?.enabled) {
+                watchModeDisplay = c.enabled("enabled (config)");
+            }
+            else {
+                watchModeDisplay = c.dim("off");
+            }
+            logCliInfo(logFilePath, "status", `${c.label("Watch mode:")}        ${watchModeDisplay}`);
             const kiCount = config.retrieval.hybridSearch?.enabled
                 ? keywordIndex?.count() ?? 0
                 : 0;
@@ -94,6 +124,38 @@ export function registerStatusCommand(program) {
             if (summary.storeChunkCount > 0 && summary.manifestExpectedChunks > 0 && summary.storeChunkCount < summary.manifestExpectedChunks * 0.5) {
                 logCliInfo(logFilePath, "status", `${c.label("Data loss detected:")} ${c.warn("yes")} — store has fewer chunks than expected. Run 'opencode-rag index' to rebuild.`);
             }
+            // Version & runtime status
+            const pkg = getPackageMetadata();
+            logCliInfo(logFilePath, "status", `${c.label("Plugin version:")}    ${c.value(pkg.version)}`);
+            const versionFilePath = path.join(os.homedir(), ".opencode", ".bundle-version");
+            const runtimeDir = path.join(os.homedir(), ".opencode", "node_modules", "opencode-rag-plugin", "dist");
+            const runtimeOk = fs.existsSync(runtimeDir);
+            if (!runtimeOk) {
+                logCliInfo(logFilePath, "status", `${c.label("Runtime:")}           ${c.warn("not set up — run `opencode-rag setup`")}`);
+            }
+            else {
+                try {
+                    const installedVersion = fs.readFileSync(versionFilePath, "utf-8").trim();
+                    if (installedVersion !== pkg.version) {
+                        logCliInfo(logFilePath, "status", `${c.label("Runtime version:")}   ${c.warn(installedVersion)} ${c.dim("(sync with `opencode-rag setup`)")}`);
+                    }
+                    else {
+                        logCliInfo(logFilePath, "status", `${c.label("Runtime:")}           ${c.success("up-to-date")}`);
+                    }
+                }
+                catch {
+                    logCliInfo(logFilePath, "status", `${c.label("Runtime:")}           ${c.warn("version unknown — run `opencode-rag setup`")}`);
+                }
+            }
+            // Async GitHub update check (fire-and-forget, 5s timeout)
+            // Only phone home if autoUpdate is explicitly enabled (opt-in).
+            if (config.autoUpdate?.enabled) {
+                checkForUpdate(pkg.version).then((info) => {
+                    if (info.updateAvailable) {
+                        process.stdout.write(`  ${c.label("Update:")}            ${c.warn(`v${info.latestVersion} available — npm update -g opencode-rag-plugin`)}\n`);
+                    }
+                }).catch(() => { });
+            }
             await cleanupContext(ctx);
         }
         catch (err) {

package/dist/cli/index.js

@@ -14,7 +14,7 @@ import { realpathSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getPackageMetadata } from "./helpers.js";
-import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerInitCommand, registerUiCommand, registerMcpCommand, registerUpdateCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerDescribeImageCommand, } from "./commands/index.js";
+import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerInitCommand, registerUiCommand, registerMcpCommand, registerSetupCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerDescribeImageCommand, } from "./commands/index.js";
 /**
  * The top-level Commander program instance that defines the `opencode-rag` CLI.
  *
@@ -38,7 +38,7 @@ registerDumpCommand(program);
 registerDescribeImageCommand(program);
 registerUiCommand(program);
 registerMcpCommand(program);
-registerUpdateCommand(program);
+registerSetupCommand(program);
 registerEvalSessionsCommand(program);
 registerEvalAnalyzeCommand(program);
 registerEvalCompareCommand(program);

package/dist/content/image.js

@@ -19,14 +19,22 @@ export function isImageFile(fp) {
 function isBmpFile(fp) {
     return fp.toLowerCase().endsWith(".bmp");
 }
+const MAX_BMP_DIMENSION = 10_000;
+const MAX_BMP_ALLOC = 500 * 1024 * 1024; // 500 MB
 function decodeBmp(buffer) {
     const signature = buffer.toString("ascii", 0, 2);
     if (signature !== "BM")
         throw new Error("Not a BMP file");
+    if (buffer.length < 54)
+        throw new Error("Truncated BMP header");
     const dibSize = buffer.readUInt32LE(14);
     const width = buffer.readInt32LE(18);
     const rawHeight = buffer.readInt32LE(22);
     const bitsPerPixel = buffer.readUInt16LE(28);
+    if (width <= 0 || Math.abs(rawHeight) <= 0)
+        throw new Error("Invalid BMP dimensions");
+    if (width > MAX_BMP_DIMENSION || Math.abs(rawHeight) > MAX_BMP_DIMENSION)
+        throw new Error(`BMP dimensions (${width}x${rawHeight}) exceed ${MAX_BMP_DIMENSION}x${MAX_BMP_DIMENSION} limit`);
     if (bitsPerPixel !== 24 && bitsPerPixel !== 32)
         throw new Error(`Unsupported BMP bit depth: ${bitsPerPixel}. Only 24 and 32 bit are supported.`);
     if (dibSize < 40)
@@ -38,8 +46,17 @@ function decodeBmp(buffer) {
     const rowSize = Math.floor((bitsPerPixel * width + 31) / 32) * 4;
     const topDown = rawHeight < 0;
     const absHeight = Math.abs(rawHeight);
+    const allocSize = width * absHeight * channels;
+    if (allocSize > MAX_BMP_ALLOC)
+        throw new Error(`BMP allocation (${allocSize} bytes) exceeds ${MAX_BMP_ALLOC} byte limit`);
     const pixelOffset = buffer.readUInt32LE(10);
-    const pixels = Buffer.alloc(width * absHeight * channels);
+    // Clamp dimensions to prevent OOM from crafted BMP headers.
+    const MAX_BMP_DIM = 16384;
+    if (width > MAX_BMP_DIM || absHeight > MAX_BMP_DIM) {
+        throw new Error(`BMP dimensions too large: ${width}x${absHeight} (max ${MAX_BMP_DIM})`);
+    }
+    const pixels = Buffer.alloc(allocSize);
+    const lastValidSrc = buffer.length - 1;
     for (let y = 0; y < absHeight; y++) {
         const srcY = topDown ? y : absHeight - 1 - y;
         const srcRow = pixelOffset + srcY * rowSize;
@@ -47,6 +64,10 @@ function decodeBmp(buffer) {
         for (let x = 0; x < width; x++) {
             const srcPx = srcRow + x * (bitsPerPixel / 8);
             const dstPx = dstRow + x * channels;
+            if (srcPx + 3 > lastValidSrc) {
+                pixels.fill(0, dstPx, dstPx + channels);
+                continue;
+            }
             if (channels === 4) {
                 pixels[dstPx] = buffer[srcPx + 2];
                 pixels[dstPx + 1] = buffer[srcPx + 1];
@@ -94,8 +115,8 @@ export async function resizeImage(buffer, filePath, maxDimension) {
             .jpeg({ quality: 80 })
             .toBuffer();
     }
-    catch {
-        return buffer;
+    catch (err) {
+        throw new Error(`Image resize failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
 /**

package/dist/content/reader.d.ts

@@ -3,6 +3,8 @@
  */
 import type { RagConfig } from "../core/config.js";
 import { type FileManifest } from "../core/manifest.js";
+import { DescriptionCache } from "../core/desc-cache.js";
+import { type ImageVisionProvider } from "../chunker/image.js";
 /** Metadata and extracted content for a single workspace file discovered during scanning. */
 export interface WorkspaceFile {
     filePath: string;
@@ -32,6 +34,9 @@ export declare function walkFiles(dir: string, extensions: Set<string>, excludeD
  * Scan the workspace directory for indexable files, reading content or dispatching
  * binary extraction (PDF, DOCX, DOC, Excel, images). Respects the file manifest
  * for incremental re-indexing by skipping unchanged files.
+ *
+ * @param descCache - Optional persistent description cache. When set, image
+ *   descriptions are cached and reused across sessions (survives aborted runs).
  */
-export declare function scanWorkspaceFiles(cwd: string, config: RagConfig, logger?: Logger, manifest?: FileManifest, filterPaths?: string[]): Promise<WorkspaceFile[]>;
+export declare function scanWorkspaceFiles(cwd: string, config: RagConfig, logger?: Logger, manifest?: FileManifest, filterPaths?: string[], injectedVisionProvider?: ImageVisionProvider, descCache?: DescriptionCache): Promise<WorkspaceFile[]>;
 export {};

package/dist/content/reader.js

@@ -4,7 +4,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import pLimit from "p-limit";
-import { computeFileHash, normalizeFilePath } from "../core/manifest.js";
+import { computeFileHash, computeDescriptionConfigHash, normalizeFilePath } from "../core/manifest.js";
+import { DescriptionCache } from "../core/desc-cache.js";
 import { createImageVisionProvider, } from "../chunker/image.js";
 import * as pdfExtractor from "./pdf.js";
 import * as docxExtractor from "./docx.js";
@@ -84,8 +85,11 @@ async function dispatchExtraction(filePath, buffer, imageVisionProvider, imagePr
  * Scan the workspace directory for indexable files, reading content or dispatching
  * binary extraction (PDF, DOCX, DOC, Excel, images). Respects the file manifest
  * for incremental re-indexing by skipping unchanged files.
+ *
+ * @param descCache - Optional persistent description cache. When set, image
+ *   descriptions are cached and reused across sessions (survives aborted runs).
  */
-export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPaths) {
+export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPaths, injectedVisionProvider, descCache) {
     const extensions = new Set(config.indexing.includeExtensions);
     let imageVisionProvider = null;
     let imagePrompt;
@@ -95,7 +99,7 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
         for (const ext of imageExtractor.SUPPORTED_IMAGE_EXTENSIONS) {
             extensions.add(ext.toLowerCase());
         }
-        imageVisionProvider = createImageVisionProvider(imageCfg);
+        imageVisionProvider = injectedVisionProvider ?? createImageVisionProvider(imageCfg);
         imagePrompt = imageCfg.prompt;
         imageResizeMaxDimension = imageCfg.resizeMaxDimension;
     }
@@ -135,6 +139,10 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
     const scanConcurrency = Math.min(config.indexing.concurrency * 2, 16);
     const textLimit = pLimit(scanConcurrency);
     const imageLimit = pLimit(1);
+    // Compute a hash of the image description config — used to build cache keys.
+    const imageDescConfigHash = config.imageDescription?.enabled
+        ? computeDescriptionConfigHash(config) ?? ""
+        : "";
     let completed = 0;
     async function processFile(filePath) {
         const normalizedPath = normalizeFilePath(filePath);
@@ -168,11 +176,48 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
             excelExtractor.EXCEL_EXTENSIONS.has(filePath.toLowerCase()) ||
             isImage;
         logger?.info(`Reading: ${filePath}`);
+        const buffer = isBinary ? await fs.readFile(filePath) : Buffer.alloc(0);
+        // For images, check the persistent description cache before calling the vision provider
+        if (isImage && descCache && imageDescConfigHash) {
+            const imageBytesHash = computeFileHash(buffer.toString("base64"));
+            const cacheKey = DescriptionCache.imageKey(imageBytesHash, imageDescConfigHash);
+            const cachedDesc = descCache.get(cacheKey);
+            if (cachedDesc) {
+                logger?.info(`  Using cached image description: ${filePath}`);
+                const content = cachedDesc;
+                let fileMtime;
+                let fileSize;
+                try {
+                    const stat = await fs.stat(filePath);
+                    fileMtime = stat.mtimeMs;
+                    fileSize = stat.size;
+                }
+                catch { /* best-effort stat */ }
+                completed++;
+                return {
+                    filePath,
+                    normalizedPath,
+                    content,
+                    hash: computeFileHash(content),
+                    isEmpty: false,
+                    isTooSmall: false,
+                    extractionStatus: "ok",
+                    mtime: fileMtime,
+                    size: fileSize,
+                };
+            }
+        }
         if (isImage) {
             logger?.info(`  Describing image: ${filePath}`);
         }
-        const buffer = isBinary ? await fs.readFile(filePath) : Buffer.alloc(0);
         const result = await dispatchExtraction(filePath, buffer, imageVisionProvider, imagePrompt, imageResizeMaxDimension);
+        // Cache the image description for future runs
+        if (isImage && result.ok && descCache && imageDescConfigHash) {
+            const imageBytesHash = computeFileHash(buffer.toString("base64"));
+            const cacheKey = DescriptionCache.imageKey(imageBytesHash, imageDescConfigHash);
+            descCache.set(cacheKey, result.content);
+            await descCache.save();
+        }
         if (!result.ok) {
             logger?.warn(`  ${filePath} (extraction failed: ${result.error})`);
         }

package/dist/core/config.d.ts

@@ -164,6 +164,8 @@ export interface RagConfig {
         documentPrefix?: string;
         /** Prefix prepended to queries before embedding (e.g. "search_query:"). */
         queryPrefix?: string;
+        /** Cached embedding vector dimension. Probed once on first startup, then persisted to config. */
+        vectorDimension?: number;
     };
     /** Indexing pipeline controls: what to index, concurrency, batch sizes. */
     indexing: {
@@ -187,6 +189,12 @@ export interface RagConfig {
         ollamaMaxBatchSize?: number;
         /** Maximum concurrent description generation requests. */
         descriptionConcurrency?: number;
+        /**
+         * Maximum file size in bytes for SVG/XML files before chunking is skipped.
+         * Large SVGs can cause tree-sitter to hang. Set to 0 for no limit.
+         * @default 1_048_576 (1 MB)
+         */
+        maxSvgSizeBytes?: number;
     };
     /** Vector storage backend configuration. */
     vectorStore: {
@@ -227,6 +235,8 @@ export interface RagConfig {
         readNoResultsBehavior?: ReadNoResultsBehavior;
         /** Maximum related files shown when read results are empty. */
         readRelatedFilesMax?: number;
+        /** Whether to inject RAG tool guidance into system prompts (default true). */
+        injectSystemPrompt?: boolean;
     };
     /** Custom chunker module registrations. */
     chunkers?: ChunkerConfig[];
@@ -293,3 +303,12 @@ export declare const CONFIG_FILE_CANDIDATES: string[];
 export declare function findConfigFile(directory: string): string | undefined;
 /** Load and parse a JSON config file, deep-merge with defaults, optionally validate. */
 export declare function loadConfig(filePath: string, validate?: boolean): RagConfig;
+/**
+ * Persist a probed embedding vector dimension into the config JSON file.
+ * Sets `embedding.vectorDimension` so subsequent startups skip the probe.
+ * This is a best-effort operation — failures are silently ignored.
+ *
+ * @param configPath - Absolute path to the config JSON file.
+ * @param dimension - The vector dimension to persist.
+ */
+export declare function persistProbedDimension(configPath: string, dimension: number): void;