pi-knowledge 0.5.3 → 0.5.4
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 +7 -0
- package/dist/src/model-worker-client.js +81 -21
- package/docs/configuration.md +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.5.4] - 2026-07-23
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
- 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.
|
|
7
|
+
- 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.
|
|
8
|
+
|
|
9
|
+
|
|
3
10
|
## [0.5.3] - 2026-07-23
|
|
4
11
|
|
|
5
12
|
### Fixed
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { execFileSync, fork, spawn } from "node:child_process";
|
|
2
2
|
import { existsSync } from "node:fs";
|
|
3
|
-
import { basename } from "node:path";
|
|
3
|
+
import { basename, delimiter, join } from "node:path";
|
|
4
4
|
import { StringDecoder } from "node:string_decoder";
|
|
5
5
|
import { fileURLToPath } from "node:url";
|
|
6
6
|
let worker = null;
|
|
@@ -26,6 +26,9 @@ function parseNodeMajor(version) {
|
|
|
26
26
|
const major = Number(match.groups.major);
|
|
27
27
|
return Number.isInteger(major) ? major : null;
|
|
28
28
|
}
|
|
29
|
+
function toError(error) {
|
|
30
|
+
return error instanceof Error ? error : new Error(String(error));
|
|
31
|
+
}
|
|
29
32
|
function validateNodeExecPath(candidate) {
|
|
30
33
|
const version = execFileSync(candidate, ["--version"], {
|
|
31
34
|
encoding: "utf8",
|
|
@@ -39,13 +42,63 @@ function validateNodeExecPath(candidate) {
|
|
|
39
42
|
}
|
|
40
43
|
return candidate;
|
|
41
44
|
}
|
|
45
|
+
function normalizeExecutableCandidate(value) {
|
|
46
|
+
const trimmed = value.trim();
|
|
47
|
+
if (trimmed.length >= 2 &&
|
|
48
|
+
((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'")))) {
|
|
49
|
+
return trimmed.slice(1, -1).trim();
|
|
50
|
+
}
|
|
51
|
+
return trimmed;
|
|
52
|
+
}
|
|
53
|
+
function pathEnvValue() {
|
|
54
|
+
return process.env.PATH ?? process.env.Path ?? process.env.path ?? "";
|
|
55
|
+
}
|
|
56
|
+
function appendIfPresent(candidates, value, suffix) {
|
|
57
|
+
const normalized = value ? normalizeExecutableCandidate(value) : "";
|
|
58
|
+
if (!normalized)
|
|
59
|
+
return;
|
|
60
|
+
candidates.push(suffix ? join(normalized, suffix) : normalized);
|
|
61
|
+
}
|
|
62
|
+
function getWindowsNodeCandidates() {
|
|
63
|
+
const candidates = [];
|
|
64
|
+
appendIfPresent(candidates, process.env.NVM_SYMLINK, "node.exe");
|
|
65
|
+
appendIfPresent(candidates, process.env.VOLTA_HOME, join("bin", "node.exe"));
|
|
66
|
+
appendIfPresent(candidates, process.env.ProgramFiles, join("nodejs", "node.exe"));
|
|
67
|
+
appendIfPresent(candidates, process.env["ProgramFiles(x86)"], join("nodejs", "node.exe"));
|
|
68
|
+
appendIfPresent(candidates, process.env.LOCALAPPDATA, join("Programs", "nodejs", "node.exe"));
|
|
69
|
+
for (const directory of pathEnvValue().split(delimiter)) {
|
|
70
|
+
appendIfPresent(candidates, directory, "node.exe");
|
|
71
|
+
}
|
|
72
|
+
return candidates;
|
|
73
|
+
}
|
|
74
|
+
function getNodeCandidates() {
|
|
75
|
+
const candidates = [];
|
|
76
|
+
appendIfPresent(candidates, process.env.NODE);
|
|
77
|
+
if (process.platform === "win32") {
|
|
78
|
+
candidates.push(...getWindowsNodeCandidates());
|
|
79
|
+
}
|
|
80
|
+
else {
|
|
81
|
+
for (const directory of pathEnvValue().split(delimiter)) {
|
|
82
|
+
appendIfPresent(candidates, directory, "node");
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
candidates.push("node");
|
|
86
|
+
return [...new Set(candidates)];
|
|
87
|
+
}
|
|
42
88
|
function getNodeExecPath() {
|
|
43
89
|
if (resolvedNodeExecPath)
|
|
44
90
|
return resolvedNodeExecPath;
|
|
45
|
-
const configured = process.env.PI_KNOWLEDGE_NODE_PATH
|
|
91
|
+
const configured = process.env.PI_KNOWLEDGE_NODE_PATH
|
|
92
|
+
? normalizeExecutableCandidate(process.env.PI_KNOWLEDGE_NODE_PATH)
|
|
93
|
+
: "";
|
|
46
94
|
if (configured) {
|
|
47
|
-
|
|
48
|
-
|
|
95
|
+
try {
|
|
96
|
+
resolvedNodeExecPath = validateNodeExecPath(configured);
|
|
97
|
+
return resolvedNodeExecPath;
|
|
98
|
+
}
|
|
99
|
+
catch (error) {
|
|
100
|
+
throw new Error(`PI_KNOWLEDGE_NODE_PATH does not point to a usable Node ${MIN_NODE_MAJOR}+ executable: ${toError(error).message}`);
|
|
101
|
+
}
|
|
49
102
|
}
|
|
50
103
|
const execName = basename(process.execPath).toLowerCase();
|
|
51
104
|
const currentProcessLooksLikeNode = execName === "node" || execName === "node.exe";
|
|
@@ -56,8 +109,7 @@ function getNodeExecPath() {
|
|
|
56
109
|
return resolvedNodeExecPath;
|
|
57
110
|
}
|
|
58
111
|
}
|
|
59
|
-
const
|
|
60
|
-
for (const candidate of [envNode, "node"].filter((value) => Boolean(value))) {
|
|
112
|
+
for (const candidate of getNodeCandidates()) {
|
|
61
113
|
try {
|
|
62
114
|
resolvedNodeExecPath = validateNodeExecPath(candidate);
|
|
63
115
|
return resolvedNodeExecPath;
|
|
@@ -66,7 +118,7 @@ function getNodeExecPath() {
|
|
|
66
118
|
// Try the next candidate before surfacing a deterministic error below.
|
|
67
119
|
}
|
|
68
120
|
}
|
|
69
|
-
throw new Error(`Node ${MIN_NODE_MAJOR}+ is required for local pi-knowledge embeddings.
|
|
121
|
+
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.`);
|
|
70
122
|
}
|
|
71
123
|
function appendWorkerStderr(current, chunk) {
|
|
72
124
|
const next = `${current}${chunk.toString("utf-8")}`;
|
|
@@ -96,7 +148,7 @@ class ModelWorkerTransport {
|
|
|
96
148
|
pending = new Map();
|
|
97
149
|
stderrTail = "";
|
|
98
150
|
exited = false;
|
|
99
|
-
|
|
151
|
+
terminalError = null;
|
|
100
152
|
constructor(child) {
|
|
101
153
|
this.child = child;
|
|
102
154
|
child.stderr?.on("data", (chunk) => {
|
|
@@ -110,21 +162,21 @@ class ModelWorkerTransport {
|
|
|
110
162
|
this.rejectPending(formatWorkerExitError(code, signal, this.stderrTail));
|
|
111
163
|
});
|
|
112
164
|
child.on("error", (error) => {
|
|
113
|
-
this.
|
|
165
|
+
this.terminalError = formatWorkerSpawnError(error, this.stderrTail);
|
|
114
166
|
this.exited = true;
|
|
115
167
|
if (worker === this)
|
|
116
168
|
worker = null;
|
|
117
|
-
this.rejectPending(
|
|
169
|
+
this.rejectPending(this.terminalError);
|
|
118
170
|
});
|
|
119
171
|
}
|
|
120
172
|
isConnected() {
|
|
121
|
-
return !this.exited && !this.child.killed && !this.
|
|
173
|
+
return !this.exited && !this.child.killed && !this.terminalError && this.isTransportConnected();
|
|
122
174
|
}
|
|
123
175
|
request(message, signal) {
|
|
124
176
|
if (signal?.aborted)
|
|
125
177
|
throw new Error("Cancelled");
|
|
126
178
|
if (!this.isConnected())
|
|
127
|
-
throw new Error("Model worker is not connected");
|
|
179
|
+
throw this.terminalError ?? new Error("Model worker is not connected");
|
|
128
180
|
const id = nextRequestId++;
|
|
129
181
|
const { promise, resolve, reject } = Promise.withResolvers();
|
|
130
182
|
let abortHandler;
|
|
@@ -196,11 +248,11 @@ class IpcModelWorkerTransport extends ModelWorkerTransport {
|
|
|
196
248
|
this.ipcChild = ipcChild;
|
|
197
249
|
ipcChild.on("message", (message) => this.handleWorkerResponse(message));
|
|
198
250
|
}
|
|
199
|
-
static create(workerPath) {
|
|
251
|
+
static create(workerPath, nodeExecPath) {
|
|
200
252
|
let child;
|
|
201
253
|
try {
|
|
202
254
|
child = fork(workerPath, {
|
|
203
|
-
execPath:
|
|
255
|
+
execPath: nodeExecPath,
|
|
204
256
|
execArgv: getWorkerExecArgv(),
|
|
205
257
|
stdio: ["ignore", "ignore", "pipe", "ipc"],
|
|
206
258
|
env: process.env,
|
|
@@ -226,12 +278,18 @@ class IpcModelWorkerTransport extends ModelWorkerTransport {
|
|
|
226
278
|
class StdioModelWorkerTransport extends ModelWorkerTransport {
|
|
227
279
|
decoder = new StringDecoder("utf8");
|
|
228
280
|
stdoutBuffer = "";
|
|
229
|
-
constructor(workerPath) {
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
281
|
+
constructor(workerPath, nodeExecPath) {
|
|
282
|
+
let child;
|
|
283
|
+
try {
|
|
284
|
+
child = spawn(nodeExecPath, [...getWorkerExecArgv(), workerPath, "--stdio"], {
|
|
285
|
+
stdio: ["pipe", "pipe", "pipe"],
|
|
286
|
+
env: process.env,
|
|
287
|
+
windowsHide: true,
|
|
288
|
+
});
|
|
289
|
+
}
|
|
290
|
+
catch (error) {
|
|
291
|
+
throw formatWorkerSpawnError(toError(error), "");
|
|
292
|
+
}
|
|
235
293
|
super(child);
|
|
236
294
|
if (!child.stdin || !child.stdout) {
|
|
237
295
|
if (!child.killed)
|
|
@@ -279,7 +337,9 @@ function getWorker() {
|
|
|
279
337
|
if (worker?.isConnected())
|
|
280
338
|
return worker;
|
|
281
339
|
const workerPath = getWorkerPath();
|
|
282
|
-
|
|
340
|
+
const nodeExecPath = getNodeExecPath();
|
|
341
|
+
worker =
|
|
342
|
+
IpcModelWorkerTransport.create(workerPath, nodeExecPath) ?? new StdioModelWorkerTransport(workerPath, nodeExecPath);
|
|
283
343
|
return worker;
|
|
284
344
|
}
|
|
285
345
|
export async function embedInModelWorker(texts, prefix, signal) {
|
package/docs/configuration.md
CHANGED
|
@@ -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
|
|
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 common Node, Volta, NVM, and `PATH` locations before failing. If worker startup still fails, set `PI_KNOWLEDGE_NODE_PATH` to 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
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-knowledge",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.4",
|
|
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",
|