@celestea/tools 2.7.1

package/dist/browser/memory-guard.js

@@ -0,0 +1,210 @@
+/**
+ * F4 step 2b: the memory backstop for an RLIMIT_AS-exempted browser.
+ *
+ * Exempting RLIMIT_AS (step 2a) removes the sandbox's only virtual-memory
+ * bound, so this module re-establishes a REAL one, in this order:
+ *
+ *   1. **cgroup v2 memory.max** — exact and kernel-enforced, but only when the
+ *      service's cgroup is delegated (writable). Measured on the target host:
+ *      /sys/fs/cgroup is read-only (mkdir -> EACCES), so this path is attempted
+ *      and honestly reported as unavailable.
+ *   2. **bounded RSS watchdog** — sample the process tree's VmRSS on an interval
+ *      and SIGKILL the tree when it exceeds the cap. This is BOUNDED but not
+ *      instantaneous: a fast allocator can overshoot by one sampling window.
+ *   3. **none** — no /proc, no pid: reported as "none" with the reason. Never
+ *      silently claimed as protected.
+ *
+ * The guard is deliberately injectable (readRssKb / killTree / cgroupRoot) so
+ * the watchdog logic is unit-tested without allocating real memory.
+ */
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** Default cap: 1 GiB of RSS for one browser tree. */
+export const DEFAULT_BROWSER_MEMORY_MB = 1024;
+/** Default sampling window. */
+export const DEFAULT_RSS_INTERVAL_MS = 500;
+/** Arm the strongest available backstop; always returns a truthful status. */
+export function armMemoryGuard(options) {
+    const pid = options.pid;
+    const limitMb = options.limitMb;
+    if (pid === null || pid === undefined)
+        return noneGuard("no pid: nothing to watch");
+    const cgroup = tryCgroupGuard(pid, limitMb, options);
+    if (cgroup !== null)
+        return cgroup;
+    return rssGuard(pid, limitMb, options);
+}
+/** Attempt cgroup v2 memory.max; null when the hierarchy is not writable. */
+function tryCgroupGuard(pid, limitMb, options) {
+    const root = options.cgroupRoot ?? "/sys/fs/cgroup";
+    const path = options.cgroupPath === undefined ? readOwnCgroupPath() : options.cgroupPath;
+    if (path === null)
+        return null;
+    const dir = join(root, path, "celestea-browser-" + pid);
+    try {
+        mkdirSync(dir, { recursive: false });
+        writeFileSync(join(dir, "memory.max"), String(limitMb * 1024 * 1024));
+        writeFileSync(join(dir, "cgroup.procs"), String(pid));
+    }
+    catch {
+        // Not delegated / read-only / already exists: clean up and fall back.
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            /* best effort */
+        }
+        return null;
+    }
+    const status = {
+        kind: "cgroup-v2",
+        limit_mb: limitMb,
+        detail: "cgroup v2 memory.max=" + limitMb + "MiB at " + dir + " (kernel-enforced)",
+        killed: false,
+    };
+    return {
+        status: () => ({ ...status }),
+        dispose: () => {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                /* the kernel keeps the cgroup until the last task leaves */
+            }
+        },
+    };
+}
+/** Read this process's own cgroup v2 path from /proc/self/cgroup. */
+export function readOwnCgroupPath(procRoot = "/proc") {
+    try {
+        const text = readFileSync(join(procRoot, "self", "cgroup"), "utf8");
+        for (const line of text.split("\n")) {
+            const parts = line.split(":");
+            if (parts.length >= 3 && parts[0] === "0")
+                return parts[2] ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/** Bounded RSS watchdog: sample, kill on overshoot, report the window. */
+function rssGuard(pid, limitMb, options) {
+    const readRss = options.readRssKb ?? readTreeRssKb;
+    const killTree = options.killTree ?? defaultKillTree;
+    const intervalMs = options.intervalMs ?? DEFAULT_RSS_INTERVAL_MS;
+    let killed = false;
+    let lastKb = null;
+    const timer = setInterval(() => {
+        if (killed)
+            return;
+        const kb = readRss(pid);
+        lastKb = kb;
+        if (kb !== null && kb / 1024 > limitMb) {
+            killed = true;
+            killTree(pid);
+            clearInterval(timer);
+        }
+    }, intervalMs);
+    timer.unref();
+    return {
+        status: () => ({
+            kind: "rss-watchdog",
+            limit_mb: limitMb,
+            detail: "cgroup v2 memory.max unavailable (read-only hierarchy); sampling the tree's VmRSS every " +
+                intervalMs +
+                "ms against a " +
+                limitMb +
+                "MiB cap" +
+                (lastKb === null ? "" : " (last sample " + Math.round(lastKb / 1024) + "MiB)"),
+            killed,
+        }),
+        dispose: () => clearInterval(timer),
+    };
+}
+function noneGuard(detail) {
+    return {
+        status: () => ({ kind: "none", limit_mb: null, detail, killed: false }),
+        dispose: () => undefined,
+    };
+}
+/** Sum VmRSS (KiB) over the pid and every descendant, bounded. */
+export function readTreeRssKb(pid, procRoot = "/proc", maxPids = 2000) {
+    const seen = new Set();
+    const queue = [pid];
+    let total = 0;
+    let read = 0;
+    while (queue.length > 0 && seen.size < maxPids) {
+        const current = queue.shift();
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        const kb = readVmRssKb(current, procRoot);
+        if (kb !== null) {
+            total += kb;
+            read += 1;
+        }
+        for (const child of childPids(current, procRoot))
+            queue.push(child);
+    }
+    return read === 0 ? null : total;
+}
+function readVmRssKb(pid, procRoot) {
+    try {
+        const text = readFileSync(join(procRoot, String(pid), "status"), "utf8");
+        for (const line of text.split("\n")) {
+            if (!line.startsWith("VmRSS:"))
+                continue;
+            const value = Number(line.replace(/[^0-9]/g, ""));
+            return Number.isFinite(value) ? value : null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/** Direct children of a pid via /proc/<pid>/task/<tid>/children. */
+function childPids(pid, procRoot) {
+    const out = [];
+    const taskDir = join(procRoot, String(pid), "task");
+    let tasks;
+    try {
+        tasks = readdirSync(taskDir);
+    }
+    catch {
+        return out;
+    }
+    for (const tid of tasks) {
+        try {
+            const text = readFileSync(join(taskDir, tid, "children"), "utf8").trim();
+            if (text === "")
+                continue;
+            for (const token of text.split(/\s+/)) {
+                const child = Number(token);
+                if (Number.isInteger(child) && child > 0)
+                    out.push(child);
+            }
+        }
+        catch {
+            /* the task vanished mid-scan */
+        }
+    }
+    return out;
+}
+function defaultKillTree(pid) {
+    try {
+        process.kill(-pid, "SIGKILL");
+        return;
+    }
+    catch {
+        /* not a group leader */
+    }
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch {
+        /* already gone */
+    }
+}

package/dist/browser/session.d.ts

@@ -0,0 +1,146 @@
+/**
+ * F4 step 2b: one SESSION's headless browser, launched THROUGH the sandbox.
+ *
+ * Why through the sandbox: the browser is the one workload that must run with
+ * `noAddressSpaceLimit: true` (step 2a) and, on the bwrap provider, with a
+ * SHARED network namespace (the DevTools ws:// endpoint lives on 127.0.0.1 and
+ * would be unreachable inside `--unshare-all`). Both facts are asserted here,
+ * never inferred: `spawned.sandbox.net_isolated === true` refuses the call with
+ * a structured `network_required` error instead of silently failing to connect.
+ *
+ * Lifecycle: the browser child is registered in the session ProcessRegistry, so
+ * the host's existing shutdown hook (`processes.dispose()`) reaps it; the
+ * manager ALSO exposes `dispose()` and removes the profile dir as soon as the
+ * child exits. No orphan is left behind.
+ *
+ * The result carries an explicit isolation block: the RLIMIT_AS exemption and
+ * the memory backstop are stated in the VALUE, so a caller can never mistake an
+ * exempted call for a sandboxed one.
+ */
+import type { ImageRef, Sandbox, SandboxChild, SandboxMeta } from "@celestea/core";
+import type { AttachmentStore } from "../attachments/store.js";
+import type { ProcessRegistry } from "../process/registry.js";
+import { CdpClient } from "./cdp.js";
+import { type MemoryGuardStatus } from "./memory-guard.js";
+import type { BoundingBox } from "./types.js";
+/** Default cap on rendered AX nodes / bytes (step 1's limits). */
+export declare const DEFAULT_BROWSER_MAX_NODES = 200;
+export declare const DEFAULT_BROWSER_MAX_BYTES: number;
+/** Default wait for the DevTools endpoint. */
+export declare const DEFAULT_BROWSER_STARTUP_MS = 20000;
+/** Grace between terminate() and kill() when disposing. */
+export declare const DEFAULT_BROWSER_DISPOSE_GRACE_MS = 3000;
+/** How long to wait for document.readyState after navigate. */
+export declare const DEFAULT_NAVIGATE_TIMEOUT_MS = 20000;
+export interface BrowserViewport {
+    width: number;
+    height: number;
+}
+export interface BrowserActRequest {
+    action: "click" | "type" | "key" | "scroll";
+    ref?: string;
+    text?: string;
+    key?: string;
+    deltaX?: number;
+    deltaY?: number;
+}
+/** The isolation facts of the running browser (explicit, never inferred). */
+export interface BrowserIsolation {
+    provider: string;
+    net_isolated: boolean;
+    tmp_private: boolean;
+    seccomp: boolean;
+    /** Always "exempted" for a browser: RLIMIT_AS is not applied. */
+    address_space_limit: "exempted";
+    /** The model-visible statement of that exemption. */
+    address_space_note: string;
+    memory_guard: MemoryGuardStatus;
+}
+export interface BrowserRef {
+    ref: string;
+    role: string;
+    name: string;
+    backend_dom_node_id: number | null;
+    box: BoundingBox | null;
+}
+export interface BrowserSnapshotValue {
+    text: string;
+    refs: BrowserRef[];
+    truncated: boolean;
+    truncation_reason: string | null;
+    total_nodes: number;
+    included_nodes: number;
+}
+export interface BrowserScreenshot {
+    attachment_id: string;
+    media_type: string;
+    width: number;
+    height: number;
+    bytes: number;
+}
+export interface BrowserResult {
+    ok: true;
+    url: string;
+    title: string;
+    snapshot: BrowserSnapshotValue;
+    screenshot: BrowserScreenshot | null;
+    attachments: ImageRef[];
+    isolation: BrowserIsolation;
+    notes: string[];
+}
+/** The model-visible sentence that must appear on every browser result. */
+export declare const ADDRESS_SPACE_NOTE = "RLIMIT_AS is EXEMPTED for this browser process (noAddressSpaceLimit=true): its virtual address space is NOT bounded by the sandbox.";
+export interface BrowserManagerOptions {
+    sandbox: Sandbox;
+    processes?: ProcessRegistry;
+    attachments?: AttachmentStore | null;
+    findExecutable?: () => string | null;
+    attach?: (endpoint: string) => Promise<CdpClient>;
+    /** Test seam: bypass the sandbox (the real path always passes the flag). */
+    spawn?: (command: string) => Promise<{
+        child: SandboxChild;
+        sandbox: SandboxMeta;
+    }>;
+    startupTimeoutMs?: number;
+    navigateTimeoutMs?: number;
+    disposeGraceMs?: number;
+    memoryLimitMb?: number;
+    maxNodes?: number;
+    maxBytes?: number;
+}
+/** Per-session browser owner. One instance is shared by both browser tools. */
+export declare class BrowserManager {
+    private readonly options;
+    private session;
+    private disposed;
+    constructor(options: BrowserManagerOptions);
+    /** Open (or reuse) the page and return its snapshot + screenshot. */
+    open(url: string, viewport?: BrowserViewport): Promise<BrowserResult>;
+    /** Act on the page opened by [open]; returns the updated snapshot. */
+    act(request: BrowserActRequest): Promise<BrowserResult>;
+    /** Reclaim the browser: terminate the tree, wait, kill, remove the profile. */
+    dispose(): Promise<void>;
+    /** True while a live browser is attached (diagnostics / tests). */
+    get running(): boolean;
+    private ensure;
+    private spawnBrowser;
+    private browserCommand;
+    private readEndpoint;
+    private navigate;
+    private perform;
+    private click;
+    private typeText;
+    private key;
+    private scroll;
+    private boxOf;
+    private capture;
+    private screenshot;
+    private isolation;
+    private notes;
+    private get startupMs();
+    private get navigateMs();
+    private get graceMs();
+    private get memoryLimitMb();
+    private get maxNodes();
+    private get maxBytes();
+}