opencode-rag-plugin 2.9.2 → 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/ReadMe.md CHANGED
@@ -50,6 +50,7 @@ workspace, and `opencode-rag update` upgrades to a newer release.
50
50
  | **Hybrid search** | Vector similarity + TF×IDF keyword fusion — the keyword index is repaired from the store whenever it drifts behind it, so the BM25 half never covers only part of the corpus |
51
51
  | **Retrieval calibration** | `opencode-rag eval:tune` sweeps the fusion weights against the labelled golden set and reports (or writes) the best configuration for your embedder and corpus |
52
52
  | **Decision model** | Local [tev1](https://ollama.com/library/tev1) classification — `make_decision` labels, routes, and scores short text with probabilities (40–150 ms warm); optional pre-ask routing so the agent asks fewer questions |
53
+ | **Shell guard** | Optional pre-execution vetting of every `shell`/`bash` command by the local decision model — flagged commands ask for confirmation, clean ones run normally (fail-open by default) |
53
54
  | **OpenCode plugin** | Auto-inject context, read-tool override, TUI settings, Ctrl+Enter to add RAG context, MCP registration on `init` |
54
55
  | **Incremental indexing** | File-hash manifest, background watcher, auto-rebuild on corruption |
55
56
  | **Privacy-first** | All processing stays local (when using Ollama) |
@@ -77,7 +78,7 @@ Launch with `opencode-rag ui`. See [Web UI documentation](doc/webui.md) for deta
77
78
  |---|---|
78
79
  | [Architecture](doc/architecture.md) | Module design, data flow, tech stack |
79
80
  | [Installation](doc/installation.md) | Full install guide, global setup, uninstall |
80
- | [Configuration](doc/configuration.md) | All options: embedding, indexing, retrieval, description, image description, decision, plugin |
81
+ | [Configuration](doc/configuration.md) | All options: embedding, indexing, retrieval, description, image description, decision, shell guard, plugin |
81
82
  | [Chunking](doc/chunking.md) | Language matrix, adding new chunkers, custom chunkers |
82
83
  | [Embedding](doc/embedding.md) | Providers, model recommendations, proxy, dimension probing |
83
84
  | [Retrieval](doc/retrieval.md) | Pipeline, hybrid search, score fusion, caching |
@@ -146,6 +147,30 @@ ollama pull tev1:4b # 4.4 GB, more accurate — recommended when scoring
146
147
 
147
148
  `opencode-rag decide` exposes the same engine from the CLI, and `init` creates a dedicated `make-decision` agent skill. See [Plugin documentation](doc/plugin.md#make_decision) and [Configuration](doc/configuration.md#decision).
148
149
 
150
+ ## Shell Guard (Optional)
151
+
152
+ The same local decision model can vet **every shell command before it runs**. With `shellGuard.enabled: true`, each `shell`/`bash` call is classified for destructive and malicious intent; a command whose `p(destructive)` or `p(malicious)` reaches the threshold is escalated to OpenCode's confirmation prompt with the full verdict — otherwise it executes unchanged.
153
+
154
+ ```json
155
+ {
156
+ "shellGuard": {
157
+ "enabled": true,
158
+ "threshold": 0.5,
159
+ "timeoutMs": 10000,
160
+ "onError": "allow"
161
+ }
162
+ }
163
+ ```
164
+
165
+ - **Off by default** — enabling adds one local model call to the critical path of every shell command.
166
+ - **Machine-wide** — put the block in `~/.config/opencode/opencode-rag.json` (the global layer, see [Configuration](doc/configuration.md#config-file-discovery)) and every workspace inherits it; a workspace config can still override or disable it.
167
+ - **Fail-open by default** (`onError: "allow"`): if the classifier is down or times out, the command runs and a warning is logged. Set `onError: "ask"` to require confirmation instead.
168
+ - **Verdict cache** (10 min, 256 entries): repeated identical commands are answered instantly; the key includes the provider/model, so switching models invalidates it, and cached probabilities are re-scored against the current threshold on every call.
169
+ - **Config edits apply without a restart** — the guard re-reads `opencode-rag.json` when it changes.
170
+ - **Backend** defaults to the `decision` section, and any `/v1/systemone` endpoint works — e.g. llama-swap with `"baseUrl": "http://localhost:11437", "model": "Clef-Flash"`.
171
+
172
+ Every verdict is logged under `scope: shell.guard`, so you can tune the threshold against real commands. See [Configuration](doc/configuration.md#shellguard) and [Plugin documentation](doc/plugin.md#shell-guard-command-vetting).
173
+
149
174
  ## Image Indexing
150
175
 
151
176
  OpenCodeRAG can index image files (PNG, JPEG, WebP, etc.) by sending them to a vision-capable LLM and storing the generated text descriptions as searchable vector chunks. This makes visual assets discoverable via natural language queries (e.g., "login screen screenshot", "architecture diagram").
@@ -326,7 +351,7 @@ Retrieval quality has its own harness: `opencode-rag eval:gate` runs the labelle
326
351
 
327
352
  ## Privacy & Security
328
353
 
329
- **100% local by default.** By default, embeddings are generated locally via Ollama. The vector database stays in your project directory. **No source code or embeddings leave your machine** unless you explicitly configure to use a third-party API.
354
+ **100% local by default.** By default, embeddings are generated locally via Ollama. The vector database stays in your project directory. **No source code or embeddings leave your machine** unless you explicitly configure to use a third-party API. The optional [Shell Guard](#shell-guard-optional) likewise sends command text only to the decision-model endpoint you configure (local Ollama or a local proxy).
330
355
 
331
356
  ## License
332
357
 
@@ -657,6 +657,13 @@ export function generateDefaultConfigJson(tuning, existingConfigRaw) {
657
657
  keepAlive: DEFAULT_CONFIG.decision.keepAlive,
658
658
  routeBeforeAsking: DEFAULT_CONFIG.decision.routeBeforeAsking,
659
659
  },
660
+ shellGuard: {
661
+ enabled: DEFAULT_CONFIG.shellGuard.enabled,
662
+ threshold: DEFAULT_CONFIG.shellGuard.threshold,
663
+ timeoutMs: DEFAULT_CONFIG.shellGuard.timeoutMs,
664
+ onError: DEFAULT_CONFIG.shellGuard.onError,
665
+ cacheTtlMs: DEFAULT_CONFIG.shellGuard.cacheTtlMs,
666
+ },
660
667
  description: {
661
668
  enabled: DEFAULT_CONFIG.description.enabled,
662
669
  provider: DEFAULT_CONFIG.description.provider,
@@ -11,7 +11,7 @@
11
11
  */
12
12
  import path from "node:path";
13
13
  import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, copyFileSync } from "node:fs";
14
- import { loadConfig, findConfigFile } from "../../core/config.js";
14
+ import { loadConfig, findConfigFile, loadWorkspaceConfig, configuredSections } from "../../core/config.js";
15
15
  import { checkProviderHealth, pullOllamaModels } from "../../embedder/health.js";
16
16
  import { destroyAllPooledConnections } from "../../embedder/http.js";
17
17
  import { c } from "../format.js";
@@ -327,8 +327,11 @@ export async function runWorkspaceInit(options = {}) {
327
327
  ? null
328
328
  : (async () => {
329
329
  console.log(`\n${c.heading("Checking provider connectivity...")}\n`);
330
- const ragConfig = loadConfig(configPath);
331
- return checkProviderHealth(ragConfig);
330
+ // Effective config (global < workspace) and the sections the user
331
+ // actually configured: models that are merely on by default are
332
+ // never probed or offered for `ollama pull`.
333
+ const ragConfig = loadWorkspaceConfig(cwd);
334
+ return checkProviderHealth(ragConfig, configuredSections(cwd));
332
335
  })();
333
336
  const installPromise = options.skipInstall
334
337
  ? null
@@ -346,7 +349,7 @@ export async function runWorkspaceInit(options = {}) {
346
349
  }
347
350
  const missingOllama = results.filter((r) => r.status === "missing" && r.provider === "ollama");
348
351
  if (missingOllama.length > 0) {
349
- const ragConfig = loadConfig(configPath);
352
+ const ragConfig = loadWorkspaceConfig(cwd);
350
353
  const pullEntries = missingOllama.map((r) => {
351
354
  if (r.type === "embedding") {
352
355
  return { model: r.model, baseUrl: ragConfig.embedding.baseUrl, proxy: ragConfig.embedding.proxy };
@@ -3,7 +3,7 @@
3
3
  * creates embedder, vector store, keyword index, and description provider.
4
4
  */
5
5
  import path from "node:path";
6
- import { loadConfig, findConfigFile, resolveLogConfig, DEFAULT_CONFIG } from "./config.js";
6
+ import { loadConfig, loadWorkspaceConfig, resolveConfigPaths, resolveLogConfig } from "./config.js";
7
7
  import { resolveApiKey } from "./resolve-api-key.js";
8
8
  import { loadChunkersFromConfig } from "../chunker/loader.js";
9
9
  import { createEmbedder, probeEmbeddingDimension } from "../embedder/factory.js";
@@ -63,23 +63,26 @@ async function loadKeywordIndex(storePath) {
63
63
  export async function resolveRagContext(opts = {}) {
64
64
  const workDir = opts.cwd ?? process.cwd();
65
65
  let configPath;
66
+ let cfg;
66
67
  if (opts.configPath) {
67
68
  configPath = path.resolve(workDir, opts.configPath);
68
- }
69
- else {
70
- configPath = findConfigFile(workDir);
71
- }
72
- let cfg;
73
- if (configPath) {
74
69
  cfg = loadConfig(configPath);
75
70
  resolveApiKey(cfg, workDir);
76
71
  await loadChunkersFromConfig(cfg, path.dirname(configPath));
77
72
  }
78
73
  else {
79
- // Deep-clone so resolveApiKey (below) cannot mutate the shared
80
- // DEFAULT_CONFIG singleton.
81
- cfg = structuredClone(DEFAULT_CONFIG);
74
+ // Defaults < global (~/.config/opencode/opencode-rag.json) < workspace.
75
+ const paths = resolveConfigPaths(workDir);
76
+ configPath = paths.workspace;
77
+ cfg = loadWorkspaceConfig(workDir);
82
78
  resolveApiKey(cfg, workDir);
79
+ const baseDir = paths.workspace
80
+ ? path.dirname(paths.workspace)
81
+ : paths.global
82
+ ? path.dirname(paths.global)
83
+ : undefined;
84
+ if (baseDir)
85
+ await loadChunkersFromConfig(cfg, baseDir);
83
86
  }
84
87
  const logFilePath = path.resolve(workDir, resolveLogConfig(cfg).logFilePath);
85
88
  const embedder = createEmbedder(cfg);
@@ -32,6 +32,17 @@ export interface AutoIndexConfig {
32
32
  /** Change-detection backend: "chokidar" (FS events, default) or "git" (poll-based). */
33
33
  watcher?: WatcherBackend;
34
34
  }
35
+ /** Handling of long-running shell commands in OpenCode sessions. */
36
+ export interface OpenCodeShellConfig {
37
+ /** Inject guidance telling the agent to background long commands (default true). */
38
+ backgroundGuidance?: boolean;
39
+ /** Threshold (ms) above which a command is "long" (default 30000). */
40
+ longRunningThresholdMs?: number;
41
+ /** Default foreground timeout (ms) to recommend for shell calls (default 120000). */
42
+ foregroundTimeoutMs?: number;
43
+ /** Record a quirk when a foreground command exceeds the threshold (default true). */
44
+ captureLongRunningQuirk?: boolean;
45
+ }
35
46
  /** Behavior when a read tool query returns no results. */
36
47
  export type ReadNoResultsBehavior = "hint" | "empty" | "error";
37
48
  /** Supported file-change watcher backends. */
@@ -199,6 +210,56 @@ export interface DecisionConfig {
199
210
  /** Base delay in ms between retries (exponential backoff). */
200
211
  retryBaseDelayMs?: number;
201
212
  }
213
+ /**
214
+ * Configuration for the optional shell-command safety guard.
215
+ *
216
+ * Every `shell`/`bash` command is classified by a local decision model
217
+ * (tev1 / Clef / Jev via `/v1/systemone`) before it runs. A command whose
218
+ * `destructive` or `malicious` probability reaches `threshold` is escalated to
219
+ * OpenCode's permission prompt; a clean command executes unchanged.
220
+ *
221
+ * The guard reuses the `decision` backend unless `provider`/`baseUrl`/`model`
222
+ * override it here. It is applied through OpenCode V2's permission
223
+ * `evaluate` hook, so it needs no rule changes in `opencode.json`.
224
+ */
225
+ export interface ShellGuardConfig {
226
+ /**
227
+ * Master gate. Default false — the guard is opt-in because every shell
228
+ * command then waits for the local decision model.
229
+ */
230
+ enabled: boolean;
231
+ /** Decision provider override (defaults to `decision.provider`). */
232
+ provider?: string;
233
+ /** Endpoint override (defaults to `decision.baseUrl`). */
234
+ baseUrl?: string;
235
+ /** Model override (defaults to `decision.model`). */
236
+ model?: string;
237
+ /**
238
+ * Flag a command when `p(destructive)` or `p(malicious)` reaches this
239
+ * probability (0-1). Default 0.5. Lower = more prompts; tune against the
240
+ * `shell.guard` debug-log lines.
241
+ */
242
+ threshold: number;
243
+ /**
244
+ * Abort a classification after this many ms and apply `onError`. Default
245
+ * 10000. Kept short because the check sits on the critical path of every
246
+ * shell command.
247
+ */
248
+ timeoutMs: number;
249
+ /**
250
+ * What to do when the classifier fails (timeout, endpoint down, malformed
251
+ * answer). `"allow"` (default) executes the command and logs a warning;
252
+ * `"ask"` escalates to the confirmation prompt.
253
+ */
254
+ onError?: "allow" | "ask";
255
+ /**
256
+ * Verdict cache TTL in ms. Default 600000 (10 min). 0 disables the cache.
257
+ * Repeated identical commands are answered instantly.
258
+ */
259
+ cacheTtlMs: number;
260
+ /** Maximum cached verdicts before the oldest are evicted. Default 256. */
261
+ maxCacheEntries?: number;
262
+ }
202
263
  export interface UiConfig {
203
264
  /** HTTP port for the UI server. */
204
265
  port: number;
@@ -604,6 +665,8 @@ export interface RagConfig {
604
665
  injectSystemPrompt?: boolean;
605
666
  /** Whether to grant the read-only RAG tools to the built-in `explore` agent (default true). */
606
667
  exploreAgentTools?: boolean;
668
+ /** Handling of long-running shell commands (backgrounding guidance + measurement). */
669
+ shell?: OpenCodeShellConfig;
607
670
  };
608
671
  /** Custom chunker module registrations. */
609
672
  chunkers?: ChunkerConfig[];
@@ -638,6 +701,8 @@ export interface RagConfig {
638
701
  imageDescription?: ImageDescriptionConfig;
639
702
  /** Decision-model (tev1) config for the `make_decision` tool. */
640
703
  decision?: DecisionConfig;
704
+ /** Optional shell-command safety guard (decision-model vetting + confirmation prompt). */
705
+ shellGuard?: ShellGuardConfig;
641
706
  /** Automated documentation mode config. */
642
707
  documentationMode?: DocumentationModeConfig;
643
708
  /** Wiki mode config that instructs the AI agent to maintain a persistent knowledge wiki. */
@@ -694,8 +759,54 @@ export declare const CONFIG_FILE_CANDIDATES: string[];
694
759
  * @returns The absolute path to the config file, or undefined if none found.
695
760
  */
696
761
  export declare function findConfigFile(directory: string): string | undefined;
697
- /** Load and parse a JSON config file, deep-merge with defaults, optionally validate. */
762
+ /**
763
+ * Resolve the machine-wide config file path.
764
+ *
765
+ * `$XDG_CONFIG_HOME/opencode/opencode-rag.json`, falling back to
766
+ * `~/.config/opencode/opencode-rag.json`. The global file is a BASE layer:
767
+ * every workspace config is merged on top of it, so machine-wide defaults
768
+ * (e.g. `shellGuard.enabled`) do not need to be repeated per project.
769
+ */
770
+ export declare function globalConfigPath(envVars?: NodeJS.ProcessEnv, homeDir?: string): string;
771
+ /** Return the global config path when that file exists. */
772
+ export declare function findGlobalConfigFile(envVars?: NodeJS.ProcessEnv, homeDir?: string): string | undefined;
773
+ /** Config layers that apply to a workspace (lowest precedence first). */
774
+ export declare function resolveConfigPaths(directory: string): {
775
+ global?: string;
776
+ workspace?: string;
777
+ };
778
+ /**
779
+ * Load and parse a JSON config file, deep-merge with defaults, optionally validate.
780
+ *
781
+ * This is the single-file loader: the given file is authoritative. Workspace
782
+ * loading with the global base layer goes through {@link loadWorkspaceConfig}.
783
+ */
698
784
  export declare function loadConfig(filePath: string, validate?: boolean): RagConfig;
785
+ /**
786
+ * Load several config files, later files overriding earlier ones.
787
+ *
788
+ * Raw JSON layers are deep-merged BEFORE the per-section defaults merge, so a
789
+ * layer that omits a section cannot reset a value supplied by a lower layer.
790
+ */
791
+ export declare function loadConfigLayers(filePaths: readonly string[], validate?: boolean): RagConfig;
792
+ /**
793
+ * Load the effective config for a workspace: defaults < global < workspace.
794
+ *
795
+ * A workspace with no local config still gets the global layer; with neither
796
+ * file present the result is `DEFAULT_CONFIG`. Explicit `--config` callers keep
797
+ * using {@link loadConfig} so their chosen file stays authoritative.
798
+ */
799
+ export declare function loadWorkspaceConfig(directory: string, validate?: boolean): RagConfig;
800
+ /**
801
+ * Top-level sections that a workspace actually configures.
802
+ *
803
+ * Read from the raw JSON layers (global + workspace), NOT from the merged
804
+ * config, so a section that exists only in `DEFAULT_CONFIG` is not reported.
805
+ * Health checks use this to probe only the models a user asked for: the
806
+ * default-on `description` / `imageDescription` models are not "configured"
807
+ * just because defaults enable them.
808
+ */
809
+ export declare function configuredSections(directory: string): Set<string>;
699
810
  /**
700
811
  * Persist a probed embedding vector dimension into the config JSON file.
701
812
  * Sets `embedding.vectorDimension` so subsequent startups skip the probe.
@@ -4,6 +4,7 @@
4
4
  */
5
5
  import { existsSync, readFileSync, writeFileSync } from "node:fs";
6
6
  import path from "node:path";
7
+ import { homedir } from "node:os";
7
8
  import { env } from "node:process";
8
9
  import { normalizeParserOverrides } from "./parser-overrides.js";
9
10
  export const DEFAULT_CONFIG = {
@@ -166,6 +167,12 @@ export const DEFAULT_CONFIG = {
166
167
  readOverride: true,
167
168
  injectSystemPrompt: true,
168
169
  exploreAgentTools: true,
170
+ shell: {
171
+ backgroundGuidance: true,
172
+ longRunningThresholdMs: 30000,
173
+ foregroundTimeoutMs: 120000,
174
+ captureLongRunningQuirk: true,
175
+ },
169
176
  autoIndex: {
170
177
  enabled: false,
171
178
  debounceMs: 2000,
@@ -196,6 +203,14 @@ export const DEFAULT_CONFIG = {
196
203
  retryMax: 2,
197
204
  retryBaseDelayMs: 500,
198
205
  },
206
+ shellGuard: {
207
+ enabled: false,
208
+ threshold: 0.5,
209
+ timeoutMs: 10000,
210
+ onError: "allow",
211
+ cacheTtlMs: 600000,
212
+ maxCacheEntries: 256,
213
+ },
199
214
  description: {
200
215
  enabled: true,
201
216
  provider: "ollama",
@@ -365,7 +380,7 @@ export function validateConfig(config) {
365
380
  const KNOWN_TOP_KEYS = new Set([
366
381
  "embedding", "indexing", "vectorStore", "retrieval", "reranking",
367
382
  "openCode", "chunkers", "chunking", "description",
368
- "imageDescription", "decision", "documentationMode", "wikiMode", "mcp", "autoUpdate", "memory", "ui", "tui", "logging",
383
+ "imageDescription", "decision", "shellGuard", "documentationMode", "wikiMode", "mcp", "autoUpdate", "memory", "ui", "tui", "logging",
369
384
  ]);
370
385
  const topKeys = new Set(Object.keys(config));
371
386
  for (const key of topKeys) {
@@ -510,6 +525,15 @@ export function validateConfig(config) {
510
525
  if (config.openCode.autoIndex?.watcher && !["chokidar", "git"].includes(config.openCode.autoIndex.watcher)) {
511
526
  warnings.push(`openCode.autoIndex.watcher "${config.openCode.autoIndex.watcher}" — expected "chokidar" or "git"`);
512
527
  }
528
+ const shellCfg = config.openCode.shell;
529
+ if (shellCfg) {
530
+ if (shellCfg.longRunningThresholdMs != null && shellCfg.longRunningThresholdMs < 0) {
531
+ warnings.push("openCode.shell.longRunningThresholdMs must be >= 0");
532
+ }
533
+ if (shellCfg.foregroundTimeoutMs != null && shellCfg.foregroundTimeoutMs <= 0) {
534
+ warnings.push("openCode.shell.foregroundTimeoutMs must be > 0");
535
+ }
536
+ }
513
537
  if (config.retrieval.contextOptimization) {
514
538
  const co = config.retrieval.contextOptimization;
515
539
  if (co.maxPerFile < 0)
@@ -569,6 +593,37 @@ export function validateConfig(config) {
569
593
  warnings.push(`decision.baseUrl "${config.decision.baseUrl}" is not a valid URL`);
570
594
  }
571
595
  }
596
+ if (config.shellGuard) {
597
+ const sg = config.shellGuard;
598
+ if (typeof sg.threshold !== "number" || !Number.isFinite(sg.threshold) || sg.threshold < 0 || sg.threshold > 1) {
599
+ warnings.push("shellGuard.threshold must be a number between 0 and 1");
600
+ }
601
+ if (typeof sg.timeoutMs !== "number" || !Number.isFinite(sg.timeoutMs) || sg.timeoutMs <= 0) {
602
+ warnings.push("shellGuard.timeoutMs must be > 0");
603
+ }
604
+ if (sg.onError != null && sg.onError !== "allow" && sg.onError !== "ask") {
605
+ warnings.push(`shellGuard.onError "${sg.onError}" — expected "allow" or "ask"`);
606
+ }
607
+ if (typeof sg.cacheTtlMs !== "number" || !Number.isFinite(sg.cacheTtlMs) || sg.cacheTtlMs < 0) {
608
+ warnings.push("shellGuard.cacheTtlMs must be >= 0");
609
+ }
610
+ if (sg.maxCacheEntries != null && (typeof sg.maxCacheEntries !== "number" || !Number.isFinite(sg.maxCacheEntries) || sg.maxCacheEntries < 0)) {
611
+ warnings.push("shellGuard.maxCacheEntries must be >= 0");
612
+ }
613
+ for (const key of ["provider", "baseUrl", "model"]) {
614
+ if (sg[key] != null && typeof sg[key] !== "string") {
615
+ warnings.push(`shellGuard.${key} must be a string when set`);
616
+ }
617
+ }
618
+ if (sg.baseUrl != null) {
619
+ try {
620
+ new URL(sg.baseUrl);
621
+ }
622
+ catch {
623
+ warnings.push(`shellGuard.baseUrl "${sg.baseUrl}" is not a valid URL`);
624
+ }
625
+ }
626
+ }
572
627
  if (config.reranking?.enabled) {
573
628
  const rr = config.reranking;
574
629
  if (!rr.baseUrl)
@@ -609,15 +664,36 @@ export function findConfigFile(directory) {
609
664
  }
610
665
  return undefined;
611
666
  }
612
- /** Load and parse a JSON config file, deep-merge with defaults, optionally validate. */
613
- export function loadConfig(filePath, validate = true) {
667
+ /**
668
+ * Resolve the machine-wide config file path.
669
+ *
670
+ * `$XDG_CONFIG_HOME/opencode/opencode-rag.json`, falling back to
671
+ * `~/.config/opencode/opencode-rag.json`. The global file is a BASE layer:
672
+ * every workspace config is merged on top of it, so machine-wide defaults
673
+ * (e.g. `shellGuard.enabled`) do not need to be repeated per project.
674
+ */
675
+ export function globalConfigPath(envVars = env, homeDir = homedir()) {
676
+ const xdg = envVars.XDG_CONFIG_HOME?.trim();
677
+ const base = xdg && xdg.length > 0 ? xdg : path.join(homeDir, ".config");
678
+ return path.join(base, "opencode", "opencode-rag.json");
679
+ }
680
+ /** Return the global config path when that file exists. */
681
+ export function findGlobalConfigFile(envVars = env, homeDir = homedir()) {
682
+ const candidate = globalConfigPath(envVars, homeDir);
683
+ return existsSync(candidate) ? candidate : undefined;
684
+ }
685
+ /** Config layers that apply to a workspace (lowest precedence first). */
686
+ export function resolveConfigPaths(directory) {
687
+ return { global: findGlobalConfigFile(), workspace: findConfigFile(directory) };
688
+ }
689
+ /** Read and parse one config file (BOM-tolerant); throws a descriptive error. */
690
+ function parseConfigFile(filePath) {
614
691
  let raw;
615
- let parsed;
616
692
  try {
617
693
  raw = readFileSync(filePath, "utf-8");
618
694
  if (raw.charCodeAt(0) === 0xfeff)
619
695
  raw = raw.slice(1);
620
- parsed = JSON.parse(raw);
696
+ return JSON.parse(raw);
621
697
  }
622
698
  catch (err) {
623
699
  const code = err.code;
@@ -629,6 +705,84 @@ export function loadConfig(filePath, validate = true) {
629
705
  }
630
706
  throw err;
631
707
  }
708
+ }
709
+ /** True for plain JSON objects (arrays and `null` are replacements, not merges). */
710
+ function isPlainObject(value) {
711
+ return typeof value === "object" && value !== null && !Array.isArray(value);
712
+ }
713
+ /** Recursively merge `override` onto `base`; arrays and primitives replace. */
714
+ function mergeConfigObjects(base, override) {
715
+ const merged = { ...base };
716
+ for (const [key, value] of Object.entries(override)) {
717
+ const current = merged[key];
718
+ merged[key] = isPlainObject(value) && isPlainObject(current)
719
+ ? mergeConfigObjects(current, value)
720
+ : value;
721
+ }
722
+ return merged;
723
+ }
724
+ /**
725
+ * Load and parse a JSON config file, deep-merge with defaults, optionally validate.
726
+ *
727
+ * This is the single-file loader: the given file is authoritative. Workspace
728
+ * loading with the global base layer goes through {@link loadWorkspaceConfig}.
729
+ */
730
+ export function loadConfig(filePath, validate = true) {
731
+ return buildConfig(parseConfigFile(filePath), validate);
732
+ }
733
+ /**
734
+ * Load several config files, later files overriding earlier ones.
735
+ *
736
+ * Raw JSON layers are deep-merged BEFORE the per-section defaults merge, so a
737
+ * layer that omits a section cannot reset a value supplied by a lower layer.
738
+ */
739
+ export function loadConfigLayers(filePaths, validate = true) {
740
+ let merged = {};
741
+ for (const filePath of filePaths) {
742
+ merged = mergeConfigObjects(merged, parseConfigFile(filePath));
743
+ }
744
+ return buildConfig(merged, validate);
745
+ }
746
+ /**
747
+ * Load the effective config for a workspace: defaults < global < workspace.
748
+ *
749
+ * A workspace with no local config still gets the global layer; with neither
750
+ * file present the result is `DEFAULT_CONFIG`. Explicit `--config` callers keep
751
+ * using {@link loadConfig} so their chosen file stays authoritative.
752
+ */
753
+ export function loadWorkspaceConfig(directory, validate = true) {
754
+ const { global, workspace } = resolveConfigPaths(directory);
755
+ const layers = [global, workspace].filter((p) => p !== undefined);
756
+ return loadConfigLayers(layers, validate);
757
+ }
758
+ /**
759
+ * Top-level sections that a workspace actually configures.
760
+ *
761
+ * Read from the raw JSON layers (global + workspace), NOT from the merged
762
+ * config, so a section that exists only in `DEFAULT_CONFIG` is not reported.
763
+ * Health checks use this to probe only the models a user asked for: the
764
+ * default-on `description` / `imageDescription` models are not "configured"
765
+ * just because defaults enable them.
766
+ */
767
+ export function configuredSections(directory) {
768
+ const { global, workspace } = resolveConfigPaths(directory);
769
+ const sections = new Set();
770
+ for (const filePath of [global, workspace]) {
771
+ if (!filePath)
772
+ continue;
773
+ try {
774
+ const parsed = parseConfigFile(filePath);
775
+ for (const key of Object.keys(parsed))
776
+ sections.add(key);
777
+ }
778
+ catch {
779
+ // Malformed layer: loadConfig reports it; health checks stay best-effort.
780
+ }
781
+ }
782
+ return sections;
783
+ }
784
+ /** Merge raw config layers onto DEFAULT_CONFIG and validate. */
785
+ function buildConfig(parsed, validate) {
632
786
  const safeObj = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
633
787
  const cfg = {
634
788
  embedding: {
@@ -674,6 +828,10 @@ export function loadConfig(filePath, validate = true) {
674
828
  ...base.autoIndex,
675
829
  ...(safeObj(user.autoIndex) ?? {}),
676
830
  },
831
+ shell: {
832
+ ...base.shell,
833
+ ...(safeObj(user.shell) ?? {}),
834
+ },
677
835
  };
678
836
  return merged;
679
837
  })(),
@@ -697,6 +855,10 @@ export function loadConfig(filePath, validate = true) {
697
855
  ...DEFAULT_CONFIG.decision,
698
856
  ...(safeObj(parsed.decision) ?? {}),
699
857
  },
858
+ shellGuard: {
859
+ ...DEFAULT_CONFIG.shellGuard,
860
+ ...(safeObj(parsed.shellGuard) ?? {}),
861
+ },
700
862
  documentationMode: {
701
863
  ...DEFAULT_CONFIG.documentationMode,
702
864
  ...(safeObj(parsed.documentationMode) ?? {}),
@@ -18,9 +18,15 @@ export interface HealthCheckResult {
18
18
  }
19
19
  /**
20
20
  * Check connectivity and model availability for all configured providers.
21
- * Returns one result per configured model (embedding + description + image_description if enabled).
21
+ *
22
+ * The embedding model is always checked — indexing cannot work without it.
23
+ * Optional models are checked only when the feature is enabled AND its section
24
+ * is actually configured: `configuredSections` comes from the raw config
25
+ * layers, so a model that is only enabled by `DEFAULT_CONFIG` is never probed
26
+ * (and never offered for `ollama pull`). Omit the set to check every enabled
27
+ * model (used by callers that are not init/setup).
22
28
  */
23
- export declare function checkProviderHealth(config: RagConfig): Promise<HealthCheckResult[]>;
29
+ export declare function checkProviderHealth(config: RagConfig, configuredSections?: ReadonlySet<string>): Promise<HealthCheckResult[]>;
24
30
  /** A model entry to pull from an Ollama server. */
25
31
  interface PullModelEntry {
26
32
  /** Model name (e.g. "nomic-embed-text") */
@@ -3,24 +3,31 @@ import { isZenProvider, resolveZenBaseUrl } from "../core/zen.js";
3
3
  import { fetchWithProxy, postJson } from "./http.js";
4
4
  /**
5
5
  * Check connectivity and model availability for all configured providers.
6
- * Returns one result per configured model (embedding + description + image_description if enabled).
6
+ *
7
+ * The embedding model is always checked — indexing cannot work without it.
8
+ * Optional models are checked only when the feature is enabled AND its section
9
+ * is actually configured: `configuredSections` comes from the raw config
10
+ * layers, so a model that is only enabled by `DEFAULT_CONFIG` is never probed
11
+ * (and never offered for `ollama pull`). Omit the set to check every enabled
12
+ * model (used by callers that are not init/setup).
7
13
  */
8
- export async function checkProviderHealth(config) {
14
+ export async function checkProviderHealth(config, configuredSections) {
9
15
  const timeoutMs = config.embedding.timeoutMs ?? 120000;
16
+ const configured = (section) => !configuredSections || configuredSections.has(section);
10
17
  const checks = [
11
18
  checkEmbeddingModel(config, timeoutMs),
12
19
  ];
13
- if (config.description?.enabled) {
20
+ if (config.description?.enabled && configured("description")) {
14
21
  checks.push(checkDescriptionModel(config, timeoutMs));
15
22
  }
16
- if (config.imageDescription?.enabled) {
23
+ if (config.imageDescription?.enabled && configured("imageDescription")) {
17
24
  checks.push(checkImageDescriptionModel(config, timeoutMs));
18
25
  const onDemand = resolveOnDemandImageConfig(config.imageDescription);
19
26
  if (onDemand.provider !== config.imageDescription.provider || onDemand.model !== config.imageDescription.model) {
20
27
  checks.push(checkOnDemandImageDescriptionModel(onDemand));
21
28
  }
22
29
  }
23
- if (config.reranking?.enabled) {
30
+ if (config.reranking?.enabled && configured("reranking")) {
24
31
  checks.push(checkRerankModel(config));
25
32
  }
26
33
  return Promise.all(checks);
package/dist/index.d.ts CHANGED
@@ -18,7 +18,7 @@ export { LanceDbStore } from "./vectorstore/lancedb.js";
18
18
  export { InMemoryVectorStore } from "./vectorstore/memory.js";
19
19
  export { retrieve } from "./retriever/retriever.js";
20
20
  export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/context-optimizer.js";
21
- export { loadConfig, DEFAULT_CONFIG } from "./core/config.js";
21
+ export { loadConfig, loadConfigLayers, loadWorkspaceConfig, resolveConfigPaths, configuredSections, findGlobalConfigFile, globalConfigPath, DEFAULT_CONFIG } from "./core/config.js";
22
22
  export { createBackgroundIndexer } from "./watcher.js";
23
23
  export { createWatchIgnore } from "./indexer.js";
24
24
  export { ImageChunker, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
package/dist/index.js CHANGED
@@ -17,7 +17,7 @@ export { LanceDbStore } from "./vectorstore/lancedb.js";
17
17
  export { InMemoryVectorStore } from "./vectorstore/memory.js";
18
18
  export { retrieve } from "./retriever/retriever.js";
19
19
  export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/context-optimizer.js";
20
- export { loadConfig, DEFAULT_CONFIG } from "./core/config.js";
20
+ export { loadConfig, loadConfigLayers, loadWorkspaceConfig, resolveConfigPaths, configuredSections, findGlobalConfigFile, globalConfigPath, DEFAULT_CONFIG } from "./core/config.js";
21
21
  export { createBackgroundIndexer } from "./watcher.js";
22
22
  export { createWatchIgnore } from "./indexer.js";
23
23
  export { ImageChunker, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
@@ -3,6 +3,7 @@
3
3
  * that is injected into both the runtime system prompt (via plugin.ts) and the AGENTS.md
4
4
  * directive (via init-helpers.ts).
5
5
  */
6
+ import type { OpenCodeShellConfig } from "../core/config.js";
6
7
  /** Sentinel marker that opens the managed section. */
7
8
  export declare const BEGIN_MARKER = "<!-- BEGIN opencode-rag -->";
8
9
  /** Sentinel marker that closes the managed section. */
@@ -29,10 +30,12 @@ export declare const DECISION_ROUTING_GUIDANCE_LINE = "- Before asking the user
29
30
  * Build the flat guidance lines array for the runtime system-prompt injector.
30
31
  * Returns a new array each call.
31
32
  */
33
+ export declare function buildShellBackgroundGuidanceLines(shell?: OpenCodeShellConfig): string[];
32
34
  export declare function buildSystemGuidanceLines(opts: {
33
35
  promptEnforcement: boolean;
34
36
  decisionEnabled?: boolean;
35
37
  routeBeforeAsking?: boolean;
38
+ shell?: OpenCodeShellConfig;
36
39
  }): string[];
37
40
  /**
38
41
  * Build the markdown-formatted AGENTS.md directive section, wrapped in sentinel
@@ -42,4 +45,5 @@ export declare function buildAgentsMdDirective(opts: {
42
45
  promptEnforcement: boolean;
43
46
  decisionEnabled?: boolean;
44
47
  routeBeforeAsking?: boolean;
48
+ shell?: OpenCodeShellConfig;
45
49
  }): string;