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

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

@@ -0,0 +1,36 @@
+---
+name: sandbox-decimal
+description: Exact decimal arithmetic inside a Code node or CodeAct action, with decimal.js running in the guest
+---
+
+# Decimals in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-decimal`. One module, decimal.js. Import it
+at the top of the body.
+
+## Exact sums
+
+```js
+import Decimal from "@nodetool-ai/sandbox-decimal";
+
+const total = inputs.amounts
+  .reduce((sum, n) => sum.plus(n), new Decimal(0));
+return { total: total.toFixed(2) };
+```
+
+## Divide without float noise
+
+```js
+import Decimal from "@nodetool-ai/sandbox-decimal";
+
+const share = new Decimal(inputs.cents).div(inputs.parts);
+return { share: share.toFixed(2) };
+```
+
+## Gotchas
+
+- **Default export.** `import Decimal from "@nodetool-ai/sandbox-decimal"`.
+- **Pass strings or Decimals.** `new Decimal(0.1)` already lost precision;
+  use `new Decimal("0.1")`.
+- **The guest has no Intl.** Format with `toFixed` / `toString`, not
+  `toLocaleString`.

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

@@ -0,0 +1,43 @@
+{
+  "name": "@nodetool-ai/sandbox-decimal",
+  "version": "0.8.4",
+  "description": "Arbitrary-precision decimal arithmetic inside the NodeTool sandbox, from decimal.js",
+  "license": "MIT",
+  "dependencies": {
+    "decimal.js": "^10.6.0"
+  },
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "js",
+        "npm": "decimal.js"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-decimal"
+  },
+  "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",
+    "decimal",
+    "money",
+    "precision"
+  ]
+}

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

@@ -0,0 +1,36 @@
+---
+name: sandbox-diff
+description: Unified text diffs in a Code node or CodeAct action, with the diff library running on the host
+---
+
+# Text diffs in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-diff`. Import it at the top of the body.
+
+The `diff` library schedules with `setTimeout`, and the guest has no timers, so
+it cannot be compiled in. This pack is a **host module**: the import resolves to
+a generated facade over NodeTool's own implementation.
+
+## unified — a unified diff of two texts
+
+```js
+import { unified } from "@nodetool-ai/sandbox-diff";
+
+const patch = await unified(inputs.before, inputs.after, {
+  oldName: "before.md",
+  newName: "after.md",
+  context: 5
+});
+return { patch, changed: patch.includes("@@") };
+```
+
+Options: `context` (lines of context, 0–100, default 3), `oldName`, `newName`.
+Identical inputs produce a header with no hunks, so `includes("@@")` is the
+cheap "did anything change" test — handy in a verify loop.
+
+## Gotchas
+
+- **`unified` is async.**
+- **5 MB per side.** Larger input is refused by name.
+- **Line-oriented.** Two texts that differ only in trailing whitespace still
+  diff; normalize first if that is noise.

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

@@ -0,0 +1,39 @@
+{
+  "name": "@nodetool-ai/sandbox-diff",
+  "version": "0.8.4",
+  "description": "Unified text diffs inside the NodeTool sandbox, from the diff library running on the host",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "diff"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-diff"
+  },
+  "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",
+    "diff",
+    "patch"
+  ]
+}

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

@@ -0,0 +1,53 @@
+---
+name: sandbox-docx
+description: Build a Word document in a Code node or CodeAct action, with docx running on the host
+---
+
+# Word documents in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-docx`. Import it at the top of the body.
+
+`docx` builds a document out of class instances (`Paragraph`, `TextRun`,
+`Table`, …) that cannot cross the guest boundary as plain data. This pack is a
+**host module**: you describe the document as a JSON element list and the host
+builds the real `.docx` bytes.
+
+## build — element list to `.docx` bytes
+
+```js
+import { build } from "@nodetool-ai/sandbox-docx";
+
+const bytes = await build({
+  properties: { title: "Q3 Report", author: "NodeTool" },
+  elements: [
+    { type: "heading", text: "Q3 Report", level: 1 },
+    { type: "paragraph", text: "Revenue grew 12% quarter over quarter.", bold: true },
+    { type: "table", rows: [["Month", "Revenue"], ["Jul", "120k"], ["Aug", "134k"]] },
+    { type: "pageBreak" },
+    { type: "paragraph", text: "See appendix for methodology.", alignment: "CENTER" }
+  ]
+});
+await workspace.writeBytes("report.docx", bytes);
+```
+
+Element types:
+
+- `heading` — `text`, `level` (1–6, default 1)
+- `paragraph` — `text`, `alignment` (`LEFT`/`CENTER`/`RIGHT`/`JUSTIFY`, default
+  `LEFT`), `bold`, `italic`, `fontSize` (points, default 12)
+- `table` — `rows`, a 2D array; every cell is stringified
+- `image` — `data` (a `Uint8Array`), `width`/`height` in inches
+- `pageBreak` — no fields
+
+`properties.title`/`author`/`subject`/`keywords` set the document's metadata.
+
+## Gotchas
+
+- **`build` is async** and returns a `Uint8Array`.
+- **Writing only.** To read an existing `.docx`, use
+  `@nodetool-ai/sandbox-mammoth` instead — these are two different libraries on
+  two different sides of the format.
+- **Images are inches, not pixels.** `width`/`height` follow docx's own
+  convention; omit them and the image renders at a fixed placeholder size.
+- **10 MB per image.** The shared host-module input cap applies to each
+  `data` field.

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

@@ -0,0 +1,40 @@
+{
+  "name": "@nodetool-ai/sandbox-docx",
+  "version": "0.8.4",
+  "description": "Build Word documents inside the NodeTool sandbox, from docx running on the host",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "docx"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-docx"
+  },
+  "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",
+    "docx",
+    "word",
+    "document"
+  ]
+}

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

@@ -0,0 +1,137 @@
+---
+name: sandbox-dsl
+description: Build a NodeTool workflow graph in the sandbox from generated node wrappers, one importable module per node namespace
+---
+
+# The workflow DSL in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-dsl`. The root exports `workflow()` and every
+namespace under a short name. Each namespace is also its own module:
+`@nodetool-ai/sandbox-dsl/nodetool.image`, `@nodetool-ai/sandbox-dsl/lib.audio`,
+and so on for all 71.
+
+Every node type is a generated function whose name and inputs come from the
+node's own metadata. A type this pack does not export does not exist, and the
+import fails before the program runs — which is the difference from building a
+graph out of type strings.
+
+## Build a graph
+
+```js
+import { workflow } from "@nodetool-ai/sandbox-dsl";
+import { stringInput } from "@nodetool-ai/sandbox-dsl/nodetool.input";
+import { resize } from "@nodetool-ai/sandbox-dsl/nodetool.image";
+import { output } from "@nodetool-ai/sandbox-dsl/nodetool.output";
+
+const prompt = stringInput({ name: "prompt", value: "a fox in snow" });
+const smaller = resize({ width: 256, height: 256 });
+return workflow(output({ name: "image", value: smaller.output() }));
+```
+
+`workflow()` returns `{ nodes, edges }` in the kernel shape — nodes carry
+`{id, type, properties}`, edges carry `{id, source, sourceHandle, target,
+targetHandle}`. Hand that straight to `validate_workflow` or `create_workflow`.
+
+## Check it, save it, run it
+
+The graph is data until something checks it. Validate first — it costs nothing
+and catches a missing property, a dangling edge, or a model nobody selected
+before a run spends money on the half of the graph that does work:
+
+```js
+import { validate_workflow, create_workflow, run_workflow, debug_workflow }
+  from "@nodetool-ai/sandbox-nodetool/workflows";
+
+const graph = workflow(output({ name: "image", value: smaller.output() }));
+
+const check = await validate_workflow({ graph });
+if (!check.ok) throw new Error(check.issues.map((i) => i.message).join("; "));
+```
+
+`validate_workflow` answers `{ok, counts, issues}` — `ok` is false only when
+the graph has errors, and each issue carries `{severity, code, message}`.
+Warnings do not set `ok` false; read them off `issues`.
+
+```js
+const saved = await create_workflow({ name: "Thumbnailer", graph });
+const run = await run_workflow({
+  workflow_id: saved.id,
+  params: { prompt: "a fox in snow" }
+});
+```
+
+`run_workflow` answers `{status, outputs}`. When a run fails and the graph looks
+right, `debug_workflow({workflow_id, params})` runs it again and answers one
+report: `{workflow_id, run, job, workflow}`. `run` carries
+`{status, outputs, error, verdict}` — `outputs` is keyed by output name and
+each name holds an array of emitted values (`run.outputs.image[0]`). `job`
+carries status, cost and logs; `verdict.headline` and `verdict.issues` say
+which node failed and why.
+
+Every model property must be selected before you save: assign a `find_model`
+result's `ref` to the node's `model`. A graph saved with unselected models is
+refused by `create_workflow`, because nothing stamps models in at run time.
+
+Where the session mounts no capability modules, the same three verbs are
+`nodetool.workflows.validate/create/run/debug`. Both forms reach one
+implementation past one permission gate.
+
+## Wiring
+
+A node function returns a reference. `ref.output()` is the default output slot;
+`ref.output("mask")` names one. Pass a handle as a property value and the edge
+is wired for you:
+
+```js
+const wired = resize({ image: source.output(), width: 512 });
+```
+
+A `list[...]` input takes an array of handles — one edge per element, and the
+sources run in parallel:
+
+```js
+const strip = combineImageGrid({
+  tiles: [a.output(), b.output(), c.output()],
+  columns: 3
+});
+```
+
+Every element must be a handle; mixing wired outputs and literal values in one
+array throws. A handle buried inside an object value throws too — a connection
+is only made from a handle assigned directly to an input.
+
+A node with several outputs has no default, so `output()` without a slot throws
+and names the slots it has. A slot the node does not have throws the same way.
+
+## Ids
+
+Ids are assigned from the node type: `resize`, `resize_2`, `string_input`. They
+are stable for a given program, so a later edit can name one — but the generated
+wrappers take inputs and nothing else, so a program cannot choose an id.
+
+## Everything in one import
+
+```js
+import * as dsl from "@nodetool-ai/sandbox-dsl";
+
+const smaller = dsl.image.resize({ width: 256, height: 256 });
+return dsl.workflow(dsl.output.output({ name: "image", value: smaller.output() }));
+```
+
+The `nodetool.*` namespaces drop the prefix (`dsl.image`, `dsl.input`,
+`dsl.text`); the rest keep it in camel case (`dsl.libAudio`, `dsl.openaiImage`).
+Importing one namespace module is cheaper than the root, which pulls all 71.
+
+## Gotchas
+
+- **`workflow()` lives only at the root.** A program that imports namespace
+  subpaths still declares `@nodetool-ai/sandbox-dsl` for the builder.
+- **A handle is not text.** `` `use ${node.output()}` `` throws rather than
+  writing `[object Object]` into a property and wiring no edge.
+- **Only reachable nodes ship.** `workflow(terminal)` walks back from its
+  terminals; a node nothing wires to is dropped. Pass every terminal you want.
+- **One graph per call.** `workflow()` clears the registry, so a handle from an
+  earlier call is spent and using it throws.
+- **This builds a graph; it does not run one.** The pack is pure computation —
+  no models are called, no assets resolve, no node executes. Run the graph
+  through the workflow tools once it validates.