agiagent-dev 2026.1.30

package/dist/agents/sandbox/browser-bridges.d.ts

@@ -0,0 +1,5 @@
+import type { BrowserBridge } from "../../browser/bridge-server.js";
+export declare const BROWSER_BRIDGES: Map<string, {
+    bridge: BrowserBridge;
+    containerName: string;
+}>;

package/dist/agents/sandbox/browser-bridges.js

@@ -0,0 +1 @@
+export const BROWSER_BRIDGES = new Map();

package/dist/agents/sandbox/browser.d.ts

@@ -0,0 +1,8 @@
+import type { SandboxBrowserContext, SandboxConfig } from "./types.js";
+export declare function ensureSandboxBrowser(params: {
+    scopeKey: string;
+    workspaceDir: string;
+    agentWorkspaceDir: string;
+    cfg: SandboxConfig;
+    evaluateEnabled?: boolean;
+}): Promise<SandboxBrowserContext | null>;

package/dist/agents/sandbox/browser.js

@@ -0,0 +1,187 @@
+import { startBrowserBridgeServer, stopBrowserBridgeServer } from "../../browser/bridge-server.js";
+import { resolveProfile } from "../../browser/config.js";
+import { DEFAULT_BROWSER_EVALUATE_ENABLED, DEFAULT_AGIAGENT_BROWSER_COLOR, DEFAULT_AGIAGENT_BROWSER_PROFILE_NAME, } from "../../browser/constants.js";
+import { BROWSER_BRIDGES } from "./browser-bridges.js";
+import { DEFAULT_SANDBOX_BROWSER_IMAGE, SANDBOX_AGENT_WORKSPACE_MOUNT } from "./constants.js";
+import { buildSandboxCreateArgs, dockerContainerState, execDocker, readDockerPort, } from "./docker.js";
+import { updateBrowserRegistry } from "./registry.js";
+import { slugifySessionKey } from "./shared.js";
+import { isToolAllowed } from "./tool-policy.js";
+async function waitForSandboxCdp(params) {
+    const deadline = Date.now() + Math.max(0, params.timeoutMs);
+    const url = `http://127.0.0.1:${params.cdpPort}/json/version`;
+    while (Date.now() < deadline) {
+        try {
+            const ctrl = new AbortController();
+            const t = setTimeout(() => ctrl.abort(), 1000);
+            try {
+                const res = await fetch(url, { signal: ctrl.signal });
+                if (res.ok) {
+                    return true;
+                }
+            }
+            finally {
+                clearTimeout(t);
+            }
+        }
+        catch {
+            // ignore
+        }
+        await new Promise((r) => setTimeout(r, 150));
+    }
+    return false;
+}
+function buildSandboxBrowserResolvedConfig(params) {
+    const cdpHost = "127.0.0.1";
+    return {
+        enabled: true,
+        evaluateEnabled: params.evaluateEnabled,
+        controlPort: params.controlPort,
+        cdpProtocol: "http",
+        cdpHost,
+        cdpIsLoopback: true,
+        remoteCdpTimeoutMs: 1500,
+        remoteCdpHandshakeTimeoutMs: 3000,
+        color: DEFAULT_AGIAGENT_BROWSER_COLOR,
+        executablePath: undefined,
+        headless: params.headless,
+        noSandbox: false,
+        attachOnly: true,
+        defaultProfile: DEFAULT_AGIAGENT_BROWSER_PROFILE_NAME,
+        profiles: {
+            [DEFAULT_AGIAGENT_BROWSER_PROFILE_NAME]: {
+                cdpPort: params.cdpPort,
+                color: DEFAULT_AGIAGENT_BROWSER_COLOR,
+            },
+        },
+    };
+}
+async function ensureSandboxBrowserImage(image) {
+    const result = await execDocker(["image", "inspect", image], {
+        allowFailure: true,
+    });
+    if (result.code === 0) {
+        return;
+    }
+    throw new Error(`Sandbox browser image not found: ${image}. Build it with scripts/sandbox-browser-setup.sh.`);
+}
+export async function ensureSandboxBrowser(params) {
+    if (!params.cfg.browser.enabled) {
+        return null;
+    }
+    if (!isToolAllowed(params.cfg.tools, "browser")) {
+        return null;
+    }
+    const slug = params.cfg.scope === "shared" ? "shared" : slugifySessionKey(params.scopeKey);
+    const name = `${params.cfg.browser.containerPrefix}${slug}`;
+    const containerName = name.slice(0, 63);
+    const state = await dockerContainerState(containerName);
+    if (!state.exists) {
+        await ensureSandboxBrowserImage(params.cfg.browser.image ?? DEFAULT_SANDBOX_BROWSER_IMAGE);
+        const args = buildSandboxCreateArgs({
+            name: containerName,
+            cfg: params.cfg.docker,
+            scopeKey: params.scopeKey,
+            labels: { "agiagent.sandboxBrowser": "1" },
+        });
+        const mainMountSuffix = params.cfg.workspaceAccess === "ro" && params.workspaceDir === params.agentWorkspaceDir
+            ? ":ro"
+            : "";
+        args.push("-v", `${params.workspaceDir}:${params.cfg.docker.workdir}${mainMountSuffix}`);
+        if (params.cfg.workspaceAccess !== "none" && params.workspaceDir !== params.agentWorkspaceDir) {
+            const agentMountSuffix = params.cfg.workspaceAccess === "ro" ? ":ro" : "";
+            args.push("-v", `${params.agentWorkspaceDir}:${SANDBOX_AGENT_WORKSPACE_MOUNT}${agentMountSuffix}`);
+        }
+        args.push("-p", `127.0.0.1::${params.cfg.browser.cdpPort}`);
+        if (params.cfg.browser.enableNoVnc && !params.cfg.browser.headless) {
+            args.push("-p", `127.0.0.1::${params.cfg.browser.noVncPort}`);
+        }
+        args.push("-e", `AGIAGENT_BROWSER_HEADLESS=${params.cfg.browser.headless ? "1" : "0"}`);
+        args.push("-e", `AGIAGENT_BROWSER_ENABLE_NOVNC=${params.cfg.browser.enableNoVnc ? "1" : "0"}`);
+        args.push("-e", `AGIAGENT_BROWSER_CDP_PORT=${params.cfg.browser.cdpPort}`);
+        args.push("-e", `AGIAGENT_BROWSER_VNC_PORT=${params.cfg.browser.vncPort}`);
+        args.push("-e", `AGIAGENT_BROWSER_NOVNC_PORT=${params.cfg.browser.noVncPort}`);
+        args.push(params.cfg.browser.image);
+        await execDocker(args);
+        await execDocker(["start", containerName]);
+    }
+    else if (!state.running) {
+        await execDocker(["start", containerName]);
+    }
+    const mappedCdp = await readDockerPort(containerName, params.cfg.browser.cdpPort);
+    if (!mappedCdp) {
+        throw new Error(`Failed to resolve CDP port mapping for ${containerName}.`);
+    }
+    const mappedNoVnc = params.cfg.browser.enableNoVnc && !params.cfg.browser.headless
+        ? await readDockerPort(containerName, params.cfg.browser.noVncPort)
+        : null;
+    const existing = BROWSER_BRIDGES.get(params.scopeKey);
+    const existingProfile = existing
+        ? resolveProfile(existing.bridge.state.resolved, DEFAULT_AGIAGENT_BROWSER_PROFILE_NAME)
+        : null;
+    const shouldReuse = existing && existing.containerName === containerName && existingProfile?.cdpPort === mappedCdp;
+    if (existing && !shouldReuse) {
+        await stopBrowserBridgeServer(existing.bridge.server).catch(() => undefined);
+        BROWSER_BRIDGES.delete(params.scopeKey);
+    }
+    const bridge = (() => {
+        if (shouldReuse && existing) {
+            return existing.bridge;
+        }
+        return null;
+    })();
+    const ensureBridge = async () => {
+        if (bridge) {
+            return bridge;
+        }
+        const onEnsureAttachTarget = params.cfg.browser.autoStart
+            ? async () => {
+                const state = await dockerContainerState(containerName);
+                if (state.exists && !state.running) {
+                    await execDocker(["start", containerName]);
+                }
+                const ok = await waitForSandboxCdp({
+                    cdpPort: mappedCdp,
+                    timeoutMs: params.cfg.browser.autoStartTimeoutMs,
+                });
+                if (!ok) {
+                    throw new Error(`Sandbox browser CDP did not become reachable on 127.0.0.1:${mappedCdp} within ${params.cfg.browser.autoStartTimeoutMs}ms.`);
+                }
+            }
+            : undefined;
+        return await startBrowserBridgeServer({
+            resolved: buildSandboxBrowserResolvedConfig({
+                controlPort: 0,
+                cdpPort: mappedCdp,
+                headless: params.cfg.browser.headless,
+                evaluateEnabled: params.evaluateEnabled ?? DEFAULT_BROWSER_EVALUATE_ENABLED,
+            }),
+            onEnsureAttachTarget,
+        });
+    };
+    const resolvedBridge = await ensureBridge();
+    if (!shouldReuse) {
+        BROWSER_BRIDGES.set(params.scopeKey, {
+            bridge: resolvedBridge,
+            containerName,
+        });
+    }
+    const now = Date.now();
+    await updateBrowserRegistry({
+        containerName,
+        sessionKey: params.scopeKey,
+        createdAtMs: now,
+        lastUsedAtMs: now,
+        image: params.cfg.browser.image,
+        cdpPort: mappedCdp,
+        noVncPort: mappedNoVnc ?? undefined,
+    });
+    const noVncUrl = mappedNoVnc && params.cfg.browser.enableNoVnc && !params.cfg.browser.headless
+        ? `http://127.0.0.1:${mappedNoVnc}/vnc.html?autoconnect=1&resize=remote`
+        : undefined;
+    return {
+        bridgeUrl: resolvedBridge.baseUrl,
+        noVncUrl,
+        containerName,
+    };
+}

package/dist/agents/sandbox/config-hash.d.ts

@@ -0,0 +1,9 @@
+import type { SandboxDockerConfig, SandboxWorkspaceAccess } from "./types.js";
+type SandboxHashInput = {
+    docker: SandboxDockerConfig;
+    workspaceAccess: SandboxWorkspaceAccess;
+    workspaceDir: string;
+    agentWorkspaceDir: string;
+};
+export declare function computeSandboxConfigHash(input: SandboxHashInput): string;
+export {};

package/dist/agents/sandbox/config-hash.js

@@ -0,0 +1,51 @@
+import crypto from "node:crypto";
+function isPrimitive(value) {
+    return value === null || (typeof value !== "object" && typeof value !== "function");
+}
+function normalizeForHash(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        const normalized = value
+            .map(normalizeForHash)
+            .filter((item) => item !== undefined);
+        const primitives = normalized.filter(isPrimitive);
+        if (primitives.length === normalized.length) {
+            return [...primitives].toSorted((a, b) => primitiveToString(a).localeCompare(primitiveToString(b)));
+        }
+        return normalized;
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value).toSorted(([a], [b]) => a.localeCompare(b));
+        const normalized = {};
+        for (const [key, entryValue] of entries) {
+            const next = normalizeForHash(entryValue);
+            if (next !== undefined) {
+                normalized[key] = next;
+            }
+        }
+        return normalized;
+    }
+    return value;
+}
+function primitiveToString(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    return JSON.stringify(value);
+}
+export function computeSandboxConfigHash(input) {
+    const payload = normalizeForHash(input);
+    const raw = JSON.stringify(payload);
+    return crypto.createHash("sha1").update(raw).digest("hex");
+}

package/dist/agents/sandbox/config.d.ts

@@ -0,0 +1,22 @@
+import type { AGIAgentConfig } from "../../config/config.js";
+import type { SandboxBrowserConfig, SandboxConfig, SandboxDockerConfig, SandboxPruneConfig, SandboxScope } from "./types.js";
+export declare function resolveSandboxScope(params: {
+    scope?: SandboxScope;
+    perSession?: boolean;
+}): SandboxScope;
+export declare function resolveSandboxDockerConfig(params: {
+    scope: SandboxScope;
+    globalDocker?: Partial<SandboxDockerConfig>;
+    agentDocker?: Partial<SandboxDockerConfig>;
+}): SandboxDockerConfig;
+export declare function resolveSandboxBrowserConfig(params: {
+    scope: SandboxScope;
+    globalBrowser?: Partial<SandboxBrowserConfig>;
+    agentBrowser?: Partial<SandboxBrowserConfig>;
+}): SandboxBrowserConfig;
+export declare function resolveSandboxPruneConfig(params: {
+    scope: SandboxScope;
+    globalPrune?: Partial<SandboxPruneConfig>;
+    agentPrune?: Partial<SandboxPruneConfig>;
+}): SandboxPruneConfig;
+export declare function resolveSandboxConfigForAgent(cfg?: AGIAgentConfig, agentId?: string): SandboxConfig;

package/dist/agents/sandbox/config.js

@@ -0,0 +1,115 @@
+import { resolveAgentConfig } from "../agent-scope.js";
+import { DEFAULT_SANDBOX_BROWSER_AUTOSTART_TIMEOUT_MS, DEFAULT_SANDBOX_BROWSER_CDP_PORT, DEFAULT_SANDBOX_BROWSER_IMAGE, DEFAULT_SANDBOX_BROWSER_NOVNC_PORT, DEFAULT_SANDBOX_BROWSER_PREFIX, DEFAULT_SANDBOX_BROWSER_VNC_PORT, DEFAULT_SANDBOX_CONTAINER_PREFIX, DEFAULT_SANDBOX_IDLE_HOURS, DEFAULT_SANDBOX_IMAGE, DEFAULT_SANDBOX_MAX_AGE_DAYS, DEFAULT_SANDBOX_WORKDIR, DEFAULT_SANDBOX_WORKSPACE_ROOT, } from "./constants.js";
+import { resolveSandboxToolPolicyForAgent } from "./tool-policy.js";
+export function resolveSandboxScope(params) {
+    if (params.scope) {
+        return params.scope;
+    }
+    if (typeof params.perSession === "boolean") {
+        return params.perSession ? "session" : "shared";
+    }
+    return "agent";
+}
+export function resolveSandboxDockerConfig(params) {
+    const agentDocker = params.scope === "shared" ? undefined : params.agentDocker;
+    const globalDocker = params.globalDocker;
+    const env = agentDocker?.env
+        ? { ...(globalDocker?.env ?? { LANG: "C.UTF-8" }), ...agentDocker.env }
+        : (globalDocker?.env ?? { LANG: "C.UTF-8" });
+    const ulimits = agentDocker?.ulimits
+        ? { ...globalDocker?.ulimits, ...agentDocker.ulimits }
+        : globalDocker?.ulimits;
+    const binds = [...(globalDocker?.binds ?? []), ...(agentDocker?.binds ?? [])];
+    return {
+        image: agentDocker?.image ?? globalDocker?.image ?? DEFAULT_SANDBOX_IMAGE,
+        containerPrefix: agentDocker?.containerPrefix ??
+            globalDocker?.containerPrefix ??
+            DEFAULT_SANDBOX_CONTAINER_PREFIX,
+        workdir: agentDocker?.workdir ?? globalDocker?.workdir ?? DEFAULT_SANDBOX_WORKDIR,
+        readOnlyRoot: agentDocker?.readOnlyRoot ?? globalDocker?.readOnlyRoot ?? true,
+        tmpfs: agentDocker?.tmpfs ?? globalDocker?.tmpfs ?? ["/tmp", "/var/tmp", "/run"],
+        network: agentDocker?.network ?? globalDocker?.network ?? "none",
+        user: agentDocker?.user ?? globalDocker?.user,
+        capDrop: agentDocker?.capDrop ?? globalDocker?.capDrop ?? ["ALL"],
+        env,
+        setupCommand: agentDocker?.setupCommand ?? globalDocker?.setupCommand,
+        pidsLimit: agentDocker?.pidsLimit ?? globalDocker?.pidsLimit,
+        memory: agentDocker?.memory ?? globalDocker?.memory,
+        memorySwap: agentDocker?.memorySwap ?? globalDocker?.memorySwap,
+        cpus: agentDocker?.cpus ?? globalDocker?.cpus,
+        ulimits,
+        seccompProfile: agentDocker?.seccompProfile ?? globalDocker?.seccompProfile,
+        apparmorProfile: agentDocker?.apparmorProfile ?? globalDocker?.apparmorProfile,
+        dns: agentDocker?.dns ?? globalDocker?.dns,
+        extraHosts: agentDocker?.extraHosts ?? globalDocker?.extraHosts,
+        binds: binds.length ? binds : undefined,
+    };
+}
+export function resolveSandboxBrowserConfig(params) {
+    const agentBrowser = params.scope === "shared" ? undefined : params.agentBrowser;
+    const globalBrowser = params.globalBrowser;
+    return {
+        enabled: agentBrowser?.enabled ?? globalBrowser?.enabled ?? false,
+        image: agentBrowser?.image ?? globalBrowser?.image ?? DEFAULT_SANDBOX_BROWSER_IMAGE,
+        containerPrefix: agentBrowser?.containerPrefix ??
+            globalBrowser?.containerPrefix ??
+            DEFAULT_SANDBOX_BROWSER_PREFIX,
+        cdpPort: agentBrowser?.cdpPort ?? globalBrowser?.cdpPort ?? DEFAULT_SANDBOX_BROWSER_CDP_PORT,
+        vncPort: agentBrowser?.vncPort ?? globalBrowser?.vncPort ?? DEFAULT_SANDBOX_BROWSER_VNC_PORT,
+        noVncPort: agentBrowser?.noVncPort ?? globalBrowser?.noVncPort ?? DEFAULT_SANDBOX_BROWSER_NOVNC_PORT,
+        headless: agentBrowser?.headless ?? globalBrowser?.headless ?? false,
+        enableNoVnc: agentBrowser?.enableNoVnc ?? globalBrowser?.enableNoVnc ?? true,
+        allowHostControl: agentBrowser?.allowHostControl ?? globalBrowser?.allowHostControl ?? false,
+        autoStart: agentBrowser?.autoStart ?? globalBrowser?.autoStart ?? true,
+        autoStartTimeoutMs: agentBrowser?.autoStartTimeoutMs ??
+            globalBrowser?.autoStartTimeoutMs ??
+            DEFAULT_SANDBOX_BROWSER_AUTOSTART_TIMEOUT_MS,
+    };
+}
+export function resolveSandboxPruneConfig(params) {
+    const agentPrune = params.scope === "shared" ? undefined : params.agentPrune;
+    const globalPrune = params.globalPrune;
+    return {
+        idleHours: agentPrune?.idleHours ?? globalPrune?.idleHours ?? DEFAULT_SANDBOX_IDLE_HOURS,
+        maxAgeDays: agentPrune?.maxAgeDays ?? globalPrune?.maxAgeDays ?? DEFAULT_SANDBOX_MAX_AGE_DAYS,
+    };
+}
+export function resolveSandboxConfigForAgent(cfg, agentId) {
+    const agent = cfg?.agents?.defaults?.sandbox;
+    // Agent-specific sandbox config overrides global
+    let agentSandbox;
+    const agentConfig = cfg && agentId ? resolveAgentConfig(cfg, agentId) : undefined;
+    if (agentConfig?.sandbox) {
+        agentSandbox = agentConfig.sandbox;
+    }
+    const scope = resolveSandboxScope({
+        scope: agentSandbox?.scope ?? agent?.scope,
+        perSession: agentSandbox?.perSession ?? agent?.perSession,
+    });
+    const toolPolicy = resolveSandboxToolPolicyForAgent(cfg, agentId);
+    return {
+        mode: agentSandbox?.mode ?? agent?.mode ?? "off",
+        scope,
+        workspaceAccess: agentSandbox?.workspaceAccess ?? agent?.workspaceAccess ?? "none",
+        workspaceRoot: agentSandbox?.workspaceRoot ?? agent?.workspaceRoot ?? DEFAULT_SANDBOX_WORKSPACE_ROOT,
+        docker: resolveSandboxDockerConfig({
+            scope,
+            globalDocker: agent?.docker,
+            agentDocker: agentSandbox?.docker,
+        }),
+        browser: resolveSandboxBrowserConfig({
+            scope,
+            globalBrowser: agent?.browser,
+            agentBrowser: agentSandbox?.browser,
+        }),
+        tools: {
+            allow: toolPolicy.allow,
+            deny: toolPolicy.deny,
+        },
+        prune: resolveSandboxPruneConfig({
+            scope,
+            globalPrune: agent?.prune,
+            agentPrune: agentSandbox?.prune,
+        }),
+    };
+}

package/dist/agents/sandbox/constants.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_SANDBOX_WORKSPACE_ROOT: string;
+export declare const DEFAULT_SANDBOX_IMAGE = "agiagent-sandbox:bookworm-slim";
+export declare const DEFAULT_SANDBOX_CONTAINER_PREFIX = "agiagent-sbx-";
+export declare const DEFAULT_SANDBOX_WORKDIR = "/workspace";
+export declare const DEFAULT_SANDBOX_IDLE_HOURS = 24;
+export declare const DEFAULT_SANDBOX_MAX_AGE_DAYS = 7;
+export declare const DEFAULT_TOOL_ALLOW: readonly ["exec", "process", "read", "write", "edit", "apply_patch", "image", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"];
+export declare const DEFAULT_TOOL_DENY: readonly ["browser", "canvas", "nodes", "cron", "gateway", "telegram", "whatsapp", "discord", "googlechat", "slack", "signal", "imessage"];
+export declare const DEFAULT_SANDBOX_BROWSER_IMAGE = "agiagent-sandbox-browser:bookworm-slim";
+export declare const DEFAULT_SANDBOX_COMMON_IMAGE = "agiagent-sandbox-common:bookworm-slim";
+export declare const DEFAULT_SANDBOX_BROWSER_PREFIX = "agiagent-sbx-browser-";
+export declare const DEFAULT_SANDBOX_BROWSER_CDP_PORT = 9222;
+export declare const DEFAULT_SANDBOX_BROWSER_VNC_PORT = 5900;
+export declare const DEFAULT_SANDBOX_BROWSER_NOVNC_PORT = 6080;
+export declare const DEFAULT_SANDBOX_BROWSER_AUTOSTART_TIMEOUT_MS = 12000;
+export declare const SANDBOX_AGENT_WORKSPACE_MOUNT = "/agent";
+export declare const SANDBOX_STATE_DIR: string;
+export declare const SANDBOX_REGISTRY_PATH: string;
+export declare const SANDBOX_BROWSER_REGISTRY_PATH: string;

package/dist/agents/sandbox/constants.js

@@ -0,0 +1,45 @@
+import os from "node:os";
+import path from "node:path";
+import { CHANNEL_IDS } from "../../channels/registry.js";
+import { STATE_DIR } from "../../config/config.js";
+export const DEFAULT_SANDBOX_WORKSPACE_ROOT = path.join(os.homedir(), ".agiagent", "sandboxes");
+export const DEFAULT_SANDBOX_IMAGE = "agiagent-sandbox:bookworm-slim";
+export const DEFAULT_SANDBOX_CONTAINER_PREFIX = "agiagent-sbx-";
+export const DEFAULT_SANDBOX_WORKDIR = "/workspace";
+export const DEFAULT_SANDBOX_IDLE_HOURS = 24;
+export const DEFAULT_SANDBOX_MAX_AGE_DAYS = 7;
+export const DEFAULT_TOOL_ALLOW = [
+    "exec",
+    "process",
+    "read",
+    "write",
+    "edit",
+    "apply_patch",
+    "image",
+    "sessions_list",
+    "sessions_history",
+    "sessions_send",
+    "sessions_spawn",
+    "session_status",
+];
+// Provider docking: keep sandbox policy aligned with provider tool names.
+export const DEFAULT_TOOL_DENY = [
+    "browser",
+    "canvas",
+    "nodes",
+    "cron",
+    "gateway",
+    ...CHANNEL_IDS,
+];
+export const DEFAULT_SANDBOX_BROWSER_IMAGE = "agiagent-sandbox-browser:bookworm-slim";
+export const DEFAULT_SANDBOX_COMMON_IMAGE = "agiagent-sandbox-common:bookworm-slim";
+export const DEFAULT_SANDBOX_BROWSER_PREFIX = "agiagent-sbx-browser-";
+export const DEFAULT_SANDBOX_BROWSER_CDP_PORT = 9222;
+export const DEFAULT_SANDBOX_BROWSER_VNC_PORT = 5900;
+export const DEFAULT_SANDBOX_BROWSER_NOVNC_PORT = 6080;
+export const DEFAULT_SANDBOX_BROWSER_AUTOSTART_TIMEOUT_MS = 12_000;
+export const SANDBOX_AGENT_WORKSPACE_MOUNT = "/agent";
+const resolvedSandboxStateDir = STATE_DIR ?? path.join(os.homedir(), ".agiagent");
+export const SANDBOX_STATE_DIR = path.join(resolvedSandboxStateDir, "sandbox");
+export const SANDBOX_REGISTRY_PATH = path.join(SANDBOX_STATE_DIR, "containers.json");
+export const SANDBOX_BROWSER_REGISTRY_PATH = path.join(SANDBOX_STATE_DIR, "browsers.json");

package/dist/agents/sandbox/context.d.ts

@@ -0,0 +1,12 @@
+import type { AGIAgentConfig } from "../../config/config.js";
+import type { SandboxContext, SandboxWorkspaceInfo } from "./types.js";
+export declare function resolveSandboxContext(params: {
+    config?: AGIAgentConfig;
+    sessionKey?: string;
+    workspaceDir?: string;
+}): Promise<SandboxContext | null>;
+export declare function ensureSandboxWorkspaceForSession(params: {
+    config?: AGIAgentConfig;
+    sessionKey?: string;
+    workspaceDir?: string;
+}): Promise<SandboxWorkspaceInfo | null>;

package/dist/agents/sandbox/context.js

@@ -0,0 +1,121 @@
+import fs from "node:fs/promises";
+import { DEFAULT_BROWSER_EVALUATE_ENABLED } from "../../browser/constants.js";
+import { defaultRuntime } from "../../runtime.js";
+import { resolveUserPath } from "../../utils.js";
+import { syncSkillsToWorkspace } from "../skills.js";
+import { DEFAULT_AGENT_WORKSPACE_DIR } from "../workspace.js";
+import { ensureSandboxBrowser } from "./browser.js";
+import { resolveSandboxConfigForAgent } from "./config.js";
+import { ensureSandboxContainer } from "./docker.js";
+import { maybePruneSandboxes } from "./prune.js";
+import { resolveSandboxRuntimeStatus } from "./runtime-status.js";
+import { resolveSandboxScopeKey, resolveSandboxWorkspaceDir } from "./shared.js";
+import { ensureSandboxWorkspace } from "./workspace.js";
+export async function resolveSandboxContext(params) {
+    const rawSessionKey = params.sessionKey?.trim();
+    if (!rawSessionKey) {
+        return null;
+    }
+    const runtime = resolveSandboxRuntimeStatus({
+        cfg: params.config,
+        sessionKey: rawSessionKey,
+    });
+    if (!runtime.sandboxed) {
+        return null;
+    }
+    const cfg = resolveSandboxConfigForAgent(params.config, runtime.agentId);
+    await maybePruneSandboxes(cfg);
+    const agentWorkspaceDir = resolveUserPath(params.workspaceDir?.trim() || DEFAULT_AGENT_WORKSPACE_DIR);
+    const workspaceRoot = resolveUserPath(cfg.workspaceRoot);
+    const scopeKey = resolveSandboxScopeKey(cfg.scope, rawSessionKey);
+    const sandboxWorkspaceDir = cfg.scope === "shared" ? workspaceRoot : resolveSandboxWorkspaceDir(workspaceRoot, scopeKey);
+    const workspaceDir = cfg.workspaceAccess === "rw" ? agentWorkspaceDir : sandboxWorkspaceDir;
+    if (workspaceDir === sandboxWorkspaceDir) {
+        await ensureSandboxWorkspace(sandboxWorkspaceDir, agentWorkspaceDir, params.config?.agents?.defaults?.skipBootstrap);
+        if (cfg.workspaceAccess !== "rw") {
+            try {
+                await syncSkillsToWorkspace({
+                    sourceWorkspaceDir: agentWorkspaceDir,
+                    targetWorkspaceDir: sandboxWorkspaceDir,
+                    config: params.config,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : JSON.stringify(error);
+                defaultRuntime.error?.(`Sandbox skill sync failed: ${message}`);
+            }
+        }
+    }
+    else {
+        await fs.mkdir(workspaceDir, { recursive: true });
+    }
+    const containerName = await ensureSandboxContainer({
+        sessionKey: rawSessionKey,
+        workspaceDir,
+        agentWorkspaceDir,
+        cfg,
+    });
+    const evaluateEnabled = params.config?.browser?.evaluateEnabled ?? DEFAULT_BROWSER_EVALUATE_ENABLED;
+    const browser = await ensureSandboxBrowser({
+        scopeKey,
+        workspaceDir,
+        agentWorkspaceDir,
+        cfg,
+        evaluateEnabled,
+    });
+    return {
+        enabled: true,
+        sessionKey: rawSessionKey,
+        workspaceDir,
+        agentWorkspaceDir,
+        workspaceAccess: cfg.workspaceAccess,
+        containerName,
+        containerWorkdir: cfg.docker.workdir,
+        docker: cfg.docker,
+        tools: cfg.tools,
+        browserAllowHostControl: cfg.browser.allowHostControl,
+        browser: browser ?? undefined,
+    };
+}
+export async function ensureSandboxWorkspaceForSession(params) {
+    const rawSessionKey = params.sessionKey?.trim();
+    if (!rawSessionKey) {
+        return null;
+    }
+    const runtime = resolveSandboxRuntimeStatus({
+        cfg: params.config,
+        sessionKey: rawSessionKey,
+    });
+    if (!runtime.sandboxed) {
+        return null;
+    }
+    const cfg = resolveSandboxConfigForAgent(params.config, runtime.agentId);
+    const agentWorkspaceDir = resolveUserPath(params.workspaceDir?.trim() || DEFAULT_AGENT_WORKSPACE_DIR);
+    const workspaceRoot = resolveUserPath(cfg.workspaceRoot);
+    const scopeKey = resolveSandboxScopeKey(cfg.scope, rawSessionKey);
+    const sandboxWorkspaceDir = cfg.scope === "shared" ? workspaceRoot : resolveSandboxWorkspaceDir(workspaceRoot, scopeKey);
+    const workspaceDir = cfg.workspaceAccess === "rw" ? agentWorkspaceDir : sandboxWorkspaceDir;
+    if (workspaceDir === sandboxWorkspaceDir) {
+        await ensureSandboxWorkspace(sandboxWorkspaceDir, agentWorkspaceDir, params.config?.agents?.defaults?.skipBootstrap);
+        if (cfg.workspaceAccess !== "rw") {
+            try {
+                await syncSkillsToWorkspace({
+                    sourceWorkspaceDir: agentWorkspaceDir,
+                    targetWorkspaceDir: sandboxWorkspaceDir,
+                    config: params.config,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : JSON.stringify(error);
+                defaultRuntime.error?.(`Sandbox skill sync failed: ${message}`);
+            }
+        }
+    }
+    else {
+        await fs.mkdir(workspaceDir, { recursive: true });
+    }
+    return {
+        workspaceDir,
+        containerWorkdir: cfg.docker.workdir,
+    };
+}

package/dist/agents/sandbox/docker.d.ts

@@ -0,0 +1,28 @@
+import type { SandboxConfig, SandboxDockerConfig } from "./types.js";
+export declare function execDocker(args: string[], opts?: {
+    allowFailure?: boolean;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+    code: number;
+}>;
+export declare function readDockerPort(containerName: string, port: number): Promise<number | null>;
+export declare function ensureDockerImage(image: string): Promise<void>;
+export declare function dockerContainerState(name: string): Promise<{
+    exists: boolean;
+    running: boolean;
+}>;
+export declare function buildSandboxCreateArgs(params: {
+    name: string;
+    cfg: SandboxDockerConfig;
+    scopeKey: string;
+    createdAtMs?: number;
+    labels?: Record<string, string>;
+    configHash?: string;
+}): string[];
+export declare function ensureSandboxContainer(params: {
+    sessionKey: string;
+    workspaceDir: string;
+    agentWorkspaceDir: string;
+    cfg: SandboxConfig;
+}): Promise<string>;