@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/agent/science/experiment-sandbox-backends.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AI-Scientist-lite — Phase 2 real-brick sandbox adapters.
+ *
+ * Thin adapters that BRANCH the existing `src/sandbox/*` backends (never modify
+ * them) and translate their result shape into the {@link ExecuteCodeResult}
+ * the orchestrator already understands. Loaded lazily by the router only when a
+ * containerised backend is actually selected AND available.
+ *
+ *   - {@link runInDocker} → `DockerSandbox` with `networkEnabled:false`, i.e.
+ *     `docker run --network none`. THE security property: the network is cut.
+ *     The docker executor is injectable so tests assert the isolation option
+ *     without a real Docker daemon.
+ *   - {@link runInE2b} → `E2BSandbox.runScript`, an off-host Firecracker microVM.
+ *     The `runScript` boundary is injectable so tests assert routing without a
+ *     real E2B account.
+ *
+ * @module agent/science/experiment-sandbox-backends
+ */
+import type { ExecuteCodeInput, ExecuteCodeLanguage, ExecuteCodeResult, ExecuteCodeRunnerOptions } from '../../tools/execute-code-runner.js';
+import type { SandboxConfig, SandboxResult } from '../../sandbox/docker-sandbox.js';
+import type { E2BSandboxResult } from '../../sandbox/e2b-sandbox.js';
+/** Injectable edges for {@link runInDocker} (real defaults resolved lazily). */
+export interface DockerBackendDeps {
+    /**
+     * The docker executor. Default: a fresh `DockerSandbox().execute`. Injected in
+     * tests to assert the isolation options (crucially `networkEnabled:false`).
+     */
+    dockerExecute?: (command: string, opts: Partial<SandboxConfig>) => Promise<SandboxResult>;
+    now?: () => Date;
+    createId?: () => string;
+}
+/**
+ * Run the experiment script inside a Docker container with the network CUT.
+ *
+ * The script is staged on the host under `<rootDir>/.codebuddy/execute-code/<id>`
+ * and bind-mounted at `/workspace`, so the container needs no network to obtain
+ * the code. `networkEnabled:false` makes `DockerSandbox` emit `--network none`.
+ */
+export declare function runInDocker(input: ExecuteCodeInput, options: ExecuteCodeRunnerOptions, deps?: DockerBackendDeps): Promise<ExecuteCodeResult>;
+/** Injectable edges for {@link runInE2b} (real defaults resolved lazily). */
+export interface E2bBackendDeps {
+    /**
+     * Runs a script in the E2B microVM. Default: `getE2BSandbox().runScript`.
+     * Injected in tests to assert routing without a real E2B account.
+     */
+    runScript?: (code: string, language: ExecuteCodeLanguage) => Promise<E2BSandboxResult>;
+    now?: () => Date;
+    createId?: () => string;
+}
+/**
+ * Run the experiment script inside an E2B Firecracker microVM. The host
+ * filesystem/secrets are unreachable (off-host), but the microVM keeps outbound
+ * network — the router discloses this and never lets e2b satisfy
+ * `requireNetworkIsolation`.
+ */
+export declare function runInE2b(input: ExecuteCodeInput, options: ExecuteCodeRunnerOptions, deps?: E2bBackendDeps): Promise<ExecuteCodeResult>;

package/dist/agent/science/experiment-sandbox-backends.js

@@ -0,0 +1,201 @@
+/**
+ * AI-Scientist-lite — Phase 2 real-brick sandbox adapters.
+ *
+ * Thin adapters that BRANCH the existing `src/sandbox/*` backends (never modify
+ * them) and translate their result shape into the {@link ExecuteCodeResult}
+ * the orchestrator already understands. Loaded lazily by the router only when a
+ * containerised backend is actually selected AND available.
+ *
+ *   - {@link runInDocker} → `DockerSandbox` with `networkEnabled:false`, i.e.
+ *     `docker run --network none`. THE security property: the network is cut.
+ *     The docker executor is injectable so tests assert the isolation option
+ *     without a real Docker daemon.
+ *   - {@link runInE2b} → `E2BSandbox.runScript`, an off-host Firecracker microVM.
+ *     The `runScript` boundary is injectable so tests assert routing without a
+ *     real E2B account.
+ *
+ * @module agent/science/experiment-sandbox-backends
+ */
+import path from 'path';
+import fs from 'fs/promises';
+import { randomUUID } from 'crypto';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 120_000;
+const MIN_TIMEOUT_MS = 1_000;
+const MAX_CAPTURE_CHARS = 1_000_000;
+/**
+ * Images are chosen so the interpreter is PRESENT (the network is cut, so no
+ * runtime download is possible). python/javascript work offline out of the box;
+ * typescript relies on `npx tsx`, which needs a network or a pre-baked image —
+ * an honest limitation of the network-cut docker backend (documented).
+ */
+const LANGUAGE_SPEC = {
+    python: { image: 'python:3.12-slim', ext: '.py', command: (p) => `python ${p}` },
+    javascript: { image: 'node:22-slim', ext: '.mjs', command: (p) => `node ${p}` },
+    typescript: { image: 'node:22-slim', ext: '.ts', command: (p) => `npx --yes tsx ${p}` },
+    shell: { image: 'node:22-slim', ext: '.sh', command: (p) => `sh ${p}` },
+};
+/**
+ * Run the experiment script inside a Docker container with the network CUT.
+ *
+ * The script is staged on the host under `<rootDir>/.codebuddy/execute-code/<id>`
+ * and bind-mounted at `/workspace`, so the container needs no network to obtain
+ * the code. `networkEnabled:false` makes `DockerSandbox` emit `--network none`.
+ */
+export async function runInDocker(input, options, deps = {}) {
+    const language = input.language ?? 'javascript';
+    const spec = LANGUAGE_SPEC[language];
+    const now = deps.now ?? options.now ?? (() => new Date());
+    const createId = deps.createId ?? options.createId ?? (() => `dkr-${randomUUID()}`);
+    const timeoutMs = clampTimeout(input.timeoutMs);
+    const rootDir = path.resolve(options.rootDir ?? process.cwd());
+    const runId = sanitizeRunId(createId());
+    const runDir = path.join(rootDir, '.codebuddy', 'execute-code', runId);
+    const scriptName = `script${spec.ext}`;
+    const scriptPath = path.join(runDir, scriptName);
+    const stdoutPath = path.join(runDir, 'stdout.log');
+    const stderrPath = path.join(runDir, 'stderr.log');
+    const resultPath = path.join(runDir, 'result.json');
+    await fs.mkdir(runDir, { recursive: true });
+    await fs.writeFile(scriptPath, requireCode(input.code), 'utf8');
+    const containerScriptPath = `/workspace/${scriptName}`;
+    const command = spec.command(containerScriptPath);
+    const startedAt = now().toISOString();
+    const dockerExecute = deps.dockerExecute ?? (await resolveDefaultDockerExecute());
+    // ── SECURITY: networkEnabled:false → `docker run --network none` ──────────
+    const sandboxResult = await dockerExecute(command, {
+        image: spec.image,
+        workspaceMount: runDir,
+        timeout: timeoutMs,
+        networkEnabled: false,
+        readOnly: false,
+    });
+    const completedAt = now().toISOString();
+    const stdout = boundText(sandboxResult.output ?? '');
+    const timedOut = /timed out/i.test(sandboxResult.error ?? '');
+    const stderr = timedOut ? '' : boundText(sandboxResult.error ?? '');
+    const exitCode = typeof sandboxResult.exitCode === 'number' ? sandboxResult.exitCode : null;
+    const ok = sandboxResult.success === true && !timedOut;
+    const error = buildError(ok, timedOut, exitCode, timeoutMs);
+    await fs.writeFile(stdoutPath, stdout, 'utf8').catch(() => undefined);
+    await fs.writeFile(stderrPath, stderr, 'utf8').catch(() => undefined);
+    const files = await listRunFiles(runDir);
+    const result = {
+        kind: 'execute_code_result',
+        ok,
+        runId,
+        language,
+        startedAt,
+        completedAt,
+        durationMs: Math.max(0, sandboxResult.durationMs ?? 0),
+        commandPreview: `[docker --network none ${spec.image}] ${command}`,
+        runDir,
+        scriptPath,
+        stdoutPath,
+        stderrPath,
+        resultPath,
+        exitCode,
+        signal: null,
+        timedOut,
+        stdout,
+        stderr,
+        files: [...new Set([...files, 'result.json'])].sort(),
+        ...(error ? { error } : {}),
+    };
+    await fs.writeFile(resultPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8').catch(() => undefined);
+    return result;
+}
+async function resolveDefaultDockerExecute() {
+    const { DockerSandbox } = await import('../../sandbox/docker-sandbox.js');
+    const sandbox = new DockerSandbox();
+    return (command, opts) => sandbox.execute(command, opts);
+}
+/**
+ * Run the experiment script inside an E2B Firecracker microVM. The host
+ * filesystem/secrets are unreachable (off-host), but the microVM keeps outbound
+ * network — the router discloses this and never lets e2b satisfy
+ * `requireNetworkIsolation`.
+ */
+export async function runInE2b(input, options, deps = {}) {
+    const language = input.language ?? 'javascript';
+    const now = deps.now ?? options.now ?? (() => new Date());
+    const createId = deps.createId ?? options.createId ?? (() => `e2b-${randomUUID()}`);
+    const runId = sanitizeRunId(createId());
+    const startedAt = now().toISOString();
+    const runScript = deps.runScript ?? (await resolveDefaultE2bRunScript());
+    const r = await runScript(requireCode(input.code), language);
+    const completedAt = now().toISOString();
+    const stdout = boundText(r.output ?? '');
+    const timedOut = /timeout|aborted/i.test(r.error ?? '');
+    const stderr = timedOut ? '' : boundText(r.error ?? '');
+    const exitCode = typeof r.exitCode === 'number' ? r.exitCode : null;
+    const ok = r.success === true && !timedOut;
+    const error = buildError(ok, timedOut, exitCode, clampTimeout(input.timeoutMs));
+    // E2B runs off-host — there is no host run directory; the paths are virtual.
+    const base = `e2b://${r.sandboxId ?? runId}`;
+    return {
+        kind: 'execute_code_result',
+        ok,
+        runId,
+        language,
+        startedAt,
+        completedAt,
+        durationMs: Math.max(0, r.durationMs ?? 0),
+        commandPreview: `[e2b microVM] script.${LANGUAGE_SPEC[language].ext.replace('.', '')}`,
+        runDir: base,
+        scriptPath: `${base}/script${LANGUAGE_SPEC[language].ext}`,
+        stdoutPath: `${base}/stdout.log`,
+        stderrPath: `${base}/stderr.log`,
+        resultPath: `${base}/result.json`,
+        exitCode,
+        signal: null,
+        timedOut,
+        stdout,
+        stderr,
+        files: [],
+        ...(error ? { error } : {}),
+    };
+}
+async function resolveDefaultE2bRunScript() {
+    const { getE2BSandbox } = await import('../../sandbox/e2b-sandbox.js');
+    const sandbox = getE2BSandbox();
+    return (code, language) => sandbox.runScript(code, language);
+}
+// ============================================================================
+// Shared helpers (kept local — the isolate runner's are private)
+// ============================================================================
+function requireCode(code) {
+    return typeof code === 'string' ? code : '';
+}
+function clampTimeout(timeoutMs) {
+    if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs))
+        return DEFAULT_TIMEOUT_MS;
+    return Math.min(MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, Math.floor(timeoutMs)));
+}
+function boundText(text) {
+    return text.length <= MAX_CAPTURE_CHARS ? text : text.slice(text.length - MAX_CAPTURE_CHARS);
+}
+function buildError(ok, timedOut, exitCode, timeoutMs) {
+    if (ok)
+        return undefined;
+    if (timedOut)
+        return `experiment timed out after ${timeoutMs}ms`;
+    return `experiment exited with code ${exitCode ?? 'unknown'}`;
+}
+function sanitizeRunId(runId) {
+    const sanitized = runId.trim().replace(/[^A-Za-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '');
+    return sanitized || `run-${randomUUID()}`;
+}
+async function listRunFiles(runDir) {
+    try {
+        const entries = await fs.readdir(runDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name)
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=experiment-sandbox-backends.js.map

package/dist/agent/science/experiment-sandbox.d.ts

@@ -0,0 +1,105 @@
+/**
+ * AI-Scientist-lite — Phase 2 experiment execution sandbox ROUTER.
+ *
+ * Phase 0 executes generated experiment code through the local `isolate` runner
+ * (`execute-code-runner.ts`): it scrubs secrets, redirects HOME, uses a throwaway
+ * cwd and a timeout — but it leaves the NETWORK WIDE OPEN. That is the security
+ * hole Phase 2 closes: this router lets the experiment step run inside a
+ * network-isolating containerised backend instead.
+ *
+ * The router is a THIN, PURE selector over three backends, exposed as an
+ * `executeCode`-shaped function so it drops straight into
+ * {@link ExperimentDeps.executeCode} without changing the orchestrator:
+ *
+ *   - `isolate` — the Phase 0/1 default. Byte-identical: the router delegates
+ *     VERBATIM to the isolate runner. NETWORK NOT ISOLATED.
+ *   - `docker`  — `docker run --network none` via `DockerSandbox` (the network is
+ *     provably cut — the adapter asserts `networkEnabled:false`).
+ *   - `e2b`     — an off-host Firecracker microVM via `E2BSandbox`. The HOST
+ *     (filesystem/secrets) is unreachable, but through the existing wrapper API
+ *     the microVM keeps OUTBOUND network. Honest: e2b protects the host, it does
+ *     NOT cut the network.
+ *
+ * Safety rules (the whole point):
+ *   1. NEVER degrade silently to a weaker sandbox. If the requested backend is
+ *      unavailable we either (a) DEGRADE to `isolate` with a LOUD warning that
+ *      the network is not isolated, or (b) FAIL CLOSED (refuse, exec not
+ *      launched) when the caller passed `requireNetworkIsolation`.
+ *   2. A backend that cannot provably cut the network (`isolate`, `e2b`) can
+ *      never satisfy `requireNetworkIsolation` — the router refuses immediately.
+ *   3. never-CRASH: a backend LAUNCHER that throws degrades cleanly (loud) unless
+ *      `requireNetworkIsolation` is set, in which case it refuses rather than fall
+ *      back to a network-open runner.
+ *
+ * Every side-effecting edge — the backend launchers, the availability detectors,
+ * the warning sink — is an INJECTABLE boundary resolved lazily to the real bricks
+ * and faked in tests (no real Docker/E2B in CI).
+ *
+ * @module agent/science/experiment-sandbox
+ */
+import type { ExecuteCodeInput, ExecuteCodeResult, ExecuteCodeRunnerOptions } from '../../tools/execute-code-runner.js';
+/** The execution backends the router can select. */
+export type ExperimentSandboxBackend = 'isolate' | 'docker' | 'e2b';
+/**
+ * The execute-code boundary shape — identical to {@link ExperimentDeps.executeCode},
+ * so a router instance plugs straight in.
+ */
+export type ExperimentSandboxRunner = (input: ExecuteCodeInput, options: ExecuteCodeRunnerOptions) => Promise<ExecuteCodeResult>;
+/**
+ * Whether a backend PROVABLY cuts outbound network egress for the untrusted
+ * experiment code.
+ *
+ *  - `isolate` → false. Env-scrubbed local spawn, but the network is WIDE OPEN
+ *    (the exact hole Phase 2 closes).
+ *  - `docker`  → true. `docker run --network none` (asserted by the adapter).
+ *  - `e2b`     → false. The microVM runs OFF-HOST (host filesystem/secrets are
+ *    unreachable), but through the existing wrapper API it keeps outbound
+ *    network. Honest: e2b protects the HOST, not the network.
+ */
+export declare const CUTS_NETWORK: Readonly<Record<ExperimentSandboxBackend, boolean>>;
+export interface ExperimentSandboxConfig {
+    /** The requested backend. */
+    backend: ExperimentSandboxBackend;
+    /**
+     * Fail closed (refuse to run — exec not launched) rather than degrade to a
+     * network-open backend. Only a backend with `CUTS_NETWORK === true` can
+     * satisfy this; anything else is refused up front.
+     */
+    requireNetworkIsolation?: boolean;
+    /** Injectable backend launchers (default: real bricks, lazily imported). */
+    runners?: Partial<Record<ExperimentSandboxBackend, ExperimentSandboxRunner>>;
+    /** Injectable availability detectors (default: real DockerSandbox/E2BSandbox). */
+    detect?: Partial<Record<'docker' | 'e2b', () => Promise<boolean>>>;
+    /** Loud sink for degradation / disclosure warnings (default: `logger.warn`). */
+    warn?: (message: string) => void;
+}
+/**
+ * Thrown when the router refuses to run under `requireNetworkIsolation`. The
+ * orchestrator catches an `executeCode` throw and turns it into a clean terminal
+ * `failed` status — the pass ends honestly (no misleading report), the process
+ * never crashes, and no experiment code is ever run in a weaker sandbox.
+ */
+export declare class ExperimentSandboxRefusal extends Error {
+    readonly code = "SANDBOX_NETWORK_ISOLATION_REFUSED";
+    constructor(message: string);
+}
+/**
+ * Build an `executeCode`-shaped runner that routes to the selected sandbox
+ * backend. See the module docstring for the full safety contract.
+ */
+export declare function createExperimentSandboxRunner(config: ExperimentSandboxConfig): ExperimentSandboxRunner;
+/**
+ * Thin object face over {@link createExperimentSandboxRunner} matching the
+ * `ExperimentSandbox.run(input, options) → ExecutionResult` abstraction. Holds
+ * the resolved backend + its network posture for callers that want to log it.
+ */
+export declare class ExperimentSandbox {
+    readonly backend: ExperimentSandboxBackend;
+    readonly cutsNetwork: boolean;
+    private readonly runner;
+    constructor(config: ExperimentSandboxConfig);
+    /** Execute the experiment in the selected sandbox. */
+    run(input: ExecuteCodeInput, options: ExecuteCodeRunnerOptions): Promise<ExecuteCodeResult>;
+    /** The `executeCode`-shaped boundary for {@link ExperimentDeps.executeCode}. */
+    asExecuteCode(): ExperimentSandboxRunner;
+}

package/dist/agent/science/experiment-sandbox.js

@@ -0,0 +1,196 @@
+/**
+ * AI-Scientist-lite — Phase 2 experiment execution sandbox ROUTER.
+ *
+ * Phase 0 executes generated experiment code through the local `isolate` runner
+ * (`execute-code-runner.ts`): it scrubs secrets, redirects HOME, uses a throwaway
+ * cwd and a timeout — but it leaves the NETWORK WIDE OPEN. That is the security
+ * hole Phase 2 closes: this router lets the experiment step run inside a
+ * network-isolating containerised backend instead.
+ *
+ * The router is a THIN, PURE selector over three backends, exposed as an
+ * `executeCode`-shaped function so it drops straight into
+ * {@link ExperimentDeps.executeCode} without changing the orchestrator:
+ *
+ *   - `isolate` — the Phase 0/1 default. Byte-identical: the router delegates
+ *     VERBATIM to the isolate runner. NETWORK NOT ISOLATED.
+ *   - `docker`  — `docker run --network none` via `DockerSandbox` (the network is
+ *     provably cut — the adapter asserts `networkEnabled:false`).
+ *   - `e2b`     — an off-host Firecracker microVM via `E2BSandbox`. The HOST
+ *     (filesystem/secrets) is unreachable, but through the existing wrapper API
+ *     the microVM keeps OUTBOUND network. Honest: e2b protects the host, it does
+ *     NOT cut the network.
+ *
+ * Safety rules (the whole point):
+ *   1. NEVER degrade silently to a weaker sandbox. If the requested backend is
+ *      unavailable we either (a) DEGRADE to `isolate` with a LOUD warning that
+ *      the network is not isolated, or (b) FAIL CLOSED (refuse, exec not
+ *      launched) when the caller passed `requireNetworkIsolation`.
+ *   2. A backend that cannot provably cut the network (`isolate`, `e2b`) can
+ *      never satisfy `requireNetworkIsolation` — the router refuses immediately.
+ *   3. never-CRASH: a backend LAUNCHER that throws degrades cleanly (loud) unless
+ *      `requireNetworkIsolation` is set, in which case it refuses rather than fall
+ *      back to a network-open runner.
+ *
+ * Every side-effecting edge — the backend launchers, the availability detectors,
+ * the warning sink — is an INJECTABLE boundary resolved lazily to the real bricks
+ * and faked in tests (no real Docker/E2B in CI).
+ *
+ * @module agent/science/experiment-sandbox
+ */
+import { logger } from '../../utils/logger.js';
+/**
+ * Whether a backend PROVABLY cuts outbound network egress for the untrusted
+ * experiment code.
+ *
+ *  - `isolate` → false. Env-scrubbed local spawn, but the network is WIDE OPEN
+ *    (the exact hole Phase 2 closes).
+ *  - `docker`  → true. `docker run --network none` (asserted by the adapter).
+ *  - `e2b`     → false. The microVM runs OFF-HOST (host filesystem/secrets are
+ *    unreachable), but through the existing wrapper API it keeps outbound
+ *    network. Honest: e2b protects the HOST, not the network.
+ */
+export const CUTS_NETWORK = {
+    isolate: false,
+    docker: true,
+    e2b: false,
+};
+/**
+ * Thrown when the router refuses to run under `requireNetworkIsolation`. The
+ * orchestrator catches an `executeCode` throw and turns it into a clean terminal
+ * `failed` status — the pass ends honestly (no misleading report), the process
+ * never crashes, and no experiment code is ever run in a weaker sandbox.
+ */
+export class ExperimentSandboxRefusal extends Error {
+    code = 'SANDBOX_NETWORK_ISOLATION_REFUSED';
+    constructor(message) {
+        super(message);
+        this.name = 'ExperimentSandboxRefusal';
+    }
+}
+// ============================================================================
+// Lazy real-brick defaults (only loaded when the backend is actually selected)
+// ============================================================================
+async function defaultIsolateRunner(input, options) {
+    const { executeCode } = await import('../../tools/execute-code-runner.js');
+    return executeCode(input, options);
+}
+async function defaultDockerRunner(input, options) {
+    const { runInDocker } = await import('./experiment-sandbox-backends.js');
+    return runInDocker(input, options);
+}
+async function defaultE2bRunner(input, options) {
+    const { runInE2b } = await import('./experiment-sandbox-backends.js');
+    return runInE2b(input, options);
+}
+async function defaultDetectDocker() {
+    const { DockerSandbox } = await import('../../sandbox/docker-sandbox.js');
+    return DockerSandbox.isAvailable();
+}
+async function defaultDetectE2b() {
+    const { E2BSandbox } = await import('../../sandbox/e2b-sandbox.js');
+    return E2BSandbox.isAvailable();
+}
+// ============================================================================
+// The router
+// ============================================================================
+/**
+ * Build an `executeCode`-shaped runner that routes to the selected sandbox
+ * backend. See the module docstring for the full safety contract.
+ */
+export function createExperimentSandboxRunner(config) {
+    const { backend } = config;
+    const requireNet = config.requireNetworkIsolation === true;
+    const warn = config.warn ?? ((message) => logger.warn(message));
+    const runners = config.runners ?? {};
+    const detect = config.detect ?? {};
+    const runIsolate = runners.isolate ?? defaultIsolateRunner;
+    const runDocker = runners.docker ?? defaultDockerRunner;
+    const runE2b = runners.e2b ?? defaultE2bRunner;
+    const detectDocker = detect.docker ?? defaultDetectDocker;
+    const detectE2b = detect.e2b ?? defaultDetectE2b;
+    return async (input, options) => {
+        // ── isolate (Phase 0/1 default) ────────────────────────────────────────
+        if (backend === 'isolate') {
+            if (requireNet) {
+                throw new ExperimentSandboxRefusal("--require-network-isolation: backend 'isolate' does NOT cut network egress " +
+                    '(env-scrubbed local spawn keeps FULL network access). Use --sandbox docker for a ' +
+                    'provable network cut. Refusing to run (exec not launched).');
+            }
+            // Byte-identical Phase 0/1: verbatim delegation to the isolate runner.
+            return runIsolate(input, options);
+        }
+        const cutsNet = CUTS_NETWORK[backend];
+        // ── A network-isolation requirement can only be met by a network-cutting
+        //    backend. e2b is off-host but keeps outbound network → refuse up front.
+        if (requireNet && !cutsNet) {
+            throw new ExperimentSandboxRefusal(`--require-network-isolation: backend '${backend}' does NOT provably cut outbound network ` +
+                '(it isolates the host, not the network). Use --sandbox docker. Refusing (exec not launched).');
+        }
+        // ── Availability detection (never throws) ──────────────────────────────
+        let available = false;
+        try {
+            available = backend === 'docker' ? await detectDocker() : await detectE2b();
+        }
+        catch {
+            available = false;
+        }
+        if (!available) {
+            if (requireNet) {
+                // cutsNet is true here (docker) — do NOT fall back to network-open isolate.
+                throw new ExperimentSandboxRefusal(`--require-network-isolation: sandbox '${backend}' is unavailable and the only fallback ` +
+                    "('isolate') leaves the network OPEN. Refusing to run (exec not launched). Install/start " +
+                    'Docker, or drop --require-network-isolation to degrade explicitly.');
+            }
+            // Loud, explicit degradation — NEVER silent.
+            warn(`[science] sandbox '${backend}' unavailable — DEGRADING to 'isolate'. WARNING: the network is ` +
+                'NOT isolated; generated experiment code runs with FULL network access. Pass ' +
+                '--require-network-isolation to refuse instead of degrading.');
+            return runIsolate(input, options);
+        }
+        // ── Available → run in the requested backend ───────────────────────────
+        try {
+            const result = backend === 'docker' ? await runDocker(input, options) : await runE2b(input, options);
+            if (backend === 'e2b') {
+                // Honest disclosure: e2b is off-host but not network-cut.
+                warn("[science] sandbox 'e2b': experiment ran OFF-HOST (host filesystem/secrets unreachable), but " +
+                    'the microVM keeps OUTBOUND network. For a provable network cut use --sandbox docker.');
+            }
+            return result;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (requireNet) {
+                throw new ExperimentSandboxRefusal(`--require-network-isolation: sandbox '${backend}' launcher failed (${message}); refusing to ` +
+                    'fall back to the network-open isolate runner (exec not launched in a weaker sandbox).');
+            }
+            // never-CRASH: a launcher failure degrades cleanly (loud).
+            warn(`[science] sandbox '${backend}' launcher failed (${message}) — DEGRADING to 'isolate'. ` +
+                'WARNING: the network is NOT isolated for this run.');
+            return runIsolate(input, options);
+        }
+    };
+}
+/**
+ * Thin object face over {@link createExperimentSandboxRunner} matching the
+ * `ExperimentSandbox.run(input, options) → ExecutionResult` abstraction. Holds
+ * the resolved backend + its network posture for callers that want to log it.
+ */
+export class ExperimentSandbox {
+    backend;
+    cutsNetwork;
+    runner;
+    constructor(config) {
+        this.backend = config.backend;
+        this.cutsNetwork = CUTS_NETWORK[config.backend];
+        this.runner = createExperimentSandboxRunner(config);
+    }
+    /** Execute the experiment in the selected sandbox. */
+    run(input, options) {
+        return this.runner(input, options);
+    }
+    /** The `executeCode`-shaped boundary for {@link ExperimentDeps.executeCode}. */
+    asExecuteCode() {
+        return this.runner;
+    }
+}
+//# sourceMappingURL=experiment-sandbox.js.map

package/dist/agent/science/experiment-variant-store.d.ts

@@ -0,0 +1,108 @@
+/**
+ * AI-Scientist-lite — Phase 1: the experiment variant store.
+ *
+ * A genuinely APPEND-ONLY record of SCORED experiment variants (JSONL — one
+ * variant per line, appended with O_APPEND), calqued on
+ * `CodeVariantStore`/`EvolutionaryArchive` but DECOUPLED from the repo: a record
+ * carries the experiment's hypothesis + code + execution summary + measured
+ * metric + fitness + lineage (`parentId`), NOT a git branch/sha of Code Buddy.
+ *
+ * JSONL append (like the CKG ledger) is why two `buddy science` runs in the same
+ * cwd no longer clobber each other: `record()` appends a single line instead of
+ * rewriting the whole file, so a concurrent writer can't erase another's variant
+ * (the old full read-modify-write was last-writer-wins). A legacy single-object
+ * store (`{schemaVersion,variants:[…]}`) is still read back and is migrated to
+ * JSONL on the next append.
+ *
+ * It records and reads back; it NEVER "publishes" a variant. `kept` flips to true
+ * ONLY after the human keep-gate approves (Phase 1 §4) — a rejected/ungated
+ * variant stays archived (auditable) but is never marked kept. Timestamps are
+ * INJECTED by the caller (no `Date.now()` here). never-throws.
+ *
+ * @module agent/science/experiment-variant-store
+ */
+import type { ExecuteCodeLanguage } from '../../tools/execute-code-runner.js';
+/** A compact, faithful summary of an execution (not the full multi-KB blob). */
+export interface ExperimentExecutionSummary {
+    ok: boolean;
+    exitCode: number | null;
+    timedOut: boolean;
+    runId: string;
+    /** The experiment folder the run happened in (the sandbox run dir). */
+    runDir: string;
+    durationMs: number;
+}
+/** The measured metric a variant was scored on. */
+export interface ExperimentVariantMetric {
+    name: string;
+    /** Raw measured value (null when the metric could not be parsed). */
+    value: number | null;
+    /** Normalised metric score in [0,1]. */
+    score: number;
+    detail: string;
+}
+export interface ExperimentVariantRecord {
+    id: string;
+    /** The hypothesis this variant tested. */
+    hypothesis: string;
+    /** The experiment program that was run. */
+    code: string;
+    language: ExecuteCodeLanguage;
+    /** Compact execution outcome (the experiment folder + exit status). */
+    executionResult: ExperimentExecutionSummary;
+    /** The measured metric the variant was scored on. */
+    metric: ExperimentVariantMetric;
+    /** Aggregate fitness in [0,1] (from `computeFitness`). */
+    score: number;
+    passedAll: boolean;
+    /** Component names that regressed vs the experiment baseline (empty = none). */
+    regressions: string[];
+    /** Genealogy: the parent variant this one was derived from (absent = root). */
+    parentId?: string;
+    /** True ONLY after the human keep-gate approved. Never set implicitly. */
+    kept: boolean;
+    /** Injected ISO-8601 timestamp (the store never calls Date.now()). */
+    createdAt: string;
+    detail?: string;
+}
+export interface ExperimentBestOptions {
+    /** Only consider variants strictly above this score (e.g. a baseline). */
+    baselineScore?: number;
+    /** Require passedAll (default true). */
+    requirePassedAll?: boolean;
+    /** Reject variants with any regression (default true). */
+    rejectRegressions?: boolean;
+    /** Require the human keep-gate to have approved (default false). */
+    requireKept?: boolean;
+}
+/**
+ * Append-only JSONL store for scored experiment variants. Mirrors
+ * `CodeVariantStore`: `record()` appends ONE line, `list()`/`get()` read back,
+ * `best()` selects. never-throws. Concurrent-safe (O_APPEND, no full rewrite).
+ */
+export declare class ExperimentVariantStore {
+    private readonly path;
+    constructor(path?: string);
+    getPath(): string;
+    list(): ExperimentVariantRecord[];
+    get(id: string): ExperimentVariantRecord | null;
+    /**
+     * Append a variant record as one JSONL line (best-effort, never throws). This
+     * is a true append (O_APPEND), so concurrent `buddy science` runs in the same
+     * cwd cannot clobber each other's variants.
+     */
+    record(rec: ExperimentVariantRecord): void;
+    /**
+     * If the store is still in the legacy `{schemaVersion,variants:[…]}` format,
+     * rewrite it as JSONL ONCE so subsequent appends stay pure appends. A
+     * non-parseable legacy blob is left untouched (never-throws; `list()` still
+     * best-effort-parses lines). Called only from `record()`.
+     */
+    private migrateLegacyIfNeeded;
+    /**
+     * The winner: highest-scoring variant that passed everything, has no
+     * regression, and (if given) strictly beats the baseline score. Ties broken by
+     * most recent. null if none qualify.
+     */
+    best(opts?: ExperimentBestOptions): ExperimentVariantRecord | null;
+}