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.
- 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 +528 -113
- 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;
|