humanish 0.105.0 → 0.106.0

package/dist/guest/runtime-desktop.js

@@ -0,0 +1,420 @@
+import { randomBytes, createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rm } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { chromium } from "playwright-core";
+import { createGuestDesktopNativeTools } from "./desktop-native.js";
+import { createGuestChromiumText } from "./chromium-text.js";
+import { createGuestBrowserTools } from "./browser-tools.js";
+import { createGuestDesktopExecutor } from "./desktop-executor.js";
+import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { GUEST_BOOTSTRAP_LIMITS, validateGuestInitialUrl } from "./bootstrap.js";
+import { startDesktopMedia, } from "./desktop-media.js";
+import { startDesktopRecorder } from "../evidence/desktop-recorder.js";
+import { createGuestProcesses, setupFailed } from "./runtime-processes.js";
+/** The guest image's fixed layout. Tests derive guest paths from it rather than spelling them. */
+export const GUEST_RUNTIME_PATHS = Object.freeze({
+    root: "/opt/humanish/control",
+    run: "/run/humanish",
+    home: "/home/humanish",
+});
+const GUEST_RUNTIME_ENV = Object.freeze({
+    PATH: "/usr/bin:/bin",
+    HOME: "/home/humanish",
+    USER: "humanish",
+    LOGNAME: "humanish",
+    LANG: "C.UTF-8",
+    LC_ALL: "C.UTF-8",
+    DISPLAY: ":0",
+    XAUTHORITY: "/run/humanish/Xauthority",
+    XDG_RUNTIME_DIR: "/run/humanish/xdg",
+    XDG_CACHE_HOME: "/home/humanish/.cache",
+    XDG_CONFIG_HOME: "/home/humanish/.config",
+    TMPDIR: "/tmp",
+});
+const CONFIG_SHA = "4ae1c52eab748a3624b3948ce792647be258caba70c8c72038b9a43be6459552";
+const XVFB_ARGS = Object.freeze([
+    ":0",
+    "-screen",
+    "0",
+    "960x720x24",
+    "-nolisten",
+    "tcp",
+    "-auth",
+    GUEST_RUNTIME_ENV.XAUTHORITY,
+]);
+const SANDBOX_FEATURES = ["PID namespaces", "Network namespaces", "Seccomp-BPF sandbox"];
+const RECORDING_PATH = `${GUEST_RUNTIME_PATHS.home}/desktop-recording.mp4`;
+/** Initial document only: do not wait for app data, subresources or network idle. */
+export async function navigateGuestInitialPage(page, initialUrl, signal) {
+    const url = validateGuestInitialUrl(initialUrl);
+    signal.throwIfAborted();
+    await page.goto(url, {
+        waitUntil: "domcontentloaded",
+        timeout: GUEST_BOOTSTRAP_LIMITS.navigationMs,
+    });
+    signal.throwIfAborted();
+    // A document event precedes compositing. Yield a paint before handing the
+    // native full-desktop capture to a participant; this is not app readiness.
+    // Playwright evaluates a string predicate as an expression and never calls it,
+    // so the string is the promise itself; a function source would resolve at once.
+    const painted = await page.waitForFunction(`new Promise(resolve => {
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve(true)));
+  })`, undefined, { timeout: GUEST_BOOTSTRAP_LIMITS.paintMs });
+    await painted.dispose();
+    signal.throwIfAborted();
+}
+/** /run/humanish and /home/humanish: real directories private to the guest user. */
+export function isPrivateGuestDirectory(stat) {
+    return (stat.isDirectory() &&
+        !stat.isSymbolicLink() &&
+        stat.uid === 1000 &&
+        stat.gid === 1000 &&
+        (stat.mode & 0o777) === 0o700);
+}
+/** The window manager config: a small, read-only, single-link file owned by root. */
+export function isPinnedOpenboxConfig(stat) {
+    return (stat.isFile() &&
+        stat.uid === 0 &&
+        stat.gid === 0 &&
+        stat.nlink === 1 &&
+        stat.size <= 4096 &&
+        (stat.mode & 0o777) === 0o444);
+}
+/** chrome://sandbox must report every namespace and seccomp feature and the overall verdict. */
+export function isAdequatelySandboxed(report) {
+    return (SANDBOX_FEATURES.every((label) => new RegExp(label + "\\s+Yes").test(report)) &&
+        report.includes("You are adequately sandboxed"));
+}
+export function chromiumLaunchArgs(media) {
+    return [
+        "--window-size=960,680",
+        "--window-position=0,20",
+        "--disable-background-networking",
+        "--disable-component-update",
+        "--no-first-run",
+        ...(media?.permission === "granted" ? ["--use-fake-ui-for-media-stream"] : []),
+    ];
+}
+/** The devices to start; the permission policy only changes Chromium's flags. */
+export function desktopMediaRequest(media) {
+    return {
+        ...(media.camera === undefined ? {} : { camera: media.camera }),
+        ...(media.microphone === undefined ? {} : { microphone: media.microphone }),
+    };
+}
+/** Audio needs Pulse, which only the microphone path starts. */
+export function recorderAudio(recording, media) {
+    return {
+        audioSources: recording.audio ? ["microphone-input", "speaker-output"] : [],
+        pulseReady: recording.audio && media?.microphone !== undefined,
+    };
+}
+async function verifyGuestLayout(check) {
+    if (process.getuid?.() !== 1000 || process.getgid?.() !== 1000)
+        throw setupFailed();
+    for (const path of [GUEST_RUNTIME_PATHS.run, GUEST_RUNTIME_PATHS.home]) {
+        const stat = await lstat(path);
+        check();
+        if (!isPrivateGuestDirectory(stat))
+            throw setupFailed();
+    }
+    const configuration = await open(`${GUEST_RUNTIME_PATHS.root}/openbox.xml`, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let config;
+    try {
+        if (!isPinnedOpenboxConfig(await configuration.stat()))
+            throw setupFailed();
+        config = await configuration.readFile();
+    }
+    finally {
+        await configuration.close();
+    }
+    if (createHash("sha256").update(config).digest("hex") !== CONFIG_SHA)
+        throw setupFailed();
+    for (const path of [
+        `${GUEST_RUNTIME_PATHS.run}/xdg`,
+        `${GUEST_RUNTIME_PATHS.run}/capture`,
+        `${GUEST_RUNTIME_PATHS.home}/.cache`,
+        `${GUEST_RUNTIME_PATHS.home}/.config`,
+    ]) {
+        check();
+        await mkdir(path, { mode: 0o700 });
+    }
+}
+async function authorizeDisplay(processes, check) {
+    const auth = await open(GUEST_RUNTIME_ENV.XAUTHORITY, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    await auth.close();
+    check();
+    await processes.spawn("/usr/bin/xauth", ["-f", GUEST_RUNTIME_ENV.XAUTHORITY, "source", "-"], `add :0 . ${randomBytes(16).toString("hex")}\n`).done;
+    check();
+}
+async function waitForDisplay(processes, signal, check) {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        check();
+        try {
+            await processes.spawn("/usr/bin/xdpyinfo", []).done;
+            return;
+        }
+        catch {
+            await delay(50, undefined, { signal });
+        }
+    }
+    throw setupFailed();
+}
+/** A recorder that fails to start leaves the desktop usable; finishRecording reports it. */
+async function startGuestRecorder(recording, media, env, signal) {
+    try {
+        return await startDesktopRecorder({
+            display: ":0",
+            width: 960,
+            height: 720,
+            outputPath: RECORDING_PATH,
+            env,
+            signal,
+            ...recorderAudio(recording, media),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+async function launchGuestBrowser(state, media, check) {
+    state.pendingContext = chromium.launchPersistentContext(`${GUEST_RUNTIME_PATHS.home}/browser`, {
+        executablePath: "/usr/bin/chromium",
+        headless: false,
+        chromiumSandbox: true,
+        viewport: null,
+        env: state.recorder?.env ?? state.media?.env ?? GUEST_RUNTIME_ENV,
+        timeout: 25_000,
+        args: chromiumLaunchArgs(media),
+    });
+    // A browser that finishes launching after the stop is closed here; teardown may not see it.
+    void state.pendingContext.then((browser) => {
+        if (state.stopping)
+            void browser.close().catch(() => { });
+    }, () => { });
+    const context = (state.context = await state.pendingContext);
+    check();
+    context.setDefaultTimeout(5000);
+    context.setDefaultNavigationTimeout(5000);
+    const page = context.pages()[0];
+    if (!page || context.pages().length !== 1)
+        throw setupFailed();
+    return { context, page };
+}
+async function verifyBrowserSandbox(context, page, check) {
+    const diagnostic = await context.newPage();
+    check();
+    await diagnostic.goto("chrome://sandbox");
+    check();
+    const report = await diagnostic.locator("body").innerText();
+    if (!isAdequatelySandboxed(report))
+        throw setupFailed();
+    await diagnostic.close();
+    check();
+    await page.bringToFront();
+    check();
+    return report;
+}
+/** Text actions run only while the browser window that setup saw still has focus. */
+function focusGuard(native, window) {
+    return async (actionSignal) => {
+        if ((await native.activeWindowId(actionSignal)) !== window)
+            throw new CuaExecutorError("action_rejected", "not_dispatched");
+    };
+}
+async function createGuestExecutorFor(state, browser, signal, onTerminal, check) {
+    const native = createGuestDesktopNativeTools({
+        display: ":0",
+        temporaryDirectory: `${GUEST_RUNTIME_PATHS.run}/capture`,
+        xauthority: GUEST_RUNTIME_ENV.XAUTHORITY,
+    });
+    const window = await native.activeWindowId(signal);
+    check();
+    state.content = createGuestChromiumText({
+        ...browser,
+        assertFocusedWindow: focusGuard(native, window),
+    });
+    return createGuestDesktopExecutor({
+        width: 960,
+        height: 720,
+        tools: createGuestBrowserTools(native, state.content),
+        authoritySignal: signal,
+        onTerminal,
+    });
+}
+async function openGuestFixture(page, check) {
+    await page.goto(`file://${GUEST_RUNTIME_PATHS.root}/neutral.html`);
+    check();
+    await page.locator("#note").waitFor();
+    check();
+}
+async function finishGuestRecording(recorder) {
+    try {
+        if (!recorder)
+            throw new Error();
+        const result = await recorder.finish();
+        const file = await open(result.outputPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const fileStat = await file.stat();
+            if (!fileStat.isFile() || fileStat.size !== result.metadata.bytes)
+                throw new Error();
+            return { metadata: result.metadata, stream: file.createReadStream({ autoClose: true }) };
+        }
+        catch (error) {
+            await file.close().catch(() => { });
+            throw error;
+        }
+    }
+    catch {
+        throw new Error("Desktop recording failed.");
+    }
+}
+/** Closes in a fixed order within 4 s; a failed step other than the recording marks it incomplete. */
+function closeGuestRuntimeDesktop(state, processes, controller, detach) {
+    if (state.closing)
+        return state.closing;
+    state.stopping = true;
+    state.closing = Promise.resolve().then(async () => {
+        let complete = true, timer;
+        const work = async () => {
+            try {
+                await state.content?.close();
+            }
+            catch {
+                complete = false;
+            }
+            try {
+                await state.recorder?.finish();
+            }
+            catch {
+                /* Recording evidence is optional to desktop teardown. */
+            }
+            try {
+                await state.media?.close();
+            }
+            catch {
+                complete = false;
+            }
+            try {
+                const browser = state.context ?? (await state.pendingContext?.catch(() => undefined));
+                if (browser)
+                    await browser.close();
+            }
+            catch {
+                complete = false;
+            }
+            processes.killRunning();
+            await processes.closed();
+        };
+        try {
+            await Promise.race([
+                work(),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        complete = false;
+                        resolve();
+                    }, 4000);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+            if (processes.killRunning())
+                complete = false;
+            detach();
+        }
+        return { complete };
+    });
+    controller.abort();
+    return state.closing;
+}
+/** Fixed guest layout with an optional admitted initial loopback app URL. */
+export async function createGuestRuntimeDesktop(options) {
+    if (options.initialUrl !== undefined)
+        validateGuestInitialUrl(options.initialUrl);
+    const controller = new AbortController();
+    const signal = AbortSignal.any([options.signal, controller.signal]);
+    const state = { stopping: false };
+    let phase = "layout";
+    const progress = (next) => {
+        phase = next;
+        options.onPhase?.(next);
+    };
+    const check = () => {
+        if (signal.aborted || state.stopping)
+            throw setupFailed();
+    };
+    const processes = createGuestProcesses({
+        env: GUEST_RUNTIME_ENV,
+        cwd: GUEST_RUNTIME_PATHS.home,
+        signal,
+        check,
+        isStopping: () => state.stopping,
+        onTerminal: options.onTerminal,
+    });
+    const abort = () => void close();
+    const close = () => closeGuestRuntimeDesktop(state, processes, controller, () => options.signal.removeEventListener("abort", abort));
+    options.signal.addEventListener("abort", abort, { once: true });
+    try {
+        progress("layout");
+        check();
+        await verifyGuestLayout(check);
+        progress("xauthority");
+        await authorizeDisplay(processes, check);
+        progress("display");
+        processes.spawn("/usr/bin/Xvfb", XVFB_ARGS, undefined, true);
+        await waitForDisplay(processes, signal, check);
+        progress("window_manager");
+        processes.spawn("/usr/bin/openbox", ["--config-file", `${GUEST_RUNTIME_PATHS.root}/openbox.xml`], undefined, true);
+        check();
+        if (options.media !== undefined) {
+            progress("media");
+            state.media = await startDesktopMedia({
+                media: desktopMediaRequest(options.media),
+                env: GUEST_RUNTIME_ENV,
+                signal,
+                onTerminal: options.onTerminal,
+            });
+            check();
+        }
+        if (options.recording !== undefined) {
+            progress("recording");
+            const env = state.media?.env ?? GUEST_RUNTIME_ENV;
+            state.recorder = await startGuestRecorder(options.recording, options.media, env, signal);
+            check();
+        }
+        progress("browser");
+        const browser = await launchGuestBrowser(state, options.media, check);
+        progress("sandbox");
+        const sandboxReport = await verifyBrowserSandbox(browser.context, browser.page, check);
+        progress("focus");
+        const executor = await createGuestExecutorFor(state, browser, signal, options.onTerminal, check);
+        if (options.initialUrl !== undefined) {
+            progress("navigation");
+            await navigateGuestInitialPage(browser.page, options.initialUrl, signal);
+            check();
+        }
+        else {
+            progress("fixture");
+            await openGuestFixture(browser.page, check);
+        }
+        return {
+            executor: state.media?.wrap(executor) ?? executor,
+            close,
+            ...(options.recording === undefined
+                ? {}
+                : { finishRecording: () => finishGuestRecording(state.recorder) }),
+            owner: { ...browser, sandboxReport, configSha256: CONFIG_SHA },
+        };
+    }
+    catch {
+        await close();
+        throw Object.assign(setupFailed(), { phase });
+    }
+    finally {
+        // The fresh private state belongs to the guest owner. No recursive home removal.
+        if (state.stopping && processes.allExited())
+            await rm(`${GUEST_RUNTIME_PATHS.run}/capture`, { recursive: true, force: true }).catch(() => { });
+    }
+}

package/dist/guest/runtime-processes.d.ts

@@ -0,0 +1,28 @@
+import { type ChildProcess } from "node:child_process";
+import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+export declare const setupFailed: () => CuaExecutorError;
+export interface GuestProcesses {
+    /** `done` resolves when the child exits 0 within its bounds and rejects otherwise. */
+    spawn(binary: string, args: readonly string[], input?: string, persistent?: boolean): {
+        done: Promise<void>;
+        child: ChildProcess;
+    };
+    /** SIGKILLs every child still running and returns whether there was one. */
+    killRunning(): boolean;
+    /** Resolves when every child spawned so far has closed. */
+    closed(): Promise<void>;
+    allExited(): boolean;
+}
+/**
+ * The guest desktop's fixed child processes. A persistent child (the display server, the window
+ * manager) that exits, fails or is killed by the owner's abort reports `onTerminal` unless the
+ * desktop is already stopping.
+ */
+export declare function createGuestProcesses(options: {
+    env: Readonly<Record<string, string>>;
+    cwd: string;
+    signal: AbortSignal;
+    check(): void;
+    isStopping(): boolean;
+    onTerminal(): void;
+}): GuestProcesses;

package/dist/guest/runtime-processes.js

@@ -0,0 +1,94 @@
+import { spawn } from "node:child_process";
+import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+/** A short-lived helper that has not exited by then is killed. Persistent children have no bound. */
+const HELPER_TIMEOUT_MS = 2000;
+/** Helpers report success through exit status, so stderr past this budget is a failure. */
+const STDERR_LIMIT_BYTES = 16_384;
+export const setupFailed = () => new CuaExecutorError("execution_failed", "not_dispatched");
+/**
+ * The guest desktop's fixed child processes. A persistent child (the display server, the window
+ * manager) that exits, fails or is killed by the owner's abort reports `onTerminal` unless the
+ * desktop is already stopping.
+ */
+export function createGuestProcesses(options) {
+    const children = [];
+    const { signal } = options;
+    const terminal = (persistent) => {
+        if (persistent && !options.isStopping())
+            options.onTerminal();
+    };
+    return {
+        spawn(binary, args, input, persistent = false) {
+            options.check();
+            const process = spawn(binary, args, {
+                env: options.env,
+                cwd: options.cwd,
+                stdio: ["pipe", "ignore", "pipe"],
+            });
+            let finish;
+            const record = {
+                child: process,
+                closed: new Promise((resolve) => {
+                    finish = resolve;
+                }),
+                exited: false,
+            };
+            children.push(record);
+            const done = new Promise((resolve, reject) => {
+                let count = 0, failed = false;
+                const fail = () => {
+                    failed = true;
+                    if (!record.exited)
+                        process.kill("SIGKILL");
+                    terminal(persistent);
+                };
+                const timer = persistent ? undefined : setTimeout(fail, HELPER_TIMEOUT_MS);
+                // xdpyinfo's normal display inventory is large and is not an error log.
+                const consume = (data) => {
+                    count += data.length;
+                    if (count > STDERR_LIMIT_BYTES)
+                        fail();
+                };
+                process.stderr.on("data", consume);
+                process.on("error", fail);
+                process.stdin.on("error", fail);
+                process.once("exit", () => {
+                    record.exited = true;
+                    terminal(persistent);
+                });
+                process.once("close", (code) => {
+                    record.exited = true;
+                    clearTimeout(timer);
+                    signal.removeEventListener("abort", fail);
+                    finish();
+                    terminal(persistent);
+                    if (failed || code !== 0)
+                        reject(setupFailed());
+                    else
+                        resolve();
+                });
+                signal.addEventListener("abort", fail, { once: true });
+                process.stdin.end(input);
+                if (signal.aborted)
+                    fail();
+            });
+            void done.catch(() => { });
+            return { done, child: process };
+        },
+        killRunning() {
+            let running = false;
+            for (const record of children)
+                if (!record.exited) {
+                    running = true;
+                    record.child.kill("SIGKILL");
+                }
+            return running;
+        },
+        async closed() {
+            await Promise.all(children.map((record) => record.closed));
+        },
+        allExited() {
+            return children.every((record) => record.exited);
+        },
+    };
+}

package/dist/guest/runtime.d.ts

@@ -0,0 +1,31 @@
+import type { Duplex, Readable } from "node:stream";
+import type { CuaExecutor } from "../actors/computer-use/loop.js";
+import type { GuestMediaConfig } from "./media-config.js";
+import type { DesktopRecordingConfig, DesktopRecordingMetadata } from "../evidence/desktop-recording-types.js";
+export interface GuestRuntimeDesktop {
+    executor: CuaExecutor;
+    finishRecording?(): Promise<{
+        metadata: DesktopRecordingMetadata;
+        stream: Readable;
+    }>;
+    close(): Promise<{
+        complete: boolean;
+    }>;
+}
+export interface GuestRuntimeOptions {
+    transport: Duplex;
+    revision: string;
+    signal: AbortSignal;
+    /** Fixed private supervision channel, not browser-control output. */
+    marker(value: "A" | "R"): void;
+    createDesktop(signal: AbortSignal, onTerminal: () => void, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig): Promise<GuestRuntimeDesktop>;
+}
+/** One admitted desktop and one dispatcher. The owner retains physical teardown. */
+export declare function runGuestRuntime(options: GuestRuntimeOptions): Promise<{
+    close(): Promise<{
+        complete: boolean;
+    }>;
+    closed: Promise<{
+        complete: boolean;
+    }>;
+}>;