@hatchet-dev/sandbox 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,11 +1,35 @@
 # Changelog
 
-All notable changes to `@hatchet-dev/sandbox`, the TypeScript SDK. The provider has its own changelog at the repository root.
+All notable changes to `@hatchet-dev/sandbox`, the TypeScript SDK.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Each release reads its notes from the matching section here.
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-11-09
+
+### Added
+
+- `create({ resources })` asks the provider for a machine size, `{ vcpu, memory, disk }`. `memory` and `disk` take a number of MiB or a Kubernetes quantity such as `'512Mi'`, `'4Gi'` or `'8G'`, and travel as `memoryMib` and `diskMib` on the wire. A provider that cannot honour a field fails the create with its own message, so plan limits show up as the task error. A provider that does not know the option ignores it. On Hatchet Cloud, Archil sizes the sandbox on create and forks keep the source's size, so `resources` with `from` is rejected there. Daytona and Freestyle resize after create, which on Daytona needs resizing enabled for the organization and on Freestyle can only grow. E2B sizes on the template and rejects the option.
+
+## [0.1.2] - 2026-11-03
+
+### Added
+
+- `create({ provider })` picks the sandbox provider by name when a tenant has more than one. It is sent as the `provider` metadata tag, so providers that already read that tag need no change.
+- The SDK works against any sandbox provider. On first use it checks whether the tenant serves the `hatchet-sandbox` task and uses that; otherwise it keeps using `brickie-sandbox`. Existing deployments need no change. A tenant should serve one of the two: turning on `hatchet-sandbox` while durable tasks that already called `brickie-sandbox` are in flight makes those tasks fail on resume with a non-determinism error, so drain them first.
+- `HATCHET_SANDBOX_OTEL=false` turns the OpenTelemetry instrumentor off. `BRICKIE_OTEL=false` still works.
+
+### Changed
+
+- The package declares `sideEffects: true` so bundlers keep the import that adds `hatchet.sandbox` to the client.
+- Run metadata tags are now `hatchet.sandbox.fn`, `hatchet.sandbox.id`, `hatchet.sandbox.image` and `hatchet.sandbox.from` (were `brickie.fn`, `brickie.sandbox`, `brickie.image`, `brickie.from`). Update any dashboard or run filter that keys on the old names.
+
+### Fixed
+
+- `files.write` of a staged file replayed in a durable task after its signed upload URL expired now asks the provider for a new URL instead of failing with `staging_failed`. For both `write` and `read`, that renewal is a plain task run rather than a durable child, so it does not shift the replayed child sequence.
+- `files.write` with several files over 2 MiB converts every input first and then takes staged keys in file order, so a durable replay assigns the same key to the same file.
+
 ## [0.1.1] - 2026-10-29
 
 ### Added

package/README.md

@@ -7,9 +7,11 @@
 
 </div>
 
-Run agent sandboxes from [Hatchet](https://hatchet.run) tasks.
+Run sandboxes from [Hatchet](https://hatchet.run) tasks, on the sandbox vendor of your choice.
 
-A sandbox is a workspace with a shell. You run commands in it and read and write its files. Each call is a Hatchet task. Each call that changes files takes a snapshot. You can start a new sandbox from any snapshot, and you can come back to a sandbox later by its ID. If you use it inside a durable task, a crash picks up where it left off.
+A sandbox is a workspace with a shell. You run commands in it and read and write its files. Each call is a Hatchet task and corresponds to a snapshot. You can start a new sandbox from any snapshot, and you can come back to a sandbox later by its ID. If you use it inside a durable task, a crash picks up where it left off.
+
+Your code only talks to Hatchet. The sandbox itself runs on a provider you connect to your tenant.
 
 ## Install
 
@@ -54,39 +56,56 @@ const again = await hatchet.sandbox.connect('conv-42');
 await again.exec('cat haiku.txt');
 ```
 
-Your app only talks to Hatchet. A brickie provider, connected to the same tenant, runs the sandboxes. Set `HATCHET_CLIENT_TOKEN` like you would for any Hatchet client. That is all the app needs.
+Set `HATCHET_CLIENT_TOKEN` like you would for any Hatchet client.
+
+## Providers
+
+A provider is a sandbox vendor connected to your Hatchet tenant, configured once in the dashboard under `Sandboxes` with the vendor's API key and optional configuration values.
+
+We currently support the following vendors:
+
+- [Daytona](https://www.daytona.io)
+- [E2B](https://e2b.dev)
+- [Archil](https://archil.com)
+- [Freestyle](https://freestyle.sh).
+
+```ts
+const sandbox = await hatchet.sandbox.create({ provider: 'e2b' });
+```
 
 ## API
 
 ### `hatchet.sandbox`
 
-| Call | Returns | What it does |
-|---|---|---|
-| `create(opts?)` | `Sandbox` | Starts a sandbox. |
-| `connect(id, { template? })` | `Sandbox` | Picks up a sandbox from its latest snapshot. Starts it again if it was stopped. Throws if the ID does not exist. |
-| `list({ sandboxId?, metadata? })` | `SandboxInfo[]` | Finds sandboxes by ID or by metadata. All given pairs must match. |
-| `delete({ sandboxId?, metadata? })` | `string[]` | Deletes every matching sandbox with all of its snapshots and files, and returns their IDs. One filter is required. |
+| Call                                | Returns         | What it does                                                                                                       |
+| ----------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `create(opts?)`                     | `Sandbox`       | Starts a sandbox.                                                                                                  |
+| `connect(id, { template? })`        | `Sandbox`       | Picks up a sandbox from its latest snapshot. Starts it again if it was stopped. Throws if the ID does not exist.   |
+| `list({ sandboxId?, metadata? })`   | `SandboxInfo[]` | Finds sandboxes by ID or by metadata. All given pairs must match.                                                  |
+| `delete({ sandboxId?, metadata? })` | `string[]`      | Deletes every matching sandbox with all of its snapshots and files, and returns their IDs. One filter is required. |
 
 Options for `create`:
 
-| Option | What it does |
-|---|---|
-| `id` | Pick your own sandbox ID. Lowercase letters, digits, and hyphens. It must not exist yet. |
-| `template` | The container image. Defaults to the provider's image. |
-| `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` | Remove the sandbox after this long with no calls. The provider sets the maximum. |
+| 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. |
 
 ### `Sandbox`
 
-| Call | Returns | What it does |
-|---|---|---|
+| Call                        | Returns                                               | What it does                                                                                                                                    |
+| --------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | `exec(cmd, { timeoutMs? })` | `{ stdout, stderr, exitCode, snapshotId?, timings? }` | Runs `sh -c cmd` in the workspace and takes a snapshot. A non-zero exit code is a normal result, not an error. On timeout the exit code is 124. |
-| `kill()` | `void` | Stops the sandbox. The snapshots stay, so `connect` still works. |
-| `delete()` | `void` | Stops the sandbox and deletes every snapshot and file stored for it. `connect` fails afterwards. |
-| `sandboxId` | `string` | The ID to use with `connect` later. |
-| `files` | `Files` | The file API below. |
+| `kill()`                    | `void`                                                | Stops the sandbox. The snapshots stay, so `connect` still works.                                                                                |
+| `delete()`                  | `void`                                                | Stops the sandbox and deletes every snapshot and file stored for it. `connect` fails afterwards.                                                |
+| `sandboxId`                 | `string`                                              | The ID to use with `connect` later.                                                                                                             |
+| `files`                     | `Files`                                               | The file API below.                                                                                                                             |
 
 Each result also has `timings` in milliseconds for `claim`, `restore`, `exec`, and `checkpoint`, and the `snapshotId` the call made.
 
@@ -94,19 +113,17 @@ Each result also has `timings` in milliseconds for `claim`, `restore`, `exec`, a
 
 Paths are relative to the workspace. A path that points outside it throws a `FilesystemError` with code `invalid_path`.
 
-| Call | What it does |
-|---|---|
-| `read(path, { format? })` | Reads a file. `format` is `'text'` (default), `'bytes'` for a `Uint8Array`, or `'blob'`. |
-| `write(path, data)` or `write([{ path, data }, ...])` | Writes one file or many. `data` can be a string, `ArrayBuffer`, `Uint8Array`, or `Blob`. |
-| `list(path?, { depth? })` | Lists entries with name, path, type, size, mode, permissions, and modified time. |
-| `exists(path)`, `getInfo(path)` | Checks a path or gets its info. |
-| `makeDir(path)`, `rename(from, to)`, `copy(from, to)`, `remove(path)` | The usual file operations. |
-| `download(url, path, { timeoutMs? })` | The provider fetches an https URL into the workspace. Private and loopback addresses are refused. |
-| `upload(path, url, { timeoutMs? })` | The provider sends a file to an https URL with HTTP PUT. Presigned URLs work well here. |
-
-The sandbox itself does not need network access for any of this.
+| Call                                                                  | What it does                                                                                      |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `read(path, { format? })`                                             | Reads a file. `format` is `'text'` (default), `'bytes'` for a `Uint8Array`, or `'blob'`.          |
+| `write(path, data)` or `write([{ path, data }, ...])`                 | Writes one file or many. `data` can be a string, `ArrayBuffer`, `Uint8Array`, or `Blob`.          |
+| `list(path?, { depth? })`                                             | Lists entries with name, path, type, size, mode, permissions, and modified time.                  |
+| `exists(path)`, `getInfo(path)`                                       | Checks a path or gets its info.                                                                   |
+| `makeDir(path)`, `rename(from, to)`, `copy(from, to)`, `remove(path)` | The usual file operations.                                                                        |
+| `download(url, path, { timeoutMs? })`                                 | The provider fetches an https URL into the workspace. Private and loopback addresses are refused. |
+| `upload(path, url, { timeoutMs? })`                                   | The provider sends a file to an https URL with HTTP PUT. Presigned URLs work well here.           |
 
-`read` and `write` carry up to 2 MiB through Hatchet. Bigger files go through the provider's object store (`--object-store` on the provider: S3, GCS, Azure Blob, or a local folder) and never pass through Hatchet. You call the same methods either way.
+`read` and `write` carry up to 2 MiB through Hatchet. Providers with an object store stage bigger files there and never pass them through Hatchet; you call the same methods either way.
 
 ## Errors
 
@@ -117,17 +134,17 @@ The sandbox itself does not need network access for any of this.
 
 ## Telemetry
 
-On first use the SDK turns on the Hatchet OpenTelemetry instrumentor. If you have OpenTelemetry set up, sandbox calls show up as spans in your task's trace. Set `BRICKIE_OTEL=false` to turn this off.
+On first use the SDK turns on the Hatchet OpenTelemetry instrumentor. If you have OpenTelemetry set up, sandbox calls show up as spans in your task's trace. Set `HATCHET_SANDBOX_OTEL=false` to turn this off.
 
 ## What you need
 
-- A Hatchet tenant. Hatchet Cloud, or a self-hosted Hatchet v0.110.0 or newer with gRPC operators turned on.
-- A brickie provider connected to that tenant. It is one binary, `brickie worker`. Get it from [github.com/hatchet-dev/brickie](https://github.com/hatchet-dev/brickie).
+- A Hatchet Cloud tenant with sandboxes enabled.
+- At least one sandbox provider connected to that tenant, configured under Sandboxes in the dashboard with your Daytona, E2B, Archil, or Freestyle API key.
 
 ## Changelog
 
-See [CHANGELOG.md](https://github.com/hatchet-dev/brickie/blob/main/sdks/typescript/CHANGELOG.md).
+See [CHANGELOG.md](./CHANGELOG.md).
 
 ## License
 
-MIT. See [LICENSE](https://github.com/hatchet-dev/brickie/blob/main/LICENSE).
+MIT. See [LICENSE](./LICENSE).

package/dist/index.cjs

@@ -0,0 +1,405 @@
+'use strict';
+
+var v1 = require('@hatchet-dev/typescript-sdk/v1');
+var fs = require('fs/promises');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
+
+// src/sandbox.ts
+var FilesystemError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "FilesystemError";
+  }
+  code;
+};
+var toEntry = (e) => ({
+  ...e,
+  modifiedTime: e.modifiedTime ? new Date(e.modifiedTime) : void 0
+});
+var STAGE_OVER_BYTES = 2 << 20;
+async function toBytes(data) {
+  if (typeof data === "string") return Buffer.from(data, "utf8");
+  if (data instanceof Blob) return Buffer.from(await data.arrayBuffer());
+  if (data instanceof Uint8Array) return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+  return Buffer.from(data);
+}
+async function putStaged(url, bytes) {
+  if (url.startsWith("file://")) {
+    await fs__namespace.writeFile(decodeURIComponent(url.slice("file://".length)), bytes);
+    return;
+  }
+  const res = await fetch(url, {
+    method: "PUT",
+    body: new Uint8Array(bytes),
+    headers: { "Content-Type": "application/octet-stream" }
+  });
+  if (!res.ok)
+    throw new FilesystemError("staging_failed", `stage upload failed: HTTP ${res.status}`);
+}
+async function getStaged(url) {
+  if (url.startsWith("file://")) {
+    return fs__namespace.readFile(decodeURIComponent(url.slice("file://".length)));
+  }
+  const res = await fetch(url);
+  if (!res.ok)
+    throw new FilesystemError("staging_failed", `stage download failed: HTTP ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+var Files = class {
+  /** @internal */
+  constructor(turn) {
+    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 });
+    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)]);
+    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. */
+  async readStaged(url, stagedKey) {
+    try {
+      return await getStaged(url);
+    } catch (e) {
+      if (url.startsWith("file://") || !(e instanceof FilesystemError)) throw e;
+      const { getUrl } = await this.call("presign", { stagedKey }, true);
+      return getStaged(getUrl);
+    }
+  }
+  async write(pathOrFiles, data) {
+    if (typeof pathOrFiles !== "string") return this.writeFiles(pathOrFiles);
+    const [entry] = await this.writeFiles([{ path: pathOrFiles, data: data ?? "" }]);
+    return entry;
+  }
+  /** Writes several files in one task. */
+  async writeFiles(files) {
+    const bytes = await Promise.all(files.map((f) => toBytes(f.data)));
+    const encoded = [];
+    for (const [i, f] of files.entries()) {
+      const b = bytes[i];
+      if (b.length <= STAGE_OVER_BYTES) {
+        encoded.push({ path: f.path, content: b.toString("base64") });
+        continue;
+      }
+      const { stagedKey, putUrl } = await this.call("presign", {});
+      try {
+        await putStaged(putUrl, b);
+        encoded.push({ path: f.path, stagedKey });
+      } catch {
+        const again = await this.call("presign", {}, true);
+        await putStaged(again.putUrl, b);
+        encoded.push({ path: f.path, stagedKey: again.stagedKey });
+      }
+    }
+    const { entries = [] } = await this.call("write", { files: encoded });
+    return entries.map(toEntry);
+  }
+  /** 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);
+  }
+  /** True if the path exists. No snapshot is made. */
+  async exists(path) {
+    const { entry } = await this.call("stat", { path });
+    return entry != 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);
+  }
+  /** Creates a directory and its parents. Returns false if it already existed. */
+  async makeDir(path) {
+    const { created } = await this.call("mkdir", { path });
+    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);
+  }
+  /** Copies a file or directory tree. */
+  async copy(srcPath, dstPath) {
+    const { entry } = await this.call("copy", { path: srcPath, newPath: dstPath });
+    return toEntry(entry);
+  }
+  /** Deletes a file or directory tree. */
+  async remove(path) {
+    await this.call("remove", { path });
+  }
+  /** 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);
+  }
+  /** The provider sends a workspace file to an https URL with HTTP PUT, for example a presigned URL. */
+  async upload(path, url, opts = {}) {
+    await this.call("upload", {
+      path,
+      url,
+      ...opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}
+    });
+  }
+};
+
+// src/otel.ts
+var telemetryStarted = false;
+async function setupTelemetry() {
+  if (telemetryStarted || process.env.HATCHET_SANDBOX_OTEL === "false" || process.env.BRICKIE_OTEL === "false") {
+    return;
+  }
+  telemetryStarted = true;
+  try {
+    const [{ registerInstrumentations }, { HatchetInstrumentor }] = await Promise.all([
+      import('@opentelemetry/instrumentation'),
+      import('@hatchet-dev/typescript-sdk/opentelemetry/index.js')
+    ]);
+    registerInstrumentations({ instrumentations: [new HatchetInstrumentor()] });
+  } catch (err) {
+    console.error(`sandbox: opentelemetry disabled: ${err.message}`);
+  }
+}
+
+// src/sandbox.ts
+var TASK_NAMES = ["hatchet-sandbox", "brickie-sandbox"];
+var taskNames = /* @__PURE__ */ new WeakMap();
+async function registered(client, name) {
+  const namespace = client.config.namespace ?? "";
+  const full = name.startsWith(namespace) ? name : `${namespace}${name}`;
+  for (let offset = 0; ; ) {
+    const { rows = [] } = await client.workflows.list({ name: full, limit: 100, offset });
+    if (rows.some((w) => w.name === full)) return true;
+    if (rows.length === 0) return false;
+    offset += rows.length;
+  }
+}
+async function probe(client) {
+  for (const name of TASK_NAMES) {
+    if (await registered(client, name)) return name;
+  }
+  return void 0;
+}
+function resolveTaskName(client) {
+  let pending = taskNames.get(client);
+  if (!pending) {
+    pending = probe(client).then(
+      (name) => {
+        if (!name) taskNames.delete(client);
+        return name ?? TASK_NAMES[TASK_NAMES.length - 1];
+      },
+      (err) => {
+        taskNames.delete(client);
+        throw err;
+      }
+    );
+    taskNames.set(client, pending);
+  }
+  return pending;
+}
+var UNITS = {
+  K: 1e3,
+  M: 1e6,
+  G: 1e9,
+  T: 1e12,
+  Ki: 2 ** 10,
+  Mi: 2 ** 20,
+  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;
+}
+function turnRunner(client) {
+  const resolved = resolveTaskName(client);
+  return async (input, opts) => {
+    const name = await resolved;
+    const additionalMetadata = {
+      "hatchet.sandbox.fn": input.fn,
+      ...input.sandboxId ? { "hatchet.sandbox.id": input.sandboxId } : {},
+      ...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, {
+      additionalMetadata
+    })).result() : await client.workflow({ name }).run(input, { additionalMetadata });
+    return result[name] ?? result;
+  };
+}
+var Sandbox = class _Sandbox {
+  constructor(run, sandboxId, template) {
+    this.run = run;
+    this.sandboxId = sandboxId;
+    this.template = template;
+    this.files = new Files((fn, input, fresh) => this.turn(fn, input, fresh));
+  }
+  run;
+  sandboxId;
+  template;
+  /** File operations on the workspace. */
+  files;
+  /** Starts a new sandbox. Prefer `hatchet.sandbox.create`. */
+  static async create(client, 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) } : {}
+    });
+    return new _Sandbox(run, created.sandboxId, opts.template);
+  }
+  /** Attaches to a sandbox by ID. Prefer `hatchet.sandbox.connect`. */
+  static async connect(client, sandboxId, 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);
+  }
+  /** 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
+    }));
+  }
+  /** 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");
+    const run = turnRunner(client);
+    const ids = [];
+    for (const { sandboxId } of await _Sandbox.list(client, opts)) {
+      await run({ fn: "$delete", input: {}, sandboxId });
+      ids.push(sandboxId);
+    }
+    return ids;
+  }
+  /** 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 } : {}
+    });
+  }
+  /** Removes the sandbox. Its snapshots stay; `connect` can bring it back. */
+  async kill() {
+    await this.turn("$destroy", {});
+  }
+  /** Removes the sandbox and deletes every snapshot and file the provider stored for it. `connect` fails afterwards. */
+  async delete() {
+    await this.turn("$delete", {});
+  }
+  async turn(fn, input, fresh = false) {
+    const result = await this.run(
+      {
+        sandboxId: this.sandboxId,
+        ...this.template ? { image: this.template } : {},
+        fn,
+        input
+      },
+      { fresh }
+    );
+    return {
+      ...result.output,
+      snapshotId: result.snapshotId,
+      timings: result.timings
+    };
+  }
+};
+Object.defineProperty(v1.HatchetClient.prototype, "sandbox", {
+  configurable: true,
+  get() {
+    return {
+      create: (opts) => Sandbox.create(this, opts),
+      connect: (sandboxId, opts) => Sandbox.connect(this, sandboxId, opts),
+      list: (opts) => Sandbox.list(this, opts),
+      delete: (opts) => Sandbox.delete(this, opts)
+    };
+  }
+});
+
+exports.Files = Files;
+exports.FilesystemError = FilesystemError;
+exports.Sandbox = Sandbox;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map