opencode-rag-plugin 1.23.2 → 2.0.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 (42) hide show
  1. package/dist/api.js +3 -0
  2. package/dist/chunker/factory.d.ts +4 -0
  3. package/dist/chunker/factory.js +36 -7
  4. package/dist/cli/commands/init-helpers.d.ts +2 -0
  5. package/dist/cli/commands/init-helpers.js +2 -5
  6. package/dist/core/chunk-role.d.ts +22 -0
  7. package/dist/core/chunk-role.js +47 -0
  8. package/dist/core/config.d.ts +19 -3
  9. package/dist/core/config.js +24 -4
  10. package/dist/core/interfaces.d.ts +10 -0
  11. package/dist/index.d.ts +2 -10
  12. package/dist/index.js +1 -7
  13. package/dist/indexer/pipeline.js +6 -0
  14. package/dist/indexer/worker.d.ts +2 -0
  15. package/dist/indexer/worker.js +2 -0
  16. package/dist/opencode/create-read-tool.js +2 -2
  17. package/dist/opencode/tools.js +7 -7
  18. package/dist/plugin-entry.d.ts +10 -12
  19. package/dist/plugin-entry.js +22 -8
  20. package/dist/plugin.js +10 -8
  21. package/dist/retriever/context-optimizer.js +13 -1
  22. package/dist/retriever/keyword-index.d.ts +15 -0
  23. package/dist/retriever/keyword-index.js +119 -7
  24. package/dist/retriever/retriever.d.ts +7 -0
  25. package/dist/retriever/retriever.js +56 -4
  26. package/dist/tui.d.ts +85 -2
  27. package/dist/tui.js +319 -378
  28. package/dist/v2/v2-adapter.d.ts +103 -0
  29. package/dist/v2/v2-adapter.js +226 -0
  30. package/dist/vectorstore/lancedb.d.ts +1 -1
  31. package/dist/vectorstore/lancedb.js +12 -4
  32. package/dist/vectorstore/memory.js +1 -0
  33. package/dist/web/ui/assets/ScatterPlot3D-CKwyh1Ec.js +4108 -0
  34. package/dist/web/ui/assets/index-Cgv1RsGv.js +4 -0
  35. package/dist/web/ui/assets/index-DjJHIo9R.css +1 -0
  36. package/dist/web/ui/assets/vendor-Dg8wMT7C.js +1 -0
  37. package/dist/web/ui/index.html +3 -3
  38. package/package.json +16 -11
  39. package/dist/web/ui/assets/ScatterPlot3D-DQLl3sKN.js +0 -4116
  40. package/dist/web/ui/assets/index-BZh9MitV.js +0 -4
  41. package/dist/web/ui/assets/index-DKhjGsql.css +0 -1
  42. package/dist/web/ui/assets/vendor-Dy7HKFCY.js +0 -1
@@ -63,6 +63,10 @@ function mergeAdjacentChunks(results, gapThreshold) {
63
63
  const sorted = [...results].sort((a, b) => a.chunk.metadata.startLine - b.chunk.metadata.startLine);
64
64
  const merged = [];
65
65
  let pending = toOptimized(sorted[0]);
66
+ // The explanation (score breakdown, ranks) of the best-scoring constituent —
67
+ // carried onto the merged result so `--explain` stays accurate after merges.
68
+ let pendingExplanation = sorted[0].explanation;
69
+ let pendingBestScore = sorted[0].score;
66
70
  for (let i = 1; i < sorted.length; i++) {
67
71
  const current = sorted[i];
68
72
  const gap = current.chunk.metadata.startLine - pending.chunk.metadata.endLine;
@@ -83,15 +87,23 @@ function mergeAdjacentChunks(results, gapThreshold) {
83
87
  endLine: current.chunk.metadata.endLine,
84
88
  },
85
89
  };
90
+ const bestScore = Math.max(pending.score, current.score);
91
+ if (current.score > pendingBestScore) {
92
+ pendingBestScore = current.score;
93
+ pendingExplanation = current.explanation;
94
+ }
86
95
  pending = {
87
96
  chunk: mergedChunk,
88
- score: Math.max(pending.score, current.score),
97
+ score: bestScore,
98
+ explanation: pendingExplanation,
89
99
  optimized: { mergedFrom: sourceIds },
90
100
  };
91
101
  }
92
102
  else {
93
103
  merged.push(pending);
94
104
  pending = toOptimized(current);
105
+ pendingExplanation = current.explanation;
106
+ pendingBestScore = current.score;
95
107
  }
96
108
  }
97
109
  if (pending)
@@ -20,11 +20,26 @@ export declare class KeywordIndex {
20
20
  private readonly storePath?;
21
21
  /** filePath (normalized) → chunk IDs, for O(chunks-in-file) removal. */
22
22
  private fileToIds;
23
+ /** Indexed-token length per chunk, and the running total — drives BM25 length
24
+ * normalization so long chunks can't dominate purely on term frequency. */
25
+ private docLengths;
26
+ private totalTokens;
27
+ /** The exact set of tokens indexed per chunk id, recorded at add time.
28
+ * Removal deletes precisely these entries instead of re-tokenizing the
29
+ * chunk: re-derivation would leave dangling inverted-index references
30
+ * whenever the chunk's text drifted between indexing and removal (the
31
+ * description stage mutates `chunk.description` after addChunks, or the
32
+ * persisted index was written by a build whose tokenizer differed). */
33
+ private chunkTokens;
23
34
  constructor(storePath?: string);
24
35
  addChunks(chunks: Chunk[]): void;
25
36
  getMatchedTerms(query: string, chunkId: string): string[];
26
37
  removeByFilePath(filePath: string): void;
27
38
  search(query: string, topK: number, filter?: MetadataFilter): SearchResult[];
39
+ /** Remove every inverted-index reference to chunk ids that no longer have a
40
+ * chunkMap entry. Uses the recorded token set when available (fast path,
41
+ * always taken for loaded indexes) and falls back to a full scan. */
42
+ private pruneDangling;
28
43
  close(): void;
29
44
  clear(): void;
30
45
  count(): number;
@@ -1,6 +1,14 @@
1
1
  import { normalizeFilePath } from "../core/manifest.js";
2
2
  import { normalizeFileExtensions, matchesFileExtension } from "../core/filters.js";
3
- const INDEX_VERSION = 2;
3
+ const INDEX_VERSION = 3;
4
+ /**
5
+ * Text indexed for keyword search: chunk content plus its LLM description when
6
+ * one exists. Without this, keyword and vector search would see different text
7
+ * spaces — a description can name a concept the raw code never spells out.
8
+ */
9
+ function indexableText(chunk) {
10
+ return chunk.description ? `${chunk.content}\n${chunk.description}` : chunk.content;
11
+ }
4
12
  /** Suffix-stripping stemmer. Only stems words >= 6 characters to reduce false positives. */
5
13
  function stem(word) {
6
14
  if (word.length < 6)
@@ -75,6 +83,17 @@ export class KeywordIndex {
75
83
  storePath;
76
84
  /** filePath (normalized) → chunk IDs, for O(chunks-in-file) removal. */
77
85
  fileToIds = new Map();
86
+ /** Indexed-token length per chunk, and the running total — drives BM25 length
87
+ * normalization so long chunks can't dominate purely on term frequency. */
88
+ docLengths = new Map();
89
+ totalTokens = 0;
90
+ /** The exact set of tokens indexed per chunk id, recorded at add time.
91
+ * Removal deletes precisely these entries instead of re-tokenizing the
92
+ * chunk: re-derivation would leave dangling inverted-index references
93
+ * whenever the chunk's text drifted between indexing and removal (the
94
+ * description stage mutates `chunk.description` after addChunks, or the
95
+ * persisted index was written by a build whose tokenizer differed). */
96
+ chunkTokens = new Map();
78
97
  constructor(storePath) {
79
98
  this.storePath = storePath;
80
99
  }
@@ -89,7 +108,10 @@ export class KeywordIndex {
89
108
  this.fileToIds.set(fileKey, ids);
90
109
  }
91
110
  ids.add(id);
92
- const tokens = tokenize(chunk.content);
111
+ const tokens = tokenize(indexableText(chunk));
112
+ this.docLengths.set(id, tokens.length);
113
+ this.totalTokens += tokens.length;
114
+ this.chunkTokens.set(id, new Set(tokens));
93
115
  for (const token of tokens) {
94
116
  let docs = this.invertedIndex.get(token);
95
117
  if (!docs) {
@@ -132,7 +154,10 @@ export class KeywordIndex {
132
154
  for (const id of idsToRemove) {
133
155
  const chunk = this.chunkMap.get(id);
134
156
  if (chunk) {
135
- const tokens = tokenize(chunk.content);
157
+ // Delete exactly the entries addChunks created. The recorded token set
158
+ // is authoritative; re-derive only when the entry predates exact
159
+ // tracking (loaded indexes always rebuild chunkTokens in load()).
160
+ const tokens = this.chunkTokens.get(id) ?? new Set(tokenize(indexableText(chunk)));
136
161
  for (const token of tokens) {
137
162
  const docs = this.invertedIndex.get(token);
138
163
  if (docs) {
@@ -143,6 +168,12 @@ export class KeywordIndex {
143
168
  }
144
169
  }
145
170
  this.chunkMap.delete(id);
171
+ this.chunkTokens.delete(id);
172
+ const len = this.docLengths.get(id);
173
+ if (len !== undefined) {
174
+ this.totalTokens -= len;
175
+ this.docLengths.delete(id);
176
+ }
146
177
  }
147
178
  }
148
179
  }
@@ -153,36 +184,91 @@ export class KeywordIndex {
153
184
  if (queryTokens.length === 0)
154
185
  return [];
155
186
  const totalChunks = this.chunkMap.size;
187
+ const avgDocLength = this.totalTokens > 0 ? this.totalTokens / totalChunks : 0;
156
188
  const scores = new Map();
189
+ // BM25: term-frequency saturation plus length normalization, so a chunk that
190
+ // merely repeats a term (or is very long) can't outrank a focused match.
191
+ const K1 = 1.2;
192
+ const B = 0.75;
157
193
  for (const token of queryTokens) {
158
194
  const docs = this.invertedIndex.get(token);
159
195
  if (!docs)
160
196
  continue;
161
197
  const df = docs.size;
162
- const idf = Math.log(1 + totalChunks / (df || 1));
198
+ const idf = Math.log(1 + (totalChunks - df + 0.5) / (df + 0.5));
163
199
  for (const [chunkId, freq] of docs) {
164
- const score = freq * idf;
165
- scores.set(chunkId, (scores.get(chunkId) ?? 0) + score);
200
+ const docLength = this.docLengths.get(chunkId) ?? avgDocLength;
201
+ const lengthNorm = avgDocLength > 0
202
+ ? 1 - B + B * (docLength / avgDocLength)
203
+ : 1;
204
+ const tf = (freq * (K1 + 1)) / (freq + K1 * lengthNorm);
205
+ scores.set(chunkId, (scores.get(chunkId) ?? 0) + idf * tf);
166
206
  }
167
207
  }
208
+ const dangling = [];
168
209
  const sorted = [...scores.entries()]
169
- .filter(([id]) => matchesFilter(this.chunkMap.get(id), filter))
210
+ .filter(([id]) => {
211
+ const chunk = this.chunkMap.get(id);
212
+ if (!chunk) {
213
+ // The inverted index references a chunk id that no longer exists.
214
+ // This is the "undefined is not an object (evaluating
215
+ // 'chunk.metadata')" crash site: a removal that missed tokens
216
+ // (index persisted by an older build, interrupted re-index) leaves
217
+ // phantom ids behind. Skip and prune them so a corrupt index
218
+ // self-heals instead of failing every filtered search.
219
+ dangling.push(id);
220
+ return false;
221
+ }
222
+ return matchesFilter(chunk, filter);
223
+ })
170
224
  .sort((a, b) => b[1] - a[1])
171
225
  .slice(0, topK);
226
+ if (dangling.length > 0)
227
+ this.pruneDangling(dangling);
172
228
  return sorted.map(([chunkId, score]) => {
173
229
  const chunk = this.chunkMap.get(chunkId);
174
230
  return { chunk, score };
175
231
  });
176
232
  }
233
+ /** Remove every inverted-index reference to chunk ids that no longer have a
234
+ * chunkMap entry. Uses the recorded token set when available (fast path,
235
+ * always taken for loaded indexes) and falls back to a full scan. */
236
+ pruneDangling(ids) {
237
+ for (const id of ids) {
238
+ const tokens = this.chunkTokens.get(id);
239
+ if (tokens) {
240
+ for (const token of tokens) {
241
+ const docs = this.invertedIndex.get(token);
242
+ if (docs) {
243
+ docs.delete(id);
244
+ if (docs.size === 0)
245
+ this.invertedIndex.delete(token);
246
+ }
247
+ }
248
+ }
249
+ else {
250
+ for (const [token, docs] of this.invertedIndex) {
251
+ if (docs.delete(id) && docs.size === 0)
252
+ this.invertedIndex.delete(token);
253
+ }
254
+ }
255
+ this.chunkTokens.delete(id);
256
+ this.docLengths.delete(id);
257
+ }
258
+ }
177
259
  close() {
178
260
  this.invertedIndex.clear();
179
261
  this.chunkMap.clear();
180
262
  this.fileToIds.clear();
263
+ this.chunkTokens.clear();
181
264
  }
182
265
  clear() {
183
266
  this.invertedIndex.clear();
184
267
  this.chunkMap.clear();
185
268
  this.fileToIds.clear();
269
+ this.chunkTokens.clear();
270
+ this.docLengths.clear();
271
+ this.totalTokens = 0;
186
272
  }
187
273
  count() {
188
274
  return this.chunkMap.size;
@@ -209,6 +295,7 @@ export class KeywordIndex {
209
295
  endLine: chunk.metadata.endLine,
210
296
  language: chunk.metadata.language,
211
297
  kind: chunk.metadata.kind ?? "",
298
+ role: chunk.metadata.role ?? "",
212
299
  quirkType: chunk.metadata.quirkType ?? "",
213
300
  tags: chunk.metadata.tags ? JSON.stringify(chunk.metadata.tags) : "",
214
301
  },
@@ -241,6 +328,19 @@ export class KeywordIndex {
241
328
  const docMap = new Map(docs);
242
329
  index.invertedIndex.set(token, docMap);
243
330
  }
331
+ // Rebuild the exact per-chunk token sets from the persisted inverted
332
+ // index, so removal is exact even for indexes written by older builds
333
+ // (whose tokenizer or indexableText may have differed).
334
+ for (const [token, docs] of index.invertedIndex) {
335
+ for (const id of docs.keys()) {
336
+ let tokens = index.chunkTokens.get(id);
337
+ if (!tokens) {
338
+ tokens = new Set();
339
+ index.chunkTokens.set(id, tokens);
340
+ }
341
+ tokens.add(token);
342
+ }
343
+ }
244
344
  for (const [id, data] of Object.entries(parsed.chunkMap)) {
245
345
  let tags;
246
346
  try {
@@ -260,11 +360,23 @@ export class KeywordIndex {
260
360
  endLine: data.endLine,
261
361
  language: data.language,
262
362
  kind: data.kind || undefined,
363
+ role: data.role === "source" || data.role === "test" || data.role === "doc" ? data.role : undefined,
263
364
  quirkType: data.quirkType || undefined,
264
365
  tags,
265
366
  },
266
367
  });
267
368
  }
369
+ // Recompute BM25 length statistics from the loaded chunk map. The persisted
370
+ // inverted index is authoritative for term frequencies; lengths are cheap
371
+ // to derive and this keeps the serialized format lean.
372
+ for (const [id, chunk] of index.chunkMap) {
373
+ // Prefer the exact token count from the inverted index over
374
+ // re-tokenizing — re-tokenization can drift from what was indexed.
375
+ const recorded = index.chunkTokens.get(id);
376
+ const len = recorded ? recorded.size : tokenize(indexableText(chunk)).length;
377
+ index.docLengths.set(id, len);
378
+ index.totalTokens += len;
379
+ }
268
380
  // Rebuild the per-file id index from the loaded chunk map so removals
269
381
  // work even for entries persisted by older versions.
270
382
  for (const [id, chunk] of index.chunkMap) {
@@ -8,6 +8,13 @@ export interface RetrieveOptions {
8
8
  minScore?: number;
9
9
  keywordIndex?: KeywordIndex;
10
10
  keywordWeight?: number;
11
+ /** Keyword weight for symbol-style queries (a bare identifier like `cosineSimilarity`).
12
+ * Keyword search nails exact symbol matches, so these queries get a higher weight. */
13
+ symbolKeywordWeight?: number;
14
+ /** Multiplier applied to the keyword contribution of documentation chunks (0-1). */
15
+ docKeywordDemotion?: number;
16
+ /** Multiplier applied to the keyword contribution of test chunks (0-1). */
17
+ testKeywordDemotion?: number;
11
18
  /** Whether hybrid search is enabled. When false, keyword index is ignored. */
12
19
  hybridEnabled?: boolean;
13
20
  queryPrefix?: string;
@@ -5,6 +5,41 @@ 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
+ /** Classify a query as a bare symbol lookup vs. natural-language prose.
9
+ * Symbol queries have no whitespace and look like one (possibly dotted) identifier. */
10
+ function detectQueryShape(query) {
11
+ const trimmed = query.trim();
12
+ if (trimmed.length === 0 || trimmed.length > 60)
13
+ return "natural-language";
14
+ if (/\s/.test(trimmed))
15
+ return "natural-language";
16
+ return /^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*$/.test(trimmed)
17
+ ? "symbol"
18
+ : "natural-language";
19
+ }
20
+ /** Demotion applied to a chunk's keyword contribution based on its file's provenance.
21
+ * Docs and tests name concepts literally, so their keyword matches are discounted. */
22
+ function keywordDemotion(chunk, docDemotion, testDemotion) {
23
+ switch (chunk.metadata.role) {
24
+ case "doc": return docDemotion;
25
+ case "test": return testDemotion;
26
+ default: return 1;
27
+ }
28
+ }
29
+ /** Calibrate a per-result confidence from the raw vector-score spread of the
30
+ * candidate set. Unlike the fused RRF score (rank 0 is always ~1.0), this
31
+ * reflects how separable the top match actually was. */
32
+ function attachConfidence(results) {
33
+ const raws = results.map((r) => r.explanation?.scoreBreakdown?.rawVectorScore ?? 0);
34
+ const max = Math.max(...raws);
35
+ const min = Math.min(...raws);
36
+ for (const r of results) {
37
+ if (!r.explanation)
38
+ continue;
39
+ const raw = r.explanation.scoreBreakdown?.rawVectorScore ?? 0;
40
+ r.explanation.confidence = max > min ? (raw - min) / (max - min) : 1;
41
+ }
42
+ }
8
43
  /**
9
44
  * Perform hybrid vector-keyword retrieval with configurable scoring.
10
45
  *
@@ -22,6 +57,15 @@ export async function retrieve(query, embedder, store, options = {}) {
22
57
  try {
23
58
  const topK = options.topK ?? 10;
24
59
  const minScore = options.minScore ?? 0;
60
+ const queryShape = detectQueryShape(query);
61
+ const baseKw = options.keywordWeight ?? 0.4;
62
+ // Symbol queries are exact-identifier lookups — keyword search is the strong
63
+ // signal there, so use the (typically higher) symbol weight.
64
+ const kw = queryShape === "symbol"
65
+ ? options.symbolKeywordWeight ?? baseKw
66
+ : baseKw;
67
+ const docDemotion = options.docKeywordDemotion ?? 0.5;
68
+ const testDemotion = options.testKeywordDemotion ?? 0.6;
25
69
  const prefixedQuery = (options.queryPrefix ?? "") + query;
26
70
  const embeddings = await embedder.embed([prefixedQuery], "query");
27
71
  const embedding = embeddings[0];
@@ -39,7 +83,6 @@ export async function retrieve(query, embedder, store, options = {}) {
39
83
  if (keywordResults.length === 0) {
40
84
  const filtered = vectorResults.filter((r) => r.score >= minScore).slice(0, topK);
41
85
  if (options.explain) {
42
- const kw = options.keywordWeight ?? 0.4;
43
86
  for (const r of filtered) {
44
87
  r.explanation = {
45
88
  scoreBreakdown: {
@@ -49,8 +92,10 @@ export async function retrieve(query, embedder, store, options = {}) {
49
92
  rawKeywordScore: 0,
50
93
  keywordWeight: kw,
51
94
  },
95
+ queryShape,
52
96
  };
53
97
  }
98
+ attachConfidence(filtered);
54
99
  }
55
100
  return filtered;
56
101
  }
@@ -62,15 +107,18 @@ export async function retrieve(query, embedder, store, options = {}) {
62
107
  for (const r of keywordResults)
63
108
  if (!chunkById.has(r.chunk.id))
64
109
  chunkById.set(r.chunk.id, r);
65
- const kw = options.keywordWeight ?? 0.4;
66
110
  const allIds = new Set([...vRank.keys(), ...kRank.keys()]);
67
111
  const combinedResults = [...allIds].map((id) => {
68
112
  const vR = vRank.get(id);
69
113
  const kR = kRank.get(id);
114
+ const chunk = chunkById.get(id)?.chunk;
115
+ if (!chunk)
116
+ return null;
117
+ const kMultiplier = kR !== undefined ? keywordDemotion(chunk, docDemotion, testDemotion) : 1;
70
118
  const vContrib = vR !== undefined ? ((1 - kw) * RRF_NORMALIZE) / (RRF_K + vR + 1) : 0;
71
- const kContrib = kR !== undefined ? (kw * RRF_NORMALIZE) / (RRF_K + kR + 1) : 0;
119
+ const kContrib = kR !== undefined ? (kw * RRF_NORMALIZE) / (RRF_K + kR + 1) * kMultiplier : 0;
72
120
  const score = vContrib + kContrib;
73
- const result = { chunk: chunkById.get(id).chunk, score };
121
+ const result = { chunk, score };
74
122
  if (options.explain) {
75
123
  result.explanation = {
76
124
  scoreBreakdown: {
@@ -82,6 +130,7 @@ export async function retrieve(query, embedder, store, options = {}) {
82
130
  vectorRank: vR,
83
131
  keywordRank: kR,
84
132
  },
133
+ queryShape,
85
134
  };
86
135
  if (options.keywordIndex && kR !== undefined) {
87
136
  const terms = options.keywordIndex.getMatchedTerms(query, id);
@@ -91,9 +140,12 @@ export async function retrieve(query, embedder, store, options = {}) {
91
140
  }
92
141
  return result;
93
142
  })
143
+ .filter((r) => r !== null)
94
144
  .filter((r) => r.score >= minScore)
95
145
  .sort((a, b) => b.score - a.score)
96
146
  .slice(0, topK);
147
+ if (options.explain)
148
+ attachConfidence(combinedResults);
97
149
  return combinedResults;
98
150
  }
99
151
  catch (err) {
package/dist/tui.d.ts CHANGED
@@ -2,13 +2,96 @@
2
2
  * @fileoverview OpenCode TUI (Terminal UI) plugin: renders a sidebar with RAG status,
3
3
  * settings dialog for editing config values, and model selection picker.
4
4
  */
5
- import type { TuiPluginModule } from "@opencode-ai/plugin/tui";
5
+ import type { JSX } from "@opentui/solid";
6
+ /**
7
+ * Structural subset of the OpenCode V2 TUI plugin context
8
+ * (`@opencode/plugin/tui`). Declared locally so this module compiles
9
+ * without depending on V2 type resolution; see `src/v2/v2-adapter.ts`
10
+ * for the server-side equivalent.
11
+ */
12
+ type V2TuiContext = {
13
+ location?: {
14
+ directory?: string;
15
+ } | undefined;
16
+ app?: {
17
+ version?: string;
18
+ } | undefined;
19
+ theme?: unknown;
20
+ renderer?: unknown;
21
+ data?: {
22
+ provider?: {
23
+ list?: () => readonly unknown[] | undefined;
24
+ };
25
+ model?: {
26
+ list?: () => readonly unknown[] | undefined;
27
+ };
28
+ } | undefined;
29
+ ui?: {
30
+ slot: (claim: {
31
+ append: string;
32
+ render: (input: {
33
+ sessionID?: string;
34
+ }) => JSX.Element;
35
+ }) => () => void;
36
+ dialog: {
37
+ select: <Value>(options: {
38
+ title: string;
39
+ placeholder?: string;
40
+ options: readonly {
41
+ title: string;
42
+ value: Value;
43
+ description?: string;
44
+ }[];
45
+ }) => Promise<Value | undefined>;
46
+ prompt: (options: {
47
+ title: string;
48
+ placeholder?: string;
49
+ value?: string;
50
+ }) => Promise<string | undefined>;
51
+ clear: () => void;
52
+ };
53
+ toast: {
54
+ show: (options: {
55
+ title?: string;
56
+ message: string;
57
+ variant?: string;
58
+ }) => void;
59
+ };
60
+ } | undefined;
61
+ keymap?: {
62
+ layer: (input: () => {
63
+ mode?: string;
64
+ priority?: number;
65
+ commands: readonly {
66
+ id: string;
67
+ title?: string;
68
+ bind?: string;
69
+ run: (input?: string) => void;
70
+ }[];
71
+ bindings: readonly string[];
72
+ }) => void;
73
+ dispatch: (id: string, input?: string) => void;
74
+ } | undefined;
75
+ };
76
+ /**
77
+ * OpenCode V2 entrypoint — satisfies the V2 default-export schema
78
+ * (`{id, setup}`), which the server-role loader validates (OpenCode ≥ 2.x
79
+ * rejects `{id, tui}`-only modules with `err_*` "Plugin must export a default
80
+ * definition with an id and an effect or setup function").
81
+ *
82
+ * The server role calls this with a server context (no `ui`/`keymap`) → no-op.
83
+ * The TUI role calls it with the V2 TUI context → registers the sidebar slot,
84
+ * keybindings, and the settings dialog. Returns a cleanup that unclaims the slot.
85
+ */
86
+ declare function setup(context: V2TuiContext): Promise<(() => void) | undefined>;
6
87
  /**
7
88
  * The OpenCodeRAG TUI plugin module.
8
89
  * Registers sidebar panels, keybindings, and the settings dialog with OpenCode's
9
90
  * terminal UI framework.
10
91
  */
11
- declare const plugin: TuiPluginModule & {
92
+ declare const plugin: {
12
93
  id: string;
94
+ /** V2 entrypoint (schema `{id, setup}`); no-op under the server role, TUI registration under the TUI role. */
95
+ setup: typeof setup;
13
96
  };
14
97
  export default plugin;