sandboxedjs 0.1.73 → 0.1.74

package/README.md

@@ -165,6 +165,17 @@ await session.run("echo $TOKEN in $(pwd)"); // → abc in /app
 
 ### Long-running processes
 
+A job put in the background with `&` keeps running after the command that started it returns,
+even from a stateless `exec`, and stops with `kill %N` in a session or when the container is
+disposed:
+
+```ts
+await box.exec("node server.js > /tmp/server.log 2>&1 &", { cwd: "/app" });
+await box.waitForPort(3000);
+```
+
+To hold the process yourself, spawn it:
+
 ```ts
 const proc = box.spawn("node server.js", { cwd: "/app" });
 
@@ -545,7 +556,10 @@ The container has no access to your filesystem, environment, or network unless y
 - The filesystem is entirely in memory. Code inside cannot read or write a host path — there is
   no `/Users`, no `/home/you`, no way to reach one.
 - Outbound network access is **off by default**; `curl https://…` fails until you pass
-  `network: { allowOutbound: true }`, optionally narrowed with `allowedHosts`.
+  `network: { allowOutbound: true }`, optionally narrowed with `allowedHosts`. The same policy
+  binds a program's own `fetch`, `http`, `https` and `WebSocket`: a refused request fails with
+  `ENETUNREACH`. `localhost` and `127.0.0.1` always mean the container's own servers — never the
+  host's.
 - Host files enter only through `files`, `mount()` or `copyIn()`, and leave only through
   `copyOut()` or `fs.readFile()`.
 - `timeoutMs` bounds runaway commands, and `exec` settles even when a process ignores its kill
@@ -1000,7 +1014,16 @@ Honest list of what does not work:
   through is to answer **No** to a prompt like `npm create vite`'s "Install with npm and start
   now?" and run `npm install && npm run dev` from the shell instead.
 - **No `net`, `tls`, `worker_threads` or `vm`.** `http` and `https` are served by a virtual stack
-  that `request()` talks to directly, so servers work; raw sockets do not.
+  that `request()` talks to directly, so servers work; raw sockets do not. A program can reach
+  servers anywhere in the container over HTTP (`http.get`, `fetch`), but not open a `WebSocket` to
+  one.
+- **`node:test` covers what test files use** — `test`/`it`, `describe`, hooks, subtests, `skip`,
+  `todo`, `only`, `mock.fn` and `mock.method`, with `spec` and `tap` reports — and `node --test`
+  finds and runs test files as Node 22 does. `run()`, coverage and mock timers are not
+  implemented. A test file exits when its tests finish, as under `--test-force-exit`.
+- **On the in-realm runtime, programs share one global object.** A global one program sets is
+  visible to the next. The worker runtime (the default where shared memory is available) gives
+  each program its own.
 - **Python is source-built CPython/WASM.** Each program gets its own interpreter
   process worker. Pure-Python wheels install normally; native extensions must
   be linked or published for Emscripten. The bundled wheel index includes the

package/dist/agent.d.cts

@@ -1,5 +1,5 @@
-import { C as Container } from './container-BxEoVOmX.cjs';
-import './contracts-CVgctitO.cjs';
+import { C as Container } from './container-DAWPIkGG.cjs';
+import './contracts-C2_dTgk3.cjs';
 
 /**
  * Structural copies of the LangChain Deep Agents backend contract.

package/dist/agent.d.ts

@@ -1,5 +1,5 @@
-import { C as Container } from './container-B5X6stfx.js';
-import './contracts-CVgctitO.js';
+import { C as Container } from './container-CsLNpeyi.js';
+import './contracts-C2_dTgk3.js';
 
 /**
  * Structural copies of the LangChain Deep Agents backend contract.

package/dist/{container-B5X6stfx.d.ts → container-CsLNpeyi.d.ts}

@@ -1,4 +1,4 @@
-import { V as Vfs, C as Cred, f as RuntimePod, D as DirEntry, p as Stats } from './contracts-CVgctitO.js';
+import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-C2_dTgk3.js';
 
 /**
  * Byte streams for stdin/stdout/stderr, pipelines and redirections.
@@ -487,6 +487,8 @@ declare class NetworkStack {
         timeoutMs?: number;
         intervalMs?: number;
     }): Promise<boolean>;
+    /** The policy every way out of the container applies, not only the shell's. */
+    get policy(): OutboundPolicy;
     outboundAllowed(url: string): boolean;
     procNetDev(): string;
     procNetRoute(): string;
@@ -979,8 +981,13 @@ declare class Shell {
     captureSubshell(command: string): Promise<string>;
     /** `<(cmd)` — run the command now and hand back a path holding its output. */
     private makeProcessSubstitution;
-    /** A copy that shares nothing mutable with this shell. */
-    fork(): Shell;
+    /**
+     * A copy that shares nothing mutable with this shell.
+     *
+     * Subshells and pipeline stages run as part of this shell's process. A
+     * background job passes a process of its own, the way fork(2) gives one.
+     */
+    fork(proc?: Process): Shell;
     private currentIO;
     run(node: Node, io: ShellIO): Promise<number>;
     private runList;
@@ -1543,6 +1550,14 @@ declare class Container {
     }): Session;
     /** The container-wide session used by `shell()` shorthand helpers. */
     get shell(): Session;
+    /**
+     * The streams one call collects into.
+     *
+     * They are detachable because a background job started by the command keeps
+     * writing after the call has returned. Nothing reads the result any more by
+     * then, so without `detach` a chatty server would grow the buffer for as long
+     * as it ran; afterwards its output still reaches the container-wide taps.
+     */
     private makeStdio;
     /** Send an HTTP request to a server running inside the container. */
     request(port: number, init?: {

package/dist/{container-BxEoVOmX.d.cts → container-DAWPIkGG.d.cts}

@@ -1,4 +1,4 @@
-import { V as Vfs, C as Cred, f as RuntimePod, D as DirEntry, p as Stats } from './contracts-CVgctitO.cjs';
+import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-C2_dTgk3.cjs';
 
 /**
  * Byte streams for stdin/stdout/stderr, pipelines and redirections.
@@ -487,6 +487,8 @@ declare class NetworkStack {
         timeoutMs?: number;
         intervalMs?: number;
     }): Promise<boolean>;
+    /** The policy every way out of the container applies, not only the shell's. */
+    get policy(): OutboundPolicy;
     outboundAllowed(url: string): boolean;
     procNetDev(): string;
     procNetRoute(): string;
@@ -979,8 +981,13 @@ declare class Shell {
     captureSubshell(command: string): Promise<string>;
     /** `<(cmd)` — run the command now and hand back a path holding its output. */
     private makeProcessSubstitution;
-    /** A copy that shares nothing mutable with this shell. */
-    fork(): Shell;
+    /**
+     * A copy that shares nothing mutable with this shell.
+     *
+     * Subshells and pipeline stages run as part of this shell's process. A
+     * background job passes a process of its own, the way fork(2) gives one.
+     */
+    fork(proc?: Process): Shell;
     private currentIO;
     run(node: Node, io: ShellIO): Promise<number>;
     private runList;
@@ -1543,6 +1550,14 @@ declare class Container {
     }): Session;
     /** The container-wide session used by `shell()` shorthand helpers. */
     get shell(): Session;
+    /**
+     * The streams one call collects into.
+     *
+     * They are detachable because a background job started by the command keeps
+     * writing after the call has returned. Nothing reads the result any more by
+     * then, so without `detach` a chatty server would grow the buffer for as long
+     * as it ran; afterwards its output still reaches the container-wide taps.
+     */
     private makeStdio;
     /** Send an HTTP request to a server running inside the container. */
     request(port: number, init?: {

package/dist/{contracts-CVgctitO.d.cts → contracts-C2_dTgk3.d.cts}

@@ -347,6 +347,27 @@ declare class VirtualTcpNetwork {
     closeAll(): void;
 }
 
+/**
+ * The outbound network policy, as plain functions every client consults.
+ *
+ * The container has several ways out — `curl` and `wget` in the shell, `http`,
+ * `https`, `fetch` and `WebSocket` in a Node program, sockets in Python — and
+ * they used to decide separately. Only the shell asked: a Node program's
+ * `fetch("https://…")` reached the internet from a container booted with
+ * outbound access off. One policy, applied at each exit, is what makes
+ * `network: { allowOutbound: false }` mean what it says.
+ *
+ * Loopback is not "outbound" at all. `127.0.0.1` inside the container is the
+ * container, so those requests are routed to its own servers and never handed
+ * to the host's network stack, whatever the policy allows.
+ */
+interface OutboundPolicy {
+    /** Whether requests may leave the container at all. */
+    allowOutbound: boolean;
+    /** When outbound is on, the hosts it may reach (subdomains included). `null` means any. */
+    allowedHosts: string[] | null;
+}
+
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
  *
@@ -479,9 +500,17 @@ interface RuntimePod {
         headers: Record<string, string>;
         body: Uint8Array;
     }) => Promise<RuntimeHttpResponse>): () => void;
+    /**
+     * Apply the container's outbound policy to programs this pod runs.
+     *
+     * Optional so a pod written elsewhere still satisfies the contract, but a pod
+     * without it cannot keep a program's own `fetch` inside the policy — only
+     * the shell's `curl` would honour it.
+     */
+    setNetworkPolicy?(policy: OutboundPolicy): void;
     snapshot(options?: Record<string, unknown>): unknown;
     restore(snapshot: unknown, options?: Record<string, unknown>): Promise<void>;
     teardown(): void;
 }
 
-export { type Cred as C, type DirEntry as D, type RuntimeVolume as R, type SpawnChild as S, Vfs as V, type WriteOptions as W, VirtualTcpNetwork as a, type RuntimeHttpResponse as b, type SyncSpawn as c, type VolumeStat as d, type VolumeStats as e, type RuntimePod as f, type RuntimePackageInstaller as g, type ChildSpawnConfig as h, type ChildHandle as i, type RuntimeProcess as j, type RuntimeSocketPeer as k, type RuntimeConnection as l, ROOT_CRED as m, type RuntimeProcessManager as n, type RuntimeProcessResult as o, Stats as p, type VirtualNode as q, type VirtualProvider as r, applyChmod as s, createChildProcessModule as t, formatMode as u, makeCred as v, octalMode as w, parseUmask as x };
+export { type Cred as C, type DirEntry as D, type OutboundPolicy as O, type RuntimeVolume as R, type SpawnChild as S, Vfs as V, type WriteOptions as W, VirtualTcpNetwork as a, type RuntimeHttpResponse as b, type SyncSpawn as c, type VolumeStat as d, type VolumeStats as e, type RuntimePod as f, type RuntimePackageInstaller as g, type ChildSpawnConfig as h, type ChildHandle as i, type RuntimeProcess as j, type RuntimeSocketPeer as k, type RuntimeConnection as l, ROOT_CRED as m, type RuntimeProcessManager as n, type RuntimeProcessResult as o, Stats as p, type VirtualNode as q, type VirtualProvider as r, applyChmod as s, createChildProcessModule as t, formatMode as u, makeCred as v, octalMode as w, parseUmask as x };

package/dist/{contracts-CVgctitO.d.ts → contracts-C2_dTgk3.d.ts}

@@ -347,6 +347,27 @@ declare class VirtualTcpNetwork {
     closeAll(): void;
 }
 
+/**
+ * The outbound network policy, as plain functions every client consults.
+ *
+ * The container has several ways out — `curl` and `wget` in the shell, `http`,
+ * `https`, `fetch` and `WebSocket` in a Node program, sockets in Python — and
+ * they used to decide separately. Only the shell asked: a Node program's
+ * `fetch("https://…")` reached the internet from a container booted with
+ * outbound access off. One policy, applied at each exit, is what makes
+ * `network: { allowOutbound: false }` mean what it says.
+ *
+ * Loopback is not "outbound" at all. `127.0.0.1` inside the container is the
+ * container, so those requests are routed to its own servers and never handed
+ * to the host's network stack, whatever the policy allows.
+ */
+interface OutboundPolicy {
+    /** Whether requests may leave the container at all. */
+    allowOutbound: boolean;
+    /** When outbound is on, the hosts it may reach (subdomains included). `null` means any. */
+    allowedHosts: string[] | null;
+}
+
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
  *
@@ -479,9 +500,17 @@ interface RuntimePod {
         headers: Record<string, string>;
         body: Uint8Array;
     }) => Promise<RuntimeHttpResponse>): () => void;
+    /**
+     * Apply the container's outbound policy to programs this pod runs.
+     *
+     * Optional so a pod written elsewhere still satisfies the contract, but a pod
+     * without it cannot keep a program's own `fetch` inside the policy — only
+     * the shell's `curl` would honour it.
+     */
+    setNetworkPolicy?(policy: OutboundPolicy): void;
     snapshot(options?: Record<string, unknown>): unknown;
     restore(snapshot: unknown, options?: Record<string, unknown>): Promise<void>;
     teardown(): void;
 }
 
-export { type Cred as C, type DirEntry as D, type RuntimeVolume as R, type SpawnChild as S, Vfs as V, type WriteOptions as W, VirtualTcpNetwork as a, type RuntimeHttpResponse as b, type SyncSpawn as c, type VolumeStat as d, type VolumeStats as e, type RuntimePod as f, type RuntimePackageInstaller as g, type ChildSpawnConfig as h, type ChildHandle as i, type RuntimeProcess as j, type RuntimeSocketPeer as k, type RuntimeConnection as l, ROOT_CRED as m, type RuntimeProcessManager as n, type RuntimeProcessResult as o, Stats as p, type VirtualNode as q, type VirtualProvider as r, applyChmod as s, createChildProcessModule as t, formatMode as u, makeCred as v, octalMode as w, parseUmask as x };
+export { type Cred as C, type DirEntry as D, type OutboundPolicy as O, type RuntimeVolume as R, type SpawnChild as S, Vfs as V, type WriteOptions as W, VirtualTcpNetwork as a, type RuntimeHttpResponse as b, type SyncSpawn as c, type VolumeStat as d, type VolumeStats as e, type RuntimePod as f, type RuntimePackageInstaller as g, type ChildSpawnConfig as h, type ChildHandle as i, type RuntimeProcess as j, type RuntimeSocketPeer as k, type RuntimeConnection as l, ROOT_CRED as m, type RuntimeProcessManager as n, type RuntimeProcessResult as o, Stats as p, type VirtualNode as q, type VirtualProvider as r, applyChmod as s, createChildProcessModule as t, formatMode as u, makeCred as v, octalMode as w, parseUmask as x };