pi-knowledge 0.14.0 → 0.16.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/CHANGELOG.md +32 -0
- package/README.md +63 -24
- package/dist/index.d.ts +10 -4
- package/dist/index.js +300 -187
- package/dist/src/coverage-snapshot.d.ts +23 -0
- package/dist/src/coverage-snapshot.js +53 -0
- package/dist/src/daemon/client.d.ts +60 -0
- package/dist/src/daemon/client.js +360 -0
- package/dist/src/daemon/main.d.ts +2 -0
- package/dist/src/daemon/main.js +109 -0
- package/dist/src/daemon/protocol.d.ts +71 -0
- package/dist/src/daemon/protocol.js +170 -0
- package/dist/src/daemon/runtime.d.ts +26 -0
- package/dist/src/daemon/runtime.js +192 -0
- package/dist/src/daemon/server.d.ts +46 -0
- package/dist/src/daemon/server.js +500 -0
- package/dist/src/daemon/service.d.ts +49 -0
- package/dist/src/daemon/service.js +527 -0
- package/dist/src/diagnostics/health.d.ts +6 -0
- package/dist/src/diagnostics/health.js +135 -2
- package/dist/src/engine.d.ts +63 -9
- package/dist/src/engine.js +959 -170
- package/dist/src/filesystem-access.d.ts +9 -0
- package/dist/src/filesystem-access.js +100 -0
- package/dist/src/indexer/chunker.d.ts +10 -0
- package/dist/src/indexer/chunker.js +284 -9
- package/dist/src/mcp/http.d.ts +47 -0
- package/dist/src/mcp/http.js +564 -0
- package/dist/src/mcp/main.d.ts +2 -0
- package/dist/src/mcp/main.js +97 -0
- package/dist/src/mcp/protocol.d.ts +81 -0
- package/dist/src/mcp/protocol.js +444 -0
- package/dist/src/mcp/server.d.ts +42 -0
- package/dist/src/mcp/server.js +378 -0
- package/dist/src/model-worker-client.js +9 -0
- package/dist/src/model-worker-contract.d.ts +3 -0
- package/dist/src/model-worker-contract.js +8 -0
- package/dist/src/model-worker.js +76 -4
- package/dist/src/network/safe-fetch.d.ts +7 -0
- package/dist/src/network/safe-fetch.js +199 -0
- package/dist/src/node-runtime.d.ts +3 -0
- package/dist/src/node-runtime.js +78 -0
- package/dist/src/profiles.d.ts +15 -0
- package/dist/src/profiles.js +160 -0
- package/dist/src/runtime-config.js +5 -6
- package/dist/src/search/tuning.d.ts +2 -0
- package/dist/src/search/tuning.js +2 -0
- package/dist/src/secure-files.d.ts +17 -0
- package/dist/src/secure-files.js +184 -0
- package/dist/src/status.js +12 -7
- package/dist/src/storage/sqlite.d.ts +4 -1
- package/dist/src/storage/sqlite.js +46 -3
- package/dist/src/type-guards.d.ts +1 -0
- package/dist/src/type-guards.js +3 -0
- package/dist/src/watcher/file-watcher.d.ts +3 -1
- package/dist/src/watcher/file-watcher.js +166 -32
- package/dist/src/windows-security.d.ts +4 -0
- package/dist/src/windows-security.js +47 -0
- package/docs/configuration.md +42 -10
- package/docs/daemon-profiles.md +302 -0
- package/docs/mcp-clients.md +266 -0
- package/docs/offline-mode.md +6 -6
- package/package.json +28 -2
package/dist/index.js
CHANGED
|
@@ -41,160 +41,289 @@ const Type = {
|
|
|
41
41
|
return { ...schema, optional: true };
|
|
42
42
|
},
|
|
43
43
|
};
|
|
44
|
+
let daemonClient;
|
|
45
|
+
let ensureClientPromise;
|
|
46
|
+
let releaseClientPromise;
|
|
47
|
+
let clientGeneration = 0;
|
|
44
48
|
const RUNTIME_EXTENSION = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
|
|
45
49
|
const WATCH_ENABLED = process.env.PI_KNOWLEDGE_WATCH === "true";
|
|
46
50
|
const AUTO_INJECT = process.env.PI_KNOWLEDGE_AUTO_INJECT === "true";
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
51
|
+
const SEARCH_MISS_ACTION_TEXT = {
|
|
52
|
+
add_knowledge_base: "Use knowledge_add to index a directory, file, URL, or text source.",
|
|
53
|
+
fix_kb_id: "Fix kb_id or omit it to search all knowledge bases.",
|
|
54
|
+
wait_for_indexing: "Retry after indexing completes.",
|
|
55
|
+
fix_knowledge_base: "Run knowledge_doctor and follow the action for the affected knowledge base.",
|
|
56
|
+
fix_embedding: "Run knowledge_doctor to resolve the embedding compatibility problem.",
|
|
57
|
+
try_semantic: 'Try mode "semantic", or rephrase with terms from the target files.',
|
|
58
|
+
try_semantic_hybrid: 'Try mode "semantic_hybrid", or rephrase with terms from the target files.',
|
|
59
|
+
relax_filter: "Relax the file type or path filter.",
|
|
60
|
+
reset_offset: "Retry with offset 0.",
|
|
61
|
+
rephrase: "Rephrase with exact terms from the target files.",
|
|
62
|
+
};
|
|
63
|
+
const SYMBOL_MISS_ACTION_TEXT = {
|
|
64
|
+
add_knowledge_base: "Use knowledge_add to index a directory, file, URL, or text source.",
|
|
65
|
+
fix_kb_id: "Fix kb_id or omit it to search all knowledge bases.",
|
|
66
|
+
wait_for_indexing: "Retry after indexing completes.",
|
|
67
|
+
fix_knowledge_base: "Run knowledge_doctor and follow the action for the affected knowledge base.",
|
|
68
|
+
rebuild_symbol_index: "Run knowledge_update for a source-backed KB, or re-add an inline/imported source to rebuild symbol metadata.",
|
|
69
|
+
broaden_symbol_search: "Retry with exact=false.",
|
|
70
|
+
relax_filter: "Relax the kind or file_pattern filter.",
|
|
71
|
+
reset_offset: "Retry with offset 0.",
|
|
72
|
+
use_text_search: 'Try knowledge_search mode "fast" for source text or "adaptive" for surrounding context.',
|
|
73
|
+
};
|
|
74
|
+
function inlineLabel(value, fallback) {
|
|
75
|
+
const normalized = value
|
|
76
|
+
.replace(/[\p{Cc}\p{Cf}]+/gu, " ")
|
|
77
|
+
.replace(/\s+/g, " ")
|
|
78
|
+
.trim()
|
|
79
|
+
.replaceAll('"', "'");
|
|
80
|
+
return normalized && normalized.length <= 80 ? `"${normalized}"` : fallback;
|
|
81
|
+
}
|
|
82
|
+
function requestedKbSuffix(requestedKbId) {
|
|
83
|
+
return requestedKbId ? ` in ${inlineLabel(requestedKbId, "the requested KB")}` : "";
|
|
84
|
+
}
|
|
85
|
+
function compactFilter(miss) {
|
|
86
|
+
const filters = [];
|
|
87
|
+
if (miss.file_type)
|
|
88
|
+
filters.push(`file_type ${inlineLabel(miss.file_type, "with the requested value")}`);
|
|
89
|
+
if (miss.path_pattern)
|
|
90
|
+
filters.push(`path_pattern ${inlineLabel(miss.path_pattern, "with the requested value")}`);
|
|
91
|
+
return filters.join(" and ") || "the requested metadata filters";
|
|
92
|
+
}
|
|
93
|
+
function formatSearchMiss(miss) {
|
|
94
|
+
const scope = requestedKbSuffix(miss.requested_kb_id);
|
|
95
|
+
const indexedChunks = miss.searched_kbs.reduce((count, kb) => count + kb.chunk_count, 0);
|
|
96
|
+
const attemptedModes = miss.attempts?.map((attempt) => attempt.mode);
|
|
97
|
+
const attemptSuffix = attemptedModes && attemptedModes.length > 1 ? ` Modes tried: ${attemptedModes.join(", ")}.` : "";
|
|
98
|
+
let cause;
|
|
99
|
+
switch (miss.reason) {
|
|
100
|
+
case "no_knowledge_bases":
|
|
101
|
+
cause = "No results: no knowledge bases are indexed.";
|
|
102
|
+
break;
|
|
103
|
+
case "knowledge_base_not_found":
|
|
104
|
+
cause = `No results: knowledge base ${inlineLabel(miss.requested_kb_id ?? "", "from the requested kb_id")} does not exist.`;
|
|
105
|
+
break;
|
|
106
|
+
case "no_searchable_knowledge_bases": {
|
|
107
|
+
const indexing = miss.skipped_kbs.find((kb) => kb.status === "indexing");
|
|
108
|
+
const errored = miss.skipped_kbs.find((kb) => kb.status === "error");
|
|
109
|
+
if (miss.action === "wait_for_indexing" && indexing) {
|
|
110
|
+
cause = `No results yet: ${inlineLabel(indexing.name, "the selected KB")} is still indexing (${indexing.chunk_count} chunks persisted).`;
|
|
111
|
+
}
|
|
112
|
+
else if (errored) {
|
|
113
|
+
cause = `No results: ${inlineLabel(errored.name, "the selected KB")} is in error state and is not searchable.`;
|
|
114
|
+
}
|
|
115
|
+
else if (indexing) {
|
|
116
|
+
cause = `No results: one or more selected knowledge bases are unavailable while ${inlineLabel(indexing.name, "one KB")} indexes.`;
|
|
117
|
+
}
|
|
118
|
+
else {
|
|
119
|
+
cause = "No results: no selected knowledge base is currently searchable.";
|
|
120
|
+
}
|
|
121
|
+
break;
|
|
122
|
+
}
|
|
123
|
+
case "no_indexed_chunks":
|
|
124
|
+
cause = "No results: the searchable knowledge bases contain no indexed chunks.";
|
|
125
|
+
break;
|
|
126
|
+
case "embedding_incompatible":
|
|
127
|
+
cause = "No results: the selected knowledge bases are incompatible with the active embedding configuration.";
|
|
128
|
+
break;
|
|
129
|
+
case "no_retrieval_candidates":
|
|
130
|
+
cause = `No results: no retrieval candidates matched${scope} (${indexedChunks} indexed chunks).${attemptSuffix}`;
|
|
131
|
+
break;
|
|
132
|
+
case "threshold_filtered": {
|
|
133
|
+
const threshold = miss.min_hybrid_score === undefined ? "the score threshold" : `the ${miss.min_hybrid_score} score threshold`;
|
|
134
|
+
cause = `No results: ${miss.retrieved_candidates} candidates were retrieved, but none passed ${threshold}.${attemptSuffix}`;
|
|
135
|
+
break;
|
|
136
|
+
}
|
|
137
|
+
case "evidence_filtered":
|
|
138
|
+
cause = `No results: ${miss.threshold_candidates} candidates passed the score threshold, but none had enough lexical evidence.${attemptSuffix}`;
|
|
139
|
+
break;
|
|
140
|
+
case "metadata_filtered":
|
|
141
|
+
cause = `No results: ${miss.eligible_candidates} eligible candidates matched the query, but none matched ${compactFilter(miss)}.`;
|
|
142
|
+
break;
|
|
143
|
+
case "reranker_empty":
|
|
144
|
+
cause = `No results: ${miss.filtered_candidates} candidates reached deep reranking, but the reranker returned none.`;
|
|
145
|
+
break;
|
|
146
|
+
case "page_out_of_range":
|
|
147
|
+
cause = `No results on this page: the requested offset exceeds ${miss.total_results} available results.`;
|
|
148
|
+
break;
|
|
149
|
+
case "no_match":
|
|
150
|
+
cause = `No results: candidates were processed but no result remained${scope}.${attemptSuffix}`;
|
|
151
|
+
break;
|
|
66
152
|
}
|
|
67
|
-
|
|
68
|
-
|
|
153
|
+
return `${cause}\n${SEARCH_MISS_ACTION_TEXT[miss.action]}`;
|
|
154
|
+
}
|
|
155
|
+
function formatSymbolMiss(miss) {
|
|
156
|
+
const scope = requestedKbSuffix(miss.requested_kb_id);
|
|
157
|
+
let cause;
|
|
158
|
+
switch (miss.reason) {
|
|
159
|
+
case "no_knowledge_bases":
|
|
160
|
+
cause = "No symbols found: no knowledge bases are indexed.";
|
|
161
|
+
break;
|
|
162
|
+
case "knowledge_base_not_found":
|
|
163
|
+
cause = `No symbols found: knowledge base ${inlineLabel(miss.requested_kb_id ?? "", "from the requested kb_id")} does not exist.`;
|
|
164
|
+
break;
|
|
165
|
+
case "no_searchable_knowledge_bases": {
|
|
166
|
+
const indexing = miss.skipped_kbs.find((kb) => kb.status === "indexing");
|
|
167
|
+
const errored = miss.skipped_kbs.find((kb) => kb.status === "error");
|
|
168
|
+
if (miss.action === "wait_for_indexing" && indexing) {
|
|
169
|
+
cause = `No symbols yet: ${inlineLabel(indexing.name, "the selected KB")} is still indexing (${indexing.chunk_count} chunks persisted).`;
|
|
170
|
+
}
|
|
171
|
+
else if (errored) {
|
|
172
|
+
cause = `No symbols found: ${inlineLabel(errored.name, "the selected KB")} is in error state and is not searchable.`;
|
|
173
|
+
}
|
|
174
|
+
else if (indexing) {
|
|
175
|
+
cause = `No symbols found: one or more selected knowledge bases are unavailable while ${inlineLabel(indexing.name, "one KB")} indexes.`;
|
|
176
|
+
}
|
|
177
|
+
else {
|
|
178
|
+
cause = "No symbols found: no selected knowledge base is currently searchable.";
|
|
179
|
+
}
|
|
180
|
+
break;
|
|
181
|
+
}
|
|
182
|
+
case "symbol_index_empty":
|
|
183
|
+
cause = `No symbols are indexed${scope}.`;
|
|
184
|
+
break;
|
|
185
|
+
case "exact_name_not_found":
|
|
186
|
+
cause = `No symbol matched the exact normalized name${scope}.`;
|
|
187
|
+
break;
|
|
188
|
+
case "metadata_filtered":
|
|
189
|
+
cause = `No symbols matched the requested kind or file_pattern${scope}; ${miss.unfiltered_matches} unfiltered matches exist.`;
|
|
190
|
+
break;
|
|
191
|
+
case "page_out_of_range":
|
|
192
|
+
cause = "No symbols on this page: the requested offset exceeds the available matches.";
|
|
193
|
+
break;
|
|
194
|
+
case "no_match":
|
|
195
|
+
cause = `No indexed symbol matched${scope}.`;
|
|
196
|
+
break;
|
|
69
197
|
}
|
|
198
|
+
return `${cause}\n${SYMBOL_MISS_ACTION_TEXT[miss.action]}`;
|
|
70
199
|
}
|
|
71
200
|
function runtimeModule(modulePath) {
|
|
72
201
|
return `${modulePath}${RUNTIME_EXTENSION}`;
|
|
73
202
|
}
|
|
74
|
-
async function
|
|
75
|
-
if (
|
|
76
|
-
await
|
|
77
|
-
if (
|
|
78
|
-
return
|
|
79
|
-
|
|
80
|
-
import(__rewriteRelativeImportExtension(runtimeModule("./src/
|
|
81
|
-
import(__rewriteRelativeImportExtension(runtimeModule("./src/
|
|
82
|
-
|
|
83
|
-
]).then(([engineModule, storage, watcher]) => {
|
|
84
|
-
runtime = { engine: new engineModule.KnowledgeEngine(), storage, watcher };
|
|
85
|
-
return runtime;
|
|
86
|
-
});
|
|
87
|
-
return runtimePromise;
|
|
88
|
-
}
|
|
89
|
-
async function ensureInitialized() {
|
|
90
|
-
if (disposePromise)
|
|
91
|
-
await disposePromise;
|
|
92
|
-
if (initialized && runtime)
|
|
93
|
-
return runtime;
|
|
94
|
-
initializePromise ??= (async () => {
|
|
95
|
-
const loaded = await loadRuntime();
|
|
96
|
-
await loaded.engine.initialize(loaded.storage.getDefaultKnowledgeDir());
|
|
97
|
-
initialized = true;
|
|
98
|
-
return loaded;
|
|
99
|
-
})();
|
|
203
|
+
async function ensureClient() {
|
|
204
|
+
if (releaseClientPromise)
|
|
205
|
+
await releaseClientPromise;
|
|
206
|
+
if (daemonClient)
|
|
207
|
+
return daemonClient;
|
|
208
|
+
ensureClientPromise ??= Promise.all([
|
|
209
|
+
import(__rewriteRelativeImportExtension(runtimeModule("./src/daemon/client"))),
|
|
210
|
+
import(__rewriteRelativeImportExtension(runtimeModule("./src/profiles"))),
|
|
211
|
+
]).then(([clientModule, profileModule]) => clientModule.ensureDaemonClient(profileModule.resolveKnowledgeProfile()));
|
|
100
212
|
try {
|
|
101
|
-
|
|
213
|
+
daemonClient = await ensureClientPromise;
|
|
214
|
+
return daemonClient;
|
|
102
215
|
}
|
|
103
216
|
catch (error) {
|
|
104
|
-
|
|
217
|
+
ensureClientPromise = undefined;
|
|
105
218
|
throw error;
|
|
106
219
|
}
|
|
107
220
|
}
|
|
108
|
-
async function
|
|
109
|
-
if (
|
|
110
|
-
return
|
|
111
|
-
|
|
112
|
-
const
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
if (!loaded && pendingInitialize) {
|
|
221
|
+
async function releaseClient() {
|
|
222
|
+
if (releaseClientPromise)
|
|
223
|
+
return releaseClientPromise;
|
|
224
|
+
clientGeneration++;
|
|
225
|
+
const pending = ensureClientPromise;
|
|
226
|
+
releaseClientPromise = (async () => {
|
|
227
|
+
if (pending) {
|
|
116
228
|
try {
|
|
117
|
-
|
|
229
|
+
await pending;
|
|
118
230
|
}
|
|
119
231
|
catch {
|
|
120
|
-
|
|
232
|
+
// Startup errors are reported by the caller that initiated startup.
|
|
121
233
|
}
|
|
122
234
|
}
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
}
|
|
127
|
-
catch {
|
|
128
|
-
loaded = runtime;
|
|
129
|
-
}
|
|
130
|
-
}
|
|
131
|
-
initialized = false;
|
|
132
|
-
initializePromise = undefined;
|
|
133
|
-
runtime = undefined;
|
|
134
|
-
runtimePromise = undefined;
|
|
135
|
-
if (!loaded)
|
|
136
|
-
return;
|
|
137
|
-
loaded.watcher.stopAllWatchers();
|
|
138
|
-
await loaded.engine.dispose({ disposeModels: false });
|
|
235
|
+
daemonClient = undefined;
|
|
236
|
+
if (ensureClientPromise === pending)
|
|
237
|
+
ensureClientPromise = undefined;
|
|
139
238
|
})();
|
|
140
239
|
try {
|
|
141
|
-
await
|
|
240
|
+
await releaseClientPromise;
|
|
142
241
|
}
|
|
143
242
|
finally {
|
|
144
|
-
|
|
243
|
+
releaseClientPromise = undefined;
|
|
145
244
|
}
|
|
146
245
|
}
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
}
|
|
246
|
+
async function configureClient(nodePath, signal) {
|
|
247
|
+
let client;
|
|
248
|
+
try {
|
|
249
|
+
client = await ensureClient();
|
|
250
|
+
}
|
|
251
|
+
catch (error) {
|
|
252
|
+
if (signal?.aborted)
|
|
253
|
+
throw new Error("Cancelled");
|
|
254
|
+
if (!nodePath) {
|
|
255
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
256
|
+
throw new Error(`Unable to start the profile daemon for automatic Node discovery: ${reason}. Pass an explicit absolute Node 22+ path to bootstrap the profile.`);
|
|
257
|
+
}
|
|
258
|
+
const generation = clientGeneration;
|
|
259
|
+
const [clientModule, profileModule] = await Promise.all([
|
|
260
|
+
import(__rewriteRelativeImportExtension(runtimeModule("./src/daemon/client"))),
|
|
261
|
+
import(__rewriteRelativeImportExtension(runtimeModule("./src/profiles"))),
|
|
262
|
+
]);
|
|
263
|
+
if (signal?.aborted)
|
|
264
|
+
throw new Error("Cancelled");
|
|
265
|
+
if (generation !== clientGeneration || releaseClientPromise) {
|
|
266
|
+
throw new Error("Knowledge client session is shutting down");
|
|
267
|
+
}
|
|
268
|
+
const bootstrap = clientModule.configureAndEnsureDaemonClient(profileModule.resolveKnowledgeProfile(), nodePath, signal);
|
|
269
|
+
ensureClientPromise = bootstrap;
|
|
270
|
+
try {
|
|
271
|
+
client = await bootstrap;
|
|
272
|
+
}
|
|
273
|
+
catch (bootstrapError) {
|
|
274
|
+
if (ensureClientPromise === bootstrap)
|
|
275
|
+
ensureClientPromise = undefined;
|
|
276
|
+
throw bootstrapError;
|
|
158
277
|
}
|
|
278
|
+
if (generation !== clientGeneration)
|
|
279
|
+
throw new Error("Knowledge client session was released");
|
|
280
|
+
if (ensureClientPromise === bootstrap)
|
|
281
|
+
daemonClient = client;
|
|
282
|
+
}
|
|
283
|
+
return client.configure(nodePath, signal);
|
|
284
|
+
}
|
|
285
|
+
function registerKnowledgeExtension(pi) {
|
|
286
|
+
pi.on("session_start", async () => {
|
|
287
|
+
const client = await ensureClient();
|
|
288
|
+
if (WATCH_ENABLED)
|
|
289
|
+
await client.enableWatchers();
|
|
159
290
|
});
|
|
160
291
|
pi.on("session_shutdown", async () => {
|
|
161
|
-
await
|
|
292
|
+
await releaseClient();
|
|
162
293
|
});
|
|
163
294
|
// Auto-inject: search KB for relevant context before each LLM call (opt-in)
|
|
164
295
|
if (AUTO_INJECT) {
|
|
165
296
|
pi.on("context", async (event) => {
|
|
166
297
|
try {
|
|
167
|
-
const
|
|
168
|
-
const kbs =
|
|
298
|
+
const client = await ensureClient();
|
|
299
|
+
const kbs = await client.list();
|
|
169
300
|
if (kbs.length === 0)
|
|
170
301
|
return;
|
|
171
|
-
|
|
172
|
-
const lastUser = [...event.messages].reverse().find((m) => m.role === "user");
|
|
302
|
+
const lastUser = [...event.messages].reverse().find((message) => message.role === "user");
|
|
173
303
|
if (!lastUser)
|
|
174
304
|
return;
|
|
175
305
|
const text = "content" in lastUser && typeof lastUser.content === "string" ? lastUser.content : "";
|
|
176
306
|
if (!text || text.length < 5)
|
|
177
307
|
return;
|
|
178
|
-
const results = await
|
|
308
|
+
const results = await client.search(text, { mode: "fast", limit: 3 });
|
|
179
309
|
if (results.results.length === 0)
|
|
180
310
|
return;
|
|
181
|
-
const context = results.results.map((
|
|
311
|
+
const context = results.results.map((result) => `[${result.file_path}]: ${result.snippet}`).join("\n\n");
|
|
182
312
|
return {
|
|
183
313
|
messages: [{ role: "user", content: `[Knowledge context]\n${context}` }, ...event.messages],
|
|
184
314
|
};
|
|
185
315
|
}
|
|
186
316
|
catch {
|
|
187
|
-
|
|
317
|
+
// Auto-injection must not prevent an agent turn when the daemon is unavailable.
|
|
188
318
|
}
|
|
189
319
|
});
|
|
190
320
|
}
|
|
191
321
|
pi.on("before_agent_start", async (event) => {
|
|
192
|
-
const
|
|
193
|
-
const kbs =
|
|
322
|
+
const client = await ensureClient();
|
|
323
|
+
const kbs = await client.list();
|
|
194
324
|
if (kbs.length === 0)
|
|
195
325
|
return undefined;
|
|
196
|
-
const
|
|
197
|
-
const guidance = `Available knowledge bases: ${desc}. Use knowledge_symbol_search for exact symbols/config keys/env vars/routes/headings, then use knowledge_search for broader domain or implementation context.`;
|
|
326
|
+
const guidance = `${kbs.length} knowledge base${kbs.length === 1 ? " is" : "s are"} available. Use knowledge_show to inspect their untrusted labels, knowledge_symbol_search for exact symbols/config keys/env vars/routes/headings, then knowledge_search for broader domain or implementation context.`;
|
|
198
327
|
return {
|
|
199
328
|
systemPrompt: `${event.systemPrompt}\n\n${guidance}`,
|
|
200
329
|
};
|
|
@@ -221,10 +350,10 @@ export default function (pi) {
|
|
|
221
350
|
}))),
|
|
222
351
|
exclude_paths: Type.Optional(Type.Array(Type.String({ description: "Relative paths under a directory source to exclude from this plan" }))),
|
|
223
352
|
}),
|
|
224
|
-
async execute(_id, params, _signal) {
|
|
225
|
-
const
|
|
353
|
+
async execute(_id, params, _signal, _onUpdate, ctx) {
|
|
354
|
+
const client = await ensureClient();
|
|
226
355
|
const { source, include_suggested_text, include_paths, exclude_paths } = params;
|
|
227
|
-
const plan =
|
|
356
|
+
const plan = await client.plan(source, {
|
|
228
357
|
include_suggested_text: include_suggested_text === true,
|
|
229
358
|
include_paths: Array.isArray(include_paths)
|
|
230
359
|
? include_paths.filter((item) => typeof item === "string")
|
|
@@ -232,7 +361,7 @@ export default function (pi) {
|
|
|
232
361
|
exclude_paths: Array.isArray(exclude_paths)
|
|
233
362
|
? exclude_paths.filter((item) => typeof item === "string")
|
|
234
363
|
: undefined,
|
|
235
|
-
}, _signal);
|
|
364
|
+
}, _signal, ctx?.filesystemAccess);
|
|
236
365
|
const samples = plan.skipped.samples
|
|
237
366
|
.map((sample) => `- ${sample.reason}: ${sample.path}${sample.size ? ` (${sample.size} bytes)` : ""}`)
|
|
238
367
|
.join("\n");
|
|
@@ -260,7 +389,7 @@ export default function (pi) {
|
|
|
260
389
|
promptGuidelines: [
|
|
261
390
|
"Use knowledge_configure when knowledge_doctor or knowledge_add reports that local embeddings cannot find a usable Node executable",
|
|
262
391
|
"On Windows, pass the full node.exe path when the user provides one; paths with spaces are accepted",
|
|
263
|
-
"If node_path is omitted,
|
|
392
|
+
"If node_path is omitted, a running daemon auto-discovers and persists Node; a fresh profile whose host cannot start Node requires an explicit absolute Node 22+ path for bootstrap",
|
|
264
393
|
"Do not switch users to API embeddings unless they explicitly choose a network embedding provider",
|
|
265
394
|
],
|
|
266
395
|
parameters: Type.Object({
|
|
@@ -269,21 +398,18 @@ export default function (pi) {
|
|
|
269
398
|
})),
|
|
270
399
|
}),
|
|
271
400
|
async execute(_id, params, _signal) {
|
|
272
|
-
if (_signal?.aborted)
|
|
273
|
-
throw new Error("Cancelled");
|
|
274
|
-
const { configureModelWorkerNodePath } = await import(__rewriteRelativeImportExtension(runtimeModule("./src/model-worker-client")));
|
|
275
401
|
if (_signal?.aborted)
|
|
276
402
|
throw new Error("Cancelled");
|
|
277
403
|
const nodePath = typeof params.node_path === "string" && params.node_path.trim() ? params.node_path : undefined;
|
|
278
|
-
const
|
|
404
|
+
const configured = await configureClient(nodePath, _signal);
|
|
279
405
|
return {
|
|
280
406
|
content: [
|
|
281
407
|
{
|
|
282
408
|
type: "text",
|
|
283
|
-
text: `Configured isolated worker Node executable: ${
|
|
409
|
+
text: `Configured isolated worker Node executable: ${configured.node_path}`,
|
|
284
410
|
},
|
|
285
411
|
],
|
|
286
|
-
details:
|
|
412
|
+
details: configured,
|
|
287
413
|
};
|
|
288
414
|
},
|
|
289
415
|
});
|
|
@@ -318,11 +444,11 @@ export default function (pi) {
|
|
|
318
444
|
}))),
|
|
319
445
|
exclude_paths: Type.Optional(Type.Array(Type.String({ description: "Relative paths under a directory source to exclude from this KB" }))),
|
|
320
446
|
}),
|
|
321
|
-
async execute(_id, params, _signal, onUpdate) {
|
|
322
|
-
const
|
|
447
|
+
async execute(_id, params, _signal, onUpdate, ctx) {
|
|
448
|
+
const client = await ensureClient();
|
|
323
449
|
const { source, name, include_suggested_text, include_paths, exclude_paths } = params;
|
|
324
|
-
const { kb, chunkCount } = await
|
|
325
|
-
onUpdate?.({ content: [{ type: "text", text:
|
|
450
|
+
const { kb, chunkCount } = await client.add(source, name, (message) => {
|
|
451
|
+
onUpdate?.({ content: [{ type: "text", text: message }] });
|
|
326
452
|
}, _signal, {
|
|
327
453
|
include_suggested_text: include_suggested_text === true,
|
|
328
454
|
include_paths: Array.isArray(include_paths)
|
|
@@ -331,21 +457,7 @@ export default function (pi) {
|
|
|
331
457
|
exclude_paths: Array.isArray(exclude_paths)
|
|
332
458
|
? exclude_paths.filter((item) => typeof item === "string")
|
|
333
459
|
: undefined,
|
|
334
|
-
});
|
|
335
|
-
// Start watcher for new directory KB
|
|
336
|
-
if (WATCH_ENABLED && kb.source_path && kb.source_type === "directory") {
|
|
337
|
-
watcher.startWatcher(kb.id, kb.source_path, (kbId) => {
|
|
338
|
-
engine.update(kbId).catch(() => { });
|
|
339
|
-
}, {
|
|
340
|
-
includeSuggestedText: include_suggested_text === true,
|
|
341
|
-
includePaths: Array.isArray(include_paths)
|
|
342
|
-
? include_paths.filter((item) => typeof item === "string")
|
|
343
|
-
: undefined,
|
|
344
|
-
excludePaths: Array.isArray(exclude_paths)
|
|
345
|
-
? exclude_paths.filter((item) => typeof item === "string")
|
|
346
|
-
: undefined,
|
|
347
|
-
});
|
|
348
|
-
}
|
|
460
|
+
}, ctx?.filesystemAccess);
|
|
349
461
|
return {
|
|
350
462
|
content: [
|
|
351
463
|
{
|
|
@@ -370,7 +482,7 @@ export default function (pi) {
|
|
|
370
482
|
"Use mode 'adaptive' when the user needs surrounding implementation context, related nearby sections, or enough context to make a code change",
|
|
371
483
|
"Use mode 'deep' for high-stakes answers, ambiguous top results, or final verification where slower cross-encoder reranking is acceptable",
|
|
372
484
|
"Use profile 'low_token' for slow local models that need fewer, stricter, longer snippets; use profile 'precision' for identifiers/errors and 'recall' or 'long_context' for broad prose/document research",
|
|
373
|
-
"If a search returns no results
|
|
485
|
+
"If a search returns no results, follow its classified action; do not repeat modes listed in the auto attempt summary",
|
|
374
486
|
"If top results are repetitive, retry with diversity 'strong' or mode 'adaptive' instead of increasing the limit first",
|
|
375
487
|
],
|
|
376
488
|
parameters: Type.Object({
|
|
@@ -418,24 +530,14 @@ export default function (pi) {
|
|
|
418
530
|
diagnostics: Type.Optional(Type.Boolean({ description: "Include ranking diagnostics and mode/fallback details in the result" })),
|
|
419
531
|
}),
|
|
420
532
|
async execute(_id, params, _signal) {
|
|
421
|
-
const
|
|
533
|
+
const client = await ensureClient();
|
|
422
534
|
const { query, mode, profile, limit, kb_id, offset, file_type, path_pattern, diversity, diagnostics } = params;
|
|
423
535
|
const filters = file_type || path_pattern ? { file_type, path_pattern } : undefined;
|
|
424
|
-
const response = await
|
|
536
|
+
const response = await client.search(query, { mode, profile, limit, kb_id, offset, filters, diversity }, _signal);
|
|
425
537
|
if (response.results.length === 0) {
|
|
426
|
-
|
|
427
|
-
"
|
|
428
|
-
|
|
429
|
-
response.retry_modes?.length ? `Retried: ${response.retry_modes.join(", ")}` : "",
|
|
430
|
-
response.warnings?.length ? `Warnings: ${response.warnings.join(" | ")}` : "",
|
|
431
|
-
diagnostics && response.tuning
|
|
432
|
-
? `Tuning: profile=${response.tuning.requested_profile}->${response.tuning.selected_profile}, limit=${response.tuning.limit}, snippet=${response.tuning.snippet_max_length}, min_hybrid=${response.tuning.min_hybrid_score}, candidates=${response.tuning.diversity_candidates}/${response.tuning.candidate_limit}, retrieval_per_kb=${response.tuning.retrieval_limit_per_kb}, retrieved=${response.tuning.retrieved_candidates}, filtered=${response.tuning.filtered_candidates}, truncated=${response.tuning.candidate_pool_truncated}`
|
|
433
|
-
: "",
|
|
434
|
-
response.suggestions?.length ? `Suggestions: ${response.suggestions.join(" | ")}` : "",
|
|
435
|
-
]
|
|
436
|
-
.filter(Boolean)
|
|
437
|
-
.join("\n");
|
|
438
|
-
return { content: [{ type: "text", text: details }], details: diagnostics ? response : undefined };
|
|
538
|
+
if (!response.miss)
|
|
539
|
+
throw new Error("Search returned no results without a miss classification");
|
|
540
|
+
return { content: [{ type: "text", text: formatSearchMiss(response.miss) }], details: response };
|
|
439
541
|
}
|
|
440
542
|
let output = `${response.total_count} results (showing ${response.results.length})`;
|
|
441
543
|
if (response.mode_used)
|
|
@@ -458,7 +560,7 @@ export default function (pi) {
|
|
|
458
560
|
? `\nProvenance: chunk=${r.provenance.chunk_id}, hash=${r.provenance.chunk_hash.slice(0, 12)}, reason=${r.provenance.match_reason}, indexed_at=${r.provenance.indexed_at}, source_mtime=${r.provenance.source_mtime ?? "unknown"}, stale=${r.provenance.stale}`
|
|
459
561
|
: "";
|
|
460
562
|
const tuning = diagnostics && response.tuning && i === 0
|
|
461
|
-
? `\nTuning: limit=${response.tuning.limit}, snippet=${response.tuning.snippet_max_length}, min_hybrid=${response.tuning.min_hybrid_score}, candidates=${response.tuning.diversity_candidates}/${response.tuning.candidate_limit}, retrieval_per_kb=${response.tuning.retrieval_limit_per_kb}, retrieved=${response.tuning.retrieved_candidates},
|
|
563
|
+
? `\nTuning: limit=${response.tuning.limit}, snippet=${response.tuning.snippet_max_length}, min_hybrid=${response.tuning.min_hybrid_score}, candidates=${response.tuning.diversity_candidates}/${response.tuning.candidate_limit}, retrieval_per_kb=${response.tuning.retrieval_limit_per_kb}, retrieved=${response.tuning.retrieved_candidates}, threshold=${response.tuning.threshold_candidates}, eligible=${response.tuning.eligible_candidates}, metadata=${response.tuning.filtered_candidates}, truncated=${response.tuning.candidate_pool_truncated}`
|
|
462
564
|
: "";
|
|
463
565
|
return `[${i + 1}] ${r.file_path} (${r.kb_name}, score: ${r.score.toFixed(3)})\n${r.snippet}${diag}${provenance}${tuning}`;
|
|
464
566
|
})
|
|
@@ -475,7 +577,7 @@ export default function (pi) {
|
|
|
475
577
|
promptGuidelines: [
|
|
476
578
|
"Use knowledge_symbol_search before knowledge_search when looking for a function, class, env var, config key, route, or Markdown heading",
|
|
477
579
|
"Use exact=true when the user provides a precise symbol or key",
|
|
478
|
-
"This is a lightweight declaration-pattern index, not full LSP;
|
|
580
|
+
"This is a lightweight declaration-pattern index, not full LSP; on a miss, follow its classified action and use knowledge_search mode 'fast' or 'adaptive' only when directed to source text",
|
|
479
581
|
"After finding a symbol, use knowledge_search mode 'adaptive' with the file path or symbol name when surrounding implementation context is needed",
|
|
480
582
|
],
|
|
481
583
|
parameters: Type.Object({
|
|
@@ -500,10 +602,10 @@ export default function (pi) {
|
|
|
500
602
|
async execute(_id, params, _signal) {
|
|
501
603
|
if (_signal?.aborted)
|
|
502
604
|
throw new Error("Cancelled");
|
|
503
|
-
const
|
|
605
|
+
const client = await ensureClient();
|
|
504
606
|
if (_signal?.aborted)
|
|
505
607
|
throw new Error("Cancelled");
|
|
506
|
-
const response =
|
|
608
|
+
const response = await client.symbolSearch(params.query, {
|
|
507
609
|
kind: params.kind,
|
|
508
610
|
kb_id: params.kb_id,
|
|
509
611
|
file_pattern: params.file_pattern,
|
|
@@ -512,14 +614,9 @@ export default function (pi) {
|
|
|
512
614
|
exact: params.exact === true,
|
|
513
615
|
}, _signal);
|
|
514
616
|
if (response.results.length === 0) {
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
type: "text",
|
|
519
|
-
text: "No symbols found. This may mean the symbol is absent, symbol metadata is missing/stale, or the lightweight extractor does not cover this syntax. For important lookups, run knowledge_doctor or fallback to knowledge_search mode 'fast'/'adaptive'.",
|
|
520
|
-
},
|
|
521
|
-
],
|
|
522
|
-
};
|
|
617
|
+
if (!response.miss)
|
|
618
|
+
throw new Error("Symbol search returned no results without a miss classification");
|
|
619
|
+
return { content: [{ type: "text", text: formatSymbolMiss(response.miss) }], details: response };
|
|
523
620
|
}
|
|
524
621
|
const lines = response.results.map((result, index) => {
|
|
525
622
|
const signature = result.signature ? ` — ${result.signature}` : "";
|
|
@@ -545,11 +642,11 @@ export default function (pi) {
|
|
|
545
642
|
parameters: Type.Object({
|
|
546
643
|
target: Type.String({ description: "KB name or ID to update" }),
|
|
547
644
|
}),
|
|
548
|
-
async execute(_id, params, _signal, onUpdate) {
|
|
549
|
-
const
|
|
550
|
-
const { added, removed, unchanged } = await
|
|
645
|
+
async execute(_id, params, _signal, onUpdate, ctx) {
|
|
646
|
+
const client = await ensureClient();
|
|
647
|
+
const { added, removed, unchanged } = await client.update(params.target, (msg) => {
|
|
551
648
|
onUpdate?.({ content: [{ type: "text", text: msg }] });
|
|
552
|
-
}, _signal);
|
|
649
|
+
}, _signal, ctx?.filesystemAccess);
|
|
553
650
|
return {
|
|
554
651
|
content: [{ type: "text", text: `Updated: +${added} added, -${removed} removed, ${unchanged} unchanged.` }],
|
|
555
652
|
};
|
|
@@ -564,17 +661,22 @@ export default function (pi) {
|
|
|
564
661
|
async execute(_id, _params, _signal) {
|
|
565
662
|
if (_signal?.aborted)
|
|
566
663
|
throw new Error("Cancelled");
|
|
567
|
-
const
|
|
568
|
-
const
|
|
664
|
+
const client = await ensureClient();
|
|
665
|
+
const [status, ping] = await Promise.all([client.status(_signal), client.ping(_signal)]);
|
|
569
666
|
return {
|
|
570
667
|
content: [
|
|
571
668
|
{
|
|
572
669
|
type: "text",
|
|
573
|
-
text:
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
670
|
+
text: [
|
|
671
|
+
`Profile: ${status.profile.name} (${status.profile.id})`,
|
|
672
|
+
`Daemon: instance ${ping.instance_id}, protocol ${ping.protocol_version}, pid ${ping.pid}`,
|
|
673
|
+
...(status.snapshot_error ? [`Coverage snapshot: ⚠️ ${status.snapshot_error}`] : []),
|
|
674
|
+
formatKnowledgeStatus({
|
|
675
|
+
snapshot: status.snapshot,
|
|
676
|
+
storagePath: status.storage_path,
|
|
677
|
+
watchCount: status.watch_count,
|
|
678
|
+
}),
|
|
679
|
+
].join("\n"),
|
|
578
680
|
},
|
|
579
681
|
],
|
|
580
682
|
};
|
|
@@ -590,8 +692,8 @@ export default function (pi) {
|
|
|
590
692
|
async execute(_id, _params, _signal) {
|
|
591
693
|
if (_signal?.aborted)
|
|
592
694
|
throw new Error("Cancelled");
|
|
593
|
-
const
|
|
594
|
-
const report =
|
|
695
|
+
const client = await ensureClient();
|
|
696
|
+
const report = await client.doctor(_signal);
|
|
595
697
|
const lines = [`Health score: ${report.health_score}/100`, report.summary, ""];
|
|
596
698
|
if (report.issues.length === 0) {
|
|
597
699
|
lines.push("No issues found.");
|
|
@@ -615,10 +717,10 @@ export default function (pi) {
|
|
|
615
717
|
async execute(_id, _params, _signal) {
|
|
616
718
|
if (_signal?.aborted)
|
|
617
719
|
throw new Error("Cancelled");
|
|
618
|
-
const
|
|
720
|
+
const client = await ensureClient();
|
|
619
721
|
if (_signal?.aborted)
|
|
620
722
|
throw new Error("Cancelled");
|
|
621
|
-
const kbs =
|
|
723
|
+
const kbs = await client.list(_signal);
|
|
622
724
|
if (kbs.length === 0)
|
|
623
725
|
return { content: [{ type: "text", text: "No knowledge bases." }] };
|
|
624
726
|
const lines = kbs.map((kb) => `• ${kb.name} — ${kb.chunk_count} chunks, ${kb.file_count} files (${kb.status})`);
|
|
@@ -647,8 +749,8 @@ export default function (pi) {
|
|
|
647
749
|
const { target, confirm } = params;
|
|
648
750
|
if (confirm !== true)
|
|
649
751
|
throw new Error("Confirmation required: pass confirm=true for destructive removal");
|
|
650
|
-
const
|
|
651
|
-
const ok =
|
|
752
|
+
const client = await ensureClient();
|
|
753
|
+
const ok = await client.remove(target, _signal);
|
|
652
754
|
return { content: [{ type: "text", text: ok ? "Removed." : "Not found." }] };
|
|
653
755
|
},
|
|
654
756
|
});
|
|
@@ -661,12 +763,12 @@ export default function (pi) {
|
|
|
661
763
|
target: Type.String({ description: "KB name or ID to export" }),
|
|
662
764
|
output: Type.String({ description: "Output file path (.jsonl)" }),
|
|
663
765
|
}),
|
|
664
|
-
async execute(_id, params, _signal, onUpdate) {
|
|
665
|
-
const
|
|
766
|
+
async execute(_id, params, _signal, onUpdate, ctx) {
|
|
767
|
+
const client = await ensureClient();
|
|
666
768
|
const { target, output } = params;
|
|
667
|
-
const count = await
|
|
668
|
-
onUpdate?.({ content: [{ type: "text", text:
|
|
669
|
-
});
|
|
769
|
+
const count = await client.exportKB(target, output, _signal, (message) => {
|
|
770
|
+
onUpdate?.({ content: [{ type: "text", text: message }] });
|
|
771
|
+
}, ctx?.filesystemAccess);
|
|
670
772
|
return { content: [{ type: "text", text: `Exported ${count} chunks to ${output}` }] };
|
|
671
773
|
},
|
|
672
774
|
});
|
|
@@ -678,11 +780,11 @@ export default function (pi) {
|
|
|
678
780
|
parameters: Type.Object({
|
|
679
781
|
input: Type.String({ description: "Input JSONL file path" }),
|
|
680
782
|
}),
|
|
681
|
-
async execute(_id, params, _signal, onUpdate) {
|
|
682
|
-
const
|
|
683
|
-
const { kb, chunkCount } = await
|
|
684
|
-
onUpdate?.({ content: [{ type: "text", text:
|
|
685
|
-
}, _signal);
|
|
783
|
+
async execute(_id, params, _signal, onUpdate, ctx) {
|
|
784
|
+
const client = await ensureClient();
|
|
785
|
+
const { kb, chunkCount } = await client.importKB(params.input, (message) => {
|
|
786
|
+
onUpdate?.({ content: [{ type: "text", text: message }] });
|
|
787
|
+
}, _signal, ctx?.filesystemAccess);
|
|
686
788
|
return { content: [{ type: "text", text: `Imported "${kb.name}": ${chunkCount} chunks (re-embedded)` }] };
|
|
687
789
|
},
|
|
688
790
|
});
|
|
@@ -707,9 +809,20 @@ export default function (pi) {
|
|
|
707
809
|
if (params.confirm !== true) {
|
|
708
810
|
throw new Error("Confirmation required: pass confirm=true for destructive clear");
|
|
709
811
|
}
|
|
710
|
-
const
|
|
711
|
-
|
|
812
|
+
const client = await ensureClient();
|
|
813
|
+
await client.clear(_signal);
|
|
712
814
|
return { content: [{ type: "text", text: "All knowledge bases cleared." }] };
|
|
713
815
|
},
|
|
714
816
|
});
|
|
715
817
|
}
|
|
818
|
+
export function getKnowledgeToolDefinitions() {
|
|
819
|
+
const tools = [];
|
|
820
|
+
registerKnowledgeExtension({
|
|
821
|
+
on() { },
|
|
822
|
+
registerTool(tool) {
|
|
823
|
+
tools.push(tool);
|
|
824
|
+
},
|
|
825
|
+
});
|
|
826
|
+
return tools;
|
|
827
|
+
}
|
|
828
|
+
export default registerKnowledgeExtension;
|