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

package/dist/python-bridge-types.js

@@ -1,2 +1,50 @@
-export {};
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Wire readers
+// ---------------------------------------------------------------------------
+//
+// The bridge decodes msgpack, so a worker reply arrives as an untyped record.
+// These readers turn one into the declared shape. Every field carries its own
+// `.catch`, so a reply is never rejected: a field the worker omits or sends in
+// the wrong type falls back to the value below instead of riding on mistyped.
+// That is the one behavior change from the assertions these replaced — before,
+// a malformed field reached callers as if it were valid.
+export const comfyStatusInfoSchema = z
+    .object({
+    enabled: z.boolean().catch(false),
+    url: z.string().optional().catch(undefined),
+    reachable: z.boolean().optional().catch(undefined),
+    system_stats: z.record(z.string(), z.unknown()).optional().catch(undefined),
+    queue_remaining: z.number().optional().catch(undefined),
+    error: z.string().optional().catch(undefined),
+    api_v2: z.boolean().optional().catch(undefined)
+})
+    .loose();
+export const blenderStatusInfoSchema = z
+    .object({
+    enabled: z.boolean().catch(false),
+    version: z.string().optional().catch(undefined),
+    error: z.string().optional().catch(undefined)
+})
+    .loose();
+/**
+ * Load errors are forwarded verbatim: the entry shape varies by worker version
+ * (older workers key them by `node_type`), and every consumer only displays
+ * them, so narrowing here would drop fields rather than protect anyone.
+ */
+const workerLoadErrorSchema = z.custom();
+export const workerStatusSchema = z
+    .object({
+    protocol_version: z.number().catch(0),
+    node_count: z.number().catch(0),
+    provider_count: z.number().catch(0),
+    namespaces: z.array(z.string()).catch([]),
+    load_errors: z.array(workerLoadErrorSchema).catch([]),
+    transport: z.string().catch(""),
+    max_frame_size: z.number().catch(0),
+    model_prepare_backends: z.array(z.string()).catch([]),
+    comfy: comfyStatusInfoSchema.optional().catch(undefined),
+    blender: blenderStatusInfoSchema.optional().catch(undefined)
+})
+    .loose();
 //# sourceMappingURL=python-bridge-types.js.map

package/dist/python-bridge-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"python-bridge-types.js","sourceRoot":"","sources":["../src/python-bridge-types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"python-bridge-types.js","sourceRoot":"","sources":["../src/python-bridge-types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmuBxB,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAC9E,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,yDAAyD;AAEzD,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC;KACnC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;IACjC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IAC3C,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IAClD,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IAC3E,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IACvD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IAC7C,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;CAChD,CAAC;KACD,KAAK,EAAE,CAAC;AAEX,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC;KACrC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;IACjC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;CAC9C,CAAC;KACD,KAAK,EAAE,CAAC;AAEX;;;;GAIG;AACH,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,EAAyB,CAAC;AAEhE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IACrC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IACnC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;IACzC,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;IACrD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;IAC/B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IACnC,sBAAsB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;IACrD,KAAK,EAAE,qBAAqB,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IACxD,OAAO,EAAE,uBAAuB,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;CAC7D,CAAC;KACD,KAAK,EAAE,CAAC"}

package/dist/python-graph-resolver.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Python-worker support for graphs executed OUTSIDE the websocket server.
+ *
+ * The websocket server wires the Python bridge into its own `resolveExecutor`
+ * (see packages/websocket/src/plugins/websocket.ts). In-process runners — the
+ * `nodetool run` / `nodetool workflows run` CLI commands and the DSL `run()` —
+ * had no such wiring, so any Python worker node failed with "Unknown node
+ * type". These helpers give those runners the same capability.
+ *
+ * Transport is chosen by {@link createPythonBridge}: when `NODETOOL_WORKER_URL`
+ * (optionally with `NODETOOL_WORKER_TOKEN`) is set, a remote WebSocket worker is
+ * used; otherwise a local stdio worker is spawned.
+ */
+import { PythonNodeExecutor } from "./python-node-executor.js";
+import type { PythonBridgeBase } from "./python-bridge-base.js";
+import type { PythonBridgeOptions } from "./python-bridge-types.js";
+/** Minimal graph-node shape the resolver needs. */
+interface GraphNodeLike {
+    id: string;
+    type: string;
+    properties?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+}
+/**
+ * Connect a Python worker bridge for a graph, but ONLY when the graph contains a
+ * node type the TS registry cannot resolve (a candidate Python node). Pure-TS
+ * graphs get no bridge — no worker spawned, no remote connection — preserving
+ * the prior behavior and cost for workflows that don't need Python.
+ *
+ * Failure handling depends on whether a remote worker was explicitly requested:
+ * - `NODETOOL_WORKER_URL` set → a connect failure is surfaced (the caller asked
+ *   for a specific remote worker, so a silent fallthrough would hide a real
+ *   misconfiguration).
+ * - unset (local stdio attempt) → a connect failure returns `null` and is
+ *   logged, so an unresolved node still reports the normal "Unknown node type"
+ *   error rather than a confusing worker-spawn error.
+ *
+ * The caller owns the returned bridge and MUST `close()` it after the run.
+ *
+ * @param nodes         The graph nodes (only `.type` is read).
+ * @param hasTsExecutor Predicate: can the in-process TS registry resolve a type?
+ * @param options       Bridge options forwarded to {@link createPythonBridge}.
+ * @returns The connected bridge, or `null` when no Python node is present (or a
+ *          local worker was unavailable).
+ */
+export declare function connectPythonBridgeForGraph(nodes: ReadonlyArray<{
+    type?: unknown;
+}>, hasTsExecutor: (nodeType: string) => boolean, options?: PythonBridgeOptions): Promise<PythonBridgeBase | null>;
+/**
+ * Build a {@link PythonNodeExecutor} for a node when the bridge advertises its
+ * type, mirroring the websocket server's `resolveExecutor`. Returns `null` when
+ * there is no bridge or the bridge does not know the node type, so the caller
+ * can fall through to its own "unknown node type" error.
+ */
+export declare function resolvePythonNodeExecutor(bridge: PythonBridgeBase | null, node: GraphNodeLike): PythonNodeExecutor | null;
+export {};
+//# sourceMappingURL=python-graph-resolver.d.ts.map

package/dist/python-graph-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-graph-resolver.d.ts","sourceRoot":"","sources":["../src/python-graph-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAKpE,mDAAmD;AACnD,UAAU,aAAa;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,aAAa,CAAC;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,EACxC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,EAC5C,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA2BlC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,gBAAgB,GAAG,IAAI,EAC/B,IAAI,EAAE,aAAa,GAClB,kBAAkB,GAAG,IAAI,CAoB3B"}

package/dist/python-graph-resolver.js

@@ -0,0 +1,79 @@
+/**
+ * Python-worker support for graphs executed OUTSIDE the websocket server.
+ *
+ * The websocket server wires the Python bridge into its own `resolveExecutor`
+ * (see packages/websocket/src/plugins/websocket.ts). In-process runners — the
+ * `nodetool run` / `nodetool workflows run` CLI commands and the DSL `run()` —
+ * had no such wiring, so any Python worker node failed with "Unknown node
+ * type". These helpers give those runners the same capability.
+ *
+ * Transport is chosen by {@link createPythonBridge}: when `NODETOOL_WORKER_URL`
+ * (optionally with `NODETOOL_WORKER_TOKEN`) is set, a remote WebSocket worker is
+ * used; otherwise a local stdio worker is spawned.
+ */
+import { createLogger } from "@nodetool-ai/config";
+import { createPythonBridge } from "./python-bridge-factory.js";
+import { PythonNodeExecutor } from "./python-node-executor.js";
+import { isNonEmptyString } from "@nodetool-ai/protocol";
+const log = createLogger("nodetool.runtime.python-graph-resolver");
+/**
+ * Connect a Python worker bridge for a graph, but ONLY when the graph contains a
+ * node type the TS registry cannot resolve (a candidate Python node). Pure-TS
+ * graphs get no bridge — no worker spawned, no remote connection — preserving
+ * the prior behavior and cost for workflows that don't need Python.
+ *
+ * Failure handling depends on whether a remote worker was explicitly requested:
+ * - `NODETOOL_WORKER_URL` set → a connect failure is surfaced (the caller asked
+ *   for a specific remote worker, so a silent fallthrough would hide a real
+ *   misconfiguration).
+ * - unset (local stdio attempt) → a connect failure returns `null` and is
+ *   logged, so an unresolved node still reports the normal "Unknown node type"
+ *   error rather than a confusing worker-spawn error.
+ *
+ * The caller owns the returned bridge and MUST `close()` it after the run.
+ *
+ * @param nodes         The graph nodes (only `.type` is read).
+ * @param hasTsExecutor Predicate: can the in-process TS registry resolve a type?
+ * @param options       Bridge options forwarded to {@link createPythonBridge}.
+ * @returns The connected bridge, or `null` when no Python node is present (or a
+ *          local worker was unavailable).
+ */
+export async function connectPythonBridgeForGraph(nodes, hasTsExecutor, options) {
+    const needsPython = nodes.some((n) => isNonEmptyString(n.type) && !hasTsExecutor(n.type));
+    if (!needsPython)
+        return null;
+    const wsUrl = options?.wsUrl ?? process.env["NODETOOL_WORKER_URL"];
+    const bridge = createPythonBridge(options);
+    try {
+        await bridge.connect();
+        return bridge;
+    }
+    catch (err) {
+        bridge.close();
+        if (wsUrl && wsUrl.trim()) {
+            // Remote worker explicitly requested — surface the failure.
+            throw err;
+        }
+        // No remote configured and a local worker isn't available here; fall
+        // through so unresolved node types report the normal error.
+        log.warn(`Python worker bridge unavailable; Python nodes will be unresolved: ${String(err)}`);
+        return null;
+    }
+}
+/**
+ * Build a {@link PythonNodeExecutor} for a node when the bridge advertises its
+ * type, mirroring the websocket server's `resolveExecutor`. Returns `null` when
+ * there is no bridge or the bridge does not know the node type, so the caller
+ * can fall through to its own "unknown node type" error.
+ */
+export function resolvePythonNodeExecutor(bridge, node) {
+    if (!bridge || !bridge.hasNodeType(node.type))
+        return null;
+    const meta = bridge
+        .getNodeMetadata()
+        .find((m) => m.node_type === node.type);
+    const props = node.properties ?? node.data ?? {};
+    const outputTypes = Object.fromEntries((meta?.outputs ?? []).map((o) => [o.name, o.type.type]));
+    return new PythonNodeExecutor(bridge, node.type, props, outputTypes, meta?.required_settings ?? [], node.id, meta?.requires_vram_gb);
+}
+//# sourceMappingURL=python-graph-resolver.js.map

package/dist/python-graph-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-graph-resolver.js","sourceRoot":"","sources":["../src/python-graph-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,MAAM,GAAG,GAAG,YAAY,CAAC,wCAAwC,CAAC,CAAC;AAUnE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,KAAwC,EACxC,aAA4C,EAC5C,OAA6B;IAE7B,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAC5B,CAAC,CAAC,EAAE,EAAE,CACJ,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CACrD,CAAC;IACF,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAE9B,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YAC1B,4DAA4D;YAC5D,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,qEAAqE;QACrE,4DAA4D;QAC5D,GAAG,CAAC,IAAI,CACN,sEAAsE,MAAM,CAC1E,GAAG,CACJ,EAAE,CACJ,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAA+B,EAC/B,IAAmB;IAEnB,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3D,MAAM,IAAI,GAAG,MAAM;SAChB,eAAe,EAAE;SACjB,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;IACjD,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CACpC,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CACxD,CAAC;IAEF,OAAO,IAAI,kBAAkB,CAC3B,MAAM,EACN,IAAI,CAAC,IAAI,EACT,KAAK,EACL,WAAW,EACX,IAAI,EAAE,iBAAiB,IAAI,EAAE,EAC7B,IAAI,CAAC,EAAE,EACP,IAAI,EAAE,gBAAgB,CACvB,CAAC;AACJ,CAAC"}

package/dist/python-node-executor.d.ts

@@ -1,16 +1,48 @@
 import type { ProcessingContext } from "./context.js";
-import type { ExecuteInputBlobs, ExecuteResult, ProgressEvent } from "./python-bridge-types.js";
+import type { ExecuteIdentity, ExecuteInputBlobs, ExecuteResult, ProgressEvent } from "./python-bridge-types.js";
 /** Minimal interface for the local Python stdio bridge. */
 interface PythonBridgeLike {
-    execute(nodeType: string, fields: Record<string, unknown>, secrets: Record<string, string>, blobs: ExecuteInputBlobs, onProgress?: (event: ProgressEvent) => void): Promise<ExecuteResult>;
-    executeStream?(nodeType: string, fields: Record<string, unknown>, secrets: Record<string, string>, blobs: ExecuteInputBlobs, onProgress?: (event: ProgressEvent) => void): AsyncGenerator<ExecuteResult>;
+    execute(nodeType: string, fields: Record<string, unknown>, secrets: Record<string, string>, blobs: ExecuteInputBlobs, onProgress?: (event: ProgressEvent) => void, identity?: ExecuteIdentity): Promise<ExecuteResult>;
+    executeStream?(nodeType: string, fields: Record<string, unknown>, secrets: Record<string, string>, blobs: ExecuteInputBlobs, onProgress?: (event: ProgressEvent) => void, identity?: ExecuteIdentity): AsyncGenerator<ExecuteResult>;
 }
 export declare class PythonNodeExecutor {
     private bridge;
     private nodeType;
     private outputTypes;
     private requiredSettings;
-    constructor(bridge: PythonBridgeLike, nodeType: string, _properties: Record<string, unknown>, outputTypes: Record<string, string>, requiredSettings: string[]);
+    /** Graph node id, used to surface Python worker progress as node_progress. */
+    private nodeId?;
+    /**
+     * VRAM hint from this node type's `discover` metadata, forwarded on every
+     * execute so the worker can size its reclaim pass. Absent for a worker
+     * that does not report one.
+     */
+    private requiresVramGb?;
+    constructor(bridge: PythonBridgeLike, nodeType: string, _properties: Record<string, unknown>, outputTypes: Record<string, string>, requiredSettings: string[], 
+    /** Graph node id, used to surface Python worker progress as node_progress. */
+    nodeId?: string | undefined, 
+    /**
+     * VRAM hint from this node type's `discover` metadata, forwarded on every
+     * execute so the worker can size its reclaim pass. Absent for a worker
+     * that does not report one.
+     */
+    requiresVramGb?: number | undefined);
+    /**
+     * Run identity for the `execute` payload (bridge protocol v4).
+     *
+     * Before v4 the worker saw an unlabeled stream of single-node executions: it
+     * constructed every node with no id, so `self._id` was `""` for all of them
+     * and its node → model map collapsed into one bucket. `node_id` is what makes
+     * that map real; `job_id` is what pairs the execution with the `job.end`
+     * boundary that releases it.
+     */
+    private identity;
+    /**
+     * Build an onProgress sink that forwards the Python worker's progress events
+     * to the context message stream as `node_progress`. Returns undefined when we
+     * lack the context or node id needed to address the message.
+     */
+    private progressHandler;
     private prepareExecution;
     private materializeOutputs;
     process(inputs: Record<string, unknown>, context?: ProcessingContext): Promise<Record<string, unknown>>;

package/dist/python-node-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"python-node-executor.d.ts","sourceRoot":"","sources":["../src/python-node-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,aAAa,EACd,MAAM,0BAA0B,CAAC;AAKlC,2DAA2D;AAC3D,UAAU,gBAAgB;IACxB,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,KAAK,EAAE,iBAAiB,EACxB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B,aAAa,CAAC,CACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,KAAK,EAAE,iBAAiB,EACxB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,cAAc,CAAC,aAAa,CAAC,CAAC;CAClC;AAgJD,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ;IAEhB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,gBAAgB;gBAJhB,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,gBAAgB,EAAE,MAAM,EAAE;YAGtB,gBAAgB;YAyEhB,kBAAkB;IAwB1B,OAAO,CACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAY5B,UAAU,CACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAiB3C"}
+{"version":3,"file":"python-node-executor.d.ts","sourceRoot":"","sources":["../src/python-node-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,aAAa,EACd,MAAM,0BAA0B,CAAC;AAOlC,2DAA2D;AAC3D,UAAU,gBAAgB;IACxB,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,KAAK,EAAE,iBAAiB,EACxB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,EAC3C,QAAQ,CAAC,EAAE,eAAe,GACzB,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B,aAAa,CAAC,CACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,KAAK,EAAE,iBAAiB,EACxB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,EAC3C,QAAQ,CAAC,EAAE,eAAe,GACzB,cAAc,CAAC,aAAa,CAAC,CAAC;CAClC;AAgID,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ;IAEhB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,gBAAgB;IACxB,8EAA8E;IAC9E,OAAO,CAAC,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAAC;IAbzB,YACU,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,gBAAgB,EAAE,MAAM,EAAE;IAClC,8EAA8E;IACtE,MAAM,CAAC,EAAE,MAAM,YAAA;IACvB;;;;OAIG;IACK,cAAc,CAAC,EAAE,MAAM,YAAA,EAC7B;IAEJ;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ;IAoBhB;;;;OAIG;IACH,OAAO,CAAC,eAAe;YAgBT,gBAAgB;YAyEhB,kBAAkB;IA6D1B,OAAO,CACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAYlC;IAEM,UAAU,CACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAiBzC;CACF"}

package/dist/python-node-executor.js

@@ -1,8 +1,15 @@
-import { createLogger } from "@nodetool-ai/config";
+import { loadMediaRefBytes } from "./media-ref-bytes.js";
+import { isString } from "@nodetool-ai/protocol";
+import { createLogger, getNodeBuiltinSync } from "@nodetool-ai/config";
 const log = createLogger("nodetool.runtime.python-node-executor");
-import { readFile } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
-import { fileURLToPath } from "node:url";
+const _nodeCrypto = getNodeBuiltinSync("node:crypto");
+const randomUUID = () => _nodeCrypto?.randomUUID
+    ? _nodeCrypto.randomUUID()
+    : globalThis.crypto?.randomUUID
+        ? globalThis.crypto.randomUUID()
+        : (() => {
+            throw new Error("node:crypto.randomUUID requires Node");
+        })();
 /** Media ref types that need blob conversion. */
 const MEDIA_TYPE_ALIASES = {
     ImageRef: "image",
@@ -14,20 +21,81 @@ const MEDIA_TYPE_ALIASES = {
     video: "video",
     model_3d: "model_3d"
 };
-/** File extensions by ref type. */
+/** Fallback extension when the ref names no format. */
 const EXTENSION_MAP = {
     image: ".png",
     audio: ".wav",
     video: ".mp4",
     model_3d: ".glb"
 };
-/** MIME types by ref type. */
+/** Fallback MIME type when the ref names no format. */
 const MIME_MAP = {
     image: "image/png",
     audio: "audio/wav",
     video: "video/mp4",
     model_3d: "model/gltf-binary"
 };
+/**
+ * MIME type per declared ref format. A ref that says `format: "jpeg"` must not
+ * be stored as `.png` with `image/png`: the extension decides how a browser
+ * and every downstream reader treat the bytes.
+ *
+ * A format absent from this table still shapes the extension — the entry only
+ * decides the content type, which falls back to the media kind's default.
+ */
+const FORMAT_MIME_MAP = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    webp: "image/webp",
+    gif: "image/gif",
+    bmp: "image/bmp",
+    tiff: "image/tiff",
+    wav: "audio/wav",
+    mp3: "audio/mpeg",
+    flac: "audio/flac",
+    ogg: "audio/ogg",
+    opus: "audio/opus",
+    m4a: "audio/mp4",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mov: "video/quicktime",
+    mkv: "video/x-matroska",
+    avi: "video/x-msvideo",
+    glb: "model/gltf-binary",
+    gltf: "model/gltf+json",
+    obj: "model/obj",
+    stl: "model/stl",
+    ply: "model/mesh",
+    fbx: "application/octet-stream"
+};
+/**
+ * The format a ref declares, as a storage-key-safe token, or null.
+ *
+ * The value is node-controlled and lands in a storage key, so anything but a
+ * short alphanumeric token is refused rather than sanitized — a format of
+ * `../../etc` has no legitimate reading.
+ */
+function refFormat(ref) {
+    const raw = ref?.["format"];
+    if (!isString(raw))
+        return null;
+    const format = raw.trim().toLowerCase();
+    return /^[a-z0-9]{1,8}$/.test(format) ? format : null;
+}
+/** True when a ref's `data` holds raw bytes rather than an inline payload. */
+function isBinaryPayload(value) {
+    if (value instanceof Uint8Array || value instanceof ArrayBuffer)
+        return true;
+    return (Array.isArray(value) &&
+        value.some((item) => item instanceof Uint8Array || item instanceof ArrayBuffer));
+}
+/** The ref the worker sent for this output slot, if it sent one. */
+function carriedRef(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
 function normalizeMediaOutputType(outputType) {
     if (!outputType) {
         return null;
@@ -43,86 +111,75 @@ function isMediaRef(value) {
 function isMediaRefList(value) {
     return Array.isArray(value) && value.every(isMediaRef);
 }
-const ASSET_ID_EXTENSION_CANDIDATES = {
-    image: ["png", "jpg", "jpeg", "webp", "gif", "bmp", "svg"],
-    audio: ["wav", "mp3", "ogg", "m4a", "aac", "flac"],
-    video: ["mp4", "webm", "mov", "avi", "mpeg", "mkv"],
-    model3d: ["glb", "gltf", "obj", "fbx"]
-};
-function isAbsoluteFilePath(uri) {
-    return (/^[A-Za-z]:[\\/]/.test(uri) || uri.startsWith("\\\\") || uri.startsWith("/"));
-}
-async function readUriBytes(uri) {
-    if (uri.startsWith("data:")) {
-        const parts = uri.split(",", 2);
-        if (parts.length !== 2) {
-            return null;
-        }
-        const [header, data] = parts;
-        const bytes = header.includes(";base64")
-            ? Buffer.from(data, "base64")
-            : Buffer.from(decodeURIComponent(data), "utf-8");
-        return new Uint8Array(bytes);
-    }
-    if (uri.startsWith("file://")) {
-        try {
-            return await readFile(fileURLToPath(uri));
-        }
-        catch {
-            return null;
-        }
-    }
-    if (isAbsoluteFilePath(uri)) {
-        try {
-            return await readFile(uri);
-        }
-        catch {
-            return null;
-        }
-    }
-    return null;
-}
-async function loadMediaRefBytes(value, context) {
-    // Inline base64 data takes priority over uri
-    const data = value.data;
-    if (typeof data === "string" && data.length > 0) {
-        return new Uint8Array(Buffer.from(data, "base64"));
-    }
-    if (data instanceof Uint8Array) {
-        return data;
-    }
-    if (!value.uri) {
-        return null;
-    }
-    if (context?.storage) {
-        const candidates = new Set();
-        candidates.add(value.uri);
-        if (value.asset_id) {
-            const refType = (value.type ?? "").toLowerCase();
-            const extensions = ASSET_ID_EXTENSION_CANDIDATES[refType] ?? ["bin"];
-            for (const extension of extensions) {
-                candidates.add(`/api/storage/${value.asset_id}.${extension}`);
-            }
-        }
-        for (const candidate of candidates) {
-            const stored = await context.storage.retrieve(candidate);
-            if (stored !== null) {
-                return stored;
-            }
-        }
-    }
-    return readUriBytes(value.uri);
-}
 export class PythonNodeExecutor {
     bridge;
     nodeType;
     outputTypes;
     requiredSettings;
-    constructor(bridge, nodeType, _properties, outputTypes, requiredSettings) {
+    nodeId;
+    requiresVramGb;
+    constructor(bridge, nodeType, _properties, outputTypes, requiredSettings, 
+    /** Graph node id, used to surface Python worker progress as node_progress. */
+    nodeId, 
+    /**
+     * VRAM hint from this node type's `discover` metadata, forwarded on every
+     * execute so the worker can size its reclaim pass. Absent for a worker
+     * that does not report one.
+     */
+    requiresVramGb) {
         this.bridge = bridge;
         this.nodeType = nodeType;
         this.outputTypes = outputTypes;
         this.requiredSettings = requiredSettings;
+        this.nodeId = nodeId;
+        this.requiresVramGb = requiresVramGb;
+    }
+    /**
+     * Run identity for the `execute` payload (bridge protocol v4).
+     *
+     * Before v4 the worker saw an unlabeled stream of single-node executions: it
+     * constructed every node with no id, so `self._id` was `""` for all of them
+     * and its node → model map collapsed into one bucket. `node_id` is what makes
+     * that map real; `job_id` is what pairs the execution with the `job.end`
+     * boundary that releases it.
+     */
+    identity(context) {
+        const identity = {};
+        if (this.nodeId) {
+            identity.nodeId = this.nodeId;
+        }
+        if (context?.jobId) {
+            identity.jobId = context.jobId;
+        }
+        if (context?.workflowId) {
+            identity.workflowId = context.workflowId;
+        }
+        if (context?.userId) {
+            identity.userId = context.userId;
+        }
+        if (this.requiresVramGb != null) {
+            identity.requiresVramGb = this.requiresVramGb;
+        }
+        return identity;
+    }
+    /**
+     * Build an onProgress sink that forwards the Python worker's progress events
+     * to the context message stream as `node_progress`. Returns undefined when we
+     * lack the context or node id needed to address the message.
+     */
+    progressHandler(context) {
+        const nodeId = this.nodeId;
+        if (!context || !nodeId)
+            return undefined;
+        return (event) => {
+            context.postMessage({
+                type: "node_progress",
+                node_id: nodeId,
+                progress: event.progress,
+                total: event.total,
+                workflow_id: context.workflowId
+            });
+        };
     }
     async prepareExecution(inputs, context) {
         // NodeActor merges node.properties + edge inputs before calling process(),
@@ -142,10 +199,10 @@ export class PythonNodeExecutor {
                     key,
                     type: ref.type,
                     hasUri: Boolean(ref.uri),
-                    uriLength: typeof ref.uri === "string" ? ref.uri.length : 0,
+                    uriLength: isString(ref.uri) ? ref.uri.length : 0,
                     hasData: ref.data !== null && ref.data !== undefined,
                     dataType: typeof ref.data,
-                    dataLength: typeof ref.data === "string"
+                    dataLength: isString(ref.data)
                         ? ref.data.length
                         : ref.data instanceof Uint8Array
                             ? ref.data.length
@@ -184,15 +241,48 @@ export class PythonNodeExecutor {
         return { fields, blobs, secrets };
     }
     async materializeOutputs(result, context) {
-        const outputs = { ...result.outputs };
+        // Output names come across the Python bridge (node-controlled), so build a
+        // null-prototype object: a blob/output named "__proto__" or "constructor"
+        // then lands as a plain own key and can't reach the prototype setter.
+        // Downstream only does own-key ops (Object.keys, spread, msgpack/JSON), so a
+        // null-prototype object behaves identically for legitimate names.
+        const outputs = Object.assign(Object.create(null), result.outputs);
         for (const [name, blobData] of Object.entries(result.blobs)) {
-            const mediaType = normalizeMediaOutputType(this.outputTypes[name]);
+            // Guard the outputTypes lookup with Object.hasOwn so an external name like
+            // "constructor" can't resolve to an inherited Object.prototype member.
+            const mediaType = Object.hasOwn(this.outputTypes, name)
+                ? normalizeMediaOutputType(this.outputTypes[name])
+                : null;
+            // The ref the worker sent for this slot, when it sent one. Rebuilding a
+            // bare {uri, type} from the media kind drops everything else it carried —
+            // a VideoRef's duration and format, a Model3DRef's material_file and
+            // texture_files, which are what make the asset renderable.
+            // Guarded with Object.hasOwn for the same reason the outputTypes lookup
+            // is: a blob named "__proto__" would otherwise read Object.prototype and
+            // spread its members into the output.
+            const ref = Object.hasOwn(result.outputs, name)
+                ? carriedRef(result.outputs[name])
+                : null;
             if (mediaType && context?.storage) {
-                const ext = EXTENSION_MAP[mediaType] ?? "";
-                const contentType = MIME_MAP[mediaType];
+                const format = refFormat(ref);
+                const ext = format ? `.${format}` : (EXTENSION_MAP[mediaType] ?? "");
+                const contentType = (format ? FORMAT_MIME_MAP[format] : undefined) ?? MIME_MAP[mediaType];
                 const storageKey = `python-bridge/${randomUUID()}${ext}`;
                 const uri = await context.storage.store(storageKey, blobData, contentType);
-                outputs[name] = { uri, type: mediaType };
+                outputs[name] = { ...ref, uri, type: mediaType };
+                // The payload is the blob, now at `uri`. A ref that also carries bytes
+                // would duplicate a megabyte-scale payload downstream, so drop them —
+                // tested by value, since an inline non-binary payload (a dataframe's
+                // rows) is content and must survive.
+                if (ref && isBinaryPayload(ref["data"])) {
+                    delete outputs[name]["data"];
+                }
+            }
+            else if (mediaType) {
+                // No storage adapter available: keep the bytes inline but preserve the
+                // media kind so downstream nodes receive a typed ref (e.g. ImageRef),
+                // not a bare Uint8Array.
+                outputs[name] = { ...ref, type: mediaType, data: blobData };
             }
             else {
                 outputs[name] = blobData;
@@ -202,7 +292,8 @@ export class PythonNodeExecutor {
     }
     async process(inputs, context) {
         const { fields, blobs, secrets } = await this.prepareExecution(inputs, context);
-        const result = await this.bridge.execute(this.nodeType, fields, secrets, blobs, undefined);
+        log.info("Python node executor calling bridge", { nodeType: this.nodeType });
+        const result = await this.bridge.execute(this.nodeType, fields, secrets, blobs, this.progressHandler(context), this.identity(context));
         return this.materializeOutputs(result, context);
     }
     async *genProcess(inputs, context) {
@@ -211,7 +302,7 @@ export class PythonNodeExecutor {
             return;
         }
         const { fields, blobs, secrets } = await this.prepareExecution(inputs, context);
-        for await (const partial of this.bridge.executeStream(this.nodeType, fields, secrets, blobs, undefined)) {
+        for await (const partial of this.bridge.executeStream(this.nodeType, fields, secrets, blobs, this.progressHandler(context), this.identity(context))) {
             yield await this.materializeOutputs(partial, context);
         }
     }