@zenera/sandbox 0.0.0-stage → 1.1.56

package/dist/mounts.d.ts

@@ -0,0 +1,84 @@
+import type { FsDriver } from './fs.ts';
+/** Where the workspace appears in the agent's namespace, and the default cwd. */
+export declare const WORKSPACE_MOUNT = "/workspace";
+/** Where a project's `assets/` directory appears. */
+export declare const ASSETS_MOUNT = "/assets";
+/** ...and where its skill catalog does, so a skill's scripts can be run. */
+export declare const SKILLS_MOUNT = "/skills";
+export type MountSource = 
+/** the project's reference material, at `/assets` */
+{
+    kind: 'assets';
+}
+/** the skill catalog — one merged tree at `/skills`, however many folders it came from */
+ | {
+    kind: 'skills';
+}
+/** the container's private, persistent `$HOME` */
+ | {
+    kind: 'home';
+}
+/** one credential file, by the variable that names it */
+ | {
+    kind: 'credential';
+    name: string;
+};
+export interface Mount {
+    /** absolute host path; must already exist */
+    host: string;
+    /** absolute path the agent names it by, e.g. `/assets` */
+    at: string;
+    /**
+     * Say it. Unset, the file tools treat an extra tree as reference material
+     * and refuse to write it, while the sandbox binds it writable — the container's
+     * `$HOME` is the one mount that relies on that.
+     */
+    readOnly?: boolean;
+    /** what the tree is, for a backend that has to supply it rather than bind `host` */
+    source?: MountSource;
+}
+/**
+ * The trees a file tool reaches, and the names it reaches them by: the
+ * workspace, the name it is also mounted at, and the extra trees beside it.
+ * What `Sandbox.files` translates into the sandbox's own paths, and what the
+ * file tools in `@zenera/neo` take.
+ */
+export interface FilesView {
+    root: string;
+    /** refuse every mutating tool; `zen run --read-only` */
+    readOnly?: boolean;
+    /**
+     * An absolute path the root is *also* known by, because something else has
+     * mounted it there — the sandbox mounts the workspace at `/workspace`, so
+     * `run_command` returns compiler errors, stack traces and `pwd` output
+     * naming files under a prefix the file tools would otherwise refuse. Set
+     * it and both spellings reach the same file.
+     */
+    mount?: string;
+    /** further trees, each under its own name; read-only unless one says otherwise */
+    mounts?: readonly Mount[];
+    /**
+     * Where the bytes are; this machine's disk when unset. `root` and every
+     * mount's `host` are paths in this driver's namespace.
+     */
+    fs?: FsDriver;
+}
+/** A mount stated by what it is: no host path, nothing to bind. */
+export type LogicalMount = Required<Omit<Mount, 'host'>>;
+/**
+ * The mounts a supplying backend is asked for. The skill catalog arrives here
+ * as one bind per skill folder — podman cannot merge directories — and leaves
+ * as the single `/skills` tree it is to the agent. A mount nobody labelled is a
+ * host directory with no meaning elsewhere, so it is refused rather than
+ * silently dropped.
+ */
+export declare function logicalMounts(mounts: readonly Mount[]): LogicalMount[];
+/**
+ * The file tools' view for a sandbox that keeps its files with the container
+ * rather than reading host directories: the workspace is its mount point, and
+ * each tree is found where the container has it — so a path the model writes
+ * means one file to the tools and the shell. What a remote `Sandbox.files`
+ * returns; a podman one reads the host paths as they are.
+ */
+export declare function inSandboxPaths(opts: FilesView, fs: FsDriver): FilesView;
+//# sourceMappingURL=mounts.d.ts.map

package/dist/mounts.js

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// The trees an agent can reach, and what each one is
+//
+// One directory is one mount, and the host hands the same array to the file
+// tools and to the sandbox so that both call it by the same name: a path a command
+// prints is a path `read_file` accepts.
+//
+// On `zen run` every tree is a host directory bound into the container, and
+// `host` is the whole story. A sandbox on another machine has no host path to
+// bind: it has to be told what the tree is — the project's assets, its skills —
+// and fetch that itself. So a mount carries both: `host` for a backend that
+// binds, `source` for one that supplies. Memory is not a mount: its files stay
+// with the graph and reach a sandbox only through `memory_copy_file`.
+// ---------------------------------------------------------------------------
+/** Where the workspace appears in the agent's namespace, and the default cwd. */
+export const WORKSPACE_MOUNT = '/workspace';
+/** Where a project's `assets/` directory appears. */
+export const ASSETS_MOUNT = '/assets';
+/** ...and where its skill catalog does, so a skill's scripts can be run. */
+export const SKILLS_MOUNT = '/skills';
+/**
+ * The mounts a supplying backend is asked for. The skill catalog arrives here
+ * as one bind per skill folder — podman cannot merge directories — and leaves
+ * as the single `/skills` tree it is to the agent. A mount nobody labelled is a
+ * host directory with no meaning elsewhere, so it is refused rather than
+ * silently dropped.
+ */
+export function logicalMounts(mounts) {
+    const out = [];
+    let skills = false;
+    for (const m of mounts) {
+        if (!m.source) {
+            throw new Error(`mount ${m.at} has no source, so only a local sandbox can provide it`);
+        }
+        if (m.source.kind === 'skills') {
+            if (!skills) {
+                out.push({ at: SKILLS_MOUNT, readOnly: true, source: m.source });
+                skills = true;
+            }
+            continue;
+        }
+        out.push({ at: m.at, readOnly: m.readOnly ?? false, source: m.source });
+    }
+    return out;
+}
+/**
+ * The file tools' view for a sandbox that keeps its files with the container
+ * rather than reading host directories: the workspace is its mount point, and
+ * each tree is found where the container has it — so a path the model writes
+ * means one file to the tools and the shell. What a remote `Sandbox.files`
+ * returns; a podman one reads the host paths as they are.
+ */
+export function inSandboxPaths(opts, fs) {
+    const mount = opts.mount ?? WORKSPACE_MOUNT;
+    return {
+        ...opts,
+        root: mount,
+        mount,
+        mounts: logicalMounts(opts.mounts ?? []).map((m) => ({ ...m, host: m.at })),
+        fs,
+    };
+}
+//# sourceMappingURL=mounts.js.map

package/dist/podman.d.ts

@@ -0,0 +1,76 @@
+import { type FsDriver } from './fs.ts';
+import { type FilesView, type Mount } from './mounts.ts';
+import { type Runner } from './process.ts';
+import { type Sandbox, type SandboxFactory, type ExecOptions, type ExecResult, type JobOutput, type JobStopped, type SandboxOptions, type SandboxSpec } from './contract.ts';
+/** What only a podman sandbox needs: which binary to drive, and how to spawn it. */
+export interface PodmanHost {
+    /** the container engine binary; `podman` when unset */
+    engine?: string;
+    /** how processes are spawned — the seam tests replace */
+    exec?: Runner;
+}
+interface Resolved extends Required<Omit<SandboxSpec, 'user'>> {
+    user?: string;
+    root: string;
+    key: string;
+    readOnly: boolean;
+    mounts: readonly Mount[];
+    execEnv: Record<string, string>;
+    execPaths: Record<string, readonly string[]>;
+    explicitCpus?: boolean;
+    explicitMemory?: boolean;
+}
+/**
+ * The container, started when it is first needed and not before. A project
+ * whose agents never shell out never pays for an image pull, and a session
+ * that only ever asks a question never leaves anything behind.
+ */
+export declare class PodmanSandbox implements Sandbox {
+    #private;
+    readonly name: string;
+    /** the container binds the host directories, so the disk is where the files are */
+    readonly fs: FsDriver;
+    readonly spec: Resolved;
+    readonly engine: string;
+    constructor(opts: SandboxOptions, host?: PodmanHost);
+    /** Whether anything was actually started — `close` is free when not. */
+    get started(): boolean;
+    /** The host paths, as they are: the container binds exactly these. */
+    files(opts: FilesView): FilesView;
+    /**
+     * Idempotent, and single-flight: several tool calls in one batch all await
+     * the same start rather than racing to create the same container.
+     */
+    start(): Promise<void>;
+    /**
+     * Runs one command and waits for it. The script goes down stdin, so no part
+     * of it is ever parsed by a shell on this side of the container.
+     */
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Starts a command and returns. The wrapper writes the log and the exit
+     * code to files the container owns, which is what makes the job readable
+     * after the `exec` that started it has long returned.
+     */
+    startJob(command: string, opts?: ExecOptions): Promise<string>;
+    /** A window of a job's log, plus whether it is still going. */
+    readJob(id: string, from?: number): Promise<JobOutput>;
+    /** Signals a job's whole process group, so its children go too. */
+    stopJob(id: string): Promise<JobStopped>;
+    /**
+     * Stops a persisted container and removes an ephemeral one. Stopping
+     * rather than removing is what makes `persist` mean anything: a stopped
+     * container costs disk, a running one costs the machine's whole budget.
+     */
+    close(): Promise<void>;
+    /**
+     * A path inside the container, contained to the working directory. Purely
+     * lexical, and correctly so: this is the container's path space, not this
+     * machine's, and there is nothing here to resolve a symlink against.
+     */
+    inside(path?: string): string;
+}
+/** Podman on this machine: what `zen run` uses, and the engine's default. */
+export declare const podmanSandbox: SandboxFactory;
+export {};
+//# sourceMappingURL=podman.d.ts.map