opencode-rag-plugin 2.9.3 → 2.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -59,6 +59,43 @@ function isPidAlive(pid) {
59
59
  * @param options - Configuration for the index pass.
60
60
  * @returns Aggregate statistics for the pass.
61
61
  */
62
+ /** Minimum gap between two regular (non-aggressive) store optimize runs. */
63
+ export const MIN_OPTIMIZE_INTERVAL_MS = 15 * 60 * 1000;
64
+ /** Last time a regular optimize actually ran in this process. */
65
+ let lastOptimizeAt = 0;
66
+ /**
67
+ * Decide whether a regular store optimize may run now, and stamp the attempt.
68
+ *
69
+ * LanceDB's `Table.optimize()` always rewrites the ANN index (it decides the
70
+ * index is stale and rebuilds it), and one IVF_FLAT build is a full,
71
+ * uncompressed copy of the vector column - 12k chunks x 4096 float32 is about
72
+ * 190 MB. The watch loop optimized at the end of EVERY pass, so a busy session
73
+ * left one dead build per pass behind: on 2026-10-26 the store carried 15 builds
74
+ * (2.5 GB) against 380 MB of live data. Optimizing at most every
75
+ * {@link MIN_OPTIMIZE_INTERVAL_MS} bounds that to the builds of the last
76
+ * interval, and the version prune inside the same call reclaims the rest.
77
+ *
78
+ * Aggressive runs (a private temp store during a full rebuild) always return
79
+ * true.
80
+ *
81
+ * @param options - `force` bypasses the throttle; `now` overrides the clock (tests).
82
+ * @returns True when the caller should run the optimize.
83
+ */
84
+ export function optimizeDue(options) {
85
+ const now = options?.now ?? Date.now();
86
+ if (options?.force) {
87
+ lastOptimizeAt = now;
88
+ return true;
89
+ }
90
+ if (now - lastOptimizeAt < MIN_OPTIMIZE_INTERVAL_MS)
91
+ return false;
92
+ lastOptimizeAt = now;
93
+ return true;
94
+ }
95
+ /** Reset the optimize throttle (tests only). */
96
+ export function resetOptimizeThrottle() {
97
+ lastOptimizeAt = 0;
98
+ }
62
99
  export async function runIndexPass(options) {
63
100
  const logger = createLogger(options.logger);
64
101
  const lockPath = path.join(options.storePath, LOCK_FILE);
@@ -170,11 +207,14 @@ async function runIndexPassInner(options, logger) {
170
207
  if (!options.force && manifestStatus === "ok" && Object.keys(manifest.files).length > 0) {
171
208
  try {
172
209
  const storedPaths = await options.store.getFilePaths();
173
- const storedSet = new Set(storedPaths);
210
+ // Case-insensitive on Windows: the store may hold `c:/...` while the
211
+ // manifest keys `C:/...` (path.resolve keeps the drive-letter case).
212
+ // A case-sensitive compare re-indexes every such file on every pass.
213
+ const storedSet = new Set(storedPaths.map((p) => p.toLowerCase()));
174
214
  let removedCount = 0;
175
215
  for (const [p, entry] of Object.entries(manifest.files)) {
176
216
  // Path missing from store entirely (aborted before store finished)
177
- if (entry.chunkCount > 0 && !storedSet.has(p)) {
217
+ if (entry.chunkCount > 0 && !storedSet.has(p.toLowerCase())) {
178
218
  delete manifest.files[p];
179
219
  removedCount++;
180
220
  }
@@ -1016,7 +1056,7 @@ async function runIndexPassInner(options, logger) {
1016
1056
  if (optimizeInterval > 0 && windowCount % optimizeInterval === 0) {
1017
1057
  const storedInWindow = await prevStore;
1018
1058
  prevStore = null;
1019
- if (storedInWindow > 0) {
1059
+ if (storedInWindow > 0 && optimizeDue({ force: Boolean(tempStorePath) })) {
1020
1060
  logger.info("Optimizing vector store (mid-run compaction, pruning old versions)...");
1021
1061
  await effectiveStore.optimize?.(tempStorePath
1022
1062
  ? { aggressive: true, skipIndex: true, logger: logger.warn }
@@ -1191,15 +1231,23 @@ async function runIndexPassInner(options, logger) {
1191
1231
  // swapped-in store is private to this process. Skipped when the rebuild did
1192
1232
  // not promote (the old store is untouched and its handle may be closed).
1193
1233
  if (!aborted() && !keepPreviousIndexState) {
1194
- logger.info("Optimizing vector store (compacting fragments, pruning old versions)...");
1195
- const optimizeStart = Date.now();
1196
- try {
1197
- const optimizeTarget = tempStorePath ? options.store : effectiveStore;
1198
- await optimizeTarget.optimize?.(tempStorePath ? { aggressive: true, logger: logger.warn } : { logger: logger.warn });
1199
- logger.info(`Vector store optimized in ${((Date.now() - optimizeStart) / 1000).toFixed(1)}s`);
1234
+ // Every optimize rebuilds the ANN index (a ~190 MB vector copy at 4096
1235
+ // dims), so passes within the throttle window skip it; the next due pass
1236
+ // compacts and prunes, which also reclaims the skipped builds.
1237
+ if (!optimizeDue({ force: Boolean(tempStorePath) })) {
1238
+ logger.debug(`Skipping vector store optimize (throttled: < ${MIN_OPTIMIZE_INTERVAL_MS / 60000} min since the last run)`);
1200
1239
  }
1201
- catch (err) {
1202
- logger.warn(`Vector store optimization failed: ${err.message}`);
1240
+ else {
1241
+ logger.info("Optimizing vector store (compacting fragments, pruning old versions)...");
1242
+ const optimizeStart = Date.now();
1243
+ try {
1244
+ const optimizeTarget = tempStorePath ? options.store : effectiveStore;
1245
+ await optimizeTarget.optimize?.(tempStorePath ? { aggressive: true, logger: logger.warn } : { logger: logger.warn });
1246
+ logger.info(`Vector store optimized in ${((Date.now() - optimizeStart) / 1000).toFixed(1)}s`);
1247
+ }
1248
+ catch (err) {
1249
+ logger.warn(`Vector store optimization failed: ${err.message}`);
1250
+ }
1203
1251
  }
1204
1252
  }
1205
1253
  // Persist description cache
package/dist/plugin.d.ts CHANGED
@@ -9,23 +9,28 @@ import { type RagConfig } from "./core/config.js";
9
9
  import { createEmbedder } from "./embedder/factory.js";
10
10
  import { retrieve } from "./retriever/retriever.js";
11
11
  /**
12
- * Load the RAG configuration for a directory, searching in order:
13
- * opencode-rag.json, .opencode/opencode-rag.json, .opencode/rag.json.
12
+ * Load the RAG configuration for a directory: DEFAULT_CONFIG, then the global
13
+ * layer (`~/.config/opencode/opencode-rag.json`), then the first workspace
14
+ * config found (`opencode-rag.json`, `.opencode/opencode-rag.json`,
15
+ * `.opencode/rag.json`).
14
16
  *
15
- * The result is cached per directory and re-read whenever the config file
16
- * changes on disk, so an edited API key or baseUrl does not require a restart.
17
+ * The result is cached per directory and re-read whenever either config file
18
+ * changes on disk, so an edited API key, baseUrl, or global `shellGuard` switch
19
+ * does not require a restart.
17
20
  */
18
21
  export declare function getConfig(directory: string): Promise<RagConfig>;
19
22
  /**
20
- * Re-read a workspace's config file when it changed on disk.
23
+ * Re-read a workspace's config when either the global or workspace file
24
+ * changed on disk.
21
25
  *
22
26
  * Only a config that this module loaded from a file is refreshed — the cache
23
- * entry is the proof that the file is the source of truth for that workspace.
24
- * A caller that supplies its own configuration (tests, embedders) keeps it.
27
+ * entry is the proof that the files are the source of truth for that
28
+ * workspace. A caller that supplies its own configuration (tests, embedders)
29
+ * keeps it.
25
30
  *
26
31
  * Synchronous on purpose: this runs on the hot path (every effective-config
27
- * lookup) and `loadConfig` is synchronous. The pluggable-chunker side effect
28
- * (`loadChunkersFromConfig`) mutates a global registry and is therefore
32
+ * lookup) and `loadWorkspaceConfig` is synchronous. The pluggable-chunker side
33
+ * effect (`loadChunkersFromConfig`) mutates a global registry and is therefore
29
34
  * re-applied asynchronously — it is not needed by the embedding path this
30
35
  * refresh exists to fix.
31
36
  *
package/dist/plugin.js CHANGED
@@ -6,7 +6,7 @@
6
6
  import { tool } from "@opencode-ai/plugin/tool";
7
7
  import { CODE_SEARCH_FILTER } from "./core/interfaces.js";
8
8
  import { normalizeFileExtensions } from "./core/filters.js";
9
- import { loadConfig, findConfigFile, DEFAULT_CONFIG, resolveLogConfig, persistProbedDimension } from "./core/config.js";
9
+ import { loadWorkspaceConfig, resolveConfigPaths, findConfigFile, DEFAULT_CONFIG, resolveLogConfig, persistProbedDimension } from "./core/config.js";
10
10
  import { createEmbedder, probeEmbeddingDimension } from "./embedder/factory.js";
11
11
  import { readStoreDimension } from "./vectorstore/lancedb.js";
12
12
  import { createDescriptionProvider } from "./describer/factory.js";
@@ -234,24 +234,39 @@ function configFileMtime(configPath) {
234
234
  return -1;
235
235
  }
236
236
  }
237
+ /** Identity of the config layers (global + workspace paths and mtimes). */
238
+ function configStamp(paths) {
239
+ return [
240
+ paths.global ? `${paths.global}:${configFileMtime(paths.global)}` : "",
241
+ paths.workspace ? `${paths.workspace}:${configFileMtime(paths.workspace)}` : "",
242
+ ].join("|");
243
+ }
237
244
  /**
238
- * Load the RAG configuration for a directory, searching in order:
239
- * opencode-rag.json, .opencode/opencode-rag.json, .opencode/rag.json.
245
+ * Load the RAG configuration for a directory: DEFAULT_CONFIG, then the global
246
+ * layer (`~/.config/opencode/opencode-rag.json`), then the first workspace
247
+ * config found (`opencode-rag.json`, `.opencode/opencode-rag.json`,
248
+ * `.opencode/rag.json`).
240
249
  *
241
- * The result is cached per directory and re-read whenever the config file
242
- * changes on disk, so an edited API key or baseUrl does not require a restart.
250
+ * The result is cached per directory and re-read whenever either config file
251
+ * changes on disk, so an edited API key, baseUrl, or global `shellGuard` switch
252
+ * does not require a restart.
243
253
  */
244
254
  export async function getConfig(directory) {
245
- const configPath = findConfigFile(directory);
246
- const mtimeMs = configFileMtime(configPath);
255
+ const paths = resolveConfigPaths(directory);
256
+ const stamp = configStamp(paths);
247
257
  const cached = configCache.get(directory);
248
- if (cached && cached.configPath === configPath && cached.mtimeMs === mtimeMs) {
258
+ if (cached && cached.stamp === stamp) {
249
259
  return cached.cfg;
250
260
  }
251
- if (configPath) {
261
+ if (paths.global || paths.workspace) {
252
262
  try {
253
- const cfg = loadConfig(configPath);
254
- await loadChunkersFromConfig(cfg, path.dirname(configPath));
263
+ const cfg = loadWorkspaceConfig(directory);
264
+ const baseDir = paths.workspace
265
+ ? path.dirname(paths.workspace)
266
+ : paths.global
267
+ ? path.dirname(paths.global)
268
+ : directory;
269
+ await loadChunkersFromConfig(cfg, baseDir);
255
270
  const hadKey = !!cfg.embedding.apiKey;
256
271
  resolveApiKey(cfg, directory);
257
272
  if (!hadKey && cfg.embedding.apiKey) {
@@ -260,13 +275,13 @@ export async function getConfig(directory) {
260
275
  message: `Resolved embedding API key from ${process.env.OPENAI_API_KEY ? "OPENAI_API_KEY env var" : "OpenCode provider config"}`,
261
276
  });
262
277
  }
263
- configCache.set(directory, { cfg, configPath, mtimeMs });
278
+ configCache.set(directory, { cfg, stamp });
264
279
  return cfg;
265
280
  }
266
281
  catch (err) {
267
282
  appendDebugLog(path.resolve(directory, ".opencode", "opencode-rag.log"), {
268
283
  scope: "config",
269
- message: `Failed to load config from ${configPath}`,
284
+ message: `Failed to load config from ${paths.workspace ?? paths.global}`,
270
285
  error: err,
271
286
  });
272
287
  }
@@ -274,19 +289,21 @@ export async function getConfig(directory) {
274
289
  // Deep-clone so a later resolveApiKey() cannot mutate the shared
275
290
  // DEFAULT_CONFIG singleton.
276
291
  const cfg = structuredClone(DEFAULT_CONFIG);
277
- configCache.set(directory, { cfg, configPath, mtimeMs });
292
+ configCache.set(directory, { cfg, stamp });
278
293
  return cfg;
279
294
  }
280
295
  /**
281
- * Re-read a workspace's config file when it changed on disk.
296
+ * Re-read a workspace's config when either the global or workspace file
297
+ * changed on disk.
282
298
  *
283
299
  * Only a config that this module loaded from a file is refreshed — the cache
284
- * entry is the proof that the file is the source of truth for that workspace.
285
- * A caller that supplies its own configuration (tests, embedders) keeps it.
300
+ * entry is the proof that the files are the source of truth for that
301
+ * workspace. A caller that supplies its own configuration (tests, embedders)
302
+ * keeps it.
286
303
  *
287
304
  * Synchronous on purpose: this runs on the hot path (every effective-config
288
- * lookup) and `loadConfig` is synchronous. The pluggable-chunker side effect
289
- * (`loadChunkersFromConfig`) mutates a global registry and is therefore
305
+ * lookup) and `loadWorkspaceConfig` is synchronous. The pluggable-chunker side
306
+ * effect (`loadChunkersFromConfig`) mutates a global registry and is therefore
290
307
  * re-applied asynchronously — it is not needed by the embedding path this
291
308
  * refresh exists to fix.
292
309
  *
@@ -300,26 +317,31 @@ export function refreshConfig(directory, fallback) {
300
317
  // No file-backed config for this workspace — the caller's config stands.
301
318
  return fallback;
302
319
  }
303
- const configPath = findConfigFile(directory);
304
- const mtimeMs = configFileMtime(configPath);
305
- if (cached.configPath === configPath && cached.mtimeMs === mtimeMs) {
320
+ const paths = resolveConfigPaths(directory);
321
+ const stamp = configStamp(paths);
322
+ if (cached.stamp === stamp) {
306
323
  return cached.cfg;
307
324
  }
308
- if (!configPath) {
309
- // The config file was removed — keep serving the last known config.
325
+ if (!paths.global && !paths.workspace) {
326
+ // The config files were removed — keep serving the last known config.
310
327
  return cached.cfg;
311
328
  }
312
329
  try {
313
- const cfg = loadConfig(configPath);
330
+ const cfg = loadWorkspaceConfig(directory);
314
331
  resolveApiKey(cfg, directory);
315
- void loadChunkersFromConfig(cfg, path.dirname(configPath)).catch(() => { });
316
- configCache.set(directory, { cfg, configPath, mtimeMs });
332
+ const baseDir = paths.workspace
333
+ ? path.dirname(paths.workspace)
334
+ : paths.global
335
+ ? path.dirname(paths.global)
336
+ : directory;
337
+ void loadChunkersFromConfig(cfg, baseDir).catch(() => { });
338
+ configCache.set(directory, { cfg, stamp });
317
339
  return cfg;
318
340
  }
319
341
  catch (err) {
320
342
  appendDebugLog(path.resolve(directory, ".opencode", "opencode-rag.log"), {
321
343
  scope: "config",
322
- message: `Failed to reload config from ${configPath}`,
344
+ message: `Failed to reload config from ${paths.workspace ?? paths.global}`,
323
345
  error: err,
324
346
  });
325
347
  return cached.cfg;
@@ -0,0 +1,157 @@
1
+ /**
2
+ * @fileoverview Optional shell-command safety guard.
3
+ *
4
+ * Every `shell`/`bash` command is classified by a local decision model
5
+ * (tev1 via Ollama, or Clef/Jev via llama-swap — all speak the same
6
+ * `/v1/systemone` protocol) before it runs. A command whose `destructive` or
7
+ * `malicious` probability reaches the configured threshold is escalated to
8
+ * OpenCode's permission prompt (V2 `permission.hook("evaluate")` sets
9
+ * `effect = "ask"`); a clean command executes unchanged.
10
+ *
11
+ * Design constraints learned from the OpenCode V2 plugin API:
12
+ * - The V1 `tool.execute.before` hook cannot block a call (throwing is
13
+ * swallowed by the adapter), so the guard uses the permission `evaluate`
14
+ * hook, which runs AFTER rules are evaluated and BEFORE the action runs.
15
+ * - That hook runs for `allow` and `ask` decisions but not for `deny`.
16
+ * - The check sits on the critical path of every shell command: the timeout
17
+ * is short (default 10 s), verdicts are cached, and failures default to
18
+ * fail-open (`onError: "allow"`).
19
+ *
20
+ * @see https://opencode.ai/v2/docs/build/plugins (Permissions)
21
+ */
22
+ import type { DecisionConfig, LoggingConfig, RagConfig, ShellGuardConfig } from "../core/config.js";
23
+ import type { DecisionProvider, DecisionQuestion, DecisionResult } from "../core/interfaces.js";
24
+ /** Tool names whose command text is vetted (V2 `shell`, V1-style `bash`). */
25
+ export declare const SHELL_GUARD_TOOL_NAMES: readonly string[];
26
+ /**
27
+ * Questions asked of the decision model for every command.
28
+ *
29
+ * Two `noul` questions drive the pass/fail decision (either one reaching the
30
+ * threshold flags the command); the `choice` question only labels the risk so
31
+ * the confirmation prompt explains *why* it was flagged.
32
+ */
33
+ export declare const SHELL_GUARD_QUESTIONS: readonly DecisionQuestion[];
34
+ /** Live configuration resolved for one guard evaluation. */
35
+ export interface ShellGuardRuntimeConfig {
36
+ guard: ShellGuardConfig;
37
+ decision: DecisionConfig;
38
+ logging: LoggingConfig;
39
+ }
40
+ /** Outcome of classifying a single shell command. */
41
+ export interface ShellGuardVerdict {
42
+ /** True when the command must be confirmed before it runs. */
43
+ flagged: boolean;
44
+ /** Probability that the command is destructive (0-1). */
45
+ destructive: number;
46
+ /** Probability that the command is malicious (0-1). */
47
+ malicious: number;
48
+ /** Risk label chosen by the model (`none` when clean). */
49
+ category: string;
50
+ /** Human-readable explanation for the permission prompt. */
51
+ reason: string;
52
+ /** Decision provider name (e.g. "ollama"). */
53
+ provider: string;
54
+ /** Decision model name (e.g. "tev1:0.8b" / "Clef-Flash"). */
55
+ model: string;
56
+ /** Classification duration in ms. */
57
+ latencyMs: number;
58
+ /** True when the verdict was served from the cache. */
59
+ cached: boolean;
60
+ /** True when no config was available (guard disabled). */
61
+ skipped?: boolean;
62
+ /** Classifier failure (timeout / endpoint error); `flagged` follows `onError`. */
63
+ error?: string;
64
+ }
65
+ /** Injectable dependencies (tests provide a fake provider and clock). */
66
+ export interface ShellGuardDeps {
67
+ /** Resolve the live runtime config; `undefined` disables the guard. */
68
+ getConfig?: () => ShellGuardRuntimeConfig | undefined;
69
+ /** Provider factory override (defaults to the decision-model factory). */
70
+ createProvider?: (config: DecisionConfig) => DecisionProvider;
71
+ /** Clock override for cache tests. */
72
+ now?: () => number;
73
+ }
74
+ /** Case-insensitive test for a shell-execution tool name. */
75
+ export declare function isShellToolName(name: string | undefined): boolean;
76
+ /**
77
+ * Truncate an oversized command for the decision model.
78
+ *
79
+ * The model's effective context is small (~2k tokens), so keep the head and
80
+ * the tail — destructive payloads usually appear at one end — and mark the
81
+ * omission explicitly.
82
+ */
83
+ export declare function buildShellGuardState(command: string, maxChars?: number): string;
84
+ /**
85
+ * Convert raw decision answers into a guard verdict.
86
+ *
87
+ * Exported for tests; production callers use {@link ShellGuard.evaluate}.
88
+ */
89
+ export declare function verdictFromDecisionResult(result: DecisionResult, opts: {
90
+ threshold: number;
91
+ provider: string;
92
+ model: string;
93
+ latencyMs: number;
94
+ cached?: boolean;
95
+ }): ShellGuardVerdict;
96
+ /** Build the message shown in the permission prompt. */
97
+ export declare function formatShellGuardReason(verdict: ShellGuardVerdict): string;
98
+ /**
99
+ * Classify shell commands and cache verdicts.
100
+ *
101
+ * One instance lives for the lifetime of the plugin registration. Provider
102
+ * instances are re-created only when the endpoint/model signature changes, so
103
+ * a config edit (e.g. switching tev1 → Clef-Flash) takes effect without a
104
+ * restart.
105
+ */
106
+ export declare class ShellGuard {
107
+ private readonly deps;
108
+ private readonly cache;
109
+ private readonly now;
110
+ private readonly createProvider;
111
+ private providerState;
112
+ constructor(deps?: ShellGuardDeps);
113
+ /**
114
+ * Classify one command.
115
+ *
116
+ * Returns a non-flagged verdict when the guard is disabled or when the
117
+ * classifier fails under `onError: "allow"` (fail-open). Never throws.
118
+ */
119
+ evaluate(command: string, abort?: AbortSignal): Promise<ShellGuardVerdict>;
120
+ /** Reset cached verdicts (tests / config reload). */
121
+ clearCache(): void;
122
+ private getProvider;
123
+ /**
124
+ * Build a verdict from a (possibly cached) classifier outcome using the
125
+ * CURRENT threshold and `onError` policy — editing either in
126
+ * `opencode-rag.json` takes effect on the next command even while cached
127
+ * probabilities are still valid.
128
+ */
129
+ private verdictFromOutcome;
130
+ private store;
131
+ private log;
132
+ }
133
+ /**
134
+ * Resolve the guard's live config from a loaded `RagConfig`.
135
+ *
136
+ * Returns `undefined` when the guard is disabled — callers use that as the
137
+ * single gate. `decision.enabled` deliberately does NOT gate the guard: the
138
+ * guard has its own switch and may run against a backend the `make_decision`
139
+ * tool does not expose.
140
+ *
141
+ * @param cfg - Fully merged workspace configuration.
142
+ * @param directory - Workspace root; when given, the log file path is
143
+ * resolved against it (the plugin's process cwd is not necessarily the
144
+ * workspace).
145
+ */
146
+ export declare function resolveShellGuardRuntimeConfig(cfg: RagConfig, directory?: string): ShellGuardRuntimeConfig | undefined;
147
+ /**
148
+ * Build a config reader that re-reads the global + workspace config when
149
+ * either changes.
150
+ *
151
+ * A shell command is classified at most a few seconds apart, so the stat
152
+ * check is cheap; re-reading makes an edit (global enabled flag, threshold,
153
+ * model) take effect without restarting OpenCode.
154
+ */
155
+ export declare function createShellGuardConfigReader(directory: string): () => ShellGuardRuntimeConfig | undefined;
156
+ /** Convenience factory used by the V2 adapter. */
157
+ export declare function createShellGuardForDirectory(directory: string): ShellGuard;