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

package/dist/.nodetool-build-stamp

@@ -1 +1 @@
-2026-10-16T18:28:20.369Z
+2026-10-17T11:16:09.598Z

package/dist/_sandbox/README.md

@@ -0,0 +1,176 @@
+# Sandbox library packs
+
+One npm package per library the sandbox offers. Library bridge packs contain
+a config-only `nodetool.sandboxModules` manifest and a SKILL.md. Authoring packs
+such as sandbox-game and sandbox-timeline also ship guest JavaScript.
+
+There is one import surface and no second route: a library is reached with
+`import`, from a pack that is installed and declared on the node. The `data.*`
+guest globals are gone.
+
+## The packs
+
+| Pack | Library | Runs | Why |
+|---|---|---|---|
+| `@nodetool-ai/sandbox-dates` | date-fns | guest | compiler admits it |
+| `@nodetool-ai/sandbox-yaml` | js-yaml | guest | compiler admits it |
+| `@nodetool-ai/sandbox-markdown` | marked | guest | compiler admits it |
+| `@nodetool-ai/sandbox-qr` | uqr | guest | compiler admits it |
+| `@nodetool-ai/sandbox-subtitle` | subtitle | host | stream internals |
+| `@nodetool-ai/sandbox-tokens` | js-tiktoken | host | megabytes of BPE ranks |
+| `@nodetool-ai/sandbox-color` | culori | guest | compiler admits it |
+| `@nodetool-ai/sandbox-decimal` | decimal.js | guest | compiler admits it |
+| `@nodetool-ai/sandbox-expr` | expr-eval | host | bundle uses Function |
+| `@nodetool-ai/sandbox-jmespath` | jmespath | guest | compiler admits it |
+| `@nodetool-ai/sandbox-chrono` | chrono-node | host | locale tables / Date internals |
+| `@nodetool-ai/sandbox-exif` | exifr | host | workers / DOM-shaped globals |
+| `@nodetool-ai/sandbox-stats` | simple-statistics | guest | compiler admits it |
+| `@nodetool-ai/sandbox-rrule` | rrule | guest | compiler admits it |
+| `@nodetool-ai/sandbox-ics` | ics | host | Node-shaped helpers |
+| `@nodetool-ai/sandbox-gif` | gifenc | guest | compiler admits it |
+| `@nodetool-ai/sandbox-game` | NodeTool's game builder | guest | creates complete game documents and saves drafts atomically |
+| `@nodetool-ai/sandbox-csv` | papaparse | host | imports `node:stream` |
+| `@nodetool-ai/sandbox-html` | cheerio + turndown | host | 25 Node builtins; turndown wants a DOM |
+| `@nodetool-ai/sandbox-xml` | fast-xml-parser | host | reads a bare `window` |
+| `@nodetool-ai/sandbox-xlsx` | exceljs | host | Node streams |
+| `@nodetool-ai/sandbox-diff` | diff | host | schedules with `setTimeout` |
+| `@nodetool-ai/sandbox-zip` | fflate | host | the 50 MB inflation cap (below) |
+| `@nodetool-ai/sandbox-ocr` | tesseract.js | host | WASM engine, workers, downloads its language data |
+| `@nodetool-ai/sandbox-tfjs` | TensorFlow.js + model zoo | host | model weights outlive a run and outsize the guest heap |
+| `@nodetool-ai/sandbox-docx` | docx | host | builds from class instances, not data |
+| `@nodetool-ai/sandbox-mammoth` | mammoth | host | Node's own zip/XML stack |
+| `@nodetool-ai/sandbox-epub` | epub2 | host | reads from a file path, not a buffer |
+| `@nodetool-ai/sandbox-fabric` | fabric | host | DOM/Canvas APIs, rasterization |
+| `@nodetool-ai/sandbox-pdflib` | pdf-lib | host | builds from class instances, not data |
+| `@nodetool-ai/sandbox-pptxgen` | pptxgenjs | host | builds from class instances, not data |
+| `@nodetool-ai/sandbox-pptx` | office-text-extractor | host | Node's own zip/XML stack |
+| `@nodetool-ai/sandbox-pdf` | pdf-parse | host | pdf.js wants Node builtins and a canvas |
+| `@nodetool-ai/sandbox-aws` | NodeTool's SigV4 signer | host | signing chain the guest has no library for |
+| `@nodetool-ai/sandbox-notion` | NodeTool's Notion helper | host | first-party, so a pack cannot bring it |
+| `@nodetool-ai/sandbox-supabase` | NodeTool's PostgREST helper | host | first-party |
+| `@nodetool-ai/sandbox-twilio` | NodeTool's Twilio helper | host | first-party |
+
+**Guest** means the M3 compiler bundles the library into the QuickJS guest and
+the pack ships that manifest entry (`{"kind": "js", "npm": "…"}`). **Host**
+means the library runs where the sandbox itself runs and the guest reaches it
+through a generated ESM facade over a per-run dispatcher; the pack's manifest
+entry is `{"kind": "host", "host": "<id>"}` and the implementation lives in
+`packages/agents/src/host-modules/`.
+
+An authored guest pack declares `{"kind": "js", "file": "sandbox/index.js"}`.
+Discovery reads that file directly. The game builder uses this form and runs
+inside QuickJS with the same module admission rules as other guest code.
+
+### The service packs build requests; they never send one
+
+The last four packs replace the S3, Notion, Supabase and Twilio nodes.
+They are not libraries: each is a pure function that turns a description of a
+request into `{url, method, headers, body}`, or in `-aws`'s case into signed
+headers. The guest passes that to its own `fetch`, so the run's fetch cap, its
+SSRF guard and its body limit still apply — moving the header math to the host
+must not move the network call with it.
+
+They run through the host registry of NodeTool's service helpers. SigV4 uses
+an HMAC-SHA256 chain over the canonical request, which the guest cannot
+compute with its own globals.
+
+### Why zip is a host pack
+
+fflate is pure JavaScript and the compiler admits it — it shipped as a guest
+pack once. It does not now, because of `MAX_UNZIP_TOTAL_BYTES`. A zip bomb is a
+policy question, and a policy enforced inside the guest is enforced by code the
+guest can decline to call; the 64 MB guest heap does not replicate it either,
+because fflate inflates into host memory first. The library therefore runs on
+the host, where the cap sits between the archive and the guest with nothing
+around it.
+
+## A pack cannot bring a host module
+
+`kind: "host"` carries an **id**, never an implementation. Discovery admits the
+entry only when the id is in `SANDBOX_HOST_MODULES`
+(`packages/protocol/src/sandbox-host.ts`) *and* the declaring package is the one
+that table pins to the id — so `@evil/x` declaring `{"host": "csv"}` is refused,
+and an unknown id is refused outright. The per-run dispatcher repeats both
+checks on every call, because the boundary is enforcement, not declaration.
+
+Adding a host module is a NodeTool change: a row in the protocol table and an
+implementation in `packages/agents/src/host-modules/registry.ts`. A third-party
+pack cannot reach host execution through this path.
+
+## Not workspaces, on purpose
+
+The root `workspaces` array names every workspace by path — there is no
+`packages/*` glob — and these directories are deliberately absent from it. A
+pack is consumed the way any third-party pack is: discovered from disk and
+mounted into the guest by the loader. Nothing in the repo may
+`import "@nodetool-ai/sandbox-yaml"` in host code, and leaving them out of the
+workspace list is what makes that impossible rather than merely discouraged —
+npm links no symlink into `node_modules`, so the specifier does not resolve for
+the host at all.
+
+The compiler still finds a guest pack's dependency in this tree: esbuild
+resolves from the pack directory upward, and js-yaml and date-fns are hoisted to
+the repo root by the workspaces that already depend on them. A host pack has no
+dependency of its own at all — the library is a dependency of
+`@nodetool-ai/agents`, where the implementation lives.
+
+## Shipped, not installed
+
+Being outside `node_modules` once meant being absent: a checkout, the desktop
+app and the server image all discovered zero of these packs, so every library
+NodeTool documents failed a Code node with "Sandbox module … is not installed".
+Discovery now reads this directory directly. `shippedPackSearchPaths()` in
+`packages/node-sdk/src/pack-loader.ts` returns it — found by walking up from the
+loader module in a checkout, and read from `_sandbox/` beside `server.mjs` in
+the packaged app and the Docker image, where `scripts/bundle-backend.mjs` stages
+every pack here (manifest, declared files, SKILL.md) and
+`scripts/verify-backend-bundle.mjs` fails a build that misses one. Both are
+scans, so a pack added to this directory ships with no list to update.
+`NODETOOL_SHIPPED_PACKS_DIR` overrides the root for a host that stages them
+elsewhere.
+
+The shipped root comes last in the search order. A pack installed from npm
+through the Package Manager therefore shadows the copy that ships with the app,
+with no duplicate-pack diagnostic: that name has an owner, and it is the one the
+user installed.
+
+Availability is not new authority. These packs declare modules; they register no
+nodes and run no code at load, so the pack allowlist that gates node packs has
+nothing to gate here. A host module still resolves only through
+`SANDBOX_HOST_MODULES`, a Code node still has to declare the specifier, and the
+credentials the service packs use still come from `nodetool.secrets.get`,
+narrowed to the names that node declares.
+
+## Registry metadata
+
+The package index lives in the external `nodetool-ai/nodetool-registry`
+repository, so nothing in this repo writes an index entry. What the index reads
+is here, in each pack's package.json: `name`, `description`, the
+`nodetool-sandbox-pack` keyword, `nodetool.sandboxModules` (the specifier
+summary the design asks index entries to carry), and `nodetool.recommended`.
+Discovery ignores every key but `apiVersion`, `sandboxModules`, and `internal`,
+so the extra metadata costs the host nothing.
+
+## Adding a pack
+
+**Guest pack.** Compile the candidate first — a pack for a library the compiler
+skips is a pack nobody can import; `nodetool packs compile --json` reports the
+named skip. Then write the package.json with `{"kind": "js", "npm": "<dep>"}`
+and the dependency pinned to a range this tree already resolves.
+
+**Authored guest pack.** Write browser-safe JavaScript and declare it with
+`{"kind": "js", "file": "sandbox/index.js"}`. Mark its bridge table row
+`source: "authored"` and test importing it in QuickJS through discovery and
+the module catalog. It needs no npm compilation.
+
+**Host pack.** Add the row to `SANDBOX_HOST_MODULES` and the loader to
+`packages/agents/src/host-modules/registry.ts`, with the implementation beside
+it and every limit inside it. Then write the package.json with
+`{"kind": "host", "host": "<id>"}`.
+
+Either way: a `SKILL.md` with the specifier, each export with one example
+written for the guest, and the gotchas that bite there; a row in
+`packages/node-sdk/src/sandbox-bridge-packs.ts` so an uninstalled specifier gets
+an "Install …" hint; and the pack directory added to
+`packages/sandbox-compiler/tests/packs.test.ts`, which discovers, compiles, and
+runs every pack in this directory.

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

@@ -0,0 +1,98 @@
+---
+name: sandbox-aws
+description: Sign AWS requests (S3 and every other SigV4 service) in a Code node or CodeAct action, with NodeTool's signer running on the host
+---
+
+# AWS SigV4 in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-aws`. Import it at the top of the body.
+
+S3 is an HTTP API, so `fetch` already reaches it. What the guest cannot do is
+sign the request: SigV4 is an HMAC-SHA256 chain over a canonical form of the
+request, and one wrong byte gives a signature mismatch that names nothing.
+This pack is a **host module**: the chain runs on the host and hands back
+headers.
+
+**Nothing here sends a request.** Both exports are pure — they take a request
+and return a signed one. The call goes out through the guest's own `fetch`, so
+the run's fetch cap and its SSRF guard still apply.
+
+## sigv4 — sign a request
+
+```js
+import { sigv4 } from "@nodetool-ai/sandbox-aws";
+
+const accessKeyId = await nodetool.secrets.get("AWS_ACCESS_KEY_ID");
+const secretAccessKey = await nodetool.secrets.get("AWS_SECRET_ACCESS_KEY");
+
+const signed = await sigv4({
+  method: "GET",
+  url: "https://my-bucket.s3.us-east-1.amazonaws.com/?list-type=2&max-keys=100",
+  region: "us-east-1",
+  service: "s3",
+  accessKeyId,
+  secretAccessKey
+});
+
+const res = await fetch(signed.url, { method: signed.method, headers: signed.headers });
+return { xml: await res.text() };
+```
+
+Options: `method` (default `GET`), `url` (required, absolute), `region`
+(default `us-east-1`), `service` (default `s3`), `accessKeyId` and
+`secretAccessKey` (required), `sessionToken` (for temporary STS credentials),
+`headers`, `body`, `payloadHash`.
+
+Returns `{url, method, headers}` — never the body. Pass the same body value to
+`fetch` yourself, so bytes make one trip, not two.
+
+### Writing an object
+
+```js
+const body = JSON.stringify(inputs.record);
+const signed = await sigv4({
+  method: "PUT",
+  url: `https://my-bucket.s3.us-east-1.amazonaws.com/${inputs.key}`,
+  region: "us-east-1", service: "s3",
+  accessKeyId, secretAccessKey,
+  headers: { "content-type": "application/json" },
+  body
+});
+await fetch(signed.url, { method: "PUT", headers: signed.headers, body });
+```
+
+A `Uint8Array` body works the same way — from `workspace.readBytes` or a
+previous `response.bytes()`.
+
+## presign — a URL that authorizes itself
+
+```js
+import { presign } from "@nodetool-ai/sandbox-aws";
+
+const url = await presign({
+  method: "GET",
+  url: "https://my-bucket.s3.us-east-1.amazonaws.com/report.pdf",
+  region: "us-east-1", service: "s3",
+  expiresIn: 3600,
+  accessKeyId, secretAccessKey
+});
+return { url };
+```
+
+Returns the URL as a string. `expiresIn` is seconds, clamped to a week. The
+payload is unsigned, which is what makes a presigned `PUT` usable — whoever
+holds the URL supplies the body.
+
+## Gotchas
+
+- **Every export is async.** A host call is a round trip.
+- **It signs; it does not send.** Nothing reaches the network until you call
+  `fetch`.
+- **The signature is time-bound.** It is stamped when you call `sigv4`, and AWS
+  rejects one more than 15 minutes old. Sign immediately before fetching, not
+  at the top of a long function.
+- **Other services work too.** Set `service` and `region` — `dynamodb`,
+  `sqs`, `lambda`, `bedrock`. Only `s3` skips path normalization, because an
+  object key is a key.
+- **10 MB of body per signature.** Hash a bigger upload yourself and pass
+  `payloadHash`, or use a presigned `PUT`.

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

@@ -0,0 +1,40 @@
+{
+  "name": "@nodetool-ai/sandbox-aws",
+  "version": "0.8.4",
+  "description": "Sign AWS requests with Signature V4 inside the NodeTool sandbox, from NodeTool's signer running on the host",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "aws"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-aws"
+  },
+  "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",
+    "aws",
+    "s3",
+    "sigv4"
+  ]
+}

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

@@ -0,0 +1,39 @@
+---
+name: sandbox-chrono
+description: Parse English dates such as next Tuesday in a Code node or CodeAct action, with chrono-node running on the host
+---
+
+# Natural-language dates in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-chrono`. Import it at the top of the body.
+
+chrono-node does not compile into QuickJS, so this pack is a **host module**.
+You pass text; you get ISO strings back.
+
+## parseDate — first match
+
+```js
+import { parseDate } from "@nodetool-ai/sandbox-chrono";
+
+const iso = await parseDate(inputs.text, inputs.now);
+return { iso };
+```
+
+`inputs.now` is an optional reference timestamp (ISO string or epoch ms).
+
+## parse — every match
+
+```js
+import { parse } from "@nodetool-ai/sandbox-chrono";
+
+const hits = await parse(inputs.text, inputs.now);
+return { hits };
+```
+
+Each hit is `{ text, start, end }` with ISO strings (`end` may be `null`).
+
+## Gotchas
+
+- **Async host calls.** Always `await`.
+- **UTC.** The guest still has no time-zone database.
+- **Pair with `@nodetool-ai/sandbox-dates`** to format the Date you parse.

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

@@ -0,0 +1,40 @@
+{
+  "name": "@nodetool-ai/sandbox-chrono",
+  "version": "0.8.4",
+  "description": "Parse natural-language dates inside the NodeTool sandbox, from chrono-node",
+  "license": "MIT",
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "host",
+        "host": "chrono"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-chrono"
+  },
+  "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",
+    "chrono",
+    "date",
+    "nlp"
+  ]
+}

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

@@ -0,0 +1,35 @@
+---
+name: sandbox-color
+description: Convert, mix, and measure colors inside a Code node or CodeAct action, with culori running in the guest
+---
+
+# Color in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-color`. One module, culori's root export.
+Import it at the top of the body.
+
+## Parse and convert
+
+```js
+import { parse, formatHex, converter } from "@nodetool-ai/sandbox-color";
+
+const color = parse(inputs.hex);
+const rgb = converter("rgb")(color);
+return { hex: formatHex(color), rgb };
+```
+
+## Mix and difference
+
+```js
+import { interpolate, formatHex, differenceCiede2000 } from "@nodetool-ai/sandbox-color";
+
+const mix = interpolate(["#2563eb", "#f97316"]);
+const mid = formatHex(mix(0.5));
+const delta = differenceCiede2000()("#2563eb", "#f97316");
+return { mid, delta };
+```
+
+## Gotchas
+
+- **Objects, not CSS strings, after parse.** A parsed color is `{ mode, ...channels }`.
+- **Named imports.** There is no useful default export.

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

@@ -0,0 +1,43 @@
+{
+  "name": "@nodetool-ai/sandbox-color",
+  "version": "0.8.4",
+  "description": "Color conversion, mixing, and difference (deltaE) inside the NodeTool sandbox, from culori",
+  "license": "MIT",
+  "dependencies": {
+    "culori": "^4.0.2"
+  },
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "js",
+        "npm": "culori"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-color"
+  },
+  "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",
+    "color",
+    "culori",
+    "deltae"
+  ]
+}

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

@@ -0,0 +1,50 @@
+---
+name: sandbox-csv
+description: Parse and write CSV in a Code node or CodeAct action, with papaparse running on the host behind a generated facade
+---
+
+# CSV in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-csv`. Import it at the top of the body.
+
+papaparse imports `node:stream`, so it cannot be compiled into the guest. This
+pack is a **host module**: the import resolves to a generated facade whose two
+exports call NodeTool's own implementation. Both are `async` — a host call is a
+round trip.
+
+## parse — CSV text to records
+
+```js
+import { parse } from "@nodetool-ai/sandbox-csv";
+
+const rows = await parse(inputs.csv);           // records keyed by the header row
+const raw = await parse(inputs.csv, { header: false });   // string[][]
+return { count: rows.length, first: rows[0] ?? null };
+```
+
+Options: `header` (default `true`), `delimiter` (one character; omit to
+auto-detect).
+
+Values stay **strings**. There is no `dynamicTyping`, so a column never changes
+shape between runs — convert what you need with `Number()` or `new Date()`.
+
+## stringify — records back to CSV
+
+```js
+import { stringify } from "@nodetool-ai/sandbox-csv";
+
+const csv = await stringify(inputs.rows, { delimiter: ";" });
+return { csv };
+```
+
+Takes records or row arrays. Options: `header` (default `true`), `delimiter`
+(exactly one character).
+
+## Gotchas
+
+- **Every export is async.** `parse(...)` without `await` gives you a Promise.
+- **5 MB of text per call.** Input over that is refused by name. Split a bigger
+  file, or read it in slices with `workspace.read`.
+- **Bounded concurrency still helps.** Host calls start when invoked, so
+  `Promise.all` over several `parse` calls runs them together; `parallelMap`
+  is the bounded form.

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

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

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

@@ -0,0 +1,47 @@
+---
+name: sandbox-dates
+description: Date arithmetic, parsing and formatting inside a Code node or CodeAct action, with date-fns running in the guest
+---
+
+# Dates in the sandbox
+
+Specifier: `@nodetool-ai/sandbox-dates`. One module, date-fns's root export —
+around 250 named functions. There is no default export, so import the names you
+use.
+
+## Arithmetic and comparison
+
+```js
+import { addDays, differenceInCalendarDays, isBefore } from "@nodetool-ai/sandbox-dates";
+
+const due = addDays(new Date(inputs.startedAt), 30);
+return { due: due.toISOString(), overdue: isBefore(due, new Date()), days: differenceInCalendarDays(due, new Date()) };
+```
+
+## Parsing and formatting
+
+```js
+import { parseISO, format, isValid } from "@nodetool-ai/sandbox-dates";
+
+const when = parseISO(inputs.timestamp);
+if (!isValid(when)) return { label: "unknown" };
+return { label: format(when, "EEEE, d MMMM yyyy") };
+```
+
+`format` uses date-fns's own English locale tables, not `Intl` — which the
+guest does not have. That is why formatting works here at all, and it is also
+the limit: another language means another locale, and locales live at
+`date-fns/locale`, a subpath this pack does not publish.
+
+## Gotchas
+
+- **UTC only.** The guest runs with no time-zone database, so `new Date()` and
+  every conversion behave as UTC. Anything zone-aware — "9 am in Berlin" —
+  belongs on the host, not here.
+- **Named imports only.** `import dates from "@nodetool-ai/sandbox-dates"` gets
+  you nothing; date-fns is pure ESM with no default export.
+- **Import what you use.** The bundle is about 176 KB and loads as one module
+  per invocation, so a node that needs one comparison pays for all of it. For a
+  single `Date` subtraction, plain arithmetic is cheaper.
+- **No timers.** `setTimeout` does not exist in the guest. date-fns needs none,
+  but code around it must not either.

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

@@ -0,0 +1,41 @@
+{
+  "name": "@nodetool-ai/sandbox-dates",
+  "version": "0.8.4",
+  "description": "Date arithmetic, parsing and formatting inside the NodeTool sandbox, from date-fns",
+  "license": "MIT",
+  "dependencies": {
+    "date-fns": "^4.4.0"
+  },
+  "nodetool": {
+    "apiVersion": 1,
+    "recommended": true,
+    "sandboxModules": [
+      {
+        "name": ".",
+        "kind": "js",
+        "npm": "date-fns"
+      }
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/sandbox-packs/sandbox-dates"
+  },
+  "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",
+    "date"
+  ]
+}