@hatchet-dev/sandbox 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -6,6 +6,22 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Eac
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-11-11
+
+### Added
+
+- `@hatchet-dev/sandbox/wire` exports the Zod schemas and types of the sandbox task protocol, `turnInput`, `turnResult`, `commandOutput`, `sandboxInfo`, `resources` and `metadata`. It imports nothing but `zod`, so code that spawns the sandbox task itself, such as a serverless durable task on an edge runtime where the main entry cannot load, can share the wire types instead of writing its own.
+
+### Changed
+
+- Every option the SDK accepts is now checked with Zod before a task is sent. Unknown option keys, an empty sandbox ID, path, or command, a non-positive `idleTimeoutMs`, `timeoutMs`, or `depth`, a sandbox `id` outside lowercase letters, digits, and hyphens, `inheritParentMetadata` without `from`, and a `download` or `upload` URL that is not https are rejected with a `ZodError`. The `resources` and `delete` checks that already existed throw a `ZodError` instead of a plain `Error`. Provider responses are checked the same way, so a malformed result fails the call instead of surfacing later as a missing field. `zod` 4 is a dependency of the package.
+
+## [0.1.4] - 2026-11-09
+
+### Fixed
+
+- `resources.memory` and `resources.disk` strings without a unit were read as MiB, so a byte count such as `'1073741824'` asked for a billion MiB. A string now has to carry a unit (`Ki`, `Mi`, `Gi`, `Ti`, `K`, `M`, `G`, `T`) and is rejected otherwise. Pass a number for MiB.
+
 ## [0.1.3] - 2026-11-09
 
 ### Added

package/README.md

@@ -86,16 +86,16 @@ const sandbox = await hatchet.sandbox.create({ provider: 'e2b' });
 
 Options for `create`:
 
-| Option                  | What it does                                                                                                                                                                    |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `provider`              | Which sandbox provider to create on, by its name. Needed when the tenant has several; a fork always uses its snapshot's.                                                        |
-| `id`                    | Pick your own sandbox ID. Lowercase letters, digits, and hyphens. It must not exist yet.                                                                                        |
-| `template`              | The image or template, in the provider's own terms. Defaults to the provider's default.                                                                                         |
-| `from`                  | Start from this snapshot. Create two sandboxes from the same snapshot and you have a fork.                                                                                      |
-| `metadata`              | Tags you can search for with `list`.                                                                                                                                            |
-| `inheritParentMetadata` | With `from`, copy the tags of the sandbox that made the snapshot onto the new one. Tags given in `metadata` take precedence.                                                    |
-| `idleTimeoutMs`         | Stop the sandbox after this long with no calls. The provider sets the maximum.                                                                                                  |
-| `resources`             | Machine size as `{ vcpu, memory, disk }`. `memory` and `disk` take MiB or a quantity like `'4Gi'`. Providers that cannot honour a field fail the create with their own message. |
+| Option                  | What it does                                                                                                                                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`              | Which sandbox provider to create on, by its name. Needed when the tenant has several; a fork always uses its snapshot's.                                                                                |
+| `id`                    | Pick your own sandbox ID. Lowercase letters, digits, and hyphens. It must not exist yet.                                                                                                                |
+| `template`              | The image or template, in the provider's own terms. Defaults to the provider's default.                                                                                                                 |
+| `from`                  | Start from this snapshot. Create two sandboxes from the same snapshot and you have a fork.                                                                                                              |
+| `metadata`              | Tags you can search for with `list`.                                                                                                                                                                    |
+| `inheritParentMetadata` | With `from`, copy the tags of the sandbox that made the snapshot onto the new one. Tags given in `metadata` take precedence.                                                                            |
+| `idleTimeoutMs`         | Stop the sandbox after this long with no calls. The provider sets the maximum.                                                                                                                          |
+| `resources`             | Machine size as `{ vcpu, memory, disk }`. `memory` and `disk` take a number of MiB or a quantity with a unit like `'4Gi'`. Providers that cannot honour a field fail the create with their own message. |
 
 ### `Sandbox`
 

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var v1 = require('@hatchet-dev/typescript-sdk/v1');
+var zod = require('zod');
 var fs = require('fs/promises');
 
 function _interopNamespace(e) {
@@ -32,10 +33,40 @@ var FilesystemError = class extends Error {
   }
   code;
 };
-var toEntry = (e) => ({
-  ...e,
-  modifiedTime: e.modifiedTime ? new Date(e.modifiedTime) : void 0
+var path = zod.z.string().min(1);
+var positiveInt = zod.z.int().positive();
+var httpsUrl = zod.z.url({ protocol: /^https$/ });
+var fileData = zod.z.union([
+  zod.z.string(),
+  zod.z.instanceof(Uint8Array),
+  zod.z.instanceof(ArrayBuffer),
+  zod.z.instanceof(Blob)
+]);
+var writeEntries = zod.z.strictObject({ path, data: fileData }).array();
+var readOpts = zod.z.strictObject({ format: zod.z.enum(["text", "bytes", "blob"]).optional() });
+var listOpts = zod.z.strictObject({ depth: positiveInt.optional() });
+var transferOpts = zod.z.strictObject({ timeoutMs: positiveInt.optional() });
+var entry = zod.z.looseObject({
+  name: zod.z.string(),
+  path: zod.z.string(),
+  type: zod.z.enum(["file", "dir"]),
+  size: zod.z.number(),
+  mode: zod.z.number(),
+  permissions: zod.z.string(),
+  modifiedTime: zod.z.coerce.date().optional()
 });
+var fsOutput = zod.z.looseObject({
+  content: zod.z.string().optional(),
+  stagedKey: zod.z.string().optional(),
+  url: zod.z.string().optional(),
+  putUrl: zod.z.string().optional(),
+  getUrl: zod.z.string().optional(),
+  entry: entry.nullish(),
+  entries: entry.array().optional(),
+  created: zod.z.boolean().optional(),
+  error: zod.z.object({ code: zod.z.string(), message: zod.z.string() }).optional()
+});
+var fsOutputWithEntry = fsOutput.extend({ entry });
 var STAGE_OVER_BYTES = 2 << 20;
 async function toBytes(data) {
   if (typeof data === "string") return Buffer.from(data, "utf8");
@@ -71,16 +102,18 @@ var Files = class {
     this.turn = turn;
   }
   turn;
-  async call(fn, input, fresh = false) {
-    const out = await this.turn(`$fs.${fn}`, input, fresh);
-    if (out.error) throw new FilesystemError(out.error.code, out.error.message);
-    return out;
-  }
-  async read(path, opts = {}) {
-    const out = await this.call("read", { path });
+  async call(fn, input, fresh = false, schema = fsOutput) {
+    const out = fsOutput.parse(await this.turn(`$fs.${fn}`, input, fresh));
+    if (out.error)
+      throw new FilesystemError(out.error.code, out.error.message);
+    return schema.parse(out);
+  }
+  async read(p, opts = {}) {
+    const { format } = readOpts.parse(opts);
+    const out = await this.call("read", { path: path.parse(p) });
     const bytes = out.url ? await this.readStaged(out.url, out.stagedKey) : Buffer.from(out.content ?? "", "base64");
-    if (opts.format === "bytes") return new Uint8Array(bytes);
-    if (opts.format === "blob") return new Blob([new Uint8Array(bytes)]);
+    if (format === "bytes") return new Uint8Array(bytes);
+    if (format === "blob") return new Blob([new Uint8Array(bytes)]);
     return bytes.toString("utf8");
   }
   /** A replayed durable read may hold a URL that has expired; the provider signs the same staged file again. The renewal is a plain run, not a durable child, so the replayed child sequence stays aligned. */
@@ -95,11 +128,12 @@ var Files = class {
   }
   async write(pathOrFiles, data) {
     if (typeof pathOrFiles !== "string") return this.writeFiles(pathOrFiles);
-    const [entry] = await this.writeFiles([{ path: pathOrFiles, data: data ?? "" }]);
-    return entry;
+    const [entry2] = await this.writeFiles([{ path: pathOrFiles, data: data ?? "" }]);
+    return entry2;
   }
   /** Writes several files in one task. */
   async writeFiles(files) {
+    writeEntries.parse(files);
     const bytes = await Promise.all(files.map((f) => toBytes(f.data)));
     const encoded = [];
     for (const [i, f] of files.entries()) {
@@ -119,58 +153,70 @@ var Files = class {
       }
     }
     const { entries = [] } = await this.call("write", { files: encoded });
-    return entries.map(toEntry);
+    return entries;
   }
   /** Lists a directory. `depth` 1 (default) is the directory itself; higher values recurse. No snapshot is made. */
-  async list(path = ".", opts = {}) {
-    const { entries = [] } = await this.call("list", { path, depth: opts.depth ?? 1 });
-    return entries.map(toEntry);
+  async list(p = ".", opts = {}) {
+    const { depth = 1 } = listOpts.parse(opts);
+    const { entries = [] } = await this.call("list", { path: path.parse(p), depth });
+    return entries;
   }
   /** True if the path exists. No snapshot is made. */
-  async exists(path) {
-    const { entry } = await this.call("stat", { path });
-    return entry != null;
+  async exists(p) {
+    const { entry: entry2 } = await this.call("stat", { path: path.parse(p) });
+    return entry2 != null;
   }
   /** Metadata of a file or directory. Throws `FilesystemError` with code `not_found` if absent. */
-  async getInfo(path) {
-    const { entry } = await this.call("stat", { path });
-    if (!entry) throw new FilesystemError("not_found", `${path} does not exist`);
-    return toEntry(entry);
+  async getInfo(p) {
+    const { entry: entry2 } = await this.call("stat", { path: path.parse(p) });
+    if (!entry2) throw new FilesystemError("not_found", `${p} does not exist`);
+    return entry2;
   }
   /** Creates a directory and its parents. Returns false if it already existed. */
-  async makeDir(path) {
-    const { created } = await this.call("mkdir", { path });
+  async makeDir(p) {
+    const { created } = await this.call("mkdir", { path: path.parse(p) });
     return created === true;
   }
   /** Renames or moves a file or directory. */
   async rename(oldPath, newPath) {
-    const { entry } = await this.call("rename", { path: oldPath, newPath });
-    return toEntry(entry);
+    const { entry: entry2 } = await this.call(
+      "rename",
+      { path: path.parse(oldPath), newPath: path.parse(newPath) },
+      false,
+      fsOutputWithEntry
+    );
+    return entry2;
   }
   /** Copies a file or directory tree. */
   async copy(srcPath, dstPath) {
-    const { entry } = await this.call("copy", { path: srcPath, newPath: dstPath });
-    return toEntry(entry);
+    const { entry: entry2 } = await this.call(
+      "copy",
+      { path: path.parse(srcPath), newPath: path.parse(dstPath) },
+      false,
+      fsOutputWithEntry
+    );
+    return entry2;
   }
   /** Deletes a file or directory tree. */
-  async remove(path) {
-    await this.call("remove", { path });
+  async remove(p) {
+    await this.call("remove", { path: path.parse(p) });
   }
   /** The provider fetches an https URL into the workspace. The sandbox needs no network. Private and loopback addresses are refused. */
-  async download(url, path, opts = {}) {
-    const { entry } = await this.call("download", {
-      url,
-      path,
-      ...opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}
-    });
-    return toEntry(entry);
+  async download(url, p, opts = {}) {
+    const { entry: entry2 } = await this.call(
+      "download",
+      { url: httpsUrl.parse(url), path: path.parse(p), ...transferOpts.parse(opts) },
+      false,
+      fsOutputWithEntry
+    );
+    return entry2;
   }
   /** The provider sends a workspace file to an https URL with HTTP PUT, for example a presigned URL. */
-  async upload(path, url, opts = {}) {
+  async upload(p, url, opts = {}) {
     await this.call("upload", {
-      path,
-      url,
-      ...opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}
+      path: path.parse(p),
+      url: httpsUrl.parse(url),
+      ...transferOpts.parse(opts)
     });
   }
 };
@@ -192,6 +238,43 @@ async function setupTelemetry() {
     console.error(`sandbox: opentelemetry disabled: ${err.message}`);
   }
 }
+var positiveInt2 = zod.z.int().positive();
+var metadata = zod.z.record(zod.z.string(), zod.z.string());
+var resources = zod.z.strictObject({
+  vcpu: positiveInt2.optional(),
+  memoryMib: positiveInt2.optional(),
+  diskMib: positiveInt2.optional()
+});
+var turnInput = zod.z.strictObject({
+  fn: zod.z.string().min(1),
+  input: zod.z.record(zod.z.string(), zod.z.unknown()),
+  sandboxId: zod.z.string().min(1).optional(),
+  image: zod.z.string().min(1).optional(),
+  snapshotId: zod.z.string().min(1).optional(),
+  metadata: metadata.optional(),
+  idleTtlMs: positiveInt2.optional(),
+  inheritMetadata: zod.z.boolean().optional(),
+  resources: resources.optional()
+});
+var turnResult = zod.z.looseObject({
+  output: zod.z.looseObject({}),
+  sandboxId: zod.z.string(),
+  snapshotId: zod.z.string().optional(),
+  timings: zod.z.record(zod.z.string(), zod.z.number()).optional()
+});
+var commandOutput = zod.z.looseObject({
+  stdout: zod.z.string(),
+  stderr: zod.z.string(),
+  exitCode: zod.z.int()
+});
+var sandboxInfo = zod.z.looseObject({
+  sandboxId: zod.z.string(),
+  metadata: metadata.optional(),
+  live: zod.z.boolean(),
+  latestSnapshot: zod.z.string().optional(),
+  createdAt: zod.z.coerce.date(),
+  lastUsed: zod.z.coerce.date().optional()
+});
 
 // src/sandbox.ts
 var TASK_NAMES = ["hatchet-sandbox", "brickie-sandbox"];
@@ -229,6 +312,11 @@ function resolveTaskName(client) {
   }
   return pending;
 }
+var positiveInt3 = zod.z.int().positive();
+var nonEmpty = zod.z.string().min(1);
+var commandResult = commandOutput.extend(
+  turnResult.pick({ snapshotId: true, timings: true }).shape
+);
 var UNITS = {
   K: 1e3,
   M: 1e6,
@@ -239,38 +327,55 @@ var UNITS = {
   Gi: 2 ** 30,
   Ti: 2 ** 40
 };
-function toMib(value, field) {
-  if (typeof value === "number") {
-    if (!Number.isInteger(value) || value <= 0)
-      throw new Error(`resources.${field}: expected a positive whole number of MiB`);
-    return value;
-  }
-  const m = /^(\d+(?:\.\d+)?)\s*([KMGT]i?)?B?$/.exec(value.trim());
-  if (!m)
-    throw new Error(
-      `resources.${field}: expected a quantity like '512Mi', '4Gi' or '8G', got ${JSON.stringify(value)}`
-    );
-  const bytes = Number(m[1]) * (m[2] ? UNITS[m[2]] : UNITS.Mi);
-  const mib = Math.ceil(bytes / UNITS.Mi);
-  if (mib <= 0) throw new Error(`resources.${field}: must be at least 1Mi`);
-  return mib;
-}
-function wireResources(r) {
-  const out = {};
-  if (r.vcpu !== void 0) {
-    if (!Number.isInteger(r.vcpu) || r.vcpu <= 0)
-      throw new Error("resources.vcpu: expected a positive whole number of cores");
-    out.vcpu = r.vcpu;
-  }
-  if (r.memory !== void 0) out.memoryMib = toMib(r.memory, "memory");
-  if (r.disk !== void 0) out.diskMib = toMib(r.disk, "disk");
-  if (Object.keys(out).length === 0)
-    throw new Error("resources: set at least one of vcpu, memory, disk");
-  return out;
-}
+var QUANTITY = /^(\d+(?:\.\d+)?)\s*([KMGT]i?)B?$/;
+var mib = zod.z.union(
+  [
+    positiveInt3,
+    zod.z.string().trim().regex(QUANTITY).transform((s) => {
+      const [, n, unit] = QUANTITY.exec(s);
+      return Math.ceil(Number(n) * UNITS[unit] / UNITS.Mi);
+    }).pipe(zod.z.int().min(1))
+  ],
+  {
+    error: "expected a positive whole number of MiB or a quantity with a unit like '512Mi', '4Gi' or '8G'"
+  }
+);
+var resources2 = zod.z.strictObject({
+  vcpu: positiveInt3.optional(),
+  memory: mib.optional(),
+  disk: mib.optional()
+}).refine(
+  (r) => r.vcpu !== void 0 || r.memory !== void 0 || r.disk !== void 0,
+  "set at least one of vcpu, memory, disk"
+).transform(({ vcpu, memory, disk }) => ({ vcpu, memoryMib: memory, diskMib: disk }));
+var sandboxOpts = zod.z.strictObject({
+  id: zod.z.string().regex(/^[a-z0-9-]+$/, "lowercase letters, digits, and hyphens only").optional(),
+  template: nonEmpty.optional(),
+  from: nonEmpty.optional(),
+  metadata: metadata.optional(),
+  idleTimeoutMs: positiveInt3.optional(),
+  inheritParentMetadata: zod.z.boolean().optional(),
+  provider: nonEmpty.optional(),
+  resources: resources2.optional()
+}).refine((o) => !o.inheritParentMetadata || o.from !== void 0, {
+  error: "inheritParentMetadata needs from",
+  path: ["inheritParentMetadata"]
+});
+var execOpts = zod.z.strictObject({ timeoutMs: positiveInt3.optional() });
+var connectOpts = zod.z.strictObject({ template: nonEmpty.optional() });
+var listOpts2 = zod.z.strictObject({
+  sandboxId: nonEmpty.optional(),
+  metadata: metadata.optional()
+});
+var deleteOpts = listOpts2.refine(
+  (o) => o.sandboxId !== void 0 || Object.keys(o.metadata ?? {}).length > 0,
+  "delete needs a sandboxId or a metadata filter"
+);
 function turnRunner(client) {
   const resolved = resolveTaskName(client);
-  return async (input, opts) => {
+  return async (raw, opts) => {
+    const input = turnInput.parse(raw);
+    const payload = input;
     const name = await resolved;
     const additionalMetadata = {
       "hatchet.sandbox.fn": input.fn,
@@ -278,10 +383,10 @@ function turnRunner(client) {
       ...input.image ? { "hatchet.sandbox.image": input.image } : {},
       ...input.snapshotId ? { "hatchet.sandbox.from": input.snapshotId } : {}
     };
-    const result = opts?.fresh ? await (await client.admin.runWorkflow(name, input, {
+    const result = opts?.fresh ? await (await client.admin.runWorkflow(name, payload, {
       additionalMetadata
-    })).result() : await client.workflow({ name }).run(input, { additionalMetadata });
-    return result[name] ?? result;
+    })).result() : await client.workflow({ name }).run(payload, { additionalMetadata });
+    return turnResult.parse(result[name] ?? result);
   };
 }
 var Sandbox = class _Sandbox {
@@ -298,54 +403,40 @@ var Sandbox = class _Sandbox {
   files;
   /** Starts a new sandbox. Prefer `hatchet.sandbox.create`. */
   static async create(client, opts = {}) {
+    const o = sandboxOpts.parse(opts);
     await setupTelemetry();
     const run = turnRunner(client);
-    const metadata = opts.provider ? { ...opts.metadata, provider: opts.provider } : opts.metadata;
     const created = await run({
       fn: "$create",
       input: {},
-      ...opts.id ? { sandboxId: opts.id } : {},
-      ...opts.template ? { image: opts.template } : {},
-      ...opts.from ? { snapshotId: opts.from } : {},
-      ...metadata ? { metadata } : {},
-      ...opts.idleTimeoutMs ? { idleTtlMs: opts.idleTimeoutMs } : {},
-      ...opts.inheritParentMetadata ? { inheritMetadata: true } : {},
-      ...opts.resources ? { resources: wireResources(opts.resources) } : {}
+      sandboxId: o.id,
+      image: o.template,
+      snapshotId: o.from,
+      metadata: o.provider ? { ...o.metadata, provider: o.provider } : o.metadata,
+      idleTtlMs: o.idleTimeoutMs,
+      inheritMetadata: o.inheritParentMetadata,
+      resources: o.resources
     });
-    return new _Sandbox(run, created.sandboxId, opts.template);
+    return new _Sandbox(run, created.sandboxId, o.template);
   }
   /** Attaches to a sandbox by ID. Prefer `hatchet.sandbox.connect`. */
   static async connect(client, sandboxId, opts = {}) {
+    const id = nonEmpty.parse(sandboxId);
+    const o = connectOpts.parse(opts);
     await setupTelemetry();
     const run = turnRunner(client);
-    await run({
-      fn: "$connect",
-      input: {},
-      sandboxId,
-      ...opts.template ? { image: opts.template } : {}
-    });
-    return new _Sandbox(run, sandboxId, opts.template);
+    await run({ fn: "$connect", input: {}, sandboxId: id, image: o.template });
+    return new _Sandbox(run, id, o.template);
   }
   /** Lists sandboxes on the provider. Prefer `hatchet.sandbox.list`. */
   static async list(client, opts = {}) {
-    const result = await turnRunner(client)({
-      fn: "$list",
-      input: {
-        ...opts.sandboxId ? { sandboxId: opts.sandboxId } : {},
-        ...opts.metadata ? { metadata: opts.metadata } : {}
-      }
-    });
-    const raw = result.output.sandboxes ?? [];
-    return raw.map((s) => ({
-      ...s,
-      createdAt: new Date(s.createdAt),
-      lastUsed: s.lastUsed ? new Date(s.lastUsed) : void 0
-    }));
+    const o = listOpts2.parse(opts);
+    const result = await turnRunner(client)({ fn: "$list", input: o });
+    return sandboxInfo.array().parse(result.output.sandboxes ?? []);
   }
   /** Deletes every sandbox matching the filter, with all their snapshots and files. Prefer `hatchet.sandbox.delete`. */
   static async delete(client, opts) {
-    if (!opts.sandboxId && Object.keys(opts.metadata ?? {}).length === 0)
-      throw new Error("delete needs a sandboxId or a metadata filter");
+    deleteOpts.parse(opts);
     const run = turnRunner(client);
     const ids = [];
     for (const { sandboxId } of await _Sandbox.list(client, opts)) {
@@ -356,10 +447,8 @@ var Sandbox = class _Sandbox {
   }
   /** Runs a shell command with `sh -c` in the workspace and makes a snapshot. A timeout gives `exitCode` 124, not an error. */
   async exec(cmd, opts = {}) {
-    return this.turn("$command", {
-      cmd,
-      ...opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}
-    });
+    const input = { cmd: nonEmpty.parse(cmd), ...execOpts.parse(opts) };
+    return commandResult.parse(await this.turn("$command", input));
   }
   /** Removes the sandbox. Its snapshots stay; `connect` can bring it back. */
   async kill() {
@@ -371,12 +460,7 @@ var Sandbox = class _Sandbox {
   }
   async turn(fn, input, fresh = false) {
     const result = await this.run(
-      {
-        sandboxId: this.sandboxId,
-        ...this.template ? { image: this.template } : {},
-        fn,
-        input
-      },
+      { sandboxId: this.sandboxId, image: this.template, fn, input },
       { fresh }
     );
     return {