@gatebolt/agent-redroom 0.1.0

package/dist/planting.js

@@ -0,0 +1,57 @@
+import {} from "./docker/cli.js";
+import { isFakeHost } from "./sidecar/dns.js";
+import {} from "./sidecar/state.js";
+import { RedroomError } from "./types.js";
+const HTML = "text/html; charset=utf-8";
+const EXECUTABLE = 0o755;
+const invalid = (code, detail) => new RedroomError(code, detail, "redroom");
+export function servedPages(pages, domain) {
+    return Object.fromEntries(Object.entries(pages).map(([url, page]) => {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw invalid("invalid_page", `${url} is not a URL`);
+        }
+        if (!["http:", "https:"].includes(parsed.protocol) ||
+            !isFakeHost(parsed.hostname, domain)) {
+            throw invalid("invalid_page", `${url} must be an http or https URL on ${domain} or a subdomain`);
+        }
+        const served = typeof page === "string"
+            ? { body: page, contentType: HTML, status: 200 }
+            : {
+                body: page.body,
+                contentType: page.contentType ?? HTML,
+                status: page.status ?? 200,
+            };
+        return [`${parsed.hostname}${parsed.pathname}${parsed.search}`, served];
+    }));
+}
+function entryOf(path, file, owner) {
+    if (typeof file === "string" || Buffer.isBuffer(file)) {
+        return { path, body: file, owner };
+    }
+    return {
+        path,
+        body: file.body,
+        owner,
+        ...(file.executable ? { mode: EXECUTABLE } : {}),
+    };
+}
+export function workspaceEntries(workspace, owner) {
+    return Object.entries(workspace).map(([path, file]) => {
+        if (path.startsWith("/")) {
+            throw invalid("invalid_file", `workspace path ${path} must be relative to the workspace`);
+        }
+        return entryOf(path, file, owner);
+    });
+}
+export function absoluteEntries(files, owner) {
+    return Object.entries(files).map(([path, file]) => {
+        if (!path.startsWith("/")) {
+            throw invalid("invalid_file", `file path ${path} must be absolute`);
+        }
+        return entryOf(path.slice(1), file, owner);
+    });
+}

package/dist/redact.d.ts

@@ -0,0 +1,3 @@
+export declare const REDACTED = "[redacted]";
+export declare function redactSecrets(text: string, secrets: readonly (string | undefined)[]): string;
+export declare function redactDeep(value: unknown, redact: (text: string) => string): unknown;

package/dist/redact.js

@@ -0,0 +1,24 @@
+export const REDACTED = "[redacted]";
+export function redactSecrets(text, secrets) {
+    let redacted = text;
+    const longestFirst = secrets
+        .filter((secret) => Boolean(secret))
+        .sort((a, b) => b.length - a.length);
+    for (const secret of longestFirst) {
+        redacted = redacted.replaceAll(secret, REDACTED);
+    }
+    return redacted;
+}
+export function redactDeep(value, redact) {
+    if (typeof value === "string")
+        return redact(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactDeep(item, redact));
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            redactDeep(item, redact),
+        ]));
+    }
+    return value;
+}

package/dist/redroom.d.ts

@@ -0,0 +1,37 @@
+import { type Agent } from "./agents/agent.js";
+import { type Docker } from "./docker/cli.js";
+import { type Run } from "./run.js";
+import { type Hit, type Limits, type ModelProxy, type RunOptions, type ToolCallCheck } from "./types.js";
+export type RedroomOptions = {
+    agent: Agent;
+    modelProxy?: ModelProxy;
+    toolCallCheck?: ToolCallCheck;
+    parallel?: number;
+    limits?: Partial<Limits>;
+    fakeDomain?: string;
+    network?: string;
+    log?: (line: string) => void;
+};
+export interface Redroom {
+    readonly session: string;
+    readonly agentVersion: string;
+    readonly controlUrl: string;
+    startRun(options?: RunOptions): Promise<Run>;
+    unattributedHits(): Promise<Hit[]>;
+    stop(): Promise<void>;
+}
+export type RedroomDeps = {
+    docker: Docker;
+    fetch: typeof fetch;
+    sleep: (ms: number) => Promise<void>;
+    randomHex: (bytes: number) => string;
+    pickSubnet: () => string;
+    newRunId: () => string;
+    leaseRenewMs: number;
+    readyAttempts: number;
+};
+export declare const DEFAULT_DOMAIN = "redroom.test";
+export declare const CONTROL_TIMEOUT_MS: number;
+export declare const defaultDeps: () => RedroomDeps;
+export declare function startRedroom(options: RedroomOptions): Promise<Redroom>;
+export declare function createRedroom(options: RedroomOptions, deps: RedroomDeps): Promise<Redroom>;

package/dist/redroom.js

@@ -0,0 +1,438 @@
+import { randomBytes, randomInt, randomUUID } from "node:crypto";
+import {} from "./agents/agent.js";
+import { dockerCli, MAX_OUTPUT_MB, tarOf, withDefaultTimeouts, } from "./docker/cli.js";
+import { AGENT_HOST, agentArgs, CA_DIR, CA_FILE, DEFAULT_LIMITS, GIT_INIT, sessionPlan, SIDECAR_HOST, SIDECAR_IMAGE, sidecarArgs, SYSTEM_CA_DIR, SYSTEM_CA_FILE, WORKSPACE, } from "./docker/plan.js";
+import { createInternalNetwork, LEASE_MS, LEASE_RENEW_MS, networkIp, removeLeftovers, tearDownSession, } from "./docker/session.js";
+import { withDeadline } from "./deadline.js";
+import { headerValues, wiring } from "./hooks.js";
+import { packagePath } from "./paths.js";
+import { absoluteEntries, servedPages, workspaceEntries } from "./planting.js";
+import { redactDeep, redactSecrets } from "./redact.js";
+import { openRun } from "./run.js";
+import { CONFIG_ENV, PORTS } from "./sidecar/config.js";
+import { DETAIL_LIMIT, messageOf, RedroomError, } from "./types.js";
+export const DEFAULT_DOMAIN = "redroom.test";
+export const CONTROL_TIMEOUT_MS = 30 * 1000;
+const DEFAULT_PARALLEL = 4;
+const READY_DELAY_MS = 500;
+const START_FAILED = "start_failed";
+const RUN_START_FAILED = "run_start_failed";
+const MAX_PARALLEL = 245;
+// Docker 28 added the isolated gateway mode; older engines ignore or reject it.
+const MIN_ENGINE_MAJOR = 28;
+const DOMAIN = /^[a-z0-9-]+(\.[a-z0-9-]+)*$/;
+export const defaultDeps = () => ({
+    docker: dockerCli(),
+    fetch: globalThis.fetch,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    randomHex: (bytes) => randomBytes(bytes).toString("hex"),
+    pickSubnet: () => `10.${200 + randomInt(55)}.${randomInt(256)}`,
+    newRunId: () => randomUUID(),
+    leaseRenewMs: LEASE_RENEW_MS,
+    readyAttempts: 120,
+});
+function stoppedError() {
+    return new RedroomError("stopped", "this redroom has stopped", "redroom");
+}
+function slots(count) {
+    let free = count;
+    let closed = false;
+    const waiting = [];
+    return {
+        async take() {
+            if (closed)
+                throw stoppedError();
+            if (free > 0) {
+                free -= 1;
+                return;
+            }
+            await new Promise((resolve, reject) => waiting.push({ resolve, reject }));
+        },
+        release() {
+            const next = waiting.shift();
+            if (next)
+                next.resolve();
+            else
+                free += 1;
+        },
+        close() {
+            closed = true;
+            for (const next of waiting.splice(0))
+                next.reject(stoppedError());
+        },
+    };
+}
+function validate(options) {
+    const parallel = options.parallel ?? DEFAULT_PARALLEL;
+    if (!Number.isInteger(parallel) || parallel < 1 || parallel > MAX_PARALLEL) {
+        throw new RedroomError("invalid_option", `parallel must be a whole number from 1 to ${MAX_PARALLEL}, got ${parallel}`, "redroom");
+    }
+    const domain = options.fakeDomain ?? DEFAULT_DOMAIN;
+    if (!DOMAIN.test(domain)) {
+        throw new RedroomError("invalid_option", `fakeDomain must be a lowercase DNS name, got ${domain}`, "redroom");
+    }
+    return {
+        parallel,
+        domain,
+        limits: { ...DEFAULT_LIMITS, ...options.limits },
+    };
+}
+export async function startRedroom(options) {
+    return createRedroom(options, defaultDeps());
+}
+export async function createRedroom(options, deps) {
+    const { agent } = options;
+    const docker = withDefaultTimeouts(deps.docker);
+    const log = options.log ?? (() => undefined);
+    const { parallel, domain, limits } = validate(options);
+    const directModel = agent.defaultModelProxy();
+    const defaultModel = options.modelProxy ?? directModel;
+    const controlSecret = deps.randomHex(24);
+    const hidden = new Set([
+        controlSecret,
+        ...headerValues(defaultModel, directModel, options.toolCallCheck),
+    ]);
+    const conceal = (text) => redactSecrets(text, [...hidden]);
+    const redact = (text) => conceal(text).slice(-DETAIL_LIMIT);
+    async function must(code, args, dockerOptions) {
+        const result = await docker(args, dockerOptions);
+        const call = {
+            command: `docker ${args.slice(0, 2).join(" ")}`,
+            exitCode: result.exitCode,
+        };
+        if (result.outputTooLarge) {
+            throw new RedroomError("output_too_large", `docker ${args[0]} wrote more than ${MAX_OUTPUT_MB} MB of output`, "docker", call);
+        }
+        if (result.exitCode !== 0) {
+            throw new RedroomError(code, `docker ${args[0]} failed (${result.exitCode}): ${redact(result.stderr.trim())}`, "docker", call);
+        }
+        return result;
+    }
+    function fetchControl(base, path, init) {
+        const timeoutError = () => new RedroomError("sidecar_timeout", `${path} did not answer within ${CONTROL_TIMEOUT_MS} ms`, "sidecar", { url: path });
+        return withDeadline(CONTROL_TIMEOUT_MS, timeoutError, async (signal) => {
+            const response = await deps.fetch(`${base}${path}`, { ...init, signal });
+            return new Response(await response.arrayBuffer(), response);
+        });
+    }
+    const version = await docker(["version", "--format", "{{.Server.Version}}"]);
+    if (version.exitCode !== 0) {
+        throw new RedroomError("docker_unavailable", `the Docker engine did not answer: ${redact(version.stderr.trim())}`, "docker", { command: "docker version", exitCode: version.exitCode });
+    }
+    const engine = version.stdout.trim();
+    if (Number.parseInt(engine, 10) < MIN_ENGINE_MAJOR) {
+        throw new RedroomError("docker_unavailable", `Docker Engine ${MIN_ENGINE_MAJOR} or newer is required to keep agents off host services, found ${engine}`, "docker", { command: "docker version", exitCode: version.exitCode });
+    }
+    const leftovers = await removeLeftovers(docker);
+    if (leftovers.containers.length + leftovers.networks.length > 0) {
+        log(`agent-redroom: removed ${leftovers.containers.length} containers and ${leftovers.networks.length} networks left by stopped sessions`);
+    }
+    await must("image_build_failed", [
+        ...["build", "-t", agent.image.tag],
+        ...Object.entries(agent.image.buildArgs).flatMap(([key, value]) => [
+            "--build-arg",
+            `${key}=${value}`,
+        ]),
+        agent.image.context,
+    ]);
+    const sidecarBuild = await docker([
+        ...["build", "-t", SIDECAR_IMAGE],
+        ...["-f", packagePath("images", "sidecar", "Dockerfile")],
+        packagePath("dist", "sidecar-bundle"),
+    ]);
+    if (sidecarBuild.exitCode !== 0) {
+        throw new RedroomError("image_build_failed", `could not build ${SIDECAR_IMAGE}; build the package so dist/sidecar-bundle/sidecar.mjs exists (${redact(sidecarBuild.stderr.trim())})`, "docker", { command: "docker build", exitCode: sidecarBuild.exitCode });
+    }
+    const reported = await must("version_failed", [
+        ...["run", "--rm", "--network", "none", agent.image.tag],
+        ...agent.versionCommand(),
+    ]);
+    const agentVersion = reported.stdout.trim().split(/\s+/)[0] ?? "";
+    if (agentVersion !== agent.version) {
+        throw new RedroomError("version_mismatch", `${agent.image.tag} reports version ${agentVersion}, expected ${agent.version}`, "agent");
+    }
+    const session = deps.randomHex(4);
+    const plan = sessionPlan(session);
+    const sidecar = (path, init = {}) => {
+        const hasBody = init.body !== undefined;
+        return fetchControl(controlUrl, path, {
+            method: init.method ?? "GET",
+            headers: {
+                authorization: `Bearer ${controlSecret}`,
+                ...(hasBody ? { "content-type": "application/json" } : {}),
+            },
+            ...(hasBody ? { body: JSON.stringify(init.body) } : {}),
+        }).catch((error) => {
+            if (error instanceof RedroomError)
+                throw error;
+            throw new RedroomError("sidecar_unreachable", `${path}: ${redact(messageOf(error))}`, "sidecar", { url: path });
+        });
+    };
+    let controlUrl;
+    let caPem;
+    try {
+        await must(START_FAILED, [
+            "network",
+            "create",
+            ...plan.labels,
+            plan.egress,
+        ]);
+        controlUrl = await startSidecar(plan);
+        caPem = await readCa();
+    }
+    catch (error) {
+        await tearDownSession(docker, plan);
+        throw error;
+    }
+    async function readCa() {
+        const response = await sidecar("/ca");
+        if (!response.ok) {
+            throw new RedroomError("sidecar_failed", `sidecar answered ${response.status} for its CA`, "sidecar", { url: "/ca", status: response.status });
+        }
+        return response.text();
+    }
+    async function startSidecar(plan) {
+        const config = {
+            controlSecret,
+            domain,
+            leaseMs: LEASE_MS,
+        };
+        const env = { [CONFIG_ENV]: JSON.stringify(config) };
+        await must(START_FAILED, sidecarArgs(plan, env, !options.network), { env });
+        if (options.network) {
+            await must(START_FAILED, [
+                "network",
+                "connect",
+                options.network,
+                plan.sidecar,
+            ]);
+        }
+        await must(START_FAILED, ["start", plan.sidecar]);
+        const base = await controlBase(plan);
+        for (let attempt = 0; attempt < deps.readyAttempts; attempt += 1) {
+            const ready = await fetchControl(base, "/lease", {
+                headers: { authorization: `Bearer ${controlSecret}` },
+            })
+                .then((response) => response.ok)
+                .catch(() => false);
+            if (ready)
+                return base;
+            await deps.sleep(READY_DELAY_MS);
+        }
+        const logs = await docker(["logs", "--tail", "30", plan.sidecar]);
+        throw new RedroomError("sidecar_not_ready", `the sidecar did not answer at ${base}: ${redact(`${logs.stdout}${logs.stderr}`)}`, "sidecar", { url: `${base}/lease` });
+    }
+    async function controlBase(plan) {
+        if (options.network) {
+            const inspected = await must(START_FAILED, [
+                ...["inspect", "--format", "{{json .NetworkSettings.Networks}}"],
+                plan.sidecar,
+            ]);
+            const ip = networkIp(inspected.stdout, options.network);
+            if (!ip) {
+                throw new RedroomError(START_FAILED, `the sidecar has no address on network ${options.network}`, "docker");
+            }
+            return `http://${ip}:${PORTS.control}`;
+        }
+        const port = await must(START_FAILED, [
+            "port",
+            plan.sidecar,
+            `${PORTS.control}/tcp`,
+        ]);
+        const address = port.stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .find((line) => line.startsWith("127.0.0.1:"));
+        if (!address) {
+            throw new RedroomError(START_FAILED, `the sidecar has no published control port: ${port.stdout.trim()}`, "docker");
+        }
+        return `http://${address}`;
+    }
+    const lease = setInterval(() => {
+        sidecar("/lease").catch((error) => {
+            log(`agent-redroom: lease renewal failed: ${redact(messageOf(error))}`);
+        });
+    }, deps.leaseRenewMs);
+    lease.unref();
+    const runSlots = slots(parallel);
+    const starting = new Set();
+    const unattributed = [];
+    let stopping = null;
+    async function startRun(runOptions = {}) {
+        if (stopping)
+            throw stoppedError();
+        const pages = servedPages(runOptions.pages ?? {}, domain);
+        const modelProxy = runOptions.modelProxy === undefined
+            ? defaultModel
+            : (runOptions.modelProxy ?? directModel);
+        if (!modelProxy) {
+            throw new RedroomError("missing_model_access", `${agent.name} needs a modelProxy or ANTHROPIC_API_KEY in the environment`, "redroom");
+        }
+        const toolCallCheck = runOptions.toolCallCheck === undefined
+            ? options.toolCallCheck
+            : (runOptions.toolCallCheck ?? undefined);
+        for (const value of headerValues(modelProxy, toolCallCheck)) {
+            hidden.add(value);
+        }
+        let workspaceTar;
+        let rootTar;
+        const id = deps.newRunId();
+        try {
+            workspaceTar = tarOf(workspaceEntries(runOptions.workspace ?? {}, agent.uid));
+            rootTar = tarOf([
+                ...absoluteEntries(runOptions.files ?? {}, agent.uid),
+                { path: `${CA_DIR.slice(1)}/${CA_FILE}`, body: caPem },
+                { path: `${SYSTEM_CA_DIR.slice(1)}/${SYSTEM_CA_FILE}`, body: caPem },
+            ], { dirs: false });
+        }
+        catch (error) {
+            if (error instanceof RedroomError)
+                throw error;
+            throw new RedroomError("invalid_file", messageOf(error), "redroom");
+        }
+        await runSlots.take();
+        if (stopping) {
+            runSlots.release();
+            throw stoppedError();
+        }
+        const secrets = runOptions.secrets ?? {};
+        const launch = async () => {
+            const name = plan.agent(id);
+            const network = plan.internal(id);
+            let subnet;
+            try {
+                subnet = await createInternalNetwork(docker, plan.labels, network, deps.pickSubnet, redact);
+            }
+            catch (error) {
+                runSlots.release();
+                throw error;
+            }
+            const ip = `${subnet}.${AGENT_HOST}`;
+            const sidecarIp = `${subnet}.${SIDECAR_HOST}`;
+            const wired = wiring(sidecarIp, id);
+            let registered = false;
+            let baseline = "";
+            let removed = false;
+            const remove = async () => {
+                if (removed)
+                    return;
+                removed = true;
+                try {
+                    await must("remove_failed", ["rm", "-f", name]);
+                }
+                finally {
+                    if (registered) {
+                        await sidecar(`/runs/${id}`, { method: "DELETE" }).catch(() => undefined);
+                    }
+                    try {
+                        await docker(["network", "disconnect", network, plan.sidecar]);
+                        await docker(["network", "rm", network]);
+                    }
+                    finally {
+                        runSlots.release();
+                    }
+                }
+            };
+            try {
+                await must(RUN_START_FAILED, [
+                    ...["network", "connect", "--ip", sidecarIp, network, plan.sidecar],
+                ]);
+                const response = await sidecar("/runs", {
+                    method: "POST",
+                    body: { id, ip, pages, secrets, modelProxy, toolCallCheck },
+                });
+                if (!response.ok) {
+                    throw new RedroomError(RUN_START_FAILED, `sidecar refused run ${id}: ${redact(await response.text())}`, "sidecar", { url: "/runs", status: response.status });
+                }
+                registered = true;
+                await must(RUN_START_FAILED, agentArgs(plan, {
+                    name,
+                    runId: id,
+                    ip,
+                    sidecarIp,
+                    image: agent.image.tag,
+                    limits,
+                    env: agent.env(wired),
+                }));
+                await must(RUN_START_FAILED, ["cp", "-", `${name}:${WORKSPACE}`], {
+                    input: workspaceTar,
+                });
+                await must(RUN_START_FAILED, ["cp", "-", `${name}:/`], {
+                    input: rootTar,
+                });
+                const wiringFiles = agent
+                    .rootFiles(wired)
+                    .map((file) => ({ path: file.path.slice(1), body: file.body }));
+                await must(RUN_START_FAILED, ["cp", "-", `${name}:/`], {
+                    input: tarOf(wiringFiles, { dirs: false }),
+                });
+                await must(RUN_START_FAILED, ["start", name]);
+                await must(RUN_START_FAILED, [
+                    ...["exec", "-u", "root", name, "update-ca-certificates"],
+                ]);
+                await must(RUN_START_FAILED, [
+                    ...["exec", "-u", agent.user, "-w", WORKSPACE, name],
+                    ...["sh", "-c", GIT_INIT],
+                ]);
+                const head = await must(RUN_START_FAILED, [
+                    ...["exec", "-u", agent.user, "-w", WORKSPACE, name],
+                    ...["git", "rev-parse", "HEAD"],
+                ]);
+                baseline = head.stdout.trim();
+                if (stopping)
+                    throw stoppedError();
+            }
+            catch (error) {
+                await remove().catch((removeError) => log(`agent-redroom: ${redact(messageOf(removeError))}`));
+                throw error instanceof RedroomError
+                    ? error
+                    : new RedroomError(RUN_START_FAILED, redact(messageOf(error)), "redroom");
+            }
+            return { name, network, ip, baseline, remove };
+        };
+        const launching = launch();
+        starting.add(launching);
+        const { name, network, ip, baseline, remove } = await launching.finally(() => starting.delete(launching));
+        return openRun({
+            docker,
+            agent,
+            agentVersion,
+            turnTimeoutMs: limits.turnTimeoutMs,
+            redact: conceal,
+            sidecar,
+            must,
+            remove,
+        }, { id, ip, name, network, secrets, baseline });
+    }
+    return {
+        session,
+        agentVersion,
+        controlUrl,
+        startRun,
+        async unattributedHits() {
+            const response = await sidecar("/hits/unattributed");
+            if (!response.ok) {
+                throw new RedroomError("sidecar_failed", `sidecar answered ${response.status} for unattributed hits`, "sidecar", { url: "/hits/unattributed", status: response.status });
+            }
+            const dropped = Number(response.headers.get("x-dropped") ?? "0");
+            if (dropped > 0) {
+                log(`agent-redroom: ${dropped} unattributed hits were dropped over the cap`);
+            }
+            const hits = redactDeep(await response.json(), conceal);
+            unattributed.push(...hits);
+            return [...unattributed];
+        },
+        stop() {
+            stopping ??= (async () => {
+                clearInterval(lease);
+                runSlots.close();
+                await Promise.allSettled(starting);
+                const problems = await tearDownSession(docker, plan);
+                for (const problem of problems) {
+                    log(`agent-redroom: teardown: ${redact(problem)}`);
+                }
+            })();
+            return stopping;
+        },
+    };
+}

package/dist/run.d.ts

@@ -0,0 +1,39 @@
+import { type Agent } from "./agents/agent.js";
+import { type Docker, type DockerOptions, type DockerResult } from "./docker/cli.js";
+import { type Hit, type ModelCall, type RunResult, type Secrets, type ToolCall, type Turn } from "./types.js";
+export type ControlInit = {
+    method?: string;
+    body?: unknown;
+};
+export type RunDeps = {
+    docker: Docker;
+    agent: Agent;
+    agentVersion: string;
+    turnTimeoutMs: number;
+    redact: (text: string) => string;
+    sidecar: (path: string, init?: ControlInit) => Promise<Response>;
+    must: (code: string, args: string[], options?: DockerOptions) => Promise<DockerResult>;
+    remove: () => Promise<void>;
+};
+export interface Run {
+    readonly id: string;
+    readonly ip: string;
+    send(message: string): Promise<Turn>;
+    exec(command: string): Promise<{
+        exitCode: number;
+        output: string;
+    }>;
+    readFile(path: string): Promise<string | null>;
+    hits(): Promise<Hit[]>;
+    toolCalls(): Promise<ToolCall[]>;
+    modelCalls(): Promise<ModelCall[]>;
+    finish(): Promise<RunResult>;
+}
+export declare function openRun(deps: RunDeps, run: {
+    id: string;
+    ip: string;
+    name: string;
+    network: string;
+    secrets: Secrets;
+    baseline: string;
+}): Run;