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
@@ -0,0 +1,144 @@
1
+ /**
2
+ * @fileoverview Tool-error → quirk recall: when a tool call fails, find matching quirk
3
+ * memory entries to inject into the next model request, and gate the existing
4
+ * auto-capture pipeline so recurring errors can become quirks.
5
+ *
6
+ * Design notes:
7
+ * - Pure and dependency-injected: the caller passes a `recall` function (the plugin
8
+ * wraps `recallQuirks`), so this module has no store/embedder dependencies and is
9
+ * cheap to unit-test.
10
+ * - Conservative by default: min score 0.7, max 2 hits per error, 3 injections per
11
+ * session, 60s cooldown per normalized error signature, plus a lexical gate so a
12
+ * semantically close but lexically unrelated quirk never gets injected.
13
+ * - A failed recall still counts as an attempt (cooldown), so a repeatedly failing
14
+ * tool does not hammer the embedder every call — but it does not consume the
15
+ * per-session budget; only actual injections do.
16
+ */
17
+ import { sharedWords } from "./quirk-store.js";
18
+ /** Defaults shared by the state factory and the selector. */
19
+ export const TOOL_ERROR_DEFAULTS = {
20
+ minScore: 0.7,
21
+ topK: 2,
22
+ minTokenOverlap: 1,
23
+ cooldownMs: 60_000,
24
+ maxPerSession: 3,
25
+ /** Error text is truncated before it becomes a recall query / capture payload. */
26
+ maxErrorChars: 400,
27
+ /** Capture payloads are sliced to match the existing auto-capture tool-result cap. */
28
+ maxCaptureChars: 500,
29
+ };
30
+ /** Collapse an error into a stable signature for cooldown/dedup purposes. */
31
+ export function normalizeToolErrorSignature(info) {
32
+ const normalized = info.error
33
+ .toLowerCase()
34
+ .replace(/\s+/g, " ")
35
+ .replace(/\d+/g, "#")
36
+ .trim()
37
+ .slice(0, 160);
38
+ return `${info.tool.toLowerCase()}|${normalized}`;
39
+ }
40
+ /** Build the recall query for a failed tool call. */
41
+ export function buildToolErrorQuery(info) {
42
+ const error = info.error.replace(/\s+/g, " ").trim().slice(0, TOOL_ERROR_DEFAULTS.maxErrorChars);
43
+ return `Tool "${info.tool}" failed: ${error}`;
44
+ }
45
+ /** Create the per-session injection state. */
46
+ export function createToolErrorInjectionState(options) {
47
+ const cooldownMs = options?.cooldownMs ?? TOOL_ERROR_DEFAULTS.cooldownMs;
48
+ const maxPerSession = options?.maxPerSession ?? TOOL_ERROR_DEFAULTS.maxPerSession;
49
+ const lastAttemptAt = new Map();
50
+ const injectedIds = new Set();
51
+ let injections = 0;
52
+ return {
53
+ shouldInject(info, now = Date.now()) {
54
+ if (injections >= maxPerSession)
55
+ return false;
56
+ const signature = normalizeToolErrorSignature(info);
57
+ const last = lastAttemptAt.get(signature);
58
+ if (last !== undefined && now - last < cooldownMs)
59
+ return false;
60
+ return true;
61
+ },
62
+ record(info, quirkIds, now = Date.now()) {
63
+ lastAttemptAt.set(normalizeToolErrorSignature(info), now);
64
+ if (quirkIds.length === 0)
65
+ return;
66
+ injections += 1;
67
+ for (const id of quirkIds)
68
+ injectedIds.add(id);
69
+ },
70
+ get injectedQuirkIds() {
71
+ return injectedIds;
72
+ },
73
+ injectionCount() {
74
+ return injections;
75
+ },
76
+ };
77
+ }
78
+ /**
79
+ * Select quirks for a failed tool call.
80
+ *
81
+ * Returns `[]` when the state blocks the attempt (cooldown/budget) or nothing
82
+ * passes the score, dedup, and lexical gates. Records the attempt in the state —
83
+ * with cooldown always, with budget only when at least one quirk is returned.
84
+ */
85
+ export async function selectToolErrorQuirks(recall, info, state, options) {
86
+ if (!state.shouldInject(info))
87
+ return [];
88
+ const minScore = options?.minScore ?? TOOL_ERROR_DEFAULTS.minScore;
89
+ const topK = options?.topK ?? TOOL_ERROR_DEFAULTS.topK;
90
+ const minTokenOverlap = options?.minTokenOverlap ?? TOOL_ERROR_DEFAULTS.minTokenOverlap;
91
+ let raw = [];
92
+ try {
93
+ // Over-fetch so the lexical gate has candidates to choose from.
94
+ raw = await recall(buildToolErrorQuery(info), { topK: Math.max(topK * 3, 6), minScore });
95
+ }
96
+ catch {
97
+ // Recall failures must never break tool execution; fall through to recording.
98
+ state.record(info, []);
99
+ return [];
100
+ }
101
+ // Filter everything first, then sort and slice — otherwise the topK cut
102
+ // would keep the first raw entries instead of the highest-scoring ones.
103
+ const candidates = [];
104
+ for (const hit of raw) {
105
+ const { id, content } = hit.chunk;
106
+ if (state.injectedQuirkIds.has(id))
107
+ continue;
108
+ if (minTokenOverlap > 0 && sharedWords(content, info.error) < minTokenOverlap)
109
+ continue;
110
+ candidates.push({
111
+ id,
112
+ content,
113
+ quirkType: hit.chunk.metadata?.quirkType,
114
+ score: hit.score,
115
+ });
116
+ }
117
+ candidates.sort((a, b) => b.score - a.score);
118
+ const hits = candidates.slice(0, topK);
119
+ state.record(info, hits.map((h) => h.id));
120
+ return hits;
121
+ }
122
+ /** Format the injection block appended to the next model request. Empty when there are no hits. */
123
+ export function formatToolErrorQuirkBlock(info, hits) {
124
+ if (hits.length === 0)
125
+ return "";
126
+ const lines = ["", "---", `⚠ **Tool error** \`${info.tool}\` — matching quirk memory:`, ""];
127
+ for (const hit of hits) {
128
+ const badge = hit.quirkType ? `[\`${hit.quirkType}\`] ` : "";
129
+ lines.push(`- ${badge}${hit.content}`);
130
+ }
131
+ return lines.join("\n");
132
+ }
133
+ /**
134
+ * Shape a tool error as an entry for the existing auto-capture pipeline
135
+ * (`CaptureExchange.toolResults`). Feed the returned entry into the session's
136
+ * tool-result list so recurring errors can become quirks at session end.
137
+ */
138
+ export function toToolErrorCaptureEntry(info) {
139
+ return {
140
+ tool: `${info.tool} (error)`,
141
+ output: info.error.slice(0, TOOL_ERROR_DEFAULTS.maxCaptureChars),
142
+ };
143
+ }
144
+ //# sourceMappingURL=tool-error-recall.js.map
@@ -0,0 +1,47 @@
1
+ /**
2
+ * @fileoverview Shared base class for RerankProvider implementations: failure
3
+ * cooldown and a bounded (query, document) score cache. Retrieval hot paths
4
+ * must never be slowed by a dead reranker, and agent sessions re-issue nearly
5
+ * identical queries often enough that a small in-memory cache pays off.
6
+ */
7
+ import type { RerankProvider } from "../core/interfaces.js";
8
+ /** Options for the cooldown + cache behavior shared by all rerank providers. */
9
+ export interface RerankProviderBaseOptions {
10
+ /** Consecutive `noteFailure()` calls before the cooldown trips. Default 3. */
11
+ cooldownThreshold?: number;
12
+ /** How long the provider reports `available() === false` after tripping. Default 300000 ms. */
13
+ cooldownMs?: number;
14
+ /** Maximum cached (query, document) scores. Default 500. */
15
+ cacheMax?: number;
16
+ }
17
+ /**
18
+ * Base implementation of {@link RerankProvider} supplying the cooldown state
19
+ * machine and an LRU-ish score cache. Subclasses implement `rerank()` and use
20
+ * {@link cacheGet}/{@link cacheSet} for memoization.
21
+ */
22
+ export declare abstract class RerankProviderBase implements RerankProvider {
23
+ abstract readonly name: string;
24
+ readonly model: string;
25
+ private failures;
26
+ private cooldownUntil;
27
+ private readonly cooldownThreshold;
28
+ private readonly cooldownMs;
29
+ private readonly cacheMax;
30
+ /** Insertion/re-touch-ordered Map — the first key is the least recently used. */
31
+ private readonly cache;
32
+ constructor(model: string, options?: RerankProviderBaseOptions);
33
+ /** False while the post-failure cooldown is active. */
34
+ available(): boolean;
35
+ /** Counts a failed call; every `cooldownThreshold` failures trip the cooldown. */
36
+ noteFailure(): void;
37
+ /** A success proves the provider is healthy again — reset the streak. */
38
+ noteSuccess(): void;
39
+ /** Look up a cached score for this provider's model + query + document. */
40
+ protected cacheGet(query: string, document: string): number | undefined;
41
+ /** Store a score, evicting the least recently used entry past the cap. */
42
+ protected cacheSet(query: string, document: string, score: number): void;
43
+ private cacheKey;
44
+ abstract rerank(query: string, documents: string[], opts?: {
45
+ timeoutMs?: number;
46
+ }): Promise<number[]>;
47
+ }
@@ -0,0 +1,73 @@
1
+ import { createHash } from "node:crypto";
2
+ /**
3
+ * Base implementation of {@link RerankProvider} supplying the cooldown state
4
+ * machine and an LRU-ish score cache. Subclasses implement `rerank()` and use
5
+ * {@link cacheGet}/{@link cacheSet} for memoization.
6
+ */
7
+ export class RerankProviderBase {
8
+ model;
9
+ failures = 0;
10
+ cooldownUntil = 0;
11
+ cooldownThreshold;
12
+ cooldownMs;
13
+ cacheMax;
14
+ /** Insertion/re-touch-ordered Map — the first key is the least recently used. */
15
+ cache = new Map();
16
+ constructor(model, options = {}) {
17
+ this.model = model;
18
+ this.cooldownThreshold = options.cooldownThreshold ?? 3;
19
+ this.cooldownMs = options.cooldownMs ?? 300_000;
20
+ this.cacheMax = options.cacheMax ?? 500;
21
+ }
22
+ /** False while the post-failure cooldown is active. */
23
+ available() {
24
+ return Date.now() >= this.cooldownUntil;
25
+ }
26
+ /** Counts a failed call; every `cooldownThreshold` failures trip the cooldown. */
27
+ noteFailure() {
28
+ this.failures += 1;
29
+ if (this.failures >= this.cooldownThreshold) {
30
+ this.failures = 0;
31
+ this.cooldownUntil = Date.now() + this.cooldownMs;
32
+ }
33
+ }
34
+ /** A success proves the provider is healthy again — reset the streak. */
35
+ noteSuccess() {
36
+ this.failures = 0;
37
+ }
38
+ /** Look up a cached score for this provider's model + query + document. */
39
+ cacheGet(query, document) {
40
+ const key = this.cacheKey(query, document);
41
+ const score = this.cache.get(key);
42
+ if (score !== undefined) {
43
+ // Touch: move to the most-recently-used end.
44
+ this.cache.delete(key);
45
+ this.cache.set(key, score);
46
+ }
47
+ return score;
48
+ }
49
+ /** Store a score, evicting the least recently used entry past the cap. */
50
+ cacheSet(query, document, score) {
51
+ const key = this.cacheKey(query, document);
52
+ this.cache.delete(key);
53
+ this.cache.set(key, score);
54
+ while (this.cache.size > this.cacheMax) {
55
+ const oldest = this.cache.keys().next();
56
+ if (oldest.done === true)
57
+ break;
58
+ this.cache.delete(oldest.value);
59
+ }
60
+ }
61
+ cacheKey(query, document) {
62
+ const hash = createHash("sha1");
63
+ hash.update(this.name);
64
+ hash.update("\0");
65
+ hash.update(this.model);
66
+ hash.update("\0");
67
+ hash.update(query);
68
+ hash.update("\0");
69
+ hash.update(document);
70
+ return hash.digest("hex");
71
+ }
72
+ }
73
+ //# sourceMappingURL=base.js.map
@@ -0,0 +1,16 @@
1
+ /**
2
+ * @fileoverview Factory for rerank providers. Mirrors the embedder/describer
3
+ * factory pattern: dispatch by config, return null when the feature is off.
4
+ * `getRerankerFor` memoizes one provider per distinct configuration so the
5
+ * failure cooldown and score cache survive across retrievals within a process.
6
+ */
7
+ import type { RerankingConfig } from "../core/config.js";
8
+ import type { RerankProvider } from "../core/interfaces.js";
9
+ /** Create a rerank provider from config, or null when reranking is disabled/unknown. */
10
+ export declare function createReranker(config?: RerankingConfig): RerankProvider | null;
11
+ /**
12
+ * Process-wide singleton lookup keyed by endpoint identity (provider|baseUrl|
13
+ * model|apiKey). Disabled configs return null without caching; an empty
14
+ * baseUrl/model returns a non-cached null so a later valid config still works.
15
+ */
16
+ export declare function getRerankerFor(config?: RerankingConfig): RerankProvider | null;
@@ -0,0 +1,47 @@
1
+ import { LlamaServerReranker } from "./llama-server.js";
2
+ /** Create a rerank provider from config, or null when reranking is disabled/unknown. */
3
+ export function createReranker(config) {
4
+ if (!config?.enabled)
5
+ return null;
6
+ const provider = config.provider ?? "llama-server";
7
+ if (provider === "llama-server") {
8
+ if (!config.baseUrl) {
9
+ console.warn("[reranker] reranking.enabled is true but reranking.baseUrl is empty — reranking disabled");
10
+ return null;
11
+ }
12
+ if (!config.model) {
13
+ console.warn("[reranker] reranking.enabled is true but reranking.model is empty — reranking disabled");
14
+ return null;
15
+ }
16
+ return new LlamaServerReranker(config);
17
+ }
18
+ console.warn(`[reranker] unknown reranking.provider "${provider}" — reranking disabled`);
19
+ return null;
20
+ }
21
+ /** Distinct-provider cache bound so config churn cannot grow it unboundedly. */
22
+ const RERANKER_CACHE_MAX = 8;
23
+ const providerCache = new Map();
24
+ /**
25
+ * Process-wide singleton lookup keyed by endpoint identity (provider|baseUrl|
26
+ * model|apiKey). Disabled configs return null without caching; an empty
27
+ * baseUrl/model returns a non-cached null so a later valid config still works.
28
+ */
29
+ export function getRerankerFor(config) {
30
+ if (!config?.enabled)
31
+ return null;
32
+ if (!config.baseUrl || !config.model)
33
+ return createReranker(config);
34
+ const key = `${config.provider ?? "llama-server"}|${config.baseUrl}|${config.model}|${config.apiKey ?? ""}`;
35
+ const cached = providerCache.get(key);
36
+ if (cached !== undefined)
37
+ return cached;
38
+ const provider = createReranker(config);
39
+ if (providerCache.size >= RERANKER_CACHE_MAX) {
40
+ const oldest = providerCache.keys().next();
41
+ if (!oldest.done)
42
+ providerCache.delete(oldest.value);
43
+ }
44
+ providerCache.set(key, provider);
45
+ return provider;
46
+ }
47
+ //# sourceMappingURL=factory.js.map
@@ -0,0 +1,33 @@
1
+ /**
2
+ * @fileoverview Rerank provider for llama-server's Cohere-style /v1/rerank
3
+ * endpoint (llama.cpp `--reranking --pooling rank`, optionally behind
4
+ * llama-swap which routes v1/rerank natively).
5
+ */
6
+ import type { RerankingConfig } from "../core/config.js";
7
+ import { RerankProviderBase } from "./base.js";
8
+ /**
9
+ * Cross-encoder reranker backed by llama-server.
10
+ *
11
+ * Sends `{ model, query, documents }` to `{baseUrl}/rerank` and maps
12
+ * `results[].relevance_score` back index-aligned with the input documents.
13
+ * Larger document sets are split into batches of at most
14
+ * `maxDocsPerRequest` and issued concurrently. Failures throw; the calling
15
+ * retrieval stage degrades to fusion order and records the failure for the
16
+ * shared cooldown in {@link RerankProviderBase}.
17
+ */
18
+ export declare class LlamaServerReranker extends RerankProviderBase {
19
+ readonly name = "llama-server";
20
+ private readonly baseUrl;
21
+ private readonly apiKey?;
22
+ private readonly defaultTimeoutMs;
23
+ private readonly proxy?;
24
+ private readonly maxDocsPerRequest;
25
+ constructor(config: Pick<RerankingConfig, "baseUrl" | "model" | "apiKey" | "timeoutMs" | "proxy">, options?: {
26
+ maxDocsPerRequest?: number;
27
+ });
28
+ rerank(query: string, documents: string[], opts?: {
29
+ timeoutMs?: number;
30
+ }): Promise<number[]>;
31
+ /** One /v1/rerank call; returns scores index-aligned with `documents`. */
32
+ private rerankBatch;
33
+ }
@@ -0,0 +1,101 @@
1
+ import { postJson } from "../embedder/http.js";
2
+ import { RerankProviderBase } from "./base.js";
3
+ /**
4
+ * Cross-encoder reranker backed by llama-server.
5
+ *
6
+ * Sends `{ model, query, documents }` to `{baseUrl}/rerank` and maps
7
+ * `results[].relevance_score` back index-aligned with the input documents.
8
+ * Larger document sets are split into batches of at most
9
+ * `maxDocsPerRequest` and issued concurrently. Failures throw; the calling
10
+ * retrieval stage degrades to fusion order and records the failure for the
11
+ * shared cooldown in {@link RerankProviderBase}.
12
+ */
13
+ export class LlamaServerReranker extends RerankProviderBase {
14
+ name = "llama-server";
15
+ baseUrl;
16
+ apiKey;
17
+ defaultTimeoutMs;
18
+ proxy;
19
+ maxDocsPerRequest;
20
+ constructor(config, options = {}) {
21
+ super(config.model);
22
+ this.baseUrl = config.baseUrl.replace(/\/+$/, "");
23
+ this.apiKey = config.apiKey;
24
+ this.defaultTimeoutMs = config.timeoutMs ?? 1500;
25
+ this.proxy = config.proxy;
26
+ // llama.cpp rerank context is sized for a handful of passages; batches
27
+ // beyond this risk context overflow on small --ctx servers.
28
+ this.maxDocsPerRequest = options.maxDocsPerRequest ?? 16;
29
+ }
30
+ async rerank(query, documents, opts) {
31
+ if (documents.length === 0)
32
+ return [];
33
+ const timeoutMs = opts?.timeoutMs ?? this.defaultTimeoutMs;
34
+ const scores = new Array(documents.length).fill(0);
35
+ const missingIndices = [];
36
+ for (let i = 0; i < documents.length; i++) {
37
+ const cached = this.cacheGet(query, documents[i] ?? "");
38
+ if (cached !== undefined) {
39
+ scores[i] = cached;
40
+ }
41
+ else {
42
+ missingIndices.push(i);
43
+ }
44
+ }
45
+ if (missingIndices.length === 0)
46
+ return scores;
47
+ const batches = [];
48
+ for (let i = 0; i < missingIndices.length; i += this.maxDocsPerRequest) {
49
+ batches.push(missingIndices.slice(i, i + this.maxDocsPerRequest));
50
+ }
51
+ const batchScores = await Promise.all(batches.map((batch) => this.rerankBatch(query, batch.map((i) => documents[i] ?? ""), timeoutMs)));
52
+ for (let b = 0; b < batches.length; b++) {
53
+ const batch = batches[b];
54
+ const batchResult = batchScores[b];
55
+ if (!batch || !batchResult)
56
+ continue;
57
+ for (let j = 0; j < batch.length; j++) {
58
+ const docIndex = batch[j];
59
+ const score = batchResult[j] ?? 0;
60
+ if (docIndex === undefined)
61
+ continue;
62
+ scores[docIndex] = score;
63
+ this.cacheSet(query, documents[docIndex] ?? "", score);
64
+ }
65
+ }
66
+ return scores;
67
+ }
68
+ /** One /v1/rerank call; returns scores index-aligned with `documents`. */
69
+ async rerankBatch(query, documents, timeoutMs) {
70
+ const headers = {};
71
+ if (this.apiKey) {
72
+ headers.Authorization = `Bearer ${this.apiKey}`;
73
+ }
74
+ const response = await postJson(`${this.baseUrl}/rerank`, { model: this.model, query, documents }, headers, timeoutMs, this.proxy);
75
+ if (!response.ok) {
76
+ const body = await response.text().catch(() => "");
77
+ throw new Error(`llama-server rerank failed (${response.status}): ${body.slice(0, 200)}`);
78
+ }
79
+ const json = (await response.json());
80
+ if (!Array.isArray(json.results)) {
81
+ throw new Error(`llama-server rerank: unexpected response: ${JSON.stringify(json).slice(0, 200)}`);
82
+ }
83
+ const scores = new Array(documents.length).fill(0);
84
+ let matched = 0;
85
+ for (const entry of json.results) {
86
+ const index = entry?.index;
87
+ const score = entry?.relevance_score;
88
+ if (typeof index !== "number" || index < 0 || index >= documents.length)
89
+ continue;
90
+ if (typeof score !== "number" || !Number.isFinite(score))
91
+ continue;
92
+ scores[index] = score;
93
+ matched++;
94
+ }
95
+ if (matched === 0) {
96
+ throw new Error("llama-server rerank: response contained no usable relevance_score entries");
97
+ }
98
+ return scores;
99
+ }
100
+ }
101
+ //# sourceMappingURL=llama-server.js.map
@@ -9,6 +9,7 @@ import type { Chunk, SearchResult, MetadataFilter } from "../core/interfaces.js"
9
9
  * @returns Array of unique normalized tokens
10
10
  */
11
11
  export declare function tokenize(text: string): string[];
12
+ export declare function indexPathFor(storePath: string): string;
12
13
  /**
13
14
  * In-memory inverted keyword index with stemming, TF-IDF scoring, and optional JSON serialization.
14
15
  *
@@ -69,7 +69,7 @@ export function tokenize(text) {
69
69
  }
70
70
  return [...tokens];
71
71
  }
72
- function indexPathFor(storePath) {
72
+ export function indexPathFor(storePath) {
73
73
  return storePath.replace(/\\/g, "/").replace(/\/+$/, "") + "/keyword-index.json";
74
74
  }
75
75
  /**
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @fileoverview Performs hybrid vector-keyword retrieval with configurable scoring and explanation.
3
3
  */
4
- import type { EmbeddingProvider, KeywordIndex, VectorStore, SearchResult, MetadataFilter } from "../core/interfaces.js";
4
+ import type { EmbeddingProvider, KeywordIndex, RerankProvider, VectorStore, SearchResult, MetadataFilter } from "../core/interfaces.js";
5
5
  /** Options controlling the retrieval behavior. */
6
6
  export interface RetrieveOptions {
7
7
  topK?: number;
@@ -20,6 +20,29 @@ export interface RetrieveOptions {
20
20
  queryPrefix?: string;
21
21
  explain?: boolean;
22
22
  filter?: MetadataFilter;
23
+ /**
24
+ * Optional cross-encoder reranker. When set (and not cooling down), the top
25
+ * fused candidates are re-scored and re-ordered after the fusion `minScore`
26
+ * gate. Any provider failure/timeout degrades to the fusion order.
27
+ */
28
+ reranker?: RerankProvider;
29
+ /** Tunables for the rerank stage (defaults apply when omitted). */
30
+ reranking?: RerankStageOptions;
31
+ }
32
+ /** Tunables for the optional rerank stage inside retrieve(). */
33
+ export interface RerankStageOptions {
34
+ /** Candidates (after the fusion minScore gate) sent to the reranker. Default 20. */
35
+ candidates?: number;
36
+ /** Per-document text truncation in characters. Default 1200. */
37
+ maxDocChars?: number;
38
+ /** Gate on the rerank score itself; 0 (default) = pure reorder, nothing dropped. */
39
+ minScore?: number;
40
+ /** `{query}`-placeholder template or prefix applied to the query before scoring. */
41
+ queryTemplate?: string;
42
+ /** Score raw chunk content or description+content. Default "content". */
43
+ docField?: "content" | "content+description";
44
+ /** Per-call timeout in ms handed to the provider. Default 1500. */
45
+ timeoutMs?: number;
23
46
  }
24
47
  /**
25
48
  * Perform hybrid vector-keyword retrieval with configurable scoring.
@@ -5,6 +5,71 @@ const FETCH_OVERFETCH_FACTOR = 3;
5
5
  const RRF_K = 60;
6
6
  /** Multiply raw RRF scores by (K+1) to normalize to ~[0,1]. */
7
7
  const RRF_NORMALIZE = RRF_K + 1;
8
+ const RERANK_DEFAULTS = {
9
+ candidates: 20,
10
+ maxDocChars: 1200,
11
+ minScore: 0,
12
+ timeoutMs: 1500,
13
+ };
14
+ /** Apply the rerank query template: `{query}` substitution, else prefix. */
15
+ function applyQueryTemplate(query, template) {
16
+ if (!template)
17
+ return query;
18
+ return template.includes("{query}") ? template.split("{query}").join(query) : template + query;
19
+ }
20
+ /** Build the rerank document text for a chunk, honoring docField + truncation. */
21
+ function buildRerankDoc(chunk, docField, maxChars) {
22
+ const text = docField === "content+description" && chunk.description
23
+ ? `${chunk.description}\n${chunk.content}`
24
+ : chunk.content;
25
+ return text.length > maxChars ? text.slice(0, maxChars) : text;
26
+ }
27
+ /**
28
+ * Optional reorder stage applied to minScore-filtered, fusion-sorted results.
29
+ *
30
+ * The first `candidates` results are scored by the reranker and re-ordered
31
+ * (rerank score desc, fusion rank as tie-breaker); the remainder keeps its
32
+ * fusion order and trails the pool. `result.score` is replaced by the rerank
33
+ * score (the fused components stay in `explanation.scoreBreakdown`, plus the
34
+ * new `rerankScore`). A provider in cooldown, missing, or failing never
35
+ * changes behavior beyond that reorder.
36
+ */
37
+ async function applyRerankStage(query, results, topK, reranker, stage) {
38
+ if (!reranker)
39
+ return results.slice(0, topK);
40
+ const pool = results.slice(0, Math.max(topK, stage?.candidates ?? RERANK_DEFAULTS.candidates));
41
+ const tail = results.slice(pool.length);
42
+ if (pool.length === 0)
43
+ return results.slice(0, topK);
44
+ if (!reranker.available())
45
+ return [...pool, ...tail].slice(0, topK);
46
+ const maxChars = stage?.maxDocChars ?? RERANK_DEFAULTS.maxDocChars;
47
+ const docField = stage?.docField ?? "content";
48
+ const docs = pool.map((r) => buildRerankDoc(r.chunk, docField, maxChars));
49
+ let scores;
50
+ try {
51
+ scores = await reranker.rerank(applyQueryTemplate(query, stage?.queryTemplate), docs, { timeoutMs: stage?.timeoutMs ?? RERANK_DEFAULTS.timeoutMs });
52
+ }
53
+ catch (err) {
54
+ reranker.noteFailure();
55
+ console.warn(`[retriever] rerank skipped (${err instanceof Error ? err.message : String(err)}) — keeping fusion order`);
56
+ return [...pool, ...tail].slice(0, topK);
57
+ }
58
+ reranker.noteSuccess();
59
+ const minRerank = stage?.minScore ?? RERANK_DEFAULTS.minScore;
60
+ const indexed = pool.map((r, i) => ({ r, i, score: scores[i] ?? 0 }));
61
+ for (const entry of indexed) {
62
+ entry.r.score = entry.score;
63
+ if (entry.r.explanation) {
64
+ entry.r.explanation.scoreBreakdown.rerankScore = entry.score;
65
+ }
66
+ }
67
+ const reordered = indexed
68
+ .filter((e) => minRerank <= 0 || e.score >= minRerank)
69
+ .sort((a, b) => b.score - a.score || a.i - b.i)
70
+ .map((e) => e.r);
71
+ return [...reordered, ...tail].slice(0, topK);
72
+ }
8
73
  /** Classify a query as a bare symbol lookup vs. natural-language prose.
9
74
  * Symbol queries have no whitespace and look like one (possibly dotted) identifier. */
10
75
  function detectQueryShape(query) {
@@ -81,7 +146,7 @@ export async function retrieve(query, embedder, store, options = {}) {
81
146
  keywordResults = options.keywordIndex.search(query, topK * FETCH_OVERFETCH_FACTOR, options.filter);
82
147
  }
83
148
  if (keywordResults.length === 0) {
84
- const filtered = vectorResults.filter((r) => r.score >= minScore).slice(0, topK);
149
+ const filtered = vectorResults.filter((r) => r.score >= minScore);
85
150
  if (options.explain) {
86
151
  for (const r of filtered) {
87
152
  r.explanation = {
@@ -97,7 +162,7 @@ export async function retrieve(query, embedder, store, options = {}) {
97
162
  }
98
163
  attachConfidence(filtered);
99
164
  }
100
- return filtered;
165
+ return applyRerankStage(query, filtered, topK, options.reranker, options.reranking);
101
166
  }
102
167
  const vRank = new Map(vectorResults.map((r, i) => [r.chunk.id, i]));
103
168
  const kRank = new Map(keywordResults.map((r, i) => [r.chunk.id, i]));
@@ -142,11 +207,10 @@ export async function retrieve(query, embedder, store, options = {}) {
142
207
  })
143
208
  .filter((r) => r !== null)
144
209
  .filter((r) => r.score >= minScore)
145
- .sort((a, b) => b.score - a.score)
146
- .slice(0, topK);
210
+ .sort((a, b) => b.score - a.score);
147
211
  if (options.explain)
148
212
  attachConfidence(combinedResults);
149
- return combinedResults;
213
+ return applyRerankStage(query, combinedResults, topK, options.reranker, options.reranking);
150
214
  }
151
215
  catch (err) {
152
216
  // Never silently mask retrieval failures as "no results" — an embedder
@@ -39,8 +39,8 @@ declare module "@opencode-ai/plugin" {
39
39
  output: { args: Record<string, unknown> }
40
40
  ) => Promise<void>;
41
41
  "tool.execute.after"?: (
42
- input: { tool: string; sessionID: string; callID: string },
43
- output: { title: string; output: string; metadata: unknown }
42
+ input: { tool: string; sessionID: string; callID: string; status?: "completed" | "error" },
43
+ output: { title: string; output: string; metadata: unknown; error?: string }
44
44
  ) => Promise<void>;
45
45
  "experimental.chat.messages.transform"?: (
46
46
  input: Record<string, never>,
@@ -68,7 +68,7 @@ type V2Tool = {
68
68
  metadata?: Record<string, unknown>;
69
69
  }>;
70
70
  };
71
- /** V2 `execute.after` hook event (completed branch). */
71
+ /** V2 `execute.after` hook event — fires for BOTH the completed and the error branch. */
72
72
  type V2ToolExecuteAfterEvent = {
73
73
  tool: string;
74
74
  sessionID: string;
@@ -77,7 +77,12 @@ type V2ToolExecuteAfterEvent = {
77
77
  result?: {
78
78
  output?: unknown;
79
79
  content?: string | readonly unknown[];
80
+ error?: unknown;
81
+ message?: unknown;
80
82
  };
83
+ /** Error payload fields observed on the error branch (defensively optional). */
84
+ error?: unknown;
85
+ message?: unknown;
81
86
  };
82
87
  /** V2 `prompt` hook event. */
83
88
  type V2PromptHookEvent = {