opencode-rag-plugin 2.13.3 → 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.
- package/dist/cli/commands/clickhouse.d.ts +34 -0
- package/dist/cli/commands/clickhouse.js +202 -1
- package/dist/cli/commands/status.js +7 -1
- package/dist/cli/commands/workspace-helpers.d.ts +9 -2
- package/dist/cli/commands/workspace-helpers.js +7 -2
- package/dist/cli/workspace.js +8 -2
- package/dist/core/auto-scaffold.js +7 -1
- package/dist/core/config.d.ts +14 -0
- package/dist/core/config.js +9 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/opencode/read-format.d.ts +12 -0
- package/dist/opencode/read-format.js +16 -0
- package/dist/opencode/system-guidance.d.ts +70 -4
- package/dist/opencode/system-guidance.js +95 -9
- package/dist/plugin.js +19 -5
- package/dist/vectorstore/clickhouse.d.ts +25 -1
- package/dist/vectorstore/clickhouse.js +44 -2
- package/dist/web/config-schema.js +10 -0
- package/package.json +1 -1
|
@@ -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`
|
|
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`
|
|
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`;
|
package/dist/cli/workspace.js
CHANGED
|
@@ -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
|
|
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"), {
|
package/dist/core/config.d.ts
CHANGED
|
@@ -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). */
|
package/dist/core/config.js
CHANGED
|
@@ -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}"
|
|
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
|
|
13
|
-
*
|
|
14
|
-
*
|
|
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
|
-
*
|
|
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;
|
|
@@ -8,9 +8,46 @@ export const BEGIN_MARKER = "<!-- BEGIN opencode-rag -->";
|
|
|
8
8
|
/** Sentinel marker that closes the managed section. */
|
|
9
9
|
export const END_MARKER = "<!-- END opencode-rag -->";
|
|
10
10
|
/**
|
|
11
|
-
* The
|
|
12
|
-
*
|
|
13
|
-
*
|
|
11
|
+
* The positional rules that actually move behaviour. Measured on a live
|
|
12
|
+
* workspace (2026-11-11): a flat wall of ~40 MUST/NEVER lines produced exactly
|
|
13
|
+
* one mandated search in the first turn and abandonment afterwards (47 of 130
|
|
14
|
+
* searching sessions called it once; 43 % of editing sessions never called it),
|
|
15
|
+
* while a single ordering rule - the search goes IN the first tool batch - put
|
|
16
|
+
* 78 % of first searches into user turn 1. Order is therefore stated before the
|
|
17
|
+
* tool list, and this block is the only guidance text the compact AGENTS.md
|
|
18
|
+
* directive carries. Shared verbatim by both carriers, so neither can drift.
|
|
19
|
+
*/
|
|
20
|
+
export const FIRST_MOVE_LINES = [
|
|
21
|
+
"First move, every task: `search_semantic` goes IN the first tool batch - an orientation call may share that batch, it never precedes it.",
|
|
22
|
+
"Re-search when the working area changes: one search per area, not one per task.",
|
|
23
|
+
"Authoritative elsewhere? When another system owns the current copy (source control, an MCP server, a database, an API), fetch it there first - `search_semantic` covers the local mirror and cross-cutting questions.",
|
|
24
|
+
"A weak result is a lead, not an answer: read the printed relevance, then verify with `read` before concluding.",
|
|
25
|
+
];
|
|
26
|
+
/** One-line pointer used by the compact AGENTS.md directive. */
|
|
27
|
+
export 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.";
|
|
28
|
+
/**
|
|
29
|
+
* Resolve a configured detail level into a concrete one.
|
|
30
|
+
*
|
|
31
|
+
* An unset level stays `"full"` so callers that know nothing about the injector
|
|
32
|
+
* keep the standalone file they always produced.
|
|
33
|
+
*
|
|
34
|
+
* @param detail - The configured level.
|
|
35
|
+
* @param injectedAtRuntime - Whether `openCode.injectSystemPrompt` will put the
|
|
36
|
+
* full protocol into the system prompt of sessions that have the tools.
|
|
37
|
+
* @returns `"full"` or `"compact"`.
|
|
38
|
+
*/
|
|
39
|
+
export function resolveAgentsMdDetail(detail, injectedAtRuntime) {
|
|
40
|
+
if (detail === "full" || detail === "compact")
|
|
41
|
+
return detail;
|
|
42
|
+
if (detail === "auto")
|
|
43
|
+
return injectedAtRuntime ? "compact" : "full";
|
|
44
|
+
return "full";
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* The always-on mandatory guidance lines - tool list, decision tree,
|
|
48
|
+
* proactive triggers, and anti-patterns. The runtime system prompt injector
|
|
49
|
+
* uses these verbatim and additionally puts {@link FIRST_MOVE_LINES} first, so
|
|
50
|
+
* the ordering rule is never buried under the list it governs.
|
|
14
51
|
*/
|
|
15
52
|
export const MANDATORY_GUIDANCE_LINES = [
|
|
16
53
|
"MANDATORY: OpenCodeRAG tools MUST be used before any code task:",
|
|
@@ -97,6 +134,9 @@ export function buildShellBackgroundGuidanceLines(shell) {
|
|
|
97
134
|
}
|
|
98
135
|
export function buildSystemGuidanceLines(opts) {
|
|
99
136
|
const lines = [...MANDATORY_GUIDANCE_LINES];
|
|
137
|
+
// Positional rules go directly under the headline: the injector used to lead
|
|
138
|
+
// with a 40-line list, and the ordering rule got skimmed (see FIRST_MOVE_LINES).
|
|
139
|
+
lines.splice(1, 0, "", ...FIRST_MOVE_LINES);
|
|
100
140
|
if (opts.decisionEnabled) {
|
|
101
141
|
const decisionLines = [...DECISION_GUIDANCE_LINES];
|
|
102
142
|
if (opts.routeBeforeAsking) {
|
|
@@ -133,12 +173,13 @@ const DECISION_AGENTS_SECTION_LINES = [
|
|
|
133
173
|
/** Extra directive bullet, only when `decision.routeBeforeAsking` is enabled. */
|
|
134
174
|
const DECISION_ROUTING_AGENTS_LINE = "- With `decision.routeBeforeAsking` enabled: route option choices through `make_decision` before asking the user; ask the user only when the model is undecided (low confidence) or the choice is preference-based.";
|
|
135
175
|
/**
|
|
136
|
-
*
|
|
137
|
-
*
|
|
176
|
+
* The complete `AGENTS.md` directive body, without sentinel markers. This is the
|
|
177
|
+
* standalone form and repeats the runtime protocol on purpose: a file that has to
|
|
178
|
+
* work without the plugin (agents that do not load it, CI, a human reading the
|
|
179
|
+
* repo) must carry the whole thing.
|
|
138
180
|
*/
|
|
139
|
-
export function
|
|
181
|
+
export function buildFullAgentsMdLines(opts) {
|
|
140
182
|
const lines = [
|
|
141
|
-
BEGIN_MARKER,
|
|
142
183
|
"## Code Navigation",
|
|
143
184
|
"",
|
|
144
185
|
"ALWAYS use OpenCodeRAG tools before reading or editing:",
|
|
@@ -201,7 +242,52 @@ export function buildAgentsMdDirective(opts) {
|
|
|
201
242
|
if (shellLines.length > 0) {
|
|
202
243
|
lines.push("", "### Long-running commands", ...shellLines.filter((l) => l.trim().length > 0));
|
|
203
244
|
}
|
|
204
|
-
lines
|
|
205
|
-
|
|
245
|
+
return lines;
|
|
246
|
+
}
|
|
247
|
+
/**
|
|
248
|
+
* The short `AGENTS.md` directive body: the positional rules plus a tool index
|
|
249
|
+
* and a pointer. Used when the runtime injector already ships the full protocol,
|
|
250
|
+
* so the same ~40 lines do not arrive twice in one request.
|
|
251
|
+
*/
|
|
252
|
+
export function buildCompactAgentsMdLines(opts) {
|
|
253
|
+
const lines = [
|
|
254
|
+
"## Code Navigation",
|
|
255
|
+
"",
|
|
256
|
+
"OpenCodeRAG indexes this workspace.",
|
|
257
|
+
"",
|
|
258
|
+
...FIRST_MOVE_LINES.map((line) => `- ${line}`),
|
|
259
|
+
"",
|
|
260
|
+
"Tools: `search_semantic` finds code by meaning - use it before grep; `get_file_skeleton` before reading a file; `find_usages` before editing a symbol; `describe_image` for images, never raw bytes; `recall_quirks` / `add_quirk` / `update_quirk` / `delete_quirk` for experiential memory. Signatures live in the tool schema, not here.",
|
|
261
|
+
"",
|
|
262
|
+
"A search that returns nothing useful usually means the workspace is not indexed: run `opencode-rag index` (or `opencode-rag status` to check).",
|
|
263
|
+
];
|
|
264
|
+
if (opts.decisionEnabled) {
|
|
265
|
+
lines.push("", opts.routeBeforeAsking
|
|
266
|
+
? "`make_decision(state, questions)` classifies/routes/scores short text with the local decision model; with `decision.routeBeforeAsking` set, route option choices through it before asking the user."
|
|
267
|
+
: "`make_decision(state, questions)` classifies/routes/scores short text with the local decision model; never as the only check for a high-stakes decision.");
|
|
268
|
+
}
|
|
269
|
+
if (opts.promptEnforcement) {
|
|
270
|
+
lines.push("", "Quirks: call `add_quirk` after resolving a failed build/test/type-check, an undocumented constraint, or a gotcha that cost more than one attempt; `update_quirk`/`delete_quirk` instead of storing a contradicting duplicate.");
|
|
271
|
+
}
|
|
272
|
+
const shellLines = buildShellBackgroundGuidanceLines(opts.shell);
|
|
273
|
+
if (shellLines.length > 0) {
|
|
274
|
+
// Same heading as the full form; the plain in-list title is dropped.
|
|
275
|
+
lines.push("", "### Long-running commands", ...shellLines.filter((l) => l.trim().length > 0).slice(1));
|
|
276
|
+
}
|
|
277
|
+
lines.push("", FULL_PROTOCOL_POINTER);
|
|
278
|
+
return lines;
|
|
279
|
+
}
|
|
280
|
+
/**
|
|
281
|
+
* Build the markdown-formatted `AGENTS.md` directive section, wrapped in sentinel
|
|
282
|
+
* markers so `mergeAgentsMdContent` can replace it in place on re-runs.
|
|
283
|
+
*
|
|
284
|
+
* @param opts - Section switches plus `agentsMdDetail` (default `"auto"`: compact
|
|
285
|
+
* when the runtime injector is on, full when it is off).
|
|
286
|
+
* @returns The marker-delimited section, without a trailing newline.
|
|
287
|
+
*/
|
|
288
|
+
export function buildAgentsMdDirective(opts) {
|
|
289
|
+
const detail = resolveAgentsMdDetail(opts.agentsMdDetail, opts.injectedAtRuntime !== false);
|
|
290
|
+
const body = detail === "compact" ? buildCompactAgentsMdLines(opts) : buildFullAgentsMdLines(opts);
|
|
291
|
+
return [BEGIN_MARKER, ...body, END_MARKER].join("\n");
|
|
206
292
|
}
|
|
207
293
|
//# sourceMappingURL=system-guidance.js.map
|
package/dist/plugin.js
CHANGED
|
@@ -36,6 +36,7 @@ import { detectOutputError, detectSessionError, extractExitCode, } from "./quirk
|
|
|
36
36
|
import { createToolErrorInjectionState, recallToolErrorQuirks, formatToolErrorQuirkBlock, toToolErrorCaptureEntry, } from "./quirks/tool-error-recall.js";
|
|
37
37
|
import { buildToolErrorQuirkContent, classifyToolErrorCause, createToolErrorCreateState, createToolErrorQuirk, formatToolGotchaBlock, hasEquivalentToolGotcha, selectToolGotchas, TOOL_ERROR_CREATE_DEFAULTS, TOOL_ERROR_QUIRK_TAG, } from "./quirks/tool-error-create.js";
|
|
38
38
|
import { buildSystemGuidanceLines } from "./opencode/system-guidance.js";
|
|
39
|
+
import { weakHitAdvisory } from "./opencode/read-format.js";
|
|
39
40
|
import { describeAutoInjectSelection, formatAutoInjectBlock, selectAutoInjectQuirksWithinBudget, } from "./quirks/auto-inject.js";
|
|
40
41
|
import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
|
|
41
42
|
import path from "node:path";
|
|
@@ -417,13 +418,25 @@ export function createLiveEmbedder(getConfig, create, initial) {
|
|
|
417
418
|
/**
|
|
418
419
|
* Format retrieval results into a Markdown context block for LLM injection.
|
|
419
420
|
* Includes per-chunk file paths, line numbers, relevance scores, and descriptions.
|
|
421
|
+
*
|
|
422
|
+
* A block whose average relevance sits under `weakHitThreshold` is labelled
|
|
423
|
+
* inline. Without the label a mandated search that returns near-noise reads as an
|
|
424
|
+
* answer, which is how the tool earns a reputation it does not deserve (measured
|
|
425
|
+
* on one workspace: 11 % of searches came back under 0.35 and the agent stopped
|
|
426
|
+
* calling the tool, not because it failed but because it looked pointless).
|
|
427
|
+
*
|
|
428
|
+
* @param results - Retrieval results, best first.
|
|
429
|
+
* @param weakHitThreshold - Average-relevance floor for the label; `0` disables it.
|
|
420
430
|
*/
|
|
421
|
-
function formatContext(results) {
|
|
431
|
+
function formatContext(results, weakHitThreshold = 0.5) {
|
|
422
432
|
if (results.length === 0)
|
|
423
433
|
return "";
|
|
424
434
|
const avgScore = results.reduce((sum, r) => sum + r.score, 0) / results.length;
|
|
425
435
|
const parts = [];
|
|
426
436
|
parts.push(`\n**${CONTEXT_MARKER}** _(context: ${results.length} chunks, avg relevance: ${avgScore.toFixed(2)})_\n`);
|
|
437
|
+
const advisory = weakHitAdvisory(avgScore, weakHitThreshold);
|
|
438
|
+
if (advisory)
|
|
439
|
+
parts.push(`${advisory}\n`);
|
|
427
440
|
parts.push("---\n");
|
|
428
441
|
for (const r of results) {
|
|
429
442
|
const m = r.chunk.metadata;
|
|
@@ -771,9 +784,10 @@ export function createRagHooks(options) {
|
|
|
771
784
|
}
|
|
772
785
|
const retrievalTool = tool({
|
|
773
786
|
description: "Search the indexed codebase by meaning, not just keywords. " +
|
|
774
|
-
"
|
|
775
|
-
"
|
|
776
|
-
"
|
|
787
|
+
"Call it IN the first tool batch of any code task - before planning, reading, or answering - and again when the working area changes. " +
|
|
788
|
+
"Prefer it over grep for 'where is X' / 'how does X work' questions; grep stays right for an exact identifier you already have. " +
|
|
789
|
+
"Exception: when another system owns the current copy (source control, an MCP server, a database, an API), fetch it there first - this index covers the local mirror. " +
|
|
790
|
+
"Returns the most relevant code snippets with file paths, line numbers, and relevance scores; a low average score means the query was wrong, not that the code is missing.",
|
|
777
791
|
args: {
|
|
778
792
|
query: tool.schema.string().min(1, "A retrieval query is required."),
|
|
779
793
|
pathHints: tool.schema.array(tool.schema.string().min(1)).max(10).optional(),
|
|
@@ -832,7 +846,7 @@ export function createRagHooks(options) {
|
|
|
832
846
|
},
|
|
833
847
|
};
|
|
834
848
|
}
|
|
835
|
-
const output = formatContext(results);
|
|
849
|
+
const output = formatContext(results, getEffectiveCfg().openCode.weakHitThreshold ?? 0.5);
|
|
836
850
|
appendVerboseLog(options.logFilePath, CONTEXT_TOOL_NAME, "retrieval completed successfully", {
|
|
837
851
|
query,
|
|
838
852
|
pathHints: args.pathHints ?? [],
|
|
@@ -24,8 +24,32 @@ export interface ResolvedClickHouseOptions {
|
|
|
24
24
|
}
|
|
25
25
|
/** Sanitize a namespace so it is safe as a table suffix. */
|
|
26
26
|
export declare function sanitizeNamespace(raw: string): string;
|
|
27
|
-
/**
|
|
27
|
+
/**
|
|
28
|
+
* Canonical form of a workspace path for namespace derivation.
|
|
29
|
+
*
|
|
30
|
+
* On Windows `path.resolve()` keeps the drive letter exactly as the caller
|
|
31
|
+
* spelled it, so `C:\repo` and `c:\repo` derived two different namespaces and one
|
|
32
|
+
* repository got indexed twice - one copy quietly going stale (measured
|
|
33
|
+
* 2026-11-11: `chunks_SLVSCODE_b2041fa6` current, `chunks_SLVSCODE_722a9877` five
|
|
34
|
+
* days behind and still serving a config file the repository had deleted). Windows
|
|
35
|
+
* paths are case-insensitive, so the drive letter is canonicalized here. The rest
|
|
36
|
+
* of the path is deliberately NOT lowercased: that would re-hash every existing
|
|
37
|
+
* deployment and silently orphan a populated index. A directory segment spelled
|
|
38
|
+
* differently still lands in its own namespace - `opencode-rag status` and
|
|
39
|
+
* `clickhouse adopt` surface those siblings instead of guessing.
|
|
40
|
+
*/
|
|
41
|
+
export declare function canonicalizeWorkspacePath(workspaceDir: string): string;
|
|
42
|
+
/** Derive a stable namespace from a workspace path (name + canonical path hash). */
|
|
28
43
|
export declare function deriveNamespace(workspaceDir: string): string;
|
|
44
|
+
/**
|
|
45
|
+
* Namespaces this workspace COULD have been indexed under before the drive letter
|
|
46
|
+
* was canonicalized. Lets a tool tell the operator "your index is alive, under
|
|
47
|
+
* this other name - adopt it" instead of starting from zero.
|
|
48
|
+
*
|
|
49
|
+
* @param workspaceDir - The workspace path as the caller has it.
|
|
50
|
+
* @returns Namespace strings, canonical form excluded, deduplicated.
|
|
51
|
+
*/
|
|
52
|
+
export declare function legacyNamespaceVariants(workspaceDir: string): string[];
|
|
29
53
|
/** Resolve a full ClickHouse config block (with defaults) for a workspace. */
|
|
30
54
|
export declare function resolveClickHouseOptions(config: RagConfig, workspaceDir: string): ResolvedClickHouseOptions;
|
|
31
55
|
/**
|
|
@@ -39,13 +39,55 @@ export function sanitizeNamespace(raw) {
|
|
|
39
39
|
.slice(0, 40);
|
|
40
40
|
return cleaned.length > 0 ? cleaned : "default";
|
|
41
41
|
}
|
|
42
|
-
/**
|
|
43
|
-
|
|
42
|
+
/**
|
|
43
|
+
* Canonical form of a workspace path for namespace derivation.
|
|
44
|
+
*
|
|
45
|
+
* On Windows `path.resolve()` keeps the drive letter exactly as the caller
|
|
46
|
+
* spelled it, so `C:\repo` and `c:\repo` derived two different namespaces and one
|
|
47
|
+
* repository got indexed twice - one copy quietly going stale (measured
|
|
48
|
+
* 2026-11-11: `chunks_SLVSCODE_b2041fa6` current, `chunks_SLVSCODE_722a9877` five
|
|
49
|
+
* days behind and still serving a config file the repository had deleted). Windows
|
|
50
|
+
* paths are case-insensitive, so the drive letter is canonicalized here. The rest
|
|
51
|
+
* of the path is deliberately NOT lowercased: that would re-hash every existing
|
|
52
|
+
* deployment and silently orphan a populated index. A directory segment spelled
|
|
53
|
+
* differently still lands in its own namespace - `opencode-rag status` and
|
|
54
|
+
* `clickhouse adopt` surface those siblings instead of guessing.
|
|
55
|
+
*/
|
|
56
|
+
export function canonicalizeWorkspacePath(workspaceDir) {
|
|
44
57
|
const absolute = path.resolve(workspaceDir);
|
|
58
|
+
if (process.platform !== "win32")
|
|
59
|
+
return absolute;
|
|
60
|
+
return absolute.replace(/^([a-z])(:)/, (_m, drive, sep) => drive.toUpperCase() + sep);
|
|
61
|
+
}
|
|
62
|
+
/** Derive a stable namespace from a workspace path (name + canonical path hash). */
|
|
63
|
+
export function deriveNamespace(workspaceDir) {
|
|
64
|
+
const absolute = canonicalizeWorkspacePath(workspaceDir);
|
|
45
65
|
const base = path.basename(absolute) || "workspace";
|
|
46
66
|
const hash = createHash("sha1").update(absolute).digest("hex").slice(0, 8);
|
|
47
67
|
return sanitizeNamespace(`${base}_${hash}`);
|
|
48
68
|
}
|
|
69
|
+
/**
|
|
70
|
+
* Namespaces this workspace COULD have been indexed under before the drive letter
|
|
71
|
+
* was canonicalized. Lets a tool tell the operator "your index is alive, under
|
|
72
|
+
* this other name - adopt it" instead of starting from zero.
|
|
73
|
+
*
|
|
74
|
+
* @param workspaceDir - The workspace path as the caller has it.
|
|
75
|
+
* @returns Namespace strings, canonical form excluded, deduplicated.
|
|
76
|
+
*/
|
|
77
|
+
export function legacyNamespaceVariants(workspaceDir) {
|
|
78
|
+
const canonical = deriveNamespace(workspaceDir);
|
|
79
|
+
const raw = path.resolve(workspaceDir);
|
|
80
|
+
const spellings = new Set([raw, raw.charAt(0).toLowerCase() + raw.slice(1), raw.charAt(0).toUpperCase() + raw.slice(1)]);
|
|
81
|
+
const out = [];
|
|
82
|
+
for (const spelling of spellings) {
|
|
83
|
+
const base = path.basename(spelling) || "workspace";
|
|
84
|
+
const hash = createHash("sha1").update(spelling).digest("hex").slice(0, 8);
|
|
85
|
+
const ns = sanitizeNamespace(`${base}_${hash}`);
|
|
86
|
+
if (ns !== canonical && !out.includes(ns))
|
|
87
|
+
out.push(ns);
|
|
88
|
+
}
|
|
89
|
+
return out;
|
|
90
|
+
}
|
|
49
91
|
/** Resolve a full ClickHouse config block (with defaults) for a workspace. */
|
|
50
92
|
export function resolveClickHouseOptions(config, workspaceDir) {
|
|
51
93
|
const ch = config.vectorStore.clickhouse;
|
|
@@ -789,6 +789,16 @@ export const SETTINGS_SECTIONS = [
|
|
|
789
789
|
boolean(["openCode", "injectSystemPrompt"], "Inject RAG guidance", {
|
|
790
790
|
description: "Add a short block describing the RAG tools and their intended workflow to the system prompt.",
|
|
791
791
|
}),
|
|
792
|
+
enumField(["openCode", "agentsMdDetail"], "AGENTS.md guidance size", ["auto", "full", "compact"], {
|
|
793
|
+
impact: "restart",
|
|
794
|
+
description: "How much of the tool protocol `AGENTS.md` carries. \"auto\" writes the short form when the system prompt already delivers the full protocol, so the same rules do not arrive twice per turn.",
|
|
795
|
+
}),
|
|
796
|
+
number(["openCode", "weakHitThreshold"], "Weak-hit label floor", {
|
|
797
|
+
minimum: 0,
|
|
798
|
+
maximum: 1,
|
|
799
|
+
step: 0.05,
|
|
800
|
+
description: "Average relevance below which a search result is labelled weak, telling the agent the hits are leads to verify. 0 disables the label.",
|
|
801
|
+
}),
|
|
792
802
|
boolean(["openCode", "exploreAgentTools"], "Give explore agent RAG tools", {
|
|
793
803
|
description: "Grant the built-in explore agent access to the RAG tools so it can search semantically.",
|
|
794
804
|
}),
|