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