@hatchet-dev/sandbox 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Eac
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-10-29
+
+### Added
+
+- `create({ from, inheritParentMetadata: true })` copies the parent sandbox's metadata onto the fork; tags given in `metadata` take precedence.
+- `hatchet.sandbox.delete({ sandboxId?, metadata? })` and `sandbox.delete()`: remove sandboxes together with every snapshot and file stored for them. `kill()` keeps snapshots as before.
+
+### Fixed
+
+- `files.read` of a staged file replayed in a durable task after its signed URL expired now asks the provider to sign the same file again instead of failing with `staging_failed`.
+
 ## [0.1.0] - 2026-10-27
 
 ### Added

package/README.md

@@ -65,6 +65,7 @@ Your app only talks to Hatchet. A brickie provider, connected to the same tenant
 | `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`:
 
@@ -74,6 +75,7 @@ Options for `create`:
 | `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. |
 
 ### `Sandbox`
@@ -81,7 +83,8 @@ Options for `create`:
 | 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` | Removes the sandbox. The snapshots stay, so `connect` still works. |
+| `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. |
 
@@ -110,6 +113,7 @@ The sandbox itself does not need network access for any of this.
 - `FilesystemError` has a `code`. One of: `not_found`, `invalid_path`, `invalid_url`, `invalid_content`, `invalid`, `is_a_directory`, `not_a_directory`, `too_large`, `staging_failed`, `transfer_failed`.
 - A command that fails does not throw. Look at `exitCode`.
 - `connect` with an unknown ID throws. `create` with an `id` that already exists throws too. Use `connect` for that one, or pick a new ID.
+- `hatchet.sandbox.delete` without a `sandboxId` or a non-empty `metadata` filter throws before touching anything. Metadata matching is a subset match, the same as `list`: a filter of `{ a, b }` matches a sandbox tagged `{ a, b, c }`.
 
 ## Telemetry
 

package/dist/files.d.ts

@@ -1,5 +1,5 @@
 import type { JsonObject } from '@hatchet-dev/typescript-sdk/v1';
-export type FileType = 'file' | 'dir' | 'symlink';
+export type FileType = 'file' | 'dir';
 export interface EntryInfo {
     name: string;
     path: string;
@@ -8,7 +8,6 @@ export interface EntryInfo {
     mode: number;
     permissions: string;
     modifiedTime?: Date;
-    symlinkTarget?: string;
 }
 export type FileData = string | ArrayBuffer | Uint8Array | Blob;
 export interface WriteEntry {
@@ -56,7 +55,7 @@ export declare class Files {
     /** @internal */
     constructor(turn: FsTurn);
     private call;
-    /** Reads a file as text (default), bytes, or a Blob. Files over the provider's `--max-file-bytes` (2 MiB) come through the provider's object store instead of Hatchet. */
+    /** Reads a file as text (default), bytes, or a Blob. Files over the provider's `--max-file-bytes` (2 MiB) come through the provider's `--store` instead of Hatchet. */
     read(path: string, opts?: ReadOpts & {
         format?: 'text';
     }): Promise<string>;
@@ -66,7 +65,9 @@ export declare class Files {
     read(path: string, opts: ReadOpts & {
         format: 'blob';
     }): Promise<Blob>;
-    /** Writes one file or several. Parent directories are created. Bytes are stored exactly. Files over 2 MiB go through the provider's object store instead of Hatchet. */
+    /** A replayed durable read may hold a URL that has expired; the provider signs the same staged file again. */
+    private readStaged;
+    /** Writes one file or several. Parent directories are created. Bytes are stored exactly. Files over 2 MiB go through the provider's `--store` instead of Hatchet. */
     write(path: string, data: FileData): Promise<EntryInfo>;
     write(files: WriteEntry[]): Promise<EntryInfo[]>;
     /** Writes several files in one task. */

package/dist/files.js

@@ -70,10 +70,7 @@ async function putStaged(url, bytes) {
 }
 async function getStaged(url) {
     if (url.startsWith('file://')) {
-        const path = decodeURIComponent(url.slice('file://'.length));
-        const bytes = await fs.readFile(path);
-        await fs.rm(path, { force: true });
-        return bytes;
+        return fs.readFile(decodeURIComponent(url.slice('file://'.length)));
     }
     const res = await fetch(url);
     if (!res.ok)
@@ -95,13 +92,25 @@ class Files {
     }
     async read(path, opts = {}) {
         const out = await this.call('read', { path });
-        const bytes = out.url ? await getStaged(out.url) : Buffer.from(out.content ?? '', 'base64');
+        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. */
+    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 });
+            return getStaged(getUrl);
+        }
+    }
     async write(pathOrFiles, data) {
         if (typeof pathOrFiles !== 'string')
             return this.writeFiles(pathOrFiles);

package/dist/sandbox.d.ts

@@ -23,6 +23,8 @@ export interface SandboxOpts {
     metadata?: Record<string, string>;
     /** Milliseconds without a turn before the provider removes the sandbox. Capped by the provider. */
     idleTimeoutMs?: number;
+    /** With `from`, start from the metadata of the sandbox that made that snapshot. Pairs given in `metadata` take precedence over inherited ones. */
+    inheritParentMetadata?: boolean;
 }
 export interface ExecOpts {
     /** Kill the command after this long. The result then has `exitCode` 124. */
@@ -61,10 +63,14 @@ export declare class Sandbox {
     static connect(client: HatchetClient, sandboxId: string, opts?: ConnectOpts): Promise<Sandbox>;
     /** Lists sandboxes on the provider. Prefer `hatchet.sandbox.list`. */
     static list(client: HatchetClient, opts?: SandboxListOpts): Promise<SandboxInfo[]>;
+    /** Deletes every sandbox matching the filter, with all their snapshots and files. Prefer `hatchet.sandbox.delete`. */
+    static delete(client: HatchetClient, opts: SandboxListOpts): Promise<string[]>;
     /** Runs a shell command with `sh -c` in the workspace and makes a snapshot. A timeout gives `exitCode` 124, not an error. */
     exec(cmd: string, opts?: ExecOpts): Promise<CommandResult>;
     /** Removes the sandbox. Its snapshots stay; `connect` can bring it back. */
     kill(): Promise<void>;
+    /** Removes the sandbox and deletes every snapshot and file the provider stored for it. `connect` fails afterwards. */
+    delete(): Promise<void>;
     private turn;
 }
 /** `hatchet.sandbox`, added to `HatchetClient` by importing `@hatchet-dev/sandbox`. */
@@ -75,6 +81,8 @@ export interface SandboxNamespace {
     connect(sandboxId: string, opts?: ConnectOpts): Promise<Sandbox>;
     /** Lists sandboxes the provider knows, filtered by ID or metadata. */
     list(opts?: SandboxListOpts): Promise<SandboxInfo[]>;
+    /** Deletes the sandboxes matching the filter, with every snapshot and file stored for them. Returns their IDs. */
+    delete(opts: SandboxListOpts): Promise<string[]>;
 }
 declare module '@hatchet-dev/typescript-sdk/v1' {
     interface HatchetClient {

package/dist/sandbox.js

@@ -44,6 +44,7 @@ class Sandbox {
             ...(opts.from ? { snapshotId: opts.from } : {}),
             ...(opts.metadata ? { metadata: opts.metadata } : {}),
             ...(opts.idleTimeoutMs ? { idleTtlMs: opts.idleTimeoutMs } : {}),
+            ...(opts.inheritParentMetadata ? { inheritMetadata: true } : {}),
         });
         return new Sandbox(run, created.sandboxId, opts.template);
     }
@@ -63,6 +64,18 @@ class Sandbox {
         const raw = (result.output.sandboxes ?? []);
         return raw.map((s) => ({ ...s, createdAt: new Date(s.createdAt), lastUsed: s.lastUsed ? new Date(s.lastUsed) : undefined }));
     }
+    /** 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 } : {}) });
@@ -71,6 +84,10 @@ class Sandbox {
     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) {
         const result = await this.run({
             sandboxId: this.sandboxId,
@@ -89,6 +106,7 @@ Object.defineProperty(v1_1.HatchetClient.prototype, 'sandbox', {
             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),
         };
     },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatchet-dev/sandbox",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Hatchet Sandbox TypeScript SDK",
   "license": "MIT",
   "repository": {
@@ -34,12 +34,14 @@
   "devDependencies": {
     "@hatchet-dev/typescript-sdk": "^1.33.1",
     "@types/node": "^24.0.0",
+    "tsx": "^4.23.15",
     "typedoc": "^0.28.0",
     "typescript": "^5.9.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc",
-    "docs": "typedoc"
+    "docs": "typedoc",
+    "test": "node --import tsx --test --test-force-exit --test-timeout=180000 test/e2e.test.ts"
   }
 }