opencode-rag-plugin 2.5.3 → 2.6.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.
package/ReadMe.md CHANGED
@@ -59,7 +59,7 @@ workspace, and `opencode-rag update` upgrades to a newer release.
59
59
  | **Documentation mode** | `/doc` slash command: agent adds JSDoc/TSDoc to undocumented files, progress tracked per subdirectory |
60
60
  | **Wiki mode** | `/wiki` slash command: agent maintains a persistent knowledge wiki at `.opencode/wiki/` (ingest, query, lint, seed) |
61
61
  | **Context optimization** | Post-retrieval dedup, per-file chunk limits, adjacent-merge to fit the context window |
62
- | **Quirk memory** | Persistent experiential memory — agents recall/persist gotchas, preferences, decisions across sessions (`add_quirk` / `recall_quirks`, `opencode-rag quirk`) |
62
+ | **Quirk memory** | Persistent experiential memory — agents recall/persist gotchas, preferences, decisions across sessions (`add_quirk` / `recall_quirks`, `opencode-rag quirk`); failed tool calls are auto-recorded as quirks |
63
63
  | **AGENTS.md directive** | `opencode-rag init` merges a tool-usage directive into `AGENTS.md` via sentinel markers |
64
64
 
65
65
  ## Web UI
@@ -210,6 +210,9 @@ OpenCodeRAG gives your agent **persistent, cross-session memory** of non-obvious
210
210
  "autoInjectMinScore": 0.75,
211
211
  "autoInjectTopK": 1,
212
212
  "autoInjectLatencyBudgetMs": 2000,
213
+ "injectOnToolError": true,
214
+ "autoCreateOnToolError": true,
215
+ "toolErrorCreateMaxPerSession": 2,
213
216
  "decay": { "enabled": false, "halfLifeDays": 30 }
214
217
  }
215
218
  }
@@ -240,6 +243,8 @@ opencode-rag quirk test "npm needs --legacy-peer-deps"
240
243
 
241
244
  When `memory.autoInject` is `true`, the plugin checks for relevant quirks on every user message using the combined agent-response + user-query as the search query. Quirks are only injected when their raw vector similarity to that query clears `autoInjectMinScore` (default 0.75) - the same threshold for the user-message and system-prompt injections; `recallMinScore` (default 0.72) is the bar for manual `recall_quirks` calls. A latency budget (`autoInjectLatencyBudgetMs`, default 2000ms) prevents slow embedders from blocking message processing. To avoid polluting the context window, each quirk is injected **at most once per session** — once recalled, it is filtered out from all subsequent auto-injections. Every `add_quirk` and every content-changing `update_quirk` is vetted by an immutable trust monitor that rejects destructive patterns (e.g. `rm -rf`, `force push`, `bypass security`). Outdated or fixed quirks should be corrected with `update_quirk` / `delete_quirk` rather than left to contradict newer memory. See [Plugin documentation](doc/plugin.md#9-quirk-memory-experiential-memory) and [CLI Reference: `quirk`](doc/cli.md#quirk).
242
245
 
246
+ **Failed tool calls become memory.** When a tool call fails, the plugin looks for a stored quirk that covers the failure and injects it into the next request (`memory.injectOnToolError`, default on). If **no** quirk covers it, it writes one — `memory.autoCreateOnToolError` (default on) — using a deterministic template built from the tool name and the error text, so no LLM is involved. The new quirk is tagged `tool-error` and recorded for *future* sessions; it is deliberately excluded from the generic auto-injection above, so a raw error dump never leaks into an unrelated turn. Creation is bounded by a per-session budget (2) and a per-error cooldown (10 min), and the quirk it would write is suppressed as soon as a similar one already exists.
247
+
243
248
  ## MCP Server (Optional)
244
249
 
245
250
  OpenCodeRAG ships a CLI-based [MCP (Model Context Protocol)](https://spec.modelcontextprotocol.io/) server that exposes semantic code tools to any MCP-compatible client (Claude Desktop, Cursor, etc.).
@@ -279,6 +279,33 @@ export interface MemoryConfig {
279
279
  toolErrorMaxPerSession: number;
280
280
  /** Latency budget (ms) for tool-error quirk recall; exceeded -> no injection (default 1500). */
281
281
  toolErrorLatencyBudgetMs: number;
282
+ /**
283
+ * Automatically create and persist a quirk when a failed tool call has no
284
+ * matching quirk memory (default true). The new quirk is a deterministic
285
+ * template built from the tool name and the error text — no LLM involved.
286
+ * It is recorded for FUTURE sessions; it is not injected into the turn that
287
+ * produced the failure (see `toolErrorInjectCreated`).
288
+ */
289
+ autoCreateOnToolError: boolean;
290
+ /** Max tool-error quirks CREATED per session (default 2). */
291
+ toolErrorCreateMaxPerSession: number;
292
+ /** Cooldown per normalized tool-error signature for creation in ms (default 600000 = 10 min). */
293
+ toolErrorCreateCooldownMs: number;
294
+ /**
295
+ * Minimum raw similarity (0-1) for an existing quirk to count as "an
296
+ * equivalent quirk already exists" and therefore suppress creation
297
+ * (default 0.6). Deliberately below `toolErrorMinScore` (0.7): a probable
298
+ * match still blocks a duplicate, it is just not injected on its own.
299
+ */
300
+ toolErrorCreateMinScore: number;
301
+ /** Latency budget (ms) for the tool-error creation path (embed + store write); default 2000. */
302
+ toolErrorCreateLatencyBudgetMs: number;
303
+ /**
304
+ * Inject a freshly created tool-error quirk into the turn that produced the
305
+ * failure (default false). The agent already saw the raw error, so the
306
+ * created quirk carries no new information for that turn.
307
+ */
308
+ toolErrorInjectCreated: boolean;
282
309
  /** Decay settings for aging quirks. */
283
310
  decay: {
284
311
  /** Whether confidence decays over time. */
@@ -322,6 +322,12 @@ export const DEFAULT_CONFIG = {
322
322
  toolErrorCooldownMs: 60_000,
323
323
  toolErrorMaxPerSession: 3,
324
324
  toolErrorLatencyBudgetMs: 1500,
325
+ autoCreateOnToolError: true,
326
+ toolErrorCreateMaxPerSession: 2,
327
+ toolErrorCreateCooldownMs: 600_000,
328
+ toolErrorCreateMinScore: 0.6,
329
+ toolErrorCreateLatencyBudgetMs: 2000,
330
+ toolErrorInjectCreated: false,
325
331
  decay: {
326
332
  enabled: false,
327
333
  halfLifeDays: 30,
@@ -467,6 +473,20 @@ export function validateConfig(config) {
467
473
  if (config.memory?.toolErrorLatencyBudgetMs != null && config.memory.toolErrorLatencyBudgetMs < 0) {
468
474
  warnings.push("memory.toolErrorLatencyBudgetMs must be >= 0");
469
475
  }
476
+ if (config.memory?.toolErrorCreateMinScore != null) {
477
+ const r = config.memory.toolErrorCreateMinScore;
478
+ if (r < 0 || r > 1)
479
+ warnings.push("memory.toolErrorCreateMinScore must be between 0 and 1");
480
+ }
481
+ if (config.memory?.toolErrorCreateMaxPerSession != null && config.memory.toolErrorCreateMaxPerSession < 0) {
482
+ warnings.push("memory.toolErrorCreateMaxPerSession must be >= 0");
483
+ }
484
+ if (config.memory?.toolErrorCreateCooldownMs != null && config.memory.toolErrorCreateCooldownMs < 0) {
485
+ warnings.push("memory.toolErrorCreateCooldownMs must be >= 0");
486
+ }
487
+ if (config.memory?.toolErrorCreateLatencyBudgetMs != null && config.memory.toolErrorCreateLatencyBudgetMs < 0) {
488
+ warnings.push("memory.toolErrorCreateLatencyBudgetMs must be >= 0");
489
+ }
470
490
  if (config.memory?.decay && config.memory.decay.halfLifeDays <= 0) {
471
491
  warnings.push("memory.decay.halfLifeDays must be > 0");
472
492
  }
package/dist/plugin.js CHANGED
@@ -29,9 +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 } from "./quirks/quirk-store.js";
32
+ import { listQuirks, lintQuirks, recallQuirks, sharedWords, reconcileQuirks, addQuirk } from "./quirks/quirk-store.js";
33
33
  import { autoCaptureQuirks } from "./quirks/auto-capture.js";
34
- import { createToolErrorInjectionState, selectToolErrorQuirks, formatToolErrorQuirkBlock, toToolErrorCaptureEntry, } from "./quirks/tool-error-recall.js";
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
36
  import { buildSystemGuidanceLines } from "./opencode/system-guidance.js";
36
37
  import { existsSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
37
38
  import path from "node:path";
@@ -641,6 +642,9 @@ export function createRagHooks(options) {
641
642
  // Tool-error quirk path: per-session injection state (cooldown/budget) and the
642
643
  // block pending for the next model request.
643
644
  const sessionToolErrorState = new Map();
645
+ // Tool-error quirk creation: per-session budget/cooldown for the quirks the
646
+ // plugin writes itself when a failure has no matching memory.
647
+ const sessionToolErrorCreateState = new Map();
644
648
  const sessionPendingToolErrorQuirk = new Map();
645
649
  // Evaluation session logger — captures OpenCode events for analysis
646
650
  const sessionLogger = createSessionLogger(options.storePath);
@@ -1004,22 +1008,113 @@ export function createRagHooks(options) {
1004
1008
  });
1005
1009
  boundedSet(sessionToolErrorState, input.sessionID, state, MAX_SESSION_MAP_SIZE);
1006
1010
  const qDeps = { embedder, store, keywordIndex: keywordIndex, cfg: getEffectiveCfg(), storePath: options.storePath };
1007
- const recall = (query, recallOpts) => recallQuirks(qDeps, query, recallOpts);
1011
+ // `explain: true` keeps the raw vector similarity on each result —
1012
+ // the confidence-discounted `score` is not comparable to a
1013
+ // similarity threshold, and the tiering below needs the raw value.
1014
+ const recall = (query, recallOpts) => recallQuirks(qDeps, query, { ...recallOpts, explain: true }).then((rs) => rs.map((r) => ({
1015
+ chunk: {
1016
+ id: r.chunk.id,
1017
+ content: r.chunk.content,
1018
+ metadata: { quirkType: r.chunk.metadata.quirkType, tags: r.chunk.metadata.tags },
1019
+ },
1020
+ score: r.score,
1021
+ rawSimilarity: r.explanation?.scoreBreakdown?.rawVectorScore,
1022
+ })));
1008
1023
  const budgetMs = memCfg.toolErrorLatencyBudgetMs ?? 1500;
1009
- await Promise.race([
1010
- selectToolErrorQuirks(recall, info, state, {
1011
- minScore: memCfg.toolErrorMinScore ?? 0.7,
1012
- topK: memCfg.toolErrorTopK ?? 2,
1024
+ // One recall, two bars: the floor decides which quirks are
1025
+ // candidates at all, the injection bar decides which are injected.
1026
+ // A candidate between the two is a "probable match": it suppresses
1027
+ // quirk creation but is only injected when no confident match
1028
+ // exists.
1029
+ const injectBar = memCfg.toolErrorMinScore ?? 0.7;
1030
+ const floorBar = memCfg.toolErrorCreateMinScore ?? 0.6;
1031
+ const topK = memCfg.toolErrorTopK ?? 2;
1032
+ let timer;
1033
+ const recallResult = await Promise.race([
1034
+ recallToolErrorQuirks(recall, info, state, {
1035
+ minScore: floorBar,
1036
+ injectMinScore: injectBar,
1037
+ topK,
1013
1038
  minTokenOverlap: memCfg.toolErrorMinTokenOverlap ?? 1,
1014
- }).then((hits) => {
1015
- if (hits.length > 0) {
1016
- boundedSet(sessionPendingToolErrorQuirk, input.sessionID, { block: formatToolErrorQuirkBlock(info, hits), ts: Date.now() }, MAX_SESSION_MAP_SIZE);
1017
- }
1039
+ // The injection budget limits CONTEXT, not memory: when it is
1040
+ // spent we still need the candidate list to decide whether a
1041
+ // quirk already covers this failure (and whether to create
1042
+ // one). The cooldown still applies.
1043
+ enforceBudget: state.hasBudget(),
1018
1044
  }),
1019
1045
  new Promise((resolve) => {
1020
- setTimeout(resolve, budgetMs);
1046
+ timer = setTimeout(() => resolve(undefined), budgetMs);
1021
1047
  }),
1022
- ]).catch(() => { });
1048
+ ]).catch(() => undefined);
1049
+ if (timer)
1050
+ clearTimeout(timer);
1051
+ if (recallResult && !recallResult.blocked) {
1052
+ // Tier 1: confident matches (>= inject bar). Tier 2: probable
1053
+ // matches (>= floor bar) — used only when tier 1 is empty.
1054
+ const tier1 = recallResult.inject;
1055
+ const tier2 = recallResult.candidates.filter((c) => c.rawSimilarity < injectBar && !state.injectedQuirkIds.has(c.id));
1056
+ const hits = tier1.length > 0 ? tier1 : tier2.slice(0, topK);
1057
+ state.record(info, hits.map((h) => h.id));
1058
+ // No candidate at all → nothing in memory covers this failure.
1059
+ // Record one so a future occurrence can be answered from memory.
1060
+ let createdHit;
1061
+ if (recallResult.candidates.length === 0 && memCfg.autoCreateOnToolError) {
1062
+ const createState = sessionToolErrorCreateState.get(input.sessionID) ?? createToolErrorCreateState({
1063
+ maxPerSession: memCfg.toolErrorCreateMaxPerSession ?? 2,
1064
+ cooldownMs: memCfg.toolErrorCreateCooldownMs ?? 600_000,
1065
+ });
1066
+ boundedSet(sessionToolErrorCreateState, input.sessionID, createState, MAX_SESSION_MAP_SIZE);
1067
+ if (createState.shouldCreate(info)) {
1068
+ const content = buildToolErrorQuirkContent(info);
1069
+ const createBudgetMs = memCfg.toolErrorCreateLatencyBudgetMs ?? 2000;
1070
+ let createTimer;
1071
+ const created = await Promise.race([
1072
+ createToolErrorQuirk({ add: (q) => addQuirk(qDeps, q) }, info, content),
1073
+ new Promise((resolve) => {
1074
+ createTimer = setTimeout(() => resolve(undefined), createBudgetMs);
1075
+ }),
1076
+ ]).catch(() => undefined);
1077
+ if (createTimer)
1078
+ clearTimeout(createTimer);
1079
+ if (created?.created && created.id) {
1080
+ createState.record(info, true);
1081
+ appendDebugLog(options.logFilePath, {
1082
+ scope: "quirk.tool-error",
1083
+ message: `created quirk ${created.id} for tool "${input.tool}"`,
1084
+ });
1085
+ if (memCfg.toolErrorInjectCreated) {
1086
+ createdHit = {
1087
+ id: created.id,
1088
+ content,
1089
+ quirkType: "gotcha",
1090
+ score: 1,
1091
+ rawSimilarity: 1,
1092
+ };
1093
+ }
1094
+ }
1095
+ else {
1096
+ // A trust-monitor rejection or a store failure — log it and
1097
+ // carry on; the tool error must never break the session.
1098
+ createState.record(info, false);
1099
+ appendDebugLog(options.logFilePath, {
1100
+ scope: "quirk.tool-error",
1101
+ message: `quirk not created for tool "${input.tool}": ${created?.reason ?? "timeout"}`,
1102
+ });
1103
+ }
1104
+ }
1105
+ }
1106
+ const finalHits = createdHit ? [...hits, createdHit] : hits;
1107
+ if (finalHits.length > 0) {
1108
+ boundedSet(sessionPendingToolErrorQuirk, input.sessionID, {
1109
+ block: formatToolErrorQuirkBlock(info, finalHits, {
1110
+ heading: createdHit
1111
+ ? `⚠ **Tool error** \`${info.tool}\` — quirk memory (incl. newly recorded):`
1112
+ : undefined,
1113
+ }),
1114
+ ts: Date.now(),
1115
+ }, MAX_SESSION_MAP_SIZE);
1116
+ }
1117
+ }
1023
1118
  }
1024
1119
  }
1025
1120
  // Cap the per-session list — long sessions accumulate full tool
@@ -1091,7 +1186,13 @@ export function createRagHooks(options) {
1091
1186
  const budgetMs = memCfg.autoInjectLatencyBudgetMs ?? 2000;
1092
1187
  let timer;
1093
1188
  let quirkResults = await Promise.race([
1094
- recallQuirks(quirkDeps, query, { topK: memCfg.autoInjectTopK ?? 1, minScore: memCfg.autoInjectMinScore ?? 0.75 })
1189
+ recallQuirks(quirkDeps, query, {
1190
+ topK: memCfg.autoInjectTopK ?? 1,
1191
+ minScore: memCfg.autoInjectMinScore ?? 0.75,
1192
+ // Auto-created tool-error quirks are raw error dumps — they
1193
+ // are surfaced by the tool-error path, not on unrelated turns.
1194
+ excludeTags: [TOOL_ERROR_QUIRK_TAG],
1195
+ })
1095
1196
  .then((r) => {
1096
1197
  if (timer)
1097
1198
  clearTimeout(timer);
@@ -1383,6 +1484,8 @@ export function createRagHooks(options) {
1383
1484
  memCfg?.passiveCapture ? "passive-capture" : "",
1384
1485
  memCfg?.promptEnforcement ? "prompt-enforce" : "",
1385
1486
  memCfg?.sessionEndExtraction ? "session-end" : "",
1487
+ memCfg?.injectOnToolError ? "tool-error-inject" : "",
1488
+ memCfg?.autoCreateOnToolError ? "tool-error-create" : "",
1386
1489
  ].filter(Boolean);
1387
1490
  if (flags.length > 0) {
1388
1491
  lines.push(`Flags: ${flags.join(", ")}`);
@@ -1416,7 +1519,13 @@ export function createRagHooks(options) {
1416
1519
  const minScore = quirkMemoryCfg.autoInjectMinScore ?? 0.75;
1417
1520
  let timer;
1418
1521
  let quirkResults = await Promise.race([
1419
- recallQuirks(quirkDeps, quirkQuery, { topK: quirkMemoryCfg.autoInjectTopK ?? 1, minScore })
1522
+ recallQuirks(quirkDeps, quirkQuery, {
1523
+ topK: quirkMemoryCfg.autoInjectTopK ?? 1,
1524
+ minScore,
1525
+ // Auto-created tool-error quirks are raw error dumps — they
1526
+ // are surfaced by the tool-error path, not on unrelated turns.
1527
+ excludeTags: [TOOL_ERROR_QUIRK_TAG],
1528
+ })
1420
1529
  .then((r) => {
1421
1530
  if (timer)
1422
1531
  clearTimeout(timer);
@@ -93,6 +93,16 @@ export declare function recallQuirks(deps: QuirkStoreDeps, query: string, option
93
93
  * cosine mapped to [0,1] the same way the vector stores report raw scores).
94
94
  * Auto-inject passes its own (usually higher) bar. */
95
95
  minScore?: number;
96
+ /** Exclude quirks carrying any of these tags. Unlike `tags` (any-of
97
+ * inclusion), this is a negative filter — used to keep specialized quirk
98
+ * classes (e.g. `tool-error`) out of the generic auto-inject path. */
99
+ excludeTags?: string[];
100
+ /** Keep `explanation` on the returned results. The caller can then read the
101
+ * RAW vector similarity (`explanation.scoreBreakdown.rawVectorScore`),
102
+ * which is not the same as `score`: `score` is confidence-discounted
103
+ * (`similarity * confidence`), so it cannot be compared against a
104
+ * similarity threshold. */
105
+ explain?: boolean;
96
106
  }): Promise<SearchResult[]>;
97
107
  /** Lint quirks for low confidence, staleness, duplicates, and orphan source refs. */
98
108
  export declare function lintQuirks(deps: QuirkStoreDeps): Promise<string[]>;
@@ -540,6 +540,11 @@ export async function recallQuirks(deps, query, options) {
540
540
  if (!options.tags.some((t) => chunkTags.includes(t)))
541
541
  return false;
542
542
  }
543
+ if (options?.excludeTags?.length) {
544
+ const chunkTags = r.chunk.metadata.tags ?? [];
545
+ if (options.excludeTags.some((t) => chunkTags.includes(t)))
546
+ return false;
547
+ }
543
548
  return true;
544
549
  });
545
550
  // Rank by semantic similarity (confidence-weighted) and report that same
@@ -549,7 +554,10 @@ export async function recallQuirks(deps, query, options) {
549
554
  const conf = r.chunk.metadata.confidence ?? 1;
550
555
  const similarity = r.explanation?.scoreBreakdown?.rawVectorScore ?? 0;
551
556
  r.score = similarity * Math.min(1, Math.max(0.01, conf));
552
- delete r.explanation;
557
+ // `explain` keeps the breakdown so a caller can read the RAW similarity
558
+ // (unaffected by the confidence discount applied to `score` above).
559
+ if (!options?.explain)
560
+ delete r.explanation;
553
561
  }
554
562
  filtered.sort((a, b) => b.score - a.score);
555
563
  return filtered.slice(0, topK);
@@ -0,0 +1,111 @@
1
+ /**
2
+ * @fileoverview Tool-error → quirk creation: when a tool call fails and NO
3
+ * existing quirk covers the failure, record a new one so future sessions can
4
+ * recall it.
5
+ *
6
+ * Design notes:
7
+ * - Pure and dependency-injected: the caller passes an `add` function (the plugin
8
+ * binds `addQuirk`), so this module has no store/embedder dependencies and is
9
+ * cheap to unit-test.
10
+ * - Deterministic content: no LLM is involved. The quirk is a template built
11
+ * from the tool name and the error text, plus an optional deterministic cause
12
+ * for a handful of well-known error classes. This keeps the path available
13
+ * even when `description.enabled` is false (the LLM-based auto-capture
14
+ * pipeline is inert then) and keeps it off the critical latency path.
15
+ * - Bounded: a per-session budget and a per-error-signature cooldown cap how
16
+ * many quirks a failing session can write. Cross-session duplication is
17
+ * prevented by the semantic recall that runs BEFORE creation — the quirk
18
+ * written for a failure is recalled on the next occurrence of that failure.
19
+ * - The trust monitor is NOT bypassed. A rejected quirk (e.g. an error text
20
+ * that contains `rm -rf`) is reported as "not created" with a reason; the
21
+ * caller logs it.
22
+ */
23
+ import type { Quirk, QuirkInput } from "./types.js";
24
+ 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";
29
+ /** Defaults for the tool-error creation path. */
30
+ export declare const TOOL_ERROR_CREATE_DEFAULTS: {
31
+ /**
32
+ * 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.
35
+ */
36
+ readonly minScore: 0.6;
37
+ /** Maximum quirks created per session. Default 2. */
38
+ readonly maxPerSession: 2;
39
+ /** Cooldown per normalized error signature in ms. Default 10 minutes. */
40
+ readonly cooldownMs: 600000;
41
+ /** Error text is truncated to this length before it becomes quirk content. */
42
+ readonly maxErrorChars: 400;
43
+ /** Hard cap on the generated quirk content. */
44
+ readonly maxContentChars: 300;
45
+ /** Confidence assigned to an auto-created quirk. */
46
+ readonly confidence: 0.6;
47
+ /** Errors shorter than this carry no information — nothing is recorded. */
48
+ readonly minErrorChars: 15;
49
+ };
50
+ /**
51
+ * Classify an error message into a short, deterministic cause.
52
+ *
53
+ * Returns `undefined` for unknown errors — the raw text is then the whole
54
+ * story.
55
+ */
56
+ export declare function classifyToolError(error: string): string | undefined;
57
+ /**
58
+ * Build the quirk content for a failed tool call.
59
+ *
60
+ * The tool name and the error text are embedded verbatim (whitespace
61
+ * collapsed, truncated) on purpose: a later occurrence of the same failure
62
+ * must share tokens with this content (the lexical recall gate) and embed
63
+ * close to it (the semantic gate), otherwise the creation path would fire
64
+ * again and again for the same error.
65
+ */
66
+ export declare function buildToolErrorQuirkContent(info: ToolErrorInfo): string;
67
+ /** True when the error carries enough information to be worth recording. */
68
+ export declare function isWorthRecordingToolError(info: ToolErrorInfo): boolean;
69
+ /** Tunables for the per-session creation state. */
70
+ export interface ToolErrorCreateOptions {
71
+ /** Maximum quirks created per session. Default 2. */
72
+ maxPerSession?: number;
73
+ /** Cooldown per normalized error signature in ms. Default 600000 (10 min). */
74
+ cooldownMs?: number;
75
+ }
76
+ /** Per-session creation bookkeeping (budget, cooldown, created signatures). */
77
+ export interface ToolErrorCreateState {
78
+ /** True when a new quirk may be created (budget left, signature not cooling down). */
79
+ shouldCreate(info: ToolErrorInfo, now?: number): boolean;
80
+ /** Record the attempt. Always refreshes the cooldown; consumes budget only when `created` is true. */
81
+ record(info: ToolErrorInfo, created: boolean, now?: number): void;
82
+ /** Normalized error signatures that already produced a quirk in this session. */
83
+ readonly createdSignatures: ReadonlySet<string>;
84
+ /** Number of quirks actually created in this session. */
85
+ creationCount(): number;
86
+ }
87
+ /** Create the per-session creation state. */
88
+ export declare function createToolErrorCreateState(options?: ToolErrorCreateOptions): ToolErrorCreateState;
89
+ /** The function that persists a quirk; injected so the module stays testable. */
90
+ export type ToolErrorQuirkAddFn = (input: QuirkInput) => Promise<Quirk>;
91
+ /** Dependencies for the creation path. */
92
+ export interface ToolErrorQuirkDeps {
93
+ /** Persists the quirk. The plugin binds `addQuirk` to the quirk store deps. */
94
+ add: ToolErrorQuirkAddFn;
95
+ }
96
+ /** The outcome of a creation attempt. */
97
+ export interface ToolErrorQuirkCreateResult {
98
+ /** True when a quirk was written. */
99
+ created: boolean;
100
+ /** The new quirk's id (only when `created`). */
101
+ id?: string;
102
+ /** Why nothing was created (e.g. trust-monitor rejection, error too short). */
103
+ reason?: string;
104
+ }
105
+ /**
106
+ * Create and persist a quirk for a failed tool call.
107
+ *
108
+ * Never throws: a trust-monitor rejection or a store failure is reported as
109
+ * `created: false` with a reason so the caller can log it and carry on.
110
+ */
111
+ export declare function createToolErrorQuirk(deps: ToolErrorQuirkDeps, info: ToolErrorInfo, content?: string): Promise<ToolErrorQuirkCreateResult>;
@@ -0,0 +1,173 @@
1
+ /**
2
+ * @fileoverview Tool-error → quirk creation: when a tool call fails and NO
3
+ * existing quirk covers the failure, record a new one so future sessions can
4
+ * recall it.
5
+ *
6
+ * Design notes:
7
+ * - Pure and dependency-injected: the caller passes an `add` function (the plugin
8
+ * binds `addQuirk`), so this module has no store/embedder dependencies and is
9
+ * cheap to unit-test.
10
+ * - Deterministic content: no LLM is involved. The quirk is a template built
11
+ * from the tool name and the error text, plus an optional deterministic cause
12
+ * for a handful of well-known error classes. This keeps the path available
13
+ * even when `description.enabled` is false (the LLM-based auto-capture
14
+ * pipeline is inert then) and keeps it off the critical latency path.
15
+ * - Bounded: a per-session budget and a per-error-signature cooldown cap how
16
+ * many quirks a failing session can write. Cross-session duplication is
17
+ * prevented by the semantic recall that runs BEFORE creation — the quirk
18
+ * written for a failure is recalled on the next occurrence of that failure.
19
+ * - The trust monitor is NOT bypassed. A rejected quirk (e.g. an error text
20
+ * that contains `rm -rf`) is reported as "not created" with a reason; the
21
+ * caller logs it.
22
+ */
23
+ 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";
28
+ /** Defaults for the tool-error creation path. */
29
+ export const TOOL_ERROR_CREATE_DEFAULTS = {
30
+ /**
31
+ * 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.
34
+ */
35
+ minScore: 0.6,
36
+ /** Maximum quirks created per session. Default 2. */
37
+ maxPerSession: 2,
38
+ /** Cooldown per normalized error signature in ms. Default 10 minutes. */
39
+ cooldownMs: 600_000,
40
+ /** Error text is truncated to this length before it becomes quirk content. */
41
+ maxErrorChars: 400,
42
+ /** Hard cap on the generated quirk content. */
43
+ maxContentChars: 300,
44
+ /** Confidence assigned to an auto-created quirk. */
45
+ confidence: 0.6,
46
+ /** Errors shorter than this carry no information — nothing is recorded. */
47
+ minErrorChars: 15,
48
+ };
49
+ /** Known error classes with a deterministic, actionable cause. */
50
+ const ERROR_CAUSES = [
51
+ {
52
+ pattern: /unknown tool|no such tool|tool .*not found|not a registered tool/i,
53
+ cause: "the tool name may be wrong, or the tool is not available in this session",
54
+ },
55
+ {
56
+ pattern: /enoent|no such file or directory|cannot find module/i,
57
+ cause: "the path or module name may be wrong",
58
+ },
59
+ {
60
+ pattern: /eacces|permission denied/i,
61
+ cause: "the path may need different permissions",
62
+ },
63
+ {
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",
66
+ },
67
+ {
68
+ pattern: /\b429\b|rate limit|too many requests/i,
69
+ cause: "the request was rate limited — retry later",
70
+ },
71
+ {
72
+ pattern: /timed? ?out|timeout|etimedout/i,
73
+ cause: "the operation timed out",
74
+ },
75
+ ];
76
+ /**
77
+ * Classify an error message into a short, deterministic cause.
78
+ *
79
+ * Returns `undefined` for unknown errors — the raw text is then the whole
80
+ * story.
81
+ */
82
+ export function classifyToolError(error) {
83
+ for (const { pattern, cause } of ERROR_CAUSES) {
84
+ if (pattern.test(error))
85
+ return cause;
86
+ }
87
+ return undefined;
88
+ }
89
+ /**
90
+ * Build the quirk content for a failed tool call.
91
+ *
92
+ * The tool name and the error text are embedded verbatim (whitespace
93
+ * collapsed, truncated) on purpose: a later occurrence of the same failure
94
+ * must share tokens with this content (the lexical recall gate) and embed
95
+ * close to it (the semantic gate), otherwise the creation path would fire
96
+ * again and again for the same error.
97
+ */
98
+ export function buildToolErrorQuirkContent(info) {
99
+ const error = info.error
100
+ .replace(/\s+/g, " ")
101
+ .trim()
102
+ .slice(0, TOOL_ERROR_CREATE_DEFAULTS.maxErrorChars);
103
+ const cause = classifyToolError(info.error);
104
+ const base = `Tool \`${info.tool}\` failed: ${error}`;
105
+ const content = cause ? `${base} — ${cause}` : base;
106
+ return content.slice(0, TOOL_ERROR_CREATE_DEFAULTS.maxContentChars);
107
+ }
108
+ /** True when the error carries enough information to be worth recording. */
109
+ export function isWorthRecordingToolError(info) {
110
+ return info.error.replace(/\s+/g, " ").trim().length >= TOOL_ERROR_CREATE_DEFAULTS.minErrorChars;
111
+ }
112
+ /** Create the per-session creation state. */
113
+ export function createToolErrorCreateState(options) {
114
+ const cooldownMs = options?.cooldownMs ?? TOOL_ERROR_CREATE_DEFAULTS.cooldownMs;
115
+ const maxPerSession = options?.maxPerSession ?? TOOL_ERROR_CREATE_DEFAULTS.maxPerSession;
116
+ const lastAttemptAt = new Map();
117
+ const createdSignatures = new Set();
118
+ let creations = 0;
119
+ return {
120
+ shouldCreate(info, now = Date.now()) {
121
+ if (creations >= maxPerSession)
122
+ return false;
123
+ const signature = normalizeToolErrorSignature(info);
124
+ const last = lastAttemptAt.get(signature);
125
+ if (last !== undefined && now - last < cooldownMs)
126
+ return false;
127
+ return true;
128
+ },
129
+ record(info, created, now = Date.now()) {
130
+ const signature = normalizeToolErrorSignature(info);
131
+ lastAttemptAt.set(signature, now);
132
+ if (!created)
133
+ return;
134
+ creations += 1;
135
+ createdSignatures.add(signature);
136
+ },
137
+ get createdSignatures() {
138
+ return createdSignatures;
139
+ },
140
+ creationCount() {
141
+ return creations;
142
+ },
143
+ };
144
+ }
145
+ /**
146
+ * Create and persist a quirk for a failed tool call.
147
+ *
148
+ * Never throws: a trust-monitor rejection or a store failure is reported as
149
+ * `created: false` with a reason so the caller can log it and carry on.
150
+ */
151
+ export async function createToolErrorQuirk(deps, info, content) {
152
+ if (!isWorthRecordingToolError(info)) {
153
+ return { created: false, reason: "error text too short to record" };
154
+ }
155
+ const text = (content ?? buildToolErrorQuirkContent(info)).trim();
156
+ if (!text) {
157
+ return { created: false, reason: "empty quirk content" };
158
+ }
159
+ try {
160
+ const quirk = await deps.add({
161
+ content: text,
162
+ quirkType: "gotcha",
163
+ tags: [TOOL_ERROR_QUIRK_TAG, TOOL_ERROR_AUTO_TAG, `tool:${info.tool}`],
164
+ confidence: TOOL_ERROR_CREATE_DEFAULTS.confidence,
165
+ sourceRef: `tool-error:${info.tool}`,
166
+ });
167
+ return { created: true, id: quirk.id };
168
+ }
169
+ catch (err) {
170
+ return { created: false, reason: err instanceof Error ? err.message : String(err) };
171
+ }
172
+ }
173
+ //# sourceMappingURL=tool-error-create.js.map
@@ -13,6 +13,12 @@
13
13
  * - A failed recall still counts as an attempt (cooldown), so a repeatedly failing
14
14
  * tool does not hammer the embedder every call — but it does not consume the
15
15
  * per-session budget; only actual injections do.
16
+ * - Two similarity bars: the recall FLOOR (`minScore`) decides which quirks are
17
+ * candidates at all, the INJECTION bar (`injectMinScore`) decides which of them
18
+ * are injected. The gap between them is the "probable match" tier — it suppresses
19
+ * quirk creation but is only injected when no confident match exists. The bars are
20
+ * compared against the RAW vector similarity, never against the confidence-
21
+ * discounted `score` (see `rawSimilarity`).
16
22
  */
17
23
  /** A failed tool call as observed by the plugin. */
18
24
  export interface ToolErrorInfo {
@@ -30,9 +36,19 @@ export interface ToolErrorRecallHit {
30
36
  content: string;
31
37
  metadata?: {
32
38
  quirkType?: string;
39
+ tags?: string[];
33
40
  };
34
41
  };
35
42
  score: number;
43
+ /**
44
+ * Raw vector similarity (0-1) — the cosine-mapped similarity WITHOUT the
45
+ * confidence discount that `recallQuirks` applies to `score`
46
+ * (`score = similarity * confidence`). Thresholds must be compared against
47
+ * this field; `score` is not comparable to a similarity threshold because a
48
+ * high-confidence quirk and a low-confidence one with the same similarity get
49
+ * different scores. Falls back to `score` when the caller cannot provide it.
50
+ */
51
+ rawSimilarity?: number;
36
52
  }
37
53
  /** Recall function the caller provides (usually a `recallQuirks` wrapper). */
38
54
  export type ToolErrorRecallFn = (query: string, options: {
@@ -45,15 +61,34 @@ export interface ToolErrorQuirkHit {
45
61
  content: string;
46
62
  quirkType?: string;
47
63
  score: number;
64
+ /** Raw vector similarity (0-1) — the value thresholds are compared against. */
65
+ rawSimilarity: number;
48
66
  }
49
67
  /** Tunables for the tool-error quirk path. */
50
68
  export interface ToolErrorRecallOptions {
51
- /** Minimum recall score for a quirk to be injected. Default 0.7. */
69
+ /**
70
+ * Recall floor — the minimum raw similarity a candidate must clear to be
71
+ * returned by the recall at all. Default 0.7.
72
+ */
52
73
  minScore?: number;
74
+ /**
75
+ * Threshold a candidate must clear to be INJECTED. Defaults to `minScore`.
76
+ * A candidate between the floor and this threshold is a "probable match": it
77
+ * suppresses quirk creation but is only injected when no confident match
78
+ * exists.
79
+ */
80
+ injectMinScore?: number;
53
81
  /** Maximum quirks injected per error. Default 2. */
54
82
  topK?: number;
55
83
  /** Minimum shared meaningful words (>=3 chars) between quirk and error. 0 disables. Default 1. */
56
84
  minTokenOverlap?: number;
85
+ /**
86
+ * Whether the per-session injection budget may block the recall outright
87
+ * (default true). Set to `false` when the caller still needs the candidate
88
+ * list even though it may not inject anything — e.g. to decide whether a
89
+ * quirk already exists. The cooldown still applies either way.
90
+ */
91
+ enforceBudget?: boolean;
57
92
  }
58
93
  /** Tunables for the per-session injection state. */
59
94
  export interface ToolErrorInjectionOptions {
@@ -66,6 +101,16 @@ export interface ToolErrorInjectionOptions {
66
101
  export interface ToolErrorInjectionState {
67
102
  /** True when this error may trigger a recall (budget left, signature not cooling down). */
68
103
  shouldInject(info: ToolErrorInfo, now?: number): boolean;
104
+ /**
105
+ * True when the per-signature cooldown blocks this error. Independent of the
106
+ * per-session budget — a cooled-down error must not trigger another recall
107
+ * (that is what stops a repeatedly failing tool from hammering the
108
+ * embedder), while an exhausted budget is a *context* limit that must not
109
+ * also block quirk creation.
110
+ */
111
+ isCoolingDown(info: ToolErrorInfo, now?: number): boolean;
112
+ /** True when the per-session injection budget still has room. */
113
+ hasBudget(): boolean;
69
114
  /** Record an attempt. Always refreshes the cooldown; counts toward the budget only when quirkIds is non-empty. */
70
115
  record(info: ToolErrorInfo, quirkIds: readonly string[], now?: number): void;
71
116
  /** Quirk ids already injected in this session. */
@@ -91,6 +136,34 @@ export declare function normalizeToolErrorSignature(info: ToolErrorInfo): string
91
136
  export declare function buildToolErrorQuery(info: ToolErrorInfo): string;
92
137
  /** Create the per-session injection state. */
93
138
  export declare function createToolErrorInjectionState(options?: ToolErrorInjectionOptions): ToolErrorInjectionState;
139
+ /** The outcome of a single tool-error recall. */
140
+ export interface ToolErrorRecallResult {
141
+ /**
142
+ * Hits that may be injected right now: they cleared the injection bar and
143
+ * were not already injected in this session.
144
+ */
145
+ inject: ToolErrorQuirkHit[];
146
+ /**
147
+ * Every hit that cleared the recall floor, sorted by raw similarity
148
+ * descending. Includes already-injected quirks — the caller uses this to
149
+ * decide whether a quirk ALREADY EXISTS (which suppresses creation) even
150
+ * when it must not be injected again.
151
+ */
152
+ candidates: ToolErrorQuirkHit[];
153
+ /** True when the attempt was blocked by the cooldown or the per-session budget. */
154
+ blocked: boolean;
155
+ }
156
+ /**
157
+ * Recall quirks for a failed tool call and tier them by raw similarity.
158
+ *
159
+ * The recall happens ONCE, at the floor (`minScore`), so the caller can tell
160
+ * "a confident match exists" from "only a probable match exists" from "no
161
+ * match at all" without paying for a second embedding.
162
+ *
163
+ * This function does NOT mutate the injection state — the caller records the
164
+ * attempt (and the injected ids) once it has decided what to inject.
165
+ */
166
+ export declare function recallToolErrorQuirks(recall: ToolErrorRecallFn, info: ToolErrorInfo, state: ToolErrorInjectionState, options?: ToolErrorRecallOptions): Promise<ToolErrorRecallResult>;
94
167
  /**
95
168
  * Select quirks for a failed tool call.
96
169
  *
@@ -100,7 +173,9 @@ export declare function createToolErrorInjectionState(options?: ToolErrorInjecti
100
173
  */
101
174
  export declare function selectToolErrorQuirks(recall: ToolErrorRecallFn, info: ToolErrorInfo, state: ToolErrorInjectionState, options?: ToolErrorRecallOptions): Promise<ToolErrorQuirkHit[]>;
102
175
  /** Format the injection block appended to the next model request. Empty when there are no hits. */
103
- export declare function formatToolErrorQuirkBlock(info: ToolErrorInfo, hits: readonly ToolErrorQuirkHit[]): string;
176
+ export declare function formatToolErrorQuirkBlock(info: ToolErrorInfo, hits: readonly ToolErrorQuirkHit[], options?: {
177
+ heading?: string;
178
+ }): string;
104
179
  /**
105
180
  * Shape a tool error as an entry for the existing auto-capture pipeline
106
181
  * (`CaptureExchange.toolResults`). Feed the returned entry into the session's
@@ -13,6 +13,12 @@
13
13
  * - A failed recall still counts as an attempt (cooldown), so a repeatedly failing
14
14
  * tool does not hammer the embedder every call — but it does not consume the
15
15
  * per-session budget; only actual injections do.
16
+ * - Two similarity bars: the recall FLOOR (`minScore`) decides which quirks are
17
+ * candidates at all, the INJECTION bar (`injectMinScore`) decides which of them
18
+ * are injected. The gap between them is the "probable match" tier — it suppresses
19
+ * quirk creation but is only injected when no confident match exists. The bars are
20
+ * compared against the RAW vector similarity, never against the confidence-
21
+ * discounted `score` (see `rawSimilarity`).
16
22
  */
17
23
  import { sharedWords } from "./quirk-store.js";
18
24
  /** Defaults shared by the state factory and the selector. */
@@ -51,13 +57,17 @@ export function createToolErrorInjectionState(options) {
51
57
  let injections = 0;
52
58
  return {
53
59
  shouldInject(info, now = Date.now()) {
54
- if (injections >= maxPerSession)
60
+ if (!this.hasBudget())
55
61
  return false;
62
+ return !this.isCoolingDown(info, now);
63
+ },
64
+ isCoolingDown(info, now = Date.now()) {
56
65
  const signature = normalizeToolErrorSignature(info);
57
66
  const last = lastAttemptAt.get(signature);
58
- if (last !== undefined && now - last < cooldownMs)
59
- return false;
60
- return true;
67
+ return last !== undefined && now - last < cooldownMs;
68
+ },
69
+ hasBudget() {
70
+ return injections < maxPerSession;
61
71
  },
62
72
  record(info, quirkIds, now = Date.now()) {
63
73
  lastAttemptAt.set(normalizeToolErrorSignature(info), now);
@@ -76,16 +86,25 @@ export function createToolErrorInjectionState(options) {
76
86
  };
77
87
  }
78
88
  /**
79
- * Select quirks for a failed tool call.
89
+ * Recall quirks for a failed tool call and tier them by raw similarity.
80
90
  *
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.
91
+ * The recall happens ONCE, at the floor (`minScore`), so the caller can tell
92
+ * "a confident match exists" from "only a probable match exists" from "no
93
+ * match at all" without paying for a second embedding.
94
+ *
95
+ * This function does NOT mutate the injection state — the caller records the
96
+ * attempt (and the injected ids) once it has decided what to inject.
84
97
  */
85
- export async function selectToolErrorQuirks(recall, info, state, options) {
86
- if (!state.shouldInject(info))
87
- return [];
98
+ export async function recallToolErrorQuirks(recall, info, state, options) {
99
+ const budgetAvailable = state.hasBudget();
100
+ if (state.isCoolingDown(info)) {
101
+ return { inject: [], candidates: [], blocked: true };
102
+ }
103
+ if (!budgetAvailable && options?.enforceBudget !== false) {
104
+ return { inject: [], candidates: [], blocked: true };
105
+ }
88
106
  const minScore = options?.minScore ?? TOOL_ERROR_DEFAULTS.minScore;
107
+ const injectMinScore = options?.injectMinScore ?? minScore;
89
108
  const topK = options?.topK ?? TOOL_ERROR_DEFAULTS.topK;
90
109
  const minTokenOverlap = options?.minTokenOverlap ?? TOOL_ERROR_DEFAULTS.minTokenOverlap;
91
110
  let raw = [];
@@ -94,17 +113,15 @@ export async function selectToolErrorQuirks(recall, info, state, options) {
94
113
  raw = await recall(buildToolErrorQuery(info), { topK: Math.max(topK * 3, 6), minScore });
95
114
  }
96
115
  catch {
97
- // Recall failures must never break tool execution; fall through to recording.
98
- state.record(info, []);
99
- return [];
116
+ // Recall failures must never break tool execution; the caller still
117
+ // records the attempt so the cooldown applies.
118
+ return { inject: [], candidates: [], blocked: false };
100
119
  }
101
120
  // Filter everything first, then sort and slice — otherwise the topK cut
102
121
  // would keep the first raw entries instead of the highest-scoring ones.
103
122
  const candidates = [];
104
123
  for (const hit of raw) {
105
124
  const { id, content } = hit.chunk;
106
- if (state.injectedQuirkIds.has(id))
107
- continue;
108
125
  if (minTokenOverlap > 0 && sharedWords(content, info.error) < minTokenOverlap)
109
126
  continue;
110
127
  candidates.push({
@@ -112,18 +129,37 @@ export async function selectToolErrorQuirks(recall, info, state, options) {
112
129
  content,
113
130
  quirkType: hit.chunk.metadata?.quirkType,
114
131
  score: hit.score,
132
+ rawSimilarity: hit.rawSimilarity ?? hit.score,
115
133
  });
116
134
  }
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;
135
+ candidates.sort((a, b) => b.rawSimilarity - a.rawSimilarity);
136
+ const inject = budgetAvailable
137
+ ? candidates
138
+ .filter((c) => c.rawSimilarity >= injectMinScore && !state.injectedQuirkIds.has(c.id))
139
+ .slice(0, topK)
140
+ : [];
141
+ return { inject, candidates, blocked: false };
142
+ }
143
+ /**
144
+ * Select quirks for a failed tool call.
145
+ *
146
+ * Returns `[]` when the state blocks the attempt (cooldown/budget) or nothing
147
+ * passes the score, dedup, and lexical gates. Records the attempt in the state —
148
+ * with cooldown always, with budget only when at least one quirk is returned.
149
+ */
150
+ export async function selectToolErrorQuirks(recall, info, state, options) {
151
+ const result = await recallToolErrorQuirks(recall, info, state, options);
152
+ if (result.blocked)
153
+ return [];
154
+ state.record(info, result.inject.map((h) => h.id));
155
+ return result.inject;
121
156
  }
122
157
  /** Format the injection block appended to the next model request. Empty when there are no hits. */
123
- export function formatToolErrorQuirkBlock(info, hits) {
158
+ export function formatToolErrorQuirkBlock(info, hits, options) {
124
159
  if (hits.length === 0)
125
160
  return "";
126
- const lines = ["", "---", `⚠ **Tool error** \`${info.tool}\` — matching quirk memory:`, ""];
161
+ const heading = options?.heading ?? `⚠ **Tool error** \`${info.tool}\` — matching quirk memory:`;
162
+ const lines = ["", "---", heading, ""];
127
163
  for (const hit of hits) {
128
164
  const badge = hit.quirkType ? `[\`${hit.quirkType}\`] ` : "";
129
165
  lines.push(`- ${badge}${hit.content}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-rag-plugin",
3
- "version": "2.5.3",
3
+ "version": "2.6.0",
4
4
  "description": "OpenCode plugin for local-first RAG-based semantic code search",
5
5
  "type": "module",
6
6
  "main": "./dist/plugin-entry.js",