Interface: SandboxHandle
Defined in: src/batteries/sandbox/manager.ts:28
A live sandbox session: the object every sandbox tool is built against.
Remarks
THIS IS A PROCESS-GLOBAL CAPABILITY WEARING A PER-HANDLE API, and the shape is a promise narrowed rather than a promise kept. SandboxManager is a singleton, so the first createSandbox() in a process establishes the policy and a later one may only NARROW it — a request that is not a subset throws E_SANDBOX_POLICY_CONFLICT naming both. One policy per process is the safe deployment; multi-tenant agents with different policies want separate processes.
Every run() re-validates against the admission baseline before spawning, so a widening of the live policy is DETECTED. Detection is not prevention: SRT's proxies consult policy per request, so a widening already affects an in-flight child for its whole lifetime.
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
effectivePolicy | readonly | () => DerivedRules | undefined | The live DERIVED rules — not the SandboxPolicy that was requested. Remarks A policy cannot express what the drift check has to compare (denyOnly/allowWithinDeny, the unioned default write paths, Linux-expanded read globs, the profile-only mandatory denies), so returning one here would compare the wrong thing and pass while the live sandbox had widened. Under ADOPTION this re-derives from the live manager on every call; an owned session is cached. | src/batteries/sandbox/manager.ts:46 |
epoch | readonly | SandboxEpoch | Opaque token issued at construction and invalidated by SandboxHandle.dispose. Remarks File-backed readers hold this rather than a filesystem reference, which is what makes disposal deterministic: a staged reader outliving its TURN is legitimate, outliving its HANDLE is not. | src/batteries/sandbox/manager.ts:36 |
Methods
dispose()
dispose(): Promise<void>;Defined in: src/batteries/sandbox/manager.ts:88
Quiesce the session: it does not abandon in-flight work.
Returns
Promise<void>
Remarks
Rejects new work with E_SANDBOX_NOT_INITIALIZED, aborts in-flight invocations through their signals, kills spawned children, then releases the enforcer. On an ADOPTED session this is a reported NO-OP — resetting a manager we did not create would strip ACEs a host application depends on.
isEpochLive()
isEpochLive(epoch: SandboxEpoch): boolean;Defined in: src/batteries/sandbox/manager.ts:78
Predicate consumed by file-backed readers; disposal makes the epoch unusable.
Parameters
| Parameter | Type |
|---|---|
epoch | SandboxEpoch |
Returns
boolean
narrow()
narrow(policy: SandboxPolicy): Promise<void>;Defined in: src/batteries/sandbox/manager.ts:76
Narrow the session policy for subsequent operations.
Parameters
| Parameter | Type | Description |
|---|---|---|
policy | SandboxPolicy | Must be a subset per the per-axis rules; reads are deny-then-allow while writes are allow-only, so "narrower" is not symmetric. Throws E_SANDBOX_NARROWING_UNSUPPORTED naming the axis where the platform cannot narrow it. |
Returns
Promise<void>
run()
run(options: {
argv: string[];
correlationId: string;
cwd: string;
env?: Record<string, string>;
policy: SandboxPolicy;
signal?: AbortSignal;
}): Promise<{
completed: Promise<{
exitCode: number;
failed: boolean;
signalCode?: string;
}>;
stderr: ReadableStream<Uint8Array<ArrayBufferLike>>;
stdout: ReadableStream<Uint8Array<ArrayBufferLike>>;
}>;Defined in: src/batteries/sandbox/manager.ts:68
Spawn under this session's policy, optionally narrowed for the single invocation.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | { argv: string[]; correlationId: string; cwd: string; env?: Record<string, string>; policy: SandboxPolicy; signal?: AbortSignal; } | - |
options.argv | string[] | - |
options.correlationId | string | - |
options.cwd | string | - |
options.env? | Record<string, string> | The caller's own EXPLICIT environment values, applied LAST. Remarks NOT the host-inheritance control. What a child inherits from the host is the ADAPTER's decision, expressed as an allow-list the adapter owns (the Node/SRT one denies by default and takes that allow-list at construction). This field is the other half of the picture: the values the caller names itself. They may add names, or override inherited ones, and because they are applied last they also win a collision with an allow-listed name. An adapter MUST NOT let env — or anything else — cause host variables BEYOND its allow-list to reach the child. Concretely, it must not merge the rest of process.env back in on top, and it must not treat the presence of env as a trigger to inherit more widely. Leaving these semantics unstated is how the Node adapter came to spread the entire process.env into every child while this field sat unused. |
options.policy | SandboxPolicy | - |
options.signal? | AbortSignal | Lifecycle cancellation for this child. Implementations must kill the spawned child and settle completed when this signal aborts. |
Returns
Promise<{ completed: Promise<{ exitCode: number; failed: boolean; signalCode?: string; }>; stderr: ReadableStream<Uint8Array<ArrayBufferLike>>; stdout: ReadableStream<Uint8Array<ArrayBufferLike>>; }>
Remarks
Resolves as soon as the child is SPAWNED, handing back live stdout/stderr streams plus a separate completed promise. Drain BOTH concurrently: pipe buffers are per-fd, so draining one to completion first can block the other and hang the child. A non-zero exit is data on completed, never a rejection.
options.policy is a PER-INVOCATION policy. Its effect is backend-specific and, under the SRT enforcer, axis-specific (measured on macOS/seatbelt AND Linux/bwrap, issue #50, both identical): a per-call FILESYSTEM grant is honoured for that ONE child, REPLACING the session baseline rather than unioning with it — the per-call policy is that child's complete filesystem policy, so it must repeat any baseline writes it still wants. A per-call NETWORK section that DIFFERS from the session's — a new domain, a narrowing, an added deny, a different disabled — is REFUSED with E_SANDBOX_NETWORK_GRANT_UNSUPPORTED (SRT's proxy filters every request against the process-global session config, so neither a per-call grant NOR a per-call narrowing is representable), so network policy is established for the session; a per-call policy must repeat the session's network section exactly (order-insensitive set equality). See per-call policy semantics.