opencode-rag-plugin 2.6.0 → 2.8.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.
@@ -11,6 +11,7 @@ import { embedBatch, probeEmbeddingDimension } from "../embedder/factory.js";
11
11
  import { createVectorStore } from "../vectorstore/factory.js";
12
12
  import { swapStoreDirectories } from "../vectorstore/lancedb.js";
13
13
  import { reconcileQuirks, QUIRK_FILE_PREFIX } from "../quirks/quirk-store.js";
14
+ import { rehydrateKeywordIndex } from "./keyword-rehydration.js";
14
15
  import { createIndexStats } from "./stats.js";
15
16
  import { prepareFile, buildTextsToEmbed } from "./worker.js";
16
17
  import { tagChunksRole } from "../core/chunk-role.js";
@@ -309,6 +310,32 @@ async function runIndexPassInner(options, logger) {
309
310
  }
310
311
  let filterPaths;
311
312
  let gitDeletedPaths = [];
313
+ // ── Keyword-index rehydration ──────────────────────────────────────────
314
+ // The keyword index (BM25 half of hybrid search) and the vector store are
315
+ // two independent stores of the same corpus, and nothing keeps them in sync
316
+ // by construction: an incremental pass only re-adds the files it reprocessed,
317
+ // so a once-partial index stays partial forever and the missing files are
318
+ // unreachable through keyword search. Rebuild the missing entries from the
319
+ // store's own rows — no re-embedding needed.
320
+ //
321
+ // Skipped during a rebuild: the rebuild re-indexes every file from source,
322
+ // so the keyword index is repopulated from scratch anyway.
323
+ if (options.keywordIndex && !rebuildPerformed) {
324
+ try {
325
+ await rehydrateKeywordIndex({
326
+ store: effectiveStore,
327
+ keywordIndex: options.keywordIndex,
328
+ logger: {
329
+ info: (message) => logger.info(message),
330
+ warn: (message) => logger.warn(message),
331
+ debug: (message) => logger.debug(message),
332
+ },
333
+ });
334
+ }
335
+ catch (err) {
336
+ logger.warn(`Keyword rehydration failed: ${err.message}`);
337
+ }
338
+ }
312
339
  if (!options.force && manifestStatus === "ok" && manifest.lastGitCommit) {
313
340
  const repoRoot = getRepoRoot(options.cwd);
314
341
  if (repoRoot) {
package/dist/plugin.js CHANGED
@@ -29,10 +29,10 @@ import { countTokens } from "./eval/token-counter.js";
29
29
  import { checkForUpdate, getCurrentVersion, installLatestUpdate } from "./core/version-check.js";
30
30
  import { loadAutoUpdateState, saveAutoUpdateState, shouldAttemptInstall } from "./core/auto-update-state.js";
31
31
  import { destroyAllPooledConnections } from "./embedder/http.js";
32
- import { listQuirks, lintQuirks, recallQuirks, sharedWords, reconcileQuirks, addQuirk } from "./quirks/quirk-store.js";
32
+ import { listQuirks, lintQuirks, recallQuirks, sharedWords, reconcileQuirks, addQuirk, listToolErrorQuirks } from "./quirks/quirk-store.js";
33
33
  import { autoCaptureQuirks } from "./quirks/auto-capture.js";
34
34
  import { createToolErrorInjectionState, recallToolErrorQuirks, formatToolErrorQuirkBlock, toToolErrorCaptureEntry, } from "./quirks/tool-error-recall.js";
35
- import { buildToolErrorQuirkContent, createToolErrorCreateState, createToolErrorQuirk, TOOL_ERROR_QUIRK_TAG, } from "./quirks/tool-error-create.js";
35
+ import { buildToolErrorQuirkContent, classifyToolErrorCause, createToolErrorCreateState, createToolErrorQuirk, formatToolGotchaBlock, hasEquivalentToolGotcha, selectToolGotchas, TOOL_ERROR_CREATE_DEFAULTS, TOOL_ERROR_QUIRK_TAG, } from "./quirks/tool-error-create.js";
36
36
  import { buildSystemGuidanceLines } from "./opencode/system-guidance.js";
37
37
  import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
38
38
  import path from "node:path";
@@ -42,6 +42,8 @@ const MAX_SESSION_MAP_SIZE = 50;
42
42
  const MAX_SESSION_TOOL_RESULTS = 20;
43
43
  /** Pending tool-error quirk blocks older than this (ms) are dropped instead of injected. */
44
44
  const TOOL_ERROR_PENDING_TTL_MS = 120_000;
45
+ /** How long the tool-error quirk list is cached before it is re-read (ms). */
46
+ const TOOL_GOTCHA_CACHE_MS = 30_000;
45
47
  /** Cache of loaded RAG configurations keyed by workspace directory. */
46
48
  const configCache = new Map();
47
49
  /** Active background indexer instances keyed by workspace directory. */
@@ -646,6 +648,9 @@ export function createRagHooks(options) {
646
648
  // plugin writes itself when a failure has no matching memory.
647
649
  const sessionToolErrorCreateState = new Map();
648
650
  const sessionPendingToolErrorQuirk = new Map();
651
+ // Tool-gotcha cache: the tool-error quirks change rarely, so the audit log is
652
+ // read at most every TOOL_GOTCHA_CACHE_MS instead of on every model request.
653
+ const toolGotchaCache = new Map();
649
654
  // Evaluation session logger — captures OpenCode events for analysis
650
655
  const sessionLogger = createSessionLogger(options.storePath);
651
656
  appendDebugLog(options.logFilePath, {
@@ -653,6 +658,23 @@ export function createRagHooks(options) {
653
658
  message: "OpenCode plugin initialized",
654
659
  });
655
660
  const readOverride = getEffectiveCfg().openCode.readOverride === true;
661
+ /**
662
+ * Read the auto-created tool-error quirks, cached briefly.
663
+ *
664
+ * Runs on every model request (the proactive tool-gotcha injection), so it
665
+ * must not hit the disk every time. The cache is invalidated explicitly
666
+ * when a new tool-error quirk is created.
667
+ */
668
+ async function getToolErrorQuirks(deps) {
669
+ const key = options.storePath;
670
+ const now = Date.now();
671
+ const cached = toolGotchaCache.get(key);
672
+ if (cached && now - cached.fetchedAt < TOOL_GOTCHA_CACHE_MS)
673
+ return cached.quirks;
674
+ const quirks = await listToolErrorQuirks(deps);
675
+ toolGotchaCache.set(key, { quirks, fetchedAt: now });
676
+ return quirks;
677
+ }
656
678
  const retrievalTool = tool({
657
679
  description: "Search the indexed codebase by meaning, not just keywords. " +
658
680
  "ESSENTIAL before any code task — replaces blind reading with targeted retrieval. " +
@@ -997,6 +1019,11 @@ export function createRagHooks(options) {
997
1019
  // `output.error` is set by the V2 adapter's error branch; the status
998
1020
  // check keeps this working if a runtime reports errors via input only.
999
1021
  const errorText = output.error ?? (input.status === "error" ? output.output : undefined);
1022
+ appendDebugLog(options.logFilePath, {
1023
+ scope: "quirk.tool-error",
1024
+ message: `tool "${input.tool}" status=${input.status ?? "unset"} error=${errorText ? "yes" : "no"}`,
1025
+ severity: "debug",
1026
+ }, getEffectiveCfg().logging.level);
1000
1027
  if (errorText && errorText.length > 0) {
1001
1028
  const info = { tool: input.tool, error: errorText, sessionID: input.sessionID };
1002
1029
  results.push(toToolErrorCaptureEntry(info));
@@ -1057,8 +1084,17 @@ export function createRagHooks(options) {
1057
1084
  state.record(info, hits.map((h) => h.id));
1058
1085
  // No candidate at all → nothing in memory covers this failure.
1059
1086
  // Record one so a future occurrence can be answered from memory.
1087
+ // The duplicate check is EXACT (same tool + same cause class), not
1088
+ // a loose similarity floor: a floor low enough to catch a genuine
1089
+ // duplicate also catches unrelated quirks, which would suppress
1090
+ // creation on every real failure.
1060
1091
  let createdHit;
1061
- if (recallResult.candidates.length === 0 && memCfg.autoCreateOnToolError) {
1092
+ let createdQuirk = false;
1093
+ const causeClass = classifyToolErrorCause(info.error)?.cls;
1094
+ const equivalent = recallResult.candidates.length > 0 ||
1095
+ (causeClass !== undefined &&
1096
+ hasEquivalentToolGotcha(await getToolErrorQuirks(qDeps), info.tool, causeClass));
1097
+ if (!equivalent && memCfg.autoCreateOnToolError) {
1062
1098
  const createState = sessionToolErrorCreateState.get(input.sessionID) ?? createToolErrorCreateState({
1063
1099
  maxPerSession: memCfg.toolErrorCreateMaxPerSession ?? 2,
1064
1100
  cooldownMs: memCfg.toolErrorCreateCooldownMs ?? 600_000,
@@ -1078,6 +1114,10 @@ export function createRagHooks(options) {
1078
1114
  clearTimeout(createTimer);
1079
1115
  if (created?.created && created.id) {
1080
1116
  createState.record(info, true);
1117
+ createdQuirk = true;
1118
+ // The proactive gotcha list changed — drop the cache so
1119
+ // the next model request sees the new gotcha.
1120
+ toolGotchaCache.delete(options.storePath);
1081
1121
  appendDebugLog(options.logFilePath, {
1082
1122
  scope: "quirk.tool-error",
1083
1123
  message: `created quirk ${created.id} for tool "${input.tool}"`,
@@ -1114,6 +1154,22 @@ export function createRagHooks(options) {
1114
1154
  ts: Date.now(),
1115
1155
  }, MAX_SESSION_MAP_SIZE);
1116
1156
  }
1157
+ appendDebugLog(options.logFilePath, {
1158
+ scope: "quirk.tool-error",
1159
+ message: `tool error "${input.tool}": candidates=${recallResult.candidates.length} injected=${finalHits.length} created=${createdQuirk ? "yes" : "no"}`,
1160
+ });
1161
+ }
1162
+ else if (recallResult) {
1163
+ appendDebugLog(options.logFilePath, {
1164
+ scope: "quirk.tool-error",
1165
+ message: `tool error "${input.tool}": skipped (cooldown or budget)`,
1166
+ });
1167
+ }
1168
+ else {
1169
+ appendDebugLog(options.logFilePath, {
1170
+ scope: "quirk.tool-error",
1171
+ message: `tool error "${input.tool}": skipped (recall timed out after ${budgetMs}ms)`,
1172
+ });
1117
1173
  }
1118
1174
  }
1119
1175
  }
@@ -1137,6 +1193,37 @@ export function createRagHooks(options) {
1137
1193
  ? "system guidance injected"
1138
1194
  : `system guidance skipped (${guidanceEnabled ? `no RAG tools in session; agent=${input?.agent ?? "unknown"}` : "injectSystemPrompt=false"})`,
1139
1195
  });
1196
+ // Which tools can this session actually call? The catalog is the set of
1197
+ // tools the model may invoke, so it is the right filter for tool-scoped
1198
+ // memory (a gotcha about a tool that is not callable is not actionable).
1199
+ appendDebugLog(options.logFilePath, {
1200
+ scope: "experimental.chat.system.transform",
1201
+ message: `tool catalog (${Object.keys(input?.tools ?? {}).length}): ${Object.keys(input?.tools ?? {}).join(", ")}`,
1202
+ severity: "debug",
1203
+ }, getEffectiveCfg().logging.level);
1204
+ // Proactive tool gotchas: surface what earlier failures taught us BEFORE
1205
+ // the model picks a tool, so a known failure is not repeated in a later
1206
+ // session. Scoped to the tools this session can actually call.
1207
+ try {
1208
+ const toolNames = Object.keys(input?.tools ?? {});
1209
+ if (toolNames.length > 0) {
1210
+ const memCfg = getEffectiveCfg().memory;
1211
+ if (memCfg?.enabled && memCfg.toolErrorProactiveInject) {
1212
+ const qDeps = { embedder, store, keywordIndex: keywordIndex, cfg: getEffectiveCfg(), storePath: options.storePath };
1213
+ const gotchas = selectToolGotchas(await getToolErrorQuirks(qDeps), toolNames, memCfg.toolErrorProactiveMaxItems ?? TOOL_ERROR_CREATE_DEFAULTS.maxProactiveItems);
1214
+ if (gotchas.length > 0) {
1215
+ output.system.unshift(formatToolGotchaBlock(gotchas));
1216
+ appendDebugLog(options.logFilePath, {
1217
+ scope: "quirk.tool-error",
1218
+ message: `proactively injected ${gotchas.length} tool gotcha(s): ${gotchas.map((g) => g.tool).join(", ")}`,
1219
+ });
1220
+ }
1221
+ }
1222
+ }
1223
+ }
1224
+ catch {
1225
+ // Non-critical — must never throw
1226
+ }
1140
1227
  if (injectGuidance) {
1141
1228
  const guidance = buildSystemGuidanceLines({ promptEnforcement: !!cfg.memory?.promptEnforcement, decisionEnabled: !!cfg.decision?.enabled, routeBeforeAsking: !!cfg.decision?.routeBeforeAsking });
1142
1229
  output.system.unshift(guidance.join("\n"));
@@ -1,6 +1,6 @@
1
1
  import type { EmbeddingProvider, VectorStore, KeywordIndex, SearchResult } from "../core/interfaces.js";
2
2
  import type { RagConfig } from "../core/config.js";
3
- import type { Quirk, QuirkInput } from "./types.js";
3
+ import { type Quirk, type QuirkInput } from "./types.js";
4
4
  /** Dependencies required by all quirk-store operations. */
5
5
  export interface QuirkStoreDeps {
6
6
  embedder: EmbeddingProvider;
@@ -104,6 +104,19 @@ export declare function recallQuirks(deps: QuirkStoreDeps, query: string, option
104
104
  * similarity threshold. */
105
105
  explain?: boolean;
106
106
  }): Promise<SearchResult[]>;
107
+ /**
108
+ * List the auto-created tool-error quirks, newest first.
109
+ *
110
+ * Reads the audit log directly instead of going through `listQuirks`: that
111
+ * function falls back to scanning the whole vector store when
112
+ * `quirks.jsonl` is missing, which is far too expensive for a path that runs
113
+ * on every model request. A tool-error quirk is always appended to the audit
114
+ * log, so an absent log means there are none.
115
+ *
116
+ * @param deps - The quirk store dependencies.
117
+ * @returns The tool-error quirks, newest `lastObserved` first.
118
+ */
119
+ export declare function listToolErrorQuirks(deps: QuirkStoreDeps): Promise<Quirk[]>;
107
120
  /** Lint quirks for low confidence, staleness, duplicates, and orphan source refs. */
108
121
  export declare function lintQuirks(deps: QuirkStoreDeps): Promise<string[]>;
109
122
  /** Simple Jaccard-based lexical similarity (word overlap). */
@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
3
3
  import path from "node:path";
4
4
  import { retrieve } from "../retriever/retriever.js";
5
5
  import { isQuirkAllowed } from "./monitor.js";
6
+ import { TOOL_ERROR_QUIRK_TAG } from "./types.js";
6
7
  export const QUIRK_FILE_PREFIX = "quirk:";
7
8
  const QUIKK_JSONL = "quirks.jsonl";
8
9
  function jsonlPath(storePath) {
@@ -562,6 +563,32 @@ export async function recallQuirks(deps, query, options) {
562
563
  filtered.sort((a, b) => b.score - a.score);
563
564
  return filtered.slice(0, topK);
564
565
  }
566
+ /**
567
+ * List the auto-created tool-error quirks, newest first.
568
+ *
569
+ * Reads the audit log directly instead of going through `listQuirks`: that
570
+ * function falls back to scanning the whole vector store when
571
+ * `quirks.jsonl` is missing, which is far too expensive for a path that runs
572
+ * on every model request. A tool-error quirk is always appended to the audit
573
+ * log, so an absent log means there are none.
574
+ *
575
+ * @param deps - The quirk store dependencies.
576
+ * @returns The tool-error quirks, newest `lastObserved` first.
577
+ */
578
+ export async function listToolErrorQuirks(deps) {
579
+ const tagged = (q) => (q.tags ?? []).includes(TOOL_ERROR_QUIRK_TAG);
580
+ if (isMemoryStore(deps.storePath)) {
581
+ return [...memQuirksFor(deps.storePath).values()]
582
+ .filter(tagged)
583
+ .sort((a, b) => b.lastObserved.localeCompare(a.lastObserved));
584
+ }
585
+ const jp = jsonlPath(deps.storePath);
586
+ if (!existsSync(jp))
587
+ return [];
588
+ return readJsonl(jp)
589
+ .filter(tagged)
590
+ .sort((a, b) => b.lastObserved.localeCompare(a.lastObserved));
591
+ }
565
592
  /** Lint quirks for low confidence, staleness, duplicates, and orphan source refs. */
566
593
  export async function lintQuirks(deps) {
567
594
  const issues = [];
@@ -21,19 +21,21 @@
21
21
  * caller logs it.
22
22
  */
23
23
  import type { Quirk, QuirkInput } from "./types.js";
24
+ import { TOOL_ERROR_AUTO_TAG, TOOL_ERROR_CAUSE_TAG_PREFIX, TOOL_ERROR_QUIRK_TAG, TOOL_ERROR_TOOL_TAG_PREFIX } from "./types.js";
24
25
  import { type ToolErrorInfo } from "./tool-error-recall.js";
25
- /** Tag every auto-created tool-error quirk carries. */
26
- export declare const TOOL_ERROR_QUIRK_TAG = "tool-error";
27
- /** Second tag marking the quirk as machine-created (not agent-authored). */
28
- export declare const TOOL_ERROR_AUTO_TAG = "auto-created";
26
+ export { TOOL_ERROR_AUTO_TAG, TOOL_ERROR_CAUSE_TAG_PREFIX, TOOL_ERROR_QUIRK_TAG, TOOL_ERROR_TOOL_TAG_PREFIX, };
29
27
  /** Defaults for the tool-error creation path. */
30
28
  export declare const TOOL_ERROR_CREATE_DEFAULTS: {
31
29
  /**
32
30
  * Minimum raw similarity for a candidate to count as "an equivalent quirk
33
- * already exists" (and therefore suppress creation). Default 0.6 — below
34
- * the 0.7 injection bar, so a probable match still blocks a duplicate.
31
+ * already exists" (and therefore suppress creation). Default 0.7 — the
32
+ * injection bar. Measured: an error query scores 0.55-0.63 against
33
+ * ARBITRARY stored quirks, so a lower floor sits inside the noise band and
34
+ * matches unrelated quirks, which suppresses creation on every real failure.
35
+ * The exact duplicate check is done by metadata instead — see
36
+ * `hasEquivalentToolGotcha`.
35
37
  */
36
- readonly minScore: 0.6;
38
+ readonly minScore: 0.7;
37
39
  /** Maximum quirks created per session. Default 2. */
38
40
  readonly maxPerSession: 2;
39
41
  /** Cooldown per normalized error signature in ms. Default 10 minutes. */
@@ -46,7 +48,33 @@ export declare const TOOL_ERROR_CREATE_DEFAULTS: {
46
48
  readonly confidence: 0.6;
47
49
  /** Errors shorter than this carry no information — nothing is recorded. */
48
50
  readonly minErrorChars: 15;
51
+ /** Max tool gotchas injected proactively into the system prompt. Default 5. */
52
+ readonly maxProactiveItems: 5;
49
53
  };
54
+ /**
55
+ * Cause classes that are worth surfacing BEFORE the tool is called.
56
+ *
57
+ * A transient failure (rate limit, timeout) must NOT be warned about in
58
+ * advance — the next call will not fail the same way, and the warning would
59
+ * be misleading. An unclassified error is excluded for the same reason: we do
60
+ * not know whether it is durable, and a raw error dump says what happened,
61
+ * not what to do.
62
+ */
63
+ export declare const PROACTIVE_CAUSE_CLASSES: ReadonlySet<string>;
64
+ /** A classified tool-error cause. */
65
+ export interface ToolErrorCause {
66
+ /** Stable class name — also used as the `cause:<class>` tag. */
67
+ cls: string;
68
+ /** Human-readable guidance appended to the quirk content. */
69
+ cause: string;
70
+ }
71
+ /**
72
+ * Classify an error message into a cause class plus its guidance.
73
+ *
74
+ * Returns `undefined` for unknown errors — the raw text is then the whole
75
+ * story.
76
+ */
77
+ export declare function classifyToolErrorCause(error: string): ToolErrorCause | undefined;
50
78
  /**
51
79
  * Classify an error message into a short, deterministic cause.
52
80
  *
@@ -109,3 +137,47 @@ export interface ToolErrorQuirkCreateResult {
109
137
  * `created: false` with a reason so the caller can log it and carry on.
110
138
  */
111
139
  export declare function createToolErrorQuirk(deps: ToolErrorQuirkDeps, info: ToolErrorInfo, content?: string): Promise<ToolErrorQuirkCreateResult>;
140
+ /** A stored tool gotcha, ready to be surfaced proactively. */
141
+ export interface ToolGotcha {
142
+ /** The tool the gotcha is about (lowercase). */
143
+ tool: string;
144
+ /** The quirk content — the lesson learned from the failure. */
145
+ content: string;
146
+ /** The quirk id, for `update_quirk` / `delete_quirk`. */
147
+ quirkId: string;
148
+ }
149
+ /**
150
+ * Pick the tool gotchas that are actionable for the tools a session can call.
151
+ *
152
+ * A gotcha about a tool the model cannot invoke is noise, so the tool name
153
+ * is matched against the session's tool catalog. This is a metadata scan, not
154
+ * a semantic recall: the question is "does a quirk exist for THIS tool", not
155
+ * "which quirk is most similar to the current request".
156
+ *
157
+ * @param quirks - Tool-error quirks, newest first.
158
+ * @param toolNames - The tool names the session may call.
159
+ * @param maxItems - Maximum number of gotchas to return.
160
+ */
161
+ export declare function selectToolGotchas(quirks: readonly Pick<Quirk, "id" | "content" | "tags">[], toolNames: readonly string[], maxItems?: number): ToolGotcha[];
162
+ /**
163
+ * Is there already a tool-error quirk for this tool AND cause class?
164
+ *
165
+ * The exact duplicate check. A semantic similarity floor cannot do this job:
166
+ * an error query scores 0.55-0.63 against arbitrary stored quirks, so any
167
+ * floor low enough to catch a genuine duplicate also catches noise — which
168
+ * silently suppressed creation on every real failure. The tags make the
169
+ * check exact: a quirk created for `write` + `schema` is the same lesson as
170
+ * the next `write` + `schema` failure, whatever the error text says.
171
+ *
172
+ * @param quirks - The stored tool-error quirks.
173
+ * @param tool - The failing tool name.
174
+ * @param causeClass - The classified cause class (e.g. "schema").
175
+ */
176
+ export declare function hasEquivalentToolGotcha(quirks: readonly Pick<Quirk, "tags">[], tool: string, causeClass: string): boolean;
177
+ /**
178
+ * Format the proactive tool-gotcha block for the system prompt.
179
+ *
180
+ * Injected BEFORE the model chooses a tool, so a known failure is not
181
+ * repeated in a later session. Empty when there are no gotchas.
182
+ */
183
+ export declare function formatToolGotchaBlock(gotchas: readonly ToolGotcha[]): string;
@@ -20,19 +20,21 @@
20
20
  * that contains `rm -rf`) is reported as "not created" with a reason; the
21
21
  * caller logs it.
22
22
  */
23
+ import { TOOL_ERROR_AUTO_TAG, TOOL_ERROR_CAUSE_TAG_PREFIX, TOOL_ERROR_QUIRK_TAG, TOOL_ERROR_TOOL_TAG_PREFIX, } from "./types.js";
23
24
  import { normalizeToolErrorSignature } from "./tool-error-recall.js";
24
- /** Tag every auto-created tool-error quirk carries. */
25
- export const TOOL_ERROR_QUIRK_TAG = "tool-error";
26
- /** Second tag marking the quirk as machine-created (not agent-authored). */
27
- export const TOOL_ERROR_AUTO_TAG = "auto-created";
25
+ export { TOOL_ERROR_AUTO_TAG, TOOL_ERROR_CAUSE_TAG_PREFIX, TOOL_ERROR_QUIRK_TAG, TOOL_ERROR_TOOL_TAG_PREFIX, };
28
26
  /** Defaults for the tool-error creation path. */
29
27
  export const TOOL_ERROR_CREATE_DEFAULTS = {
30
28
  /**
31
29
  * Minimum raw similarity for a candidate to count as "an equivalent quirk
32
- * already exists" (and therefore suppress creation). Default 0.6 — below
33
- * the 0.7 injection bar, so a probable match still blocks a duplicate.
30
+ * already exists" (and therefore suppress creation). Default 0.7 — the
31
+ * injection bar. Measured: an error query scores 0.55-0.63 against
32
+ * ARBITRARY stored quirks, so a lower floor sits inside the noise band and
33
+ * matches unrelated quirks, which suppresses creation on every real failure.
34
+ * The exact duplicate check is done by metadata instead — see
35
+ * `hasEquivalentToolGotcha`.
34
36
  */
35
- minScore: 0.6,
37
+ minScore: 0.7,
36
38
  /** Maximum quirks created per session. Default 2. */
37
39
  maxPerSession: 2,
38
40
  /** Cooldown per normalized error signature in ms. Default 10 minutes. */
@@ -45,47 +47,79 @@ export const TOOL_ERROR_CREATE_DEFAULTS = {
45
47
  confidence: 0.6,
46
48
  /** Errors shorter than this carry no information — nothing is recorded. */
47
49
  minErrorChars: 15,
50
+ /** Max tool gotchas injected proactively into the system prompt. Default 5. */
51
+ maxProactiveItems: 5,
48
52
  };
49
53
  /** Known error classes with a deterministic, actionable cause. */
50
54
  const ERROR_CAUSES = [
51
55
  {
56
+ cls: "unknown-tool",
52
57
  pattern: /unknown tool|no such tool|tool .*not found|not a registered tool/i,
53
58
  cause: "the tool name may be wrong, or the tool is not available in this session",
54
59
  },
55
60
  {
56
- pattern: /enoent|no such file or directory|cannot find module/i,
57
- cause: "the path or module name may be wrong",
61
+ cls: "schema",
62
+ pattern: /expected .*(received|but got)|invalid argument|invalid type|schema|must be (a|an|string|number|boolean|object|array)/i,
63
+ cause: "the arguments do not match the tool's schema",
58
64
  },
59
65
  {
66
+ cls: "permissions",
60
67
  pattern: /eacces|permission denied/i,
61
68
  cause: "the path may need different permissions",
62
69
  },
63
70
  {
64
- pattern: /expected .*(received|but got)|invalid argument|invalid type|schema|must be (a|an|string|number|boolean|object|array)/i,
65
- cause: "the arguments do not match the tool's schema",
71
+ cls: "path",
72
+ pattern: /enoent|no such file or directory|cannot find module/i,
73
+ cause: "the path or module name may be wrong",
66
74
  },
67
75
  {
76
+ cls: "rate-limit",
68
77
  pattern: /\b429\b|rate limit|too many requests/i,
69
78
  cause: "the request was rate limited — retry later",
70
79
  },
71
80
  {
81
+ cls: "timeout",
72
82
  pattern: /timed? ?out|timeout|etimedout/i,
73
83
  cause: "the operation timed out",
74
84
  },
75
85
  ];
76
86
  /**
77
- * Classify an error message into a short, deterministic cause.
87
+ * Cause classes that are worth surfacing BEFORE the tool is called.
88
+ *
89
+ * A transient failure (rate limit, timeout) must NOT be warned about in
90
+ * advance — the next call will not fail the same way, and the warning would
91
+ * be misleading. An unclassified error is excluded for the same reason: we do
92
+ * not know whether it is durable, and a raw error dump says what happened,
93
+ * not what to do.
94
+ */
95
+ export const PROACTIVE_CAUSE_CLASSES = new Set([
96
+ "unknown-tool",
97
+ "schema",
98
+ "permissions",
99
+ "path",
100
+ ]);
101
+ /**
102
+ * Classify an error message into a cause class plus its guidance.
78
103
  *
79
104
  * Returns `undefined` for unknown errors — the raw text is then the whole
80
105
  * story.
81
106
  */
82
- export function classifyToolError(error) {
83
- for (const { pattern, cause } of ERROR_CAUSES) {
107
+ export function classifyToolErrorCause(error) {
108
+ for (const { cls, pattern, cause } of ERROR_CAUSES) {
84
109
  if (pattern.test(error))
85
- return cause;
110
+ return { cls, cause };
86
111
  }
87
112
  return undefined;
88
113
  }
114
+ /**
115
+ * Classify an error message into a short, deterministic cause.
116
+ *
117
+ * Returns `undefined` for unknown errors — the raw text is then the whole
118
+ * story.
119
+ */
120
+ export function classifyToolError(error) {
121
+ return classifyToolErrorCause(error)?.cause;
122
+ }
89
123
  /**
90
124
  * Build the quirk content for a failed tool call.
91
125
  *
@@ -156,11 +190,17 @@ export async function createToolErrorQuirk(deps, info, content) {
156
190
  if (!text) {
157
191
  return { created: false, reason: "empty quirk content" };
158
192
  }
193
+ // The cause class is what makes a gotcha usable PROACTIVELY: a transient
194
+ // failure must not be warned about before the next call.
195
+ const cause = classifyToolErrorCause(info.error);
196
+ const tags = [TOOL_ERROR_QUIRK_TAG, TOOL_ERROR_AUTO_TAG, `tool:${info.tool}`];
197
+ if (cause)
198
+ tags.push(`${TOOL_ERROR_CAUSE_TAG_PREFIX}${cause.cls}`);
159
199
  try {
160
200
  const quirk = await deps.add({
161
201
  content: text,
162
202
  quirkType: "gotcha",
163
- tags: [TOOL_ERROR_QUIRK_TAG, TOOL_ERROR_AUTO_TAG, `tool:${info.tool}`],
203
+ tags,
164
204
  confidence: TOOL_ERROR_CREATE_DEFAULTS.confidence,
165
205
  sourceRef: `tool-error:${info.tool}`,
166
206
  });
@@ -170,4 +210,83 @@ export async function createToolErrorQuirk(deps, info, content) {
170
210
  return { created: false, reason: err instanceof Error ? err.message : String(err) };
171
211
  }
172
212
  }
213
+ /**
214
+ * Pick the tool gotchas that are actionable for the tools a session can call.
215
+ *
216
+ * A gotcha about a tool the model cannot invoke is noise, so the tool name
217
+ * is matched against the session's tool catalog. This is a metadata scan, not
218
+ * a semantic recall: the question is "does a quirk exist for THIS tool", not
219
+ * "which quirk is most similar to the current request".
220
+ *
221
+ * @param quirks - Tool-error quirks, newest first.
222
+ * @param toolNames - The tool names the session may call.
223
+ * @param maxItems - Maximum number of gotchas to return.
224
+ */
225
+ export function selectToolGotchas(quirks, toolNames, maxItems = TOOL_ERROR_CREATE_DEFAULTS.maxProactiveItems) {
226
+ if (toolNames.length === 0 || maxItems <= 0)
227
+ return [];
228
+ const callable = new Set(toolNames.map((t) => t.toLowerCase()));
229
+ const gotchas = [];
230
+ for (const q of quirks) {
231
+ const tags = q.tags ?? [];
232
+ if (!tags.includes(TOOL_ERROR_QUIRK_TAG))
233
+ continue;
234
+ const toolTag = tags.find((t) => t.startsWith(TOOL_ERROR_TOOL_TAG_PREFIX));
235
+ if (!toolTag)
236
+ continue;
237
+ const tool = toolTag.slice(TOOL_ERROR_TOOL_TAG_PREFIX.length).toLowerCase();
238
+ if (!callable.has(tool))
239
+ continue;
240
+ // Only durable, actionable causes are worth warning about in advance.
241
+ const causeTag = tags.find((t) => t.startsWith(TOOL_ERROR_CAUSE_TAG_PREFIX));
242
+ if (!causeTag)
243
+ continue;
244
+ const cls = causeTag.slice(TOOL_ERROR_CAUSE_TAG_PREFIX.length);
245
+ if (!PROACTIVE_CAUSE_CLASSES.has(cls))
246
+ continue;
247
+ gotchas.push({ tool, content: q.content, quirkId: q.id });
248
+ if (gotchas.length >= maxItems)
249
+ break;
250
+ }
251
+ return gotchas;
252
+ }
253
+ /**
254
+ * Is there already a tool-error quirk for this tool AND cause class?
255
+ *
256
+ * The exact duplicate check. A semantic similarity floor cannot do this job:
257
+ * an error query scores 0.55-0.63 against arbitrary stored quirks, so any
258
+ * floor low enough to catch a genuine duplicate also catches noise — which
259
+ * silently suppressed creation on every real failure. The tags make the
260
+ * check exact: a quirk created for `write` + `schema` is the same lesson as
261
+ * the next `write` + `schema` failure, whatever the error text says.
262
+ *
263
+ * @param quirks - The stored tool-error quirks.
264
+ * @param tool - The failing tool name.
265
+ * @param causeClass - The classified cause class (e.g. "schema").
266
+ */
267
+ export function hasEquivalentToolGotcha(quirks, tool, causeClass) {
268
+ const toolTag = `${TOOL_ERROR_TOOL_TAG_PREFIX}${tool.toLowerCase()}`;
269
+ const causeTag = `${TOOL_ERROR_CAUSE_TAG_PREFIX}${causeClass}`;
270
+ return quirks.some((q) => (q.tags ?? []).includes(toolTag) && (q.tags ?? []).includes(causeTag));
271
+ }
272
+ /**
273
+ * Format the proactive tool-gotcha block for the system prompt.
274
+ *
275
+ * Injected BEFORE the model chooses a tool, so a known failure is not
276
+ * repeated in a later session. Empty when there are no gotchas.
277
+ */
278
+ export function formatToolGotchaBlock(gotchas) {
279
+ if (gotchas.length === 0)
280
+ return "";
281
+ const lines = [
282
+ "",
283
+ "---",
284
+ "⚠ **Known tool gotchas** — these tools failed before. Check before calling them:",
285
+ "",
286
+ ];
287
+ for (const g of gotchas) {
288
+ lines.push(`- ${g.content}`);
289
+ }
290
+ return lines.join("\n");
291
+ }
173
292
  //# sourceMappingURL=tool-error-create.js.map
@@ -1,5 +1,13 @@
1
1
  /** Quirk sub-type labels. */
2
2
  export type QuirkType = "gotcha" | "preference" | "decision" | "environment-constraint";
3
+ /** Tag every auto-created tool-error quirk carries. */
4
+ export declare const TOOL_ERROR_QUIRK_TAG = "tool-error";
5
+ /** Second tag marking the quirk as machine-created (not agent-authored). */
6
+ export declare const TOOL_ERROR_AUTO_TAG = "auto-created";
7
+ /** Prefix of the per-tool tag: `tool:<name>`. */
8
+ export declare const TOOL_ERROR_TOOL_TAG_PREFIX = "tool:";
9
+ /** Prefix of the cause-class tag: `cause:<class>`. */
10
+ export declare const TOOL_ERROR_CAUSE_TAG_PREFIX = "cause:";
3
11
  /** Input for adding a new quirk. */
4
12
  export interface QuirkInput {
5
13
  content: string;
@@ -1,2 +1,9 @@
1
- export {};
1
+ /** Tag every auto-created tool-error quirk carries. */
2
+ export const TOOL_ERROR_QUIRK_TAG = "tool-error";
3
+ /** Second tag marking the quirk as machine-created (not agent-authored). */
4
+ export const TOOL_ERROR_AUTO_TAG = "auto-created";
5
+ /** Prefix of the per-tool tag: `tool:<name>`. */
6
+ export const TOOL_ERROR_TOOL_TAG_PREFIX = "tool:";
7
+ /** Prefix of the cause-class tag: `cause:<class>`. */
8
+ export const TOOL_ERROR_CAUSE_TAG_PREFIX = "cause:";
2
9
  //# sourceMappingURL=types.js.map
@@ -45,6 +45,16 @@ export declare class KeywordIndex {
45
45
  clear(): void;
46
46
  count(): number;
47
47
  hasChunk(id: string): boolean;
48
+ /**
49
+ * Normalized file paths that currently have at least one indexed chunk.
50
+ *
51
+ * The keyword index and the vector store are two independent stores of the
52
+ * same corpus, and nothing keeps them in sync by construction: an
53
+ * incremental index pass only calls {@link addChunks} for the files it
54
+ * reprocessed, so a once-partial index stays partial forever. Comparing
55
+ * this list with the store's file list is how that drift is detected.
56
+ */
57
+ getIndexedFilePaths(): string[];
48
58
  save(storePath?: string): Promise<void>;
49
59
  static load(storePath: string): Promise<KeywordIndex>;
50
60
  static clearFile(storePath: string): Promise<void>;