@poolzin/pool-bot 2026.2.25 → 2026.2.26

package/dist/agents/sandbox/browser.js

@@ -1,23 +1,31 @@
+import crypto from "node:crypto";
 import { startBrowserBridgeServer, stopBrowserBridgeServer } from "../../browser/bridge-server.js";
 import { resolveProfile } from "../../browser/config.js";
-import { DEFAULT_BROWSER_EVALUATE_ENABLED, DEFAULT_CLAWD_BROWSER_COLOR, } from "../../browser/constants.js";
+import { DEFAULT_BROWSER_EVALUATE_ENABLED, DEFAULT_CLAWD_BROWSER_COLOR, DEFAULT_CLAWD_BROWSER_PROFILE_NAME, } from "../../browser/constants.js";
+import { defaultRuntime } from "../../runtime.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 { computeSandboxBrowserConfigHash } from "./config-hash.js";
+import { resolveSandboxBrowserDockerCreateConfig } from "./config.js";
+import { DEFAULT_SANDBOX_BROWSER_IMAGE, SANDBOX_AGENT_WORKSPACE_MOUNT, SANDBOX_BROWSER_SECURITY_HASH_EPOCH, } from "./constants.js";
+import { buildSandboxCreateArgs, dockerContainerState, execDocker, readDockerContainerEnvVar, readDockerContainerLabel, readDockerPort, } from "./docker.js";
+import { buildNoVncDirectUrl, buildNoVncObserverTokenUrl, consumeNoVncObserverToken, generateNoVncPassword, isNoVncEnabled, NOVNC_PASSWORD_ENV_KEY, issueNoVncObserverToken, } from "./novnc-auth.js";
+import { readBrowserRegistry, updateBrowserRegistry } from "./registry.js";
+import { resolveSandboxAgentId, slugifySessionKey } from "./shared.js";
 import { isToolAllowed } from "./tool-policy.js";
+const HOT_BROWSER_WINDOW_MS = 5 * 60 * 1000;
+const CDP_SOURCE_RANGE_ENV_KEY = "POOLBOT_BROWSER_CDP_SOURCE_RANGE";
 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);
+            const t = setTimeout(ctrl.abort.bind(ctrl), 1000);
             try {
                 const res = await fetch(url, { signal: ctrl.signal });
-                if (res.ok)
+                if (res.ok) {
                     return true;
+                }
             }
             finally {
                 clearTimeout(t);
@@ -46,9 +54,13 @@ function buildSandboxBrowserResolvedConfig(params) {
         headless: params.headless,
         noSandbox: false,
         attachOnly: true,
-        defaultProfile: "clawd",
+        defaultProfile: DEFAULT_CLAWD_BROWSER_PROFILE_NAME,
+        extraArgs: [],
         profiles: {
-            clawd: { cdpPort: params.cdpPort, color: DEFAULT_CLAWD_BROWSER_COLOR },
+            [DEFAULT_CLAWD_BROWSER_PROFILE_NAME]: {
+                cdpPort: params.cdpPort,
+                color: DEFAULT_CLAWD_BROWSER_COLOR,
+            },
         },
     };
 }
@@ -56,26 +68,115 @@ async function ensureSandboxBrowserImage(image) {
     const result = await execDocker(["image", "inspect", image], {
         allowFailure: true,
     });
-    if (result.code === 0)
+    if (result.code === 0) {
         return;
+    }
     throw new Error(`Sandbox browser image not found: ${image}. Build it with scripts/sandbox-browser-setup.sh.`);
 }
+async function ensureDockerNetwork(network) {
+    const normalized = network.trim().toLowerCase();
+    if (!normalized ||
+        normalized === "bridge" ||
+        normalized === "none" ||
+        normalized.startsWith("container:")) {
+        return;
+    }
+    const inspect = await execDocker(["network", "inspect", network], { allowFailure: true });
+    if (inspect.code === 0) {
+        return;
+    }
+    await execDocker(["network", "create", "--driver", "bridge", network]);
+}
 export async function ensureSandboxBrowser(params) {
-    if (!params.cfg.browser.enabled)
+    if (!params.cfg.browser.enabled) {
         return null;
-    if (!isToolAllowed(params.cfg.tools, "browser"))
+    }
+    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 browserImage = params.cfg.browser.image ?? DEFAULT_SANDBOX_BROWSER_IMAGE;
+    const cdpSourceRange = params.cfg.browser.cdpSourceRange?.trim() || undefined;
+    const browserDockerCfg = resolveSandboxBrowserDockerCreateConfig({
+        docker: params.cfg.docker,
+        browser: { ...params.cfg.browser, image: browserImage },
+    });
+    const expectedHash = computeSandboxBrowserConfigHash({
+        docker: browserDockerCfg,
+        browser: {
+            cdpPort: params.cfg.browser.cdpPort,
+            vncPort: params.cfg.browser.vncPort,
+            noVncPort: params.cfg.browser.noVncPort,
+            headless: params.cfg.browser.headless,
+            enableNoVnc: params.cfg.browser.enableNoVnc,
+            cdpSourceRange,
+        },
+        securityEpoch: SANDBOX_BROWSER_SECURITY_HASH_EPOCH,
+        workspaceAccess: params.cfg.workspaceAccess,
+        workspaceDir: params.workspaceDir,
+        agentWorkspaceDir: params.agentWorkspaceDir,
+    });
+    const now = Date.now();
+    let hasContainer = state.exists;
+    let running = state.running;
+    let currentHash = null;
+    let hashMismatch = false;
+    const noVncEnabled = isNoVncEnabled(params.cfg.browser);
+    let noVncPassword;
+    if (hasContainer) {
+        if (noVncEnabled) {
+            noVncPassword =
+                (await readDockerContainerEnvVar(containerName, NOVNC_PASSWORD_ENV_KEY)) ?? undefined;
+        }
+        const registry = await readBrowserRegistry();
+        const registryEntry = registry.entries.find((entry) => entry.containerName === containerName);
+        currentHash = await readDockerContainerLabel(containerName, "poolbot.configHash");
+        hashMismatch = !currentHash || currentHash !== expectedHash;
+        if (!currentHash) {
+            currentHash = registryEntry?.configHash ?? null;
+            hashMismatch = !currentHash || currentHash !== expectedHash;
+        }
+        if (hashMismatch) {
+            const lastUsedAtMs = registryEntry?.lastUsedAtMs;
+            const isHot = running && (typeof lastUsedAtMs !== "number" || now - lastUsedAtMs < HOT_BROWSER_WINDOW_MS);
+            if (isHot) {
+                const hint = (() => {
+                    if (params.cfg.scope === "session") {
+                        return `poolbot sandbox recreate --browser --session ${params.scopeKey}`;
+                    }
+                    if (params.cfg.scope === "agent") {
+                        const agentId = resolveSandboxAgentId(params.scopeKey) ?? "main";
+                        return `poolbot sandbox recreate --browser --agent ${agentId}`;
+                    }
+                    return "poolbot sandbox recreate --browser --all";
+                })();
+                defaultRuntime.log(`Sandbox browser config changed for ${containerName} (recently used). Recreate to apply: ${hint}`);
+            }
+            else {
+                await execDocker(["rm", "-f", containerName], { allowFailure: true });
+                hasContainer = false;
+                running = false;
+            }
+        }
+    }
+    if (!hasContainer) {
+        if (noVncEnabled) {
+            noVncPassword = generateNoVncPassword();
+        }
+        await ensureDockerNetwork(browserDockerCfg.network);
+        await ensureSandboxBrowserImage(browserImage);
         const args = buildSandboxCreateArgs({
             name: containerName,
-            cfg: params.cfg.docker,
+            cfg: browserDockerCfg,
             scopeKey: params.scopeKey,
-            labels: { "poolbot.sandboxBrowser": "1" },
+            labels: {
+                "poolbot.sandboxBrowser": "1",
+                "poolbot.browserConfigEpoch": SANDBOX_BROWSER_SECURITY_HASH_EPOCH,
+            },
+            configHash: expectedHash,
         });
         const mainMountSuffix = params.cfg.workspaceAccess === "ro" && params.workspaceDir === params.agentWorkspaceDir
             ? ":ro"
@@ -86,48 +187,75 @@ export async function ensureSandboxBrowser(params) {
             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) {
+        if (noVncEnabled) {
             args.push("-p", `127.0.0.1::${params.cfg.browser.noVncPort}`);
         }
         args.push("-e", `POOLBOT_BROWSER_HEADLESS=${params.cfg.browser.headless ? "1" : "0"}`);
-        args.push("-e", `CLAWDBOT_BROWSER_HEADLESS=${params.cfg.browser.headless ? "1" : "0"}`);
         args.push("-e", `POOLBOT_BROWSER_ENABLE_NOVNC=${params.cfg.browser.enableNoVnc ? "1" : "0"}`);
-        args.push("-e", `CLAWDBOT_BROWSER_ENABLE_NOVNC=${params.cfg.browser.enableNoVnc ? "1" : "0"}`);
         args.push("-e", `POOLBOT_BROWSER_CDP_PORT=${params.cfg.browser.cdpPort}`);
-        args.push("-e", `CLAWDBOT_BROWSER_CDP_PORT=${params.cfg.browser.cdpPort}`);
+        if (cdpSourceRange) {
+            args.push("-e", `${CDP_SOURCE_RANGE_ENV_KEY}=${cdpSourceRange}`);
+        }
         args.push("-e", `POOLBOT_BROWSER_VNC_PORT=${params.cfg.browser.vncPort}`);
-        args.push("-e", `CLAWDBOT_BROWSER_VNC_PORT=${params.cfg.browser.vncPort}`);
         args.push("-e", `POOLBOT_BROWSER_NOVNC_PORT=${params.cfg.browser.noVncPort}`);
-        args.push("-e", `CLAWDBOT_BROWSER_NOVNC_PORT=${params.cfg.browser.noVncPort}`);
-        args.push(params.cfg.browser.image);
+        if (noVncEnabled && noVncPassword) {
+            args.push("-e", `${NOVNC_PASSWORD_ENV_KEY}=${noVncPassword}`);
+        }
+        args.push(browserImage);
         await execDocker(args);
         await execDocker(["start", containerName]);
     }
-    else if (!state.running) {
+    else if (!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
+    const mappedNoVnc = noVncEnabled
         ? await readDockerPort(containerName, params.cfg.browser.noVncPort)
         : null;
+    if (noVncEnabled && !noVncPassword) {
+        noVncPassword =
+            (await readDockerContainerEnvVar(containerName, NOVNC_PASSWORD_ENV_KEY)) ?? undefined;
+    }
     const existing = BROWSER_BRIDGES.get(params.scopeKey);
-    const existingProfile = existing ? resolveProfile(existing.bridge.state.resolved, "clawd") : null;
+    const existingProfile = existing
+        ? resolveProfile(existing.bridge.state.resolved, DEFAULT_CLAWD_BROWSER_PROFILE_NAME)
+        : null;
+    let desiredAuthToken = params.bridgeAuth?.token?.trim() || undefined;
+    let desiredAuthPassword = params.bridgeAuth?.password?.trim() || undefined;
+    if (!desiredAuthToken && !desiredAuthPassword) {
+        // Always require auth for the sandbox bridge server, even if gateway auth
+        // mode doesn't produce a shared secret (e.g. trusted-proxy).
+        // Keep it stable across calls by reusing the existing bridge auth.
+        desiredAuthToken = existing?.authToken;
+        desiredAuthPassword = existing?.authPassword;
+        if (!desiredAuthToken && !desiredAuthPassword) {
+            desiredAuthToken = crypto.randomBytes(24).toString("hex");
+        }
+    }
     const shouldReuse = existing && existing.containerName === containerName && existingProfile?.cdpPort === mappedCdp;
+    const authMatches = !existing ||
+        (existing.authToken === desiredAuthToken && existing.authPassword === desiredAuthPassword);
     if (existing && !shouldReuse) {
         await stopBrowserBridgeServer(existing.bridge.server).catch(() => undefined);
         BROWSER_BRIDGES.delete(params.scopeKey);
     }
+    if (existing && shouldReuse && !authMatches) {
+        await stopBrowserBridgeServer(existing.bridge.server).catch(() => undefined);
+        BROWSER_BRIDGES.delete(params.scopeKey);
+    }
     const bridge = (() => {
-        if (shouldReuse && existing)
+        if (shouldReuse && authMatches && existing) {
             return existing.bridge;
+        }
         return null;
     })();
     const ensureBridge = async () => {
-        if (bridge)
+        if (bridge) {
             return bridge;
+        }
         const onEnsureAttachTarget = params.cfg.browser.autoStart
             ? async () => {
                 const state = await dockerContainerState(containerName);
@@ -150,28 +278,37 @@ export async function ensureSandboxBrowser(params) {
                 headless: params.cfg.browser.headless,
                 evaluateEnabled: params.evaluateEnabled ?? DEFAULT_BROWSER_EVALUATE_ENABLED,
             }),
+            authToken: desiredAuthToken,
+            authPassword: desiredAuthPassword,
             onEnsureAttachTarget,
+            resolveSandboxNoVncToken: consumeNoVncObserverToken,
         });
     };
     const resolvedBridge = await ensureBridge();
-    if (!shouldReuse) {
+    if (!shouldReuse || !authMatches) {
         BROWSER_BRIDGES.set(params.scopeKey, {
             bridge: resolvedBridge,
             containerName,
+            authToken: desiredAuthToken,
+            authPassword: desiredAuthPassword,
         });
     }
-    const now = Date.now();
     await updateBrowserRegistry({
         containerName,
         sessionKey: params.scopeKey,
         createdAtMs: now,
         lastUsedAtMs: now,
-        image: params.cfg.browser.image,
+        image: browserImage,
+        configHash: hashMismatch && running ? (currentHash ?? undefined) : expectedHash,
         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`
+    const noVncUrl = mappedNoVnc && noVncEnabled
+        ? (() => {
+            const directUrl = buildNoVncDirectUrl(mappedNoVnc, noVncPassword);
+            const token = issueNoVncObserverToken({ url: directUrl });
+            return buildNoVncObserverTokenUrl(resolvedBridge.baseUrl, token);
+        })()
         : undefined;
     return {
         bridgeUrl: resolvedBridge.baseUrl,

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

@@ -1,45 +1,32 @@
-import crypto from "node:crypto";
-function isPrimitive(value) {
-    return value === null || (typeof value !== "object" && typeof value !== "function");
-}
+import { hashTextSha256 } from "./hash.js";
 function normalizeForHash(value) {
-    if (value === undefined)
+    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].sort((a, b) => primitiveToString(a).localeCompare(primitiveToString(b)));
-        }
-        return normalized;
+        return value.map(normalizeForHash).filter((item) => item !== undefined);
     }
     if (value && typeof value === "object") {
-        const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+        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)
+            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) {
+    return computeHash(input);
+}
+export function computeSandboxBrowserConfigHash(input) {
+    return computeHash(input);
+}
+function computeHash(input) {
     const payload = normalizeForHash(input);
     const raw = JSON.stringify(payload);
-    return crypto.createHash("sha1").update(raw).digest("hex");
+    return hashTextSha256(raw);
 }

package/dist/agents/sandbox/config.js

@@ -1,9 +1,22 @@
 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 { DEFAULT_SANDBOX_BROWSER_AUTOSTART_TIMEOUT_MS, DEFAULT_SANDBOX_BROWSER_CDP_PORT, DEFAULT_SANDBOX_BROWSER_IMAGE, DEFAULT_SANDBOX_BROWSER_NETWORK, 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 resolveSandboxBrowserDockerCreateConfig(params) {
+    const browserNetwork = params.browser.network.trim();
+    const base = {
+        ...params.docker,
+        // Browser container needs network access for Chrome, downloads, etc.
+        network: browserNetwork || DEFAULT_SANDBOX_BROWSER_NETWORK,
+        // For hashing and consistency, treat browser image as the docker image even though we
+        // pass it separately as the final `docker create` argument.
+        image: params.browser.image,
+    };
+    return params.browser.binds !== undefined ? { ...base, binds: params.browser.binds } : base;
+}
 export function resolveSandboxScope(params) {
-    if (params.scope)
+    if (params.scope) {
         return params.scope;
+    }
     if (typeof params.perSession === "boolean") {
         return params.perSession ? "session" : "shared";
     }
@@ -47,13 +60,18 @@ export function resolveSandboxDockerConfig(params) {
 export function resolveSandboxBrowserConfig(params) {
     const agentBrowser = params.scope === "shared" ? undefined : params.agentBrowser;
     const globalBrowser = params.globalBrowser;
+    const binds = [...(globalBrowser?.binds ?? []), ...(agentBrowser?.binds ?? [])];
+    // Treat `binds: []` as an explicit override, so it can disable `docker.binds` for the browser container.
+    const bindsConfigured = globalBrowser?.binds !== undefined || agentBrowser?.binds !== undefined;
     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,
+        network: agentBrowser?.network ?? globalBrowser?.network ?? DEFAULT_SANDBOX_BROWSER_NETWORK,
         cdpPort: agentBrowser?.cdpPort ?? globalBrowser?.cdpPort ?? DEFAULT_SANDBOX_BROWSER_CDP_PORT,
+        cdpSourceRange: agentBrowser?.cdpSourceRange ?? globalBrowser?.cdpSourceRange,
         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,
@@ -63,6 +81,7 @@ export function resolveSandboxBrowserConfig(params) {
         autoStartTimeoutMs: agentBrowser?.autoStartTimeoutMs ??
             globalBrowser?.autoStartTimeoutMs ??
             DEFAULT_SANDBOX_BROWSER_AUTOSTART_TIMEOUT_MS,
+        binds: bindsConfigured ? binds : undefined,
     };
 }
 export function resolveSandboxPruneConfig(params) {

package/dist/agents/sandbox/constants.js

@@ -43,3 +43,5 @@ const resolvedSandboxStateDir = STATE_DIR ?? path.join(os.homedir(), ".poolbot")
 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");
+export const SANDBOX_BROWSER_SECURITY_HASH_EPOCH = "2026-02-21-novnc-auth-default";
+export const DEFAULT_SANDBOX_BROWSER_NETWORK = "poolbot-sandbox-browser";

package/dist/agents/sandbox/docker.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { createSubsystemLogger } from "../../logging/subsystem.js";
 import { sanitizeEnvVars } from "./sanitize-env-vars.js";
 function createAbortError() {
     const err = new Error("Aborted");
@@ -82,6 +83,7 @@ import { DEFAULT_SANDBOX_IMAGE, SANDBOX_AGENT_WORKSPACE_MOUNT } from "./constant
 import { readRegistry, updateRegistry } from "./registry.js";
 import { resolveSandboxAgentId, resolveSandboxScopeKey, slugifySessionKey } from "./shared.js";
 import { validateSandboxSecurity } from "./validate-sandbox-security.js";
+const log = createSubsystemLogger("docker");
 const HOT_CONTAINER_WINDOW_MS = 5 * 60 * 1000;
 export async function execDocker(args, opts) {
     const result = await execDockerRaw(args, opts);
@@ -102,6 +104,18 @@ export async function readDockerContainerLabel(containerName, label) {
     }
     return raw;
 }
+export async function readDockerContainerEnvVar(containerName, envVar) {
+    const result = await execDocker(["inspect", "-f", "{{range .Config.Env}}{{println .}}{{end}}", containerName], { allowFailure: true });
+    if (result.code !== 0) {
+        return null;
+    }
+    for (const line of result.stdout.split(/\r?\n/)) {
+        if (line.startsWith(`${envVar}=`)) {
+            return line.slice(envVar.length + 1);
+        }
+    }
+    return null;
+}
 export async function readDockerPort(containerName, port) {
     const result = await execDocker(["port", containerName, `${port}/tcp`], {
         allowFailure: true,
@@ -212,10 +226,10 @@ export function buildSandboxCreateArgs(params) {
     }
     const envSanitization = sanitizeEnvVars(params.cfg.env ?? {});
     if (envSanitization.blocked.length > 0) {
-        console.warn("[Security] Blocked sensitive environment variables:", envSanitization.blocked.join(", "));
+        log.warn(`Blocked sensitive environment variables: ${envSanitization.blocked.join(", ")}`);
     }
     if (envSanitization.warnings.length > 0) {
-        console.warn("[Security] Suspicious environment variables:", envSanitization.warnings);
+        log.warn(`Suspicious environment variables: ${envSanitization.warnings.join(", ")}`);
     }
     for (const [key, value] of Object.entries(envSanitization.allowed)) {
         args.push("--env", `${key}=${value}`);

package/dist/agents/sandbox/novnc-auth.js

@@ -0,0 +1,62 @@
+import crypto from "node:crypto";
+export const NOVNC_PASSWORD_ENV_KEY = "POOLBOT_BROWSER_NOVNC_PASSWORD";
+const NOVNC_TOKEN_TTL_MS = 5 * 60 * 1000;
+const NO_VNC_OBSERVER_TOKENS = new Map();
+function pruneExpiredNoVncObserverTokens(now) {
+    for (const [token, entry] of NO_VNC_OBSERVER_TOKENS) {
+        if (entry.expiresAt <= now) {
+            NO_VNC_OBSERVER_TOKENS.delete(token);
+        }
+    }
+}
+export function isNoVncEnabled(params) {
+    return params.enableNoVnc && !params.headless;
+}
+export function generateNoVncPassword() {
+    // VNC auth uses an 8-char password max.
+    return crypto.randomBytes(4).toString("hex");
+}
+export function buildNoVncDirectUrl(port, password) {
+    const query = new URLSearchParams({
+        autoconnect: "1",
+        resize: "remote",
+    });
+    if (password?.trim()) {
+        query.set("password", password);
+    }
+    return `http://127.0.0.1:${port}/vnc.html?${query.toString()}`;
+}
+export function issueNoVncObserverToken(params) {
+    const now = params.nowMs ?? Date.now();
+    pruneExpiredNoVncObserverTokens(now);
+    const token = crypto.randomBytes(24).toString("hex");
+    NO_VNC_OBSERVER_TOKENS.set(token, {
+        url: params.url,
+        expiresAt: now + Math.max(1, params.ttlMs ?? NOVNC_TOKEN_TTL_MS),
+    });
+    return token;
+}
+export function consumeNoVncObserverToken(token, nowMs) {
+    const now = nowMs ?? Date.now();
+    pruneExpiredNoVncObserverTokens(now);
+    const normalized = token.trim();
+    if (!normalized) {
+        return null;
+    }
+    const entry = NO_VNC_OBSERVER_TOKENS.get(normalized);
+    if (!entry) {
+        return null;
+    }
+    NO_VNC_OBSERVER_TOKENS.delete(normalized);
+    if (entry.expiresAt <= now) {
+        return null;
+    }
+    return entry.url;
+}
+export function buildNoVncObserverTokenUrl(baseUrl, token) {
+    const query = new URLSearchParams({ token });
+    return `${baseUrl}/sandbox/novnc?${query.toString()}`;
+}
+export function resetNoVncObserverTokensForTests() {
+    NO_VNC_OBSERVER_TOKENS.clear();
+}

package/dist/agents/sandbox/sanitize-env-vars.js

@@ -28,7 +28,7 @@ const ALLOWED_ENV_VAR_PATTERNS = [
     /^TZ$/i,
     /^NODE_ENV$/i,
 ];
-function validateEnvVarValue(value) {
+export function validateEnvVarValue(value) {
     if (value.includes("\0")) {
         return "Contains null bytes";
     }

package/dist/agents/sandbox/shared.js

@@ -1,11 +1,11 @@
-import crypto from "node:crypto";
 import path from "node:path";
 import { normalizeAgentId } from "../../routing/session-key.js";
 import { resolveUserPath } from "../../utils.js";
 import { resolveAgentIdFromSessionKey } from "../agent-scope.js";
+import { hashTextSha256 } from "./hash.js";
 export function slugifySessionKey(value) {
     const trimmed = value.trim() || "session";
-    const hash = crypto.createHash("sha1").update(trimmed).digest("hex").slice(0, 8);
+    const hash = hashTextSha256(trimmed).slice(0, 8);
     const safe = trimmed
         .toLowerCase()
         .replace(/[^a-z0-9._-]+/g, "-")
@@ -20,19 +20,23 @@ export function resolveSandboxWorkspaceDir(root, sessionKey) {
 }
 export function resolveSandboxScopeKey(scope, sessionKey) {
     const trimmed = sessionKey.trim() || "main";
-    if (scope === "shared")
+    if (scope === "shared") {
         return "shared";
-    if (scope === "session")
+    }
+    if (scope === "session") {
         return trimmed;
+    }
     const agentId = resolveAgentIdFromSessionKey(trimmed);
     return `agent:${agentId}`;
 }
 export function resolveSandboxAgentId(scopeKey) {
     const trimmed = scopeKey.trim();
-    if (!trimmed || trimmed === "shared")
+    if (!trimmed || trimmed === "shared") {
         return undefined;
+    }
     const parts = trimmed.split(":").filter(Boolean);
-    if (parts[0] === "agent" && parts[1])
+    if (parts[0] === "agent" && parts[1]) {
         return normalizeAgentId(parts[1]);
+    }
     return resolveAgentIdFromSessionKey(trimmed);
 }

package/dist/agents/sandbox-paths.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { isNotFoundPathError, isPathInside } from "../infra/path-guards.js";
 const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
 const HTTP_URL_RE = /^https?:\/\//i;
 const DATA_URL_RE = /^data:/i;
@@ -70,12 +71,32 @@ export async function resolveSandboxedMediaSource(params) {
             throw new Error(`Invalid file:// URL for sandboxed media: ${raw}`);
         }
     }
-    const resolved = await assertSandboxPath({
+    const tmpMediaPath = await resolveAllowedTmpMediaPath({
+        candidate,
+        sandboxRoot: params.sandboxRoot,
+    });
+    if (tmpMediaPath) {
+        return tmpMediaPath;
+    }
+    const sandboxResult = await assertSandboxPath({
         filePath: candidate,
         cwd: params.sandboxRoot,
         root: params.sandboxRoot,
     });
-    return resolved.resolved;
+    return sandboxResult.resolved;
+}
+async function resolveAllowedTmpMediaPath(params) {
+    const candidateIsAbsolute = path.isAbsolute(expandPath(params.candidate));
+    if (!candidateIsAbsolute) {
+        return undefined;
+    }
+    const resolved = path.resolve(resolveSandboxInputPath(params.candidate, params.sandboxRoot));
+    const tmpDir = path.resolve(os.tmpdir());
+    if (!isPathInside(tmpDir, resolved)) {
+        return undefined;
+    }
+    await assertNoSymlinkEscape(path.relative(tmpDir, resolved), tmpDir);
+    return resolved;
 }
 async function assertNoSymlinkEscape(relative, root, options) {
     if (!relative) {
@@ -104,8 +125,7 @@ async function assertNoSymlinkEscape(relative, root, options) {
             }
         }
         catch (err) {
-            const anyErr = err;
-            if (anyErr.code === "ENOENT") {
+            if (isNotFoundPathError(err)) {
                 return;
             }
             throw err;
@@ -120,13 +140,6 @@ async function tryRealpath(value) {
         return path.resolve(value);
     }
 }
-function isPathInside(root, target) {
-    const relative = path.relative(root, target);
-    if (!relative || relative === "") {
-        return true;
-    }
-    return !(relative.startsWith("..") || path.isAbsolute(relative));
-}
 function shortPath(value) {
     if (value.startsWith(os.homedir())) {
         return `~${value.slice(os.homedir().length)}`;