@sapiom/sandbox 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @sapiom/sandbox
+
+## 0.2.0
+
+### Minor Changes
+
+- de766f0: Add @sapiom/sandbox package for sandbox environment lifecycle management
+
+### Patch Changes
+
+- Updated dependencies [c9ad2cb]
+  - @sapiom/fetch@0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sapiom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# @sapiom/sandbox
+
+Sandbox environment management for the Sapiom SDK. Create isolated execution environments, manage files, run commands, and stream output in real time.
+
+## Installation
+
+```bash
+npm install @sapiom/sandbox
+# or
+pnpm add @sapiom/sandbox
+```
+
+## Quickstart
+
+```typescript
+import { SapiomSandbox } from "@sapiom/sandbox";
+
+// Create a sandbox (uses SAPIOM_API_KEY env var by default)
+const sandbox = await SapiomSandbox.create({ name: "my-sandbox" });
+
+// Write a file
+await sandbox.writeFile("hello.py", 'print("Hello from the sandbox!")');
+
+// Execute a command and wait for completion
+const result = await sandbox.exec("python hello.py");
+console.log(result.stdout); // "Hello from the sandbox!"
+
+// Stream output from a long-running process
+const proc = await sandbox.execStream("node runner.js");
+for await (const line of proc.output) {
+  console.log(`[${line.stream}] ${line.data}`);
+}
+console.log("exit code:", proc.exitCode);
+
+// Clean up
+await sandbox.destroy();
+```
+
+## API
+
+### `SapiomSandbox.create(opts)`
+
+Creates a new sandbox and returns a handle for interacting with it.
+
+```typescript
+const sandbox = await SapiomSandbox.create({
+  name: "my-sandbox",
+  tier: "m",
+  ttl: "1h",
+  image: "python:3.12",
+  envs: { NODE_ENV: "production" },
+});
+```
+
+**Options:**
+
+| Option    | Type                     | Required | Description                                           |
+|-----------|--------------------------|----------|-------------------------------------------------------|
+| `name`    | `string`                 | Yes      | Sandbox name (lowercase alphanumeric + hyphens, 2-63 chars) |
+| `apiKey`  | `string`                 | No       | Sapiom API key. Falls back to `SAPIOM_API_KEY` env var |
+| `baseUrl` | `string`                 | No       | Override the sandbox service URL                       |
+| `fetch`   | `typeof fetch`           | No       | Pre-configured fetch function (overrides `apiKey`)     |
+| `tier`    | `SandboxTier`            | No       | Memory tier: `'xs'`, `'s'`, `'m'`, `'l'`, `'xl'` (default `'s'`) |
+| `ttl`     | `string`                 | No       | Time-to-live (e.g. `'1h'`, `'24h'`, `'7d'`)           |
+| `envs`    | `Record<string, string>` | No       | Environment variables                                  |
+| `port`    | `number`                 | No       | Single port to expose (mutually exclusive with `ports`) |
+| `ports`   | `PortSpec[]`             | No       | Array of port specs to expose (mutually exclusive with `port`) |
+| `image`   | `string`                 | No       | Pre-built Docker image for instant creation             |
+
+### `sandbox.writeFile(path, content)`
+
+Writes a file relative to the sandbox's workspace root.
+
+```typescript
+await sandbox.writeFile("src/index.ts", 'console.log("hi")');
+```
+
+### `sandbox.readFile(path)`
+
+Reads a file relative to the sandbox's workspace root and returns its content as a string.
+
+```typescript
+const content = await sandbox.readFile("src/index.ts");
+```
+
+### `sandbox.exec(command, opts?)`
+
+Executes a shell command inside the sandbox. By default waits for the process to finish.
+
+```typescript
+// Wait for completion (default)
+const result = await sandbox.exec("npm install");
+console.log(result.exitCode); // 0
+console.log(result.stdout);
+console.log(result.stderr);
+
+// Fire-and-forget
+const bg = await sandbox.exec("npm start", { waitForCompletion: false });
+console.log(bg.pid);
+
+// Check on it later
+const status = await sandbox.getProcess(bg.pid);
+console.log(status.completed, status.exitCode);
+
+// Or wait for it to finish
+const final = await sandbox.waitForProcess(bg.pid);
+console.log(final.exitCode);
+```
+
+**Options:**
+
+| Option               | Type                     | Default | Description                                      |
+|----------------------|--------------------------|---------|--------------------------------------------------|
+| `cwd`                | `string`                 | —       | Working directory (resolved relative to workspaceRoot) |
+| `env`                | `Record<string, string>` | —       | Environment variables for the process             |
+| `waitForCompletion`  | `boolean`                | `true`  | Wait for the process to finish                    |
+| `pollInterval`       | `number`                 | `1000`  | Polling interval in ms                            |
+| `timeout`            | `number`                 | `60000` | Timeout in ms when waiting                        |
+| `signal`             | `AbortSignal`            | —       | Signal to cancel the operation                    |
+
+### `sandbox.execStream(command, opts?)`
+
+Executes a command and streams output in real time via an async iterable. Ideal for long-running processes like AI agent runs.
+
+```typescript
+const proc = await sandbox.execStream("node agent.js");
+for await (const line of proc.output) {
+  // line.stream is 'stdout' or 'stderr'
+  process.stdout.write(line.data);
+}
+console.log("exit code:", proc.exitCode);
+```
+
+Supports cancellation via `AbortSignal`:
+
+```typescript
+const controller = new AbortController();
+const proc = await sandbox.execStream("long-task", {
+  signal: controller.signal,
+});
+
+setTimeout(() => controller.abort(), 30_000);
+
+for await (const line of proc.output) {
+  console.log(line.data);
+}
+```
+
+**Options:**
+
+| Option    | Type                     | Default | Description                                      |
+|-----------|--------------------------|---------|--------------------------------------------------|
+| `cwd`     | `string`                 | —       | Working directory (resolved relative to workspaceRoot) |
+| `env`     | `Record<string, string>` | —       | Environment variables for the process             |
+| `signal`  | `AbortSignal`            | —       | Signal to cancel the operation                    |
+
+### `sandbox.getProcess(pid)`
+
+Gets the current status of a process by PID.
+
+```typescript
+const status = await sandbox.getProcess(pid);
+console.log(status.completed, status.exitCode);
+```
+
+### `sandbox.waitForProcess(pid, opts?)`
+
+Waits for a process to complete by polling its status. Returns the same `ExecResult` as `exec()`.
+
+```typescript
+const result = await sandbox.waitForProcess(pid, { timeout: 120_000 });
+console.log(result.exitCode, result.stdout);
+```
+
+### `sandbox.destroy()`
+
+Destroys the sandbox and releases all associated resources.
+
+```typescript
+await sandbox.destroy();
+```
+
+## Properties
+
+| Property                | Type     | Description                                  |
+|-------------------------|----------|----------------------------------------------|
+| `sandbox.name`          | `string` | Sandbox identifier                           |
+| `sandbox.workspaceRoot` | `string` | Absolute workspace root path in the sandbox  |
+
+## License
+
+MIT

package/dist/cjs/index.d.ts

@@ -0,0 +1,3 @@
+export { SapiomSandbox } from "./sandbox.js";
+export type { SandboxCreateOptions, SandboxCreateResponse, SandboxTier, PortSpec, ExecOptions, ExecStreamOptions, ExecResult, StreamingExecResult, OutputLine, ProcessCreateResponse, ProcessStatusResponse, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,UAAU,EACV,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SapiomSandbox = void 0;
+var sandbox_js_1 = require("./sandbox.js");
+Object.defineProperty(exports, "SapiomSandbox", { enumerable: true, get: function () { return sandbox_js_1.SapiomSandbox; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,2CAA6C;AAApC,2GAAA,aAAa,OAAA"}

package/dist/cjs/sandbox.d.ts

@@ -0,0 +1,80 @@
+import type { SandboxCreateOptions, ExecOptions, ExecResult, ExecStreamOptions, StreamingExecResult, ProcessStatusResponse } from "./types.js";
+export declare class SapiomSandbox {
+    /** Name / identifier of the sandbox. */
+    readonly name: string;
+    /** Absolute workspace root path inside the sandbox. */
+    readonly workspaceRoot: string;
+    private readonly _fetch;
+    private readonly _baseUrl;
+    private constructor();
+    /**
+     * Create a new sandbox and return a handle for interacting with it.
+     */
+    static create(opts: SandboxCreateOptions): Promise<SapiomSandbox>;
+    /**
+     * Write a file inside the sandbox.
+     *
+     * @param path - File path relative to workspaceRoot.
+     * @param content - File content as a string.
+     */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Read a file from the sandbox.
+     *
+     * @param path - File path relative to workspaceRoot.
+     * @returns The file content as a string.
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Execute a command in the sandbox.
+     *
+     * By default waits for the process to finish (polls process status).
+     * Set `opts.waitForCompletion = false` for fire-and-forget execution.
+     * Use {@link execStream} for real-time streaming output.
+     *
+     * @param command - The shell command to run.
+     * @param opts - Execution options.
+     */
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Execute a command and stream its output in real time.
+     *
+     * Returns a {@link StreamingExecResult} whose `output` property is an
+     * async iterable of {@link OutputLine} objects. `exitCode` is populated
+     * after the iterable is fully consumed.
+     *
+     * @param command - The shell command to run.
+     * @param opts - Stream execution options.
+     */
+    execStream(command: string, opts?: ExecStreamOptions): Promise<StreamingExecResult>;
+    /**
+     * Get the current status of a process by PID.
+     *
+     * Useful for checking on processes started with
+     * `exec(cmd, { waitForCompletion: false })`.
+     *
+     * @param pid - The process ID returned from exec.
+     */
+    getProcess(pid: string): Promise<ProcessStatusResponse>;
+    /**
+     * Wait for a process to complete by polling its status.
+     *
+     * Useful for processes started with
+     * `exec(cmd, { waitForCompletion: false })`.
+     *
+     * @param pid - The process ID returned from exec.
+     * @param opts - Polling options.
+     */
+    waitForProcess(pid: string, opts?: {
+        pollInterval?: number;
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<ExecResult>;
+    /**
+     * Destroy the sandbox and release all resources.
+     */
+    destroy(): Promise<void>;
+    private _createProcess;
+    private _pollProcess;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/cjs/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EAEpB,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EAGnB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA0DpB,qBAAa,aAAa;IACxB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,uDAAuD;IACvD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,OAAO;IAYP;;OAEG;WACU,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IAiCvE;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB7D;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiB7C;;;;;;;;;OASG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IA0BpE;;;;;;;;;OASG;IACG,UAAU,CACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,iBAAiB,GACvB,OAAO,CAAC,mBAAmB,CAAC;IA4H/B;;;;;;;OAOG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAe7D;;;;;;;;OAQG;IACG,cAAc,CAClB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACvE,OAAO,CAAC,UAAU,CAAC;IAItB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAkBhB,cAAc;YA8Bd,YAAY;CAqC3B"}

package/dist/cjs/sandbox.js

@@ -0,0 +1,345 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SapiomSandbox = void 0;
+const fetch_1 = require("@sapiom/fetch");
+const DEFAULT_BASE_URL = "https://blaxel.services.sapiom.ai";
+const DEFAULT_POLL_INTERVAL = 1000;
+const DEFAULT_EXEC_TIMEOUT = 60000;
+function assertRelativePath(path) {
+    const segments = path.split("/");
+    for (const seg of segments) {
+        if (seg === "..") {
+            throw new Error(`Path must not contain '..' segments: ${path}`);
+        }
+    }
+}
+function resolvePath(workspaceRoot, relativePath) {
+    assertRelativePath(relativePath);
+    const base = workspaceRoot.endsWith("/")
+        ? workspaceRoot.slice(0, -1)
+        : workspaceRoot;
+    const rel = relativePath.startsWith("/")
+        ? relativePath.slice(1)
+        : relativePath;
+    return `${base}/${rel}`;
+}
+function encodePathSegments(path) {
+    return path
+        .split("/")
+        .map((seg) => encodeURIComponent(seg))
+        .join("/");
+}
+function fileUrl(baseUrl, sandboxName, absolutePath) {
+    // Strip leading slash so the URL path is well-formed, then encode each segment
+    const cleanPath = absolutePath.startsWith("/")
+        ? absolutePath.slice(1)
+        : absolutePath;
+    return `${baseUrl}/v1/sandboxes/${encodeURIComponent(sandboxName)}/filesystem/${encodePathSegments(cleanPath)}`;
+}
+function parseOutputLine(line) {
+    if (line.startsWith("stdout:")) {
+        return { stream: "stdout", data: line.slice(7) };
+    }
+    if (line.startsWith("stderr:")) {
+        return { stream: "stderr", data: line.slice(7) };
+    }
+    // Unrecognized framing — treat as stdout rather than dropping
+    return { stream: "stdout", data: line };
+}
+class SapiomSandbox {
+    constructor(name, workspaceRoot, fetchFn, baseUrl) {
+        this.name = name;
+        this.workspaceRoot = workspaceRoot;
+        this._fetch = fetchFn;
+        this._baseUrl = baseUrl;
+    }
+    /**
+     * Create a new sandbox and return a handle for interacting with it.
+     */
+    static async create(opts) {
+        const baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+        const fetchFn = opts.fetch ?? (0, fetch_1.createFetch)({ apiKey: opts.apiKey });
+        if (opts.port !== undefined && opts.ports !== undefined) {
+            throw new Error("Cannot specify both 'port' and 'ports'");
+        }
+        const body = { name: opts.name };
+        if (opts.tier !== undefined)
+            body.tier = opts.tier;
+        if (opts.ttl !== undefined)
+            body.ttl = opts.ttl;
+        if (opts.envs !== undefined)
+            body.envs = opts.envs;
+        if (opts.port !== undefined)
+            body.port = opts.port;
+        if (opts.ports !== undefined)
+            body.ports = opts.ports;
+        if (opts.image !== undefined)
+            body.image = opts.image;
+        const response = await fetchFn(`${baseUrl}/v1/sandboxes`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Failed to create sandbox: ${response.status} ${text}`);
+        }
+        const data = (await response.json());
+        return new SapiomSandbox(data.name, data.workspaceRoot, fetchFn, baseUrl);
+    }
+    /**
+     * Write a file inside the sandbox.
+     *
+     * @param path - File path relative to workspaceRoot.
+     * @param content - File content as a string.
+     */
+    async writeFile(path, content) {
+        assertRelativePath(path);
+        const url = fileUrl(this._baseUrl, this.name, path);
+        const response = await this._fetch(url, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ content }),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Failed to write file '${path}': ${response.status} ${text}`);
+        }
+    }
+    /**
+     * Read a file from the sandbox.
+     *
+     * @param path - File path relative to workspaceRoot.
+     * @returns The file content as a string.
+     */
+    async readFile(path) {
+        assertRelativePath(path);
+        const url = fileUrl(this._baseUrl, this.name, path);
+        const response = await this._fetch(url);
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Failed to read file '${path}': ${response.status} ${text}`);
+        }
+        const data = (await response.json());
+        return data.content;
+    }
+    /**
+     * Execute a command in the sandbox.
+     *
+     * By default waits for the process to finish (polls process status).
+     * Set `opts.waitForCompletion = false` for fire-and-forget execution.
+     * Use {@link execStream} for real-time streaming output.
+     *
+     * @param command - The shell command to run.
+     * @param opts - Execution options.
+     */
+    async exec(command, opts) {
+        const proc = await this._createProcess(command, opts);
+        // If the process already completed synchronously, return immediately
+        if (proc.status === "completed") {
+            return {
+                pid: proc.pid,
+                exitCode: proc.exitCode ?? 0,
+                stdout: proc.stdout ?? "",
+                stderr: proc.stderr ?? "",
+            };
+        }
+        const waitForCompletion = opts?.waitForCompletion ?? true;
+        if (!waitForCompletion) {
+            return {
+                pid: proc.pid,
+                exitCode: -1,
+                stdout: proc.stdout ?? "",
+                stderr: proc.stderr ?? "",
+            };
+        }
+        return this._pollProcess(proc.pid, opts);
+    }
+    /**
+     * Execute a command and stream its output in real time.
+     *
+     * Returns a {@link StreamingExecResult} whose `output` property is an
+     * async iterable of {@link OutputLine} objects. `exitCode` is populated
+     * after the iterable is fully consumed.
+     *
+     * @param command - The shell command to run.
+     * @param opts - Stream execution options.
+     */
+    async execStream(command, opts) {
+        const proc = await this._createProcess(command, opts);
+        // If the process already completed synchronously, return without
+        // opening the log stream — yield the stdout/stderr from the create
+        // response directly.
+        if (proc.status === "completed") {
+            const code = proc.exitCode ?? 0;
+            const stdout = proc.stdout ?? "";
+            const stderr = proc.stderr ?? "";
+            const output = (async function* () {
+                if (stdout)
+                    yield { stream: "stdout", data: stdout };
+                if (stderr)
+                    yield { stream: "stderr", data: stderr };
+            })();
+            return {
+                pid: proc.pid,
+                get exitCode() {
+                    return code;
+                },
+                output,
+            };
+        }
+        let finalExitCode = -1;
+        // Capture references for the generator closure
+        const fetchFn = this._fetch;
+        const baseUrl = this._baseUrl;
+        const sandboxName = this.name;
+        const signal = opts?.signal;
+        async function* streamOutput() {
+            const response = await fetchFn(`${baseUrl}/v1/sandboxes/${encodeURIComponent(sandboxName)}/process/${proc.pid}/logs/stream`, { signal });
+            if (!response.ok) {
+                const text = await response.text();
+                throw new Error(`Failed to stream process ${proc.pid}: ${response.status} ${text}`);
+            }
+            if (!response.body) {
+                throw new Error(`No response body for process ${proc.pid} log stream`);
+            }
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split("\n");
+                    buffer = lines.pop();
+                    for (const line of lines) {
+                        if (!line)
+                            continue;
+                        yield parseOutputLine(line);
+                    }
+                }
+                // Flush remaining multibyte bytes from the decoder
+                buffer += decoder.decode();
+                if (buffer) {
+                    yield parseOutputLine(buffer);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            // Fetch final process status for the exit code
+            const statusResponse = await fetchFn(`${baseUrl}/v1/sandboxes/${encodeURIComponent(sandboxName)}/process/${proc.pid}`, { signal });
+            if (!statusResponse.ok) {
+                const text = await statusResponse.text();
+                throw new Error(`Failed to get final status for process ${proc.pid}: ${statusResponse.status} ${text}`);
+            }
+            let status = (await statusResponse.json());
+            // If the process hasn't completed yet (e.g. stream disconnected
+            // before the process finished), poll until it does.
+            while (status.status !== "completed") {
+                await new Promise((resolve) => setTimeout(resolve, 1000));
+                const retry = await fetchFn(`${baseUrl}/v1/sandboxes/${encodeURIComponent(sandboxName)}/process/${proc.pid}`, { signal });
+                if (!retry.ok) {
+                    const text = await retry.text();
+                    throw new Error(`Failed to get final status for process ${proc.pid}: ${retry.status} ${text}`);
+                }
+                status = (await retry.json());
+            }
+            finalExitCode = status.exitCode ?? 0;
+        }
+        return {
+            pid: proc.pid,
+            get exitCode() {
+                return finalExitCode;
+            },
+            output: streamOutput(),
+        };
+    }
+    /**
+     * Get the current status of a process by PID.
+     *
+     * Useful for checking on processes started with
+     * `exec(cmd, { waitForCompletion: false })`.
+     *
+     * @param pid - The process ID returned from exec.
+     */
+    async getProcess(pid) {
+        const response = await this._fetch(`${this._baseUrl}/v1/sandboxes/${encodeURIComponent(this.name)}/process/${pid}`);
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Failed to get process ${pid}: ${response.status} ${text}`);
+        }
+        return (await response.json());
+    }
+    /**
+     * Wait for a process to complete by polling its status.
+     *
+     * Useful for processes started with
+     * `exec(cmd, { waitForCompletion: false })`.
+     *
+     * @param pid - The process ID returned from exec.
+     * @param opts - Polling options.
+     */
+    async waitForProcess(pid, opts) {
+        return this._pollProcess(pid, opts);
+    }
+    /**
+     * Destroy the sandbox and release all resources.
+     */
+    async destroy() {
+        const response = await this._fetch(`${this._baseUrl}/v1/sandboxes/${encodeURIComponent(this.name)}`, { method: "DELETE" });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Failed to destroy sandbox: ${response.status} ${text}`);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    async _createProcess(command, opts) {
+        const body = { command };
+        if (opts?.cwd !== undefined) {
+            body.cwd = resolvePath(this.workspaceRoot, opts.cwd);
+        }
+        if (opts?.env !== undefined)
+            body.env = opts.env;
+        const response = await this._fetch(`${this._baseUrl}/v1/sandboxes/${encodeURIComponent(this.name)}/process`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: opts?.signal,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Failed to execute command: ${response.status} ${text}`);
+        }
+        return (await response.json());
+    }
+    async _pollProcess(pid, opts) {
+        const pollInterval = opts?.pollInterval ?? DEFAULT_POLL_INTERVAL;
+        const timeout = opts?.timeout ?? DEFAULT_EXEC_TIMEOUT;
+        const deadline = Date.now() + timeout;
+        while (Date.now() < deadline) {
+            const response = await this._fetch(`${this._baseUrl}/v1/sandboxes/${encodeURIComponent(this.name)}/process/${pid}`, { signal: opts?.signal });
+            if (!response.ok) {
+                const text = await response.text();
+                throw new Error(`Failed to poll process ${pid}: ${response.status} ${text}`);
+            }
+            const status = (await response.json());
+            if (status.status === "completed") {
+                return {
+                    pid,
+                    exitCode: status.exitCode ?? 0,
+                    stdout: status.stdout ?? "",
+                    stderr: status.stderr ?? "",
+                };
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        }
+        throw new Error(`Process ${pid} timed out after ${timeout}ms`);
+    }
+}
+exports.SapiomSandbox = SapiomSandbox;
+//# sourceMappingURL=sandbox.js.map