opencode-rag-plugin 2.5.2 → 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 +6 -1
- package/dist/cli/index.d.ts +5 -0
- package/dist/cli/index.js +75 -5
- package/dist/core/config.d.ts +27 -0
- package/dist/core/config.js +20 -0
- package/dist/plugin.js +124 -15
- package/dist/quirks/quirk-store.d.ts +10 -0
- package/dist/quirks/quirk-store.js +9 -1
- package/dist/quirks/tool-error-create.d.ts +111 -0
- package/dist/quirks/tool-error-create.js +173 -0
- package/dist/quirks/tool-error-recall.d.ts +77 -2
- package/dist/quirks/tool-error-recall.js +58 -22
- package/package.json +1 -1
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.).
|
package/dist/cli/index.d.ts
CHANGED
|
@@ -27,6 +27,11 @@ export declare function shouldAutoRunCli(moduleUrl: string, argv1?: string): boo
|
|
|
27
27
|
* This is the public API entry point for running the CLI from code
|
|
28
28
|
* (e.g. from tests or the library export).
|
|
29
29
|
*
|
|
30
|
+
* Never terminates the host process: Commander's exits are converted into
|
|
31
|
+
* errors. `--help` and `--version` resolve normally (their output was
|
|
32
|
+
* already printed); every other Commander error — a missing required
|
|
33
|
+
* argument, an unknown option — is rethrown so the caller can react.
|
|
34
|
+
*
|
|
30
35
|
* @param argv - The argument vector to parse (defaults to `process.argv`).
|
|
31
36
|
*/
|
|
32
37
|
export declare function runCli(argv?: string[]): Promise<void>;
|
package/dist/cli/index.js
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
* referenced by the `bin` entry in `package.json`. The sibling file
|
|
11
11
|
* `dist/cli.js` is a backwards-compatibility re-export shim.
|
|
12
12
|
*/
|
|
13
|
-
import { Command } from "commander";
|
|
13
|
+
import { Command, CommanderError } from "commander";
|
|
14
14
|
import { realpathSync } from "node:fs";
|
|
15
15
|
import { basename, dirname } from "node:path";
|
|
16
16
|
import { fileURLToPath } from "node:url";
|
|
@@ -29,6 +29,15 @@ program
|
|
|
29
29
|
.name("opencode-rag")
|
|
30
30
|
.description(`Local-first RAG semantic code search v${pkg.version}`)
|
|
31
31
|
.version(pkg.version);
|
|
32
|
+
// Commander's default is to call `process.exit()` for `--help`, `--version`
|
|
33
|
+
// and argument-validation errors. That is fatal for `runCli()` — the
|
|
34
|
+
// programmatic API used by tests and library consumers: a `--help` would
|
|
35
|
+
// terminate the *host* process instead of returning. Override the exit so
|
|
36
|
+
// Commander throws a `CommanderError` that the caller can handle.
|
|
37
|
+
//
|
|
38
|
+
// This MUST be set before the sub-commands are registered: they inherit
|
|
39
|
+
// `_exitCallback` from the parent through `copyInheritedSettings()`.
|
|
40
|
+
program.exitOverride();
|
|
32
41
|
registerIndexCommand(program);
|
|
33
42
|
registerQueryCommand(program);
|
|
34
43
|
registerClearCommand(program);
|
|
@@ -73,8 +82,57 @@ export function shouldAutoRunCli(moduleUrl, argv1) {
|
|
|
73
82
|
return false;
|
|
74
83
|
}
|
|
75
84
|
}
|
|
85
|
+
/**
|
|
86
|
+
* Commander error codes that mean "the requested output was printed, exit
|
|
87
|
+
* successfully". `--help` and `--version` are successful outcomes, not
|
|
88
|
+
* failures — they just ask Commander to exit with code 0.
|
|
89
|
+
*/
|
|
90
|
+
const DISPLAY_EXIT_CODES = new Set([
|
|
91
|
+
"commander.helpDisplayed",
|
|
92
|
+
"commander.help",
|
|
93
|
+
"commander.version",
|
|
94
|
+
]);
|
|
95
|
+
/**
|
|
96
|
+
* Check whether a thrown value is Commander's "output was displayed" exit.
|
|
97
|
+
*
|
|
98
|
+
* @param err - The value thrown by `program.parseAsync()`.
|
|
99
|
+
* @returns `true` for `--help` / `--version` style exits.
|
|
100
|
+
*/
|
|
101
|
+
function isDisplayExit(err) {
|
|
102
|
+
const code = err?.code;
|
|
103
|
+
return typeof code === "string" && DISPLAY_EXIT_CODES.has(code);
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Run the CLI as a real command-line process.
|
|
107
|
+
*
|
|
108
|
+
* Commander already wrote the error message to stderr before throwing, so
|
|
109
|
+
* the only thing left to do is map the error to an exit code. Setting
|
|
110
|
+
* `process.exitCode` (instead of calling `process.exit()`) lets pending
|
|
111
|
+
* async work drain first and avoids tearing down live handles mid-flight.
|
|
112
|
+
*
|
|
113
|
+
* @param err - The value thrown by `program.parseAsync()`.
|
|
114
|
+
*/
|
|
115
|
+
function handleCliExit(err) {
|
|
116
|
+
if (isDisplayExit(err)) {
|
|
117
|
+
// Commander's own `help()` exits with `process.exitCode || 0` — respect
|
|
118
|
+
// an exit code a command may already have set.
|
|
119
|
+
process.exitCode = process.exitCode || 0;
|
|
120
|
+
return;
|
|
121
|
+
}
|
|
122
|
+
if (err instanceof CommanderError) {
|
|
123
|
+
process.exitCode = err.exitCode;
|
|
124
|
+
return;
|
|
125
|
+
}
|
|
126
|
+
// Not a Commander control-flow error — rethrow so Node reports it as an
|
|
127
|
+
// unhandled rejection with a visible stack trace, exactly as before.
|
|
128
|
+
throw err;
|
|
129
|
+
}
|
|
130
|
+
/** Parse `process.argv` as a real CLI invocation. */
|
|
131
|
+
function runAsCli() {
|
|
132
|
+
void program.parseAsync(process.argv).catch(handleCliExit);
|
|
133
|
+
}
|
|
76
134
|
if (shouldAutoRunCli(import.meta.url, process.argv[1])) {
|
|
77
|
-
|
|
135
|
+
runAsCli();
|
|
78
136
|
}
|
|
79
137
|
else {
|
|
80
138
|
// Fallback: auto-run only when the script being executed IS the CLI entry
|
|
@@ -85,7 +143,7 @@ else {
|
|
|
85
143
|
const cliScript = basename(modulePath);
|
|
86
144
|
const runningScript = basename(argvRaw);
|
|
87
145
|
if (cliScript === runningScript) {
|
|
88
|
-
|
|
146
|
+
runAsCli();
|
|
89
147
|
}
|
|
90
148
|
else {
|
|
91
149
|
// Backwards-compatibility: when a shim points to the sibling cli.js
|
|
@@ -94,7 +152,7 @@ else {
|
|
|
94
152
|
try {
|
|
95
153
|
const resolvedArgv = realpathSync(argvRaw);
|
|
96
154
|
if (dirname(resolvedArgv) === dirname(dirname(modulePath))) {
|
|
97
|
-
|
|
155
|
+
runAsCli();
|
|
98
156
|
}
|
|
99
157
|
}
|
|
100
158
|
catch {
|
|
@@ -108,9 +166,21 @@ else {
|
|
|
108
166
|
* This is the public API entry point for running the CLI from code
|
|
109
167
|
* (e.g. from tests or the library export).
|
|
110
168
|
*
|
|
169
|
+
* Never terminates the host process: Commander's exits are converted into
|
|
170
|
+
* errors. `--help` and `--version` resolve normally (their output was
|
|
171
|
+
* already printed); every other Commander error — a missing required
|
|
172
|
+
* argument, an unknown option — is rethrown so the caller can react.
|
|
173
|
+
*
|
|
111
174
|
* @param argv - The argument vector to parse (defaults to `process.argv`).
|
|
112
175
|
*/
|
|
113
176
|
export async function runCli(argv = process.argv) {
|
|
114
|
-
|
|
177
|
+
try {
|
|
178
|
+
await program.parseAsync(argv);
|
|
179
|
+
}
|
|
180
|
+
catch (err) {
|
|
181
|
+
if (isDisplayExit(err))
|
|
182
|
+
return;
|
|
183
|
+
throw err;
|
|
184
|
+
}
|
|
115
185
|
}
|
|
116
186
|
//# sourceMappingURL=index.js.map
|
package/dist/core/config.d.ts
CHANGED
|
@@ -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. */
|
package/dist/core/config.js
CHANGED
|
@@ -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,
|
|
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
|
-
|
|
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
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
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
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
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, {
|
|
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, {
|
|
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
|
-
|
|
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
|
-
/**
|
|
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[]
|
|
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 (
|
|
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
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
-
*
|
|
89
|
+
* Recall quirks for a failed tool call and tier them by raw similarity.
|
|
80
90
|
*
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
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
|
|
86
|
-
|
|
87
|
-
|
|
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;
|
|
98
|
-
|
|
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.
|
|
118
|
-
const
|
|
119
|
-
|
|
120
|
-
|
|
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
|
|
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}`);
|