pi-knowledge 0.5.3 → 0.5.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,21 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.5.5] - 2026-07-23
4
+
5
+ ### Added
6
+ - Added `knowledge_configure` so agents can validate and persist a Node 22+ executable for the isolated local model worker without relying on environment variables injected after OMP startup.
7
+
8
+ ### Fixed
9
+ - Auto-discovers Codex bundled Windows Node runtimes under `%LOCALAPPDATA%\OpenAI\Codex\runtimes\cua_node\*\bin\node.exe` for OMP sessions without global `node` on `PATH`.
10
+ - Reuses persisted runtime config before falling back to process or PATH discovery, so one successful configuration survives future OMP sessions.
11
+
12
+ ## [0.5.4] - 2026-07-23
13
+
14
+ ### Fixed
15
+ - Prevented missing Windows `node.exe` from surfacing as an uncaught `uv_spawn 'node'` failure by resolving Node before worker startup and wrapping synchronous spawn failures with model-worker diagnostics.
16
+ - Expanded Windows Node discovery to common Node, Volta, and NVM install locations, and stripped accidental surrounding quotes from `PI_KNOWLEDGE_NODE_PATH` paths with spaces.
17
+
18
+
3
19
  ## [0.5.3] - 2026-07-23
4
20
 
5
21
  ### Fixed
package/README.md CHANGED
@@ -110,6 +110,7 @@ omp install ./pi-knowledge
110
110
  | `knowledge_show` | List all knowledge bases with stats |
111
111
  | `knowledge_status` | Show engine status with health diagnostics (stale, orphans, coverage) |
112
112
  | `knowledge_doctor` | Diagnose health score, skipped files, stuck jobs, stale data, and recommended fixes |
113
+ | `knowledge_configure` | Persist runtime prerequisites such as a Windows `node.exe` path for the isolated local model worker |
113
114
  | `knowledge_clear` | Remove all knowledge bases after `confirm: true` |
114
115
  | `knowledge_export` | Export a KB to shareable JSONL file |
115
116
  | `knowledge_import` | Import a KB from JSONL (re-embeds content) |
package/dist/index.js CHANGED
@@ -248,6 +248,41 @@ export default function (pi) {
248
248
  };
249
249
  },
250
250
  });
251
+ pi.registerTool({
252
+ name: "knowledge_configure",
253
+ label: "Knowledge Configure",
254
+ description: "Configure pi-knowledge runtime settings such as the local model worker Node executable",
255
+ promptSnippet: "Configure local pi-knowledge runtime prerequisites before indexing",
256
+ promptGuidelines: [
257
+ "Use knowledge_configure when knowledge_doctor or knowledge_add reports that local embeddings cannot find a usable Node executable",
258
+ "On Windows, pass the full node.exe path when the user provides one; paths with spaces are accepted",
259
+ "If node_path is omitted, the tool auto-discovers a usable Node 22+ executable and persists it for future sessions",
260
+ "Do not switch users to API embeddings unless they explicitly choose a network embedding provider",
261
+ ],
262
+ parameters: Type.Object({
263
+ node_path: Type.Optional(Type.String({
264
+ description: "Optional full path to a Node 22+ executable for the isolated local embedding model worker, such as C:\\Program Files\\nodejs\\node.exe",
265
+ })),
266
+ }),
267
+ async execute(_id, params, _signal) {
268
+ if (_signal?.aborted)
269
+ throw new Error("Cancelled");
270
+ const { configureModelWorkerNodePath } = await import(__rewriteRelativeImportExtension(runtimeModule("./src/model-worker-client")));
271
+ if (_signal?.aborted)
272
+ throw new Error("Cancelled");
273
+ const nodePath = typeof params.node_path === "string" && params.node_path.trim() ? params.node_path : undefined;
274
+ const configuredPath = configureModelWorkerNodePath(nodePath);
275
+ return {
276
+ content: [
277
+ {
278
+ type: "text",
279
+ text: `Configured local model worker Node executable: ${configuredPath}`,
280
+ },
281
+ ],
282
+ details: { node_path: configuredPath },
283
+ };
284
+ },
285
+ });
251
286
  pi.registerTool({
252
287
  name: "knowledge_add",
253
288
  label: "Knowledge Add",
@@ -1,3 +1,6 @@
1
+ export declare function validateModelWorkerNodePath(nodePath: string): string;
2
+ export declare function resolveModelWorkerNodePath(): string;
3
+ export declare function configureModelWorkerNodePath(nodePath?: string): string;
1
4
  export declare function embedInModelWorker(texts: string[], prefix: "query" | "passage", signal?: AbortSignal): Promise<Float32Array[]>;
2
5
  export interface RerankWorkerCandidate {
3
6
  chunkId: string;
@@ -1,8 +1,9 @@
1
1
  import { execFileSync, fork, spawn } from "node:child_process";
2
- import { existsSync } from "node:fs";
3
- import { basename } from "node:path";
2
+ import { existsSync, readdirSync, statSync } from "node:fs";
3
+ import { basename, delimiter, join } from "node:path";
4
4
  import { StringDecoder } from "node:string_decoder";
5
5
  import { fileURLToPath } from "node:url";
6
+ import { getConfiguredNodePath, writeRuntimeConfig } from "./runtime-config.js";
6
7
  let worker = null;
7
8
  let nextRequestId = 1;
8
9
  let resolvedNodeExecPath = null;
@@ -26,6 +27,9 @@ function parseNodeMajor(version) {
26
27
  const major = Number(match.groups.major);
27
28
  return Number.isInteger(major) ? major : null;
28
29
  }
30
+ function toError(error) {
31
+ return error instanceof Error ? error : new Error(String(error));
32
+ }
29
33
  function validateNodeExecPath(candidate) {
30
34
  const version = execFileSync(candidate, ["--version"], {
31
35
  encoding: "utf8",
@@ -39,13 +43,93 @@ function validateNodeExecPath(candidate) {
39
43
  }
40
44
  return candidate;
41
45
  }
46
+ function normalizeExecutableCandidate(value) {
47
+ const trimmed = value.trim();
48
+ if (trimmed.length >= 2 &&
49
+ ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'")))) {
50
+ return trimmed.slice(1, -1).trim();
51
+ }
52
+ return trimmed;
53
+ }
54
+ function pathEnvValue() {
55
+ return process.env.PATH ?? process.env.Path ?? process.env.path ?? "";
56
+ }
57
+ function appendIfPresent(candidates, value, suffix) {
58
+ const normalized = value ? normalizeExecutableCandidate(value) : "";
59
+ if (!normalized)
60
+ return;
61
+ candidates.push(suffix ? join(normalized, suffix) : normalized);
62
+ }
63
+ function appendCodexNodeCandidates(candidates) {
64
+ const localAppData = process.env.LOCALAPPDATA ? normalizeExecutableCandidate(process.env.LOCALAPPDATA) : "";
65
+ if (!localAppData)
66
+ return;
67
+ const runtimeRoot = join(localAppData, "OpenAI", "Codex", "runtimes", "cua_node");
68
+ if (!existsSync(runtimeRoot))
69
+ return;
70
+ const discovered = readdirSync(runtimeRoot, { withFileTypes: true })
71
+ .filter((entry) => entry.isDirectory())
72
+ .map((entry) => {
73
+ const nodePath = join(runtimeRoot, entry.name, "bin", "node.exe");
74
+ const mtimeMs = existsSync(nodePath) ? statSync(nodePath).mtimeMs : 0;
75
+ return { nodePath, mtimeMs };
76
+ })
77
+ .filter((candidate) => candidate.mtimeMs > 0)
78
+ .sort((a, b) => b.mtimeMs - a.mtimeMs);
79
+ for (const candidate of discovered)
80
+ candidates.push(candidate.nodePath);
81
+ }
82
+ function getWindowsNodeCandidates() {
83
+ const candidates = [];
84
+ appendIfPresent(candidates, process.env.NVM_SYMLINK, "node.exe");
85
+ appendIfPresent(candidates, process.env.VOLTA_HOME, join("bin", "node.exe"));
86
+ appendIfPresent(candidates, process.env.ProgramFiles, join("nodejs", "node.exe"));
87
+ appendIfPresent(candidates, process.env["ProgramFiles(x86)"], join("nodejs", "node.exe"));
88
+ appendIfPresent(candidates, process.env.LOCALAPPDATA, join("Programs", "nodejs", "node.exe"));
89
+ appendCodexNodeCandidates(candidates);
90
+ for (const directory of pathEnvValue().split(delimiter)) {
91
+ appendIfPresent(candidates, directory, "node.exe");
92
+ }
93
+ return candidates;
94
+ }
95
+ function getNodeCandidates() {
96
+ const candidates = [];
97
+ appendIfPresent(candidates, process.env.NODE);
98
+ if (process.platform === "win32") {
99
+ candidates.push(...getWindowsNodeCandidates());
100
+ }
101
+ else {
102
+ for (const directory of pathEnvValue().split(delimiter)) {
103
+ appendIfPresent(candidates, directory, "node");
104
+ }
105
+ }
106
+ candidates.push("node");
107
+ return [...new Set(candidates)];
108
+ }
42
109
  function getNodeExecPath() {
43
110
  if (resolvedNodeExecPath)
44
111
  return resolvedNodeExecPath;
45
- const configured = process.env.PI_KNOWLEDGE_NODE_PATH?.trim();
112
+ const configured = process.env.PI_KNOWLEDGE_NODE_PATH
113
+ ? normalizeExecutableCandidate(process.env.PI_KNOWLEDGE_NODE_PATH)
114
+ : "";
46
115
  if (configured) {
47
- resolvedNodeExecPath = validateNodeExecPath(configured);
48
- return resolvedNodeExecPath;
116
+ try {
117
+ resolvedNodeExecPath = validateNodeExecPath(configured);
118
+ return resolvedNodeExecPath;
119
+ }
120
+ catch (error) {
121
+ throw new Error(`PI_KNOWLEDGE_NODE_PATH does not point to a usable Node ${MIN_NODE_MAJOR}+ executable: ${toError(error).message}`);
122
+ }
123
+ }
124
+ const persisted = getConfiguredNodePath();
125
+ if (persisted) {
126
+ try {
127
+ resolvedNodeExecPath = validateNodeExecPath(normalizeExecutableCandidate(persisted));
128
+ return resolvedNodeExecPath;
129
+ }
130
+ catch {
131
+ // Persisted paths can point at removable Codex runtimes; continue with auto-discovery.
132
+ }
49
133
  }
50
134
  const execName = basename(process.execPath).toLowerCase();
51
135
  const currentProcessLooksLikeNode = execName === "node" || execName === "node.exe";
@@ -56,8 +140,7 @@ function getNodeExecPath() {
56
140
  return resolvedNodeExecPath;
57
141
  }
58
142
  }
59
- const envNode = process.env.NODE?.trim();
60
- for (const candidate of [envNode, "node"].filter((value) => Boolean(value))) {
143
+ for (const candidate of getNodeCandidates()) {
61
144
  try {
62
145
  resolvedNodeExecPath = validateNodeExecPath(candidate);
63
146
  return resolvedNodeExecPath;
@@ -66,7 +149,19 @@ function getNodeExecPath() {
66
149
  // Try the next candidate before surfacing a deterministic error below.
67
150
  }
68
151
  }
69
- throw new Error(`Node ${MIN_NODE_MAJOR}+ is required for local pi-knowledge embeddings. Set PI_KNOWLEDGE_NODE_PATH to a working node.exe path.`);
152
+ throw new Error(`Node ${MIN_NODE_MAJOR}+ is required for local pi-knowledge embeddings, but no usable node executable was found. Install Node ${MIN_NODE_MAJOR}+ or set PI_KNOWLEDGE_NODE_PATH to the full node.exe path.`);
153
+ }
154
+ export function validateModelWorkerNodePath(nodePath) {
155
+ return validateNodeExecPath(normalizeExecutableCandidate(nodePath));
156
+ }
157
+ export function resolveModelWorkerNodePath() {
158
+ return getNodeExecPath();
159
+ }
160
+ export function configureModelWorkerNodePath(nodePath) {
161
+ const resolved = nodePath ? validateModelWorkerNodePath(nodePath) : getNodeExecPath();
162
+ writeRuntimeConfig({ node_path: resolved });
163
+ resolvedNodeExecPath = resolved;
164
+ return resolved;
70
165
  }
71
166
  function appendWorkerStderr(current, chunk) {
72
167
  const next = `${current}${chunk.toString("utf-8")}`;
@@ -96,7 +191,7 @@ class ModelWorkerTransport {
96
191
  pending = new Map();
97
192
  stderrTail = "";
98
193
  exited = false;
99
- spawnError = null;
194
+ terminalError = null;
100
195
  constructor(child) {
101
196
  this.child = child;
102
197
  child.stderr?.on("data", (chunk) => {
@@ -110,21 +205,21 @@ class ModelWorkerTransport {
110
205
  this.rejectPending(formatWorkerExitError(code, signal, this.stderrTail));
111
206
  });
112
207
  child.on("error", (error) => {
113
- this.spawnError = error;
208
+ this.terminalError = formatWorkerSpawnError(error, this.stderrTail);
114
209
  this.exited = true;
115
210
  if (worker === this)
116
211
  worker = null;
117
- this.rejectPending(formatWorkerSpawnError(error, this.stderrTail));
212
+ this.rejectPending(this.terminalError);
118
213
  });
119
214
  }
120
215
  isConnected() {
121
- return !this.exited && !this.child.killed && !this.spawnError && this.isTransportConnected();
216
+ return !this.exited && !this.child.killed && !this.terminalError && this.isTransportConnected();
122
217
  }
123
218
  request(message, signal) {
124
219
  if (signal?.aborted)
125
220
  throw new Error("Cancelled");
126
221
  if (!this.isConnected())
127
- throw new Error("Model worker is not connected");
222
+ throw this.terminalError ?? new Error("Model worker is not connected");
128
223
  const id = nextRequestId++;
129
224
  const { promise, resolve, reject } = Promise.withResolvers();
130
225
  let abortHandler;
@@ -196,11 +291,11 @@ class IpcModelWorkerTransport extends ModelWorkerTransport {
196
291
  this.ipcChild = ipcChild;
197
292
  ipcChild.on("message", (message) => this.handleWorkerResponse(message));
198
293
  }
199
- static create(workerPath) {
294
+ static create(workerPath, nodeExecPath) {
200
295
  let child;
201
296
  try {
202
297
  child = fork(workerPath, {
203
- execPath: getNodeExecPath(),
298
+ execPath: nodeExecPath,
204
299
  execArgv: getWorkerExecArgv(),
205
300
  stdio: ["ignore", "ignore", "pipe", "ipc"],
206
301
  env: process.env,
@@ -226,12 +321,18 @@ class IpcModelWorkerTransport extends ModelWorkerTransport {
226
321
  class StdioModelWorkerTransport extends ModelWorkerTransport {
227
322
  decoder = new StringDecoder("utf8");
228
323
  stdoutBuffer = "";
229
- constructor(workerPath) {
230
- const child = spawn(getNodeExecPath(), [...getWorkerExecArgv(), workerPath, "--stdio"], {
231
- stdio: ["pipe", "pipe", "pipe"],
232
- env: process.env,
233
- windowsHide: true,
234
- });
324
+ constructor(workerPath, nodeExecPath) {
325
+ let child;
326
+ try {
327
+ child = spawn(nodeExecPath, [...getWorkerExecArgv(), workerPath, "--stdio"], {
328
+ stdio: ["pipe", "pipe", "pipe"],
329
+ env: process.env,
330
+ windowsHide: true,
331
+ });
332
+ }
333
+ catch (error) {
334
+ throw formatWorkerSpawnError(toError(error), "");
335
+ }
235
336
  super(child);
236
337
  if (!child.stdin || !child.stdout) {
237
338
  if (!child.killed)
@@ -279,7 +380,9 @@ function getWorker() {
279
380
  if (worker?.isConnected())
280
381
  return worker;
281
382
  const workerPath = getWorkerPath();
282
- worker = IpcModelWorkerTransport.create(workerPath) ?? new StdioModelWorkerTransport(workerPath);
383
+ const nodeExecPath = getNodeExecPath();
384
+ worker =
385
+ IpcModelWorkerTransport.create(workerPath, nodeExecPath) ?? new StdioModelWorkerTransport(workerPath, nodeExecPath);
283
386
  return worker;
284
387
  }
285
388
  export async function embedInModelWorker(texts, prefix, signal) {
@@ -0,0 +1,7 @@
1
+ export type RuntimeConfig = {
2
+ node_path?: string;
3
+ updated_at?: number;
4
+ };
5
+ export declare function readRuntimeConfig(knowledgeDir?: string): RuntimeConfig;
6
+ export declare function getConfiguredNodePath(): string | undefined;
7
+ export declare function writeRuntimeConfig(update: RuntimeConfig, knowledgeDir?: string): RuntimeConfig;
@@ -0,0 +1,36 @@
1
+ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { getDefaultKnowledgeDir } from "./storage/sqlite.js";
4
+ const CONFIG_FILE = "config.json";
5
+ function runtimeConfigPath(knowledgeDir = getDefaultKnowledgeDir()) {
6
+ return join(knowledgeDir, CONFIG_FILE);
7
+ }
8
+ function isRuntimeConfig(value) {
9
+ if (typeof value !== "object" || value === null)
10
+ return false;
11
+ if ("node_path" in value && value.node_path !== undefined && typeof value.node_path !== "string")
12
+ return false;
13
+ return !("updated_at" in value) || value.updated_at === undefined || typeof value.updated_at === "number";
14
+ }
15
+ export function readRuntimeConfig(knowledgeDir = getDefaultKnowledgeDir()) {
16
+ const configPath = runtimeConfigPath(knowledgeDir);
17
+ if (!existsSync(configPath))
18
+ return {};
19
+ const parsed = JSON.parse(readFileSync(configPath, "utf8"));
20
+ if (!isRuntimeConfig(parsed))
21
+ throw new Error(`Invalid pi-knowledge runtime config: ${configPath}`);
22
+ return parsed;
23
+ }
24
+ export function getConfiguredNodePath() {
25
+ return readRuntimeConfig().node_path?.trim() || undefined;
26
+ }
27
+ export function writeRuntimeConfig(update, knowledgeDir = getDefaultKnowledgeDir()) {
28
+ mkdirSync(knowledgeDir, { recursive: true });
29
+ const existing = readRuntimeConfig(knowledgeDir);
30
+ const next = { ...existing, ...update, updated_at: Date.now() };
31
+ const configPath = runtimeConfigPath(knowledgeDir);
32
+ const tempPath = `${configPath}.${process.pid}.tmp`;
33
+ writeFileSync(tempPath, `${JSON.stringify(next, null, 2)}\n`);
34
+ renameSync(tempPath, configPath);
35
+ return next;
36
+ }
@@ -30,7 +30,7 @@ Default data storage is `~/.pi/knowledge` under Pi and `~/.omp/knowledge` under
30
30
  | `PI_KNOWLEDGE_EMBEDDING_IDLE_MS` | `30000` | Idle timer used only when native idle disposal coordination is enabled. Mainly for lifecycle stress tests. |
31
31
  | `PI_KNOWLEDGE_OFFLINE` | unset | Use with a pre-populated model cache for offline local model operation. See `docs/offline-mode.md`. |
32
32
 
33
- Local embeddings require a real Node 22+ executable for the isolated model worker. `pi-knowledge` first tries Node IPC and automatically falls back to a stdin/stdout JSONL worker transport when the host runtime does not expose `child_process.fork().send()`, which can happen in Windows OMP compatibility layers. If worker startup fails, set `PI_KNOWLEDGE_NODE_PATH` to the full `node.exe` path or use an OpenAI-compatible embedding provider.
33
+ Local embeddings require a real Node 22+ executable for the isolated model worker. `pi-knowledge` first tries Node IPC and automatically falls back to a stdin/stdout JSONL worker transport when the host runtime does not expose `child_process.fork().send()`, which can happen in Windows OMP compatibility layers. On Windows it searches `PI_KNOWLEDGE_NODE_PATH`, persisted `knowledge_configure` settings, common Node, Volta, NVM, Codex `cua_node`, and `PATH` locations before failing. If worker startup still fails, call `knowledge_configure` with the full `node.exe` path such as `C:\Program Files\nodejs\node.exe`; accidental surrounding quotes are ignored. OpenAI-compatible embeddings avoid the local worker entirely.
34
34
 
35
35
  API embedding failures intentionally surface by default. Silent fallback can hide bad API keys, wrong base URLs, unsupported model names, or context-window errors and can produce a KB with a different embedding model than intended.
36
36
 
@@ -48,6 +48,8 @@ Search diagnostics include result provenance in both text output and structured
48
48
 
49
49
  `knowledge_doctor` emits both human-readable issues and machine-readable actions in structured `details`. Action codes include `run_update`, `rebuild_kb`, `wait_for_indexing`, `review_skipped_scope`, `rebuild_vectors`, `check_source`, and `none`. Agents should prefer these action codes over parsing the English action text.
50
50
 
51
+ `knowledge_configure` writes runtime configuration to the knowledge directory's `config.json`. It validates Node 22+ before persisting `node_path`, so agents can configure a Codex- or user-installed `node.exe` once without relying on environment variables being injected into an already-running OMP process.
52
+
51
53
  `knowledge_symbol_search` uses a lightweight declaration-pattern index stored in `knowledge.db`. It is rebuilt during `knowledge_add`, `knowledge_update`, and `knowledge_import`, and can find common code symbols, route-like handlers, Markdown headings, config keys, and environment variables. It is not a full LSP or code graph; for methods, uncommon syntax, or empty important lookups, use `knowledge_search` mode `fast`/`adaptive` and check `knowledge_doctor` for stale or missing symbol metadata. Older file/directory/URL KBs without symbol metadata should be updated before relying on symbol lookup. Imported portable KBs and inline text KBs do not retain an active source path; rebuild their symbols by re-importing or re-adding the content.
52
54
 
53
55
  ## Test and Release Fixtures
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-knowledge",
3
- "version": "0.5.3",
3
+ "version": "0.5.5",
4
4
  "description": "Local-first RAG knowledge base for Pi and OMP coding agents with hybrid code/doc search, reranking, diagnostics, and large-project indexing",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",