opencode-rag-plugin 2.2.1 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/dist/api.js +2 -0
  2. package/dist/chunker/factory.js +48 -18
  3. package/dist/chunker/image.js +6 -0
  4. package/dist/cli/commands/clear.js +21 -1
  5. package/dist/cli/commands/query.js +6 -0
  6. package/dist/cli/commands/status.js +4 -0
  7. package/dist/core/bootstrap.d.ts +3 -1
  8. package/dist/core/bootstrap.js +5 -0
  9. package/dist/core/config.d.ts +69 -1
  10. package/dist/core/config.js +63 -1
  11. package/dist/core/interfaces.d.ts +34 -0
  12. package/dist/describer/describer.js +9 -1
  13. package/dist/embedder/factory.d.ts +5 -1
  14. package/dist/embedder/factory.js +76 -6
  15. package/dist/embedder/health.d.ts +1 -1
  16. package/dist/embedder/health.js +43 -0
  17. package/dist/eval/rerank-eval.d.ts +45 -0
  18. package/dist/eval/rerank-eval.js +581 -0
  19. package/dist/indexer/pipeline.d.ts +17 -0
  20. package/dist/indexer/pipeline.js +123 -3
  21. package/dist/indexer/stats.d.ts +7 -0
  22. package/dist/mcp/handlers.js +3 -0
  23. package/dist/opencode/create-read-tool.js +5 -2
  24. package/dist/plugin.js +67 -6
  25. package/dist/quirks/quirk-store.d.ts +1 -0
  26. package/dist/quirks/quirk-store.js +1 -1
  27. package/dist/quirks/tool-error-recall.d.ts +112 -0
  28. package/dist/quirks/tool-error-recall.js +144 -0
  29. package/dist/reranker/base.d.ts +47 -0
  30. package/dist/reranker/base.js +73 -0
  31. package/dist/reranker/factory.d.ts +16 -0
  32. package/dist/reranker/factory.js +47 -0
  33. package/dist/reranker/llama-server.d.ts +33 -0
  34. package/dist/reranker/llama-server.js +101 -0
  35. package/dist/retriever/keyword-index.d.ts +1 -0
  36. package/dist/retriever/keyword-index.js +1 -1
  37. package/dist/retriever/retriever.d.ts +24 -1
  38. package/dist/retriever/retriever.js +69 -5
  39. package/dist/types/opencode-plugin.d.ts +2 -2
  40. package/dist/v2/v2-adapter.d.ts +6 -1
  41. package/dist/v2/v2-adapter.js +52 -8
  42. package/dist/vectorstore/lancedb.d.ts +1 -1
  43. package/dist/vectorstore/lancedb.js +43 -7
  44. package/dist/web/api.js +5 -0
  45. package/dist/web/ui/assets/index-C0QXKA-b.js +4 -0
  46. package/dist/web/ui/assets/index-Dp009QCQ.css +1 -0
  47. package/dist/web/ui/index.html +2 -2
  48. package/package.json +1 -1
  49. package/dist/web/ui/assets/index-Cgv1RsGv.js +0 -4
  50. package/dist/web/ui/assets/index-DjJHIo9R.css +0 -1
package/dist/api.js CHANGED
@@ -56,6 +56,8 @@ export async function search(query, options = {}) {
56
56
  hybridEnabled: ctx.config.retrieval.hybridSearch?.enabled,
57
57
  queryPrefix: ctx.config.embedding.queryPrefix,
58
58
  explain: options.explain,
59
+ reranker: ctx.reranker,
60
+ reranking: ctx.config.reranking,
59
61
  filter: {
60
62
  pathPatterns: options.pathHints,
61
63
  languages: options.languageHints,
@@ -240,27 +240,57 @@ function splitOversized(chunks, filePath, maxLines = MAX_CHUNK_LINES, maxChars =
240
240
  let currentLines = [];
241
241
  let currentCharCount = 0;
242
242
  let lineOffset = 0;
243
+ const flushWindow = (endLineExclusive) => {
244
+ if (currentLines.length === 0)
245
+ return;
246
+ subChunks.push({
247
+ id: uuid(),
248
+ content: currentLines.join("\n"),
249
+ metadata: {
250
+ filePath,
251
+ startLine: chunk.metadata.startLine + lineOffset,
252
+ endLine: chunk.metadata.startLine + endLineExclusive - 1,
253
+ language: chunk.metadata.language,
254
+ },
255
+ });
256
+ // Seed the next window with the last `overlap` lines so split chunks
257
+ // still share their boundary context.
258
+ const tail = overlap > 0 ? currentLines.slice(Math.max(0, currentLines.length - overlap)) : [];
259
+ currentLines = [...tail];
260
+ currentCharCount = tail.reduce((sum, l) => sum + l.length + 1, 0);
261
+ lineOffset = endLineExclusive - tail.length;
262
+ };
243
263
  for (let i = 0; i < lines.length; i++) {
244
264
  const line = lines[i];
245
265
  const lineLen = line.length + 1;
266
+ // A single line longer than the character budget cannot be split at
267
+ // line boundaries. Hard-wrap it by characters so no chunk exceeds
268
+ // maxChars -- otherwise minified bundles (one long line) become
269
+ // whole-file chunks that exceed the embedding model's context size.
270
+ if (maxChars > 0 && line.length > maxChars) {
271
+ flushWindow(i);
272
+ // The wrapped slices must stay within the character budget, so the
273
+ // overlap lines seeded by flushWindow are intentionally not reused.
274
+ currentLines = [];
275
+ currentCharCount = 0;
276
+ for (let start = 0; start < line.length; start += maxChars) {
277
+ subChunks.push({
278
+ id: uuid(),
279
+ content: line.slice(start, start + maxChars),
280
+ metadata: {
281
+ filePath,
282
+ startLine: chunk.metadata.startLine + i,
283
+ endLine: chunk.metadata.startLine + i,
284
+ language: chunk.metadata.language,
285
+ },
286
+ });
287
+ }
288
+ lineOffset = i + 1;
289
+ continue;
290
+ }
246
291
  if (currentLines.length > 0 &&
247
292
  (currentLines.length >= maxLines || currentCharCount + lineLen > maxChars)) {
248
- subChunks.push({
249
- id: uuid(),
250
- content: currentLines.join("\n"),
251
- metadata: {
252
- filePath,
253
- startLine: chunk.metadata.startLine + lineOffset,
254
- endLine: chunk.metadata.startLine + i - 1,
255
- language: chunk.metadata.language,
256
- },
257
- });
258
- // Seed the next window with the last `overlap` lines so split chunks
259
- // still share their boundary context.
260
- const tail = overlap > 0 ? currentLines.slice(Math.max(0, currentLines.length - overlap)) : [];
261
- currentLines = [...tail];
262
- currentCharCount = tail.reduce((sum, l) => sum + l.length + 1, 0);
263
- lineOffset = i - tail.length;
293
+ flushWindow(i);
264
294
  }
265
295
  currentLines.push(line);
266
296
  currentCharCount += lineLen;
@@ -333,9 +363,9 @@ export async function chunkFile(filePath, content, nodeTypesOverrides, options)
333
363
  chunker = withByteLimit(chunker, options.maxSvgSizeBytes);
334
364
  }
335
365
  }
336
- const chunks = await chunker.chunk(filePath, content);
366
+ let chunks = await chunker.chunk(filePath, content);
337
367
  if (chunks.length === 0) {
338
- return fallbackChunker.chunk(filePath, content);
368
+ chunks = await fallbackChunker.chunk(filePath, content);
339
369
  }
340
370
  const overlap = Math.max(0, options?.chunkOverlap ?? 0);
341
371
  const maxLines = options?.maxChunkSize && options.maxChunkSize > 0 ? options.maxChunkSize : MAX_CHUNK_LINES;
@@ -118,6 +118,7 @@ class OpenAIImageVisionProvider {
118
118
  apiKey;
119
119
  timeoutMs;
120
120
  extraHeaders;
121
+ think;
121
122
  proxy;
122
123
  constructor(config, extraHeaders) {
123
124
  this.baseUrl = config.baseUrl.replace(/\/+$/, "");
@@ -125,6 +126,7 @@ class OpenAIImageVisionProvider {
125
126
  this.apiKey = config.apiKey ?? "";
126
127
  this.timeoutMs = config.timeoutMs;
127
128
  this.extraHeaders = extraHeaders ?? {};
129
+ this.think = config.think;
128
130
  this.proxy = config.proxy;
129
131
  }
130
132
  async describeImage(imageBase64, mimeType, prompt, systemPrompt, abort) {
@@ -147,6 +149,10 @@ class OpenAIImageVisionProvider {
147
149
  model: this.model,
148
150
  messages,
149
151
  max_tokens: 2048,
152
+ // Reasoning models (Qwen3.x / Ornith etc.) think before answering; honor
153
+ // `think: false` for OpenAI-compatible providers by forwarding
154
+ // chat_template_kwargs (llama.cpp / vLLM convention).
155
+ ...(this.think === false ? { chat_template_kwargs: { enable_thinking: false } } : {}),
150
156
  };
151
157
  const headers = {
152
158
  ...this.extraHeaders,
@@ -9,6 +9,7 @@ import path from "node:path";
9
9
  import readline from "node:readline";
10
10
  import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo } from "../format.js";
11
11
  import { manifestPathFor } from "../../core/manifest.js";
12
+ import { indexPathFor } from "../../retriever/keyword-index.js";
12
13
  /**
13
14
  * Prompt the user for a yes/no answer via the terminal.
14
15
  * Returns `true` for "y", `false` for "n", and `undefined` on EOF.
@@ -69,8 +70,27 @@ export function registerClearCommand(program) {
69
70
  }
70
71
  logCliInfo(logFilePath, "clear", `${c.label("Clearing")} ${c.num(prevCount)} indexed chunks...`);
71
72
  await store.clear();
73
+ // Trust, but verify: an interrupted clear used to leave the store AND
74
+ // the manifest completely untouched while printing nothing after the
75
+ // "Clearing…" line. Only drop the manifest/keyword index once the
76
+ // table is provably empty, so a failed clear cannot desynchronise them.
77
+ let remaining;
78
+ try {
79
+ remaining = await store.count();
80
+ }
81
+ catch (err) {
82
+ logCliError(logFilePath, "clear", `\nClear could not be verified: ${err.message}. Manifest and keyword index were left in place.`, err);
83
+ await cleanupContext(ctx);
84
+ process.exit(1);
85
+ }
86
+ if (remaining > 0) {
87
+ logCliError(logFilePath, "clear", `\nClear incomplete: ${remaining} of ${prevCount} chunks are still stored (interrupted, or the store is held open by another process). Manifest and keyword index were left in place.`);
88
+ await cleanupContext(ctx);
89
+ process.exit(1);
90
+ }
72
91
  await fs.unlink(manifestPathFor(ctx.storePath)).catch(() => { });
73
- logCliInfo(logFilePath, "clear", `${c.success("Done.")} vector database cleared.`);
92
+ await fs.unlink(indexPathFor(ctx.storePath)).catch(() => { });
93
+ logCliInfo(logFilePath, "clear", `${c.success("Done.")} vector database cleared (was ${c.num(prevCount)} chunks); manifest and keyword index removed.`);
74
94
  await cleanupContext(ctx);
75
95
  }
76
96
  catch (err) {
@@ -8,6 +8,7 @@ import path from "node:path";
8
8
  import pc from "picocolors";
9
9
  import { CODE_SEARCH_FILTER } from "../../core/interfaces.js";
10
10
  import { retrieve } from "../../retriever/retriever.js";
11
+ import { getRerankerFor } from "../../reranker/factory.js";
11
12
  import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo, formatDuration } from "../format.js";
12
13
  import { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "../../retriever/context-optimizer.js";
13
14
  /**
@@ -54,6 +55,8 @@ export function registerQueryCommand(program) {
54
55
  keywordWeight: hybridCfg?.keywordWeight,
55
56
  hybridEnabled: hybridCfg?.enabled,
56
57
  queryPrefix: config.embedding.queryPrefix,
58
+ reranker: getRerankerFor(config.reranking) ?? undefined,
59
+ reranking: config.reranking,
57
60
  explain: options.explain ?? false,
58
61
  filter: CODE_SEARCH_FILTER,
59
62
  });
@@ -72,6 +75,9 @@ export function registerQueryCommand(program) {
72
75
  if (r.explanation) {
73
76
  const sb = r.explanation.scoreBreakdown;
74
77
  logCliInfo(logFilePath, "query", ` ${c.label(" Vector:")} ${c.score(sb.rawVectorScore.toFixed(4))} ${c.label("Keyword:")} ${c.score(sb.rawKeywordScore.toFixed(4))} ${c.label("KW weight:")} ${sb.keywordWeight.toFixed(2)}`);
78
+ if (sb.rerankScore !== undefined) {
79
+ logCliInfo(logFilePath, "query", ` ${c.label(" Rerank:")} ${c.score(sb.rerankScore.toFixed(4))}`);
80
+ }
75
81
  if (r.explanation.matchedTerms && r.explanation.matchedTerms.length > 0) {
76
82
  logCliInfo(logFilePath, "query", ` ${c.label(" Matched:")} ${c.lang(r.explanation.matchedTerms.join(", "))}`);
77
83
  }
@@ -100,6 +100,10 @@ export function registerStatusCommand(program) {
100
100
  logCliInfo(logFilePath, "status", `${c.label("Pending files:")} ${c.num(summary.pendingFiles)}`);
101
101
  logCliInfo(logFilePath, "status", `${c.label("Indexed chunks:")} ${c.num(summary.storeChunkCount)}`);
102
102
  logCliInfo(logFilePath, "status", `${c.label("Expected chunks:")} ${c.num(summary.manifestExpectedChunks)}`);
103
+ logCliInfo(logFilePath, "status", `${c.label("Orphan chunks:")} ${c.num(summary.orphanChunks)}`);
104
+ if (summary.orphanChunks > 0) {
105
+ logCliInfo(logFilePath, "status", `${c.label("Unaccounted rows:")} ${c.warn("yes")} — stored chunks no manifest entry owns (files whose embedding never completed). Run 'opencode-rag index' to sweep them.`);
106
+ }
103
107
  // Read watcher status from the background auto-indexer
104
108
  const watcherStatusPath = path.join(storePath, "watcher-status.json");
105
109
  let watchModeDisplay;
@@ -3,7 +3,7 @@
3
3
  * creates embedder, vector store, keyword index, and description provider.
4
4
  */
5
5
  import { type RagConfig } from "./config.js";
6
- import type { EmbeddingProvider, VectorStore, KeywordIndex as IKeywordIndex, DescriptionProvider } from "./interfaces.js";
6
+ import type { EmbeddingProvider, RerankProvider, VectorStore, KeywordIndex as IKeywordIndex, DescriptionProvider } from "./interfaces.js";
7
7
  /** Options for bootstrapping the RAG pipeline context. */
8
8
  export interface BootstrapOptions {
9
9
  /** Working directory for resolving config and store paths. Defaults to process.cwd(). */
@@ -31,6 +31,8 @@ export interface RagContext {
31
31
  keywordIndex: IKeywordIndex;
32
32
  /** Optional LLM-based description provider. */
33
33
  descriptionProvider?: DescriptionProvider;
34
+ /** Cross-encoder reranker for the retrieval stage (undefined when disabled). */
35
+ reranker?: RerankProvider;
34
36
  /** Detected embedding dimension. */
35
37
  dimension: number;
36
38
  /** Resolved path to the debug log file. */
@@ -9,6 +9,7 @@ import { loadChunkersFromConfig } from "../chunker/loader.js";
9
9
  import { createEmbedder, probeEmbeddingDimension } from "../embedder/factory.js";
10
10
  import { createDescriptionProvider } from "../describer/factory.js";
11
11
  import { createVectorStore } from "../vectorstore/factory.js";
12
+ import { getRerankerFor } from "../reranker/factory.js";
12
13
  import { readStoreDimension } from "../vectorstore/lancedb.js";
13
14
  import { KeywordIndex } from "../retriever/keyword-index.js";
14
15
  import { reconcileQuirks } from "../quirks/quirk-store.js";
@@ -119,6 +120,9 @@ export async function resolveRagContext(opts = {}) {
119
120
  const descriptionProvider = descriptionConfig?.enabled
120
121
  ? createDescriptionProvider(descriptionConfig)
121
122
  : undefined;
123
+ // Optional cross-encoder reranker (process-wide singleton per endpoint so
124
+ // cooldown + score cache survive across retrievals). Null/disabled by default.
125
+ const reranker = getRerankerFor(cfg.reranking) ?? undefined;
122
126
  return {
123
127
  config: cfg,
124
128
  embedder,
@@ -126,6 +130,7 @@ export async function resolveRagContext(opts = {}) {
126
130
  storePath,
127
131
  keywordIndex,
128
132
  descriptionProvider,
133
+ reranker,
129
134
  dimension,
130
135
  logFilePath,
131
136
  configPath,
@@ -75,7 +75,14 @@ export interface DescriptionConfig {
75
75
  retryMax?: number;
76
76
  /** Base delay in ms between retries (exponential backoff). */
77
77
  retryBaseDelayMs?: number;
78
- /** Whether to include chain-of-thought tokens in the response. */
78
+ /**
79
+ * Whether the model may emit chain-of-thought tokens before the answer.
80
+ * For the Ollama provider this sets the `think` request field. For
81
+ * OpenAI-compatible providers `false` forwards
82
+ * `chat_template_kwargs.enable_thinking=false` (llama.cpp / vLLM
83
+ * convention); without it, reasoning models spend thousands of extra
84
+ * tokens per description and indexing runs ~50x slower.
85
+ */
79
86
  think?: boolean;
80
87
  /** Context window size for the LLM. */
81
88
  numCtx?: number;
@@ -208,6 +215,24 @@ export interface MemoryConfig {
208
215
  autoCaptureMaxPerTurn: number;
209
216
  /** Lexical similarity threshold (0-1) above which a candidate is considered a duplicate and skipped. */
210
217
  autoCaptureDedupThreshold: number;
218
+ /**
219
+ * Inject matching quirks into the next model request after a FAILED tool call
220
+ * (default true). Failed calls are also appended to the auto-capture pipeline,
221
+ * so recurring errors can become quirks.
222
+ */
223
+ injectOnToolError: boolean;
224
+ /** Minimum relevance score (0-1) for a quirk to be injected after a tool error (default 0.7). */
225
+ toolErrorMinScore: number;
226
+ /** Max quirks injected per tool error (default 2). */
227
+ toolErrorTopK: number;
228
+ /** Minimum shared word tokens (>=3 chars) between a quirk and the error text; 0 disables (default 1). */
229
+ toolErrorMinTokenOverlap: number;
230
+ /** Cooldown per normalized tool-error signature in ms (default 60000). */
231
+ toolErrorCooldownMs: number;
232
+ /** Max tool-error quirk injections per session (default 3). */
233
+ toolErrorMaxPerSession: number;
234
+ /** Latency budget (ms) for tool-error quirk recall; exceeded -> no injection (default 1500). */
235
+ toolErrorLatencyBudgetMs: number;
211
236
  /** Decay settings for aging quirks. */
212
237
  decay: {
213
238
  /** Whether confidence decays over time. */
@@ -254,6 +279,47 @@ export interface ContextOptimizationConfig {
254
279
  /** Jaccard similarity threshold (0-1) for same-file dedup. */
255
280
  similarityThreshold: number;
256
281
  }
282
+ /**
283
+ * Optional cross-encoder rerank stage (opt-in, default OFF).
284
+ *
285
+ * After hybrid fusion the top candidates are re-scored by a cross-encoder
286
+ * (e.g. Qwen3-Reranker served by llama-server's `/v1/rerank`). The stage is a
287
+ * pure reorder (+ optional gate); the fusion `minScore` gate runs unchanged
288
+ * BEFORE reranking, so disabling reranking reproduces today's behavior
289
+ * exactly. Provider errors/timeouts always degrade to the fusion order —
290
+ * retrieval never fails because of the reranker.
291
+ */
292
+ export interface RerankingConfig {
293
+ /** Master switch — when false (default) no reranker is created. */
294
+ enabled: boolean;
295
+ /** Rerank provider implementation. @default "llama-server" */
296
+ provider?: "llama-server";
297
+ /** Base URL of the rerank endpoint (e.g. http://127.0.0.1:8080/v1). The stage POSTs to {baseUrl}/rerank. */
298
+ baseUrl: string;
299
+ /** Optional bearer token (e.g. llama-swap auth). */
300
+ apiKey?: string;
301
+ /** Reranker model name passed to the server. */
302
+ model: string;
303
+ /** How many fused candidates to send per query (after the fusion minScore gate). @default 20 */
304
+ candidates?: number;
305
+ /** Each candidate's document text is truncated to this many characters. @default 1200 */
306
+ maxDocChars?: number;
307
+ /** Additional gate on the rerank score itself (0 = pure reorder, default). NOT comparable to retrieval.minScore — rerank scores are provider-scaled, not calibrated. */
308
+ minScore?: number;
309
+ /** Per-call timeout in ms; on expiry the fusion order is kept. @default 1500 */
310
+ timeoutMs?: number;
311
+ /**
312
+ * Query template applied before scoring. With a `{query}` placeholder the
313
+ * query is substituted, otherwise the template is used as a prefix.
314
+ * Use this for instruct-style rerankers (e.g. Qwen3-Reranker) — do NOT
315
+ * reuse embedding.queryPrefix here. @default ""
316
+ */
317
+ queryTemplate?: string;
318
+ /** Document text: raw content, or description + content. @default "content" */
319
+ docField?: "content" | "content+description";
320
+ /** Proxy configuration for the rerank endpoint. */
321
+ proxy?: ProxyConfig;
322
+ }
257
323
  /** Complete configuration for the OpenCodeRAG pipeline. */
258
324
  export interface RagConfig {
259
325
  /** Embedding provider settings (model, endpoint, prefixes). */
@@ -398,6 +464,8 @@ export interface RagConfig {
398
464
  /** Context window optimization settings for post-retrieval quality filtering. */
399
465
  contextOptimization?: ContextOptimizationConfig;
400
466
  };
467
+ /** Optional cross-encoder rerank stage (opt-in; absent = disabled). */
468
+ reranking?: RerankingConfig;
401
469
  /** OpenCode plugin integration settings. */
402
470
  openCode: {
403
471
  /** Whether the OpenCode plugin is active. */
@@ -145,6 +145,20 @@ export const DEFAULT_CONFIG = {
145
145
  similarityThreshold: 0.8,
146
146
  },
147
147
  },
148
+ reranking: {
149
+ enabled: false,
150
+ provider: "llama-server",
151
+ // llama-server's default port; llama-swap users typically point this at
152
+ // their swap proxy (which routes v1/rerank) instead.
153
+ baseUrl: "http://127.0.0.1:8080/v1",
154
+ model: "qwen3-reranker-0.6b",
155
+ candidates: 20,
156
+ maxDocChars: 1200,
157
+ minScore: 0,
158
+ timeoutMs: 1500,
159
+ queryTemplate: "",
160
+ docField: "content",
161
+ },
148
162
  openCode: {
149
163
  enabled: true,
150
164
  maxContextChunks: 10,
@@ -288,6 +302,13 @@ export const DEFAULT_CONFIG = {
288
302
  sessionEndExtraction: true,
289
303
  autoCaptureMaxPerTurn: 2,
290
304
  autoCaptureDedupThreshold: 0.85,
305
+ injectOnToolError: true,
306
+ toolErrorMinScore: 0.7,
307
+ toolErrorTopK: 2,
308
+ toolErrorMinTokenOverlap: 1,
309
+ toolErrorCooldownMs: 60_000,
310
+ toolErrorMaxPerSession: 3,
311
+ toolErrorLatencyBudgetMs: 1500,
291
312
  decay: {
292
313
  enabled: false,
293
314
  halfLifeDays: 30,
@@ -318,7 +339,7 @@ export function resolveLogConfig(config) {
318
339
  export function validateConfig(config) {
319
340
  const warnings = [];
320
341
  const KNOWN_TOP_KEYS = new Set([
321
- "embedding", "indexing", "vectorStore", "retrieval",
342
+ "embedding", "indexing", "vectorStore", "retrieval", "reranking",
322
343
  "openCode", "chunkers", "chunking", "description",
323
344
  "imageDescription", "documentationMode", "wikiMode", "mcp", "autoUpdate", "memory", "ui", "tui", "logging",
324
345
  ]);
@@ -416,6 +437,23 @@ export function validateConfig(config) {
416
437
  if (t < 0 || t > 1)
417
438
  warnings.push("memory.autoCaptureDedupThreshold must be between 0 and 1");
418
439
  }
440
+ if (config.memory?.toolErrorMinScore != null) {
441
+ const r = config.memory.toolErrorMinScore;
442
+ if (r < 0 || r > 1)
443
+ warnings.push("memory.toolErrorMinScore must be between 0 and 1");
444
+ }
445
+ if (config.memory?.toolErrorTopK != null && config.memory.toolErrorTopK < 1) {
446
+ warnings.push("memory.toolErrorTopK must be >= 1");
447
+ }
448
+ if (config.memory?.toolErrorCooldownMs != null && config.memory.toolErrorCooldownMs < 0) {
449
+ warnings.push("memory.toolErrorCooldownMs must be >= 0");
450
+ }
451
+ if (config.memory?.toolErrorMaxPerSession != null && config.memory.toolErrorMaxPerSession < 0) {
452
+ warnings.push("memory.toolErrorMaxPerSession must be >= 0");
453
+ }
454
+ if (config.memory?.toolErrorLatencyBudgetMs != null && config.memory.toolErrorLatencyBudgetMs < 0) {
455
+ warnings.push("memory.toolErrorLatencyBudgetMs must be >= 0");
456
+ }
419
457
  if (config.memory?.decay && config.memory.decay.halfLifeDays <= 0) {
420
458
  warnings.push("memory.decay.halfLifeDays must be > 0");
421
459
  }
@@ -470,6 +508,25 @@ export function validateConfig(config) {
470
508
  warnings.push("imageDescription.onDemand.timeoutMs must be > 0");
471
509
  }
472
510
  }
511
+ if (config.reranking?.enabled) {
512
+ const rr = config.reranking;
513
+ if (!rr.baseUrl)
514
+ warnings.push("reranking.baseUrl must be set when reranking.enabled is true");
515
+ if (!rr.model)
516
+ warnings.push("reranking.model must be set when reranking.enabled is true");
517
+ if (rr.candidates !== undefined && (rr.candidates < 1 || rr.candidates > 100)) {
518
+ warnings.push("reranking.candidates should be between 1 and 100 (latency scales linearly with document count)");
519
+ }
520
+ if (rr.minScore !== undefined && (rr.minScore < 0 || rr.minScore > 1)) {
521
+ warnings.push("reranking.minScore must be between 0 and 1");
522
+ }
523
+ if (rr.timeoutMs !== undefined && rr.timeoutMs <= 0) {
524
+ warnings.push("reranking.timeoutMs must be > 0");
525
+ }
526
+ if (rr.maxDocChars !== undefined && rr.maxDocChars <= 0) {
527
+ warnings.push("reranking.maxDocChars must be > 0");
528
+ }
529
+ }
473
530
  return { valid: warnings.length === 0, warnings };
474
531
  }
475
532
  /** Config file locations to search, in order of precedence. */
@@ -541,6 +598,11 @@ export function loadConfig(filePath, validate = true) {
541
598
  ...(safeObj(parsed.retrieval?.contextOptimization) ?? {}),
542
599
  },
543
600
  },
601
+ // Flat section — no nested objects, a shallow spread merge is safe.
602
+ reranking: {
603
+ ...DEFAULT_CONFIG.reranking,
604
+ ...(safeObj(parsed.reranking) ?? {}),
605
+ },
544
606
  openCode: (() => {
545
607
  const base = DEFAULT_CONFIG.openCode;
546
608
  const user = parsed.openCode ?? {};
@@ -81,6 +81,11 @@ export interface SearchExplanation {
81
81
  vectorRank?: number;
82
82
  /** Rank (0-indexed) in the keyword index results. */
83
83
  keywordRank?: number;
84
+ /** Cross-encoder relevance from the optional rerank stage. Higher means more
85
+ * relevant. NOT a calibrated probability (provider-dependent, llama-server
86
+ * semantics) and NOT comparable to the RRF-normalized fused components.
87
+ * Set only when the rerank stage actually ran for this result. */
88
+ rerankScore?: number;
84
89
  };
85
90
  /** Calibrated relevance in [0,1] derived from the raw vector-score spread of the
86
91
  * candidate set — unlike the fused `score` (RRF-normalized so rank 0 is always
@@ -128,6 +133,35 @@ export interface EmbeddingProvider {
128
133
  /** Embed one or more text strings. `purpose` may apply a prefix for query vs. document embeddings. */
129
134
  embed(texts: string[], purpose?: "query" | "document"): Promise<number[][]>;
130
135
  }
136
+ /**
137
+ * Cross-encoder reranker: scores (query, document) pairs for relevance.
138
+ *
139
+ * Deliberately narrow so a decision model (typed classifier) can implement the
140
+ * same contract later. Providers never throw into retrieval hot paths by
141
+ * design: callers catch `rerank()` rejections, degrade to the original order,
142
+ * and feed the failure into `noteFailure()` so repeated outages trip an
143
+ * automatic cooldown (`available() === false`).
144
+ */
145
+ export interface RerankProvider {
146
+ /** Provider name (e.g. "llama-server"). */
147
+ readonly name: string;
148
+ /** Model identifier used for scoring (cache/log attribution). */
149
+ readonly model: string;
150
+ /** False while a failure cooldown is active — callers must skip reranking. */
151
+ available(): boolean;
152
+ /**
153
+ * Score every document against the query; the returned array is index-aligned
154
+ * with `documents` (higher = more relevant). May reject — the caller then
155
+ * keeps the pre-rerank order and calls `noteFailure()`.
156
+ */
157
+ rerank(query: string, documents: string[], opts?: {
158
+ timeoutMs?: number;
159
+ }): Promise<number[]>;
160
+ /** Record a failed call (counts toward the cooldown). */
161
+ noteFailure(): void;
162
+ /** Record a successful call (resets the failure streak). */
163
+ noteSuccess(): void;
164
+ }
131
165
  /** In-memory TF-IDF inverted index for keyword-based search alongside vector search. */
132
166
  export interface KeywordIndex {
133
167
  /** Release resources and free memory. */
@@ -180,7 +180,15 @@ export class LlmDescriptionProvider {
180
180
  : `${baseUrl}${baseUrl.endsWith("/v1") ? "" : "/v1"}/chat/completions`;
181
181
  const body = isOllama
182
182
  ? { model: this.config.model, messages, stream: false, think: this.config.think ?? false, options: { num_ctx: this.config.numCtx }, keep_alive: normalizeKeepAlive(this.config.keepAlive) }
183
- : { model: this.config.model, messages };
183
+ : {
184
+ model: this.config.model,
185
+ messages,
186
+ // Reasoning models (Qwen3.x etc.) think before answering; a full
187
+ // reasoning pass per chunk makes indexing ~50x slower. Honor
188
+ // `think: false` for OpenAI-compatible providers as well by
189
+ // forwarding chat_template_kwargs (llama.cpp / vLLM convention).
190
+ ...(this.config.think === false ? { chat_template_kwargs: { enable_thinking: false } } : {}),
191
+ };
184
192
  const headers = {};
185
193
  if (this.config.apiKey) {
186
194
  headers.Authorization = `Bearer ${this.config.apiKey}`;
@@ -46,7 +46,11 @@ export declare function probeEmbeddingDimension(embedder: EmbeddingProvider): Pr
46
46
  * for transient failures — auth/validation errors are not retried). If all
47
47
  * retries are exhausted or the provider returns a mismatched embedding count,
48
48
  * the batch is skipped and empty arrays are returned for those texts so the
49
- * caller can still process successfully embedded batches.
49
+ * caller can still process successfully embedded batches. Failures are logged
50
+ * to the workspace debug log (scope `embedder.batch`); batches that fail for a
51
+ * non-permanent reason (provider context limit, request timeout, count or
52
+ * dimension mismatch) are split in half and retried recursively down to single
53
+ * texts, so one oversized or slow text cannot discard its healthy siblings.
50
54
  *
51
55
  * @param embedder - The embedding provider to use
52
56
  * @param texts - Array of text strings to embed
@@ -3,6 +3,8 @@ import { OllamaProvider } from "./ollama.js";
3
3
  import { OpenAIProvider } from "./openai.js";
4
4
  import { CohereProvider } from "./cohere.js";
5
5
  import pLimit from "p-limit";
6
+ import path from "node:path";
7
+ import { appendDebugLog } from "../core/fileLogger.js";
6
8
  /**
7
9
  * Create an embedding provider instance based on the application configuration.
8
10
  *
@@ -73,6 +75,29 @@ const PERMANENT_STATUS_RE = /\(?(400|401|403|404|422)\)?/;
73
75
  function isPermanentError(err) {
74
76
  return PERMANENT_STATUS_RE.test(err instanceof Error ? err.message : String(err));
75
77
  }
78
+ /**
79
+ * Provider errors that mean the request exceeded the model context window.
80
+ * llama.cpp rejects the WHOLE request when any single input is over the limit
81
+ * (HTTP 400 exceed_context_size_error), so such batches are split and retried.
82
+ */
83
+ const CONTEXT_LIMIT_RE = /exceed_context_size|exceeds the available context size/i;
84
+ function isContextLimitError(err) {
85
+ return CONTEXT_LIMIT_RE.test(err instanceof Error ? err.message : String(err));
86
+ }
87
+ /**
88
+ * Provider request timeouts. The server usually keeps chewing on an oversized
89
+ * input after the client gave up, so a timeout is the silent twin of a
90
+ * context-limit rejection: without splitting, every healthy text in the batch
91
+ * loses its vector too.
92
+ */
93
+ const TIMEOUT_RE = /timed out|timeout/i;
94
+ function isTimeoutError(err) {
95
+ return TIMEOUT_RE.test(err instanceof Error ? err.message : String(err));
96
+ }
97
+ /** Resolve the workspace debug log file used for batch failure diagnostics. */
98
+ function getBatchLogFilePath() {
99
+ return path.resolve(process.cwd(), ".opencode", "opencode-rag.log");
100
+ }
76
101
  /**
77
102
  * Embed a list of texts in batches with optional concurrency control and per-batch retry.
78
103
  *
@@ -84,7 +109,11 @@ function isPermanentError(err) {
84
109
  * for transient failures — auth/validation errors are not retried). If all
85
110
  * retries are exhausted or the provider returns a mismatched embedding count,
86
111
  * the batch is skipped and empty arrays are returned for those texts so the
87
- * caller can still process successfully embedded batches.
112
+ * caller can still process successfully embedded batches. Failures are logged
113
+ * to the workspace debug log (scope `embedder.batch`); batches that fail for a
114
+ * non-permanent reason (provider context limit, request timeout, count or
115
+ * dimension mismatch) are split in half and retried recursively down to single
116
+ * texts, so one oversized or slow text cannot discard its healthy siblings.
88
117
  *
89
118
  * @param embedder - The embedding provider to use
90
119
  * @param texts - Array of text strings to embed
@@ -105,8 +134,15 @@ export async function embedBatch(embedder, texts, batchSize = 10, purpose, concu
105
134
  for (let i = 0; i < texts.length; i += batchSize) {
106
135
  batches.push({ index: i, texts: texts.slice(i, i + batchSize) });
107
136
  }
108
- async function embedWithRetry(batchTexts) {
109
- for (let attempt = 0; attempt <= retryMax; attempt++) {
137
+ // `depth` counts split levels: the top-level batch gets the full retry
138
+ // budget, every sub-batch only a single attempt — otherwise one slow text
139
+ // would multiply its retries across the whole split tree and stall the pass.
140
+ async function embedWithRetry(batchTexts, depth = 0) {
141
+ const maxRetries = depth === 0 ? retryMax : Math.min(1, retryMax);
142
+ let lastError;
143
+ let attempts = 0;
144
+ for (let attempt = 0; attempt <= maxRetries; attempt++) {
145
+ attempts = attempt + 1;
110
146
  try {
111
147
  const embeddings = await embedder.embed(batchTexts, purpose);
112
148
  // Validate the response shape: a count mismatch would silently attach
@@ -122,15 +158,49 @@ export async function embedBatch(embedder, texts, batchSize = 10, purpose, concu
122
158
  return embeddings;
123
159
  }
124
160
  catch (err) {
125
- if (attempt < retryMax && !isPermanentError(err)) {
161
+ lastError = err;
162
+ if (attempt < maxRetries && !isPermanentError(err)) {
126
163
  const delay = retryBaseDelayMs * Math.pow(2, attempt) * (0.8 + Math.random() * 0.4);
127
164
  await new Promise(resolve => setTimeout(resolve, delay));
128
165
  }
129
- else if (attempt >= retryMax || isPermanentError(err)) {
130
- return null;
166
+ else if (attempt >= maxRetries || isPermanentError(err)) {
167
+ break;
131
168
  }
132
169
  }
133
170
  }
171
+ const longestText = batchTexts.reduce((max, text) => Math.max(max, text.length), 0);
172
+ appendDebugLog(getBatchLogFilePath(), {
173
+ scope: "embedder.batch",
174
+ severity: "warn",
175
+ message: `Embedding batch failed after ${attempts} attempt(s) ` +
176
+ `(${batchTexts.length} text(s), longest ${longestText} chars): ` +
177
+ `${lastError instanceof Error ? lastError.message : String(lastError)}`,
178
+ error: lastError,
179
+ });
180
+ // A single overlong or slow text can make the provider reject the whole
181
+ // request (llama.cpp HTTP 400 exceed_context_size_error) or time it out.
182
+ // Split the batch recursively so one bad text cannot discard its healthy
183
+ // siblings; text(s) that still fail come back as empty vectors and are
184
+ // counted by the caller. A context-limit rejection carries a permanent 400
185
+ // status, so it needs its own predicate; timeouts are already non-permanent
186
+ // (belt and braces). Genuine permanent errors never split — halving the
187
+ // batch would fail the same way, only slower.
188
+ const splittable = !isPermanentError(lastError) || isContextLimitError(lastError) || isTimeoutError(lastError);
189
+ if (batchTexts.length > 1 && splittable) {
190
+ const mid = Math.ceil(batchTexts.length / 2);
191
+ appendDebugLog(getBatchLogFilePath(), {
192
+ scope: "embedder.batch",
193
+ severity: "info",
194
+ message: `Splitting failed batch of ${batchTexts.length} text(s) into ${mid}+${batchTexts.length - mid} ` +
195
+ `(depth ${depth + 1}) after: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
196
+ });
197
+ const left = await embedWithRetry(batchTexts.slice(0, mid), depth + 1);
198
+ const right = await embedWithRetry(batchTexts.slice(mid), depth + 1);
199
+ return [
200
+ ...(left ?? batchTexts.slice(0, mid).map(() => [])),
201
+ ...(right ?? batchTexts.slice(mid).map(() => [])),
202
+ ];
203
+ }
134
204
  return null;
135
205
  }
136
206
  if (concurrency <= 1 || batches.length <= 1) {