@nodetool-ai/runtime 0.7.0-rc.11

package/dist/python-stdio-bridge.js

@@ -0,0 +1,704 @@
+/**
+ * Python worker bridge using stdio transport.
+ *
+ * Communicates over stdin/stdout
+ * with length-prefixed msgpack framing instead of WebSocket.
+ * This eliminates WebSocket connection instability.
+ *
+ * Protocol: [4 bytes big-endian length][msgpack payload]
+ * Readiness: "NODETOOL_STDIO_READY" on stderr
+ * Logs: all Python output goes to stderr
+ */
+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 "./bridge-protocol.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";
+function isProductionMode() {
+    return process.env["NODETOOL_ENV"] === "production";
+}
+export class PythonStdioBridge extends EventEmitter {
+    _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);
+    /** Recent stderr lines from the worker for diagnostics. */
+    _recentStderr = [];
+    constructor(options = {}) {
+        super();
+        this._options = options;
+    }
+    // ── Connection lifecycle ───────────────────────────────────────────
+    async connect() {
+        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() {
+        const candidates = this._getPythonLaunchCandidates();
+        let lastError = null;
+        for (const candidate of candidates) {
+            try {
+                await this._spawnCandidate(candidate);
+                return;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+            }
+        }
+        throw (lastError ??
+            new Error(candidates.length === 0
+                ? "No Python interpreter found — Python nodes will not be available"
+                : "Failed to start Python worker (stdio)"));
+    }
+    async _spawnCandidate(candidate) {
+        const args = [
+            ...(candidate.argsPrefix ?? []),
+            "-m",
+            "nodetool.worker",
+            "--stdio",
+            ...(this._options.workerArgs ?? [])
+        ];
+        return new Promise((resolve, reject) => {
+            const proc = spawn(candidate.command, args, {
+                stdio: ["pipe", "pipe", "pipe"]
+            });
+            this._process = proc;
+            let ready = false;
+            let stderrOutput = "";
+            let settled = false;
+            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()}` : "")));
+            }, startupTimeoutMs);
+            const settleError = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(startupTimer);
+                reject(error);
+            };
+            const settleSuccess = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(startupTimer);
+                resolve();
+            };
+            // Stdout is binary protocol data — accumulate and parse frames.
+            proc.stdout.on("data", (chunk) => {
+                this._readBuffer = Buffer.concat([this._readBuffer, chunk]);
+                this._drainFrames();
+            });
+            // Stderr carries logs and the readiness signal.
+            proc.stderr.on("data", (chunk) => {
+                const text = chunk.toString();
+                stderrOutput += text;
+                this._rememberStderr(text);
+                this.emit("stderr", text);
+                if (!ready && text.includes("NODETOOL_STDIO_READY")) {
+                    ready = true;
+                    this._connected = true;
+                    settleSuccess();
+                }
+            });
+            proc.on("error", (err) => {
+                if (!ready)
+                    settleError(err);
+            });
+            proc.on("exit", (code) => {
+                this._connected = false;
+                if (!ready) {
+                    const detail = stderrOutput.trim();
+                    // The most common cause of this failure in shipped builds is that
+                    // the JS side was published ahead of the matching nodetool-core
+                    // Python wheel, so the older worker doesn't know `--stdio`. Give
+                    // users an actionable message instead of raw argparse output.
+                    if (/unrecognized arguments:.*--stdio/.test(detail)) {
+                        settleError(new Error("The bundled Python environment is outdated and does not " +
+                            "support the new stdio worker protocol. Please reinstall " +
+                            "the Python environment from Settings → Packages " +
+                            "(Reinstall environment) to update nodetool-core. " +
+                            `Worker source: ${candidate.source} (${candidate.command}).`));
+                        return;
+                    }
+                    settleError(new Error(detail ||
+                        `Python worker (${candidate.source}: ${candidate.command}) exited before startup with code ${code}`));
+                    return;
+                }
+                this.emit("exit", code);
+                const exitErr = new Error(`Python worker exited with code ${code}`);
+                for (const [, req] of this._pending) {
+                    req.reject(exitErr);
+                }
+                this._pending.clear();
+                for (const [, req] of this._pendingStream) {
+                    req.reject(exitErr);
+                }
+                this._pendingStream.clear();
+            });
+        });
+    }
+    // ── 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();
+                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}`));
+            }
+        }
+    }
+    // ── Send ───────────────────────────────────────────────────────────
+    _send(msg) {
+        if (!this._process?.stdin || !this._connected) {
+            throw new Error("Not connected to Python worker");
+        }
+        const payload = Buffer.from(msgpack.encode(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;
+            });
+        }
+        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;
+            });
+        }
+        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._process) {
+            // Close stdin — the Python side will exit cleanly.
+            this._process.stdin?.end();
+            this._process.kill();
+            this._process = null;
+        }
+        this._connected = false;
+    }
+    /** Check if a Python interpreter can be found (without spawning). */
+    hasPython() {
+        if (isProductionMode() && !PYTHON_BRIDGE_ALLOWED_IN_PRODUCTION) {
+            return false;
+        }
+        return this._getPythonLaunchCandidates().length > 0;
+    }
+    getRecentStderrLines(limit = 12) {
+        return this._recentStderr.slice(-limit);
+    }
+    getRecentStderrSummary(limit = 12) {
+        const lines = this.getRecentStderrLines(limit)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .filter((line) => line !== "NODETOOL_STDIO_READY");
+        if (lines.length === 0)
+            return null;
+        return lines.join(" | ");
+    }
+    _rememberStderr(text) {
+        for (const rawLine of text.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (!line)
+                continue;
+            this._recentStderr.push(line);
+        }
+        if (this._recentStderr.length > 200) {
+            this._recentStderr.splice(0, this._recentStderr.length - 200);
+        }
+    }
+    // ── Python path detection ───────────────────────────────────────────
+    _getPythonLaunchCandidates() {
+        const explicitPythonPath = this._options.pythonPath ?? process.env.NODETOOL_PYTHON;
+        if (explicitPythonPath) {
+            return [{ command: explicitPythonPath, source: "NODETOOL_PYTHON" }];
+        }
+        const condaPrefix = process.env.CONDA_PREFIX;
+        if (condaPrefix && this._looksLikeNodeToolEnv(condaPrefix)) {
+            const activeEnvPython = process.platform === "win32"
+                ? join(condaPrefix, "python.exe")
+                : join(condaPrefix, "bin", "python");
+            if (existsSync(activeEnvPython)) {
+                return [{ command: activeEnvPython, source: "active CONDA_PREFIX" }];
+            }
+        }
+        return this._getManagedPythonPaths().map((command) => ({
+            command,
+            source: "NodeTool-managed env"
+        }));
+    }
+    _looksLikeNodeToolEnv(envPath) {
+        const normalized = envPath.replaceAll("\\", "/").toLowerCase();
+        const envName = basename(envPath).toLowerCase();
+        return (envName === "nodetool" ||
+            envName === "conda_env" ||
+            normalized.includes("/nodetool/conda_env"));
+    }
+    _getManagedPythonPaths() {
+        const home = homedir();
+        if (process.platform === "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"),
+                join(home, "Miniconda3", "envs", "nodetool", "python.exe"),
+                join(home, "miniconda3", "envs", "nodetool", "python.exe"),
+                join(home, "Anaconda3", "envs", "nodetool", "python.exe"),
+                join(home, "anaconda3", "envs", "nodetool", "python.exe"),
+                String.raw `C:\ProgramData\nodetool\conda_env\python.exe`
+            ].filter((c, i, a) => existsSync(c) && a.indexOf(c) === i);
+        }
+        if (process.platform === "darwin") {
+            return [
+                join(home, "nodetool_env", "bin", "python"),
+                join(home, "miniconda3", "envs", "nodetool", "bin", "python"),
+                join(home, "anaconda3", "envs", "nodetool", "bin", "python")
+            ].filter((c, i, a) => existsSync(c) && a.indexOf(c) === i);
+        }
+        return [
+            join(home, ".local", "share", "nodetool", "conda_env", "bin", "python"),
+            "/opt/nodetool/conda_env/bin/python",
+            join(home, "miniconda3", "envs", "nodetool", "bin", "python"),
+            join(home, "anaconda3", "envs", "nodetool", "bin", "python")
+        ].filter((c, i, a) => existsSync(c) && a.indexOf(c) === i);
+    }
+}
+//# sourceMappingURL=python-stdio-bridge.js.map