Nodetool JS Scripting

Write NodeTool sandbox JavaScript

Three places take the same guest JavaScript, with the same globals, the same imports and the same limits.

Pick a Code node when the logic belongs to one graph. Pick a script document when the same logic is called from several places, needs its own tests, or needs version history. Pick native flow when the control flow is easier to write than to wire.

The body contract

// inputs: { rows: [...], threshold: 10 }
const kept = inputs.rows.filter((r) => r.score > inputs.threshold);
progress(50, `kept ${kept.length}`);
for (const row of kept) await emit("row", row);   // streams as it goes
await output("count", kept.length);               // final, posted at the end

• Inputs arrive on the inputs object, never as globals of their own name. Values are deep-copied through JSON before entering the guest.
• Outputs leave through await output(name, value) and await emit(name, value), and nothing else. name must be a declared output handle. A second output on the same handle throws. return is ordinary control flow and its value is ignored. For a script document this is enforced: a body that declares outputs and returns them instead of emitting them is an error, because a script has no legacy return contract. A Code node still accepts the old return/yield contract for one more release, with a deprecation warning.
• Media inputs arrive as refs. Read one with media.bytes / media.text / media.info, and build one with media.toDocument / toImage / toAudio / toVideo. Pass the whole input object, not its uri, so the ref's own type travels with it. Every media.* call is async.
• stream is the input side of emit. A body that mentions stream runs once over the whole stream and pulls its own items. A body that never mentions it runs once per incoming item. Nothing is configured: deleting the last stream call flips the node back.

for await (const item of stream(name))            // one handle, in order, until EOS
for await (const [handle, item] of stream.any())  // every handle, arrival order
const item = await stream.first(name)             // next value, undefined at EOS
stream.open(name)                                 // could more still arrive?

• state survives across streaming invocations and resets at each run.
• progress(percent, message) drives the node's progress bar.

Capabilities are globals, libraries are imports

Globals need no declaration: console, fetch, workspace, getSecret, nodetool.secrets.*, sleep, crypto, format, image, audio, video, media, canvas, assetToSandbox / sandboxToAsset, progress, emit / output, and the pure helpers toBase64 / fromBase64 / toHex / fromHex / parallelMap. media.* and workspace.* need a ProcessingContext, so they throw in a bare sandbox call with no run behind it.

Everything else is a sandbox package the body imports:

import yaml from "@nodetool-ai/sandbox-yaml";

Discover them with list_sandbox_packages and read one's API with get_sandbox_package_docs. Do not guess a specifier: a pack this host does not carry fails validation with "Install <pack>". nodetool packs compile builds one for a dependency that is not shipped.

image.*, audio.* and video.* transforms return a sandbox://media/<id> handle, not bytes. Chain the calls, then <type>.toAsset(handle) before the run ends. A handle does not survive into a later run.

Running an agent from code

Use run_agent when the work needs more than one model call: look something up, act, read the result, correct.

import { run_agent } from "@nodetool-ai/sandbox-nodetool/agents";

const answer = await run_agent({
  prompt: "Read storyboard " + inputs.storyboardId + " and list its shot titles.",
  model: inputs.model,                // {provider, id} from a model selector
  tools: ["get_storyboard"],          // capability wire names, nothing else
  output_schema: { type: "object", properties: { titles: { type: "array", items: { type: "string" } } } }
});
await output("titles", answer.result.titles);

Without output_schema, answer.text is the agent's final message. The agent reports its text and tool calls while it runs. A mini app shows them in an Agent Activity widget bound to op:<id>/exec#transcript. generate_text stays the right call for one prompt with no tools.

Calling nodes from code

import "@nodetool-ai/sandbox-nodetool/flow";   // mounts the bridge, required
import { concat } from "@nodetool-ai/sandbox-flow/nodetool.text";

const r = await concat({ a: inputs.left, b: inputs.right });
await output("joined", r.output);

await is the edge, a variable is the wire, Promise.all is the fan-out. Both imports are required: the facade does not mount without the capability module. Streaming-output nodes carry .stream(inputs), an async iterable where an early break closes the stream and runs node cleanup. Every call passes the per-call permission gate and bills through the invoking run, bounded by a recursion depth cap of 4 and 16 concurrently open streams per run. Streaming inputs accept arrays only in v1.

A program that must open in the editor, be validated, or run on the server still builds a graph. Use nodetool-workflow-builder for that.

Building a timeline from code

import { video } from "@nodetool-ai/sandbox-timeline";

const v = video({ width: 1920, height: 1080, fps: 30 });
const title = v.scene("title", 3, (s) => {
  const t = s.text("Hello", { size: 120, weight: 600, color: "#ffffff" });
  t.enter({ from: { opacity: 0 }, at: 0, dur: 0.5 });
});
v.series([title]);
const saved = await v.save(nodetool.timelines, { name: "Hello" });
await output("timeline_id", saved.timeline_id);

The pack authors a whole motion-graphics cut in seconds, local to each scene, and saves it with one set_timeline_document, instead of one edit_timeline op per clip. Pass the body's nodetool.timelines to v.save: a module cannot see the belt. get_sandbox_package_docs on the specifier returns the full authoring API.

Save the build script itself as a JS script document and it links to the timeline it makes automatically: v.save(nodetool.timelines, {name}) with no timeline_id the first time creates the timeline and links this script to it; every later run of the same script updates that timeline in place instead of making another. Revise with edit_js_script's string-replacement ops (below) rather than resending the whole body.