pi-knowledge 0.15.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 (61) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +59 -22
  3. package/dist/index.d.ts +10 -4
  4. package/dist/index.js +145 -166
  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 +13 -8
  22. package/dist/src/engine.js +569 -100
  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/secure-files.d.ts +17 -0
  47. package/dist/src/secure-files.js +184 -0
  48. package/dist/src/status.js +12 -7
  49. package/dist/src/storage/sqlite.d.ts +4 -1
  50. package/dist/src/storage/sqlite.js +46 -3
  51. package/dist/src/type-guards.d.ts +1 -0
  52. package/dist/src/type-guards.js +3 -0
  53. package/dist/src/watcher/file-watcher.d.ts +3 -1
  54. package/dist/src/watcher/file-watcher.js +166 -32
  55. package/dist/src/windows-security.d.ts +4 -0
  56. package/dist/src/windows-security.js +47 -0
  57. package/docs/configuration.md +39 -9
  58. package/docs/daemon-profiles.md +302 -0
  59. package/docs/mcp-clients.md +266 -0
  60. package/docs/offline-mode.md +6 -6
  61. package/package.json +28 -2
package/dist/index.js CHANGED
@@ -41,33 +41,13 @@ 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
- };
66
- }
67
- catch {
68
- return {};
69
- }
70
- }
71
51
  const SEARCH_MISS_ACTION_TEXT = {
72
52
  add_knowledge_base: "Use knowledge_add to index a directory, file, URL, or text source.",
73
53
  fix_kb_id: "Fix kb_id or omit it to search all knowledge bases.",
@@ -220,130 +200,130 @@ function formatSymbolMiss(miss) {
220
200
  function runtimeModule(modulePath) {
221
201
  return `${modulePath}${RUNTIME_EXTENSION}`;
222
202
  }
223
- async function loadRuntime() {
224
- if (disposePromise)
225
- await disposePromise;
226
- if (runtime)
227
- return runtime;
228
- runtimePromise ??= Promise.all([
229
- import(__rewriteRelativeImportExtension(runtimeModule("./src/engine"))),
230
- import(__rewriteRelativeImportExtension(runtimeModule("./src/storage/sqlite"))),
231
- import(__rewriteRelativeImportExtension(runtimeModule("./src/watcher/file-watcher"))),
232
- ]).then(([engineModule, storage, watcher]) => {
233
- runtime = { engine: new engineModule.KnowledgeEngine(), storage, watcher };
234
- return runtime;
235
- });
236
- return runtimePromise;
237
- }
238
- async function ensureInitialized() {
239
- if (disposePromise)
240
- await disposePromise;
241
- if (initialized && runtime)
242
- return runtime;
243
- initializePromise ??= (async () => {
244
- const loaded = await loadRuntime();
245
- await loaded.engine.initialize(loaded.storage.getDefaultKnowledgeDir());
246
- initialized = true;
247
- return loaded;
248
- })();
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()));
249
212
  try {
250
- return await initializePromise;
213
+ daemonClient = await ensureClientPromise;
214
+ return daemonClient;
251
215
  }
252
216
  catch (error) {
253
- initializePromise = undefined;
217
+ ensureClientPromise = undefined;
254
218
  throw error;
255
219
  }
256
220
  }
257
- async function disposeRuntime() {
258
- if (disposePromise)
259
- return disposePromise;
260
- const pendingInitialize = initializePromise;
261
- const pendingRuntime = runtimePromise;
262
- disposePromise = (async () => {
263
- let loaded = runtime;
264
- if (!loaded && pendingInitialize) {
265
- try {
266
- loaded = await pendingInitialize;
267
- }
268
- catch {
269
- loaded = runtime;
270
- }
271
- }
272
- if (!loaded && pendingRuntime) {
221
+ async function releaseClient() {
222
+ if (releaseClientPromise)
223
+ return releaseClientPromise;
224
+ clientGeneration++;
225
+ const pending = ensureClientPromise;
226
+ releaseClientPromise = (async () => {
227
+ if (pending) {
273
228
  try {
274
- loaded = await pendingRuntime;
229
+ await pending;
275
230
  }
276
231
  catch {
277
- loaded = runtime;
232
+ // Startup errors are reported by the caller that initiated startup.
278
233
  }
279
234
  }
280
- initialized = false;
281
- initializePromise = undefined;
282
- runtime = undefined;
283
- runtimePromise = undefined;
284
- if (!loaded)
285
- return;
286
- loaded.watcher.stopAllWatchers();
287
- await loaded.engine.dispose({ disposeModels: false });
235
+ daemonClient = undefined;
236
+ if (ensureClientPromise === pending)
237
+ ensureClientPromise = undefined;
288
238
  })();
289
239
  try {
290
- await disposePromise;
240
+ await releaseClientPromise;
291
241
  }
292
242
  finally {
293
- disposePromise = undefined;
243
+ releaseClientPromise = undefined;
294
244
  }
295
245
  }
296
- export default function (pi) {
297
- pi.on("session_start", async () => {
298
- const { engine, watcher } = await ensureInitialized();
299
- if (WATCH_ENABLED) {
300
- for (const kb of engine.list()) {
301
- if (kb.source_path && kb.source_type === "directory") {
302
- watcher.startWatcher(kb.id, kb.source_path, (kbId) => {
303
- engine.update(kbId).catch(() => { });
304
- }, scanOptionsFromSourceOptions(kb.source_options));
305
- }
306
- }
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;
307
272
  }
273
+ catch (bootstrapError) {
274
+ if (ensureClientPromise === bootstrap)
275
+ ensureClientPromise = undefined;
276
+ throw bootstrapError;
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();
308
290
  });
309
291
  pi.on("session_shutdown", async () => {
310
- await disposeRuntime();
292
+ await releaseClient();
311
293
  });
312
294
  // Auto-inject: search KB for relevant context before each LLM call (opt-in)
313
295
  if (AUTO_INJECT) {
314
296
  pi.on("context", async (event) => {
315
297
  try {
316
- const { engine } = await ensureInitialized();
317
- const kbs = engine.list();
298
+ const client = await ensureClient();
299
+ const kbs = await client.list();
318
300
  if (kbs.length === 0)
319
301
  return;
320
- // Find last user message
321
- const lastUser = [...event.messages].reverse().find((m) => m.role === "user");
302
+ const lastUser = [...event.messages].reverse().find((message) => message.role === "user");
322
303
  if (!lastUser)
323
304
  return;
324
305
  const text = "content" in lastUser && typeof lastUser.content === "string" ? lastUser.content : "";
325
306
  if (!text || text.length < 5)
326
307
  return;
327
- const results = await engine.search(text, { mode: "fast", limit: 3 });
308
+ const results = await client.search(text, { mode: "fast", limit: 3 });
328
309
  if (results.results.length === 0)
329
310
  return;
330
- 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");
331
312
  return {
332
313
  messages: [{ role: "user", content: `[Knowledge context]\n${context}` }, ...event.messages],
333
314
  };
334
315
  }
335
316
  catch {
336
- /* silent fail */
317
+ // Auto-injection must not prevent an agent turn when the daemon is unavailable.
337
318
  }
338
319
  });
339
320
  }
340
321
  pi.on("before_agent_start", async (event) => {
341
- const { engine } = await ensureInitialized();
342
- const kbs = engine.list();
322
+ const client = await ensureClient();
323
+ const kbs = await client.list();
343
324
  if (kbs.length === 0)
344
325
  return undefined;
345
- const desc = kbs.map((kb) => `"${kb.name}" (${kb.chunk_count} chunks, ${kb.file_count} files)`).join(", ");
346
- 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.`;
347
327
  return {
348
328
  systemPrompt: `${event.systemPrompt}\n\n${guidance}`,
349
329
  };
@@ -370,10 +350,10 @@ export default function (pi) {
370
350
  }))),
371
351
  exclude_paths: Type.Optional(Type.Array(Type.String({ description: "Relative paths under a directory source to exclude from this plan" }))),
372
352
  }),
373
- async execute(_id, params, _signal) {
374
- const { engine } = await ensureInitialized();
353
+ async execute(_id, params, _signal, _onUpdate, ctx) {
354
+ const client = await ensureClient();
375
355
  const { source, include_suggested_text, include_paths, exclude_paths } = params;
376
- const plan = engine.plan(source, {
356
+ const plan = await client.plan(source, {
377
357
  include_suggested_text: include_suggested_text === true,
378
358
  include_paths: Array.isArray(include_paths)
379
359
  ? include_paths.filter((item) => typeof item === "string")
@@ -381,7 +361,7 @@ export default function (pi) {
381
361
  exclude_paths: Array.isArray(exclude_paths)
382
362
  ? exclude_paths.filter((item) => typeof item === "string")
383
363
  : undefined,
384
- }, _signal);
364
+ }, _signal, ctx?.filesystemAccess);
385
365
  const samples = plan.skipped.samples
386
366
  .map((sample) => `- ${sample.reason}: ${sample.path}${sample.size ? ` (${sample.size} bytes)` : ""}`)
387
367
  .join("\n");
@@ -409,7 +389,7 @@ export default function (pi) {
409
389
  promptGuidelines: [
410
390
  "Use knowledge_configure when knowledge_doctor or knowledge_add reports that local embeddings cannot find a usable Node executable",
411
391
  "On Windows, pass the full node.exe path when the user provides one; paths with spaces are accepted",
412
- "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",
413
393
  "Do not switch users to API embeddings unless they explicitly choose a network embedding provider",
414
394
  ],
415
395
  parameters: Type.Object({
@@ -418,21 +398,18 @@ export default function (pi) {
418
398
  })),
419
399
  }),
420
400
  async execute(_id, params, _signal) {
421
- if (_signal?.aborted)
422
- throw new Error("Cancelled");
423
- const { configureModelWorkerNodePath } = await import(__rewriteRelativeImportExtension(runtimeModule("./src/model-worker-client")));
424
401
  if (_signal?.aborted)
425
402
  throw new Error("Cancelled");
426
403
  const nodePath = typeof params.node_path === "string" && params.node_path.trim() ? params.node_path : undefined;
427
- const configuredPath = configureModelWorkerNodePath(nodePath);
404
+ const configured = await configureClient(nodePath, _signal);
428
405
  return {
429
406
  content: [
430
407
  {
431
408
  type: "text",
432
- text: `Configured isolated worker Node executable: ${configuredPath}`,
409
+ text: `Configured isolated worker Node executable: ${configured.node_path}`,
433
410
  },
434
411
  ],
435
- details: { node_path: configuredPath },
412
+ details: configured,
436
413
  };
437
414
  },
438
415
  });
@@ -467,11 +444,11 @@ export default function (pi) {
467
444
  }))),
468
445
  exclude_paths: Type.Optional(Type.Array(Type.String({ description: "Relative paths under a directory source to exclude from this KB" }))),
469
446
  }),
470
- async execute(_id, params, _signal, onUpdate) {
471
- const { engine, watcher } = await ensureInitialized();
447
+ async execute(_id, params, _signal, onUpdate, ctx) {
448
+ const client = await ensureClient();
472
449
  const { source, name, include_suggested_text, include_paths, exclude_paths } = params;
473
- const { kb, chunkCount } = await engine.add(source, name, (msg) => {
474
- onUpdate?.({ content: [{ type: "text", text: msg }] });
450
+ const { kb, chunkCount } = await client.add(source, name, (message) => {
451
+ onUpdate?.({ content: [{ type: "text", text: message }] });
475
452
  }, _signal, {
476
453
  include_suggested_text: include_suggested_text === true,
477
454
  include_paths: Array.isArray(include_paths)
@@ -480,21 +457,7 @@ export default function (pi) {
480
457
  exclude_paths: Array.isArray(exclude_paths)
481
458
  ? exclude_paths.filter((item) => typeof item === "string")
482
459
  : undefined,
483
- });
484
- // Start watcher for new directory KB
485
- if (WATCH_ENABLED && kb.source_path && kb.source_type === "directory") {
486
- watcher.startWatcher(kb.id, kb.source_path, (kbId) => {
487
- engine.update(kbId).catch(() => { });
488
- }, {
489
- includeSuggestedText: include_suggested_text === true,
490
- includePaths: Array.isArray(include_paths)
491
- ? include_paths.filter((item) => typeof item === "string")
492
- : undefined,
493
- excludePaths: Array.isArray(exclude_paths)
494
- ? exclude_paths.filter((item) => typeof item === "string")
495
- : undefined,
496
- });
497
- }
460
+ }, ctx?.filesystemAccess);
498
461
  return {
499
462
  content: [
500
463
  {
@@ -567,10 +530,10 @@ export default function (pi) {
567
530
  diagnostics: Type.Optional(Type.Boolean({ description: "Include ranking diagnostics and mode/fallback details in the result" })),
568
531
  }),
569
532
  async execute(_id, params, _signal) {
570
- const { engine } = await ensureInitialized();
533
+ const client = await ensureClient();
571
534
  const { query, mode, profile, limit, kb_id, offset, file_type, path_pattern, diversity, diagnostics } = params;
572
535
  const filters = file_type || path_pattern ? { file_type, path_pattern } : undefined;
573
- 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);
574
537
  if (response.results.length === 0) {
575
538
  if (!response.miss)
576
539
  throw new Error("Search returned no results without a miss classification");
@@ -639,10 +602,10 @@ export default function (pi) {
639
602
  async execute(_id, params, _signal) {
640
603
  if (_signal?.aborted)
641
604
  throw new Error("Cancelled");
642
- const { engine } = await ensureInitialized();
605
+ const client = await ensureClient();
643
606
  if (_signal?.aborted)
644
607
  throw new Error("Cancelled");
645
- const response = engine.symbolSearch(params.query, {
608
+ const response = await client.symbolSearch(params.query, {
646
609
  kind: params.kind,
647
610
  kb_id: params.kb_id,
648
611
  file_pattern: params.file_pattern,
@@ -679,11 +642,11 @@ export default function (pi) {
679
642
  parameters: Type.Object({
680
643
  target: Type.String({ description: "KB name or ID to update" }),
681
644
  }),
682
- async execute(_id, params, _signal, onUpdate) {
683
- const { engine } = await ensureInitialized();
684
- 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) => {
685
648
  onUpdate?.({ content: [{ type: "text", text: msg }] });
686
- }, _signal);
649
+ }, _signal, ctx?.filesystemAccess);
687
650
  return {
688
651
  content: [{ type: "text", text: `Updated: +${added} added, -${removed} removed, ${unchanged} unchanged.` }],
689
652
  };
@@ -698,17 +661,22 @@ export default function (pi) {
698
661
  async execute(_id, _params, _signal) {
699
662
  if (_signal?.aborted)
700
663
  throw new Error("Cancelled");
701
- const { engine, storage, watcher } = await ensureInitialized();
702
- const snapshot = engine.statusSnapshot(_signal);
664
+ const client = await ensureClient();
665
+ const [status, ping] = await Promise.all([client.status(_signal), client.ping(_signal)]);
703
666
  return {
704
667
  content: [
705
668
  {
706
669
  type: "text",
707
- text: formatKnowledgeStatus({
708
- snapshot,
709
- storagePath: storage.getDefaultKnowledgeDir(),
710
- watchCount: watcher.getActiveWatcherCount(),
711
- }),
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"),
712
680
  },
713
681
  ],
714
682
  };
@@ -724,8 +692,8 @@ export default function (pi) {
724
692
  async execute(_id, _params, _signal) {
725
693
  if (_signal?.aborted)
726
694
  throw new Error("Cancelled");
727
- const { engine } = await ensureInitialized();
728
- const report = engine.doctor(_signal);
695
+ const client = await ensureClient();
696
+ const report = await client.doctor(_signal);
729
697
  const lines = [`Health score: ${report.health_score}/100`, report.summary, ""];
730
698
  if (report.issues.length === 0) {
731
699
  lines.push("No issues found.");
@@ -749,10 +717,10 @@ export default function (pi) {
749
717
  async execute(_id, _params, _signal) {
750
718
  if (_signal?.aborted)
751
719
  throw new Error("Cancelled");
752
- const { engine } = await ensureInitialized();
720
+ const client = await ensureClient();
753
721
  if (_signal?.aborted)
754
722
  throw new Error("Cancelled");
755
- const kbs = engine.list(_signal);
723
+ const kbs = await client.list(_signal);
756
724
  if (kbs.length === 0)
757
725
  return { content: [{ type: "text", text: "No knowledge bases." }] };
758
726
  const lines = kbs.map((kb) => `• ${kb.name} — ${kb.chunk_count} chunks, ${kb.file_count} files (${kb.status})`);
@@ -781,8 +749,8 @@ export default function (pi) {
781
749
  const { target, confirm } = params;
782
750
  if (confirm !== true)
783
751
  throw new Error("Confirmation required: pass confirm=true for destructive removal");
784
- const { engine } = await ensureInitialized();
785
- const ok = engine.remove(target);
752
+ const client = await ensureClient();
753
+ const ok = await client.remove(target, _signal);
786
754
  return { content: [{ type: "text", text: ok ? "Removed." : "Not found." }] };
787
755
  },
788
756
  });
@@ -795,12 +763,12 @@ export default function (pi) {
795
763
  target: Type.String({ description: "KB name or ID to export" }),
796
764
  output: Type.String({ description: "Output file path (.jsonl)" }),
797
765
  }),
798
- async execute(_id, params, _signal, onUpdate) {
799
- const { engine } = await ensureInitialized();
766
+ async execute(_id, params, _signal, onUpdate, ctx) {
767
+ const client = await ensureClient();
800
768
  const { target, output } = params;
801
- const count = await engine.exportKB(target, output, _signal, (msg) => {
802
- onUpdate?.({ content: [{ type: "text", text: msg }] });
803
- });
769
+ const count = await client.exportKB(target, output, _signal, (message) => {
770
+ onUpdate?.({ content: [{ type: "text", text: message }] });
771
+ }, ctx?.filesystemAccess);
804
772
  return { content: [{ type: "text", text: `Exported ${count} chunks to ${output}` }] };
805
773
  },
806
774
  });
@@ -812,11 +780,11 @@ export default function (pi) {
812
780
  parameters: Type.Object({
813
781
  input: Type.String({ description: "Input JSONL file path" }),
814
782
  }),
815
- async execute(_id, params, _signal, onUpdate) {
816
- const { engine } = await ensureInitialized();
817
- const { kb, chunkCount } = await engine.importKB(params.input, (msg) => {
818
- onUpdate?.({ content: [{ type: "text", text: msg }] });
819
- }, _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);
820
788
  return { content: [{ type: "text", text: `Imported "${kb.name}": ${chunkCount} chunks (re-embedded)` }] };
821
789
  },
822
790
  });
@@ -841,9 +809,20 @@ export default function (pi) {
841
809
  if (params.confirm !== true) {
842
810
  throw new Error("Confirmation required: pass confirm=true for destructive clear");
843
811
  }
844
- const { engine } = await ensureInitialized();
845
- engine.clear();
812
+ const client = await ensureClient();
813
+ await client.clear(_signal);
846
814
  return { content: [{ type: "text", text: "All knowledge bases cleared." }] };
847
815
  },
848
816
  });
849
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;
@@ -0,0 +1,23 @@
1
+ import type { KnowledgeProfile } from "./profiles.ts";
2
+ import type { KnowledgeBase } from "./storage/sqlite.ts";
3
+ export interface CoverageSnapshotKnowledgeBase {
4
+ name: string;
5
+ source_type: KnowledgeBase["source_type"];
6
+ source_path: string | null;
7
+ exclude_paths: string[];
8
+ file_count: number;
9
+ chunk_count: number;
10
+ updated_at: number;
11
+ status: KnowledgeBase["status"];
12
+ }
13
+ export interface CoverageSnapshot {
14
+ schema_version: 1;
15
+ generated_at: number;
16
+ profile: string;
17
+ kbs: CoverageSnapshotKnowledgeBase[];
18
+ }
19
+ export type CoverageSnapshotWriter = (path: string, value: unknown) => void;
20
+ export declare function coverageSnapshotPath(profile: KnowledgeProfile): string;
21
+ export declare function buildCoverageSnapshot(profile: KnowledgeProfile, knowledgeBases: readonly KnowledgeBase[], generatedAt?: number): CoverageSnapshot;
22
+ export declare function writeCoverageSnapshot(profile: KnowledgeProfile, knowledgeBases: readonly KnowledgeBase[], writer?: CoverageSnapshotWriter): void;
23
+ export declare function boundedCoverageSnapshotError(error: unknown): string;
@@ -0,0 +1,53 @@
1
+ import { join } from "node:path";
2
+ import { writeJsonAtomic } from "./secure-files.js";
3
+ import { isObjectRecord } from "./type-guards.js";
4
+ export function coverageSnapshotPath(profile) {
5
+ return join(profile.storageDir, "coverage.json");
6
+ }
7
+ function excludePaths(sourceOptions) {
8
+ if (!sourceOptions)
9
+ return [];
10
+ try {
11
+ const parsed = JSON.parse(sourceOptions);
12
+ if (!isObjectRecord(parsed) || !Array.isArray(parsed.exclude_paths))
13
+ return [];
14
+ return parsed.exclude_paths.filter((value) => typeof value === "string");
15
+ }
16
+ catch {
17
+ return [];
18
+ }
19
+ }
20
+ function compareText(left, right) {
21
+ return left < right ? -1 : left > right ? 1 : 0;
22
+ }
23
+ function normalizeExcludePaths(paths) {
24
+ return paths.map((path) => path.replaceAll("\\", "/").replace(/^\/+/, "").replace(/\/+$/, "")).filter(Boolean);
25
+ }
26
+ export function buildCoverageSnapshot(profile, knowledgeBases, generatedAt = Date.now()) {
27
+ return {
28
+ schema_version: 1,
29
+ generated_at: generatedAt,
30
+ profile: profile.name,
31
+ kbs: [...knowledgeBases]
32
+ .sort((left, right) => compareText(left.name, right.name) || compareText(left.id, right.id))
33
+ .map((kb) => ({
34
+ name: kb.name,
35
+ source_type: kb.source_type,
36
+ source_path: kb.source_path,
37
+ exclude_paths: normalizeExcludePaths(excludePaths(kb.source_options)),
38
+ file_count: kb.file_count,
39
+ chunk_count: kb.chunk_count,
40
+ updated_at: kb.indexed_at,
41
+ status: kb.status,
42
+ })),
43
+ };
44
+ }
45
+ export function writeCoverageSnapshot(profile, knowledgeBases, writer = writeJsonAtomic) {
46
+ writer(coverageSnapshotPath(profile), buildCoverageSnapshot(profile, knowledgeBases));
47
+ }
48
+ export function boundedCoverageSnapshotError(error) {
49
+ const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
50
+ ? error.code
51
+ : "unknown";
52
+ return `coverage snapshot write failed (${code})`;
53
+ }
@@ -0,0 +1,60 @@
1
+ import type { AddOptions, DoctorReport, IndexPlan, KnowledgeStatusSnapshot, SearchOptions, SearchResponse, SymbolSearchOptions, SymbolSearchResponse } from "../engine.ts";
2
+ import type { FilesystemAccessPolicy } from "../filesystem-access.ts";
3
+ import type { KnowledgeProfile } from "../profiles.ts";
4
+ import type { KnowledgeBase } from "../storage/sqlite.ts";
5
+ import type { DaemonServiceStatus } from "./service.ts";
6
+ export interface DaemonPing {
7
+ ready: boolean;
8
+ protocol_version: number;
9
+ profile: {
10
+ name: string;
11
+ id: string;
12
+ };
13
+ storage_dir: string;
14
+ instance_id: string;
15
+ pid: number;
16
+ package_version: string;
17
+ build_identity: string;
18
+ runtime_configuration_signature: string;
19
+ }
20
+ export type ProgressCallback = (message: string) => void;
21
+ export declare function ensureDaemonClient(profile?: KnowledgeProfile): Promise<KnowledgeDaemonClient>;
22
+ export declare function configureAndEnsureDaemonClient(profile: KnowledgeProfile, nodePath: string, signal?: AbortSignal): Promise<KnowledgeDaemonClient>;
23
+ export declare function waitForDaemonShutdown(profile: KnowledgeProfile, instanceId: string, timeoutMs?: number): Promise<void>;
24
+ export declare class KnowledgeDaemonClient {
25
+ readonly profile: KnowledgeProfile;
26
+ constructor(profile: KnowledgeProfile);
27
+ ping(signal?: AbortSignal): Promise<DaemonPing>;
28
+ plan(source: string, options?: AddOptions, signal?: AbortSignal, access?: FilesystemAccessPolicy): Promise<IndexPlan>;
29
+ configure(nodePath?: string, signal?: AbortSignal): Promise<{
30
+ node_path: string;
31
+ }>;
32
+ add(source: string, name: string, onProgress?: ProgressCallback, signal?: AbortSignal, options?: AddOptions, access?: FilesystemAccessPolicy): Promise<{
33
+ kb: KnowledgeBase;
34
+ chunkCount: number;
35
+ }>;
36
+ search(query: string, options?: SearchOptions, signal?: AbortSignal): Promise<SearchResponse>;
37
+ symbolSearch(query: string, options?: SymbolSearchOptions, signal?: AbortSignal): Promise<SymbolSearchResponse>;
38
+ update(target: string, onProgress?: ProgressCallback, signal?: AbortSignal, access?: FilesystemAccessPolicy): Promise<{
39
+ added: number;
40
+ removed: number;
41
+ unchanged: number;
42
+ }>;
43
+ list(signal?: AbortSignal): Promise<KnowledgeBase[]>;
44
+ status(signal?: AbortSignal): Promise<DaemonServiceStatus>;
45
+ doctor(signal?: AbortSignal): Promise<DoctorReport>;
46
+ remove(target: string, signal?: AbortSignal): Promise<boolean>;
47
+ exportKB(target: string, output: string, signal?: AbortSignal, onProgress?: ProgressCallback, access?: FilesystemAccessPolicy): Promise<number>;
48
+ importKB(input: string, onProgress?: ProgressCallback, signal?: AbortSignal, access?: FilesystemAccessPolicy): Promise<{
49
+ kb: KnowledgeBase;
50
+ chunkCount: number;
51
+ }>;
52
+ clear(signal?: AbortSignal): Promise<void>;
53
+ enableWatchers(signal?: AbortSignal): Promise<{
54
+ watch_count: number;
55
+ }>;
56
+ shutdown(signal?: AbortSignal): Promise<{
57
+ accepted: boolean;
58
+ }>;
59
+ }
60
+ export type { KnowledgeStatusSnapshot };