opencode-rag-plugin 2.13.2 → 2.13.4

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.
@@ -56,6 +56,40 @@ export declare function promptHidden(rl: ReturnType<typeof createInterface>, que
56
56
  export declare function composeClickHouseUrl(rawUrl: string, port: string): string;
57
57
  /** Run the interactive (or flag-driven) ClickHouse setup. */
58
58
  export declare function runClickHouseSetup(options?: ClickHouseSetupOptions): Promise<void>;
59
+ /** Options shared by `clickhouse adopt` and `clickhouse compact`. */
60
+ export interface ClickHouseMaintenanceOptions {
61
+ /** Namespace to adopt from; defaults to every legacy spelling of this workspace. */
62
+ from?: string;
63
+ /** Target namespace; defaults to the configured/derived one. */
64
+ to?: string;
65
+ /** Execute the statements. Without it the command only prints what it would do. */
66
+ apply?: boolean;
67
+ /** Working directory override (tests); defaults to `process.cwd()`. */
68
+ cwd?: string;
69
+ }
70
+ /**
71
+ * `clickhouse adopt` - move an index that lives under a stale namespace spelling
72
+ * onto the current one, instead of re-embedding it from scratch.
73
+ *
74
+ * Exists because `deriveNamespace()` used to hash the workspace path exactly as
75
+ * spelled: the same repository opened as `C:\repo` and `c:\repo` got two tables,
76
+ * one of them quietly going stale while the agent read it and concluded retrieval
77
+ * was bad. No rows are created here - a `RENAME TABLE` moves them.
78
+ *
79
+ * @param options - Flags from the CLI.
80
+ */
81
+ export declare function runClickHouseAdopt(options?: ClickHouseMaintenanceOptions): Promise<void>;
82
+ /**
83
+ * `clickhouse compact` - delete tombstoned chunk rows and collapse the merge tree.
84
+ *
85
+ * A ReplacingMergeTree keeps superseded embeddings until something forces the
86
+ * merge, and every read filters on `is_deleted = 0`. Left alone that inflates the
87
+ * ANN candidate pool - one measured workspace carried 153 424 rows of which 9 167
88
+ * were live - and that costs both recall and latency on every search.
89
+ *
90
+ * @param options - Flags from the CLI.
91
+ */
92
+ export declare function runClickHouseCompact(options?: ClickHouseMaintenanceOptions): Promise<void>;
59
93
  /** Register the `clickhouse` command group. */
60
94
  export declare function registerClickHouseCommand(program: Command): void;
61
95
  export {};
@@ -2,7 +2,7 @@ import path from "node:path";
2
2
  import { copyFileSync, existsSync, mkdirSync } from "node:fs";
3
3
  import { createInterface } from "node:readline/promises";
4
4
  import { loadWorkspaceConfig, globalConfigPath, findConfigFile, projectConfigPath } from "../../core/config.js";
5
- import { ClickHouseStore, deriveNamespace, resolveClickHouseOptions, sanitizeNamespace, } from "../../vectorstore/clickhouse.js";
5
+ import { ClickHouseStore, deriveNamespace, legacyNamespaceVariants, resolveClickHouseOptions, sanitizeNamespace, } from "../../vectorstore/clickhouse.js";
6
6
  import { readJsonObject, writeJsonFile } from "../helpers.js";
7
7
  import { c } from "../format.js";
8
8
  /**
@@ -301,6 +301,178 @@ export async function runClickHouseSetup(options = {}) {
301
301
  function findOrCreateWorkspaceConfig(cwd) {
302
302
  return findConfigFile(cwd) ?? projectConfigPath(cwd);
303
303
  }
304
+ /** Run one parameterless query per call and return its rows as objects. */
305
+ async function withAdmin(url, database, username, password, fn) {
306
+ const { createClient } = await import("@clickhouse/client");
307
+ const client = createClient({ url, username, password, database, request_timeout: 60_000 });
308
+ try {
309
+ const run = async (sql) => await (await client.query({ query: sql, format: "JSONEachRow" })).json();
310
+ return await fn(run);
311
+ }
312
+ finally {
313
+ await client.close().catch(() => { });
314
+ }
315
+ }
316
+ /** A namespace is interpolated into DDL, so it must look like one of ours. */
317
+ function assertSafeNamespace(ns) {
318
+ if (!/^[A-Za-z0-9_]{1,64}$/.test(ns))
319
+ throw new Error(`Refusing to touch unsafe namespace name: ${JSON.stringify(ns)}`);
320
+ return ns;
321
+ }
322
+ /** Read the ClickHouse connection block this workspace points at. */
323
+ function clickHouseTarget(cwd) {
324
+ const cfg = loadWorkspaceConfig(cwd);
325
+ if ((cfg.vectorStore.provider ?? "lancedb") !== "clickhouse") {
326
+ throw new Error('This workspace does not use the ClickHouse backend (vectorStore.provider is not "clickhouse").');
327
+ }
328
+ const options = resolveClickHouseOptions(cfg, cwd);
329
+ return {
330
+ url: options.url,
331
+ database: options.database,
332
+ username: options.username,
333
+ password: options.password,
334
+ namespace: options.namespace,
335
+ pinned: Boolean(cfg.vectorStore.clickhouse?.namespace?.trim()),
336
+ };
337
+ }
338
+ /**
339
+ * `clickhouse adopt` - move an index that lives under a stale namespace spelling
340
+ * onto the current one, instead of re-embedding it from scratch.
341
+ *
342
+ * Exists because `deriveNamespace()` used to hash the workspace path exactly as
343
+ * spelled: the same repository opened as `C:\repo` and `c:\repo` got two tables,
344
+ * one of them quietly going stale while the agent read it and concluded retrieval
345
+ * was bad. No rows are created here - a `RENAME TABLE` moves them.
346
+ *
347
+ * @param options - Flags from the CLI.
348
+ */
349
+ export async function runClickHouseAdopt(options = {}) {
350
+ const cwd = options.cwd ?? process.cwd();
351
+ const t = clickHouseTarget(cwd);
352
+ const target = assertSafeNamespace(options.to ?? t.namespace);
353
+ const candidates = [
354
+ ...new Set([
355
+ ...(options.from ? [assertSafeNamespace(options.from)] : []),
356
+ ...(t.pinned ? [] : legacyNamespaceVariants(cwd)),
357
+ ]),
358
+ ];
359
+ if (candidates.length === 0) {
360
+ console.log(`\n ${c.success("Nothing to adopt:")} namespace "${target}" is pinned in the config, so no alternative spelling is derived.`);
361
+ console.log(` ${c.label("If your index lives elsewhere:")} pass --from <namespace>\n`);
362
+ return;
363
+ }
364
+ await withAdmin(t.url, t.database, t.username, t.password, async (run) => {
365
+ const existing = (await run(`SELECT name FROM system.tables WHERE database = '${t.database}'`))
366
+ .map((r) => r.name)
367
+ .filter((name) => typeof name === "string" && name.length > 0);
368
+ const live = candidates.filter((ns) => existing.includes(`chunks_${ns}`));
369
+ if (live.length === 0) {
370
+ console.log(`\n ${c.warn("No index to adopt.")} None of ${candidates.join(", ")} exists in ${t.database}.\n`);
371
+ return;
372
+ }
373
+ console.log(`\n ${c.heading("ClickHouse namespace adoption")} - target "${target}"\n`);
374
+ const stats = [];
375
+ for (const ns of live) {
376
+ const row = (await run(`SELECT count() AS rows, toString(max(ver)) AS ver FROM ${t.database}.chunks_${assertSafeNamespace(ns)}`))[0];
377
+ stats.push({ ns, rows: Number(row?.rows ?? 0) || 0, ver: String(row?.ver ?? "").slice(0, 19) });
378
+ }
379
+ for (const s of stats) {
380
+ console.log(` ${c.file(`chunks_${s.ns}`.padEnd(46))} ${String(s.rows).padStart(8)} rows newest ${s.ver}`);
381
+ }
382
+ const chosen = options.from ? assertSafeNamespace(options.from) : (stats.length === 1 ? stats[0].ns : "");
383
+ if (!chosen) {
384
+ console.log(`\n ${c.warn("Two or more spellings exist.")} Pass ${c.value("--from <namespace>")} for the one that holds your real index.`);
385
+ console.log(` Hint: the one with the newest \`ver\` is the one that was still being written to.\n`);
386
+ return;
387
+ }
388
+ if (chosen === target) {
389
+ console.log(`\n ${c.success("Already adopted:")} the source namespace is the target namespace.\n`);
390
+ return;
391
+ }
392
+ const targetStats = existing.includes(`chunks_${target}`)
393
+ ? (await run(`SELECT count() AS n, toString(max(ver)) AS ver FROM ${t.database}.chunks_${target}`))[0]
394
+ : undefined;
395
+ const targetRows = Number(targetStats?.n ?? 0);
396
+ if (targetRows > 0) {
397
+ const source = stats.find((s) => s.ns === chosen);
398
+ console.log(`\n ${c.error("Refusing:")} both indexes are populated, and merging them is not this command's call to guess.`);
399
+ console.log(` target ${t.database}.chunks_${target}: ${targetRows} rows, newest ${String(targetStats?.ver ?? "").slice(0, 19)}`);
400
+ console.log(` source ${t.database}.chunks_${chosen}: ${source?.rows ?? "?"} rows, newest ${source?.ver ?? "?"}`);
401
+ console.log(` ${c.label("Pick one:")}`);
402
+ console.log(` - the source is the fresher one -> ${c.value(`opencode-rag clickhouse adopt --from ${chosen} --apply`)} (after dropping the target, or pin vectorStore.clickhouse.namespace to "${chosen}")`);
403
+ console.log(` - the target is the fresher one -> the source is a stale duplicate; drop it: DROP TABLE ${t.database}.chunks_${chosen}; DROP TABLE ${t.database}.state_${chosen};`);
404
+ console.log(` - unsure -> trust the newer \`newest\` timestamp; the index that stopped moving is the one no session writes to.\n`);
405
+ return;
406
+ }
407
+ const statements = [];
408
+ for (const kind of ["chunks", "state"]) {
409
+ const src = `${t.database}.${kind}_${chosen}`;
410
+ const dst = `${t.database}.${kind}_${target}`;
411
+ if (!existing.includes(`${kind}_${chosen}`))
412
+ continue;
413
+ if (existing.includes(`${kind}_${target}`))
414
+ statements.push(`DROP TABLE ${dst}`);
415
+ statements.push(`RENAME TABLE ${src} TO ${dst}`);
416
+ }
417
+ console.log(`\n ${c.label("Statements:")}`);
418
+ for (const s of statements)
419
+ console.log(` ${s}`);
420
+ if (!options.apply) {
421
+ console.log(`\n ${c.warn("Dry run.")} Re-run with ${c.value("--apply")} to execute. Restart OpenCode afterwards so the store reconnects.\n`);
422
+ return;
423
+ }
424
+ for (const s of statements) {
425
+ await run(s);
426
+ console.log(` ${c.success("Applied:")} ${s}`);
427
+ }
428
+ console.log(`\n ${c.success("Adopted.")} The index "${chosen}" now answers as "${target}". Restart OpenCode to drop the old table handle.\n`);
429
+ });
430
+ }
431
+ /**
432
+ * `clickhouse compact` - delete tombstoned chunk rows and collapse the merge tree.
433
+ *
434
+ * A ReplacingMergeTree keeps superseded embeddings until something forces the
435
+ * merge, and every read filters on `is_deleted = 0`. Left alone that inflates the
436
+ * ANN candidate pool - one measured workspace carried 153 424 rows of which 9 167
437
+ * were live - and that costs both recall and latency on every search.
438
+ *
439
+ * @param options - Flags from the CLI.
440
+ */
441
+ export async function runClickHouseCompact(options = {}) {
442
+ const cwd = options.cwd ?? process.cwd();
443
+ const t = clickHouseTarget(cwd);
444
+ const ns = assertSafeNamespace(options.to ?? t.namespace);
445
+ await withAdmin(t.url, t.database, t.username, t.password, async (run) => {
446
+ const exists = Number((await run(`SELECT count() AS n FROM system.tables WHERE database = '${t.database}' AND name = 'chunks_${ns}'`))[0]?.n ?? 0) > 0;
447
+ if (!exists) {
448
+ console.log(`\n ${c.warn("No such table:")} ${t.database}.chunks_${ns}\n`);
449
+ return;
450
+ }
451
+ const row = (await run(`SELECT count() AS total, countIf(is_deleted = 0) AS live FROM ${t.database}.chunks_${ns}`))[0];
452
+ const totalN = Number(row?.total ?? 0) || 0;
453
+ const liveN = Number(row?.live ?? 0) || 0;
454
+ const dead = totalN - liveN;
455
+ console.log(`\n ${c.heading("ClickHouse table")} ${t.database}.chunks_${ns}`);
456
+ console.log(` ${c.label("Rows:")} ${totalN}`);
457
+ console.log(` ${c.label("Live:")} ${liveN}`);
458
+ console.log(` ${c.label("Dead:")} ${dead}${totalN > 0 ? ` (${Math.round((dead / totalN) * 100)}%)` : ""}\n`);
459
+ if (dead === 0) {
460
+ console.log(` ${c.success("Nothing to sweep.")}\n`);
461
+ return;
462
+ }
463
+ if (!options.apply) {
464
+ console.log(` ${c.warn("Dry run.")} Re-run with ${c.value("--apply")} to run:`);
465
+ console.log(` ALTER TABLE ${t.database}.chunks_${ns} DELETE WHERE is_deleted = 1`);
466
+ console.log(` OPTIMIZE TABLE ${t.database}.chunks_${ns} FINAL\n`);
467
+ return;
468
+ }
469
+ await run(`ALTER TABLE ${t.database}.chunks_${ns} DELETE WHERE is_deleted = 1`);
470
+ console.log(` ${c.success("Mutation queued:")} is_deleted = 1`);
471
+ await run(`OPTIMIZE TABLE ${t.database}.chunks_${ns} FINAL`);
472
+ const after = Number((await run(`SELECT count() AS n FROM ${t.database}.chunks_${ns}`))[0]?.n ?? 0);
473
+ console.log(` ${c.success("Optimized FINAL:")}, ${after} rows visible (mutations run asynchronously - re-check in a moment)\n`);
474
+ });
475
+ }
304
476
  /** Register the `clickhouse` command group. */
305
477
  export function registerClickHouseCommand(program) {
306
478
  const group = program
@@ -331,5 +503,34 @@ export function registerClickHouseCommand(program) {
331
503
  process.exitCode = 1;
332
504
  }
333
505
  });
506
+ group
507
+ .command("adopt")
508
+ .description("Move an index from a stale namespace spelling onto this workspace's current one")
509
+ .option("--from <namespace>", "namespace to adopt from (default: the legacy spelling of this path)")
510
+ .option("--to <namespace>", "target namespace (default: configured/derived)")
511
+ .option("--apply", "execute the RENAME statements (default: dry run)")
512
+ .action(async (options) => {
513
+ try {
514
+ await runClickHouseAdopt(options);
515
+ }
516
+ catch (err) {
517
+ console.error(`\n${c.error("Adopt failed:")} ${err.message}\n`);
518
+ process.exitCode = 1;
519
+ }
520
+ });
521
+ group
522
+ .command("compact")
523
+ .description("Delete tombstoned chunk rows and collapse the merge tree")
524
+ .option("--to <namespace>", "namespace to compact (default: configured/derived)")
525
+ .option("--apply", "execute the mutation (default: dry run)")
526
+ .action(async (options) => {
527
+ try {
528
+ await runClickHouseCompact(options);
529
+ }
530
+ catch (err) {
531
+ console.error(`\n${c.error("Compact failed:")} ${err.message}\n`);
532
+ process.exitCode = 1;
533
+ }
534
+ });
334
535
  }
335
536
  //# sourceMappingURL=clickhouse.js.map
@@ -13,7 +13,7 @@ import { findKeywordIndexGaps } from "../../indexer/keyword-rehydration.js";
13
13
  import { deriveWatcherHealth, discoverWatcherStates } from "../../watcher.js";
14
14
  import { getPackageMetadata } from "../helpers.js";
15
15
  import { checkForUpdate } from "../../core/version-check.js";
16
- import { deriveNamespace, sanitizeNamespace } from "../../vectorstore/clickhouse.js";
16
+ import { deriveNamespace, sanitizeNamespace, legacyNamespaceVariants } from "../../vectorstore/clickhouse.js";
17
17
  /**
18
18
  * Check for a stale index.lock file and clean it up if the owning process is dead.
19
19
  *
@@ -88,6 +88,12 @@ export function registerStatusCommand(program) {
88
88
  const annMode = ch?.ann === "hnsw" ? "hnsw ANN" : "exact scans";
89
89
  logCliInfo(logFilePath, "status", `${c.label("Vector store:")} ${c.value("clickhouse")} ${c.file(`${ch?.url ?? ""}/${ch?.database ?? ""}`)} ` +
90
90
  `(namespace ${c.value(namespace)}, ${annMode})`);
91
+ if (!ch?.namespace?.trim()) {
92
+ const siblings = legacyNamespaceVariants(cwd);
93
+ if (siblings.length > 0) {
94
+ logCliInfo(logFilePath, "status", `${c.label("Other spellings:")} this path also hashes to ${siblings.join(", ")} - if your index lives there run ${c.value("opencode-rag clickhouse adopt")}, or pin vectorStore.clickhouse.namespace`);
95
+ }
96
+ }
91
97
  if (ch?.ann === "hnsw") {
92
98
  const hasIndex = store.hasVectorIndex;
93
99
  if (hasIndex) {
@@ -5,6 +5,8 @@
5
5
  * Helper functions for the `setup` command — file generation, config building,
6
6
  * dependency installation, and gitignore merging.
7
7
  */
8
+ import { type AgentGuidanceDetail } from "../../opencode/system-guidance.js";
9
+ import type { OpenCodeShellConfig } from "../../core/config.js";
8
10
  import type { PackageMetadata } from "../types.js";
9
11
  import type { IndexingTuning } from "./backend-detect.js";
10
12
  /**
@@ -137,15 +139,20 @@ export declare function mergeGitignoreContent(existingContent?: string): string;
137
139
  * @param opts - Optional settings. `promptEnforcement` controls whether the
138
140
  * quirk-capture enforcement rules are included (default `true`);
139
141
  * `decisionEnabled` controls whether the `make_decision` guidance section is
140
- * included (default `false` — the tool is not registered when disabled);
142
+ * included (default `false` - the tool is not registered when disabled);
141
143
  * `routeBeforeAsking` adds the optional pre-ask decision-routing rule
142
- * (default `false`).
144
+ * (default `false`); `agentsMdDetail` picks the section size (default `"full"` -
145
+ * pass `"auto"` together with `injectedAtRuntime` to let the runtime injector
146
+ * decide and avoid shipping the same protocol twice).
143
147
  * @returns The merged `AGENTS.md` content with a trailing newline.
144
148
  */
145
149
  export declare function mergeAgentsMdContent(existingContent?: string, opts?: {
146
150
  promptEnforcement?: boolean;
147
151
  decisionEnabled?: boolean;
148
152
  routeBeforeAsking?: boolean;
153
+ agentsMdDetail?: AgentGuidanceDetail;
154
+ injectedAtRuntime?: boolean;
155
+ shell?: OpenCodeShellConfig;
149
156
  }): string;
150
157
  /**
151
158
  * Get the runtime directory path (`~/.opencode`).
@@ -403,9 +403,11 @@ export function mergeGitignoreContent(existingContent) {
403
403
  * @param opts - Optional settings. `promptEnforcement` controls whether the
404
404
  * quirk-capture enforcement rules are included (default `true`);
405
405
  * `decisionEnabled` controls whether the `make_decision` guidance section is
406
- * included (default `false` — the tool is not registered when disabled);
406
+ * included (default `false` - the tool is not registered when disabled);
407
407
  * `routeBeforeAsking` adds the optional pre-ask decision-routing rule
408
- * (default `false`).
408
+ * (default `false`); `agentsMdDetail` picks the section size (default `"full"` -
409
+ * pass `"auto"` together with `injectedAtRuntime` to let the runtime injector
410
+ * decide and avoid shipping the same protocol twice).
409
411
  * @returns The merged `AGENTS.md` content with a trailing newline.
410
412
  */
411
413
  export function mergeAgentsMdContent(existingContent, opts) {
@@ -413,6 +415,9 @@ export function mergeAgentsMdContent(existingContent, opts) {
413
415
  promptEnforcement: opts?.promptEnforcement ?? true,
414
416
  decisionEnabled: opts?.decisionEnabled ?? false,
415
417
  routeBeforeAsking: opts?.routeBeforeAsking ?? false,
418
+ agentsMdDetail: opts?.agentsMdDetail,
419
+ injectedAtRuntime: opts?.injectedAtRuntime,
420
+ shell: opts?.shell,
416
421
  });
417
422
  if (!existingContent) {
418
423
  return `${section}\n`;
@@ -271,18 +271,24 @@ export async function scaffoldWorkspace(options = {}) {
271
271
  let promptEnforcement = true;
272
272
  let decisionEnabled = false;
273
273
  let routeBeforeAsking = false;
274
+ let agentsMdDetail = "auto";
275
+ let injectedAtRuntime = true;
276
+ let shellCfg;
274
277
  try {
275
278
  if (existsSync(configPath)) {
276
279
  const existingCfg = loadConfig(configPath, false);
277
280
  promptEnforcement = existingCfg.memory?.promptEnforcement ?? true;
278
281
  decisionEnabled = existingCfg.decision?.enabled ?? false;
279
282
  routeBeforeAsking = existingCfg.decision?.routeBeforeAsking ?? false;
283
+ agentsMdDetail = existingCfg.openCode?.agentsMdDetail ?? "auto";
284
+ injectedAtRuntime = existingCfg.openCode?.injectSystemPrompt !== false;
285
+ shellCfg = existingCfg.openCode?.shell;
280
286
  }
281
287
  }
282
288
  catch {
283
- // Malformed or missing config — use defaults.
289
+ // Malformed or missing config - use defaults.
284
290
  }
285
- const nextAgentsMd = mergeAgentsMdContent(agentsMdExists ? readFileSync(agentsMdPath, "utf-8") : undefined, { promptEnforcement, decisionEnabled, routeBeforeAsking });
291
+ const nextAgentsMd = mergeAgentsMdContent(agentsMdExists ? readFileSync(agentsMdPath, "utf-8") : undefined, { promptEnforcement, decisionEnabled, routeBeforeAsking, agentsMdDetail, injectedAtRuntime, shell: shellCfg });
286
292
  if (!agentsMdExists || options.force) {
287
293
  writeFileSync(agentsMdPath, nextAgentsMd, "utf-8");
288
294
  console.log(` ${agentsMdExists ? c.updated("Updated:") : c.created("Created:")} AGENTS.md`);
@@ -54,16 +54,22 @@ export function autoScaffoldWorkspace(directory) {
54
54
  let promptEnforcement = true;
55
55
  let decisionEnabled = false;
56
56
  let routeBeforeAsking = false;
57
+ let agentsMdDetail = "auto";
58
+ let injectedAtRuntime = true;
59
+ let shellCfg;
57
60
  try {
58
61
  const cfg = loadWorkspaceConfig(directory, false);
59
62
  promptEnforcement = cfg.memory?.promptEnforcement ?? true;
60
63
  decisionEnabled = cfg.decision?.enabled ?? false;
61
64
  routeBeforeAsking = cfg.decision?.routeBeforeAsking ?? false;
65
+ agentsMdDetail = cfg.openCode?.agentsMdDetail ?? "auto";
66
+ injectedAtRuntime = cfg.openCode?.injectSystemPrompt !== false;
67
+ shellCfg = cfg.openCode?.shell;
62
68
  }
63
69
  catch {
64
70
  // Defaults.
65
71
  }
66
- createIfMissing(agentsPath, mergeAgentsMdContent(undefined, { promptEnforcement, decisionEnabled, routeBeforeAsking }), created, directory);
72
+ createIfMissing(agentsPath, mergeAgentsMdContent(undefined, { promptEnforcement, decisionEnabled, routeBeforeAsking, agentsMdDetail, injectedAtRuntime, shell: shellCfg }), created, directory);
67
73
  }
68
74
  if (created.length > 0) {
69
75
  appendDebugLog(path.join(opencodeDir, "opencode-rag.log"), {
@@ -757,6 +757,20 @@ export interface RagConfig {
757
757
  readRelatedFilesMax?: number;
758
758
  /** Whether to inject RAG tool guidance into system prompts when the session's tool catalog exposes the RAG tools (default true). */
759
759
  injectSystemPrompt?: boolean;
760
+ /**
761
+ * How much guidance a generated `AGENTS.md` block carries: `"auto"` (default)
762
+ * writes the compact form when `injectSystemPrompt` will deliver the full
763
+ * protocol at runtime and the full form when it will not; `"full"` always
764
+ * writes the complete protocol (pre-2.14 behaviour, standalone repos);
765
+ * `"compact"` always writes the short form.
766
+ */
767
+ agentsMdDetail?: "auto" | "full" | "compact";
768
+ /**
769
+ * Average relevance below which a `search_semantic` result block is labelled
770
+ * weak, telling the agent the hits are leads to verify rather than an answer
771
+ * (default 0.5, `0` disables the label).
772
+ */
773
+ weakHitThreshold?: number;
760
774
  /** Whether to grant the read-only RAG tools to the built-in `explore` agent (default true). */
761
775
  exploreAgentTools?: boolean;
762
776
  /** Handling of long-running shell commands (backgrounding guidance + measurement). */
@@ -183,6 +183,8 @@ export const DEFAULT_CONFIG = {
183
183
  maxContextChunks: 10,
184
184
  readOverride: true,
185
185
  injectSystemPrompt: true,
186
+ agentsMdDetail: "auto",
187
+ weakHitThreshold: 0.5,
186
188
  exploreAgentTools: true,
187
189
  shell: {
188
190
  backgroundGuidance: true,
@@ -585,7 +587,13 @@ export function validateConfig(config) {
585
587
  warnings.push("openCode.maxContextChunks must be > 0");
586
588
  }
587
589
  if (config.openCode.autoIndex?.watcher && !["chokidar", "git"].includes(config.openCode.autoIndex.watcher)) {
588
- warnings.push(`openCode.autoIndex.watcher "${config.openCode.autoIndex.watcher}" — expected "chokidar" or "git"`);
590
+ warnings.push(`openCode.autoIndex.watcher "${config.openCode.autoIndex.watcher}" - expected "chokidar" or "git"`);
591
+ }
592
+ if (config.openCode.agentsMdDetail && !["auto", "full", "compact"].includes(config.openCode.agentsMdDetail)) {
593
+ warnings.push(`openCode.agentsMdDetail "${config.openCode.agentsMdDetail}" - expected "auto", "full" or "compact"`);
594
+ }
595
+ if (config.openCode.weakHitThreshold != null && (config.openCode.weakHitThreshold < 0 || config.openCode.weakHitThreshold > 1)) {
596
+ warnings.push("openCode.weakHitThreshold must be between 0 and 1 (0 disables the weak-hit label)");
589
597
  }
590
598
  const shellCfg = config.openCode.shell;
591
599
  if (shellCfg) {
package/dist/index.d.ts CHANGED
@@ -16,7 +16,7 @@ export { formatDecisionAnswers } from "./decision/format.js";
16
16
  export { createVectorStore } from "./vectorstore/factory.js";
17
17
  export { LanceDbStore } from "./vectorstore/lancedb.js";
18
18
  export { InMemoryVectorStore } from "./vectorstore/memory.js";
19
- export { ClickHouseStore, resolveClickHouseOptions, sanitizeNamespace, deriveNamespace } from "./vectorstore/clickhouse.js";
19
+ export { ClickHouseStore, resolveClickHouseOptions, sanitizeNamespace, deriveNamespace, canonicalizeWorkspacePath, legacyNamespaceVariants } from "./vectorstore/clickhouse.js";
20
20
  export type { ResolvedClickHouseOptions } from "./vectorstore/clickhouse.js";
21
21
  export { retrieve } from "./retriever/retriever.js";
22
22
  export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/context-optimizer.js";
package/dist/index.js CHANGED
@@ -15,7 +15,7 @@ export { formatDecisionAnswers } from "./decision/format.js";
15
15
  export { createVectorStore } from "./vectorstore/factory.js";
16
16
  export { LanceDbStore } from "./vectorstore/lancedb.js";
17
17
  export { InMemoryVectorStore } from "./vectorstore/memory.js";
18
- export { ClickHouseStore, resolveClickHouseOptions, sanitizeNamespace, deriveNamespace } from "./vectorstore/clickhouse.js";
18
+ export { ClickHouseStore, resolveClickHouseOptions, sanitizeNamespace, deriveNamespace, canonicalizeWorkspacePath, legacyNamespaceVariants } from "./vectorstore/clickhouse.js";
19
19
  export { retrieve } from "./retriever/retriever.js";
20
20
  export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/context-optimizer.js";
21
21
  export { loadConfig, loadConfigLayers, loadWorkspaceConfig, resolveConfigPaths, configuredSections, findGlobalConfigFile, globalConfigPath, DEFAULT_CONFIG } from "./core/config.js";
@@ -18,6 +18,18 @@ export interface FormatReadOutputOptions {
18
18
  /** Maximum output character count. */
19
19
  maxChars: number;
20
20
  }
21
+ /**
22
+ * The advisory printed under a retrieval header whose average relevance is weak.
23
+ *
24
+ * A mandated search that returns near-noise reads as an answer when nothing says
25
+ * otherwise - which is how a working tool acquires a reputation for being useless.
26
+ * Labelling the block costs one line and hands the agent the next move instead.
27
+ *
28
+ * @param avgRelevance - Mean fused score of the returned chunks.
29
+ * @param threshold - Floor below which the label appears; `<= 0` disables it.
30
+ * @returns A markdown line without trailing newline, or `""` when not applicable.
31
+ */
32
+ export declare function weakHitAdvisory(avgRelevance: number, threshold: number): string;
21
33
  /**
22
34
  * Format RAG retrieval results for the search_semantic tool output.
23
35
  *
@@ -2,6 +2,22 @@
2
2
  * @fileoverview Formats RAG retrieval output, hybrid file-content output, file fallbacks, and related-file suggestions for the read tool.
3
3
  */
4
4
  import { normalizeParserOverrides } from "../core/parser-overrides.js";
5
+ /**
6
+ * The advisory printed under a retrieval header whose average relevance is weak.
7
+ *
8
+ * A mandated search that returns near-noise reads as an answer when nothing says
9
+ * otherwise - which is how a working tool acquires a reputation for being useless.
10
+ * Labelling the block costs one line and hands the agent the next move instead.
11
+ *
12
+ * @param avgRelevance - Mean fused score of the returned chunks.
13
+ * @param threshold - Floor below which the label appears; `<= 0` disables it.
14
+ * @returns A markdown line without trailing newline, or `""` when not applicable.
15
+ */
16
+ export function weakHitAdvisory(avgRelevance, threshold) {
17
+ if (!(threshold > 0) || !(avgRelevance < threshold))
18
+ return "";
19
+ return `_(weak: nothing here cleared the ${threshold.toFixed(2)} floor. Treat these as leads, not as an answer - narrow the query or add \`pathHints\`/\`fileExtensions\`, and verify with \`read\` before concluding anything.)_`;
20
+ }
5
21
  /**
6
22
  * Format RAG retrieval results for the search_semantic tool output.
7
23
  *
@@ -9,9 +9,46 @@ export declare const BEGIN_MARKER = "<!-- BEGIN opencode-rag -->";
9
9
  /** Sentinel marker that closes the managed section. */
10
10
  export declare const END_MARKER = "<!-- END opencode-rag -->";
11
11
  /**
12
- * The always-on mandatory guidance lines — tool list, decision tree,
13
- * proactive triggers, and anti-patterns. Used verbatim by the runtime
14
- * system prompt injector.
12
+ * The positional rules that actually move behaviour. Measured on a live
13
+ * workspace (2026-11-11): a flat wall of ~40 MUST/NEVER lines produced exactly
14
+ * one mandated search in the first turn and abandonment afterwards (47 of 130
15
+ * searching sessions called it once; 43 % of editing sessions never called it),
16
+ * while a single ordering rule - the search goes IN the first tool batch - put
17
+ * 78 % of first searches into user turn 1. Order is therefore stated before the
18
+ * tool list, and this block is the only guidance text the compact AGENTS.md
19
+ * directive carries. Shared verbatim by both carriers, so neither can drift.
20
+ */
21
+ export declare const FIRST_MOVE_LINES: readonly string[];
22
+ /** One-line pointer used by the compact AGENTS.md directive. */
23
+ export declare const FULL_PROTOCOL_POINTER = "The full protocol (decision tree, proactive triggers, anti-patterns) is injected into the system prompt by the plugin - `openCode.injectSystemPrompt`. Do not restate it here.";
24
+ /**
25
+ * How much guidance a generated `AGENTS.md` block carries.
26
+ *
27
+ * - `auto`: compact when the runtime injector will deliver the full protocol
28
+ * anyway, full when it will not. One carrier, one copy.
29
+ * - `full`: the complete protocol in `AGENTS.md` (the pre-2.14 behaviour, and the
30
+ * result when the option is unset) - use it when `injectSystemPrompt` is off or
31
+ * when the file must stand alone (agents without the plugin, CI, humans).
32
+ * - `compact`: always the short form, regardless of the injector.
33
+ */
34
+ export type AgentGuidanceDetail = "auto" | "full" | "compact";
35
+ /**
36
+ * Resolve a configured detail level into a concrete one.
37
+ *
38
+ * An unset level stays `"full"` so callers that know nothing about the injector
39
+ * keep the standalone file they always produced.
40
+ *
41
+ * @param detail - The configured level.
42
+ * @param injectedAtRuntime - Whether `openCode.injectSystemPrompt` will put the
43
+ * full protocol into the system prompt of sessions that have the tools.
44
+ * @returns `"full"` or `"compact"`.
45
+ */
46
+ export declare function resolveAgentsMdDetail(detail: AgentGuidanceDetail | undefined, injectedAtRuntime: boolean): "full" | "compact";
47
+ /**
48
+ * The always-on mandatory guidance lines - tool list, decision tree,
49
+ * proactive triggers, and anti-patterns. The runtime system prompt injector
50
+ * uses these verbatim and additionally puts {@link FIRST_MOVE_LINES} first, so
51
+ * the ordering rule is never buried under the list it governs.
15
52
  */
16
53
  export declare const MANDATORY_GUIDANCE_LINES: readonly string[];
17
54
  /**
@@ -38,12 +75,41 @@ export declare function buildSystemGuidanceLines(opts: {
38
75
  shell?: OpenCodeShellConfig;
39
76
  }): string[];
40
77
  /**
41
- * Build the markdown-formatted AGENTS.md directive section, wrapped in sentinel
78
+ * The complete `AGENTS.md` directive body, without sentinel markers. This is the
79
+ * standalone form and repeats the runtime protocol on purpose: a file that has to
80
+ * work without the plugin (agents that do not load it, CI, a human reading the
81
+ * repo) must carry the whole thing.
82
+ */
83
+ export declare function buildFullAgentsMdLines(opts: {
84
+ promptEnforcement: boolean;
85
+ decisionEnabled?: boolean;
86
+ routeBeforeAsking?: boolean;
87
+ shell?: OpenCodeShellConfig;
88
+ }): string[];
89
+ /**
90
+ * The short `AGENTS.md` directive body: the positional rules plus a tool index
91
+ * and a pointer. Used when the runtime injector already ships the full protocol,
92
+ * so the same ~40 lines do not arrive twice in one request.
93
+ */
94
+ export declare function buildCompactAgentsMdLines(opts: {
95
+ promptEnforcement: boolean;
96
+ decisionEnabled?: boolean;
97
+ routeBeforeAsking?: boolean;
98
+ shell?: OpenCodeShellConfig;
99
+ }): string[];
100
+ /**
101
+ * Build the markdown-formatted `AGENTS.md` directive section, wrapped in sentinel
42
102
  * markers so `mergeAgentsMdContent` can replace it in place on re-runs.
103
+ *
104
+ * @param opts - Section switches plus `agentsMdDetail` (default `"auto"`: compact
105
+ * when the runtime injector is on, full when it is off).
106
+ * @returns The marker-delimited section, without a trailing newline.
43
107
  */
44
108
  export declare function buildAgentsMdDirective(opts: {
45
109
  promptEnforcement: boolean;
46
110
  decisionEnabled?: boolean;
47
111
  routeBeforeAsking?: boolean;
48
112
  shell?: OpenCodeShellConfig;
113
+ agentsMdDetail?: AgentGuidanceDetail;
114
+ injectedAtRuntime?: boolean;
49
115
  }): string;