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.
Files changed (63) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/README.md +63 -24
  3. package/dist/index.d.ts +10 -4
  4. package/dist/index.js +300 -187
  5. package/dist/src/coverage-snapshot.d.ts +23 -0
  6. package/dist/src/coverage-snapshot.js +53 -0
  7. package/dist/src/daemon/client.d.ts +60 -0
  8. package/dist/src/daemon/client.js +360 -0
  9. package/dist/src/daemon/main.d.ts +2 -0
  10. package/dist/src/daemon/main.js +109 -0
  11. package/dist/src/daemon/protocol.d.ts +71 -0
  12. package/dist/src/daemon/protocol.js +170 -0
  13. package/dist/src/daemon/runtime.d.ts +26 -0
  14. package/dist/src/daemon/runtime.js +192 -0
  15. package/dist/src/daemon/server.d.ts +46 -0
  16. package/dist/src/daemon/server.js +500 -0
  17. package/dist/src/daemon/service.d.ts +49 -0
  18. package/dist/src/daemon/service.js +527 -0
  19. package/dist/src/diagnostics/health.d.ts +6 -0
  20. package/dist/src/diagnostics/health.js +135 -2
  21. package/dist/src/engine.d.ts +63 -9
  22. package/dist/src/engine.js +959 -170
  23. package/dist/src/filesystem-access.d.ts +9 -0
  24. package/dist/src/filesystem-access.js +100 -0
  25. package/dist/src/indexer/chunker.d.ts +10 -0
  26. package/dist/src/indexer/chunker.js +284 -9
  27. package/dist/src/mcp/http.d.ts +47 -0
  28. package/dist/src/mcp/http.js +564 -0
  29. package/dist/src/mcp/main.d.ts +2 -0
  30. package/dist/src/mcp/main.js +97 -0
  31. package/dist/src/mcp/protocol.d.ts +81 -0
  32. package/dist/src/mcp/protocol.js +444 -0
  33. package/dist/src/mcp/server.d.ts +42 -0
  34. package/dist/src/mcp/server.js +378 -0
  35. package/dist/src/model-worker-client.js +9 -0
  36. package/dist/src/model-worker-contract.d.ts +3 -0
  37. package/dist/src/model-worker-contract.js +8 -0
  38. package/dist/src/model-worker.js +76 -4
  39. package/dist/src/network/safe-fetch.d.ts +7 -0
  40. package/dist/src/network/safe-fetch.js +199 -0
  41. package/dist/src/node-runtime.d.ts +3 -0
  42. package/dist/src/node-runtime.js +78 -0
  43. package/dist/src/profiles.d.ts +15 -0
  44. package/dist/src/profiles.js +160 -0
  45. package/dist/src/runtime-config.js +5 -6
  46. package/dist/src/search/tuning.d.ts +2 -0
  47. package/dist/src/search/tuning.js +2 -0
  48. package/dist/src/secure-files.d.ts +17 -0
  49. package/dist/src/secure-files.js +184 -0
  50. package/dist/src/status.js +12 -7
  51. package/dist/src/storage/sqlite.d.ts +4 -1
  52. package/dist/src/storage/sqlite.js +46 -3
  53. package/dist/src/type-guards.d.ts +1 -0
  54. package/dist/src/type-guards.js +3 -0
  55. package/dist/src/watcher/file-watcher.d.ts +3 -1
  56. package/dist/src/watcher/file-watcher.js +166 -32
  57. package/dist/src/windows-security.d.ts +4 -0
  58. package/dist/src/windows-security.js +47 -0
  59. package/docs/configuration.md +42 -10
  60. package/docs/daemon-profiles.md +302 -0
  61. package/docs/mcp-clients.md +266 -0
  62. package/docs/offline-mode.md +6 -6
  63. 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
- let runtime;
48
- let runtimePromise;
49
- let initializePromise;
50
- let initialized = false;
51
- let disposePromise;
52
- function scanOptionsFromSourceOptions(raw) {
53
- if (!raw)
54
- return {};
55
- try {
56
- const parsed = JSON.parse(raw);
57
- return {
58
- includeSuggestedText: parsed.include_suggested_text === true,
59
- includePaths: Array.isArray(parsed.include_paths)
60
- ? parsed.include_paths.filter((item) => typeof item === "string")
61
- : undefined,
62
- excludePaths: Array.isArray(parsed.exclude_paths)
63
- ? parsed.exclude_paths.filter((item) => typeof item === "string")
64
- : undefined,
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
- catch {
68
- return {};
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 loadRuntime() {
75
- if (disposePromise)
76
- await disposePromise;
77
- if (runtime)
78
- return runtime;
79
- runtimePromise ??= Promise.all([
80
- import(__rewriteRelativeImportExtension(runtimeModule("./src/engine"))),
81
- import(__rewriteRelativeImportExtension(runtimeModule("./src/storage/sqlite"))),
82
- import(__rewriteRelativeImportExtension(runtimeModule("./src/watcher/file-watcher"))),
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
- return await initializePromise;
213
+ daemonClient = await ensureClientPromise;
214
+ return daemonClient;
102
215
  }
103
216
  catch (error) {
104
- initializePromise = undefined;
217
+ ensureClientPromise = undefined;
105
218
  throw error;
106
219
  }
107
220
  }
108
- async function disposeRuntime() {
109
- if (disposePromise)
110
- return disposePromise;
111
- const pendingInitialize = initializePromise;
112
- const pendingRuntime = runtimePromise;
113
- disposePromise = (async () => {
114
- let loaded = runtime;
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
- loaded = await pendingInitialize;
229
+ await pending;
118
230
  }
119
231
  catch {
120
- loaded = runtime;
232
+ // Startup errors are reported by the caller that initiated startup.
121
233
  }
122
234
  }
123
- if (!loaded && pendingRuntime) {
124
- try {
125
- loaded = await pendingRuntime;
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 disposePromise;
240
+ await releaseClientPromise;
142
241
  }
143
242
  finally {
144
- disposePromise = undefined;
243
+ releaseClientPromise = undefined;
145
244
  }
146
245
  }
147
- export default function (pi) {
148
- pi.on("session_start", async () => {
149
- const { engine, watcher } = await ensureInitialized();
150
- if (WATCH_ENABLED) {
151
- for (const kb of engine.list()) {
152
- if (kb.source_path && kb.source_type === "directory") {
153
- watcher.startWatcher(kb.id, kb.source_path, (kbId) => {
154
- engine.update(kbId).catch(() => { });
155
- }, scanOptionsFromSourceOptions(kb.source_options));
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 disposeRuntime();
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 { engine } = await ensureInitialized();
168
- const kbs = engine.list();
298
+ const client = await ensureClient();
299
+ const kbs = await client.list();
169
300
  if (kbs.length === 0)
170
301
  return;
171
- // Find last user message
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 engine.search(text, { mode: "fast", limit: 3 });
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((r) => `[${r.file_path}]: ${r.snippet}`).join("\n\n");
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
- /* silent fail */
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 { engine } = await ensureInitialized();
193
- const kbs = engine.list();
322
+ const client = await ensureClient();
323
+ const kbs = await client.list();
194
324
  if (kbs.length === 0)
195
325
  return undefined;
196
- const desc = kbs.map((kb) => `"${kb.name}" (${kb.chunk_count} chunks, ${kb.file_count} files)`).join(", ");
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 { engine } = await ensureInitialized();
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 = engine.plan(source, {
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, the tool auto-discovers a usable Node 22+ executable and persists it for future sessions",
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 configuredPath = configureModelWorkerNodePath(nodePath);
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: ${configuredPath}`,
409
+ text: `Configured isolated worker Node executable: ${configured.node_path}`,
284
410
  },
285
411
  ],
286
- details: { node_path: configuredPath },
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 { engine, watcher } = await ensureInitialized();
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 engine.add(source, name, (msg) => {
325
- onUpdate?.({ content: [{ type: "text", text: msg }] });
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 or obviously weak results, retry once with a different mode before concluding the KB lacks the answer",
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 { engine } = await ensureInitialized();
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 engine.search(query, { mode, profile, limit, kb_id, offset, filters, diversity }, _signal);
536
+ const response = await client.search(query, { mode, profile, limit, kb_id, offset, filters, diversity }, _signal);
425
537
  if (response.results.length === 0) {
426
- const details = [
427
- "No results found.",
428
- response.mode_used ? `Mode used: ${response.mode_used}` : "",
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}, filtered=${response.tuning.filtered_candidates}, truncated=${response.tuning.candidate_pool_truncated}`
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; for methods, uncommon syntax, or missing symbols, fallback to knowledge_search mode 'fast' or 'adaptive'",
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 { engine } = await ensureInitialized();
605
+ const client = await ensureClient();
504
606
  if (_signal?.aborted)
505
607
  throw new Error("Cancelled");
506
- const response = engine.symbolSearch(params.query, {
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
- return {
516
- content: [
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 { engine } = await ensureInitialized();
550
- const { added, removed, unchanged } = await engine.update(params.target, (msg) => {
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 { engine, storage, watcher } = await ensureInitialized();
568
- const snapshot = engine.statusSnapshot(_signal);
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: formatKnowledgeStatus({
574
- snapshot,
575
- storagePath: storage.getDefaultKnowledgeDir(),
576
- watchCount: watcher.getActiveWatcherCount(),
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 { engine } = await ensureInitialized();
594
- const report = engine.doctor(_signal);
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 { engine } = await ensureInitialized();
720
+ const client = await ensureClient();
619
721
  if (_signal?.aborted)
620
722
  throw new Error("Cancelled");
621
- const kbs = engine.list(_signal);
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 { engine } = await ensureInitialized();
651
- const ok = engine.remove(target);
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 { engine } = await ensureInitialized();
766
+ async execute(_id, params, _signal, onUpdate, ctx) {
767
+ const client = await ensureClient();
666
768
  const { target, output } = params;
667
- const count = await engine.exportKB(target, output, _signal, (msg) => {
668
- onUpdate?.({ content: [{ type: "text", text: msg }] });
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 { engine } = await ensureInitialized();
683
- const { kb, chunkCount } = await engine.importKB(params.input, (msg) => {
684
- onUpdate?.({ content: [{ type: "text", text: msg }] });
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 { engine } = await ensureInitialized();
711
- engine.clear();
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;