@fabric-harness/sdk 0.1.0

package/dist/sandbox.js

@@ -0,0 +1,922 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+/**
+ * Wrap a provider-owned remote sandbox client in Fabric's SandboxEnv contract.
+ * Provider credentials and SDK objects remain outside model context/history;
+ * Fabric only sees the narrow file/shell/snapshot API exposed here.
+ */
+export function createRemoteSandboxEnv(api, options = {}) {
+    return new RemoteSandboxEnv(api, options);
+}
+class RemoteSandboxEnv {
+    api;
+    options;
+    cwd;
+    capabilities;
+    constructor(api, options) {
+        this.api = api;
+        this.options = options;
+        this.cwd = normalizeRemotePath(options.cwd ?? '/workspace');
+        this.capabilities = options.capabilities ?? {
+            exec: true,
+            filesystem: true,
+            binaryFiles: true,
+            snapshots: typeof api.snapshot === 'function',
+            restore: typeof api.restore === 'function',
+            network: 'provider-managed',
+            persistence: 'session',
+            isolation: 'provider',
+        };
+    }
+    exec(command, options = {}) {
+        const execOptions = { ...options };
+        execOptions.cwd = options.cwd ? this.resolvePath(options.cwd) : this.cwd;
+        return this.api.exec(command, execOptions);
+    }
+    readFile(filePath) { return this.api.readFile(this.resolvePath(filePath)); }
+    readFileBuffer(filePath) { return this.api.readFileBuffer(this.resolvePath(filePath)); }
+    writeFile(filePath, content) { return this.api.writeFile(this.resolvePath(filePath), content); }
+    stat(filePath) { return this.api.stat(this.resolvePath(filePath)); }
+    readdir(dirPath) { return this.api.readdir(this.resolvePath(dirPath)); }
+    exists(filePath) { return this.api.exists(this.resolvePath(filePath)); }
+    mkdir(dirPath, options = {}) { return this.api.mkdir(this.resolvePath(dirPath), options); }
+    rm(filePath, options = {}) { return this.api.rm(this.resolvePath(filePath), options); }
+    resolvePath(filePath) {
+        const resolved = filePath.startsWith('/')
+            ? normalizeRemotePath(filePath)
+            : normalizeRemotePath(path.posix.join(this.cwd, filePath));
+        if (resolved !== this.cwd && !resolved.startsWith(`${this.cwd}/`)) {
+            throw new Error(`Path escapes remote sandbox workspace: ${filePath}`);
+        }
+        return resolved;
+    }
+    async snapshot() {
+        if (!this.api.snapshot)
+            throw new Error('Remote sandbox does not support snapshots.');
+        return this.api.snapshot();
+    }
+    async restore(snapshot) {
+        if (!this.api.restore)
+            throw new Error('Remote sandbox does not support restore.');
+        await this.api.restore(snapshot);
+    }
+    async cleanup() {
+        const cleanup = this.options.cleanup;
+        if (!cleanup)
+            return;
+        if (typeof cleanup === 'function')
+            await cleanup();
+        else
+            await cleanup.cleanup();
+    }
+}
+function normalizeRemotePath(value) {
+    const normalized = path.posix.resolve('/', value);
+    return normalized === '/' ? '/' : normalized.replace(/\/+$/u, '');
+}
+function fileStatFromNode(node) {
+    const stat = {
+        type: node.type,
+        size: node.type === 'file' ? node.content.byteLength : 0,
+    };
+    if (node.mtime !== undefined) {
+        stat.mtime = node.mtime;
+    }
+    if (node.mode !== undefined) {
+        stat.mode = node.mode;
+    }
+    return stat;
+}
+function fileStatFromFs(stats) {
+    const type = stats.isFile()
+        ? 'file'
+        : stats.isDirectory()
+            ? 'directory'
+            : stats.isSymbolicLink()
+                ? 'symlink'
+                : 'other';
+    return {
+        type,
+        size: Number(stats.size),
+        mtime: stats.mtime,
+        mode: Number(stats.mode),
+    };
+}
+function cloneEntries(entries) {
+    const clone = new Map();
+    for (const [entryPath, entry] of entries) {
+        clone.set(entryPath, entry.type === 'file'
+            ? { ...entry, content: new Uint8Array(entry.content) }
+            : { ...entry });
+    }
+    return clone;
+}
+export class EmptySandboxEnv {
+    cwd;
+    capabilities = { exec: false, filesystem: true, binaryFiles: true, snapshots: true, restore: true, network: 'none', persistence: 'ephemeral', isolation: 'process' };
+    entries = new Map();
+    snapshots = new Map();
+    nextSnapshotId = 0;
+    constructor(cwd = '/workspace') {
+        this.cwd = path.posix.resolve('/', cwd);
+        this.entries.set(this.cwd, { type: 'directory', mtime: new Date() });
+    }
+    async exec(command) {
+        return {
+            command,
+            exitCode: 127,
+            stdout: '',
+            stderr: 'Empty sandbox does not support shell execution.',
+        };
+    }
+    async readFile(filePath) {
+        return new TextDecoder().decode(await this.readFileBuffer(filePath));
+    }
+    async readFileBuffer(filePath) {
+        const entry = this.entries.get(this.resolvePath(filePath));
+        if (!entry || entry.type !== 'file') {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        return new Uint8Array(entry.content);
+    }
+    async writeFile(filePath, content) {
+        const resolved = this.resolvePath(filePath);
+        const parent = path.posix.dirname(resolved);
+        if (!(await this.exists(parent))) {
+            await this.mkdir(parent, { recursive: true });
+        }
+        const bytes = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+        this.entries.set(resolved, {
+            type: 'file',
+            content: new Uint8Array(bytes),
+            mtime: new Date(),
+        });
+    }
+    async stat(filePath) {
+        const entry = this.entries.get(this.resolvePath(filePath));
+        if (!entry) {
+            throw new Error(`Path not found: ${filePath}`);
+        }
+        return fileStatFromNode(entry);
+    }
+    async readdir(dirPath) {
+        const resolved = this.resolvePath(dirPath);
+        const entry = this.entries.get(resolved);
+        if (!entry || entry.type !== 'directory') {
+            throw new Error(`Directory not found: ${dirPath}`);
+        }
+        const names = new Set();
+        const prefix = resolved.endsWith('/') ? resolved : `${resolved}/`;
+        for (const entryPath of this.entries.keys()) {
+            if (!entryPath.startsWith(prefix) || entryPath === resolved) {
+                continue;
+            }
+            const remainder = entryPath.slice(prefix.length);
+            const [name] = remainder.split('/');
+            if (name) {
+                names.add(name);
+            }
+        }
+        return [...names].sort();
+    }
+    async exists(filePath) {
+        return this.entries.has(this.resolvePath(filePath));
+    }
+    async mkdir(dirPath, options = {}) {
+        const resolved = this.resolvePath(dirPath);
+        const segments = resolved.split('/').filter(Boolean);
+        let current = '';
+        for (const segment of segments) {
+            current = `${current}/${segment}`;
+            const entry = this.entries.get(current);
+            if (entry?.type === 'file') {
+                throw new Error(`Cannot create directory over file: ${current}`);
+            }
+            if (!entry) {
+                if (!options.recursive && current !== resolved) {
+                    throw new Error(`Parent directory does not exist: ${path.posix.dirname(resolved)}`);
+                }
+                this.entries.set(current, { type: 'directory', mtime: new Date() });
+            }
+        }
+    }
+    async rm(filePath, options = {}) {
+        const resolved = this.resolvePath(filePath);
+        const entry = this.entries.get(resolved);
+        if (!entry) {
+            if (options.force) {
+                return;
+            }
+            throw new Error(`Path not found: ${filePath}`);
+        }
+        if (entry.type === 'directory') {
+            const prefix = resolved.endsWith('/') ? resolved : `${resolved}/`;
+            const children = [...this.entries.keys()].filter((entryPath) => entryPath.startsWith(prefix));
+            if (children.length > 0 && !options.recursive) {
+                throw new Error(`Directory is not empty: ${filePath}`);
+            }
+            for (const child of children) {
+                this.entries.delete(child);
+            }
+        }
+        if (resolved !== this.cwd) {
+            this.entries.delete(resolved);
+        }
+    }
+    resolvePath(filePath) {
+        const resolved = filePath.startsWith('/')
+            ? path.posix.resolve(filePath)
+            : path.posix.resolve(this.cwd, filePath);
+        if (resolved !== this.cwd && !resolved.startsWith(`${this.cwd}/`)) {
+            throw new Error(`Path escapes sandbox workspace: ${filePath}`);
+        }
+        return resolved;
+    }
+    async snapshot() {
+        const id = `empty-snapshot-${++this.nextSnapshotId}`;
+        this.snapshots.set(id, cloneEntries(this.entries));
+        return { id };
+    }
+    async restore(snapshot) {
+        const entries = this.snapshots.get(snapshot.id);
+        if (!entries) {
+            throw new Error(`Snapshot not found: ${snapshot.id}`);
+        }
+        this.entries = cloneEntries(entries);
+    }
+    async cleanup() {
+        this.snapshots.clear();
+    }
+}
+export class LocalSandboxEnv {
+    cwd;
+    capabilities = { exec: true, filesystem: true, binaryFiles: true, snapshots: true, restore: true, network: 'egress', persistence: 'durable', isolation: 'process' };
+    env;
+    snapshotRoot;
+    outputLimitBytes;
+    defaultTimeoutMs;
+    constructor(options = {}) {
+        this.cwd = path.resolve(options.workspacePath ?? process.cwd());
+        this.env = {
+            ...(options.inheritSafeEnv === false ? {} : safeHostEnv()),
+            ...envFromAllowlist(options.envAllowlist),
+            ...(options.env ?? {}),
+        };
+        this.outputLimitBytes = options.outputLimitBytes ?? 1024 * 1024;
+        if (options.defaultTimeoutMs !== undefined)
+            this.defaultTimeoutMs = options.defaultTimeoutMs;
+        this.snapshotRoot = path.resolve(options.snapshotRoot ?? path.join(this.cwd, '.fabricharness', 'checkpoints', sanitizeId(options.sessionId ?? 'local')));
+    }
+    async exec(command, options = {}) {
+        const startedAt = Date.now();
+        const cwd = options.cwd ? await this.resolveExistingPath(options.cwd) : this.cwd;
+        const childEnv = { ...this.env, ...options.env };
+        return new Promise((resolve) => {
+            const child = spawn(command, {
+                cwd,
+                env: childEnv,
+                shell: true,
+                windowsHide: true,
+            });
+            let stdout = '';
+            let stderr = '';
+            let timedOut = false;
+            let aborted = false;
+            const abort = () => {
+                aborted = true;
+                child.kill('SIGTERM');
+            };
+            if (options.signal?.aborted)
+                abort();
+            else
+                options.signal?.addEventListener('abort', abort, { once: true });
+            const effectiveTimeout = options.timeout ?? this.defaultTimeoutMs;
+            const timeout = effectiveTimeout
+                ? setTimeout(() => {
+                    timedOut = true;
+                    child.kill('SIGTERM');
+                }, effectiveTimeout)
+                : undefined;
+            child.stdout?.setEncoding('utf8');
+            child.stderr?.setEncoding('utf8');
+            child.stdout?.on('data', (chunk) => {
+                stdout = appendLimited(stdout, chunk, this.outputLimitBytes);
+            });
+            child.stderr?.on('data', (chunk) => {
+                stderr = appendLimited(stderr, chunk, this.outputLimitBytes);
+            });
+            child.on('error', (error) => {
+                if (timeout) {
+                    clearTimeout(timeout);
+                }
+                options.signal?.removeEventListener('abort', abort);
+                resolve({
+                    command,
+                    exitCode: aborted ? 130 : 1,
+                    stdout,
+                    stderr: aborted ? `${stderr}Command aborted.\n` : `${stderr}${error.message}`,
+                    durationMs: Date.now() - startedAt,
+                });
+            });
+            child.on('close', (code, signal) => {
+                if (timeout) {
+                    clearTimeout(timeout);
+                }
+                options.signal?.removeEventListener('abort', abort);
+                resolve({
+                    command,
+                    exitCode: aborted ? 130 : timedOut ? 124 : (code ?? 1),
+                    stdout,
+                    stderr: aborted ? `${stderr}Command aborted.\n` : timedOut ? `${stderr}Command timed out and was terminated.\n` : stderr,
+                    durationMs: Date.now() - startedAt,
+                    ...(signal ? { signal } : {}),
+                });
+            });
+        });
+    }
+    async readFile(filePath) {
+        return fs.readFile(await this.resolveExistingPath(filePath), 'utf8');
+    }
+    async readFileBuffer(filePath) {
+        return fs.readFile(await this.resolveExistingPath(filePath));
+    }
+    async writeFile(filePath, content) {
+        const resolved = await this.resolveWritablePath(filePath);
+        await fs.mkdir(path.dirname(resolved), { recursive: true });
+        await fs.writeFile(resolved, content);
+    }
+    async stat(filePath) {
+        return fileStatFromFs(await fs.stat(await this.resolveExistingPath(filePath)));
+    }
+    async readdir(dirPath) {
+        return fs.readdir(await this.resolveExistingPath(dirPath));
+    }
+    async exists(filePath) {
+        try {
+            await fs.access(await this.resolveExistingPath(filePath));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async mkdir(dirPath, options = {}) {
+        await fs.mkdir(await this.resolveWritablePath(dirPath), { recursive: options.recursive });
+    }
+    async rm(filePath, options = {}) {
+        await fs.rm(await this.resolveExistingPath(filePath), options);
+    }
+    resolvePath(filePath) {
+        const resolved = path.resolve(this.cwd, filePath);
+        this.assertInsideWorkspace(resolved, filePath);
+        return resolved;
+    }
+    async resolveExistingPath(filePath) {
+        const resolved = this.resolvePath(filePath);
+        const real = await fs.realpath(resolved);
+        this.assertInsideWorkspace(real, filePath);
+        return real;
+    }
+    async resolveWritablePath(filePath) {
+        const resolved = this.resolvePath(filePath);
+        try {
+            const real = await fs.realpath(resolved);
+            this.assertInsideWorkspace(real, filePath);
+            return real;
+        }
+        catch {
+            const parentReal = await fs.realpath(await this.nearestExistingParent(path.dirname(resolved)));
+            this.assertInsideWorkspace(parentReal, filePath);
+            return resolved;
+        }
+    }
+    async nearestExistingParent(dirPath) {
+        let current = dirPath;
+        while (current !== path.dirname(current)) {
+            try {
+                const stats = await fs.stat(current);
+                if (stats.isDirectory())
+                    return current;
+            }
+            catch {
+                // keep walking toward the workspace root
+            }
+            current = path.dirname(current);
+        }
+        return this.cwd;
+    }
+    assertInsideWorkspace(resolved, original) {
+        if (resolved !== this.cwd && !resolved.startsWith(`${this.cwd}${path.sep}`)) {
+            throw new Error(`Path escapes sandbox workspace: ${original}`);
+        }
+    }
+    async snapshot() {
+        return snapshotWorkspace(this.cwd, this.snapshotRoot, 'local');
+    }
+    async restore(snapshot) {
+        await restoreWorkspace(this.cwd, this.snapshotRoot, snapshot);
+    }
+    async cleanup() {
+        // Local sandbox does not own the workspace directory or checkpoint store.
+    }
+}
+export class DockerSandboxEnv {
+    cwd = '/workspace';
+    capabilities = { exec: true, filesystem: true, binaryFiles: true, snapshots: true, restore: true, network: 'restricted', persistence: 'session', isolation: 'container' };
+    hostWorkspacePath;
+    image;
+    env;
+    network;
+    user;
+    cpus;
+    memory;
+    pidsLimit;
+    readOnlyRootFilesystem;
+    mountReadOnly;
+    outputLimitBytes;
+    ownsWorkspace;
+    snapshotRoot;
+    constructor(options) {
+        this.hostWorkspacePath = path.resolve(options.workspacePath);
+        this.image = options.image ?? 'node:22-alpine';
+        this.env = { ...envFromAllowlist(options.envAllowlist), ...(options.env ?? {}) };
+        this.network = normalizeDockerNetwork(options.network);
+        if (options.user !== undefined)
+            this.user = options.user;
+        if (options.cpus !== undefined)
+            this.cpus = options.cpus;
+        if (options.memory !== undefined)
+            this.memory = options.memory;
+        if (options.pidsLimit !== undefined)
+            this.pidsLimit = options.pidsLimit;
+        this.readOnlyRootFilesystem = options.readOnlyRootFilesystem ?? true;
+        this.mountReadOnly = options.mountReadOnly ?? false;
+        this.outputLimitBytes = options.outputLimitBytes ?? 1024 * 1024;
+        this.ownsWorkspace = options.ownsWorkspace ?? false;
+        this.snapshotRoot = path.resolve(options.snapshotRoot ?? path.join(this.hostWorkspacePath, '.fabricharness', 'checkpoints', sanitizeId(options.sessionId ?? 'docker')));
+    }
+    async exec(command, options = {}) {
+        await fs.mkdir(this.hostWorkspacePath, { recursive: true });
+        const startedAt = Date.now();
+        const containerName = `fabric-harness-${randomUUID()}`;
+        const cwd = options.cwd ? this.toContainerPath(options.cwd) : this.cwd;
+        const args = [
+            'run',
+            '--rm',
+            '--name',
+            containerName,
+            '--network',
+            this.network,
+            '-v',
+            `${this.hostWorkspacePath}:${this.cwd}${this.mountReadOnly ? ':ro' : ''}`,
+            '-w',
+            cwd,
+        ];
+        if (this.user)
+            args.push('-u', this.user);
+        if (this.cpus !== undefined)
+            args.push('--cpus', String(this.cpus));
+        if (this.memory !== undefined)
+            args.push('--memory', this.memory);
+        if (this.pidsLimit !== undefined)
+            args.push('--pids-limit', String(this.pidsLimit));
+        if (this.readOnlyRootFilesystem)
+            args.push('--read-only', '--tmpfs', '/tmp:rw,noexec,nosuid,size=64m');
+        for (const [key, value] of Object.entries({ ...this.env, ...options.env }))
+            args.push('-e', `${key}=${value}`);
+        args.push(this.image, 'sh', '-lc', command);
+        return new Promise((resolve) => {
+            const child = spawn('docker', args, { windowsHide: true });
+            let stdout = '';
+            let stderr = '';
+            let timedOut = false;
+            let aborted = false;
+            const abort = () => {
+                aborted = true;
+                child.kill('SIGTERM');
+                void runDocker(['rm', '-f', containerName]);
+            };
+            if (options.signal?.aborted)
+                abort();
+            else
+                options.signal?.addEventListener('abort', abort, { once: true });
+            const timeout = options.timeout
+                ? setTimeout(() => {
+                    timedOut = true;
+                    child.kill('SIGTERM');
+                    void runDocker(['rm', '-f', containerName]);
+                }, options.timeout)
+                : undefined;
+            child.stdout?.setEncoding('utf8');
+            child.stderr?.setEncoding('utf8');
+            child.stdout?.on('data', (chunk) => { stdout = appendLimited(stdout, chunk, this.outputLimitBytes); });
+            child.stderr?.on('data', (chunk) => { stderr = appendLimited(stderr, chunk, this.outputLimitBytes); });
+            child.on('error', (error) => {
+                if (timeout)
+                    clearTimeout(timeout);
+                options.signal?.removeEventListener('abort', abort);
+                resolve({ command, exitCode: aborted ? 130 : 1, stdout, stderr: aborted ? `${stderr}Command aborted.\n` : `${stderr}${error.message}`, durationMs: Date.now() - startedAt });
+            });
+            child.on('close', (code, signal) => {
+                if (timeout)
+                    clearTimeout(timeout);
+                options.signal?.removeEventListener('abort', abort);
+                resolve({
+                    command,
+                    exitCode: aborted ? 130 : timedOut ? 124 : (code ?? 1),
+                    stdout,
+                    stderr: aborted ? `${stderr}Command aborted.\n` : timedOut ? `${stderr}Command timed out and container was terminated.\n` : stderr,
+                    durationMs: Date.now() - startedAt,
+                    ...(signal ? { signal } : {}),
+                });
+            });
+        });
+    }
+    async readFile(filePath) {
+        return fs.readFile(this.resolvePath(filePath), 'utf8');
+    }
+    async readFileBuffer(filePath) {
+        return fs.readFile(this.resolvePath(filePath));
+    }
+    async writeFile(filePath, content) {
+        const resolved = this.resolvePath(filePath);
+        await fs.mkdir(path.dirname(resolved), { recursive: true });
+        await fs.writeFile(resolved, content);
+    }
+    async stat(filePath) {
+        return fileStatFromFs(await fs.stat(this.resolvePath(filePath)));
+    }
+    async readdir(dirPath) {
+        return fs.readdir(this.resolvePath(dirPath));
+    }
+    async exists(filePath) {
+        try {
+            await fs.access(this.resolvePath(filePath));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async mkdir(dirPath, options = {}) {
+        await fs.mkdir(this.resolvePath(dirPath), { recursive: options.recursive });
+    }
+    async rm(filePath, options = {}) {
+        await fs.rm(this.resolvePath(filePath), options);
+    }
+    resolvePath(filePath) {
+        const relative = this.toWorkspaceRelativePath(filePath);
+        const resolved = path.resolve(this.hostWorkspacePath, relative);
+        if (resolved !== this.hostWorkspacePath && !resolved.startsWith(`${this.hostWorkspacePath}${path.sep}`)) {
+            throw new Error(`Path escapes sandbox workspace: ${filePath}`);
+        }
+        return resolved;
+    }
+    async snapshot() {
+        return snapshotWorkspace(this.hostWorkspacePath, this.snapshotRoot, 'docker');
+    }
+    async restore(snapshot) {
+        await restoreWorkspace(this.hostWorkspacePath, this.snapshotRoot, snapshot);
+    }
+    async cleanup() {
+        if (this.ownsWorkspace)
+            await fs.rm(this.hostWorkspacePath, { recursive: true, force: true });
+    }
+    toContainerPath(filePath) {
+        const relative = this.toWorkspaceRelativePath(filePath);
+        return relative ? path.posix.join(this.cwd, relative.split(path.sep).join('/')) : this.cwd;
+    }
+    toWorkspaceRelativePath(filePath) {
+        if (filePath.startsWith('/')) {
+            const resolved = path.posix.resolve(filePath);
+            if (resolved !== this.cwd && !resolved.startsWith(`${this.cwd}/`)) {
+                throw new Error(`Path escapes sandbox workspace: ${filePath}`);
+            }
+            return resolved.slice(this.cwd.length).replace(/^\//, '');
+        }
+        const resolved = path.posix.resolve(this.cwd, filePath);
+        if (resolved !== this.cwd && !resolved.startsWith(`${this.cwd}/`)) {
+            throw new Error(`Path escapes sandbox workspace: ${filePath}`);
+        }
+        return resolved.slice(this.cwd.length).replace(/^\//, '');
+    }
+}
+export async function pruneSnapshots(snapshotRoot, options = {}) {
+    if (!await fileExists(snapshotRoot))
+        return { removed: [], kept: [] };
+    const entries = await fs.readdir(snapshotRoot, { withFileTypes: true });
+    const snapshots = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const snapshotPath = path.join(snapshotRoot, entry.name);
+        const manifestPath = path.join(snapshotPath, 'manifest.json');
+        let createdAt = (await fs.stat(snapshotPath)).mtimeMs;
+        if (await fileExists(manifestPath)) {
+            try {
+                const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+                if (manifest.createdAt)
+                    createdAt = new Date(manifest.createdAt).getTime();
+            }
+            catch {
+                // Ignore malformed manifests during retention scanning; restore still validates integrity.
+            }
+        }
+        snapshots.push({ id: entry.name, path: snapshotPath, createdAt });
+    }
+    snapshots.sort((a, b) => b.createdAt - a.createdAt);
+    const keep = Math.max(0, options.keep ?? snapshots.length);
+    const cutoff = options.olderThanMs !== undefined ? Date.now() - options.olderThanMs : undefined;
+    const removed = [];
+    const kept = [];
+    for (const [index, snapshot] of snapshots.entries()) {
+        const removeByCount = index >= keep;
+        const removeByAge = cutoff !== undefined && snapshot.createdAt < cutoff;
+        if (removeByCount || removeByAge) {
+            await fs.rm(snapshot.path, { recursive: true, force: true });
+            removed.push(snapshot.id);
+        }
+        else {
+            kept.push(snapshot.id);
+        }
+    }
+    return { removed, kept };
+}
+async function snapshotWorkspace(workspaceRoot, snapshotRoot, backend) {
+    const id = `${backend}-snapshot-${Date.now()}-${randomUUID()}`;
+    const snapshotDir = path.join(snapshotRoot, id);
+    const filesDir = path.join(snapshotDir, 'files');
+    await fs.mkdir(filesDir, { recursive: true });
+    await copyDirectory(workspaceRoot, filesDir, { excludeRoots: [snapshotRoot] });
+    const files = await snapshotFileManifest(filesDir);
+    const manifest = {
+        schemaVersion: 1,
+        id,
+        backend,
+        workspaceRoot,
+        createdAt: new Date().toISOString(),
+        parent: null,
+        files,
+        totalBytes: files.reduce((sum, file) => sum + file.bytes, 0),
+    };
+    await fs.writeFile(path.join(snapshotDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+    return { id, metadata: { path: snapshotDir, backend } };
+}
+async function restoreWorkspace(workspaceRoot, snapshotRoot, snapshot) {
+    const snapshotDir = resolveSnapshotDir(snapshotRoot, snapshot);
+    const filesDir = path.join(snapshotDir, 'files');
+    const stat = await fs.stat(filesDir);
+    if (!stat.isDirectory())
+        throw new Error(`Snapshot files directory not found: ${snapshot.id}`);
+    await verifySnapshotIntegrity(snapshotDir, filesDir);
+    await fs.mkdir(workspaceRoot, { recursive: true });
+    await removeDirectoryContents(workspaceRoot, [snapshotRoot]);
+    await copyDirectory(filesDir, workspaceRoot);
+}
+async function verifySnapshotIntegrity(snapshotDir, filesDir) {
+    const manifestPath = path.join(snapshotDir, 'manifest.json');
+    if (!await fileExists(manifestPath))
+        return;
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    if (!Array.isArray(manifest.files))
+        return;
+    for (const file of manifest.files) {
+        const filePath = path.resolve(filesDir, file.path);
+        if (filePath !== filesDir && !filePath.startsWith(`${filesDir}${path.sep}`))
+            throw new Error(`Snapshot manifest path escapes files directory: ${file.path}`);
+        const stat = await fs.stat(filePath);
+        if (stat.size !== file.bytes)
+            throw new Error(`Snapshot file size mismatch: ${file.path}`);
+        const digest = await sha256File(filePath);
+        if (digest !== file.sha256)
+            throw new Error(`Snapshot file checksum mismatch: ${file.path}`);
+    }
+}
+async function snapshotFileManifest(root) {
+    const files = await listRegularFiles(root);
+    const manifest = [];
+    for (const file of files) {
+        const stat = await fs.stat(file);
+        manifest.push({ path: toPosix(path.relative(root, file)), bytes: stat.size, sha256: await sha256File(file) });
+    }
+    return manifest.sort((a, b) => a.path.localeCompare(b.path));
+}
+async function listRegularFiles(root) {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const entryPath = path.join(root, entry.name);
+        if (entry.isDirectory())
+            files.push(...await listRegularFiles(entryPath));
+        else if (entry.isFile())
+            files.push(entryPath);
+    }
+    return files;
+}
+async function sha256File(filePath) {
+    return createHash('sha256').update(await fs.readFile(filePath)).digest('hex');
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function toPosix(value) {
+    return value.split(path.sep).join('/');
+}
+function resolveSnapshotDir(snapshotRoot, snapshot) {
+    const metadataPath = typeof snapshot.metadata?.path === 'string' ? snapshot.metadata.path : undefined;
+    const candidate = path.resolve(metadataPath ?? path.join(snapshotRoot, snapshot.id));
+    const root = path.resolve(snapshotRoot);
+    if (candidate !== root && !candidate.startsWith(`${root}${path.sep}`)) {
+        throw new Error(`Snapshot path escapes snapshot root: ${snapshot.id}`);
+    }
+    return candidate;
+}
+async function copyDirectory(source, destination, options = {}) {
+    await fs.mkdir(destination, { recursive: true });
+    const entries = await fs.readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path.join(source, entry.name);
+        if (isExcludedPath(sourcePath, options.excludeRoots ?? []))
+            continue;
+        const destinationPath = path.join(destination, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirectory(sourcePath, destinationPath, options);
+            continue;
+        }
+        if (entry.isSymbolicLink()) {
+            const target = await fs.readlink(sourcePath);
+            await fs.symlink(target, destinationPath);
+            continue;
+        }
+        if (entry.isFile()) {
+            await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+            await fs.copyFile(sourcePath, destinationPath);
+        }
+    }
+}
+async function removeDirectoryContents(directory, excludeRoots = []) {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+        const entryPath = path.join(directory, entry.name);
+        if (isExcludedPath(entryPath, excludeRoots) || containsExcludedRoot(entryPath, excludeRoots))
+            continue;
+        await fs.rm(entryPath, { recursive: true, force: true });
+    }
+}
+function isExcludedPath(candidate, excludeRoots) {
+    const resolved = path.resolve(candidate);
+    return excludeRoots.some((root) => {
+        const excluded = path.resolve(root);
+        return resolved === excluded || resolved.startsWith(`${excluded}${path.sep}`);
+    });
+}
+function containsExcludedRoot(candidate, excludeRoots) {
+    const resolved = path.resolve(candidate);
+    return excludeRoots.some((root) => {
+        const excluded = path.resolve(root);
+        return excluded.startsWith(`${resolved}${path.sep}`);
+    });
+}
+function sanitizeId(value) {
+    return value.replace(/[^a-zA-Z0-9._:-]/g, '_');
+}
+function normalizeDockerNetwork(network) {
+    if (network === true)
+        return 'bridge';
+    if (network === false || network === undefined)
+        return 'none';
+    return network;
+}
+function envFromAllowlist(allowlist) {
+    if (!allowlist || allowlist.length === 0)
+        return {};
+    const env = {};
+    for (const key of allowlist) {
+        const value = process.env[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return env;
+}
+const SAFE_HOST_ENV_KEYS = [
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'HOSTNAME',
+    'SHELL',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TZ',
+    'TERM',
+    'TMPDIR',
+    'TMP',
+    'TEMP',
+];
+function safeHostEnv() {
+    return envFromAllowlist(SAFE_HOST_ENV_KEYS);
+}
+function appendLimited(current, chunk, limit) {
+    if (limit <= 0)
+        return '';
+    const next = `${current}${chunk}`;
+    if (Buffer.byteLength(next, 'utf8') <= limit)
+        return next;
+    const marker = '\n[output truncated by Fabric Harness]\n';
+    return `${next.slice(Math.max(0, next.length - limit + marker.length))}${marker}`;
+}
+function runDocker(args) {
+    return new Promise((resolve) => {
+        const child = spawn('docker', args, { stdio: 'ignore', windowsHide: true });
+        child.on('close', () => resolve());
+        child.on('error', () => resolve());
+    });
+}
+export class UnimplementedSandboxEnv extends EmptySandboxEnv {
+    async exec(command) {
+        return {
+            command,
+            exitCode: 127,
+            stdout: '',
+            stderr: 'Sandbox runtime not implemented yet.',
+        };
+    }
+}
+export async function createSandboxEnv(options = {}) {
+    const backend = options.backend ?? 'empty';
+    if (backend === 'empty') {
+        return new EmptySandboxEnv();
+    }
+    if (backend === 'local') {
+        const localOptions = {};
+        if (options.workspacePath !== undefined) {
+            localOptions.workspacePath = options.workspacePath;
+        }
+        if (options.env !== undefined) {
+            localOptions.env = options.env;
+        }
+        if (options.sessionId !== undefined) {
+            localOptions.sessionId = options.sessionId;
+        }
+        if (typeof options.metadata?.snapshotRoot === 'string') {
+            localOptions.snapshotRoot = options.metadata.snapshotRoot;
+        }
+        if (typeof options.metadata?.outputLimitBytes === 'number')
+            localOptions.outputLimitBytes = options.metadata.outputLimitBytes;
+        if (typeof options.metadata?.defaultTimeoutMs === 'number')
+            localOptions.defaultTimeoutMs = options.metadata.defaultTimeoutMs;
+        if (typeof options.metadata?.inheritSafeEnv === 'boolean')
+            localOptions.inheritSafeEnv = options.metadata.inheritSafeEnv;
+        if (Array.isArray(options.metadata?.envAllowlist))
+            localOptions.envAllowlist = options.metadata.envAllowlist.filter((value) => typeof value === 'string');
+        return new LocalSandboxEnv(localOptions);
+    }
+    if (backend === 'docker') {
+        const workspacePath = options.workspacePath ?? await fs.mkdtemp(path.join(tmpdir(), 'fabric-harness-docker-'));
+        const dockerOptions = {
+            workspacePath,
+            ownsWorkspace: options.workspacePath === undefined,
+        };
+        if (options.env !== undefined)
+            dockerOptions.env = options.env;
+        if (options.sessionId !== undefined)
+            dockerOptions.sessionId = options.sessionId;
+        if (typeof options.metadata?.snapshotRoot === 'string')
+            dockerOptions.snapshotRoot = options.metadata.snapshotRoot;
+        if (typeof options.metadata?.image === 'string')
+            dockerOptions.image = options.metadata.image;
+        if (typeof options.metadata?.dockerImage === 'string')
+            dockerOptions.image = options.metadata.dockerImage;
+        if (typeof options.metadata?.network === 'string' || typeof options.metadata?.network === 'boolean')
+            dockerOptions.network = options.metadata.network;
+        if (typeof options.metadata?.user === 'string')
+            dockerOptions.user = options.metadata.user;
+        if (typeof options.metadata?.cpus === 'string' || typeof options.metadata?.cpus === 'number')
+            dockerOptions.cpus = options.metadata.cpus;
+        if (typeof options.metadata?.memory === 'string')
+            dockerOptions.memory = options.metadata.memory;
+        if (typeof options.metadata?.pidsLimit === 'number')
+            dockerOptions.pidsLimit = options.metadata.pidsLimit;
+        if (typeof options.metadata?.readOnlyRootFilesystem === 'boolean')
+            dockerOptions.readOnlyRootFilesystem = options.metadata.readOnlyRootFilesystem;
+        if (typeof options.metadata?.mountReadOnly === 'boolean')
+            dockerOptions.mountReadOnly = options.metadata.mountReadOnly;
+        if (typeof options.metadata?.outputLimitBytes === 'number')
+            dockerOptions.outputLimitBytes = options.metadata.outputLimitBytes;
+        if (Array.isArray(options.metadata?.envAllowlist))
+            dockerOptions.envAllowlist = options.metadata.envAllowlist.filter((value) => typeof value === 'string');
+        return new DockerSandboxEnv(dockerOptions);
+    }
+    throw new Error(`Sandbox backend is not implemented yet: ${backend}`);
+}
+//# sourceMappingURL=sandbox.js.map