@zenera/sandbox 0.0.0-stage → 1.1.57

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,61 @@
-# 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`** - `prepare` (pull the image, or build it from `build:`),
+  `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.
+
+## The image
+
+A spec names an `image` to pull, or a `build` (`{ dockerfile, context, args }`)
+to build. Getting it there is the sandbox's job, in `prepare()`: podman builds
+on this machine, a sandbox service on its own builders. What every backend
+shares is the build's identity, `buildIdentity(build)` - the context's files
+and the hash of them - so a project names the same image everywhere.
+`prepare({ onProgress, slow, force, allowBuild: false })` reports progress,
+rebuilds, or refuses to build at all; `start` does whatever of it is still
+needed. A failed build is an `ImageBuildError` (`isImageBuildError` checks it
+by name, across copies of this package).
+
+## Implementations
+
+- **`PodmanSandbox`** / `podmanSandbox` - a podman container on this machine,
+  binding host directories, with `fs = localFs`. `ensurePodmanImage` is its
+  image step on its own.
+- 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,230 @@
+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;
+    /**
+     * A Dockerfile to build instead of an image to pull. The sandbox builds it
+     * where it runs — podman on this machine, a service on its own builders —
+     * under a tag derived from its content; `image` is then ignored.
+     */
+    build?: BuildSpec;
+    /** 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';
+/** A Dockerfile and what it may see. Paths are absolute and already checked by the host. */
+export interface BuildSpec {
+    dockerfile: string;
+    /** the build context: what `COPY` can reach */
+    context: string;
+    /** `--build-arg`s; part of the image's identity */
+    args?: Record<string, string>;
+}
+/** How a sandbox gets its image ready. */
+export interface PrepareOptions {
+    /** lines worth showing a person: what is being pulled or built, and how it ended */
+    onProgress?(line: string): void;
+    /** wraps a slow step — a pull, a build — so a host can show it is still going */
+    slow?<T>(label: string, work: Promise<T>): Promise<T>;
+    /** pull or build again even when the image is there; `zen sandbox pull` */
+    force?: boolean;
+    /**
+     * false: an image that would have to be built is a `SandboxError` instead —
+     * for a host whose images are built somewhere else, ahead of time.
+     */
+    allowBuild?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * 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;
+    /**
+     * Makes the image available — pulled, or built from `build` — without
+     * starting anything, so a host can do the slow part before the first turn
+     * and show it. Idempotent and single-flight unless `force`; `start` does
+     * whatever of it is still needed.
+     */
+    prepare(opts?: PrepareOptions): Promise<void>;
+    /** 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/image.d.ts

@@ -0,0 +1,62 @@
+import { SandboxError, type BuildSpec, type PrepareOptions } from './contract.ts';
+import { type Runner } from './process.ts';
+/** Where locally built images are tagged. Not scoped: a `/` or an `@` is not a legal tag. */
+export declare const LOCAL_IMAGE_REPO = "localhost/zenera-sandbox";
+/**
+ * A build context is meant to be small — a Dockerfile and whatever it copies.
+ * Hashing a directory someone pointed at their whole home folder would hang
+ * before it was wrong, so it stops and says which key to narrow.
+ */
+export declare const MAX_CONTEXT_FILES = 2000;
+/** What a build is made of: the address every backend agrees on. */
+export interface BuildIdentity {
+    /** 12 hex characters; the tag a build is known by */
+    hash: string;
+    /** every file in the context, relative and sorted — exactly what was hashed */
+    files: readonly string[];
+}
+/**
+ * The content address of a build: the Dockerfile, then every file the build can
+ * see, by path and by content, then its arguments.
+ *
+ * `.dockerignore` is not read. The engine honours it and this does not, so an
+ * ignored file that changes yields a new tag and a build that produces the same
+ * image — wasteful, never wrong, and the alternative is reimplementing a match
+ * syntax whose disagreements would be silent.
+ */
+export declare function buildIdentity(spec: BuildSpec): BuildIdentity;
+/** The tag a build is run under on this machine. */
+export declare function localImageTag(build: BuildSpec | BuildIdentity): string;
+/**
+ * A build that ran and failed, rather than an engine that could not be asked.
+ * Both stop a run, but only one of them is the project's fault: `zen check`
+ * reports a Dockerfile that does not build as an error, and a laptop without
+ * podman as a warning.
+ */
+export declare class ImageBuildError extends SandboxError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Whether `err` is a failed build, by name rather than by class: a plugin
+ * that provides the sandbox may bring its own copy of this package, and its
+ * `ImageBuildError` is then a different class that means the same thing.
+ */
+export declare function isImageBuildError(err: unknown): err is ImageBuildError;
+/**
+ * Puts the image on this machine's engine: nothing when it is already there,
+ * a build when the spec names a Dockerfile, a pull otherwise.
+ *
+ * Skipping a present build is safe in a way it would not be for an ordinary
+ * tag, because this one is a hash of the Dockerfile and its context: the image
+ * existing *means* the content is unchanged. What it does not cover is a moved
+ * base image — `podman build` reuses whatever `FROM node:24` resolved to last
+ * time — which is what `force` is for.
+ */
+export declare function ensurePodmanImage(target: {
+    image: string;
+    build?: BuildSpec;
+}, host?: {
+    engine?: string;
+    exec?: Runner;
+}, opts?: PrepareOptions): Promise<void>;
+//# sourceMappingURL=image.d.ts.map