@nodetool-ai/code-nodes 0.8.1

package/README.md

@@ -0,0 +1,25 @@
+# @nodetool-ai/code-nodes
+
+Code-execution nodes for [NodeTool](https://nodetool.ai).
+
+Run JavaScript inside visual AI workflows in a QuickJS WASM sandbox.
+
+## Install
+
+```bash
+npm install @nodetool-ai/code-nodes
+```
+
+## Nodes
+
+**Code execution** — `nodetool.code.Code` runs JavaScript in a QuickJS WASM
+sandbox with `fetch()`, workspace file access, secrets, and media helpers.
+Dynamic inputs arrive on the `inputs` object; the returned object becomes the
+outputs. Libraries are sandbox packs the body imports — the node declares no
+packages; the host resolves each specifier against the installed catalog. Full
+reference: [JavaScript Sandbox](https://docs.nodetool.ai/javascript-sandbox).
+
+## Links
+
+- [NodeTool](https://nodetool.ai)
+- [GitHub](https://github.com/nodetool-ai/nodetool)

package/dist/.nodetool-build-stamp

@@ -0,0 +1 @@
+2026-09-28T09:19:16.401Z

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./nodes/code-node.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./nodes/code-node.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/nodes/code-node.d.ts

@@ -0,0 +1,218 @@
+/**
+ * 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.
+ */
+import { BaseNode, type JsScriptLink } from "@nodetool-ai/node-sdk";
+import type { ProcessingContext, StreamingInputs, StreamingOutputs } from "@nodetool-ai/runtime";
+import { type RunSandboxResult } from "@nodetool-ai/agents/js-sandbox";
+/** This node's output bag is the sandbox's: handle name → the guest's value. */
+type CodeOutputs = NonNullable<RunSandboxResult["outputs"]>;
+/** Type-only view of the agents package index; erased at compile time. */
+type AgentsModule = typeof import("@nodetool-ai/agents");
+type AgentTool = InstanceType<AgentsModule["Tool"]>;
+/**
+ * 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 declare function setCodeNodeAgentsModule(mod: AgentsModule | null): void;
+/**
+ * Test/host injection point: replace the assembled toolbelt with a fixed set
+ * (`[]` simulates a beltless host). Pass `null` to restore the default
+ * assembly.
+ */
+export declare function setCodeNodeTools(tools: AgentTool[] | null): void;
+/**
+ * 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 declare const EMIT_CHANNEL_CAPACITY = 64;
+export declare class CodeNode extends BaseNode {
+    static readonly nodeType = "nodetool.code.Code";
+    static readonly platforms: readonly import("@nodetool-ai/protocol").Platform[];
+    static readonly title = "Code";
+    static readonly description: string;
+    static readonly inlineFields: string[];
+    static readonly inputFields: never[];
+    static readonly supportsDynamicInputs = true;
+    static readonly 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 readonly resolveStreamingInput: NonNullable<typeof BaseNode.resolveStreamingInput>;
+    /**
+     * 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.
+     */
+    private _state;
+    code: string;
+    secrets: string[];
+    script: JsScriptLink | Record<string, never>;
+    timeout: number;
+    max_response_mb: number;
+    allow_local_network: boolean;
+    allow_host_filesystem: boolean;
+    initialize(): Promise<void>;
+    /**
+     * 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.
+     */
+    private progressSink;
+    /**
+     * 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.
+     */
+    private logSink;
+    /** Post on the node's log channel, where the run has one. */
+    private postLog;
+    /**
+     * 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.
+     */
+    private sandboxLimits;
+    /**
+     * 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.
+     */
+    private resolveModules;
+    /** Post a warning on the node's log channel, where the run has one. */
+    private logWarning;
+    /**
+     * 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.
+     */
+    private sandboxGlobals;
+    /** Milliseconds the guest may run, or undefined for no limit. */
+    private timeoutMs;
+    /**
+     * 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.
+     */
+    private envelope;
+    /**
+     * 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).
+     */
+    private sandboxOptions;
+    /**
+     * 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.
+     */
+    private resolveCapabilities;
+    process(context?: ProcessingContext): Promise<CodeOutputs>;
+    /**
+     * 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.
+     */
+    run(inputs: StreamingInputs, outputs: StreamingOutputs, context?: ProcessingContext): Promise<void>;
+    /** The deprecated return-bag path: implicit return, normalized output. */
+    private runLegacySingleShot;
+    genProcess(context?: ProcessingContext): AsyncGenerator<CodeOutputs>;
+    /**
+     * 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.
+     */
+    private pumpEmitContract;
+    /** The deprecated `yield` path: the guest collects, the host replays. */
+    private runLegacyStream;
+}
+export {};
+//# sourceMappingURL=code-node.d.ts.map

package/dist/nodes/code-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-node.d.ts","sourceRoot":"","sources":["../../src/nodes/code-node.ts"],"names":[],"mappings":"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"}