@zenera/sandbox 0.0.0-stage → 1.1.56

package/dist/process.js

@@ -0,0 +1,122 @@
+import { spawn } from 'node:child_process';
+import { SandboxError } from "./contract.js";
+/** One command's output is capped, so a `cat` of a log file cannot fill the context. */
+const MAX_OUTPUT = 64 * 1024;
+/** Nothing runs longer than this, whatever it asked for. */
+export const MAX_TIMEOUT_MS = 3_600_000;
+export const runProcess = (bin, args, opts = {}) => new Promise((settle, fail) => {
+    const max = opts.maxBytes ?? MAX_OUTPUT;
+    const out = [];
+    const err = [];
+    let outSize = 0;
+    let errSize = 0;
+    let truncated = false;
+    let timedOut = false;
+    let done = false;
+    const child = spawn(bin, [...args], { shell: false, stdio: ['pipe', 'pipe', 'pipe'] });
+    const keep = (into, size, chunk) => {
+        const room = max - size;
+        if (room <= 0) {
+            truncated = true;
+            return size;
+        }
+        if (chunk.length > room) {
+            truncated = true;
+            into.push(chunk.subarray(0, room));
+            return max;
+        }
+        into.push(chunk);
+        return size + chunk.length;
+    };
+    child.stdout.on('data', (c) => (outSize = keep(out, outSize, c)));
+    child.stderr.on('data', (c) => (errSize = keep(err, errSize, c)));
+    // SIGTERM first so a well-behaved process can flush; SIGKILL after, so
+    // one that ignores it cannot hold the turn open forever.
+    let hard;
+    const stop = () => {
+        child.kill('SIGTERM');
+        hard = setTimeout(() => child.kill('SIGKILL'), 2000);
+        hard.unref();
+    };
+    const timer = opts.timeoutMs
+        ? setTimeout(() => {
+            timedOut = true;
+            stop();
+        }, Math.min(opts.timeoutMs, MAX_TIMEOUT_MS))
+        : undefined;
+    const onAbort = () => stop();
+    opts.signal?.addEventListener('abort', onAbort, { once: true });
+    const finish = (fn) => {
+        if (done) {
+            return;
+        }
+        done = true;
+        clearTimeout(timer);
+        clearTimeout(hard);
+        opts.signal?.removeEventListener('abort', onAbort);
+        fn();
+    };
+    child.on('error', (e) => {
+        finish(() => fail(e.code === 'ENOENT'
+            ? new SandboxError(`${bin} is not installed, or not on PATH`)
+            : e));
+    });
+    child.on('close', (code) => {
+        finish(() => settle({
+            code: code ?? (timedOut ? 124 : 1),
+            stdout: Buffer.concat(out).toString('utf8'),
+            stderr: Buffer.concat(err).toString('utf8'),
+            truncated,
+            timedOut,
+        }));
+    });
+    if (opts.input !== undefined) {
+        child.stdin.on('error', () => {
+            // A command that exits before reading its script closes the
+            // pipe under us. That is the command's answer, not an error.
+        });
+        child.stdin.end(opts.input);
+    }
+    else {
+        child.stdin.end();
+    }
+});
+// ---------------------------------------------------------------------------
+// Reaching the engine at all
+//
+// On macOS and Windows the client is remote: unless it has been pointed at the
+// machine's forwarded endpoint, every invocation opens its own ssh connection
+// into the virtual machine, and sshd refuses new ones past `MaxStartups` — ten
+// by default, with a random drop above that. A wide batch therefore loses
+// calls for a reason that has nothing to do with the command, on a different
+// task each time.
+//
+// A refused connection is the one failure that can be retried without asking
+// what the command was: it happened before authentication, so nothing ran.
+// ---------------------------------------------------------------------------
+const TRANSPORT = /kex_exchange_identification|ssh: handshake failed|ssh: unexpected packet|connection closed by remote host|connection reset by peer|connection refused/i;
+const ATTEMPTS = 4;
+/**
+ * `run`, retried while the engine could not be reached at all.
+ *
+ * Empty stdout is the guard that keeps this from retrying real work: a command
+ * that produced output ran, whatever its stderr says afterwards. The wait is
+ * jittered because the burst being backed off from is N clients arriving
+ * together, and a fixed delay would only reassemble it.
+ */
+export function resilient(run, attempts = ATTEMPTS) {
+    return async (bin, args, opts = {}) => {
+        for (let n = 1;; n++) {
+            const res = await run(bin, args, opts);
+            if (n >= attempts ||
+                res.code === 0 ||
+                res.stdout !== '' ||
+                opts.signal?.aborted ||
+                !TRANSPORT.test(res.stderr)) {
+                return res;
+            }
+            await new Promise((go) => setTimeout(go, 2 ** n * 50 + Math.random() * 100));
+        }
+    };
+}
+//# sourceMappingURL=process.js.map

package/dist/testing.d.ts

@@ -0,0 +1,25 @@
+import { type Sandbox } from './contract.ts';
+import type { FsDriver } from './fs.ts';
+export interface FsUnderTest {
+    fs: FsDriver;
+    /** an existing, empty directory the suite may write under */
+    root: string;
+    cleanup?: () => void | Promise<void>;
+}
+/** What `FsDriver` promises, down to the error codes the file tools rely on. */
+export declare function describeFsDriver(name: string, make: () => FsUnderTest | Promise<FsUnderTest>): void;
+export interface SandboxUnderTest {
+    sandbox: Sandbox;
+    /** the workspace the sandbox was opened with, in the host's terms */
+    root: string;
+    cleanup?: () => void | Promise<void>;
+}
+/**
+ * What `Sandbox` promises: commands run, jobs outlive the call that started
+ * them, and — the invariant — a file written through `fs` is the file `exec`
+ * sees, and the reverse. Needs a real shell, so for podman it is a live test.
+ */
+export declare function describeSandbox(name: string, make: () => SandboxUnderTest | Promise<SandboxUnderTest>, opts?: {
+    timeout?: number;
+}): void;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.js

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest';
+import { SandboxError } from "./contract.js";
+import { WORKSPACE_MOUNT } from "./mounts.js";
+/** What `FsDriver` promises, down to the error codes the file tools rely on. */
+export function describeFsDriver(name, make) {
+    describe(`FsDriver contract: ${name}`, () => {
+        const withFs = (fn) => async () => {
+            const t = await make();
+            try {
+                await fn(t, (...p) => t.fs.path.join(t.root, ...p));
+            }
+            finally {
+                await t.cleanup?.();
+            }
+        };
+        it('writes, reads and stats a file under directories it makes', withFs(async ({ fs }, at) => {
+            await fs.mkdirp(at('a', 'b'));
+            await fs.writeFile(at('a', 'b', 'c.txt'), 'hello\n');
+            expect((await fs.readFile(at('a', 'b', 'c.txt'))).toString()).toBe('hello\n');
+            expect((await fs.readHead(at('a', 'b', 'c.txt'), 4)).toString()).toBe('hell');
+            const info = await fs.stat(at('a', 'b', 'c.txt'));
+            expect(info.isFile()).toBe(true);
+            expect(info.isDirectory()).toBe(false);
+            expect(info.size).toBe(6);
+            expect((await fs.stat(at('a'))).isDirectory()).toBe(true);
+            await fs.mkdirp(at('a', 'b'));
+        }));
+        it('lists a directory with each entry’s kind', withFs(async ({ fs }, at) => {
+            await fs.mkdirp(at('d', 'sub'));
+            await fs.writeFile(at('d', 'f.txt'), 'x');
+            const entries = await fs.readdir(at('d'));
+            const kinds = Object.fromEntries(entries.map((e) => [
+                e.name,
+                e.isDirectory() ? 'dir' : e.isFile() ? 'file' : '?',
+            ]));
+            expect(kinds).toEqual({ sub: 'dir', 'f.txt': 'file' });
+        }));
+        it('moves, copies and removes, recursively when asked', withFs(async ({ fs }, at) => {
+            await fs.mkdirp(at('src', 'deep'));
+            await fs.writeFile(at('src', 'deep', 'f.txt'), 'one');
+            await fs.copy(at('src'), at('copy'), { recursive: true });
+            expect((await fs.readFile(at('copy', 'deep', 'f.txt'))).toString()).toBe('one');
+            await fs.rename(at('copy'), at('moved'));
+            await expect(fs.stat(at('copy'))).rejects.toMatchObject({ code: 'ENOENT' });
+            expect((await fs.readFile(at('moved', 'deep', 'f.txt'))).toString()).toBe('one');
+            await fs.rm(at('moved'), { recursive: true });
+            await expect(fs.stat(at('moved'))).rejects.toMatchObject({ code: 'ENOENT' });
+            await fs.rm(at('moved'), { force: true });
+        }));
+        it('fails with the code and path the file tools translate', withFs(async ({ fs }, at) => {
+            await expect(fs.readFile(at('ghost.txt'))).rejects.toMatchObject({
+                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('.')));
+        }));
+    });
+}
+/**
+ * What `Sandbox` promises: commands run, jobs outlive the call that started
+ * them, and — the invariant — a file written through `fs` is the file `exec`
+ * sees, and the reverse. Needs a real shell, so for podman it is a live test.
+ */
+export function describeSandbox(name, make, opts = {}) {
+    const timeout = opts.timeout ?? 120_000;
+    describe(`Sandbox contract: ${name}`, () => {
+        const withSandbox = (fn) => async () => {
+            const t = await make();
+            try {
+                await fn(t);
+            }
+            finally {
+                await t.sandbox.close();
+                await t.cleanup?.();
+            }
+        };
+        it('runs a command, and reports its exit code and output', withSandbox(async ({ sandbox }) => {
+            const ok = await sandbox.exec('echo out; echo err >&2');
+            expect(ok).toMatchObject({ exit_code: 0, stdout: 'out\n', stderr: 'err\n' });
+            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');
+            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'));
+            expect(back.toString()).toBe('by exec');
+        }), timeout);
+        it('keeps a job running past the call that started it, and stops it', withSandbox(async ({ sandbox }) => {
+            const id = await sandbox.startJob('echo started; sleep 30');
+            let out = await sandbox.readJob(id);
+            for (let i = 0; i < 20 && !out.output.includes('started'); i++) {
+                await new Promise((r) => setTimeout(r, 250));
+                out = await sandbox.readJob(id);
+            }
+            expect(out).toMatchObject({ job_id: id, running: true });
+            expect(out.output).toContain('started');
+            expect(await sandbox.stopJob(id)).toMatchObject({ job_id: id, stopped: true });
+            await expect(sandbox.readJob('job-unknown')).rejects.toBeInstanceOf(SandboxError);
+        }), timeout);
+        it('is free to close, and closes once', withSandbox(async ({ sandbox }) => {
+            await sandbox.exec('true');
+            await sandbox.close();
+            expect(sandbox.started).toBe(false);
+        }), timeout);
+    });
+}
+//# sourceMappingURL=testing.js.map

package/package.json

@@ -1,6 +1,59 @@
 {
-  "name": "@zenera/sandbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@zenera/sandbox",
+    "version": "1.1.56",
+    "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",
+        "container",
+        "podman",
+        "ai-agents",
+        "agent-runtime"
+    ],
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "author": "Andrey Ryabov",
+    "homepage": "https://github.com/zenera-ai/ZeneraNeo#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/zenera-ai/ZeneraNeo.git",
+        "directory": "packages/sandbox"
+    },
+    "bugs": "https://github.com/zenera-ai/ZeneraNeo/issues",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./testing": {
+            "types": "./dist/testing.d.ts",
+            "default": "./dist/testing.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "!dist/**/*.map"
+    ],
+    "engines": {
+        "node": ">=24"
+    },
+    "scripts": {
+        "build": "tsc -b",
+        "clean": "tsc -b --clean && rm -rf dist",
+        "prepack": "tsc -b"
+    },
+    "peerDependencies": {
+        "vitest": ">=3"
+    },
+    "peerDependenciesMeta": {
+        "vitest": {
+            "optional": true
+        }
+    }
+}