@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.2

package/dist/python-stdio-bridge.js

@@ -8,69 +8,55 @@
  * Protocol: [4 bytes big-endian length][msgpack payload]
  * Readiness: "NODETOOL_STDIO_READY" on stderr
  * Logs: all Python output goes to stderr
+ *
+ * Transport-agnostic protocol logic lives in PythonBridgeBase; this subclass
+ * supplies the stdio transport (subprocess spawn + length-prefixed framing).
  */
-import * as msgpack from "@msgpack/msgpack";
-import { randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
-import { EventEmitter } from "node:events";
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, join } from "node:path";
-import { createLogger } from "@nodetool-ai/config";
-import { BRIDGE_PROTOCOL_VERSION, MIN_NODETOOL_CORE_VERSION } from "@nodetool-ai/protocol/bridge-protocol";
+import { packBridgeMessage, unpackBridgeMessage } from "./python-bridge-codec.js";
+import { getNodeBuiltinSync } from "@nodetool-ai/config";
+// Python bridge is fundamentally Node-only (subprocess + raw FDs).
+// Lazy-load the builtins so the module *graph* loads off-Node;
+// instantiating PythonStdioBridge there throws at construction.
+const nodeCp = getNodeBuiltinSync("node:child_process");
+const nodeFs = getNodeBuiltinSync("node:fs");
+const nodeOs = getNodeBuiltinSync("node:os");
+const nodePath = getNodeBuiltinSync("node:path");
+function notOnNode(api) {
+    throw new Error(`${api} requires Node — PythonStdioBridge is Node-only`);
+}
+const spawn = (...args) => nodeCp ? nodeCp.spawn(...args) : notOnNode("node:child_process.spawn");
+const existsSync = (p) => nodeFs ? nodeFs.existsSync(p) : notOnNode("node:fs.existsSync");
+const homedir = () => nodeOs ? nodeOs.homedir() : notOnNode("node:os.homedir");
+const basename = (p) => nodePath ? nodePath.basename(p) : notOnNode("node:path.basename");
+const join = (...parts) => nodePath ? nodePath.join(...parts) : notOnNode("node:path.join");
+import { createLogger, getByteLimitEnv, safeProcessEnv, safeProcessPlatform } from "@nodetool-ai/config";
+import { PythonBridgeBase } from "./python-bridge-base.js";
+import { encodeFrame, FrameDecoder, FrameSizeError } from "./python-bridge-framing.js";
 const log = createLogger("nodetool.runtime.python-stdio-bridge");
-const MAX_BRIDGE_FRAME_SIZE = Number(process.env["NODETOOL_BRIDGE_MAX_FRAME_SIZE"] ?? 256 * 1024 * 1024);
-const PYTHON_BRIDGE_ALLOWED_IN_PRODUCTION = process.env["NODETOOL_ALLOW_PYTHON_BRIDGE_IN_PRODUCTION"] === "1";
+const MAX_BRIDGE_FRAME_SIZE = getByteLimitEnv("NODETOOL_BRIDGE_MAX_FRAME_SIZE", 256 * 1024 * 1024);
+const PYTHON_BRIDGE_ALLOWED_IN_PRODUCTION = safeProcessEnv()["NODETOOL_ALLOW_PYTHON_BRIDGE_IN_PRODUCTION"] === "1";
 function isProductionMode() {
-    return process.env["NODETOOL_ENV"] === "production";
+    return safeProcessEnv()["NODETOOL_ENV"] === "production";
 }
-export class PythonStdioBridge extends EventEmitter {
+export class PythonStdioBridge extends PythonBridgeBase {
     _process = null;
-    _nodeMetadata = [];
-    _loadErrors = [];
-    _workerStatus = null;
-    _pending = new Map();
-    _pendingStream = new Map();
-    _options;
-    _connected = false;
-    _connectPromise = null;
-    /** Buffered stdout data waiting to be parsed into frames. */
-    _readBuffer = Buffer.alloc(0);
+    /** Incremental length-prefixed frame decoder for stdout. */
+    _frameDecoder = new FrameDecoder({
+        maxFrameSize: MAX_BRIDGE_FRAME_SIZE
+    });
     /** Recent stderr lines from the worker for diagnostics. */
     _recentStderr = [];
     constructor(options = {}) {
-        super();
-        this._options = options;
+        super(options);
     }
-    // ── Connection lifecycle ───────────────────────────────────────────
-    async connect() {
+    // ── Connection guard ───────────────────────────────────────────────
+    _assertCanConnect() {
         if (isProductionMode() && !PYTHON_BRIDGE_ALLOWED_IN_PRODUCTION) {
             throw new Error("Python bridge is disabled in production. Python workers are a local-only feature.");
         }
-        await this._spawnAndConnect();
-        await this._discover();
-        try {
-            await this.getWorkerStatus();
-        }
-        catch (err) {
-            log.warn("Failed to fetch initial Python worker status; load_errors will be unavailable until next status fetch", err);
-        }
     }
-    ensureConnected() {
-        if (this._connected)
-            return Promise.resolve();
-        if (!this._connectPromise) {
-            this._connectPromise = this.connect().then(() => {
-                this._connectPromise = null;
-            }, (err) => {
-                this._connectPromise = null;
-                throw err;
-            });
-        }
-        return this._connectPromise;
-    }
-    // ── Spawn & stdio setup ────────────────────────────────────────────
-    async _spawnAndConnect() {
+    // ── Transport: spawn & stdio setup ─────────────────────────────────
+    async _openTransport() {
         const candidates = this._getPythonLaunchCandidates();
         let lastError = null;
         for (const candidate of candidates) {
@@ -97,7 +83,22 @@ export class PythonStdioBridge extends EventEmitter {
         ];
         return new Promise((resolve, reject) => {
             const proc = spawn(candidate.command, args, {
-                stdio: ["pipe", "pipe", "pipe"]
+                stdio: ["pipe", "pipe", "pipe"],
+                env: {
+                    // Default before the spread so a user-set value still wins. Reduces
+                    // CUDA allocator fragmentation (the WDDM PCIe-spill on VAE decode);
+                    // only takes effect when set before torch initializes CUDA, which is
+                    // why it belongs here rather than in a node's process().
+                    PYTORCH_CUDA_ALLOC_CONF: "expandable_segments:True",
+                    // The options object is built before `spawn` runs, so a bare
+                    // `process.env` here would throw `ReferenceError` off-Node instead
+                    // of the `notOnNode("node:child_process.spawn")` this file goes out
+                    // of its way to raise.
+                    ...safeProcessEnv(),
+                    TQDM_DISABLE: "1",
+                    HF_HUB_DISABLE_PROGRESS_BARS: "1",
+                    TRANSFORMERS_VERBOSITY: "error"
+                }
             });
             this._process = proc;
             let ready = false;
@@ -106,13 +107,34 @@ export class PythonStdioBridge extends EventEmitter {
             const startupTimeoutMs = this._options.startupTimeoutMs ?? 20000;
             const startupTimer = setTimeout(() => {
                 settleError(new Error(`Python worker did not become ready within ${startupTimeoutMs}ms.` +
-                    (stderrOutput.trim() ? ` Recent stderr: ${stderrOutput.trim()}` : "")));
+                    (stderrOutput.trim()
+                        ? ` Recent stderr: ${stderrOutput.trim()}`
+                        : "")));
             }, startupTimeoutMs);
             const settleError = (error) => {
                 if (settled)
                     return;
                 settled = true;
                 clearTimeout(startupTimer);
+                // Tear down this candidate so a timed-out or failed spawn doesn't leak:
+                // its stdout handler would keep appending to the SHARED frame decoder
+                // (desyncing the next candidate's frame stream) and the heavy worker
+                // (mid torch/CUDA import) would stay alive forever.
+                proc.stdout?.removeAllListeners();
+                proc.stderr?.removeAllListeners();
+                proc.stdin?.removeAllListeners();
+                proc.stdin?.on("error", () => { });
+                try {
+                    proc.kill();
+                }
+                catch {
+                    // already dead
+                }
+                if (this._process === proc) {
+                    this._process = null;
+                    this._connected = false;
+                }
+                this._frameDecoder.reset();
                 reject(error);
             };
             const settleSuccess = () => {
@@ -124,8 +146,7 @@ export class PythonStdioBridge extends EventEmitter {
             };
             // Stdout is binary protocol data — accumulate and parse frames.
             proc.stdout.on("data", (chunk) => {
-                this._readBuffer = Buffer.concat([this._readBuffer, chunk]);
-                this._drainFrames();
+                this._drainFrames(chunk);
             });
             // Stderr carries logs and the readiness signal.
             proc.stderr.on("data", (chunk) => {
@@ -143,6 +164,20 @@ export class PythonStdioBridge extends EventEmitter {
                 if (!ready)
                     settleError(err);
             });
+            // stdin is a separate stream (EventEmitter) from the ChildProcess, so
+            // proc.on("error") does NOT cover write failures. Without this listener a
+            // broken-pipe write (EPIPE/ECONNRESET while the worker is exiting) emits
+            // an unhandled 'error' that crashes the whole Node backend. Fail the
+            // in-flight requests instead.
+            proc.stdin.on("error", (err) => {
+                this._connected = false;
+                if (!ready) {
+                    settleError(err);
+                }
+                else {
+                    this._rejectAllPending(new Error(`Python worker stdin error: ${err.message}`));
+                }
+            });
             proc.on("exit", (code) => {
                 this._connected = false;
                 if (!ready) {
@@ -177,436 +212,64 @@ export class PythonStdioBridge extends EventEmitter {
         });
     }
     // ── Frame reader ───────────────────────────────────────────────────
-    /** Extract complete length-prefixed frames from _readBuffer. */
-    _drainFrames() {
-        while (this._readBuffer.length >= 4) {
-            const length = this._readBuffer.readUInt32BE(0);
-            if (length > MAX_BRIDGE_FRAME_SIZE) {
-                this.emit("error", new Error(`Incoming Python bridge frame exceeds max size (${length} > ${MAX_BRIDGE_FRAME_SIZE})`));
-                this.close();
+    /** Extract complete length-prefixed frames from a stdout chunk. */
+    _drainFrames(chunk) {
+        // Dispatch every valid frame as soon as `FrameDecoder.push` extracts it,
+        // so frames preceding a corrupt one (a bad length prefix later in the
+        // same chunk) still reach `_handleMessage` — only the protocol failure
+        // itself is deferred to after dispatch.
+        try {
+            this._frameDecoder.push(chunk, (payload) => {
+                try {
+                    const msg = unpackBridgeMessage(payload);
+                    this._handleMessage(msg);
+                }
+                catch (err) {
+                    throw new Error(`Failed to decode msgpack frame: ${err}`);
+                }
+            });
+        }
+        catch (err) {
+            if (err instanceof FrameSizeError) {
+                const stderrHint = this.getRecentStderrSummary(6);
+                const desyncHint = "This usually means the Python worker wrote non-protocol data to stdout " +
+                    "(for example a library print/progress bar), desynchronizing the msgpack frame stream.";
+                this._failProtocol(new Error(`${err.message}. ${desyncHint}` +
+                    (stderrHint ? ` Recent stderr: ${stderrHint}` : "")));
                 return;
             }
-            if (this._readBuffer.length < 4 + length)
-                break; // incomplete frame
-            const payload = this._readBuffer.subarray(4, 4 + length);
-            this._readBuffer = this._readBuffer.subarray(4 + length);
-            try {
-                const msg = msgpack.decode(payload);
-                this._handleMessage(msg);
-            }
-            catch (err) {
-                this.emit("error", new Error(`Failed to decode msgpack frame: ${err}`));
-            }
+            this._failProtocol(err instanceof Error ? err : new Error(String(err)));
         }
     }
+    _failProtocol(error) {
+        log.error(error.message);
+        this._rejectAllPending(error);
+        this.close();
+    }
     // ── Send ───────────────────────────────────────────────────────────
     _send(msg) {
         if (!this._process?.stdin || !this._connected) {
             throw new Error("Not connected to Python worker");
         }
-        const payload = Buffer.from(msgpack.encode(msg));
+        const payload = Buffer.from(packBridgeMessage(msg));
         if (payload.length > MAX_BRIDGE_FRAME_SIZE) {
             throw new Error(`Outgoing Python bridge frame exceeds max size (${payload.length} > ${MAX_BRIDGE_FRAME_SIZE})`);
         }
-        const header = Buffer.alloc(4);
-        header.writeUInt32BE(payload.length, 0);
-        this._process.stdin.write(header);
-        this._process.stdin.write(payload);
-    }
-    // ── Message dispatch ────────────────────────────────────────────────
-    _handleMessage(msg) {
-        const type = msg.type;
-        const requestId = msg.request_id;
-        if (type === "discover" && requestId) {
-            const pending = this._pending.get(requestId);
-            if (pending) {
-                const data = msg.data;
-                // Reject the discover promise if the worker's protocol is older
-                // than what this build of the JS runtime requires. Workers that
-                // pre-date the protocol_version field are treated as version 1
-                // (the initial protocol release) — they speak the same wire
-                // format as v1, they just don't announce it.
-                const workerVersion = typeof data.protocol_version === "number"
-                    ? data.protocol_version
-                    : 1;
-                if (workerVersion < BRIDGE_PROTOCOL_VERSION) {
-                    this._pending.delete(requestId);
-                    pending.reject(new Error(`The installed nodetool-core speaks bridge protocol v${workerVersion}, ` +
-                        `but this Nodetool build requires v${BRIDGE_PROTOCOL_VERSION}. ` +
-                        `Please reinstall the Python environment from Settings → Packages ` +
-                        `(Reinstall environment) — it will fetch nodetool-core>=${MIN_NODETOOL_CORE_VERSION}.`));
-                    return;
-                }
-                if (workerVersion > BRIDGE_PROTOCOL_VERSION) {
-                    // Forward-compat: a newer worker is expected to keep speaking
-                    // older protocols, so we proceed with a warning.
-                    this.emit("stderr", `[python-bridge] Worker protocol v${workerVersion} is newer than ` +
-                        `JS runtime v${BRIDGE_PROTOCOL_VERSION}; assuming backward compatibility.\n`);
-                }
-                this._nodeMetadata = data.nodes;
-                this._loadErrors = data.load_errors ?? [];
-                pending.resolve({ outputs: {}, blobs: {} });
-            }
-        }
-        else if (type === "result" && requestId) {
-            const streamReq = this._pendingStream.get(requestId);
-            if (streamReq) {
-                this._pendingStream.delete(requestId);
-                streamReq.resolve(msg.data);
-                return;
-            }
-            const pending = this._pending.get(requestId);
-            if (pending) {
-                this._pending.delete(requestId);
-                const data = msg.data;
-                pending.resolve({ outputs: data.outputs, blobs: data.blobs ?? {} });
-            }
-        }
-        else if (type === "error" && requestId) {
-            const streamReq = this._pendingStream.get(requestId);
-            if (streamReq) {
-                this._pendingStream.delete(requestId);
-                const data = msg.data;
-                const err = new Error(data.error);
-                err.traceback = data.traceback;
-                streamReq.reject(err);
-                return;
-            }
-            const pending = this._pending.get(requestId);
-            if (pending) {
-                this._pending.delete(requestId);
-                const data = msg.data;
-                const err = new Error(data.error);
-                err.traceback = data.traceback;
-                pending.reject(err);
-            }
-        }
-        else if (type === "chunk" && requestId) {
-            const streamReq = this._pendingStream.get(requestId);
-            if (streamReq) {
-                streamReq.onChunk(msg.data);
-            }
-        }
-        else if (type === "progress" && requestId) {
-            const pending = this._pending.get(requestId);
-            if (pending?.onProgress) {
-                const data = msg.data;
-                pending.onProgress({ request_id: requestId, ...data });
-            }
-            this.emit("progress", msg.data);
-        }
-    }
-    // ── Discover ───────────────────────────────────────────────────────
-    async _discover() {
-        const requestId = randomUUID();
-        return new Promise((resolve, reject) => {
-            this._pending.set(requestId, {
-                resolve: () => {
-                    this._pending.delete(requestId);
-                    resolve();
-                },
-                reject: (err) => {
-                    this._pending.delete(requestId);
-                    reject(err);
-                }
-            });
-            this._send({ type: "discover", request_id: requestId, data: {} });
-        });
-    }
-    // ── Node execution ─────────────────────────────────────────────────
-    async execute(nodeType, fields, secrets, blobs, onProgress) {
-        const requestId = randomUUID();
-        return new Promise((resolve, reject) => {
-            this._pending.set(requestId, { resolve, reject, onProgress });
-            this._send({
-                type: "execute",
-                request_id: requestId,
-                data: { node_type: nodeType, fields, secrets, blobs }
-            });
-        });
-    }
-    async *executeStream(nodeType, fields, secrets, blobs, onProgress) {
-        const requestId = randomUUID();
-        const chunks = [];
-        let done = false;
-        let error = null;
-        let finalResult = null;
-        let emittedCount = 0;
-        let resolveWait = null;
-        if (onProgress) {
-            this._pending.set(requestId, {
-                resolve: () => undefined,
-                reject: () => undefined,
-                onProgress
-            });
-        }
-        const onChunk = (chunk) => {
-            chunks.push({
-                outputs: chunk.outputs ?? {},
-                blobs: chunk.blobs ?? {}
-            });
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        };
-        const streamPromise = new Promise((resolve, reject) => {
-            this._pendingStream.set(requestId, { resolve, reject, onChunk });
-        });
-        streamPromise
-            .then((result) => {
-            finalResult = {
-                outputs: result.outputs ?? {},
-                blobs: result.blobs ?? {}
-            };
-            done = true;
-            this._pending.delete(requestId);
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        })
-            .catch((err) => {
-            error = err;
-            done = true;
-            this._pending.delete(requestId);
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        });
-        this._send({
-            type: "execute.stream",
-            request_id: requestId,
-            data: { node_type: nodeType, fields, secrets, blobs }
-        });
-        while (true) {
-            while (chunks.length > 0) {
-                emittedCount += 1;
-                yield chunks.shift();
-            }
-            if (done)
-                break;
-            if (error)
-                throw error;
-            await new Promise((resolve) => {
-                resolveWait = resolve;
-            });
-        }
-        if (error)
-            throw error;
-        if (emittedCount === 0 && finalResult) {
-            yield finalResult;
-        }
-    }
-    cancel(requestId) {
-        this._send({ type: "cancel", request_id: requestId, data: {} });
-    }
-    getNodeMetadata() {
-        return this._nodeMetadata;
-    }
-    getLoadErrors() {
-        return this._loadErrors;
-    }
-    async getWorkerStatus() {
-        const requestId = randomUUID();
-        const result = await new Promise((resolve, reject) => {
-            this._pendingStream.set(requestId, {
-                resolve,
-                reject,
-                onChunk: () => { }
-            });
-            this._send({ type: "worker.status", request_id: requestId, data: {} });
-        });
-        this._workerStatus =
-            result;
-        this._loadErrors = this._workerStatus.load_errors ?? this._loadErrors;
-        return this._workerStatus;
-    }
-    hasNodeType(nodeType) {
-        return this._nodeMetadata.some((n) => n.node_type === nodeType);
-    }
-    get isConnected() {
-        return this._connected;
-    }
-    // ── Provider bridge methods ────────────────────────────────────────
-    async listProviders() {
-        const result = await this._providerCall("provider.list", {});
-        return result.providers;
-    }
-    async getProviderModels(providerId, modelType, secrets) {
-        const result = await this._providerCall("provider.models", {
-            provider: providerId,
-            model_type: modelType,
-            secrets: secrets ?? {}
-        });
-        return result.models;
-    }
-    async providerGenerate(providerId, messages, model, options) {
-        const result = await this._providerCall("provider.generate", {
-            provider: providerId,
-            messages,
-            model,
-            ...options
-        });
-        return result.message;
-    }
-    async *providerStream(providerId, messages, model, options) {
-        const requestId = randomUUID();
-        const chunks = [];
-        let done = false;
-        let error = null;
-        let resolveWait = null;
-        const onChunk = (chunk) => {
-            chunks.push(chunk);
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        };
-        const streamPromise = new Promise((resolve, reject) => {
-            this._pendingStream.set(requestId, { resolve, reject, onChunk });
-        });
-        streamPromise
-            .then(() => {
-            done = true;
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        })
-            .catch((err) => {
-            error = err;
-            done = true;
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        });
-        this._send({
-            type: "provider.stream",
-            request_id: requestId,
-            data: { provider: providerId, messages, model, ...options }
-        });
-        while (true) {
-            while (chunks.length > 0)
-                yield chunks.shift();
-            if (done)
-                break;
-            if (error)
-                throw error;
-            await new Promise((resolve) => {
-                resolveWait = resolve;
-            });
+        // Writing to a broken pipe can throw synchronously (or emit 'error'); turn
+        // it into a rejected request rather than an uncaught exception.
+        try {
+            this._process.stdin.write(encodeFrame(payload));
         }
-        if (error)
-            throw error;
-    }
-    async providerTextToImage(providerId, params, secrets) {
-        const result = await this._providerCall("provider.text_to_image", {
-            provider: providerId,
-            params,
-            secrets: secrets ?? {}
-        });
-        return result.blobs.image;
-    }
-    async providerImageToImage(providerId, image, params, secrets) {
-        const result = await this._providerCall("provider.image_to_image", {
-            provider: providerId,
-            image,
-            params,
-            secrets: secrets ?? {}
-        });
-        return result.blobs.image;
-    }
-    async *providerTTS(providerId, text, model, options) {
-        const requestId = randomUUID();
-        const chunks = [];
-        let done = false;
-        let error = null;
-        let resolveWait = null;
-        const onChunk = (chunk) => {
-            const blobs = chunk.blobs;
-            if (blobs?.audio)
-                chunks.push(blobs.audio);
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        };
-        const streamPromise = new Promise((resolve, reject) => {
-            this._pendingStream.set(requestId, { resolve, reject, onChunk });
-        });
-        streamPromise
-            .then(() => {
-            done = true;
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        })
-            .catch((err) => {
-            error = err;
-            done = true;
-            if (resolveWait) {
-                resolveWait();
-                resolveWait = null;
-            }
-        });
-        this._send({
-            type: "provider.tts",
-            request_id: requestId,
-            data: { provider: providerId, text, model, ...options }
-        });
-        while (true) {
-            while (chunks.length > 0)
-                yield chunks.shift();
-            if (done)
-                break;
-            if (error)
-                throw error;
-            await new Promise((resolve) => {
-                resolveWait = resolve;
-            });
+        catch (err) {
+            this._connected = false;
+            throw new Error(`Failed to write to Python worker stdin: ${err instanceof Error ? err.message : String(err)}`);
         }
-        if (error)
-            throw error;
-    }
-    async providerASR(providerId, audio, model, options) {
-        const result = await this._providerCall("provider.asr", {
-            provider: providerId,
-            audio,
-            model,
-            ...options
-        });
-        const r = result;
-        return {
-            text: r.text,
-            chunks: r.chunks
-        };
-    }
-    async providerEmbedding(providerId, text, model, dimensions) {
-        const result = await this._providerCall("provider.embedding", {
-            provider: providerId,
-            text,
-            model,
-            dimensions
-        });
-        return result.embeddings;
-    }
-    async _providerCall(type, data) {
-        const requestId = randomUUID();
-        return new Promise((resolve, reject) => {
-            this._pendingStream.set(requestId, {
-                resolve,
-                reject,
-                onChunk: () => { }
-            });
-            this._send({ type, request_id: requestId, data });
-        });
     }
     // ── Shutdown ───────────────────────────────────────────────────────
     close() {
+        if (this._pending.size > 0 || this._pendingStream.size > 0) {
+            this._rejectAllPending(new Error("Python bridge closed"));
+        }
         if (this._process) {
             // Close stdin — the Python side will exit cleanly.
             this._process.stdin?.end();
@@ -614,6 +277,7 @@ export class PythonStdioBridge extends EventEmitter {
             this._process = null;
         }
         this._connected = false;
+        this._frameDecoder.reset();
     }
     /** Check if a Python interpreter can be found (without spawning). */
     hasPython() {
@@ -622,6 +286,14 @@ export class PythonStdioBridge extends EventEmitter {
         }
         return this._getPythonLaunchCandidates().length > 0;
     }
+    /**
+     * For the stdio transport, availability means a local Python interpreter was
+     * found (and the bridge is permitted to run in this environment). Delegates to
+     * {@link hasPython}.
+     */
+    isAvailable() {
+        return this.hasPython();
+    }
     getRecentStderrLines(limit = 12) {
         return this._recentStderr.slice(-limit);
     }
@@ -647,13 +319,13 @@ export class PythonStdioBridge extends EventEmitter {
     }
     // ── Python path detection ───────────────────────────────────────────
     _getPythonLaunchCandidates() {
-        const explicitPythonPath = this._options.pythonPath ?? process.env.NODETOOL_PYTHON;
+        const explicitPythonPath = this._options.pythonPath ?? safeProcessEnv().NODETOOL_PYTHON;
         if (explicitPythonPath) {
             return [{ command: explicitPythonPath, source: "NODETOOL_PYTHON" }];
         }
-        const condaPrefix = process.env.CONDA_PREFIX;
+        const condaPrefix = safeProcessEnv().CONDA_PREFIX;
         if (condaPrefix && this._looksLikeNodeToolEnv(condaPrefix)) {
-            const activeEnvPython = process.platform === "win32"
+            const activeEnvPython = safeProcessPlatform() === "win32"
                 ? join(condaPrefix, "python.exe")
                 : join(condaPrefix, "bin", "python");
             if (existsSync(activeEnvPython)) {
@@ -674,11 +346,12 @@ export class PythonStdioBridge extends EventEmitter {
     }
     _getManagedPythonPaths() {
         const home = homedir();
-        if (process.platform === "win32") {
+        const env = safeProcessEnv();
+        if (safeProcessPlatform() === "win32") {
             return [
-                process.env.ALLUSERSPROFILE
-                    ? join(process.env.ALLUSERSPROFILE, "nodetool", "conda_env", "python.exe")
-                    : join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "nodetool", "conda_env", "python.exe"),
+                env.ALLUSERSPROFILE
+                    ? join(env.ALLUSERSPROFILE, "nodetool", "conda_env", "python.exe")
+                    : join(env.APPDATA ?? join(home, "AppData", "Roaming"), "nodetool", "conda_env", "python.exe"),
                 join(home, "Miniconda3", "envs", "nodetool", "python.exe"),
                 join(home, "miniconda3", "envs", "nodetool", "python.exe"),
                 join(home, "Anaconda3", "envs", "nodetool", "python.exe"),
@@ -686,7 +359,7 @@ export class PythonStdioBridge extends EventEmitter {
                 String.raw `C:\ProgramData\nodetool\conda_env\python.exe`
             ].filter((c, i, a) => existsSync(c) && a.indexOf(c) === i);
         }
-        if (process.platform === "darwin") {
+        if (safeProcessPlatform() === "darwin") {
             return [
                 join(home, "nodetool_env", "bin", "python"),
                 join(home, "miniconda3", "envs", "nodetool", "bin", "python"),