@nodetool-ai/node-sdk 0.8.4-a24.2 → 0.8.4

package/dist/_sandbox/sandbox-expr/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: sandbox-expr
+description: Evaluate a math formula without eval in a Code node or CodeAct action, with expr-eval running on the host
+---
+
+# Formulas in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-expr`. Import it at the top of the body.
+
+The published expr-eval bundle trips the guest scanner, so this pack is a
+**host module**.
+
+## evaluate — formula plus variables
+
+```js
+import { evaluate } from "@nodetool-ai/sandbox-expr";
+
+const value = await evaluate(inputs.formula, inputs.vars);
+return { value };
+```
+
+`inputs.formula` is a string such as `"2 * qty + fee"`. `inputs.vars` is
+`{ qty: 3, fee: 1.5 }`.
+
+## Gotchas
+
+- **Not JavaScript.** `^` is power. Unknown names throw.
+- **Do not use `eval`.** The guest deletes it. This pack is the formula path.

package/dist/_sandbox/sandbox-expr/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@nodetool-ai/sandbox-expr",
+  "version": "0.8.4",
+  "description": "Evaluate a math expression without eval, inside the NodeTool sandbox, from expr-eval",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "expr"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-expr"
+  },
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "SKILL.md"
+  ],
+  "keywords": [
+    "nodetool",
+    "nodetool-sandbox-pack",
+    "sandbox",
+    "expression",
+    "formula",
+    "eval"
+  ]
+}

package/dist/_sandbox/sandbox-fabric/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: sandbox-fabric
+description: Build, parse, and rasterize SVG with Fabric.js (renderSVG, loadSVG, render)
+---
+
+# Fabric.js in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-fabric`. Import it at the top of the body.
+
+## render — Canvas spec / JSON to image bytes
+
+Renders a scene description (objects, dimensions, background color) to raster
+image bytes (`Uint8Array`):
+
+```js
+import { render } from "@nodetool-ai/sandbox-fabric";
+
+const imageBytes = await render({
+  width: 800,
+  height: 600,
+  backgroundColor: "#f8fafc",
+  objects: [
+    {
+      type: "rect",
+      left: 100,
+      top: 100,
+      width: 200,
+      height: 120,
+      fill: "#3b82f6",
+      rx: 10,
+      ry: 10
+    },
+    {
+      type: "textbox",
+      left: 120,
+      top: 140,
+      text: "NodeTool & Fabric.js",
+      fontSize: 20,
+      fill: "#ffffff"
+    }
+  ]
+}, { format: "png", multiplier: 1 });
+
+return { image: imageBytes };
+```
+
+## renderSVG — Canvas spec / JSON to SVG string
+
+Renders a scene specification directly into an SVG string:
+
+```js
+import { renderSVG } from "@nodetool-ai/sandbox-fabric";
+
+const svgString = await renderSVG({
+  width: 500,
+  height: 500,
+  backgroundColor: "#ffffff",
+  objects: [
+    {
+      type: "circle",
+      left: 250,
+      top: 250,
+      radius: 100,
+      fill: "#ef4444"
+    }
+  ]
+});
+
+return { svg: svgString };
+```
+
+## toDataURL — Canvas spec to Data URL
+
+Exports the scene as a base64 Data URL string:
+
+```js
+import { toDataURL } from "@nodetool-ai/sandbox-fabric";
+
+const dataUrl = await toDataURL({
+  width: 400,
+  height: 300,
+  objects: [
+    { type: "rect", left: 50, top: 50, width: 100, height: 100, fill: "green" }
+  ]
+}, { format: "png" });
+
+return { dataUrl };
+```
+
+## loadSVG — Parse SVG string into Fabric objects
+
+Parses an SVG document into Fabric objects and canvas options:
+
+```js
+import { loadSVG, render } from "@nodetool-ai/sandbox-fabric";
+
+const parsed = await loadSVG("<svg ...>...</svg>");
+const imageBytes = await render({
+  width: 600,
+  height: 400,
+  objects: parsed.objects
+});
+
+return { image: imageBytes };
+```
+
+## Gotchas
+
+- **Host execution.** Fabric.js depends on canvas and DOM APIs that do not exist
+  in the pure WebAssembly QuickJS guest. It runs on the host and passes plain
+  serializable data across the sandbox boundary.
+- **Dimensions are bounded.** Canvas dimensions are clamped to a maximum of 8192
+  pixels to prevent excessive memory consumption.

package/dist/_sandbox/sandbox-fabric/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@nodetool-ai/sandbox-fabric",
+  "version": "0.8.4",
+  "description": "Build, parse, and rasterize SVG with Fabric.js (renderSVG, loadSVG, render)",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "fabric"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-fabric"
+  },
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "SKILL.md"
+  ],
+  "keywords": [
+    "nodetool",
+    "nodetool-sandbox-pack",
+    "sandbox",
+    "fabric",
+    "canvas",
+    "svg"
+  ]
+}

package/dist/_sandbox/sandbox-flow/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: sandbox-flow
+description: Call NodeTool nodes as typed async functions from sandbox code, one importable module per node namespace, with streaming and plain JavaScript control flow
+---
+
+# Calling nodes from the sandbox
+
+Specifier: `@nodetool-ai/sandbox-flow`. Each node namespace is its own module —
+`@nodetool-ai/sandbox-flow/nodetool.text`,
+`@nodetool-ai/sandbox-flow/lib.audio`, and so on for all 69. Every node type is
+a generated async function whose name and inputs come from the node's own
+metadata, so a type this pack does not export has no import to resolve.
+
+This is not the graph DSL. Nothing is built, saved, or scheduled: the call runs
+the node and resolves to its outputs. `await` is the edge, a variable is the
+wire, `Promise.all` is the fan-out, and `if`/`for`/`try` are themselves.
+
+```js
+import { concat } from "@nodetool-ai/sandbox-flow/nodetool.text";
+
+const r = await concat({ a: "hello ", b: "world" });
+return r.output;
+```
+
+These examples are chat code actions, where `return` is the action's result.
+In a Code node or a JS script document, `return` is control flow only: hand a
+value on with `await output(name, value)` or stream it with `emit`. A script
+document that returns its outputs fails, and a Code node accepts that old
+contract only with a deprecation warning.
+
+## Two imports, both required
+
+1. `import { … } from "@nodetool-ai/sandbox-flow/<namespace>";` — the nodes.
+2. `import "@nodetool-ai/sandbox-nodetool/flow";` — the capability module.
+
+The second one is not decoration. The host mounts a capability module by
+reading the **body's** static imports, and this pack's guest code calls into
+`@nodetool-ai/sandbox-nodetool/flow`. Without the body-side import the facade
+is never mounted and the pack's own import of it is refused by name.
+
+```js
+import "@nodetool-ai/sandbox-nodetool/flow";
+import { concat } from "@nodetool-ai/sandbox-flow/nodetool.text";
+```
+
+## Streaming
+
+A node that streams its output carries a `.stream` member; a one-shot node does
+not, so the surface tells you which is which. Awaiting the plain call on a
+streaming node still works — it drains the node and returns the last value per
+slot.
+
+```js
+import "@nodetool-ai/sandbox-nodetool/flow";
+import { agent } from "@nodetool-ai/sandbox-flow/nodetool.agents";
+
+let text = "";
+for await (const chunk of agent.stream({ prompt: "Summarize the file" })) {
+  text += chunk.chunk ?? "";
+  if (text.length > 2000) break; // closes the stream; the node stops
+}
+return text;
+```
+
+Breaking early releases the stream on the host. Read it to the end, or break —
+both are fine; abandoning the loop object without either is what leaks.
+
+A node written against the streaming-input contract streams `{slot, value}`
+instead of partial outputs, one item per emission, and its inputs accept an
+array wherever a single value goes:
+
+```js
+import { take } from "@nodetool-ai/sandbox-flow/nodetool.control";
+
+const kept = [];
+for await (const { slot, value } of take.stream({ input_item: [1, 2, 3], n: 2 })) {
+  if (slot === "output") kept.push(value);
+}
+```
+
+Arrays are the whole of streaming input in this version. An async iterable on
+an input handle is not accepted.
+
+## Errors
+
+A node that fails rejects the call with its own error. There is no verdict
+machinery and no per-node error stream — your `try`/`catch` is the supervisor,
+and retry, fallback, and timeout are yours to write:
+
+```js
+import "@nodetool-ai/sandbox-nodetool/flow";
+import { textToSpeech } from "@nodetool-ai/sandbox-flow/gemini.audio";
+
+try {
+  return await textToSpeech({ text: draft });
+} catch (error) {
+  return { error: String(error) };
+}
+```
+
+## Fan-out
+
+Concurrency is `Promise.all`, and it is real: the calls run at once.
+
+```js
+const summaries = await Promise.all(
+  documents.map((document) => summarizer({ text: document }))
+);
+```
+
+Nothing throttles this. A hundred items is a hundred concurrent model calls —
+batch them yourself when that matters.
+
+## The untyped root
+
+`import { callNode } from "@nodetool-ai/sandbox-flow"` takes a node type as a
+string and checks nothing until the host answers. Use it when the type is
+decided at run time; otherwise import the namespace, where a wrong name is an
+import error rather than a failed call.
+
+## Gotchas
+
+- **Inputs are values, not handles.** There is nothing to wire and no
+  `.output()` — the call returns the outputs record.
+- **No graph comes out of this.** Nothing opens in the editor, validates, or
+  replays. When the artifact matters, build a graph with
+  `@nodetool-ai/sandbox-dsl` instead.
+- **A missing property is the node's default**, exactly as in a graph run.
+- **Names follow the node class**: `nodetool.text.Concat` is `concat`,
+  `nodetool.constant.Integer` is `integer`. Reserved words take a trailing
+  underscore (`if_`).