@nodetool-ai/code-nodes 0.8.1

package/dist/nodes/code-node.js

@@ -0,0 +1,1010 @@
+/**
+ * Universal Code Node — sandboxed JavaScript execution via QuickJS WASM.
+ *
+ * Runs user code in an isolated QuickJS WebAssembly guest (see
+ * `@nodetool-ai/agents/js-sandbox`) with standard JavaScript plus the bridge
+ * APIs: fetch(), workspace (text/bytes/stat/mkdir/remove/copy/move/root),
+ * getSecret(), sleep(), progress(), crypto (randomUUID/digest/hmac), format,
+ * media (read a media input's bytes, build a media output) and the base64/hex
+ * helpers. Dynamic inputs arrive on the `inputs` object.
+ *
+ * On a server host the code also gets the `nodetool` object model — the
+ * platform as objects (`nodetool.workflows`, `nodetool.assets`, …), backed by
+ * the agent toolbelt through imported capability modules. The belt is loaded
+ * lazily and only on Node: the in-browser runner bundles this module, so the
+ * toolbelt (native canvas, IMAP, execution) must never sit in its static
+ * import graph. Without a belt, `nodetool.capabilities()` reports `{}` and
+ * every method throws naming its missing tool instead of a ReferenceError.
+ *
+ * Outputs leave the body through two host calls: `await emit(name, value)`
+ * streams one value downstream immediately, `await output(name, value)` sets a
+ * handle's final value, delivered as one bag when the body completes. The
+ * body's return value carries no outputs.
+ *
+ * Example:
+ *   // inputs: { x: 5, text: "hello" }
+ *   // code:
+ *   for (const word of inputs.text.split(" ")) await emit("word", word);
+ *   await output("sum", inputs.x + 10);
+ *   // streams { word: … } per word, then the final bag { sum: 15 }
+ *
+ * A body that calls neither runs the deprecated return/yield contract.
+ *
+ * Inputs arrive one of two ways. A body that never mentions `stream` runs once
+ * per incoming item with `inputs` holding that item's snapshot. A body that
+ * calls `stream` runs once for the whole stream and pulls values itself
+ * (`stream(name)`, `stream.any()`, `stream.first`, `stream.open`), executing
+ * through {@link CodeNode.run} — the kernel's streaming-input mode, which
+ * hydration selects per node from the body itself.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseNode, prop, CODE_INPUTS_GLOBAL, parseCodeBody, staticImportSpecifiers, hasReturnStatement, hasYieldStatement, wrapImplicitReturn, normalizeCodeOutput, usesEmitOutputContract, usesStreamInputContract } from "@nodetool-ai/node-sdk";
+import { runInSandbox, TOOLS_PRELUDE, NODETOOL_API_PRELUDE_FULL } from "@nodetool-ai/agents/js-sandbox";
+import { importHidden } from "@nodetool-ai/config";
+import { ALL_PLATFORMS, SANDBOX_CAPABILITY_PACK } from "@nodetool-ai/protocol";
+/** JS keywords that cannot be used as variable names. */
+const JS_RESERVED = new Set([
+    "abstract",
+    "arguments",
+    "await",
+    "boolean",
+    "break",
+    "byte",
+    "case",
+    "catch",
+    "char",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "double",
+    "else",
+    "enum",
+    "eval",
+    "export",
+    "extends",
+    "false",
+    "final",
+    "finally",
+    "float",
+    "for",
+    "function",
+    "goto",
+    "if",
+    "implements",
+    "import",
+    "in",
+    "instanceof",
+    "int",
+    "interface",
+    "let",
+    "long",
+    "native",
+    "new",
+    "null",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "return",
+    "short",
+    "static",
+    "super",
+    "switch",
+    "synchronized",
+    "this",
+    "throw",
+    "throws",
+    "transient",
+    "true",
+    "try",
+    "typeof",
+    "undefined",
+    "var",
+    "void",
+    "volatile",
+    "while",
+    "with",
+    "yield"
+]);
+// ---------------------------------------------------------------------------
+// The `nodetool` object model — toolbelt bridge
+// ---------------------------------------------------------------------------
+/**
+ * The guest prelude every run gets: the belt bridge over `__callTool`, then
+ * the `nodetool` object model on top of it. Both are plain strings, so
+ * prepending them costs nothing even where no belt exists — the object model
+ * degrades per namespace by design.
+ */
+const NODETOOL_PRELUDE = `${TOOLS_PRELUDE}\n${NODETOOL_API_PRELUDE_FULL}`;
+/**
+ * Bridge globals for a host with no toolbelt (browser runner, no context):
+ * the prelude builds zero wrappers, `nodetool.capabilities()` returns `{}`,
+ * and every `nodetool.*` method throws naming its missing tool.
+ */
+const NO_TOOLS_GLOBALS = {
+    __toolNames: [],
+    __callTool: async () => ({
+        ok: false,
+        error: "no tools in this environment"
+    })
+};
+let agentsModulePromise = null;
+let injectedAgentsModule = null;
+/**
+ * Hand the Code node the agents package a host already holds.
+ *
+ * The bare specifier below resolves in a workspace checkout and in the CLI,
+ * and resolves nowhere in the bundled backend: `bundle-backend.mjs` inlines
+ * every workspace package into `server.mjs` and stages only third-party
+ * externals, so `node_modules/@nodetool-ai/agents` does not exist in the
+ * packaged desktop app or in the Docker/Fly image. Without this, a Code node
+ * body in production runs with no toolbelt (`nodetool.capabilities()` is `{}`,
+ * `yt_dlp` is missing) and cannot import
+ * `@nodetool-ai/sandbox-nodetool/*` at all.
+ *
+ * The server calls this at bootstrap with the copy esbuild already inlined,
+ * which also keeps the run on one module instance — a staged second copy would
+ * carry its own capability registry.
+ */
+export function setCodeNodeAgentsModule(mod) {
+    injectedAgentsModule = mod;
+    agentsModulePromise = null;
+}
+/**
+ * The agents package index: the injected one, else loaded lazily and hidden
+ * from bundlers. `importHidden` answers `null` off Node, so a browser bundle
+ * never resolves the toolbelt's server-only dependencies, and a host that
+ * neither injects nor can resolve the specifier degrades the same way —
+ * no belt, no capability modules.
+ */
+function loadAgentsModule() {
+    if (injectedAgentsModule)
+        return Promise.resolve(injectedAgentsModule);
+    if (!agentsModulePromise) {
+        agentsModulePromise = importHidden("@nodetool-ai/agents").catch(() => null);
+    }
+    return agentsModulePromise;
+}
+let toolOverride = null;
+/**
+ * Test/host injection point: replace the assembled toolbelt with a fixed set
+ * (`[]` simulates a beltless host). Pass `null` to restore the default
+ * assembly.
+ */
+export function setCodeNodeTools(tools) {
+    toolOverride = tools;
+}
+/**
+ * The belt a JS script gets, from the one function that assembles it
+ * (`assembleSandboxToolbelt` in `@nodetool-ai/agents`). This used to be a
+ * second copy of that assembly with the comment "must match" — and it drifted:
+ * the Apify and SerpAPI capabilities were added to the shared belt and not to
+ * this copy, so `run_apify_actor` inside a Code node resolved to nothing and
+ * calling it failed with a bare `TypeError: not a function`.
+ */
+function assembleToolbelt(mod) {
+    return mod.assembleSandboxToolbelt();
+}
+/**
+ * The permission gate this run answers to: the one the host put on the
+ * context, or the headless gate when no host set one (invariant I-1).
+ *
+ * A kernel workflow run sets no key, so a shipped example with a Code node
+ * keeps running under `auto`. A body reached through a chat's `run_node`
+ * inherits that turn's live mode, so approving `run_node` is approval to run
+ * the node, not to run whatever its body calls.
+ */
+function codeNodeGate(mod, context) {
+    return mod.gateFromContext(context, "Code node");
+}
+/**
+ * Globals wiring the `tools`/`nodetool` preludes to a real tool bridge, or
+ * the inert stub when no belt is constructible. Tool execution needs a
+ * ProcessingContext; without one the stub keeps the prelude harmless.
+ *
+ * The belt is wrapped in the run's gate before the bridge sees it: the bridge
+ * calls `process()` directly, so an unwrapped belt would let a body call a
+ * write capability the host's mode blocks.
+ */
+async function toolBridgeGlobals(context) {
+    if (!context)
+        return NO_TOOLS_GLOBALS;
+    const mod = await loadAgentsModule();
+    if (!mod)
+        return NO_TOOLS_GLOBALS;
+    const tools = mod.gateTools(toolOverride ?? assembleToolbelt(mod), codeNodeGate(mod, context));
+    return mod.buildToolBridge({ tools, context }).globals;
+}
+/**
+ * Bags a node invocation may hold before `emit` blocks the guest. Exported so
+ * a test can drive the producer past the bound without guessing the number.
+ */
+export const EMIT_CHANNEL_CAPACITY = 64;
+/**
+ * A bounded async queue with one producer (the guest's `emit` bridge) and one
+ * consumer (the `genProcess` pump). `push` resolves once the item is in the
+ * queue, which is only below capacity — that resolution is the backpressure
+ * release. `take` resolves `null` when the channel is closed and drained, so
+ * the consumer cannot finish while bags are still queued.
+ */
+class BoundedChannel {
+    capacity;
+    items = [];
+    takers = [];
+    pushers = [];
+    closed = false;
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    async push(item) {
+        while (this.items.length >= this.capacity && !this.closed) {
+            await new Promise((resolve) => this.pushers.push(resolve));
+        }
+        if (this.closed)
+            return;
+        this.items.push(item);
+        this.takers.shift()?.();
+    }
+    async take() {
+        for (;;) {
+            if (this.items.length > 0) {
+                // SAFETY: the queue is non-empty here and nothing awaits before the
+                // shift. `T` may itself include `undefined`, so no runtime check can
+                // tell "empty" from "the item was undefined".
+                const item = this.items.shift();
+                this.pushers.shift()?.();
+                return item;
+            }
+            if (this.closed)
+                return null;
+            await new Promise((resolve) => this.takers.push(resolve));
+        }
+    }
+    /** No further pushes; queued items still drain. Wakes everyone waiting. */
+    close() {
+        this.closed = true;
+        while (this.takers.length > 0)
+            this.takers.shift()?.();
+        while (this.pushers.length > 0)
+            this.pushers.shift()?.();
+    }
+}
+/** Answer the guest gets for a take that never resolved into a value. */
+const END_OF_STREAM = { done: true };
+/**
+ * What the cancellation promise resolves to. Shaped as an exhausted iterator
+ * result rather than as a take, so racing it against `iterator.next()` yields
+ * one `IteratorResult` union that `done` narrows on its own.
+ */
+const CANCELLED_RESULT = {
+    done: true,
+    value: undefined
+};
+/**
+ * The host side of the guest's `stream` global: one inbox iterator per handle
+ * (plus one `any()` iterator), created on first use and driven one take at a
+ * time.
+ *
+ * Two takes on the same handle cannot run concurrently — an async generator
+ * rejects a `next()` while another is pending — so calls are serialized on a
+ * per-key promise chain. Distinct handles keep their own chain and proceed in
+ * parallel, which is what lets a body await two streams at once.
+ */
+class InputStreamBridge {
+    inputs;
+    perHandle = new Map();
+    anyIterator;
+    /** Per-key serialization: `null` is the `any()` iterator's own chain. */
+    chains = new Map();
+    cancelled;
+    constructor(inputs) {
+        this.inputs = inputs;
+        // A cancelled run must not leave the guest parked on a take that can no
+        // longer be answered: every pending and future take resolves as EOS, the
+        // body unwinds, and the sandbox's own abort ends the run.
+        this.cancelled = new Promise((resolve) => {
+            const signal = inputs.signal;
+            if (signal.aborted) {
+                resolve(CANCELLED_RESULT);
+                return;
+            }
+            signal.addEventListener("abort", () => resolve(CANCELLED_RESULT), {
+                once: true
+            });
+        });
+    }
+    take(handle) {
+        const previous = this.chains.get(handle);
+        const next = previous
+            ? previous.then(() => this.pull(handle), () => this.pull(handle))
+            : this.pull(handle);
+        this.chains.set(handle, next);
+        return next;
+    }
+    /** `stream.open(name)`: could this handle still produce a value? */
+    isOpen(handle) {
+        return (this.inputs.hasStream(handle) ||
+            this.inputs.hasBuffered?.(handle) === true);
+    }
+    async pull(handle) {
+        if (this.inputs.signal.aborted)
+            return END_OF_STREAM;
+        if (handle === null) {
+            const iterator = (this.anyIterator ??= this.inputs.any());
+            const result = await Promise.race([iterator.next(), this.cancelled]);
+            if (result.done === true)
+                return END_OF_STREAM;
+            const [source, value] = result.value;
+            return { done: false, handle: source, value: jsonSafe(value) };
+        }
+        let iterator = this.perHandle.get(handle);
+        if (!iterator) {
+            iterator = this.inputs.stream(handle);
+            this.perHandle.set(handle, iterator);
+        }
+        const result = await Promise.race([iterator.next(), this.cancelled]);
+        if (result.done === true)
+            return END_OF_STREAM;
+        return {
+            done: false,
+            handle,
+            value: jsonSafe(result.value)
+        };
+    }
+}
+export class CodeNode extends BaseNode {
+    static nodeType = "nodetool.code.Code";
+    static platforms = ALL_PLATFORMS;
+    static title = "Code";
+    static description = "Execute vanilla JavaScript in a sandboxed environment. " +
+        "APIs: fetch(), workspace.read/write/list/readBytes/writeBytes/stat/mkdir/remove/copy/move/root(), " +
+        "getSecret(), sleep(), progress(), crypto.digest/hmac/randomUUID/getRandomValues, " +
+        "format.number/date/relativeTime/list, " +
+        "media.bytes/text/info to read a document, image, audio or video input and " +
+        "media.toDocument/toImage/toAudio/toVideo to return one, " +
+        "toBase64/fromBase64/toHex/fromHex, parallelMap, plus the `nodetool` object model " +
+        "(workflows, assets, jobs, …) backed by platform tools on server hosts — " +
+        "nodetool.capabilities() reports what is live. Tool-backed calls can spend money " +
+        "(media generation, workflow runs) and reach the web; each tool applies its own " +
+        "permission gating. " +
+        "Dynamic inputs arrive on the `inputs` object; outputs leave through " +
+        "await emit(name, value) to stream a value now and await output(name, value) " +
+        "to set a handle's final value. The return value carries no outputs. " +
+        "A body that calls stream(name), stream.any(), stream.first(name) or " +
+        "stream.open(name) runs once and reads its connected inputs as they " +
+        "arrive, instead of once per item." +
+        "\n    code, javascript, script, function, dynamic, custom, logic, " +
+        "parse, transform, convert, format, compute, calculate, filter, map, " +
+        "merge, extract, json, csv, text, string, math, " +
+        "pdf, document, read document, image bytes, audio, video, file, media";
+    static inlineFields = ["code"];
+    static inputFields = [];
+    static supportsDynamicInputs = true;
+    static supportsDynamicOutputs = true;
+    /**
+     * Whether this node streams its inputs is a property of its body, not of the
+     * type: a body that calls `stream` drains its own inbox in {@link run},
+     * every other body keeps the buffered per-item invocation. Both hydration
+     * paths re-read the body through this hook, so editing the last `stream`
+     * call out flips the mode back with no saved flag involved.
+     */
+    static resolveStreamingInput = (node) => usesStreamInputContract(String(node?.properties?.code ?? ""));
+    /**
+     * Persistent state across streaming invocations; reset each workflow run.
+     * The guest owns the contents and the sandbox syncs them back marshalled, so
+     * what survives a call is what survives a JSON round trip.
+     */
+    _state = {};
+    async initialize() {
+        this._state = {};
+    }
+    /**
+     * Forward guest `progress(percent, message)` calls to the kernel as
+     * `node_progress` messages — the same channel the Python worker and the
+     * ComfyUI node use, so the editor's node progress bar picks them up.
+     */
+    progressSink(context) {
+        if (!context || !this.__node_id)
+            return undefined;
+        return (progress, message) => {
+            context.postMessage({
+                type: "node_progress",
+                node_id: this.__node_id,
+                progress,
+                total: 100,
+                chunk: message,
+                workflow_id: context.workflowId
+            });
+        };
+    }
+    /**
+     * Forward guest `console.*` calls as `log_update` messages — the same
+     * channel package-resolution warnings already use, so the editor's log
+     * panel shows them as they happen.
+     */
+    logSink(context) {
+        if (!context || !this.__node_id)
+            return undefined;
+        return (level, message) => {
+            this.postLog(context, message, consoleSeverity(level));
+        };
+    }
+    /** Post on the node's log channel, where the run has one. */
+    postLog(context, content, severity) {
+        if (!context || !this.__node_id)
+            return;
+        context.postMessage({
+            type: "log_update",
+            node_id: this.__node_id,
+            node_name: CodeNode.title,
+            content,
+            severity,
+            workflow_id: context.workflowId
+        });
+    }
+    /**
+     * Sandbox policy from the node's props. The sandbox clamps
+     * `maxResponseBodyBytes` to its own ceiling, so no clamping here.
+     *
+     * The two capability switches default to the restrictive value and are only
+     * ever widened by an explicit choice on this node — nothing the guest code
+     * can reach.
+     */
+    sandboxLimits(envelope) {
+        const mb = Number(this.max_response_mb ?? 1);
+        const declared = envelope.secrets
+            .map((name) => String(name).trim())
+            .filter((name) => name !== "");
+        return {
+            maxResponseBodyBytes: Number.isFinite(mb)
+                ? Math.round(mb * 1024 * 1024)
+                : undefined,
+            allowPrivateNetwork: this.allow_local_network === true,
+            filesystemAccess: this.allow_host_filesystem === true ? "host" : "workspace",
+            // An empty list is "no scope declared", not "no secrets": scoping is
+            // opt-in, so a node authored before it existed keeps the reach it had.
+            secretScope: declared.length > 0 ? declared : null
+        };
+    }
+    /**
+     * Resolve the packs the body imports through the host's catalog.
+     *
+     * The imports are the declaration: a static `import` of an installed pack is
+     * served, and nothing else is — same rule a JS script runs under, so a body
+     * moved between the two behaves identically. A body that imports no pack gets
+     * no loader at all. An import that cannot be served — no catalog in this
+     * process, an uninstalled pack, a module the host refused — fails the node
+     * here rather than as a resolve error inside the guest. Version and digest
+     * drift only warn: resolution uses what is installed, and saying so on the
+     * node's log is the whole remedy.
+     *
+     * NodeTool's own guest modules (`@nodetool-ai/sandbox-nodetool/*`) are not
+     * packs; {@link CodeNode.resolveCapabilities} mounts those.
+     */
+    resolveModules(envelope, context) {
+        const statements = importableStatements(envelope.code);
+        if (statements === null)
+            return undefined;
+        const specifiers = [
+            ...new Set(staticImportSpecifiers(statements).filter((specifier) => specifier !== SANDBOX_CAPABILITY_PACK &&
+                !specifier.startsWith(`${SANDBOX_CAPABILITY_PACK}/`)))
+        ];
+        if (specifiers.length === 0)
+            return undefined;
+        const catalog = context?.sandboxModuleCatalog;
+        if (!catalog) {
+            throw new Error(`Sandbox packages are not available in this process, so ${specifiers
+                .map((specifier) => `"${specifier}"`)
+                .join(", ")} cannot be imported.`);
+        }
+        const resolution = catalog.resolveForExecution(specifiers.map((specifier) => ({ specifier })));
+        const errors = resolution.statuses.filter((status) => status.status === "error");
+        if (errors.length > 0) {
+            throw new Error(errors
+                .map((status) => `${status.message} (pack "${status.packName}")`)
+                .join(" "));
+        }
+        for (const status of resolution.statuses) {
+            if (status.status !== "warning")
+                continue;
+            this.logWarning(context, `${status.message} (pack "${status.packName}")`);
+        }
+        return resolution;
+    }
+    /** Post a warning on the node's log channel, where the run has one. */
+    logWarning(context, content) {
+        this.postLog(context, content, "warning");
+    }
+    /**
+     * The globals every run gets, on either contract. Declared inputs arrive on
+     * one `inputs` object rather than as globals of their own name: sharing the
+     * global namespace with the sandbox API let an input called `env` or `data`
+     * shadow a bridge, and made every undeclared identifier ambiguous between a
+     * typo and a missing slot. State stays a direct reference so mutations
+     * persist across calls.
+     */
+    async sandboxGlobals(context) {
+        const allInputs = {
+            ...this.serialize(),
+            ...Object.fromEntries(this.dynamicProps)
+        };
+        return {
+            [CODE_INPUTS_GLOBAL]: deepCopyInputs(extractDynamicInputs(allInputs)),
+            state: this._state,
+            ...(await toolBridgeGlobals(context))
+        };
+    }
+    /** Milliseconds the guest may run, or undefined for no limit. */
+    timeoutMs(envelope) {
+        return envelope.timeoutSeconds > 0
+            ? envelope.timeoutSeconds * 1000
+            : undefined;
+    }
+    /**
+     * What this invocation runs: the node's own properties, always.
+     *
+     * Linking a script *materializes* it — the pinned version's code, secrets
+     * and timeout are copied onto the node when the link is made or
+     * updated, and the `script` property records only which version they came
+     * from. So execution needs no database, no resolver, and no await: the body
+     * a run executes is the body the graph carries, which is also the body
+     * hydration read to decide whether this node streams its inputs.
+     */
+    envelope() {
+        return {
+            code: String(this.code ?? "return {};"),
+            secrets: Array.isArray(this.secrets) ? this.secrets : [],
+            timeoutSeconds: Number(this.timeout ?? 30)
+        };
+    }
+    /**
+     * Everything a run of this node's body needs regardless of contract: the
+     * prelude, the node's own policy, its globals and its module resolution.
+     * Every execution path starts from this and adds only what its own contract
+     * needs (an emit sink, an input bridge, a cancellation signal).
+     */
+    async sandboxOptions(code, envelope, context) {
+        return {
+            code: `${NODETOOL_PRELUDE}\n${code}`,
+            context,
+            timeoutMs: this.timeoutMs(envelope),
+            globals: await this.sandboxGlobals(context),
+            limits: this.sandboxLimits(envelope),
+            onProgress: this.progressSink(context),
+            onLog: this.logSink(context),
+            modules: this.resolveModules(envelope, context),
+            capabilities: await this.resolveCapabilities(code, context)
+        };
+    }
+    /**
+     * NodeTool's own guest modules (`@nodetool-ai/sandbox-nodetool/*`) for the
+     * namespaces this body imports, or nothing when it imports none.
+     *
+     * They are not packs, so they never reach the catalog: the host decides what
+     * a run can reach, and it says so with the gate it put on the context. The
+     * run carries that gate, exactly as the belt does — the import path and the
+     * belt bridge are two doors onto the same capabilities, so one gated and the
+     * other not would be no gate at all. It is the wiring
+     * `mountJsScriptSandbox` builds for a JS script, over the Code node's own
+     * module resolution.
+     */
+    async resolveCapabilities(code, context) {
+        if (!context)
+            return undefined;
+        const mod = await loadAgentsModule();
+        if (!mod)
+            return undefined;
+        const mounted = await mod.mountCapabilityModules(code, mod.createCapabilityRun({
+            context,
+            gate: codeNodeGate(mod, context),
+            availableSecrets: mod.contextSecretAvailability(context)
+        }));
+        if (!mounted.ok) {
+            throw new Error(mounted.error.replace("The action imports", "The code imports"));
+        }
+        return mounted.mount;
+    }
+    async process(context) {
+        const envelope = this.envelope();
+        const code = envelope.code;
+        if (!usesEmitOutputContract(code)) {
+            // The legacy return/yield contract runs unwarned: the deprecation
+            // notice lives in validate_code, not in every run's message stream —
+            // reliability goldens and downstream consumers pin that stream.
+            return this.runLegacySingleShot(envelope, context);
+        }
+        const result = await runInSandbox(await this.sandboxOptions(code, envelope, context));
+        if (!result.success) {
+            throw new Error(result.error ?? "Code execution failed");
+        }
+        // Single-shot callers see no stream, so an emitted value would be lost.
+        // Precedence: a handle's final `output` value wins; where there is none,
+        // the LAST value emitted for that handle stands in.
+        const merged = {};
+        for (const { name, value } of result.emitted ?? []) {
+            merged[name] = value;
+        }
+        return { ...merged, ...(result.outputs ?? {}) };
+    }
+    /**
+     * Streaming-input execution: one invocation that drains its own inbox.
+     *
+     * The kernel calls this instead of the per-item path when the hydrated
+     * `is_streaming_input` flag is true, which for this node means the body
+     * calls `stream` (see {@link CodeNode.resolveStreamingInput}). The body runs
+     * once; `stream(name)` / `stream.any()` pull values out of `inputs` one take
+     * at a time, `emit` routes live through `outputs.emit`, and the `output`
+     * finals post as one bag when the body ends.
+     */
+    async run(inputs, outputs, context) {
+        const envelope = this.envelope();
+        const code = envelope.code;
+        if (!usesStreamInputContract(code)) {
+            // The kernel only routes here when hydration said the body streams, and
+            // hydration re-reads the body every time. Reaching this means a stale
+            // saved flag was trusted (a graph built with `withExplicitNodeFlags` and
+            // never hydrated), and there is no safe recovery: this path never
+            // delivers per-item invocations, so a buffered body would silently see
+            // none of its connected inputs. Fail loudly instead.
+            throw new Error("Code node is flagged streaming-input but its body never calls " +
+                "stream(...). Hydrate the graph against the node registry, or add " +
+                "a stream(name) call to consume the connected inputs.");
+        }
+        const bridge = new InputStreamBridge(inputs);
+        const abort = new AbortController();
+        const onCancel = () => abort.abort();
+        if (inputs.signal.aborted) {
+            abort.abort();
+        }
+        else {
+            inputs.signal.addEventListener("abort", onCancel, { once: true });
+        }
+        try {
+            const result = await runInSandbox({
+                ...(await this.sandboxOptions(code, envelope, context)),
+                signal: abort.signal,
+                // Awaited, so a downstream inbox at its bound blocks the guest's
+                // `emit` — the same backpressure the buffered pump gets from its
+                // channel, one link earlier.
+                onEmit: async (name, value) => {
+                    await outputs.emit(name, value);
+                },
+                onTakeInput: (handle) => bridge.take(handle),
+                onStreamOpen: (handle) => bridge.isOpen(handle)
+            });
+            // A cancelled run has nothing to report: the takes were unparked as
+            // end-of-stream and the body unwound on a signal it did not choose.
+            if (inputs.signal.aborted)
+                return;
+            if (!result.success) {
+                throw new Error(result.error ?? "Code execution failed");
+            }
+            // One bag, one frame: the finals of a single invocation belong together,
+            // so sibling handles share lineage instead of arriving as N items.
+            const finals = result.outputs ?? {};
+            if (Object.keys(finals).length > 0) {
+                await outputs.emitGroup(finals);
+            }
+        }
+        finally {
+            inputs.signal.removeEventListener("abort", onCancel);
+            abort.abort();
+        }
+    }
+    /** The deprecated return-bag path: implicit return, normalized output. */
+    async runLegacySingleShot(envelope, context) {
+        const code = envelope.code;
+        const body = hasReturnStatement(code) ? code : wrapImplicitReturn(code);
+        const result = await runInSandbox(await this.sandboxOptions(body, envelope, context));
+        if (!result.success) {
+            throw new Error(result.error ?? "Code execution failed");
+        }
+        return normalizeCodeOutput(result.result);
+    }
+    async *genProcess(context) {
+        const envelope = this.envelope();
+        if (usesEmitOutputContract(envelope.code)) {
+            yield* this.pumpEmitContract(envelope, context);
+            return;
+        }
+        if (!hasYieldStatement(envelope.code)) {
+            yield await this.runLegacySingleShot(envelope, context);
+            return;
+        }
+        yield* this.runLegacyStream(envelope, context);
+    }
+    /**
+     * The emit/output pump: start the run, hand every `emit` bag downstream as
+     * it happens, then post the final `output` bag once the run succeeds.
+     *
+     * The guest's `emit` promise resolves only when the channel has accepted its
+     * bag, so a producer faster than the kernel blocks at the channel bound —
+     * backpressure with no new kernel concept.
+     */
+    async *pumpEmitContract(envelope, context) {
+        const channel = new BoundedChannel(EMIT_CHANNEL_CAPACITY);
+        const abort = new AbortController();
+        let result;
+        let failure;
+        // Never rejects: the run's outcome is read after the drain, so a rejection
+        // parked on the promise would otherwise look unhandled while we pump.
+        const run = (async () => {
+            try {
+                result = await runInSandbox({
+                    ...(await this.sandboxOptions(envelope.code, envelope, context)),
+                    signal: abort.signal,
+                    onEmit: (name, value) => channel.push({ [name]: value })
+                });
+            }
+            catch (err) {
+                failure = err;
+            }
+            finally {
+                // Closing here is what ends the drain, and it happens only after the
+                // run has settled — so every bag pushed before that is still taken.
+                channel.close();
+            }
+        })();
+        try {
+            for (;;) {
+                const bag = await channel.take();
+                if (!bag)
+                    break;
+                yield bag;
+            }
+            await run;
+            if (failure)
+                throw failure;
+            if (!result || !result.success) {
+                throw new Error(result?.error ?? "Code execution failed");
+            }
+            // A failed run discards finals; only a successful one posts its bag.
+            const outputs = result.outputs ?? {};
+            if (Object.keys(outputs).length > 0) {
+                yield outputs;
+            }
+        }
+        finally {
+            // The consumer may abandon the generator mid-stream (a downstream
+            // routing error, or a `break`). Aborting unblocks the guest, closing the
+            // channel releases any `emit` waiting for room, and awaiting the run
+            // leaves nothing in flight behind us.
+            abort.abort();
+            channel.close();
+            await run;
+        }
+    }
+    /** The deprecated `yield` path: the guest collects, the host replays. */
+    async *runLegacyStream(envelope, context) {
+        const code = envelope.code;
+        // The prelude sits outside the yield_ rewrite: only user code streams.
+        const wrappedBody = `${NODETOOL_PRELUDE}
+      const __yielded = [];
+      function yield_(value) { __yielded.push(value); }
+      ${code.replace(/\byield\b/g, "yield_")}
+      return __yielded;
+    `;
+        const result = await runInSandbox({
+            // The body itself, not the rewritten one: `code` is overridden below,
+            // but the options are also what decide which platform modules this run
+            // mounts, and that answer is read off the imports the user wrote.
+            ...(await this.sandboxOptions(envelope.code, envelope, context)),
+            code: wrappedBody
+        });
+        if (!result.success) {
+            throw new Error(result.error ?? "Code execution failed");
+        }
+        // The guest returns the array `yield_` collected. A body that replaced the
+        // return value with something else streams nothing.
+        const items = Array.isArray(result.result)
+            ? result.result
+            : [];
+        for (const item of items) {
+            if (item !== null && item !== undefined) {
+                yield normalizeCodeOutput(item);
+            }
+        }
+    }
+}
+__decorate([
+    prop({
+        type: "str",
+        default: "return {};",
+        title: "Code",
+        description: "JavaScript code to execute. " +
+            "Dynamic inputs arrive on the `inputs` object. " +
+            "APIs: fetch(url, options), workspace.read/write/list/readBytes/writeBytes/stat/mkdir/remove/copy/move/root, " +
+            "workspace.stat(path) returns {exists, size, isDirectory, isFile, isSymlink, modifiedMs, createdMs, accessedMs}, " +
+            "nodetool.secrets.get(name) (throws when unset; limited to the names in " +
+            "`secrets` when that is set), getSecret(name), sleep(ms), progress(percent, message), " +
+            "crypto.randomUUID/getRandomValues/digest/hmac, " +
+            "format.number/date/relativeTime/list, " +
+            "media.bytes(ref)/media.text(ref, {encoding})/media.info(ref) to read a document, " +
+            "image, audio or video input, and media.toDocument/toImage/toAudio/toVideo(bytes, " +
+            "{mimeType, filename}) to build one to return, " +
+            "toBase64/fromBase64/toHex/fromHex. Libraries — CSV, HTML, XML, XLSX, YAML, zip, dates, " +
+            "diffs — are sandbox packages: `import` one at the top and the host resolves it " +
+            "against the installed packs. " +
+            "console.log/warn/error/info appear on the node log as they run. " +
+            "Await fetch, sleep, workspace, getSecret, format, media, an imported package's " +
+            "calls, and crypto.digest/hmac; the rest are synchronous. " +
+            "Concurrent calls run in parallel: use Promise.all or " +
+            "parallelMap(items, fn, concurrency) to fan out fetches. " +
+            "The `nodetool` object model exposes platform tools (nodetool.workflows, " +
+            "nodetool.assets, …) where the host carries them — nodetool.capabilities() " +
+            "reports live namespaces; elsewhere a method throws naming its missing tool. " +
+            "A persistent `state` object survives across streaming invocations. " +
+            "Outputs: `await emit(name, value)` streams one value to output handle " +
+            "`name` right away and can be called any number of times; " +
+            "`await output(name, value)` records that handle's final value, delivered " +
+            "as one bag when the body ends. `return` is control flow only — the " +
+            "returned value carries no outputs. " +
+            "Inputs: `for await (const item of stream(name))` reads a connected " +
+            "handle as values arrive, `stream.any()` yields [handle, value] across " +
+            "all handles in arrival order, `stream.first(name)` takes one value " +
+            "(undefined at end of stream), and `stream.open(name)` says whether more " +
+            "can still arrive. A body using any of them runs once for the whole " +
+            "stream — waiting on input does not spend the timeout — and `inputs.*` " +
+            "then carries only the values configured on the node. A body that never " +
+            "mentions `stream` runs once per incoming item, as before. " +
+            "Deprecated: a body that calls neither emit nor output still runs the old " +
+            "contract, where a returned object's keys become output handles and " +
+            "yield(value) streams."
+    })
+], CodeNode.prototype, "code", void 0);
+__decorate([
+    prop({
+        type: "list[str]",
+        default: [],
+        title: "Secrets",
+        description: "Secret names this code may read, e.g. [\"NOTION_API_KEY\"]. " +
+            "nodetool.secrets.get(name) and getSecret(name) refuse every other name, " +
+            "so a node that talks to one service cannot read the credentials of " +
+            "another. Empty means unscoped — the whole secret store, which is what a " +
+            "node written before scopes existed still gets."
+    })
+], CodeNode.prototype, "secrets", void 0);
+__decorate([
+    prop({
+        type: "dict",
+        default: {},
+        title: "Script",
+        // The editor renders this with the script picker; an unlinked node stores
+        // the empty object.
+        json_schema_extra: { type: "js_script_link" },
+        description: "Which JS script version this node's body was copied from, as " +
+            '{"id": "<script id>", "version": <n>}. Linking materializes the pinned ' +
+            "version: its code, secrets and timeout become the node's own, " +
+            "so editing the script does not silently change this workflow and a run " +
+            "needs no script storage. \"Update to latest\" re-copies and re-pins. " +
+            "Empty means the node was never linked."
+    })
+], CodeNode.prototype, "script", void 0);
+__decorate([
+    prop({
+        type: "int",
+        default: 30,
+        title: "Timeout",
+        description: "Max seconds before execution is aborted (0 = no limit)."
+    })
+], CodeNode.prototype, "timeout", void 0);
+__decorate([
+    prop({
+        type: "int",
+        default: 1,
+        title: "Max Response Size",
+        description: "Megabytes of response body a single fetch() may read before it is aborted."
+    })
+], CodeNode.prototype, "max_response_mb", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: false,
+        title: "Allow Local Network",
+        description: "Permit fetch() to reach localhost and private IP ranges. Off by default — " +
+            "sandboxed code is untrusted, so the SSRF guard is the norm. Turn it on " +
+            "only for a node that has to reach a service on this machine or network."
+    })
+], CodeNode.prototype, "allow_local_network", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: false,
+        title: "Allow Host Filesystem",
+        description: "Let workspace.* reach any path the process can, with ~ expanded, instead " +
+            "of being confined to the workspace. Off by default — host mode can read " +
+            "credential files. Turn it on only for a node that has to work outside " +
+            "the workspace."
+    })
+], CodeNode.prototype, "allow_host_filesystem", void 0);
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * The body's top-level statements, or null when it does not parse.
+ *
+ * A body on the legacy `yield` contract is not valid module syntax — a
+ * top-level `yield` is a reserved word outside a generator — so it parses only
+ * after the same rewrite {@link CodeNode.runLegacyStream} applies before
+ * running it. Reading the imports off the rewritten body keeps a legacy
+ * streaming body able to import a pack.
+ */
+function importableStatements(code) {
+    const parsed = parseCodeBody(code);
+    if (!("error" in parsed))
+        return parsed.statements;
+    const rewritten = parseCodeBody(code.replace(/\byield\b/g, "yield_"));
+    return "error" in rewritten ? null : rewritten.statements;
+}
+/** Map a guest `console.*` method onto a `log_update` severity. */
+function consoleSeverity(level) {
+    if (level === "warn")
+        return "warning";
+    if (level === "error")
+        return "error";
+    return "info";
+}
+/** Extract dynamic inputs, filtering reserved/invalid keys. */
+function extractDynamicInputs(inputs) {
+    const reserved = new Set([
+        "code",
+        "script",
+        // Retired: the node no longer declares packages (they come from the body's
+        // imports), but a graph saved before that still carries the key and must
+        // not turn it into a dynamic input.
+        "packages",
+        "secrets",
+        "timeout",
+        "max_response_mb",
+        "allow_local_network",
+        "allow_host_filesystem"
+    ]);
+    const result = {};
+    for (const [key, value] of Object.entries(inputs)) {
+        if (reserved.has(key) || key.startsWith("_"))
+            continue;
+        if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key))
+            continue;
+        if (JS_RESERVED.has(key))
+            continue;
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * One value, deep-copied into JSON-safe form for the guest. The marshal rule
+ * for a streamed item is the buffered one: plain data crosses, anything that
+ * cannot be serialized becomes `null`. Media inputs are refs — plain objects —
+ * so they survive and stay readable through `media.*`.
+ */
+function jsonSafe(value) {
+    if (value === null || value === undefined)
+        return value;
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Deep-copy all input values to make them safe for the sandbox.
+ * Strips functions, symbols, and other non-serializable types.
+ */
+function deepCopyInputs(inputs) {
+    const result = {};
+    for (const [key, value] of Object.entries(inputs)) {
+        result[key] = jsonSafe(value);
+    }
+    return result;
+}
+//# sourceMappingURL=code-node.js.map