pi-knowledge 0.4.4 → 0.4.5

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 CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.4.5] - 2026-06-24
4
+
5
+ ### Fixed
6
+ - Deferred extension runtime imports so OMP plugin validation does not resolve native dependencies during install.
7
+ - Added Bun-binary-safe `better-sqlite3` loading fallback for hoisted plugin dependencies.
8
+ - Hardened lazy runtime shutdown so in-flight extension startup is disposed before Pi or OMP exits.
9
+
3
10
  ## [0.4.4] - 2026-06-23
4
11
 
5
12
  ### Fixed
package/dist/index.d.ts CHANGED
@@ -27,7 +27,7 @@ type BeforeAgentStartEvent = {
27
27
  };
28
28
  type ExtensionAPI = {
29
29
  on(event: "context", handler: (event: ContextEvent, ctx: unknown) => unknown): void;
30
- on(event: "before_agent_start", handler: (event: BeforeAgentStartEvent, ctx: unknown) => unknown): void;
30
+ on(event: "before_agent_start", handler: (event: BeforeAgentStartEvent, ctx: unknown) => unknown | Promise<unknown>): void;
31
31
  on(event: "session_start" | "session_shutdown", handler: (event: unknown, ctx: unknown) => unknown): void;
32
32
  registerTool(tool: ToolDefinition): void;
33
33
  };
package/dist/index.js CHANGED
@@ -1,6 +1,11 @@
1
- import { KnowledgeEngine } from "./src/engine.js";
2
- import { getDefaultKnowledgeDir } from "./src/storage/sqlite.js";
3
- import { getActiveWatcherCount, startWatcher, stopAllWatchers } from "./src/watcher/file-watcher.js";
1
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
2
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
3
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
4
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
5
+ });
6
+ }
7
+ return path;
8
+ };
4
9
  const Type = {
5
10
  Object(properties) {
6
11
  const required = Object.entries(properties)
@@ -34,16 +39,97 @@ const Type = {
34
39
  return { ...schema, optional: true };
35
40
  },
36
41
  };
37
- const engine = new KnowledgeEngine();
42
+ const RUNTIME_EXTENSION = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
38
43
  const WATCH_ENABLED = process.env.PI_KNOWLEDGE_WATCH === "true";
39
44
  const AUTO_INJECT = process.env.PI_KNOWLEDGE_AUTO_INJECT === "true";
45
+ let runtime;
46
+ let runtimePromise;
47
+ let initializePromise;
48
+ let initialized = false;
49
+ let disposePromise;
50
+ function runtimeModule(modulePath) {
51
+ return `${modulePath}${RUNTIME_EXTENSION}`;
52
+ }
53
+ async function loadRuntime() {
54
+ if (disposePromise)
55
+ await disposePromise;
56
+ if (runtime)
57
+ return runtime;
58
+ runtimePromise ??= Promise.all([
59
+ import(__rewriteRelativeImportExtension(runtimeModule("./src/engine"))),
60
+ import(__rewriteRelativeImportExtension(runtimeModule("./src/storage/sqlite"))),
61
+ import(__rewriteRelativeImportExtension(runtimeModule("./src/watcher/file-watcher"))),
62
+ ]).then(([engineModule, storage, watcher]) => {
63
+ runtime = { engine: new engineModule.KnowledgeEngine(), storage, watcher };
64
+ return runtime;
65
+ });
66
+ return runtimePromise;
67
+ }
68
+ async function ensureInitialized() {
69
+ if (disposePromise)
70
+ await disposePromise;
71
+ if (initialized && runtime)
72
+ return runtime;
73
+ initializePromise ??= (async () => {
74
+ const loaded = await loadRuntime();
75
+ await loaded.engine.initialize(loaded.storage.getDefaultKnowledgeDir());
76
+ initialized = true;
77
+ return loaded;
78
+ })();
79
+ try {
80
+ return await initializePromise;
81
+ }
82
+ catch (error) {
83
+ initializePromise = undefined;
84
+ throw error;
85
+ }
86
+ }
87
+ async function disposeRuntime() {
88
+ if (disposePromise)
89
+ return disposePromise;
90
+ const pendingInitialize = initializePromise;
91
+ const pendingRuntime = runtimePromise;
92
+ disposePromise = (async () => {
93
+ let loaded = runtime;
94
+ if (!loaded && pendingInitialize) {
95
+ try {
96
+ loaded = await pendingInitialize;
97
+ }
98
+ catch {
99
+ loaded = runtime;
100
+ }
101
+ }
102
+ if (!loaded && pendingRuntime) {
103
+ try {
104
+ loaded = await pendingRuntime;
105
+ }
106
+ catch {
107
+ loaded = runtime;
108
+ }
109
+ }
110
+ initialized = false;
111
+ initializePromise = undefined;
112
+ runtime = undefined;
113
+ runtimePromise = undefined;
114
+ if (!loaded)
115
+ return;
116
+ loaded.watcher.stopAllWatchers();
117
+ await loaded.engine.dispose({ disposeModels: false });
118
+ })();
119
+ try {
120
+ await disposePromise;
121
+ }
122
+ finally {
123
+ disposePromise = undefined;
124
+ }
125
+ }
40
126
  export default function (pi) {
41
127
  pi.on("session_start", async () => {
42
- await engine.initialize(getDefaultKnowledgeDir());
128
+ const { engine, watcher } = await ensureInitialized();
43
129
  if (WATCH_ENABLED) {
44
130
  for (const kb of engine.list()) {
45
131
  if (kb.source_path && kb.source_type === "directory") {
46
- startWatcher(kb.id, kb.source_path, (kbId) => {
132
+ watcher.startWatcher(kb.id, kb.source_path, (kbId) => {
47
133
  engine.update(kbId).catch(() => { });
48
134
  });
49
135
  }
@@ -51,23 +137,23 @@ export default function (pi) {
51
137
  }
52
138
  });
53
139
  pi.on("session_shutdown", async () => {
54
- stopAllWatchers();
55
- await engine.dispose({ disposeModels: false });
140
+ await disposeRuntime();
56
141
  });
57
142
  // Auto-inject: search KB for relevant context before each LLM call (opt-in)
58
143
  if (AUTO_INJECT) {
59
144
  pi.on("context", async (event) => {
60
- const kbs = engine.list();
61
- if (kbs.length === 0)
62
- return;
63
- // Find last user message
64
- const lastUser = [...event.messages].reverse().find((m) => m.role === "user");
65
- if (!lastUser)
66
- return;
67
- const text = "content" in lastUser && typeof lastUser.content === "string" ? lastUser.content : "";
68
- if (!text || text.length < 5)
69
- return;
70
145
  try {
146
+ const { engine } = await ensureInitialized();
147
+ const kbs = engine.list();
148
+ if (kbs.length === 0)
149
+ return;
150
+ // Find last user message
151
+ const lastUser = [...event.messages].reverse().find((m) => m.role === "user");
152
+ if (!lastUser)
153
+ return;
154
+ const text = "content" in lastUser && typeof lastUser.content === "string" ? lastUser.content : "";
155
+ if (!text || text.length < 5)
156
+ return;
71
157
  const results = await engine.search(text, { mode: "fast", limit: 3 });
72
158
  if (results.results.length === 0)
73
159
  return;
@@ -81,7 +167,8 @@ export default function (pi) {
81
167
  }
82
168
  });
83
169
  }
84
- pi.on("before_agent_start", (event) => {
170
+ pi.on("before_agent_start", async (event) => {
171
+ const { engine } = await ensureInitialized();
85
172
  const kbs = engine.list();
86
173
  if (kbs.length === 0)
87
174
  return undefined;
@@ -112,7 +199,8 @@ export default function (pi) {
112
199
  }))),
113
200
  exclude_paths: Type.Optional(Type.Array(Type.String({ description: "Relative paths under a directory source to exclude from this plan" }))),
114
201
  }),
115
- execute(_id, params) {
202
+ async execute(_id, params) {
203
+ const { engine } = await ensureInitialized();
116
204
  const { source, include_suggested_text, include_paths, exclude_paths } = params;
117
205
  const plan = engine.plan(source, {
118
206
  include_suggested_text: include_suggested_text === true,
@@ -170,6 +258,7 @@ export default function (pi) {
170
258
  exclude_paths: Type.Optional(Type.Array(Type.String({ description: "Relative paths under a directory source to exclude from this KB" }))),
171
259
  }),
172
260
  async execute(_id, params, _signal, onUpdate) {
261
+ const { engine, watcher } = await ensureInitialized();
173
262
  const { source, name, include_suggested_text, include_paths, exclude_paths } = params;
174
263
  const { kb, chunkCount } = await engine.add(source, name, (msg) => {
175
264
  onUpdate?.({ content: [{ type: "text", text: msg }] });
@@ -184,7 +273,7 @@ export default function (pi) {
184
273
  });
185
274
  // Start watcher for new directory KB
186
275
  if (WATCH_ENABLED && kb.source_path && kb.source_type === "directory") {
187
- startWatcher(kb.id, kb.source_path, (kbId) => {
276
+ watcher.startWatcher(kb.id, kb.source_path, (kbId) => {
188
277
  engine.update(kbId).catch(() => { });
189
278
  });
190
279
  }
@@ -231,6 +320,7 @@ export default function (pi) {
231
320
  diagnostics: Type.Optional(Type.Boolean({ description: "Include ranking diagnostics and mode/fallback details in the result" })),
232
321
  }),
233
322
  async execute(_id, params) {
323
+ const { engine } = await ensureInitialized();
234
324
  const { query, mode, limit, kb_id, offset, file_type, diversity, diagnostics } = params;
235
325
  const filters = file_type ? { file_type } : undefined;
236
326
  const response = await engine.search(query, { mode, limit, kb_id, offset, filters, diversity });
@@ -275,6 +365,7 @@ export default function (pi) {
275
365
  target: Type.String({ description: "KB name or ID to update" }),
276
366
  }),
277
367
  async execute(_id, params, _signal, onUpdate) {
368
+ const { engine } = await ensureInitialized();
278
369
  const { added, removed, unchanged } = await engine.update(params.target, (msg) => {
279
370
  onUpdate?.({ content: [{ type: "text", text: msg }] });
280
371
  }, _signal);
@@ -289,11 +380,12 @@ export default function (pi) {
289
380
  description: "Show knowledge engine status with health diagnostics: staleness, orphans, and coverage",
290
381
  parameters: Type.Object({}),
291
382
  async execute() {
383
+ const { engine, storage, watcher } = await ensureInitialized();
292
384
  const kbs = engine.list();
293
- const watchCount = getActiveWatcherCount();
385
+ const watchCount = watcher.getActiveWatcherCount();
294
386
  const diagnostics = engine.diagnose();
295
387
  const lines = [
296
- `Storage: ${getDefaultKnowledgeDir()}`,
388
+ `Storage: ${storage.getDefaultKnowledgeDir()}`,
297
389
  `Knowledge bases: ${kbs.length}`,
298
390
  `Active watchers: ${watchCount}`,
299
391
  "",
@@ -354,6 +446,7 @@ export default function (pi) {
354
446
  promptSnippet: "Diagnose knowledge base health and recommended actions",
355
447
  parameters: Type.Object({}),
356
448
  async execute() {
449
+ const { engine } = await ensureInitialized();
357
450
  const report = engine.doctor();
358
451
  const lines = [`Health score: ${report.health_score}/100`, report.summary, ""];
359
452
  if (report.issues.length === 0) {
@@ -375,6 +468,7 @@ export default function (pi) {
375
468
  description: "List all indexed knowledge bases",
376
469
  parameters: Type.Object({}),
377
470
  async execute() {
471
+ const { engine } = await ensureInitialized();
378
472
  const kbs = engine.list();
379
473
  if (kbs.length === 0)
380
474
  return { content: [{ type: "text", text: "No knowledge bases." }] };
@@ -390,6 +484,7 @@ export default function (pi) {
390
484
  target: Type.String({ description: "KB name or ID to remove" }),
391
485
  }),
392
486
  async execute(_id, params) {
487
+ const { engine } = await ensureInitialized();
393
488
  const ok = engine.remove(params.target);
394
489
  return { content: [{ type: "text", text: ok ? "Removed." : "Not found." }] };
395
490
  },
@@ -403,6 +498,7 @@ export default function (pi) {
403
498
  output: Type.String({ description: "Output file path (.jsonl)" }),
404
499
  }),
405
500
  async execute(_id, params) {
501
+ const { engine } = await ensureInitialized();
406
502
  const { target, output } = params;
407
503
  const count = await engine.exportKB(target, output);
408
504
  return { content: [{ type: "text", text: `Exported ${count} chunks to ${output}` }] };
@@ -416,6 +512,7 @@ export default function (pi) {
416
512
  input: Type.String({ description: "Input JSONL file path" }),
417
513
  }),
418
514
  async execute(_id, params, _signal, onUpdate) {
515
+ const { engine } = await ensureInitialized();
419
516
  const { kb, chunkCount } = await engine.importKB(params.input, (msg) => {
420
517
  onUpdate?.({ content: [{ type: "text", text: msg }] });
421
518
  }, _signal);
@@ -428,6 +525,7 @@ export default function (pi) {
428
525
  description: "Remove all knowledge bases",
429
526
  parameters: Type.Object({}),
430
527
  async execute() {
528
+ const { engine } = await ensureInitialized();
431
529
  engine.clear();
432
530
  return { content: [{ type: "text", text: "All knowledge bases cleared." }] };
433
531
  },
@@ -1,4 +1,4 @@
1
- import Database from "better-sqlite3";
1
+ import type Database from "better-sqlite3";
2
2
  export interface KnowledgeBase {
3
3
  id: string;
4
4
  name: string;
@@ -1,8 +1,9 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import { existsSync, mkdirSync } from "node:fs";
3
+ import { createRequire } from "node:module";
3
4
  import { homedir } from "node:os";
4
5
  import { basename, dirname, join } from "node:path";
5
- import Database from "better-sqlite3";
6
+ import { fileURLToPath } from "node:url";
6
7
  const SCHEMA_VERSION = 3;
7
8
  const SCHEMA_SQL = `
8
9
  CREATE TABLE IF NOT EXISTS schema_version (
@@ -82,6 +83,74 @@ CREATE TRIGGER IF NOT EXISTS chunks_au AFTER UPDATE ON chunks BEGIN
82
83
  INSERT INTO chunks_fts(rowid, content_tokenized) VALUES (new.rowid, new.content_tokenized);
83
84
  END;
84
85
  `;
86
+ const localRequire = createRequire(import.meta.url);
87
+ let databaseConstructor;
88
+ let betterSqlite3PackageRoot;
89
+ function findBetterSqlite3PackageRoot() {
90
+ if (betterSqlite3PackageRoot)
91
+ return betterSqlite3PackageRoot;
92
+ let current = dirname(fileURLToPath(import.meta.url));
93
+ while (true) {
94
+ const candidate = join(current, "node_modules", "better-sqlite3");
95
+ if (existsSync(join(candidate, "package.json"))) {
96
+ betterSqlite3PackageRoot = candidate;
97
+ return betterSqlite3PackageRoot;
98
+ }
99
+ const parent = dirname(current);
100
+ if (parent === current)
101
+ return undefined;
102
+ current = parent;
103
+ }
104
+ }
105
+ function findBetterSqlite3Entry() {
106
+ const packageRoot = findBetterSqlite3PackageRoot();
107
+ return packageRoot ? join(packageRoot, "lib", "index.js") : undefined;
108
+ }
109
+ function findBetterSqlite3NativeBinding() {
110
+ const packageRoot = findBetterSqlite3PackageRoot();
111
+ if (!packageRoot)
112
+ return undefined;
113
+ const candidate = join(packageRoot, "build", "Release", "better_sqlite3.node");
114
+ return existsSync(candidate) ? candidate : undefined;
115
+ }
116
+ function betterSqlite3PackageName() {
117
+ return ["better", "sqlite3"].join("-");
118
+ }
119
+ function bunSqliteModuleName() {
120
+ return ["bun", "sqlite"].join(":");
121
+ }
122
+ function isBunRuntime() {
123
+ return typeof process.versions.bun === "string";
124
+ }
125
+ function loadDatabaseConstructor() {
126
+ if (databaseConstructor)
127
+ return databaseConstructor;
128
+ if (isBunRuntime()) {
129
+ const bunSqlite = localRequire(bunSqliteModuleName());
130
+ databaseConstructor = bunSqlite.Database;
131
+ return databaseConstructor;
132
+ }
133
+ try {
134
+ databaseConstructor = localRequire(betterSqlite3PackageName());
135
+ return databaseConstructor;
136
+ }
137
+ catch (error) {
138
+ const entry = findBetterSqlite3Entry();
139
+ if (entry) {
140
+ databaseConstructor = localRequire(entry);
141
+ return databaseConstructor;
142
+ }
143
+ throw error;
144
+ }
145
+ }
146
+ function applyPragma(db, pragma) {
147
+ const sqlite = db;
148
+ if (typeof sqlite.pragma === "function") {
149
+ sqlite.pragma(pragma);
150
+ return;
151
+ }
152
+ db.exec(`PRAGMA ${pragma}`);
153
+ }
85
154
  export function getDefaultKnowledgeDir() {
86
155
  const explicit = process.env.PI_KNOWLEDGE_DIR?.trim() || process.env.OMP_KNOWLEDGE_DIR?.trim();
87
156
  if (explicit)
@@ -116,10 +185,12 @@ export function openDatabase(knowledgeDir) {
116
185
  mkdirSync(dir, { recursive: true });
117
186
  }
118
187
  const dbPath = join(dir, "knowledge.db");
119
- const db = new Database(dbPath);
120
- db.pragma("journal_mode = WAL");
121
- db.pragma("busy_timeout = 5000");
122
- db.pragma("foreign_keys = ON");
188
+ const Database = loadDatabaseConstructor();
189
+ const nativeBinding = isBunRuntime() ? undefined : findBetterSqlite3NativeBinding();
190
+ const db = nativeBinding ? new Database(dbPath, { nativeBinding }) : new Database(dbPath);
191
+ applyPragma(db, "journal_mode = WAL");
192
+ applyPragma(db, "busy_timeout = 5000");
193
+ applyPragma(db, "foreign_keys = ON");
123
194
  const hasVersion = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='schema_version'").get();
124
195
  if (!hasVersion) {
125
196
  db.exec(SCHEMA_SQL);
package/extension.js CHANGED
@@ -1,7 +1,11 @@
1
1
  import { existsSync } from "node:fs";
2
2
 
3
+ function extensionModule(modulePath) {
4
+ return `./${modulePath}`;
5
+ }
6
+
3
7
  const module = existsSync(new URL("./dist/index.js", import.meta.url))
4
- ? await import("./dist/index.js")
5
- : await import("./index.ts");
8
+ ? await import(extensionModule("dist/index.js"))
9
+ : await import(extensionModule("index.ts"));
6
10
 
7
11
  export default module.default;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-knowledge",
3
- "version": "0.4.4",
3
+ "version": "0.4.5",
4
4
  "description": "Local-first RAG knowledge base for Pi agents with hybrid code/doc search, reranking, diagnostics, and large-project indexing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",