@zenera/sandbox 1.1.57 → 1.1.59

package/README.md

@@ -10,8 +10,7 @@ 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.fs.writeFile('/workspace/notes.md', 'hello'); // what `cat notes.md` sees
 await sandbox.close();
 ```
 
@@ -19,14 +18,18 @@ await sandbox.close();
 
 - **`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.**
+  `close` at the end of a turn, and the files: `fs`, an `FsDriver` in the
+  agent's own paths (`/workspace/a.py`) and contained to the sandbox's trees.
+  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.
+- **`FsDriver`** - the filesystem seam, usable without a sandbox. `RootedFs`
+  serves named trees from directories on this machine - `/workspace` from the
+  session's folder, `/assets` read-only - and is the one place a path is
+  contained: it must name a tree, its symlinks must resolve into one, and a
+  read-only tree refuses every change. `localFs` is this machine's disk as it
+  is; `InMemoryFs` keeps a tree in memory.
 
 ## The image
 
@@ -43,10 +46,10 @@ 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.
+  binding host directories, with `fs` a `RootedFs` over them under the names
+  they are bound at. `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()`.
+  `fs` itself, under the same names.
 
 ## Testing an implementation
 

package/dist/contract.d.ts

@@ -1,5 +1,5 @@
 import type { FsDriver } from './fs.ts';
-import type { FilesView, Mount } from './mounts.ts';
+import type { 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";
 /**
@@ -134,13 +134,12 @@ export interface Sandbox {
      * 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.
+     * The files every command sees, under the names commands see them by —
+     * /workspace, /assets, … — and contained: nothing outside those trees,
+     * nothing changed in a read-only one.
      */
-    files(opts: FilesView): FilesView;
+    readonly fs: FsDriver;
     /** whether anything was actually started — `close` is free when not */
     readonly started: boolean;
     /**

package/dist/fs.d.ts

@@ -12,13 +12,6 @@ export type FsEntry = Omit<FsStat, 'size'> & {
 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>;

package/dist/fs.js

@@ -1,10 +1,8 @@
-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),

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

@@ -6,7 +6,6 @@ export declare class InMemoryFs implements FsDriver {
     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>;

package/dist/in-memory-fs.js

@@ -15,13 +15,6 @@ export class InMemoryFs {
         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'));
     }

package/dist/index.d.ts

@@ -6,4 +6,5 @@ export * from './limits.ts';
 export * from './mounts.ts';
 export * from './podman.ts';
 export * from './process.ts';
+export * from './rooted-fs.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -9,4 +9,5 @@ export * from "./limits.js";
 export * from "./mounts.js";
 export * from "./podman.js";
 export * from "./process.js";
+export * from "./rooted-fs.js";
 //# sourceMappingURL=index.js.map

package/dist/mounts.d.ts

@@ -1,4 +1,3 @@
-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. */
@@ -37,48 +36,4 @@ export interface Mount {
     /** 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

@@ -1,9 +1,9 @@
 // ---------------------------------------------------------------------------
 // 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.
+// One directory is one mount, at the name the agent knows it by. The sandbox
+// serves every tree under those names — its `fs` and its commands alike — so 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
@@ -18,46 +18,4 @@ export const WORKSPACE_MOUNT = '/workspace';
 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

@@ -1,5 +1,5 @@
-import { type FsDriver } from './fs.ts';
-import { type FilesView, type Mount } from './mounts.ts';
+import { type Mount } from './mounts.ts';
+import { RootedFs } from './rooted-fs.ts';
 import { type Runner } from './process.ts';
 import { type BuildSpec, type PrepareOptions, 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. */
@@ -30,15 +30,13 @@ interface Resolved extends Required<Omit<SandboxSpec, 'user' | 'build'>> {
 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;
+    /** the directories the container binds, under the names it binds them at */
+    readonly fs: RootedFs;
     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;
     /** Pulls the image, or builds it from the Dockerfile, unless the engine already has it. */
     prepare(opts?: PrepareOptions): Promise<void>;
     /**

package/dist/podman.js

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto';
 import { posix } from 'node:path';
 import { ensurePodmanImage, localImageTag } from "./image.js";
-import { localFs } from "./fs.js";
 import { sandboxLimits } from "./limits.js";
 import { WORKSPACE_MOUNT } from "./mounts.js";
+import { RootedFs } from "./rooted-fs.js";
 import { MAX_TIMEOUT_MS, resilient, runProcess } from "./process.js";
 import { DEFAULT_SANDBOX_IMAGE, SandboxError, } from "./contract.js";
 // ---------------------------------------------------------------------------
@@ -47,8 +47,8 @@ const CGROUP = [
  */
 export class PodmanSandbox {
     name;
-    /** the container binds the host directories, so the disk is where the files are */
-    fs = localFs;
+    /** the directories the container binds, under the names it binds them at */
+    fs;
     spec;
     engine;
     #run;
@@ -65,15 +65,18 @@ export class PodmanSandbox {
         this.#spawn = host.exec ?? runProcess;
         this.#run = resilient(this.#spawn);
         this.name = containerName(this.spec);
+        this.fs = new RootedFs([
+            { at: this.spec.workdir, dir: this.spec.root, readOnly: this.spec.readOnly },
+            // A credential is one file, not a tree, and no tool has any business reading it.
+            ...this.spec.mounts
+                .filter((m) => m.source?.kind !== 'credential')
+                .map((m) => ({ at: m.at, dir: m.host, readOnly: m.readOnly })),
+        ]);
     }
     /** Whether anything was actually started — `close` is free when not. */
     get started() {
         return this.#created;
     }
-    /** The host paths, as they are: the container binds exactly these. */
-    files(opts) {
-        return { ...opts, fs: this.fs };
-    }
     /** Pulls the image, or builds it from the Dockerfile, unless the engine already has it. */
     prepare(opts = {}) {
         if (this.#prepared && !opts.force) {

package/dist/rooted-fs.d.ts

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { type FsDriver, type FsEntry, type FsStat } from './fs.ts';
+/** One tree: the name the agent knows it by, and the directory it is here. */
+export interface Tree {
+    /** absolute, posix: `/workspace`, `/assets`, `/skills/review` */
+    at: string;
+    /** where it is on this machine */
+    dir: string;
+    readOnly?: boolean;
+}
+export declare class RootedFs implements FsDriver {
+    #private;
+    readonly path: path.PlatformPath;
+    constructor(trees: readonly Tree[]);
+    get trees(): readonly Required<Tree>[];
+    /**
+     * Where an agent path is on this machine, contained: it must name a tree,
+     * and whatever of it exists must resolve, symlinks and all, into a tree — a
+     * writable one when `write`. The path need not exist.
+     */
+    hostPath(at: string, opts?: {
+        write?: boolean;
+    }): string;
+    /** An agent path for a file on this machine; undefined when it is in no tree. */
+    agentPath(host: string): string | undefined;
+    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=rooted-fs.d.ts.map

package/dist/rooted-fs.js

@@ -0,0 +1,169 @@
+import { realpathSync } from 'node:fs';
+import { cp, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path, { posix } from 'node:path';
+import { fsError } from "./fs.js";
+export class RootedFs {
+    path = posix;
+    /** longest name first, so a nested tree wins over the one it sits in */
+    #trees;
+    constructor(trees) {
+        this.#trees = trees
+            .map((t) => ({
+            at: name(t.at),
+            dir: path.resolve(t.dir),
+            readOnly: t.readOnly ?? false,
+        }))
+            .sort((a, b) => b.at.length - a.at.length);
+    }
+    get trees() {
+        return this.#trees;
+    }
+    /**
+     * Where an agent path is on this machine, contained: it must name a tree,
+     * and whatever of it exists must resolve, symlinks and all, into a tree — a
+     * writable one when `write`. The path need not exist.
+     */
+    hostPath(at, opts = {}) {
+        const clean = agentPath(at);
+        const tree = this.#treeOf(clean);
+        if (!tree) {
+            throw fsError('EACCES', 'open', clean);
+        }
+        if (opts.write && tree.readOnly) {
+            throw fsError('EROFS', 'open', clean);
+        }
+        const host = clean === tree.at
+            ? tree.dir
+            : path.join(tree.dir, ...posix.relative(tree.at, clean).split('/'));
+        this.#contain(host, clean, opts.write === true);
+        return host;
+    }
+    /** An agent path for a file on this machine; undefined when it is in no tree. */
+    agentPath(host) {
+        return this.#owner(host)?.at;
+    }
+    async stat(at) {
+        const host = this.hostPath(at);
+        return guard(at, () => stat(host));
+    }
+    async readdir(at) {
+        const host = this.hostPath(at);
+        return guard(at, () => readdir(host, { withFileTypes: true }));
+    }
+    async readFile(at) {
+        const host = this.hostPath(at);
+        return guard(at, () => readFile(host));
+    }
+    async readHead(at, bytes) {
+        const host = this.hostPath(at);
+        return guard(at, async () => {
+            const handle = await open(host, '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();
+            }
+        });
+    }
+    async writeFile(at, data) {
+        const host = this.hostPath(at, { write: true });
+        await guard(at, () => writeFile(host, data));
+    }
+    async mkdirp(at) {
+        const host = this.hostPath(at, { write: true });
+        await guard(at, () => mkdir(host, { recursive: true }));
+    }
+    async rm(at, opts = {}) {
+        const host = this.hostPath(at, { write: true });
+        await guard(at, () => rm(host, { recursive: opts.recursive === true, force: opts.force === true }));
+    }
+    async rename(from, to) {
+        const src = this.hostPath(from, { write: true });
+        const dst = this.hostPath(to, { write: true });
+        await guard(from, () => rename(src, dst));
+    }
+    async copy(from, to, opts = {}) {
+        const src = this.hostPath(from);
+        const dst = this.hostPath(to, { write: true });
+        await guard(from, () => cp(src, dst, { recursive: opts.recursive === true }));
+    }
+    #treeOf(at) {
+        return this.#trees.find((t) => at === t.at || t.at === '/' || at.startsWith(`${t.at}/`));
+    }
+    #owner(host) {
+        let best;
+        for (const tree of this.#trees) {
+            const base = canonical(tree.dir);
+            if (host !== base && !host.startsWith(base + path.sep)) {
+                continue;
+            }
+            // The deepest directory owns a path that two trees both contain.
+            if (best && best.depth >= base.length) {
+                continue;
+            }
+            const rest = path.relative(base, host).split(path.sep).join('/');
+            best = { tree, at: rest ? posix.join(tree.at, rest) : tree.at, depth: base.length };
+        }
+        return best;
+    }
+    #contain(host, at, write) {
+        let probe = host;
+        for (;;) {
+            let real;
+            try {
+                real = realpathSync(probe);
+            }
+            catch (err) {
+                const code = err.code;
+                const up = path.dirname(probe);
+                if (code !== 'ENOENT' || up === probe) {
+                    throw code ? fsError(code, 'realpath', at) : err;
+                }
+                probe = up;
+                continue;
+            }
+            const owner = this.#owner(real);
+            if (!owner) {
+                throw fsError('EACCES', 'realpath', at);
+            }
+            if (write && owner.tree.readOnly) {
+                throw fsError('EROFS', 'open', at);
+            }
+            return;
+        }
+    }
+}
+/** A path the agent gave, made absolute and normal; anything else is not a path. */
+function agentPath(at) {
+    if (typeof at !== 'string' || !at.startsWith('/') || at.includes('\0')) {
+        throw fsError('EINVAL', 'open', String(at));
+    }
+    return name(at);
+}
+function name(at) {
+    const clean = posix.normalize(at.replace(/\\/g, '/'));
+    return clean.length > 1 ? clean.replace(/\/+$/, '') : clean;
+}
+/** A tree's directory with its own symlinks resolved (macOS: /var is /private/var). */
+function canonical(dir) {
+    try {
+        return realpathSync(dir);
+    }
+    catch {
+        return dir;
+    }
+}
+/** Node's failure, with the agent's path in it instead of this machine's. */
+async function guard(at, work) {
+    try {
+        return await work();
+    }
+    catch (err) {
+        const e = err;
+        throw e?.code ? fsError(e.code, e.syscall ?? 'fs', at) : err;
+    }
+}
+//# sourceMappingURL=rooted-fs.js.map

package/dist/testing.js

@@ -52,8 +52,6 @@ export function describeFsDriver(name, make) {
                 code: 'ENOENT',
                 path: expect.stringContaining('ghost.txt'),
             });
-            expect(() => fs.realpathSync(at('ghost', 'deeper'))).toThrow(expect.objectContaining({ code: 'ENOENT' }));
-            expect(fs.realpathSync(at())).toBe(fs.realpathSync(at('.')));
         }));
     });
 }
@@ -81,13 +79,12 @@ export function describeSandbox(name, make, opts = {}) {
             expect((await sandbox.exec('exit 3')).exit_code).toBe(3);
             expect(sandbox.started).toBe(true);
         }), timeout);
-        it('shows a command the files `fs` wrote, and `fs` the files a command wrote', withSandbox(async ({ sandbox, root }) => {
-            const view = sandbox.files({ root, mount: WORKSPACE_MOUNT });
-            const fs = view.fs;
-            await fs.writeFile(fs.path.join(view.root, 'from-fs.txt'), 'written by fs\n');
+        it('shows a command the files `fs` wrote, and `fs` the files a command wrote', withSandbox(async ({ sandbox }) => {
+            const fs = sandbox.fs;
+            await fs.writeFile(`${WORKSPACE_MOUNT}/from-fs.txt`, 'written by fs\n');
             expect((await sandbox.exec('cat from-fs.txt')).stdout).toBe('written by fs\n');
             await sandbox.exec('mkdir -p out && printf "by exec" > out/from-exec.txt');
-            const back = await fs.readFile(fs.path.join(view.root, 'out', 'from-exec.txt'));
+            const back = await fs.readFile(`${WORKSPACE_MOUNT}/out/from-exec.txt`);
             expect(back.toString()).toBe('by exec');
         }), timeout);
         it('keeps a job running past the call that started it, and stops it', withSandbox(async ({ sandbox }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/sandbox",
-    "version": "1.1.57",
+    "version": "1.1.59",
     "description": "Where an agent's commands run and the files they see: the Sandbox contract, a podman implementation, filesystem drivers and a contract test suite for other implementations.",
     "keywords": [
         "sandbox",