opencode-rag-plugin 2.2.2 → 2.3.1

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 (58) hide show
  1. package/ReadMe.md +2 -0
  2. package/dist/api.js +2 -0
  3. package/dist/chunker/factory.js +48 -18
  4. package/dist/chunker/image.js +6 -0
  5. package/dist/cli/commands/clear.js +21 -1
  6. package/dist/cli/commands/init-helpers.d.ts +4 -1
  7. package/dist/cli/commands/init-helpers.js +55 -20
  8. package/dist/cli/commands/init.js +13 -1
  9. package/dist/cli/commands/query.js +6 -0
  10. package/dist/cli/commands/setup.js +43 -12
  11. package/dist/cli/commands/status.js +4 -0
  12. package/dist/cli/commands/update.d.ts +3 -2
  13. package/dist/cli/commands/update.js +7 -3
  14. package/dist/core/bootstrap.d.ts +3 -1
  15. package/dist/core/bootstrap.js +5 -0
  16. package/dist/core/config.d.ts +74 -1
  17. package/dist/core/config.js +63 -1
  18. package/dist/core/interfaces.d.ts +34 -0
  19. package/dist/core/package-manager.d.ts +69 -0
  20. package/dist/core/package-manager.js +250 -0
  21. package/dist/core/setup-runtime.d.ts +7 -4
  22. package/dist/core/setup-runtime.js +33 -31
  23. package/dist/core/version-check.d.ts +19 -11
  24. package/dist/core/version-check.js +30 -11
  25. package/dist/describer/describer.js +9 -1
  26. package/dist/embedder/factory.d.ts +5 -1
  27. package/dist/embedder/factory.js +76 -6
  28. package/dist/embedder/health.d.ts +1 -1
  29. package/dist/embedder/health.js +43 -0
  30. package/dist/eval/rerank-eval.d.ts +45 -0
  31. package/dist/eval/rerank-eval.js +581 -0
  32. package/dist/indexer/pipeline.d.ts +17 -0
  33. package/dist/indexer/pipeline.js +123 -3
  34. package/dist/indexer/stats.d.ts +7 -0
  35. package/dist/mcp/handlers.js +3 -0
  36. package/dist/opencode/create-read-tool.js +5 -2
  37. package/dist/plugin.js +67 -6
  38. package/dist/quirks/quirk-store.d.ts +1 -0
  39. package/dist/quirks/quirk-store.js +1 -1
  40. package/dist/quirks/tool-error-recall.d.ts +112 -0
  41. package/dist/quirks/tool-error-recall.js +144 -0
  42. package/dist/reranker/base.d.ts +47 -0
  43. package/dist/reranker/base.js +73 -0
  44. package/dist/reranker/factory.d.ts +16 -0
  45. package/dist/reranker/factory.js +47 -0
  46. package/dist/reranker/llama-server.d.ts +33 -0
  47. package/dist/reranker/llama-server.js +101 -0
  48. package/dist/retriever/keyword-index.d.ts +1 -0
  49. package/dist/retriever/keyword-index.js +1 -1
  50. package/dist/retriever/retriever.d.ts +24 -1
  51. package/dist/retriever/retriever.js +69 -5
  52. package/dist/types/opencode-plugin.d.ts +2 -2
  53. package/dist/v2/v2-adapter.d.ts +6 -1
  54. package/dist/v2/v2-adapter.js +52 -8
  55. package/dist/vectorstore/lancedb.d.ts +1 -1
  56. package/dist/vectorstore/lancedb.js +43 -7
  57. package/dist/web/api.js +5 -0
  58. package/package.json +1 -1
@@ -2,16 +2,11 @@ import path from "node:path";
2
2
  import os from "node:os";
3
3
  import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, symlinkSync, lstatSync, } from "node:fs";
4
4
  import { execSync } from "node:child_process";
5
+ import { bestAvailablePackageManager, globalInstallCommand, installHint, resolveGlobalInstall, } from "./package-manager.js";
5
6
  const PLUGIN_NAME = "opencode-rag-plugin";
6
7
  export function getRuntimeDir() {
7
8
  return path.join(os.homedir(), ".opencode");
8
9
  }
9
- export function getNpmGlobalRoot() {
10
- return execSync("npm root -g", {
11
- encoding: "utf-8",
12
- timeout: 10_000,
13
- }).trim();
14
- }
15
10
  function createJunction(targetPath, linkPath) {
16
11
  const type = process.platform === "win32" ? "junction" : "dir";
17
12
  symlinkSync(targetPath, linkPath, type);
@@ -33,8 +28,8 @@ export function readVersionFile(versionFile) {
33
28
  }
34
29
  }
35
30
  /** Bin name npm generates for this package (without .cmd/.ps1). */
36
- function getBinName() {
37
- const pkgJson = path.join(getNpmGlobalRoot(), PLUGIN_NAME, "package.json");
31
+ function getBinName(packageDir) {
32
+ const pkgJson = path.join(packageDir, "package.json");
38
33
  try {
39
34
  const pkg = JSON.parse(readFileSync(pkgJson, "utf-8"));
40
35
  if (pkg.bin && typeof pkg.bin === "object") {
@@ -55,14 +50,19 @@ function getBinName() {
55
50
  * (e.g. Notepad++) instead of Node.js, the CLI opens the editor instead of
56
51
  * running. This function patches the wrappers to call `node` explicitly.
57
52
  *
58
- * Runs only on Windows. Safe to call on every setup — detects already-patched
59
- * wrappers by checking for the `node` prefix.
53
+ * npm only: pnpm/bun/yarn shims already invoke `node` explicitly, and their
54
+ * global bin directories are not laid out relative to the global root the way
55
+ * npm's are (`<prefix>\node_modules` next to `<prefix>`). Runs only on
56
+ * Windows; safe to call on every setup — detects already-patched wrappers by
57
+ * checking for the `node` prefix.
60
58
  */
61
- export function patchWindowsWrappers(npmGlobalRoot) {
59
+ export function patchWindowsWrappers(install) {
62
60
  if (process.platform !== "win32")
63
61
  return;
64
- const binDir = path.resolve(npmGlobalRoot, "..");
65
- const binName = getBinName();
62
+ if (install.pm !== "npm")
63
+ return;
64
+ const binDir = path.resolve(install.globalRoot, "..");
65
+ const binName = getBinName(install.packageDir);
66
66
  // ── .cmd wrapper ──────────────────────────────────────────────
67
67
  const cmdFile = path.join(binDir, `${binName}.cmd`);
68
68
  if (existsSync(cmdFile)) {
@@ -107,20 +107,16 @@ export async function setupRuntime(options) {
107
107
  if (alreadyInstalled && installedVersion === pluginVersion && !options?.force) {
108
108
  return { success: true, errors: [] };
109
109
  }
110
- let npmGlobalRoot;
111
- try {
112
- npmGlobalRoot = getNpmGlobalRoot();
113
- }
114
- catch {
115
- errors.push("npm is not available on PATH. Cannot determine global package location.");
116
- return { success: false, errors };
117
- }
118
- const globalPluginDir = path.join(npmGlobalRoot, PLUGIN_NAME);
119
- const globalSdkPluginDir = path.join(npmGlobalRoot, "@opencode-ai", "plugin");
120
- if (!existsSync(globalPluginDir)) {
121
- errors.push(`Plugin not found at: ${globalPluginDir}`);
110
+ // Locate the global install with any package manager (issue #34: npm may be
111
+ // absent entirely — pnpm/yarn/bun installs must work too).
112
+ const install = resolveGlobalInstall(PLUGIN_NAME);
113
+ if (!install) {
114
+ errors.push(`Could not find a global ${PLUGIN_NAME} install (checked npm, pnpm, yarn, and bun). ` +
115
+ `Install it first: ${installHint(PLUGIN_NAME)}`);
122
116
  return { success: false, errors };
123
117
  }
118
+ const globalPluginDir = install.packageDir;
119
+ const globalSdkPluginDir = path.join(install.globalRoot, "@opencode-ai", "plugin");
124
120
  if (!existsSync(path.join(globalPluginDir, "dist", "cli.js"))) {
125
121
  errors.push(`Global install seems incomplete: dist/ not found in ${globalPluginDir}`);
126
122
  return { success: false, errors };
@@ -161,18 +157,24 @@ export async function setupRuntime(options) {
161
157
  cpSync(globalPluginDir, runtimePluginDir, { recursive: true });
162
158
  }
163
159
  // Ensure the @opencode-ai/plugin SDK is available globally.
164
- // We must NOT run `npm install` inside the runtime dir because npm
165
- // re-resolves all of node_modules/ and replaces the plugin junction
166
- // with the published npm version (corrupting the local link).
160
+ // We must NOT run a package install inside the runtime dir because the
161
+ // package manager re-resolves all of node_modules/ and replaces the plugin
162
+ // junction with the published npm version (corrupting the local link).
167
163
  if (!existsSync(globalSdkPluginDir)) {
164
+ const sdkPm = install.pm ?? bestAvailablePackageManager();
165
+ if (!sdkPm) {
166
+ errors.push("No package manager (npm/pnpm/yarn/bun) found on PATH — cannot install the @opencode-ai/plugin SDK globally.");
167
+ return { success: false, errors };
168
+ }
169
+ const sdkInstallCommand = globalInstallCommand(sdkPm, "@opencode-ai/plugin");
168
170
  try {
169
- execSync(`npm install -g @opencode-ai/plugin`, {
171
+ execSync(sdkInstallCommand, {
170
172
  stdio: "pipe",
171
173
  timeout: 60_000,
172
174
  });
173
175
  }
174
176
  catch (cause) {
175
- errors.push(`Failed to install @opencode-ai/plugin SDK globally: ${cause.message}`);
177
+ errors.push(`Failed to install @opencode-ai/plugin SDK globally (${sdkInstallCommand}): ${cause.message}`);
176
178
  return { success: false, errors };
177
179
  }
178
180
  }
@@ -213,7 +215,7 @@ export async function setupRuntime(options) {
213
215
  return { success: false, errors };
214
216
  }
215
217
  writeFileSync(versionFile, pluginVersion, "utf-8");
216
- patchWindowsWrappers(npmGlobalRoot);
218
+ patchWindowsWrappers(install);
217
219
  const cliEntry = path.join(runtimePluginDir, "dist", "cli.js");
218
220
  const pluginEntry = path.join(runtimePluginDir, "dist", "plugin-entry.js");
219
221
  const sdkPkg = path.join(runtimeSdkPluginDir, "package.json");
@@ -1,9 +1,11 @@
1
1
  /**
2
2
  * @fileoverview Version check and self-update functionality. Checks GitHub
3
- * releases for new versions and installs the newest version via npm, then
4
- * re-syncs the OpenCode runtime junctions.
3
+ * releases for new versions and installs the newest version via the package
4
+ * manager that owns the global install (npm/pnpm/yarn/bun), then re-syncs the
5
+ * OpenCode runtime junctions.
5
6
  */
6
7
  import { setupRuntime } from "./setup-runtime.js";
8
+ import { type PackageManagerName } from "./package-manager.js";
7
9
  /** Information about an available update. */
8
10
  export interface UpdateInfo {
9
11
  /** The currently installed version string. */
@@ -28,7 +30,7 @@ export interface InstallUpdateResult {
28
30
  /** Version after the update (undefined if the install failed). */
29
31
  toVersion?: string;
30
32
  }
31
- /** Callable shape for the npm runner (a subset of execSync's signature). */
33
+ /** Callable shape for the installer runner (a subset of execSync's signature). */
32
34
  type NpmRunner = (command: string, options: {
33
35
  stdio: "inherit" | "pipe";
34
36
  timeout: number;
@@ -67,24 +69,30 @@ export declare function checkForUpdate(currentVersion: string): Promise<UpdateIn
67
69
  /**
68
70
  * Install the newest published version of OpenCodeRAG.
69
71
  *
70
- * Runs `npm install -g <package>@latest` to refresh the global install, then
71
- * calls {@link setupRuntime} with `force: true` to re-create the
72
- * `~/.opencode/node_modules/` junctions so OpenCode picks up the new build on
73
- * the next restart.
72
+ * Runs the global install command of the package manager that owns the
73
+ * current install (`npm install -g` / `pnpm add -g` / `yarn global add` /
74
+ * `bun add -g` with `<package>@latest`) — the npm binary itself is not
75
+ * required when the package was installed with another manager (GitHub
76
+ * issue #34). Then calls {@link setupRuntime} with `force: true` to
77
+ * re-create the `~/.opencode/node_modules/` junctions so OpenCode picks up
78
+ * the new build on the next restart.
74
79
  *
75
- * @param options - Optional verbosity flag. When `verbose` is true, npm output
76
- * is streamed to the console; otherwise it is captured silently. The
77
- * `_execSync` and `_setupRuntime` seams are for testing only.
80
+ * @param options - Optional verbosity flag. When `verbose` is true, installer
81
+ * output is streamed to the console; otherwise it is captured silently. The
82
+ * `_execSync`, `_setupRuntime`, `_getCurrentVersion`, and `_packageManager`
83
+ * seams are for testing only.
78
84
  * @returns An {@link InstallUpdateResult} with success status, message, and the
79
85
  * from/to versions.
80
86
  */
81
87
  export declare function installLatestUpdate(options?: {
82
88
  verbose?: boolean;
83
- /** Test seam: override the npm runner. */
89
+ /** Test seam: override the installer runner. */
84
90
  _execSync?: NpmRunner;
85
91
  /** Test seam: override the runtime sync. */
86
92
  _setupRuntime?: typeof setupRuntime;
87
93
  /** Test seam: override the version reader for the "to" version. */
88
94
  _getCurrentVersion?: typeof getCurrentVersion;
95
+ /** Test seam: pin the package manager (`null` = force "none found"). */
96
+ _packageManager?: PackageManagerName | null;
89
97
  }): Promise<InstallUpdateResult>;
90
98
  export {};
@@ -1,13 +1,15 @@
1
1
  /**
2
2
  * @fileoverview Version check and self-update functionality. Checks GitHub
3
- * releases for new versions and installs the newest version via npm, then
4
- * re-syncs the OpenCode runtime junctions.
3
+ * releases for new versions and installs the newest version via the package
4
+ * manager that owns the global install (npm/pnpm/yarn/bun), then re-syncs the
5
+ * OpenCode runtime junctions.
5
6
  */
6
7
  import { readFileSync } from "node:fs";
7
8
  import path from "node:path";
8
9
  import { fileURLToPath } from "node:url";
9
10
  import { execSync } from "node:child_process";
10
11
  import { setupRuntime } from "./setup-runtime.js";
12
+ import { bestAvailablePackageManager, globalInstallCommand, resolveGlobalInstall, } from "./package-manager.js";
11
13
  /** npm package name (must match the `name` field in package.json). */
12
14
  const PACKAGE_NAME = "opencode-rag-plugin";
13
15
  /** GitHub repo used for release checks (owner/repo). */
@@ -107,14 +109,18 @@ export async function checkForUpdate(currentVersion) {
107
109
  /**
108
110
  * Install the newest published version of OpenCodeRAG.
109
111
  *
110
- * Runs `npm install -g <package>@latest` to refresh the global install, then
111
- * calls {@link setupRuntime} with `force: true` to re-create the
112
- * `~/.opencode/node_modules/` junctions so OpenCode picks up the new build on
113
- * the next restart.
112
+ * Runs the global install command of the package manager that owns the
113
+ * current install (`npm install -g` / `pnpm add -g` / `yarn global add` /
114
+ * `bun add -g` with `<package>@latest`) — the npm binary itself is not
115
+ * required when the package was installed with another manager (GitHub
116
+ * issue #34). Then calls {@link setupRuntime} with `force: true` to
117
+ * re-create the `~/.opencode/node_modules/` junctions so OpenCode picks up
118
+ * the new build on the next restart.
114
119
  *
115
- * @param options - Optional verbosity flag. When `verbose` is true, npm output
116
- * is streamed to the console; otherwise it is captured silently. The
117
- * `_execSync` and `_setupRuntime` seams are for testing only.
120
+ * @param options - Optional verbosity flag. When `verbose` is true, installer
121
+ * output is streamed to the console; otherwise it is captured silently. The
122
+ * `_execSync`, `_setupRuntime`, `_getCurrentVersion`, and `_packageManager`
123
+ * seams are for testing only.
118
124
  * @returns An {@link InstallUpdateResult} with success status, message, and the
119
125
  * from/to versions.
120
126
  */
@@ -125,8 +131,21 @@ export async function installLatestUpdate(options) {
125
131
  const syncRuntime = options?._setupRuntime ?? setupRuntime;
126
132
  const readVersion = options?._getCurrentVersion ?? getCurrentVersion;
127
133
  const fromVersion = readVersion();
134
+ // Note: an explicit `null` pins "no package manager" (test seam), so this
135
+ // must not use ?? — null is a value here, not an absence.
136
+ const pm = options?._packageManager !== undefined
137
+ ? options._packageManager
138
+ : resolveGlobalInstall(PACKAGE_NAME)?.pm ?? bestAvailablePackageManager();
139
+ if (!pm) {
140
+ return {
141
+ success: false,
142
+ message: `No package manager (npm/pnpm/yarn/bun) found on PATH. Update manually with ` +
143
+ `'npm install -g ${PACKAGE_NAME}@latest' or the equivalent for your package manager.`,
144
+ fromVersion,
145
+ };
146
+ }
128
147
  try {
129
- run(`npm install -g ${PACKAGE_NAME}@latest --no-fund --no-audit`, {
148
+ run(globalInstallCommand(pm, `${PACKAGE_NAME}@latest`), {
130
149
  stdio,
131
150
  timeout: 120_000,
132
151
  });
@@ -134,7 +153,7 @@ export async function installLatestUpdate(options) {
134
153
  catch (err) {
135
154
  return {
136
155
  success: false,
137
- message: `npm install failed: ${err.message}`,
156
+ message: `${pm} install failed: ${err.message}`,
138
157
  fromVersion,
139
158
  };
140
159
  }
@@ -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) {
@@ -10,7 +10,7 @@ export interface HealthCheckResult {
10
10
  /** Model identifier that was tested */
11
11
  model: string;
12
12
  /** Which capability was checked */
13
- type: "embedding" | "description" | "image_description" | "image_description_on_demand";
13
+ type: "embedding" | "description" | "image_description" | "image_description_on_demand" | "rerank";
14
14
  /** Whether the provider is reachable and the model is available */
15
15
  status: "ok" | "missing" | "error";
16
16
  /** Human-readable error message when status is not "ok" */
@@ -20,8 +20,51 @@ export async function checkProviderHealth(config) {
20
20
  checks.push(checkOnDemandImageDescriptionModel(onDemand));
21
21
  }
22
22
  }
23
+ if (config.reranking?.enabled) {
24
+ checks.push(checkRerankModel(config));
25
+ }
23
26
  return Promise.all(checks);
24
27
  }
28
+ /** Check the rerank endpoint (llama-server `/v1/rerank`) with a minimal two-document scoring call. */
29
+ async function checkRerankModel(config) {
30
+ const rr = config.reranking;
31
+ const provider = rr?.provider ?? "llama-server";
32
+ const model = rr?.model ?? "unknown";
33
+ if (!rr?.enabled || !rr.baseUrl || !rr.model) {
34
+ return { provider, model, type: "rerank", status: "error", error: "reranking.enabled is true but reranking.baseUrl/model is not configured" };
35
+ }
36
+ const headers = {};
37
+ if (rr.apiKey) {
38
+ headers.Authorization = `Bearer ${rr.apiKey}`;
39
+ }
40
+ try {
41
+ const response = await postJson(`${rr.baseUrl.replace(/\/+$/, "")}/rerank`, { model: rr.model, query: "health check", documents: ["First health check document.", "Second health check document."] }, headers, Math.min(rr.timeoutMs ?? 1500, 15000), rr.proxy);
42
+ if (response.ok) {
43
+ return { provider, model, type: "rerank", status: "ok" };
44
+ }
45
+ const body = await response.text().catch(() => "");
46
+ if (response.status === 404) {
47
+ return {
48
+ provider,
49
+ model,
50
+ type: "rerank",
51
+ status: "error",
52
+ error: "HTTP 404 from the rerank endpoint — is llama-server started with --reranking (and does your proxy route /v1/rerank)?",
53
+ };
54
+ }
55
+ if (isModelNotFoundError(body)) {
56
+ return { provider, model, type: "rerank", status: "missing" };
57
+ }
58
+ return { provider, model, type: "rerank", status: "error", error: `HTTP ${response.status}: ${body.slice(0, 200)}` };
59
+ }
60
+ catch (err) {
61
+ const msg = err.message || String(err);
62
+ if (isConnectionError(msg)) {
63
+ return { provider, model, type: "rerank", status: "error", error: "Connection refused. Is the rerank server running?" };
64
+ }
65
+ return { provider, model, type: "rerank", status: "error", error: msg.slice(0, 200) };
66
+ }
67
+ }
25
68
  /** Dispatch the embedding-model check to the correct provider-specific handler. */
26
69
  async function checkEmbeddingModel(config, timeoutMs) {
27
70
  const { provider, baseUrl, model, apiKey, proxy } = config.embedding;
@@ -0,0 +1,45 @@
1
+ /**
2
+ * @fileoverview Rerank A/B evaluation harness: runs labeled ground-truth queries through
3
+ * the real retrieval pipeline (baseline vs. opt-in rerank stage) and reports
4
+ * Hit@k, Precision@5, Recall@k, MRR, nDCG@10, and warm latency (p50/p95).
5
+ *
6
+ * Usage: node --import tsx src/eval/rerank-eval.ts [options]
7
+ *
8
+ * Options:
9
+ * --arms=baseline,rerank20,rerank30,rerank-desc Arms to run (default: baseline,rerank20,rerank30)
10
+ * --topk=20 Override retrieval topK (default: config)
11
+ * --minScore=0.35 Override retrieval minScore (default: config)
12
+ * --category=nl Only run labels of one category (nl|gotcha|symbol|de)
13
+ * --limit=10 Only run the first N labels (after filtering)
14
+ * --warmup=2 Discarded warmup queries per arm before measuring (default 2;
15
+ * llama-swap cold starts measure 15-25s and would pollute p50/p95)
16
+ * --labels=path Label file (default: src/eval/rerank-labels.json)
17
+ * --report=path Report file (default: doc/rerank-eval-report.md)
18
+ * --rerank-base-url=URL Rerank endpoint (e.g. http://127.0.0.1:11437/v1). Passing any
19
+ * --rerank-* flag enables the rerank arms without touching the
20
+ * user's opencode-rag.json (synthesized enabled section).
21
+ * --rerank-model=NAME Reranker model name (e.g. Qwen3-Reranker-0.6B)
22
+ * --rerank-api-key=KEY Optional bearer token for the rerank endpoint
23
+ * --rerank-provider=ID Provider id (default: llama-server)
24
+ * --rerank-timeout=MS Override the rerank stage timeout for this run (default: provider
25
+ * config, 1500). Raise it when the server needs >1.5 s for large
26
+ * candidate pools — otherwise most queries degrade to fusion order.
27
+ * --embedding-model=ID Override embedding.model for this run (e.g. Qwen3-Embedding:8B).
28
+ * Useful when the shared config is broken or leased by another session.
29
+ * --embedding-base-url=… Override embedding.baseUrl for this run.
30
+ *
31
+ * Design notes:
32
+ * - Ground truth lives in `rerank-labels.json` as query -> file paths (+ optional
33
+ * symbol). Chunk IDs are deliberately NOT used: they do not survive re-indexing.
34
+ * - The reranker module is imported dynamically so this harness type-checks and runs
35
+ * while `src/reranker/**` is still under construction. Rerank arms are skipped with
36
+ * a diagnostic when the config has no enabled `reranking.*` section, the module is
37
+ * missing, or the provider cannot be created (e.g. llama-server without --reranking).
38
+ * - Latency is measured warm: each arm issues one discarded warmup query first, so
39
+ * embedding/rerank connection setup does not pollute p50/p95. Cold start is a
40
+ * separate, documented number — not part of this measurement.
41
+ * - `retrieve()` is called through a loose local signature on purpose: the rerank
42
+ * stage is being developed in parallel, and this harness must not depend on its
43
+ * exact RetrieveOptions type.
44
+ */
45
+ export {};