@ggui-ai/sandbox 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Loqu, Inc. (Guuey)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,99 @@
+# @ggui-ai/sandbox
+
+Bounded process-isolation runner for untrusted Node subprocesses.
+
+## Usage
+
+```ts
+import { runSandboxed } from "@ggui-ai/sandbox";
+
+const result = await runSandboxed({
+  command: process.execPath, // node
+  args: ["./build-probe.js"],
+  timeoutMs: 15_000,
+  env: { NODE_ENV: "production" }, // parent process.env NEVER merged
+  maxStdoutBytes: 4 * 1024 * 1024, // 4 MiB cap
+  nodeHeapMb: 256,
+});
+
+if (result.outcome === "exit" && result.exitCode === 0) {
+  // result.stdout + result.stderr captured, child gone, tmpdir cleaned.
+}
+```
+
+## What it actually enforces (MVP)
+
+One subprocess, one bounded run, one pinned outcome. Portably, from pure Node user-space:
+
+- **Process boundary.** `spawn` with `shell: false`, `detached: false`, `windowsHide: true`, `stdio: ['pipe','pipe','pipe']`. Child cannot attach to the parent's controlling terminal, cannot fork into a new process group, cannot inherit open fds.
+- **Working-directory isolation.** Caller supplies an absolute `cwd`, or the sandbox mints an owned `mkdtempSync` dir and removes it at the end of the run. Relative `cwd` values are rejected at validation — no silent resolve against the parent's CWD.
+- **Environment allowlist.** The parent's `process.env` is **never** merged in. Only the caller's `env` keys plus a minimal bootstrap (`PATH`, `HOME`, `TMPDIR` when present on the parent) reach the child. Callers that want to forward extra vars copy them in explicitly.
+- **Wall-clock timeout.** `timeoutMs` is required. On overrun the sandbox sends `SIGTERM`, waits `gracePeriodMs`, then escalates to `SIGKILL`. Outcome is `'timeout'`.
+- **Output byte caps.** `stdout` and `stderr` are captured up to `maxStdoutBytes` / `maxStderrBytes` (defaults: 8 MiB / 1 MiB). Exceeding the cap terminates the child with outcome `'overflow-stdout'` / `'overflow-stderr'` and the captured output is truncated to exactly the cap.
+- **No stdin leakage.** Absent `stdin` → closed immediately. Present → written then closed. Parent stdin is never forwarded.
+- **V8 heap cap (Node children only).** When `nodeHeapMb` is set AND the command basename is `node` / equals `process.execPath`, the sandbox prepends `--max-old-space-size=<mb>` to `NODE_OPTIONS`. Caps V8's old-generation heap only.
+
+Every decision path funnels through a single `finish()` closure — no fd, timer, or tmpdir leaks regardless of which termination path fires first.
+
+## What it does NOT enforce
+
+All of the following need OS-level primitives (network namespaces, seccomp, cgroups, chroot/Landlock) that aren't portable from Node user-space. Consumers who need these run the sandbox under a stronger layer (Docker `network:none`, gVisor, firecracker, systemd with the right ambient config):
+
+- **Network egress blocking.** Not enforced. The child has the same network access as the parent.
+- **Filesystem read boundaries.** Not enforced. The child runs as the parent's UID/GID and can read anything the parent can. Relative paths resolve under `cwd`; absolute paths and `..` traversal remain reachable.
+- **CPU share / scheduling cap.** Not enforced. Node has no portable rlimit surface for CPU time. Total RSS is not capped either — only V8's old-gen heap (and only when the child is Node).
+- **Syscall filtering.** Not enforced. No seccomp, no LSM hooks. The child can make any syscall the parent could.
+- **Fork-bomb / grandchild containment.** Not enforced. The sandbox kills only its direct child; descendants that reparent (the classic daemon / double-fork trick) survive.
+
+If the threat model requires any of these guarantees, **do not rely on this package alone**. The sandbox is the portable MVP; stacking it under Docker / gVisor / firecracker is the production posture, not a "later" improvement.
+
+## API
+
+```ts
+runSandboxed(opts: SandboxOptions): Promise<SandboxResult>
+```
+
+### `SandboxOptions`
+
+| Field            | Required | Default      | Notes                                                     |
+| ---------------- | -------- | ------------ | --------------------------------------------------------- |
+| `command`        | ✅       | —            | Absolute path to the executable. No shell interpretation. |
+| `args`           | ✅       | —            | Forwarded verbatim. Pass `[]` for no args.                |
+| `cwd`            | ❌       | owned tmpdir | Must be absolute when supplied.                           |
+| `env`            | ❌       | `{}`         | Allowlist. Parent's `process.env` is NEVER merged.        |
+| `timeoutMs`      | ✅       | —            | Positive finite integer. No "infinity".                   |
+| `shutdownSignal` | ❌       | `'SIGTERM'`  | Soft-kill signal; SIGKILL escalation is unconditional.    |
+| `gracePeriodMs`  | ❌       | `2000`       | Must be `< timeoutMs`.                                    |
+| `stdin`          | ❌       | closed       | `string \| Uint8Array`. Absent = immediate EOF.           |
+| `maxStdoutBytes` | ❌       | 8 MiB        | Positive integer. Overflow → `'overflow-stdout'`.         |
+| `maxStderrBytes` | ❌       | 1 MiB        | Positive integer. Overflow → `'overflow-stderr'`.         |
+| `nodeHeapMb`     | ❌       | —            | Node children only. Sets `--max-old-space-size`.          |
+| `signal`         | ❌       | —            | External `AbortSignal` → outcome `'canceled'`.            |
+| `spawner`        | ❌       | real `spawn` | Test seam; production leaves unset.                       |
+
+### `SandboxResult`
+
+```ts
+interface SandboxResult {
+  outcome: "exit" | "timeout" | "canceled" | "overflow-stdout" | "overflow-stderr" | "spawn-error";
+  exitCode: number | null; // present only on 'exit'
+  signal: NodeJS.Signals | null; // present only on 'exit'
+  stdout: string; // UTF-8, truncated to maxStdoutBytes
+  stderr: string; // UTF-8, truncated to maxStderrBytes
+  durationMs: number;
+  stdoutTruncated: boolean;
+  stderrTruncated: boolean;
+  cwd: string; // absolute
+  cwdOwnedBySandbox: boolean; // true → already cleaned up
+  nodeHeapMbApplied: boolean;
+  errorMessage: string; // non-empty only on 'spawn-error'
+}
+```
+
+## Typical use
+
+The UI-gen render-probe path uses this package so LLM-generated TSX never executes in the parent Node process — each render spawns a subprocess through `runSandboxed` with a short timeout, a bounded stdout cap, a V8 heap cap, a sandbox-owned tmpdir cwd, and an env allowlist forwarding only `NODE_ENV`.
+
+## License
+
+Apache 2.0

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@ggui-ai/sandbox` — bounded process-isolation runner for
+ * OSS UI-gen workloads.
+ *
+ * Public surface:
+ *
+ *   - {@link runSandboxed} — one-shot runner. Spawns a subprocess,
+ *     enforces timeout + output caps + env allowlist + cwd
+ *     isolation, returns a {@link SandboxResult} with captured
+ *     output + terminal outcome.
+ *
+ *   - {@link SandboxOptions} / {@link SandboxResult} /
+ *     {@link SandboxOutcome} — pinned types.
+ *
+ * For the honest security boundary + what this MVP does NOT enforce,
+ * see the JSDoc header on `./types.ts` and the package README.
+ */
+export { runSandboxed } from './run.js';
+export type { SandboxOptions, SandboxOutcome, SandboxResult, } from './types.js';
+export type { Spawner, SpawnerOptions } from './spawner.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EACV,cAAc,EACd,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@ggui-ai/sandbox` — bounded process-isolation runner for
+ * OSS UI-gen workloads.
+ *
+ * Public surface:
+ *
+ *   - {@link runSandboxed} — one-shot runner. Spawns a subprocess,
+ *     enforces timeout + output caps + env allowlist + cwd
+ *     isolation, returns a {@link SandboxResult} with captured
+ *     output + terminal outcome.
+ *
+ *   - {@link SandboxOptions} / {@link SandboxResult} /
+ *     {@link SandboxOutcome} — pinned types.
+ *
+ * For the honest security boundary + what this MVP does NOT enforce,
+ * see the JSDoc header on `./types.ts` and the package README.
+ */
+export { runSandboxed } from './run.js';

package/dist/run.d.ts

@@ -0,0 +1,8 @@
+import type { SandboxOptions, SandboxResult } from './types.js';
+/**
+ * Run a command in a bounded subprocess. See {@link SandboxOptions}
+ * and the `./types.ts` header for the full semantics + honest-boundary
+ * lock.
+ */
+export declare function runSandboxed(opts: SandboxOptions): Promise<SandboxResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EACV,cAAc,EAEd,aAAa,EACd,MAAM,YAAY,CAAC;AAepB;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,aAAa,CAAC,CA2PxB"}

package/dist/run.js

@@ -0,0 +1,428 @@
+/**
+ * `runSandboxed` — bounded subprocess runner.
+ *
+ * Single code path per outcome. The state machine is intentionally
+ * small:
+ *
+ *   starting  →  (spawn error)      →  'spawn-error'
+ *             →  (child exits)      →  'exit'
+ *             →  (timeout fires)    →  kill → 'timeout'
+ *             →  (signal aborts)    →  kill → 'canceled'
+ *             →  (stdout overflow)  →  kill → 'overflow-stdout'
+ *             →  (stderr overflow)  →  kill → 'overflow-stderr'
+ *
+ * Once an outcome is decided, the runner:
+ *
+ *   1. stops accepting further outcome transitions (`outcomeDecided`),
+ *   2. if the child is still alive, sends `shutdownSignal`,
+ *   3. after `gracePeriodMs` escalates to `SIGKILL`,
+ *   4. waits for the 'exit' event to flush remaining stdio,
+ *   5. decodes captured buffers as UTF-8, truncated to their caps,
+ *   6. cleans up the owned tmpdir if one was created,
+ *   7. resolves the promise with a full `SandboxResult`.
+ *
+ * The runner resolves exactly once. All cleanup paths funnel through
+ * a single `finish()` closure so we can't leak a file descriptor,
+ * timer, or tmpdir no matter which path fired first.
+ */
+import { spawn } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, isAbsolute, join } from 'node:path';
+/**
+ * Default wall-clock grace between `shutdownSignal` and `SIGKILL`.
+ * 2 seconds covers typical Node child shutdown; a hostile / stuck
+ * child hits the SIGKILL escalation deterministically.
+ */
+const DEFAULT_GRACE_PERIOD_MS = 2_000;
+/** Default stdout budget — 8 MiB. */
+const DEFAULT_MAX_STDOUT_BYTES = 8 * 1024 * 1024;
+/** Default stderr budget — 1 MiB. */
+const DEFAULT_MAX_STDERR_BYTES = 1 * 1024 * 1024;
+/**
+ * Run a command in a bounded subprocess. See {@link SandboxOptions}
+ * and the `./types.ts` header for the full semantics + honest-boundary
+ * lock.
+ */
+export async function runSandboxed(opts) {
+    // ── 1. Validate inputs ───────────────────────────────────────────
+    validateOptions(opts);
+    const gracePeriodMs = opts.gracePeriodMs ?? DEFAULT_GRACE_PERIOD_MS;
+    const maxStdoutBytes = opts.maxStdoutBytes ?? DEFAULT_MAX_STDOUT_BYTES;
+    const maxStderrBytes = opts.maxStderrBytes ?? DEFAULT_MAX_STDERR_BYTES;
+    const shutdownSignal = opts.shutdownSignal ?? 'SIGTERM';
+    if (gracePeriodMs >= opts.timeoutMs) {
+        throw new RangeError(`runSandboxed: gracePeriodMs (${gracePeriodMs}) must be < timeoutMs (${opts.timeoutMs}) so SIGTERM has time to take effect before the sandbox considers the child stuck.`);
+    }
+    const start = Date.now();
+    // ── 2. Resolve cwd (owned tmpdir or caller-supplied absolute) ────
+    let cwd;
+    let cwdOwnedBySandbox = false;
+    if (opts.cwd !== undefined) {
+        cwd = opts.cwd;
+    }
+    else {
+        cwd = mkdtempSync(join(tmpdir(), 'ggui-sandbox-'));
+        cwdOwnedBySandbox = true;
+    }
+    // ── 3. Resolve env + detect Node child for heap cap ──────────────
+    const { env, nodeHeapMbApplied } = resolveEnv(opts);
+    // ── 4. Pre-spawn guard: caller already aborted ───────────────────
+    if (opts.signal?.aborted) {
+        cleanupCwd(cwd, cwdOwnedBySandbox);
+        return {
+            outcome: 'canceled',
+            exitCode: null,
+            signal: null,
+            stdout: '',
+            stderr: '',
+            durationMs: 0,
+            stdoutTruncated: false,
+            stderrTruncated: false,
+            cwd,
+            cwdOwnedBySandbox,
+            nodeHeapMbApplied,
+            errorMessage: '',
+        };
+    }
+    // ── 5. Spawn the child ──────────────────────────────────────────
+    const spawner = opts.spawner ??
+        ((cmd, args, spawnOpts) => spawn(cmd, args, {
+            cwd: spawnOpts.cwd,
+            env: spawnOpts.env,
+            stdio: spawnOpts.stdio,
+            shell: spawnOpts.shell,
+            detached: spawnOpts.detached,
+            windowsHide: spawnOpts.windowsHide,
+        }));
+    let child;
+    try {
+        child = spawner(opts.command, opts.args, {
+            cwd,
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            shell: false,
+            detached: false,
+            windowsHide: true,
+        });
+    }
+    catch (err) {
+        cleanupCwd(cwd, cwdOwnedBySandbox);
+        return {
+            outcome: 'spawn-error',
+            exitCode: null,
+            signal: null,
+            stdout: '',
+            stderr: '',
+            durationMs: Date.now() - start,
+            stdoutTruncated: false,
+            stderrTruncated: false,
+            cwd,
+            cwdOwnedBySandbox,
+            nodeHeapMbApplied,
+            errorMessage: err instanceof Error ? err.message : String(err),
+        };
+    }
+    // ── 6. Supervise the child ──────────────────────────────────────
+    return new Promise((resolve) => {
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        let outcome = 'exit'; // Overwritten on every
+        let outcomeDecided = false; //                   decision path
+        let errorMessage = '';
+        let killTimer = null;
+        let onAbort = null;
+        // Wall-clock timer — runs from spawn. Firing decides 'timeout'.
+        const timeoutTimer = setTimeout(() => decide('timeout', ''), opts.timeoutMs);
+        timeoutTimer.unref?.();
+        // External abort signal — fires 'canceled' when parent wants to
+        // cancel mid-run.
+        if (opts.signal) {
+            onAbort = () => decide('canceled', '');
+            opts.signal.addEventListener('abort', onAbort, { once: true });
+        }
+        // stdin — close immediately when absent, else write-then-close.
+        // Errors here are non-fatal — the child may close its stdin
+        // before we finish writing, which is fine.
+        if (opts.stdin !== undefined && child.stdin) {
+            try {
+                child.stdin.end(opts.stdin);
+            }
+            catch {
+                /* child stdin already closed — not our problem */
+            }
+        }
+        else {
+            child.stdin?.end();
+        }
+        const onStdout = (chunk) => {
+            if (outcomeDecided)
+                return;
+            const remaining = maxStdoutBytes - stdoutBytes;
+            if (chunk.length <= remaining) {
+                stdoutChunks.push(chunk);
+                stdoutBytes += chunk.length;
+                return;
+            }
+            // Overflow — accept only the remaining bytes, then decide.
+            if (remaining > 0) {
+                stdoutChunks.push(chunk.subarray(0, remaining));
+                stdoutBytes += remaining;
+            }
+            stdoutTruncated = true;
+            decide('overflow-stdout', '');
+        };
+        const onStderr = (chunk) => {
+            if (outcomeDecided)
+                return;
+            const remaining = maxStderrBytes - stderrBytes;
+            if (chunk.length <= remaining) {
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+                return;
+            }
+            if (remaining > 0) {
+                stderrChunks.push(chunk.subarray(0, remaining));
+                stderrBytes += remaining;
+            }
+            stderrTruncated = true;
+            decide('overflow-stderr', '');
+        };
+        child.stdout?.on('data', onStdout);
+        child.stderr?.on('data', onStderr);
+        child.on('error', (err) => {
+            // Post-spawn error. When the child never gets a pid (ENOENT on
+            // Linux surfaces async via 'error' with no 'exit' follow-up),
+            // 'exit' will not fire — we must resolve from here. Per Node's
+            // docs, 'exit' MAY fire after 'error' but isn't guaranteed.
+            const message = err instanceof Error ? err.message : String(err);
+            if (child.pid === undefined && !outcomeDecided) {
+                outcomeDecided = true;
+                clearTimeout(timeoutTimer);
+                if (onAbort && opts.signal) {
+                    opts.signal.removeEventListener('abort', onAbort);
+                    onAbort = null;
+                }
+                cleanupCwd(cwd, cwdOwnedBySandbox);
+                resolve({
+                    outcome: 'spawn-error',
+                    exitCode: null,
+                    signal: null,
+                    stdout: decodeUpTo(stdoutChunks, maxStdoutBytes),
+                    stderr: decodeUpTo(stderrChunks, maxStderrBytes),
+                    durationMs: Date.now() - start,
+                    stdoutTruncated,
+                    stderrTruncated,
+                    cwd,
+                    cwdOwnedBySandbox,
+                    nodeHeapMbApplied,
+                    errorMessage: message,
+                });
+                return;
+            }
+            decide('spawn-error', message);
+        });
+        const decide = (next, message) => {
+            if (outcomeDecided)
+                return;
+            outcomeDecided = true;
+            outcome = next;
+            errorMessage = message;
+            // If the child is still alive, request graceful shutdown. The
+            // real terminal state ('stopped') is observed on the 'exit'
+            // event below.
+            killChild(child, shutdownSignal, gracePeriodMs, (timer) => {
+                killTimer = timer;
+            });
+        };
+        child.on('exit', (code, signal) => {
+            // Flush any buffered output (the 'data' listener handles it
+            // live, but the kernel can deliver final chunks after exit on
+            // some platforms). Node's ChildProcess already emits all
+            // 'data' before 'exit', so we just decode.
+            if (killTimer) {
+                clearTimeout(killTimer);
+                killTimer = null;
+            }
+            clearTimeout(timeoutTimer);
+            if (onAbort && opts.signal) {
+                opts.signal.removeEventListener('abort', onAbort);
+                onAbort = null;
+            }
+            // If no one has decided yet, the child exited on its own.
+            if (!outcomeDecided) {
+                outcomeDecided = true;
+                outcome = 'exit';
+            }
+            const stdout = decodeUpTo(stdoutChunks, maxStdoutBytes);
+            const stderr = decodeUpTo(stderrChunks, maxStderrBytes);
+            cleanupCwd(cwd, cwdOwnedBySandbox);
+            resolve({
+                outcome,
+                exitCode: outcome === 'exit' ? code : null,
+                signal: outcome === 'exit' ? signal : null,
+                stdout,
+                stderr,
+                durationMs: Date.now() - start,
+                stdoutTruncated,
+                stderrTruncated,
+                cwd,
+                cwdOwnedBySandbox,
+                nodeHeapMbApplied,
+                errorMessage,
+            });
+        });
+    });
+}
+/**
+ * Input validation — throws synchronously on invalid configuration
+ * so callers find bugs at the call site, not as a confusing 'exit'
+ * outcome with an empty stderr.
+ */
+function validateOptions(opts) {
+    if (!opts.command || typeof opts.command !== 'string') {
+        throw new TypeError('runSandboxed: `command` must be a non-empty string');
+    }
+    if (!Array.isArray(opts.args)) {
+        throw new TypeError('runSandboxed: `args` must be an array');
+    }
+    if (typeof opts.timeoutMs !== 'number' ||
+        !Number.isFinite(opts.timeoutMs) ||
+        opts.timeoutMs <= 0 ||
+        !Number.isInteger(opts.timeoutMs)) {
+        throw new RangeError('runSandboxed: `timeoutMs` must be a positive finite integer');
+    }
+    if (opts.cwd !== undefined && !isAbsolute(opts.cwd)) {
+        throw new TypeError(`runSandboxed: \`cwd\` must be an absolute path, got ${JSON.stringify(opts.cwd)}`);
+    }
+    if (opts.maxStdoutBytes !== undefined &&
+        (opts.maxStdoutBytes <= 0 || !Number.isInteger(opts.maxStdoutBytes))) {
+        throw new RangeError('runSandboxed: `maxStdoutBytes` must be a positive integer');
+    }
+    if (opts.maxStderrBytes !== undefined &&
+        (opts.maxStderrBytes <= 0 || !Number.isInteger(opts.maxStderrBytes))) {
+        throw new RangeError('runSandboxed: `maxStderrBytes` must be a positive integer');
+    }
+    if (opts.gracePeriodMs !== undefined && opts.gracePeriodMs < 0) {
+        throw new RangeError('runSandboxed: `gracePeriodMs` must be >= 0');
+    }
+    if (opts.nodeHeapMb !== undefined &&
+        (opts.nodeHeapMb <= 0 || !Number.isInteger(opts.nodeHeapMb))) {
+        throw new RangeError('runSandboxed: `nodeHeapMb` must be a positive integer');
+    }
+}
+/**
+ * Resolve the child's environment.
+ *
+ * The parent's `process.env` is NEVER merged in. Only three things
+ * reach the child:
+ *
+ *   1. A minimal bootstrap (`PATH`, `HOME`, and `TMPDIR` when
+ *      present on the parent). `PATH` is required or the kernel
+ *      cannot locate the command; `HOME` is required for most Node
+ *      shutdown paths (e.g. npm config); `TMPDIR` lets child code
+ *      that writes scratch files respect the parent's temp location.
+ *      Callers can override any of these by declaring the key
+ *      explicitly in `opts.env`.
+ *
+ *   2. Every key from `opts.env` (verbatim — parent values NEVER
+ *      leak).
+ *
+ *   3. `NODE_OPTIONS=--max-old-space-size=<nodeHeapMb>` when the
+ *      child is a Node process AND `opts.nodeHeapMb` is set.
+ *      Merges with any `NODE_OPTIONS` the caller supplied.
+ */
+function resolveEnv(opts) {
+    const env = {};
+    // Bootstrap — only the three keys that matter for the child to
+    // locate its binary, have a home dir, and know where to scratch.
+    const bootstrapKeys = ['PATH', 'HOME', 'TMPDIR'];
+    for (const key of bootstrapKeys) {
+        const parentValue = process.env[key];
+        if (parentValue !== undefined)
+            env[key] = parentValue;
+    }
+    // Explicit allowlist — callers OVERRIDE bootstrap values if they
+    // declare the key themselves. Shallow merge; no special handling.
+    if (opts.env) {
+        for (const [key, value] of Object.entries(opts.env)) {
+            env[key] = value;
+        }
+    }
+    // Node heap cap — only applied for Node children.
+    let nodeHeapMbApplied = false;
+    if (opts.nodeHeapMb !== undefined && isNodeCommand(opts.command)) {
+        const flag = `--max-old-space-size=${opts.nodeHeapMb}`;
+        const existing = env.NODE_OPTIONS;
+        env.NODE_OPTIONS = existing ? `${existing} ${flag}` : flag;
+        nodeHeapMbApplied = true;
+    }
+    return { env, nodeHeapMbApplied };
+}
+function isNodeCommand(command) {
+    if (command === process.execPath)
+        return true;
+    const base = basename(command);
+    return base === 'node' || base === 'node.exe';
+}
+/**
+ * Kill the child. Sends `shutdownSignal` first; after `gracePeriodMs`
+ * escalates to SIGKILL. Both calls tolerate "child already exited" —
+ * `kill()` returns false but doesn't throw on a reaped child.
+ *
+ * `onTimer` lets the caller hold a reference to the escalation timer
+ * so it can cancel on early exit without a second kill attempt.
+ */
+function killChild(child, signal, gracePeriodMs, onTimer) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // Already gone.
+        return;
+    }
+    const timer = setTimeout(() => {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    }, gracePeriodMs);
+    timer.unref?.();
+    onTimer(timer);
+}
+/**
+ * Concatenate captured buffer chunks and decode as UTF-8, truncated
+ * to `max` bytes. UTF-8 decode tolerates a truncation mid-codepoint
+ * by replacing the partial bytes with the replacement character.
+ */
+function decodeUpTo(chunks, max) {
+    const joined = Buffer.concat(chunks);
+    const sliced = joined.length > max ? joined.subarray(0, max) : joined;
+    return sliced.toString('utf-8');
+}
+/**
+ * Remove the tmpdir the sandbox created. Best-effort — a stray lock
+ * file or open handle in the child should not propagate as a caller-
+ * visible error. Real failures surface via logs, not exceptions.
+ */
+function cleanupCwd(cwd, owned) {
+    if (!owned)
+        return;
+    try {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort. Tests that need a clean tmpdir use mkdtempSync
+        // under os.tmpdir() so the OS eventually reclaims it.
+    }
+}

package/dist/spawner.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Spawner seam. Broken out from the runner so tests can substitute
+ * a fake child process without touching the filesystem or launching
+ * a real OS process.
+ *
+ * Kept minimal — only the shape the sandbox actually uses. Real
+ * production wiring imports `spawn` from `node:child_process`.
+ */
+import type { ChildProcess } from 'node:child_process';
+export type Spawner = (command: string, args: readonly string[], options: SpawnerOptions) => ChildProcess;
+export interface SpawnerOptions {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly stdio: ['pipe', 'pipe', 'pipe'];
+    readonly shell: false;
+    readonly detached: false;
+    readonly windowsHide: true;
+}
+//# sourceMappingURL=spawner.d.ts.map

package/dist/spawner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawner.d.ts","sourceRoot":"","sources":["../src/spawner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,MAAM,OAAO,GAAG,CACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,cAAc,KACpB,YAAY,CAAC;AAElB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;CAC5B"}

package/dist/spawner.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * `@ggui-ai/sandbox` — public API types.
+ *
+ * One high-level entry point (`runSandboxed`) with a small, pinned
+ * surface. The discriminated `SandboxOutcome` lets callers branch on
+ * terminal state without re-deriving it from exit codes / signals.
+ *
+ * ## Honest security boundary (MVP)
+ *
+ * What this package DOES enforce, portably, from pure Node:
+ *
+ *   - **Process boundary.** Work runs in a fresh `child_process.spawn`
+ *     subprocess with `shell: false` + `detached: false` + `stdio:
+ *     ['pipe', 'pipe', 'pipe']`. The child cannot attach to the
+ *     parent's controlling terminal, cannot inherit open fds, and
+ *     cannot fork into a new process group. A crash in the child
+ *     cannot corrupt parent state.
+ *
+ *   - **Working-directory isolation.** Callers either bring their own
+ *     absolute `cwd` or let the sandbox mint an owned tmpdir that it
+ *     cleans up on finish. Relative paths inside the child resolve
+ *     against the declared `cwd` only. (Not an FS boundary — the
+ *     child still has the parent user's read permissions on absolute
+ *     paths; see "Does NOT enforce" below.)
+ *
+ *   - **Environment allowlist.** The child receives the `env` object
+ *     verbatim. The parent's `process.env` is NEVER merged.
+ *     Consumers that want to expose specific variables write them
+ *     explicitly. A minimal bootstrap (`PATH`, `HOME`, `TMPDIR` if
+ *     present on the parent) is injected only so the child can
+ *     resolve the command and write scratch data — and is documented
+ *     in {@link SandboxOptions.env}.
+ *
+ *   - **Wall-clock timeout.** `timeoutMs` is required — no
+ *     "infinity." On overrun the sandbox sends `SIGTERM`, waits
+ *     `gracePeriodMs`, then escalates to `SIGKILL`. Outcome is
+ *     `'timeout'`.
+ *
+ *   - **Output byte caps.** stdout + stderr are accumulated up to
+ *     `maxStdoutBytes` / `maxStderrBytes`. When either is exceeded
+ *     the sandbox terminates the child and returns outcome
+ *     `'overflow-stdout'` / `'overflow-stderr'`. Captured output is
+ *     truncated to exactly the cap.
+ *
+ *   - **V8 heap cap (Node children only).** When `nodeHeapMb` is
+ *     set AND the command is `process.execPath` (or has the basename
+ *     `node`), the sandbox prepends `--max-old-space-size=<mb>` to
+ *     `args` via the `NODE_OPTIONS` env var. This caps V8's old-
+ *     generation heap. It does NOT cap total RSS (native buffers,
+ *     ArrayBuffers, child-of-child memory).
+ *
+ *   - **No stdin leakage.** When `stdin` is absent the child's stdin
+ *     is closed immediately. When present, the sandbox writes exactly
+ *     the supplied bytes then closes. The parent never forwards its
+ *     own stdin.
+ *
+ * What this package does NOT enforce (portably from Node):
+ *
+ *   - **Network egress blocking.** Impossible portably from Node
+ *     user-space. Real enforcement needs OS primitives: Linux
+ *     network namespaces + iptables, macOS pf, Windows WFP, or a
+ *     sidecar (Docker network:none, gVisor, firecracker). Consumers
+ *     who need no-egress MUST layer those themselves; the sandbox
+ *     does not pretend.
+ *
+ *   - **Filesystem read boundaries.** The child shares the parent
+ *     process's UID/GID + filesystem visibility. Relative paths
+ *     resolve under `cwd`, but absolute paths and `..` traversals
+ *     remain reachable. A true FS sandbox needs chroot / pivot_root /
+ *     user namespaces / Landlock (Linux) / sandbox-exec (macOS).
+ *
+ *   - **CPU share / scheduling cap.** Node has no portable rlimit
+ *     surface for CPU time. Consumers who need CPU caps run the
+ *     sandbox under a cgroup / `ulimit` / container.
+ *
+ *   - **Syscall filtering.** No seccomp, no LSM hooks. The child can
+ *     make any syscall the parent could.
+ *
+ *   - **Fork-bomb containment.** No `RLIMIT_NPROC`. A malicious
+ *     child could spawn descendants that the sandbox does NOT track
+ *     or kill. (The sandbox kills only its direct child; grandchildren
+ *     survive if they reparent.)
+ *
+ * Every "does not" above is a deliberate omission to keep the MVP
+ * portable + honest. Consumers that require any of those guarantees
+ * run the sandbox under a stronger layer (Docker, gVisor, firecracker,
+ * etc.) — the sandbox does not lie about what it gives them.
+ */
+import type { Spawner } from './spawner.js';
+/**
+ * Options for a single {@link runSandboxed} invocation. Immutable —
+ * callers construct a fresh object per run.
+ */
+export interface SandboxOptions {
+    /**
+     * Absolute path to the executable. Required. No shell interpretation
+     * (`shell: false` is the only supported mode); to run a Node script
+     * pass `process.execPath` or a resolved `node` path and put the
+     * script path in `args`.
+     */
+    readonly command: string;
+    /**
+     * Args forwarded verbatim to the child. Pass `[]` for no args.
+     */
+    readonly args: readonly string[];
+    /**
+     * Working directory. Absolute paths only. Absent = sandbox creates
+     * an owned tmpdir under `os.tmpdir()` and removes it at the end
+     * of the run (result.cwdOwnedBySandbox === true). Relative paths
+     * are rejected — the sandbox does not silently resolve against the
+     * parent's CWD.
+     */
+    readonly cwd?: string;
+    /**
+     * Environment variables exposed to the child. **The parent's
+     * `process.env` is NEVER merged in.** Only the keys in this map
+     * plus a minimal bootstrap (`PATH`, `HOME`, and `TMPDIR` when
+     * present on the parent — required so the kernel + Node can find
+     * the command and write scratch data) reach the child. Callers
+     * that want to forward extra variables do so explicitly by reading
+     * `process.env` and copying the keys they want.
+     *
+     * Absent = empty allowlist (child gets only the bootstrap).
+     */
+    readonly env?: Readonly<Record<string, string>>;
+    /**
+     * Wall-clock timeout in milliseconds. Required — the sandbox does
+     * not support "run forever." Must be a positive finite integer.
+     *
+     * On overrun:
+     *   1. sandbox sends {@link shutdownSignal} to the child,
+     *   2. waits up to {@link gracePeriodMs},
+     *   3. escalates to `SIGKILL` if the child is still alive.
+     *
+     * Outcome is `'timeout'`.
+     */
+    readonly timeoutMs: number;
+    /**
+     * Signal to send when terminating. Defaults to `'SIGTERM'`.
+     * The escalation to `'SIGKILL'` after {@link gracePeriodMs} is
+     * unconditional and not configurable.
+     */
+    readonly shutdownSignal?: NodeJS.Signals;
+    /**
+     * Grace period in ms between the soft-kill signal and the hard
+     * `SIGKILL`. Defaults to `2000`. Must be >= 0 and < {@link
+     * timeoutMs} to leave headroom for a child that ignores SIGTERM.
+     */
+    readonly gracePeriodMs?: number;
+    /**
+     * Optional data written to the child's stdin. When omitted, stdin
+     * is closed immediately and the child reads EOF. Strings are
+     * encoded as UTF-8; `Uint8Array` is written verbatim.
+     */
+    readonly stdin?: string | Uint8Array;
+    /**
+     * Max bytes to capture from stdout before terminating the child.
+     * Defaults to `8 * 1024 * 1024` (8 MiB). Must be > 0.
+     * Exceeding the cap terminates the child with outcome
+     * `'overflow-stdout'`; captured stdout is truncated to the cap.
+     */
+    readonly maxStdoutBytes?: number;
+    /**
+     * Max bytes to capture from stderr before terminating the child.
+     * Defaults to `1 * 1024 * 1024` (1 MiB). Must be > 0.
+     * Exceeding the cap terminates the child with outcome
+     * `'overflow-stderr'`; captured stderr is truncated to the cap.
+     */
+    readonly maxStderrBytes?: number;
+    /**
+     * V8 old-generation heap cap in MiB. Applied only when the
+     * resolved `command` basename is `node` (or equals
+     * `process.execPath`). For non-Node children the field is ignored
+     * and {@link SandboxResult.nodeHeapMbApplied} is `false`.
+     *
+     * Applied via `NODE_OPTIONS=--max-old-space-size=<mb>`. Caps V8's
+     * old-gen only — not total RSS.
+     */
+    readonly nodeHeapMb?: number;
+    /**
+     * External cancellation. When the signal fires, the sandbox
+     * terminates the child (SIGTERM → grace → SIGKILL) and returns
+     * outcome `'canceled'`.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Test seam — substitute a spawner to exercise the runner without
+     * launching real processes. Production code leaves this unset.
+     */
+    readonly spawner?: Spawner;
+}
+/**
+ * Terminal state of a sandbox run. Exhaustive; every possible
+ * shutdown path maps to exactly one of these.
+ */
+export type SandboxOutcome = 
+/** Child exited on its own within the budget. `exitCode`/`signal`
+ * record why. */
+'exit'
+/** `timeoutMs` elapsed; sandbox killed the child. */
+ | 'timeout'
+/** External `signal` aborted the run; sandbox killed the child. */
+ | 'canceled'
+/** stdout exceeded `maxStdoutBytes`; sandbox killed the child. */
+ | 'overflow-stdout'
+/** stderr exceeded `maxStderrBytes`; sandbox killed the child. */
+ | 'overflow-stderr'
+/** Spawn failed or an internal error occurred before the child
+ * could be supervised. `errorMessage` carries detail. */
+ | 'spawn-error';
+/**
+ * Result of a {@link runSandboxed} invocation. All fields are
+ * non-optional — consumers get a consistent shape whatever the
+ * outcome. Fields that are only meaningful for some outcomes carry
+ * documented sentinels (e.g. `exitCode: null` for signal-induced
+ * termination).
+ */
+export interface SandboxResult {
+    /** Terminal state. */
+    readonly outcome: SandboxOutcome;
+    /** Exit code when the child exited on its own; `null` when the
+     * sandbox killed it or spawn failed. */
+    readonly exitCode: number | null;
+    /** Signal that terminated the child; `null` when the child exited
+     * with an explicit code or spawn failed. */
+    readonly signal: NodeJS.Signals | null;
+    /** Captured stdout, decoded as UTF-8. Truncated to
+     * `maxStdoutBytes`. */
+    readonly stdout: string;
+    /** Captured stderr, decoded as UTF-8. Truncated to
+     * `maxStderrBytes`. */
+    readonly stderr: string;
+    /** Wall-clock duration in milliseconds. */
+    readonly durationMs: number;
+    /** True iff stdout output was truncated (actual stream was larger
+     * than `maxStdoutBytes`). */
+    readonly stdoutTruncated: boolean;
+    /** True iff stderr output was truncated. */
+    readonly stderrTruncated: boolean;
+    /** Absolute `cwd` the child ran in. When the caller brought their
+     * own it is echoed back; when the sandbox minted one this points
+     * at the owned tmpdir (already removed by the time the result
+     * resolves, per `cwdOwnedBySandbox`). */
+    readonly cwd: string;
+    /** True iff the sandbox created (and cleaned up) `cwd`. */
+    readonly cwdOwnedBySandbox: boolean;
+    /** True iff the sandbox applied the V8 heap cap (Node child only). */
+    readonly nodeHeapMbApplied: boolean;
+    /** Human-readable reason when `outcome === 'spawn-error'`.
+     * Empty string for every other outcome. */
+    readonly errorMessage: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAEjC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEhD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;IAEzC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAErC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc;AACxB;iBACiB;AACf,MAAM;AACR,qDAAqD;GACnD,SAAS;AACX,mEAAmE;GACjE,UAAU;AACZ,kEAAkE;GAChE,iBAAiB;AACnB,kEAAkE;GAChE,iBAAiB;AACnB;yDACyD;GACvD,aAAa,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;4CACwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC;gDAC4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAEvC;2BACuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;2BACuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;iCAC6B;IAC7B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAElC,4CAA4C;IAC5C,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAElC;;;6CAGyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,2DAA2D;IAC3D,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IAEpC,sEAAsE;IACtE,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IAEpC;+CAC2C;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ggui-ai/sandbox",
+  "version": "0.1.0-rc.1",
+  "description": "Bounded process-isolation runner for untrusted Node subprocesses. Spawns a child with explicit cwd, env allowlist, wall-clock timeout, output caps, and (for Node children) a V8 heap cap. Honest scope — does NOT attempt network egress blocking, filesystem read boundaries, CPU limits, or syscall filtering (those need OS primitives: namespaces / seccomp / cgroups).",
+  "keywords": [
+    "ggui",
+    "sandbox",
+    "process-isolation",
+    "subprocess",
+    "spawn"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/ggui-ai/ggui/tree/main/packages/sandbox",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ggui-ai/ggui.git",
+    "directory": "packages/sandbox"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/ggui-ai/ggui/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "ggui contributors <hello@ggui.ai>",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}