opencode-rag-plugin 2.9.3 → 2.10.0

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.
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;