@zenera/sandbox 0.0.0-stage → 1.1.56

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Ryabov
+
+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

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @zenera/sandbox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Where an agent's commands run, and the files those commands see. One
+`Sandbox` per session, shared by every agent in it. Depends on Node alone, so a
+host, a sandbox service and the agent inside a container can all build on the
+same contract.
+
+```ts
+import { podmanSandbox } from '@zenera/sandbox';
+
+const sandbox = podmanSandbox({ root: '/path/to/workspace', key: 'session-1' });
+await sandbox.exec('python -V');
+const view = sandbox.files({ root: '/path/to/workspace', mount: '/workspace' });
+await view.fs!.writeFile(`${view.root}/notes.md`, 'hello');
+await sandbox.close();
+```
+
+## The contract
+
+- **`Sandbox`** - `exec`, background jobs (`startJob`, `readJob`, `stopJob`),
+  `close` at the end of a turn, and the files: `fs` (an `FsDriver`) and
+  `files(view)`, which maps the host's workspace and mounts to the paths `fs`
+  finds them at. The invariant: **a file written through `fs` is the file
+  `exec` sees under the same name, and the reverse.**
+- **`SandboxFactory`** - `(opts: SandboxOptions) => Sandbox`, how a host picks
+  where sandboxes run.
+- **`FsDriver`** - the filesystem seam, usable without a sandbox. `localFs` is
+  this machine's disk; `InMemoryFs` keeps a tree in memory.
+
+## Implementations
+
+- **`PodmanSandbox`** / `podmanSandbox` - a podman container on this machine,
+  binding host directories, with `fs = localFs`.
+- A sandbox that keeps its files with the container (a sandbox service) serves
+  `fs` itself and returns `inSandboxPaths(view, fs)` from `files()`.
+
+## Testing an implementation
+
+`@zenera/sandbox/testing` exports the contract as vitest suites, the same ones
+this package runs against its own implementations:
+
+```ts
+import { describeFsDriver, describeSandbox } from '@zenera/sandbox/testing';
+
+describeFsDriver('remote fs', () => ({ fs: new RemoteFs(url), root: '/workspace' }));
+describeSandbox('remote', () => ({ sandbox: openRemote(opts), root: opts.root }));
+```

package/dist/contract.d.ts

@@ -0,0 +1,194 @@
+import type { FsDriver } from './fs.ts';
+import type { FilesView, Mount } from './mounts.ts';
+/** The image a project gets when it does not name one. */
+export declare const DEFAULT_SANDBOX_IMAGE = "docker.io/library/python:3.14-slim-bookworm";
+/**
+ * Everything about a container that an author can state: the project's
+ * `sandbox:` block, resolved. The identity of a container here *is* its
+ * configuration, so a persisted one is reused only while the spec is equal.
+ */
+export interface SandboxSpec {
+    /** the base image commands run in */
+    image?: string;
+    /** fractional cores, as podman's `--cpus` */
+    cpus?: number;
+    /** MiB, as podman's `--memory` */
+    memory?: number;
+    network?: SandboxNetwork;
+    /** where the workspace is mounted, and the default cwd */
+    workdir?: string;
+    /** default seconds a single command may take */
+    timeout?: number;
+    /** how much of the host the container is allowed to be; `standard` by default */
+    hardening?: SandboxHardening;
+    /** uid, name, or `uid:gid`; unset means the image's own user */
+    user?: string;
+    /** keep the container between sessions rather than removing it */
+    persist?: boolean;
+    /** environment inside the container — resolved values, never a passthrough */
+    env?: Record<string, string>;
+    /**
+     * Variables forwarded from this process by *name*, for credentials.
+     *
+     * Separate from `env` for two reasons, both about the value never being
+     * written down. `--env NAME` without an `=` tells podman to read the value
+     * out of its own environment, so the secret never appears on a command
+     * line, in `ps`, or in `podman inspect`. And the container's identity is
+     * computed from the names alone, so rotating a key does not abandon a
+     * persisted container's filesystem.
+     */
+    secrets?: readonly string[];
+}
+export type SandboxNetwork = 'bridge' | 'none' | 'host';
+/**
+ * Two postures, because they cannot both be the default.
+ *
+ * `standard` is the one this tool was built around: a container with an init,
+ * a pid ceiling and `no-new-privileges`, running an image the agent can still
+ * install into. Installing a package is the ordinary use of a shell, so the
+ * capabilities stay and the root filesystem stays writable.
+ *
+ * `strict` is for running code nobody has read. Every capability is dropped,
+ * the root filesystem is read-only, the only writable temporary space is an
+ * in-memory `/tmp` with `noexec,nosuid,nodev`, the process runs as the host's
+ * own unprivileged uid rather than as container root, and the network is off
+ * unless the project turns it back on. What that costs is exactly what it
+ * removes: `apt`, `pip` and anything else that writes outside the mounts stop
+ * working, so a strict project bakes its dependencies into the image instead.
+ *
+ * What it does *not* do is make the bind mounts go away. `/workspace` is the
+ * work itself and stays writable — the profile shrinks the blast radius of a
+ * command, it does not pretend the agent has nothing to edit.
+ */
+export type SandboxHardening = 'standard' | 'strict';
+export interface SandboxOptions extends SandboxSpec {
+    /** host directory mounted at `workdir` */
+    root: string;
+    /**
+     * Stable name for whatever owns this sandbox — a session id, typically.
+     * It prefixes the container name, so a crashed process leaves something a
+     * human can recognise rather than a hash.
+     */
+    key: string;
+    /** refuse to mount the workspace writable */
+    readOnly?: boolean;
+    /** extra bind mounts; the host side must already exist */
+    mounts?: readonly Mount[];
+    /**
+     * Environment set on every command rather than on the container: values
+     * that belong to the run, not to the container — the user it is acting for.
+     *
+     * `env` is fixed when the container is created, and a persisted container
+     * is kept between sessions; a run's values written there
+     * would still be answering for whoever came before. Not part of the
+     * container's name either, for the same reason in reverse: a new user is
+     * not a new machine. Plain values on podman's command line, so nothing
+     * secret goes here — that is what `secrets` is for.
+     */
+    execEnv?: Record<string, string>;
+    /**
+     * Directories put in front of a path-like variable for every command —
+     * `PYTHONPATH`, say — keeping whatever the image already set behind them.
+     * `--env` could only replace the image's value, and an image that relies on
+     * its own `PYTHONPATH` would break on the first `python`.
+     */
+    execPaths?: Record<string, readonly string[]>;
+}
+/**
+ * One session's sandbox. `PodmanSandbox` is one on this machine; a remote
+ * sandbox service is another. The tools and the job model are the same for
+ * both.
+ */
+export interface Sandbox {
+    /**
+     * Derived from the spec, so a persisted sandbox is found again by an equal
+     * spec, and a host can tell a reused one from a new one.
+     */
+    readonly name: string;
+    /** the files every command sees, under the same names */
+    readonly fs: FsDriver;
+    /**
+     * The file tools' view of this sandbox, in its own paths: given the host's
+     * workspace and mounts, where `fs` actually finds each of them.
+     */
+    files(opts: FilesView): FilesView;
+    /** whether anything was actually started — `close` is free when not */
+    readonly started: boolean;
+    /** idempotent and single-flight; every other call starts the sandbox itself */
+    start(): Promise<void>;
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+    /** starts a command and returns its job id; the output goes to a log */
+    startJob(command: string, opts?: ExecOptions): Promise<string>;
+    /**
+     * A window of a job's log, from line `from` (1-based), plus whether it is
+     * still going. An unknown id is a `SandboxError`.
+     */
+    readJob(id: string, from?: number): Promise<JobOutput>;
+    /** Signals the job and everything it started. An unknown id is a `SandboxError`. */
+    stopJob(id: string): Promise<JobStopped>;
+    /**
+     * The session is done for now (the end of a turn): stops a persisted
+     * sandbox, removes an ephemeral one, and keeps the files — a sandbox that
+     * holds them elsewhere persists them here.
+     */
+    close(): Promise<void>;
+}
+/** Opens a session's sandbox. Cheap: nothing starts until it is used. */
+export type SandboxFactory = (opts: SandboxOptions) => Sandbox;
+/** A failure the caller can do something about — a missing engine, usually. */
+export declare class SandboxError extends Error {
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+export interface ExecOptions {
+    cwd?: string;
+    /** seconds; the spec's default otherwise */
+    timeout?: number;
+    signal?: AbortSignal;
+}
+export interface ExecResult {
+    exit_code: number;
+    stdout: string;
+    stderr: string;
+    truncated?: boolean;
+    timed_out?: boolean;
+    duration_ms: number;
+    out_of_memory?: OutOfMemory;
+}
+export interface JobOutput {
+    job_id: string;
+    command: string;
+    running: boolean;
+    /** once it has ended */
+    exit_code?: number;
+    duration_ms: number;
+    /** the window returned, 1-based and inclusive */
+    start_line: number;
+    end_line: number;
+    /** how long the log is now */
+    lines: number;
+    /** more of the log follows `end_line` */
+    truncated?: boolean;
+    output: string;
+    out_of_memory?: OutOfMemory;
+}
+export interface JobStopped {
+    job_id: string;
+    stopped: boolean;
+}
+/**
+ * Why a command was killed for memory, which is a different question from
+ * whether it was. A container that overran its own `--memory` will do it again
+ * however long anyone waits; one the kernel sacrificed for a neighbour may
+ * simply succeed later. Exit code 137 is all either of them says.
+ */
+export interface OutOfMemory {
+    /** what this container was allowed */
+    limit_mib: number;
+    /** high-water mark for the container's whole life, not for this command */
+    peak_mib?: number;
+    /** false when the limit itself is the problem, so an unchanged rerun ends the same way */
+    retryable: boolean;
+    hint: string;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.js

@@ -0,0 +1,27 @@
+// ---------------------------------------------------------------------------
+// The sandbox
+//
+// The whole environment a session's agents work in: one place commands run —
+// a container, here or on a sandbox service — and the files they see. Every
+// agent of the session shares it. This is the contract every implementation
+// keeps, with one invariant:
+//
+//   A file written through `fs` is, at once, the file `exec` sees under the
+//   same name — and the reverse.
+//
+// On `zen run` that is free: a podman container binds the host directory the
+// disk driver reads. A sandbox service keeps the files with the container, so
+// it serves `fs` itself.
+// ---------------------------------------------------------------------------
+/** The image a project gets when it does not name one. */
+export const DEFAULT_SANDBOX_IMAGE = 'docker.io/library/python:3.14-slim-bookworm';
+/** A failure the caller can do something about — a missing engine, usually. */
+export class SandboxError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = 'SandboxError';
+        this.hint = hint;
+    }
+}
+//# sourceMappingURL=contract.js.map

package/dist/fs.d.ts

@@ -0,0 +1,46 @@
+import { type PlatformPath } from 'node:path';
+export interface FsStat {
+    size: number;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+/** One name in a listing: what `stat` says of it, less the size. */
+export type FsEntry = Omit<FsStat, 'size'> & {
+    name: string;
+};
+export interface FsDriver {
+    /** how this driver's paths are spelled: the host's for `localFs`, posix otherwise */
+    readonly path: PlatformPath;
+    /**
+     * The path with every symlink resolved; throws `ENOENT` when it does not
+     * exist. Synchronous because containment is decided synchronously. A
+     * driver whose files live elsewhere may answer lexically here, provided
+     * the far side refuses an escape on its own.
+     */
+    realpathSync(path: string): string;
+    stat(path: string): Promise<FsStat>;
+    readdir(path: string): Promise<FsEntry[]>;
+    readFile(path: string): Promise<Buffer>;
+    /** at most the first `bytes` bytes, for sniffing a file too large to read whole */
+    readHead(path: string, bytes: number): Promise<Buffer>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    /** with parents, and no complaint when it already exists */
+    mkdirp(path: string): Promise<void>;
+    rm(path: string, opts?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    copy(from: string, to: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+}
+/** This machine's disk, through `node:fs`. */
+export declare const localFs: FsDriver;
+/**
+ * A failure shaped like Node's, for drivers that are not `node:fs`: the file
+ * tools read `code` and `path` to say what went wrong in the model's words.
+ */
+export declare function fsError(code: string, syscall: string, at: string): NodeJS.ErrnoException;
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.js

@@ -0,0 +1,39 @@
+import { realpathSync } from 'node:fs';
+import { cp, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path, {} from 'node:path';
+/** This machine's disk, through `node:fs`. */
+export const localFs = {
+    path,
+    realpathSync: (p) => realpathSync(p),
+    stat: (p) => stat(p),
+    readdir: (p) => readdir(p, { withFileTypes: true }),
+    readFile: (p) => readFile(p),
+    async readHead(p, bytes) {
+        const handle = await open(p, 'r');
+        try {
+            const buf = Buffer.alloc(bytes);
+            const { bytesRead } = await handle.read(buf, 0, bytes, 0);
+            return buf.subarray(0, bytesRead);
+        }
+        finally {
+            await handle.close();
+        }
+    },
+    writeFile: (p, data) => writeFile(p, data),
+    mkdirp: async (p) => void (await mkdir(p, { recursive: true })),
+    rm: (p, opts) => rm(p, opts),
+    rename: (from, to) => rename(from, to),
+    copy: (from, to, opts) => cp(from, to, { recursive: opts?.recursive === true }),
+};
+/**
+ * A failure shaped like Node's, for drivers that are not `node:fs`: the file
+ * tools read `code` and `path` to say what went wrong in the model's words.
+ */
+export function fsError(code, syscall, at) {
+    const err = new Error(`${code}: ${syscall} '${at}'`);
+    err.code = code;
+    err.syscall = syscall;
+    err.path = at;
+    return err;
+}
+//# sourceMappingURL=fs.js.map

package/dist/in-memory-fs.d.ts

@@ -0,0 +1,25 @@
+import { type FsDriver, type FsEntry, type FsStat } from './fs.ts';
+export declare class InMemoryFs implements FsDriver {
+    #private;
+    readonly path: import("path").PlatformPath;
+    /** Files to start with, by absolute path; their directories are made as needed. */
+    constructor(files?: Record<string, string | Uint8Array>);
+    /** An empty directory, with its parents. */
+    dir(at: string): this;
+    realpathSync(at: string): string;
+    stat(at: string): Promise<FsStat>;
+    readdir(at: string): Promise<FsEntry[]>;
+    readFile(at: string): Promise<Buffer>;
+    readHead(at: string, bytes: number): Promise<Buffer>;
+    writeFile(at: string, data: string | Uint8Array): Promise<void>;
+    mkdirp(at: string): Promise<void>;
+    rm(at: string, opts?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    copy(from: string, to: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+}
+//# sourceMappingURL=in-memory-fs.d.ts.map

package/dist/in-memory-fs.js

@@ -0,0 +1,165 @@
+import { posix } from 'node:path';
+import { fsError } from "./fs.js";
+export class InMemoryFs {
+    path = posix;
+    #nodes = new Map([['/', { kind: 'dir' }]]);
+    /** Files to start with, by absolute path; their directories are made as needed. */
+    constructor(files = {}) {
+        for (const [at, data] of Object.entries(files)) {
+            this.#mkdirs(posix.dirname(this.#abs(at)));
+            this.#nodes.set(this.#abs(at), { kind: 'file', data: Buffer.from(data) });
+        }
+    }
+    /** An empty directory, with its parents. */
+    dir(at) {
+        this.#mkdirs(this.#abs(at));
+        return this;
+    }
+    realpathSync(at) {
+        const abs = this.#abs(at);
+        if (!this.#nodes.has(abs)) {
+            throw fsError('ENOENT', 'realpath', at);
+        }
+        return abs;
+    }
+    async stat(at) {
+        return info(this.#get(at, 'stat'));
+    }
+    async readdir(at) {
+        const abs = this.#abs(at);
+        if (this.#get(at, 'scandir').kind !== 'dir') {
+            throw fsError('ENOTDIR', 'scandir', at);
+        }
+        return this.#children(abs).map((child) => ({
+            name: posix.basename(child),
+            ...info(this.#nodes.get(child)),
+        }));
+    }
+    async readFile(at) {
+        const node = this.#get(at, 'open');
+        if (node.kind !== 'file') {
+            throw fsError('EISDIR', 'read', at);
+        }
+        return Buffer.from(node.data);
+    }
+    async readHead(at, bytes) {
+        return (await this.readFile(at)).subarray(0, bytes);
+    }
+    async writeFile(at, data) {
+        const abs = this.#abs(at);
+        this.#parent(abs, 'open');
+        if (this.#nodes.get(abs)?.kind === 'dir') {
+            throw fsError('EISDIR', 'open', at);
+        }
+        this.#nodes.set(abs, { kind: 'file', data: Buffer.from(data) });
+    }
+    async mkdirp(at) {
+        this.#mkdirs(this.#abs(at));
+    }
+    async rm(at, opts = {}) {
+        const abs = this.#abs(at);
+        const node = this.#nodes.get(abs);
+        if (!node) {
+            if (opts.force) {
+                return;
+            }
+            throw fsError('ENOENT', 'rm', at);
+        }
+        if (node.kind === 'dir') {
+            if (!opts.recursive) {
+                throw fsError('EISDIR', 'rm', at);
+            }
+            for (const key of this.#below(abs)) {
+                this.#nodes.delete(key);
+            }
+        }
+        this.#nodes.delete(abs);
+    }
+    async rename(from, to) {
+        const src = this.#abs(from);
+        const dst = this.#abs(to);
+        const node = this.#get(from, 'rename');
+        this.#parent(dst, 'rename');
+        const there = this.#nodes.get(dst);
+        if (there?.kind === 'dir' && this.#children(dst).length > 0) {
+            throw fsError('ENOTEMPTY', 'rename', to);
+        }
+        const moved = node.kind === 'dir' ? this.#below(src) : [];
+        this.#nodes.delete(dst);
+        this.#nodes.set(dst, node);
+        this.#nodes.delete(src);
+        for (const key of moved) {
+            this.#nodes.set(dst + key.slice(src.length), this.#nodes.get(key));
+            this.#nodes.delete(key);
+        }
+    }
+    async copy(from, to, opts = {}) {
+        const src = this.#abs(from);
+        const dst = this.#abs(to);
+        const node = this.#get(from, 'cp');
+        if (node.kind === 'dir' && !opts.recursive) {
+            throw fsError('EISDIR', 'cp', from);
+        }
+        this.#parent(dst, 'cp');
+        this.#nodes.set(dst, copyOf(node));
+        if (node.kind === 'dir') {
+            for (const key of this.#below(src)) {
+                this.#nodes.set(dst + key.slice(src.length), copyOf(this.#nodes.get(key)));
+            }
+        }
+    }
+    #abs(at) {
+        return posix.resolve('/', at);
+    }
+    #get(at, syscall) {
+        const node = this.#nodes.get(this.#abs(at));
+        if (!node) {
+            throw fsError('ENOENT', syscall, at);
+        }
+        return node;
+    }
+    /** The parent has to be there already, as it does for `node:fs` without `recursive`. */
+    #parent(abs, syscall) {
+        const up = this.#nodes.get(posix.dirname(abs));
+        if (!up) {
+            throw fsError('ENOENT', syscall, abs);
+        }
+        if (up.kind !== 'dir') {
+            throw fsError('ENOTDIR', syscall, abs);
+        }
+    }
+    #mkdirs(abs) {
+        if (abs === '/') {
+            return;
+        }
+        this.#mkdirs(posix.dirname(abs));
+        const node = this.#nodes.get(abs);
+        if (node?.kind === 'file') {
+            throw fsError('EEXIST', 'mkdir', abs);
+        }
+        if (!node) {
+            this.#nodes.set(abs, { kind: 'dir' });
+        }
+    }
+    #children(abs) {
+        const prefix = abs === '/' ? '/' : `${abs}/`;
+        return [...this.#nodes.keys()]
+            .filter((k) => k !== abs && k.startsWith(prefix) && !k.slice(prefix.length).includes('/'))
+            .sort();
+    }
+    #below(abs) {
+        return [...this.#nodes.keys()].filter((k) => k.startsWith(`${abs}/`));
+    }
+}
+function info(node) {
+    return {
+        size: node.kind === 'file' ? node.data.byteLength : 0,
+        isFile: () => node.kind === 'file',
+        isDirectory: () => node.kind === 'dir',
+        isSymbolicLink: () => false,
+    };
+}
+function copyOf(node) {
+    return node.kind === 'file' ? { kind: 'file', data: Buffer.from(node.data) } : { kind: 'dir' };
+}
+//# sourceMappingURL=in-memory-fs.js.map

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './contract.ts';
+export * from './fs.ts';
+export * from './in-memory-fs.ts';
+export * from './limits.ts';
+export * from './mounts.ts';
+export * from './podman.ts';
+export * from './process.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,11 @@
+// The sandbox: where a session's commands run and the files they see. Depends
+// on Node alone, so a host, a sandbox service and the agent inside a container
+// can all stand on the same contract. Contract tests: `@zenera/sandbox/testing`.
+export * from "./contract.js";
+export * from "./fs.js";
+export * from "./in-memory-fs.js";
+export * from "./limits.js";
+export * from "./mounts.js";
+export * from "./podman.js";
+export * from "./process.js";
+//# sourceMappingURL=index.js.map

package/dist/limits.d.ts

@@ -0,0 +1,19 @@
+import type { SandboxHardening, SandboxSpec } from './contract.ts';
+export interface SandboxLimits {
+    /** MiB */
+    memory: number;
+    /** fractional cores */
+    cpus: number;
+    hardening: SandboxHardening;
+    /** whether the numbers above were written down, or are this profile's defaults */
+    declared: boolean;
+}
+/**
+ * What a spec's ceilings come to, for a report that has no container to ask.
+ *
+ * It exists so `zen sandbox status` cannot disagree with what a run actually
+ * applies: the defaults are stated once, here and in `resolveSpec`, and
+ * nothing outside this module repeats them.
+ */
+export declare function sandboxLimits(spec?: Pick<SandboxSpec, 'cpus' | 'memory' | 'hardening'>): SandboxLimits;
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.js

@@ -0,0 +1,33 @@
+// ---------------------------------------------------------------------------
+// A sandbox's ceilings
+//
+// Stated once, here, so the sandbox that applies them and `zen sandbox status`
+// that reports them cannot disagree.
+// ---------------------------------------------------------------------------
+// Standard mode's resource ceilings. Even without the strict profile, an
+// unbounded container can exhaust host cores or memory during runaway builds.
+const DEFAULT_CPUS = 4;
+const DEFAULT_MEMORY = 4096;
+// Strict mode's own defaults. A limit that is only there when someone
+// remembered to write it down is not a limit, so the profile supplies one for
+// each of the four exhaustible things: cores, memory, processes and disk.
+const STRICT_CPUS = 2;
+const STRICT_MEMORY = 2048;
+/**
+ * What a spec's ceilings come to, for a report that has no container to ask.
+ *
+ * It exists so `zen sandbox status` cannot disagree with what a run actually
+ * applies: the defaults are stated once, here and in `resolveSpec`, and
+ * nothing outside this module repeats them.
+ */
+export function sandboxLimits(spec = {}) {
+    const hardening = spec.hardening ?? 'standard';
+    const strict = hardening === 'strict';
+    return {
+        memory: spec.memory ?? (strict ? STRICT_MEMORY : DEFAULT_MEMORY),
+        cpus: spec.cpus ?? (strict ? STRICT_CPUS : DEFAULT_CPUS),
+        hardening,
+        declared: spec.memory !== undefined || spec.cpus !== undefined,
+    };
+}
+//# sourceMappingURL=limits.js.map