nodetool-js-scripting
Write JavaScript that runs in NodeTool's QuickJS sandbox: Code node bodies, saved JS script documents, sandbox package imports, and calling nodes from code.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 635
- Forks
- 91
01 前言 Front Matter
- name
- nodetool-js-scripting
- featured
- true
- description
- Write JavaScript that runs in NodeTool's QuickJS sandbox: Code node bodies, saved JS script documents, sandbox package imports, and calling nodes from code.
02 资源文件 1
- 参考文档prompt.md9.0 KB
03 SKILL.md 正文
Write NodeTool sandbox JavaScript
Three places take the same guest JavaScript, with the same globals, the same imports and the same limits.
| Where | What it is | Reach it with |
|---|---|---|
| Code node | A body inside a workflow graph | validate_code, run_code, test_code |
| JS script document | A named, versioned script with declared ports, secrets, a timeout and saved tests | list_js_scripts, get_js_script, save_js_script, edit_js_script, validate_js_script, run_js_script, test_js_script |
| Native flow | Guest code calling nodes as async functions, no graph | import "@nodetool-ai/sandbox-nodetool/flow" |
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
inputsobject, never as globals of their own name. Values are deep-copied through JSON before entering the guest. - Outputs leave through
await output(name, value)andawait emit(name, value), and nothing else.namemust be a declared output handle. A secondoutputon the same handle throws.returnis 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 withmedia.toDocument/toImage/toAudio/toVideo. Pass the whole input object, not itsuri, so the ref's own type travels with it. Everymedia.*call is async. streamis the input side ofemit. A body that mentionsstreamruns 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 laststreamcall 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?
statesurvives 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.
The loop
- Write or read the body.
get_js_scriptfor a saved script. validate_code/validate_js_scriptafter every edit. It catches syntax, imports against the installed catalog, undefined names, undeclaredinputs.*reads, outputs noemit/outputcall reaches, duplicate or non-identifier port names, and tests naming ports the script does not declare. It is far cheaper than running.run_code/run_js_scriptwith real inputs.outputvalues come back asoutputs,emitvalues asstreamed, an ordered list of{name, value}. Stage a streamed input withinput_streams, keyed by handle.test_code/test_js_scriptas the regression check. A case suppliesinputs(orinput_streams) and optionallyexpect— final values per handle, compared structurally, with unnamed outputs ignored, andexpected_streamed, the full ordered emit list. A case with neither passes when the body runs without error.- Save.
save_js_scriptvalidates first and is CAS on update. For a small revision,edit_js_script(js_script_id, ops)is cheaper: each op is{old, new}, andoldmust match exactly once in the current code — like a code editor's find/replace, refused by name on zero or on an ambiguous match. It validates the result the same waysave_js_scriptdoes.
Script documents get the same version family as the other documents:
list_js_script_versions, get_js_script_version, create_js_script_version,
restore_js_script_version, delete_js_script_version.
Secrets and limits
Read a credential with nodetool.secrets.get(name) — never inline one, and
never write one into a body or a test case. A script's declared secrets are
intersected with whatever allowance the invoking context carries. There is no
set_secret: request_secret asks the user's own client for one and the value
never enters the guest, the transcript, or the model's context. A headless run
carries no secret prompt, so the call is refused by name rather than quietly
writing something nobody approved.
Script composition is bounded like sub-agents: depth cap 4 with a script id chain, so a cycle fails the call naming it. Execution time defaults to 30s and every limit is overridable per invocation and clamped to a ceiling.
Verify from a shell
These are the nodetool CLI. From a NodeTool checkout the same commands run
as npm run dev:nodetool -- <command>.
nodetool jsscript validate <id|file.json> --json
nodetool jsscript run <id|file.json> --inputs '{"numbers":[1,2,3]}'
nodetool jsscript run <id|file.json> --input-streams '{"numbers":[1,2,3]}'
nodetool jsscript test <id|file.json> --json
nodetool jsscript versions list|show|create|restore|delete <id>
A path that exists on disk wins over an id, and a file target needs no database.
jsscript test exits non-zero on any failure and is the keyless selfcheck the
harness gate runs.
Reference
In a NodeTool checkout, these repository sources go further:
docs/javascript-sandbox.md— the guest surface, marshaling, limits, concurrency and the security model.docs/js-script-document-design.md— document shape, storage, invocation from agents, Code nodes and mini apps.docs/harnesses.md§ nodetool jsscriptpackages/sandbox-packs/README.md
04 同仓库更多 Skills
humanizer
Rewrite AI-sounding text so it reads like the writer without changing what it says. Use when editing or reviewing prose for AI tells: not-X-but-Y contrasts, one-line closers, staged openers, forced triads, dashes everywhere, inflated claims, sales language, stock AI words, bold labels, or filler.
nodetool
Use the NodeTool MCP server to build, validate, run, and debug visual AI workflows, and to work with assets, collections, and jobs. Use when the user mentions NodeTool or asks for a workflow graph, a node, or a media generation run on their NodeTool server.
wan-2-6-prompting
Prompt Alibaba's Wan 2.6 video — text-to-video with a global style line plus timing-bracketed shots, and image-to-video that describes only what changes over time. Covers the shot-mode switch per provider, the prompt budget, negative prompts, motion intensity wording, audio input and prompt expansion. Use whenever the model id names a Wan 2.6 video route (alibaba/wan-2.6/text-to-video, alibaba/wan-2.6/image-to-video, wan-video/wan-2.6-t2v, wan-video/wan-2.6-i2v, wan-video/wan2.6-i2v-flash) on generate_video, animate_image or a TextToVideo node. Not for Wan 2.5 or 2.7, or the Wan 2.6 image routes.
video-workflow
Build a reusable NodeTool video workflow for batches or repeated inputs. For a single finished piece, use a storyboard skill.
video-clone
Analyze a reference video and recreate its shot structure with a new product or cast in NodeTool.
video-audio-continuity
Keep sound continuous across a multi-scene piece cut from generated video — why one clip per scene hard-cuts the audio at every boundary, when to write all the scenes into a single generation instead, the sound-design vocabulary that survives a provider's copyright filter, and how to check the length, the aspect ratio and the mix of what came back. Use when a piece has more than one scene and the video model writes its own audio (Seedance 2, Veo 3, MiniMax H3, Kling 2.6 and later), or when a cut's sound drops out at the shot changes.