opencode-rag-plugin 1.17.2 → 1.17.3

package/ReadMe.md

@@ -125,14 +125,16 @@ The agent maintains all wiki pages during normal coding sessions (ingest on lear
 
 See [Plugin documentation](doc/plugin.md#6-wiki-mode--slash-command-wiki) for the full protocol.
 
-## MCP Server
+## MCP Server (Optional)
 
-OpenCodeRAG ships a CLI-based [MCP (Model Context Protocol)](https://spec.modelcontextprotocol.io/) server that exposes semantic code tools to any MCP-compatible client (Claude Desktop, OpenCode, Cursor, etc.).
+OpenCodeRAG ships a CLI-based [MCP (Model Context Protocol)](https://spec.modelcontextprotocol.io/) server that exposes semantic code tools to any MCP-compatible client (Claude Desktop, Cursor, etc.).
 
 ```bash
 opencode-rag mcp
 ```
 
+> **Note:** The MCP server is **optional**. When running as an OpenCode plugin, the four tools are registered **in-process** and work without the MCP server. The `chat.message` hook for hotkey injection also runs in-process. The MCP server is only needed when an **external** MCP client connects to OpenCodeRAG. The plugin auto-starts the server only if `mcp.enabled` is `true` in your config (default: `false`).
+
 ### MCP Tools
 
 | Tool | Description |

package/dist/core/auto-update-state.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Persisted state for the background auto-update mechanism.
+ * Tracks when an install was last attempted, for which version,
+ * and consecutive failure counts to implement cooldown and backoff.
+ */
+/** Persisted state of a background auto-update attempt. */
+export interface AutoUpdateState {
+    /** Epoch ms of the most recent attempt. */
+    lastAttemptAt: number;
+    /** The latestVersion we tried to install (or checked). */
+    lastAttemptedVersion: string;
+    /** Outcome of the last attempt. */
+    lastResult: "success" | "failure";
+    /** Consecutive failures so far (reset on success). */
+    consecutiveFailures: number;
+}
+/** Full path to the state file for a given store path. */
+export declare function statePath(storePath: string): string;
+/** Load persisted auto-update state, or return null if missing / corrupt. */
+export declare function loadAutoUpdateState(storePath: string): AutoUpdateState | null;
+/** Persist auto-update state to disk (best-effort, never throws). */
+export declare function saveAutoUpdateState(storePath: string, state: AutoUpdateState): void;
+/**
+ * Determine whether an auto-install attempt should proceed, based on
+ * the persisted state, the version we just discovered, and configured
+ * limits.
+ *
+ * @returns An object with `attempt: boolean` and `reason: string`.
+ */
+export declare function shouldAttemptInstall(state: AutoUpdateState | null, latestVersion: string, cooldownMs: number, maxConsecutiveFailures: number): {
+    attempt: boolean;
+    reason: string;
+};

package/dist/core/auto-update-state.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Persisted state for the background auto-update mechanism.
+ * Tracks when an install was last attempted, for which version,
+ * and consecutive failure counts to implement cooldown and backoff.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/** Name of the state file written to the store path. */
+const STATE_FILE_NAME = ".auto-update-state.json";
+/** Full path to the state file for a given store path. */
+export function statePath(storePath) {
+    return path.join(storePath, STATE_FILE_NAME);
+}
+/** Load persisted auto-update state, or return null if missing / corrupt. */
+export function loadAutoUpdateState(storePath) {
+    try {
+        const p = statePath(storePath);
+        if (!existsSync(p))
+            return null;
+        const raw = readFileSync(p, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.lastAttemptAt !== "number" ||
+            typeof parsed.lastAttemptedVersion !== "string" ||
+            (parsed.lastResult !== "success" && parsed.lastResult !== "failure") ||
+            typeof parsed.consecutiveFailures !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist auto-update state to disk (best-effort, never throws). */
+export function saveAutoUpdateState(storePath, state) {
+    try {
+        writeFileSync(statePath(storePath), JSON.stringify(state, null, 2), "utf-8");
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Determine whether an auto-install attempt should proceed, based on
+ * the persisted state, the version we just discovered, and configured
+ * limits.
+ *
+ * @returns An object with `attempt: boolean` and `reason: string`.
+ */
+export function shouldAttemptInstall(state, latestVersion, cooldownMs, maxConsecutiveFailures) {
+    if (!state) {
+        return { attempt: true, reason: "first run" };
+    }
+    const elapsed = Date.now() - state.lastAttemptAt;
+    if (state.lastAttemptedVersion === latestVersion && elapsed < cooldownMs) {
+        return {
+            attempt: false,
+            reason: `version ${latestVersion} already attempted ${Math.round(elapsed / 1000)}s ago (cooldown ${Math.round(cooldownMs / 1000)}s)`,
+        };
+    }
+    if (state.lastResult === "failure" && state.consecutiveFailures >= maxConsecutiveFailures && elapsed < cooldownMs) {
+        return {
+            attempt: false,
+            reason: `${state.consecutiveFailures} consecutive failures within cooldown window`,
+        };
+    }
+    return { attempt: true, reason: "proceeding" };
+}
+//# sourceMappingURL=auto-update-state.js.map

package/dist/core/config.d.ts

@@ -128,15 +128,21 @@ export interface TuiConfig {
     /** Keybinding to toggle the chunk viewer panel. */
     chunksKeybinding: string;
 }
-/** Configuration for MCP (Model Context Protocol) server integration. */
+/** Configuration for the standalone MCP (Model Context Protocol) server. */
 export interface McpConfig {
-    /** Whether the MCP server is enabled. */
+    /** Whether to auto-start the MCP server on plugin load. Default false — agent tools run in-process regardless. Set true only when an external MCP client needs to connect via `opencode-rag mcp`. */
     enabled: boolean;
 }
 /** Configuration for automatic self-updates. */
 export interface AutoUpdateConfig {
     /** Whether update checking is enabled (defaults to true). */
     enabled: boolean;
+    /** When true, automatically install a newer release on startup (default false). */
+    autoInstall?: boolean;
+    /** Cooldown window (ms) before re-attempting the same version (default 3 600 000 = 1h). */
+    cooldownMs?: number;
+    /** Back off after this many consecutive failures (default 3). */
+    maxConsecutiveFailures?: number;
 }
 /** Configuration for post-retrieval context window optimization (adjacent merge, similarity dedup, file diversity cap). */
 export interface ContextOptimizationConfig {

package/dist/core/config.js

@@ -245,10 +245,13 @@ export const DEFAULT_CONFIG = {
             "- The wiki is git-trackable in `.opencode/` — every edit is a diff",
     },
     mcp: {
-        enabled: true,
+        enabled: false,
     },
     autoUpdate: {
         enabled: true,
+        autoInstall: false,
+        cooldownMs: 3_600_000,
+        maxConsecutiveFailures: 3,
     },
     ui: {
         port: 3210,

package/dist/plugin.js

@@ -22,7 +22,8 @@ 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, getCurrentVersion } from "./core/version-check.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 { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import path from "node:path";
@@ -41,6 +42,8 @@ const mcpServers = new Map();
 const pendingUpdateInfo = new Map();
 /** Workspace directories that have already been prompted about an update this session. */
 const notifiedUpdateDirs = new Set();
+/** Pending "restart needed" notice after a background auto-install. */
+const pendingRestartNotice = new Map();
 /** Guard flag to prevent re-entrant shutdown. */
 let shutdownRegistered = false;
 /** Close all active background indexers and MCP servers, then destroy idle sockets. */
@@ -61,6 +64,7 @@ async function shutdownPluginResources() {
     }
     configCache.clear();
     pendingUpdateInfo.clear();
+    pendingRestartNotice.clear();
     notifiedUpdateDirs.clear();
     destroyAllPooledConnections();
 }
@@ -699,6 +703,16 @@ export function createRagHooks(options) {
                     `they would like you to install it. If they agree, run \`opencode-rag update\` via the bash tool, then tell ` +
                     `them to restart OpenCode to load the new version. Do not mention this notice again.`);
             }
+            // Inject a one-time "restart needed" notice after a background auto-install.
+            // Fires only once per workspace per session, mirroring the notify-only pattern above.
+            const restartInfo = pendingRestartNotice.get(options.worktree);
+            if (restartInfo && !notifiedUpdateDirs.has(options.worktree + ":restart")) {
+                notifiedUpdateDirs.add(options.worktree + ":restart");
+                pendingRestartNotice.delete(options.worktree);
+                output.system.unshift(`OpenCodeRAG was automatically updated from v${restartInfo.fromVersion} to v${restartInfo.toVersion} ` +
+                    `in the background. At the very start of your next response, tell the user the update was installed ` +
+                    `and ask them to restart OpenCode to load the new version. Do not mention this notice again.`);
+            }
             // Inject documentation mode system prompt if enabled
             const docMode = getEffectiveCfg().documentationMode;
             if (docMode?.enabled && docMode.systemPrompt) {
@@ -1161,6 +1175,7 @@ export const ragPlugin = async (input, _options) => {
     // Clean up stale config cache and pending update info for this directory
     configCache.delete(input.directory);
     pendingUpdateInfo.delete(input.directory);
+    pendingRestartNotice.delete(input.directory);
     notifiedUpdateDirs.delete(input.directory);
     // Clean up idle HTTP sockets from previous provider connections
     destroyAllPooledConnections();
@@ -1253,8 +1268,11 @@ export const ragPlugin = async (input, _options) => {
             catch { /* ignore */ }
         }
     }
-    // Auto-start MCP server if enabled (skip in temp dirs / test environments)
-    const mcpCfg = effectiveCfg.mcp ?? { enabled: true };
+    // Auto-start standalone MCP server if enabled (default: off). Agent tools
+    // (search_semantic, get_file_skeleton, find_usages, describe_image) and the
+    // chat.message hook run in-process regardless. Enable only when an external
+    // MCP client connects to `opencode-rag mcp`.
+    const mcpCfg = effectiveCfg.mcp ?? { enabled: false };
     const isTempDir = path.resolve(input.directory).startsWith(tmpdir());
     if (mcpCfg.enabled && !isTempDir) {
         const mcpInstance = startMcpServerProcess(input.directory, logFilePath, logLevel);
@@ -1262,14 +1280,75 @@ export const ragPlugin = async (input, _options) => {
     }
     // Auto-update check (non-blocking, best-effort). On by default; can be
     // disabled via `autoUpdate.enabled: false` in opencode-rag.json. When a newer
-    // release is found it is stored and surfaced as a one-time install prompt via
-    // the system transform hook (see createRagHooks).
+    // release is found it is either surfaced as a one-time install prompt via
+    // the system transform hook (default) or automatically installed in the
+    // background when `autoUpdate.autoInstall: true` is configured.
     const autoUpdateCfg = effectiveCfg.autoUpdate;
     if (autoUpdateCfg?.enabled) {
         const currentVersion = getCurrentVersion();
         checkForUpdate(currentVersion)
             .then((info) => {
-            if (info.updateAvailable) {
+            if (!info.updateAvailable)
+                return;
+            if (autoUpdateCfg?.autoInstall) {
+                // Background auto-install branch (opt-in). Persist a cooldown file
+                // so we don't re-install on every plugin reload or after failures.
+                const cooldownMs = autoUpdateCfg.cooldownMs ?? 3_600_000;
+                const maxFailures = autoUpdateCfg.maxConsecutiveFailures ?? 3;
+                const state = loadAutoUpdateState(storePath);
+                const { attempt, reason } = shouldAttemptInstall(state, info.latestVersion, cooldownMs, maxFailures);
+                if (!attempt) {
+                    appendDebugLog(logFilePath, {
+                        scope: "updater",
+                        message: `Auto-install skipped: ${reason}`,
+                    }, logLevel);
+                    return;
+                }
+                saveAutoUpdateState(storePath, {
+                    lastAttemptAt: Date.now(),
+                    lastAttemptedVersion: info.latestVersion,
+                    lastResult: "failure",
+                    consecutiveFailures: 1,
+                });
+                installLatestUpdate({ verbose: false })
+                    .then((result) => {
+                    if (result.success && result.toVersion && result.toVersion !== currentVersion) {
+                        pendingRestartNotice.set(input.directory, {
+                            fromVersion: currentVersion,
+                            toVersion: result.toVersion,
+                        });
+                        saveAutoUpdateState(storePath, {
+                            lastAttemptAt: Date.now(),
+                            lastAttemptedVersion: info.latestVersion,
+                            lastResult: "success",
+                            consecutiveFailures: 0,
+                        });
+                        appendDebugLog(logFilePath, {
+                            scope: "updater",
+                            message: `Auto-installed v${currentVersion} → v${result.toVersion}`,
+                        }, logLevel);
+                    }
+                    else {
+                        saveAutoUpdateState(storePath, {
+                            lastAttemptAt: Date.now(),
+                            lastAttemptedVersion: info.latestVersion,
+                            lastResult: "success",
+                            consecutiveFailures: 0,
+                        });
+                    }
+                })
+                    .catch(() => {
+                    const existing = loadAutoUpdateState(storePath);
+                    saveAutoUpdateState(storePath, {
+                        lastAttemptAt: Date.now(),
+                        lastAttemptedVersion: info.latestVersion,
+                        lastResult: "failure",
+                        consecutiveFailures: (existing?.consecutiveFailures ?? 0) + 1,
+                    });
+                });
+            }
+            else {
+                // Notify-only: surface as a one-time agent prompt
                 pendingUpdateInfo.set(input.directory, info);
                 appendDebugLog(logFilePath, {
                     scope: "updater",

package/dist/vectorstore/lancedb.d.ts

@@ -30,6 +30,7 @@ export declare class LanceDbStore implements VectorStore {
     private db;
     private table;
     private tableInit;
+    private writeLock;
     /**
      * @param dbPath - Filesystem path to the LanceDB database directory.
      * @param vectorDimension - Dimension of the embedding vectors. Default: 384.

package/dist/vectorstore/lancedb.js

@@ -75,6 +75,7 @@ export class LanceDbStore {
     db = null;
     table = null;
     tableInit = null;
+    writeLock = Promise.resolve(void 0);
     /**
      * @param dbPath - Filesystem path to the LanceDB database directory.
      * @param vectorDimension - Dimension of the embedding vectors. Default: 384.
@@ -184,12 +185,17 @@ export class LanceDbStore {
     async addChunks(chunks) {
         if (chunks.length === 0)
             return;
+        const done = this.writeLock.then(() => this.addChunksInternal(chunks));
+        this.writeLock = done.catch(() => { });
         try {
-            await this.addChunksInternal(chunks);
+            await done;
         }
         catch (err) {
+            this.writeLock = Promise.resolve();
             if (isCorruptionError(err) && await this.tryRepair()) {
-                await this.addChunksInternal(chunks);
+                const retry = this.addChunksInternal(chunks);
+                this.writeLock = retry.catch(() => { });
+                await retry;
                 return;
             }
             throw err;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-rag-plugin",
-  "version": "1.17.2",
+  "version": "1.17.3",
   "description": "OpenCode plugin for local-first RAG-based semantic code search",
   "type": "module",
   "main": "./dist/plugin-entry.js",