humanish 0.105.0 → 0.106.0

package/dist/substrates/e2b/desktop-geometry.d.ts

@@ -0,0 +1,83 @@
+import { type DevicePreset } from "../../lab/device-presets.js";
+import { type RunDesktopGeometry } from "../../run/streams.js";
+import { type ChromeCdpPagePreference } from "./cdp-probe.js";
+import { type DesktopBrowserFamily, type DesktopBrowserLaunchIdentity } from "./desktop-browser.js";
+import type { ChromeCdpEndpoint } from "./desktop-cdp.js";
+import type { E2BDesktopSandbox } from "./sdk.js";
+/**
+ * The DECLARED preset to record alongside the rendered screen, or undefined when the preset
+ * rendered faithfully.
+ *
+ * `desktopGeometry.screen.verified` compares the FLOORED number with itself, so on its own a
+ * floored run is indistinguishable from a faithful one: a reader sees requested 500 / verified 500
+ * and concludes a 500-wide screen was asked for. Recording the declared preset is what makes
+ * "the preset width did not render" legible in the bundle.
+ */
+export declare function declaredScreenForRender(preset: DevicePreset, presetName: string, rendered: readonly [number, number]): {
+    width: number;
+    height: number;
+    preset: string;
+} | undefined;
+/**
+ * Verify the desktop screen geometry IN-SANDBOX (the per-lane device claim is checked, never
+ * assumed). A parseable mismatch fails closed. Unavailable/unparseable evidence is returned as
+ * an explicit warning: the lane may still run, but its bundle records only the requested screen
+ * and never upgrades that request into a verified measurement.
+ */
+export declare function inspectDesktopScreenGeometry(args: {
+    desktop: E2BDesktopSandbox;
+    participantId: string;
+    requestedScreen: readonly [number, number];
+    requestTimeoutMs: number;
+}): Promise<{
+    verified?: RunDesktopGeometry["screen"]["verified"];
+    error?: string;
+    warning?: string;
+}>;
+/**
+ * Read the running browser's actual outer-window bounds and CSS layout viewport through the
+ * already-enabled local Chrome DevTools endpoint. The returned values come from `window.*` in
+ * the target page; requested E2B resolution is deliberately not an input to this function.
+ * Missing channels report their reason via `onUnavailable`, so the geometry warning can name
+ * the cause (a dead CDP endpoint, no python3) instead of only the symptom. Returns `undefined`
+ * only when neither channel could be measured.
+ * Outer bounds and CSS dimensions are independent channels: a background page can report zero
+ * outer dimensions while still reporting a CSS viewport. Final captures follow the active tab;
+ * launch captures and emulation attribution keep the pinned target.
+ */
+export declare function makeChromeDesktopGeometryObserver(desktop: E2BDesktopSandbox, requestTimeoutMs: number, endpoint: ChromeCdpEndpoint, options?: {
+    /** The page target to measure; absent, the probe attributes one from the endpoint. */
+    targetId?: string | undefined;
+    /** Called with the reason whenever a channel could not be measured. */
+    onUnavailable?: (reason: string) => void;
+    /** Launch captures stay pinned; final captures follow the active tab. */
+    prefer?: ChromeCdpPagePreference;
+}): () => Promise<(Pick<RunDesktopGeometry, "browserWindow" | "viewport"> & {
+    targetId?: string;
+}) | undefined>;
+/** Root-relative physical client bounds from xwininfo's C-locale stats. */
+export declare function parseXwininfoGeometry(output: string): RunDesktopGeometry["browserWindow"] | undefined;
+/** Hosted-browser geometry capture shared by the per-lane and shared-world routes. */
+export declare function captureDesktopBrowserGeometry(args: {
+    desktop: E2BDesktopSandbox;
+    browserFamily: DesktopBrowserFamily;
+    launchIdentity?: DesktopBrowserLaunchIdentity;
+    browserTargetId?: string;
+    /** Launch captures stay pinned; final captures follow the participant's current page. */
+    pagePreference?: ChromeCdpPagePreference;
+    browserWindowId?: string;
+    participantId: string;
+    /** Runtime-only lane target URL (attributes the CDP page); never persisted by this capture. */
+    targetUrl: string;
+    requestedScreen: readonly [number, number];
+    requestTimeoutMs: number;
+    resize?: boolean;
+}): Promise<{
+    /** Known physical clipping (or unverified repair of it); startup must stop before actions. */
+    unusable?: string;
+    browserWindowId?: string;
+    browserTargetId?: string;
+    browserWindow?: RunDesktopGeometry["browserWindow"];
+    viewport?: RunDesktopGeometry["viewport"];
+    warnings: string[];
+}>;

package/dist/substrates/e2b/desktop-geometry.js

@@ -0,0 +1,331 @@
+// Screen and browser-window geometry on a hosted E2B desktop, measured in the sandbox rather than
+// taken from the request.
+import {} from "../../lab/device-presets.js";
+import { failureTail, redactText, toErrorMessage } from "../../evidence/redaction.js";
+import {} from "../../run/streams.js";
+import { chromeCdpProbeCommand, parseChromeCdpProbeOutput, } from "./cdp-probe.js";
+import { shellQuote } from "../shell.js";
+import { e2bShell } from "./shell.js";
+import { findVisibleBrowserWindowId, fillDesktopBrowserWindow, } from "./desktop-browser.js";
+/**
+ * The DECLARED preset to record alongside the rendered screen, or undefined when the preset
+ * rendered faithfully.
+ *
+ * `desktopGeometry.screen.verified` compares the FLOORED number with itself, so on its own a
+ * floored run is indistinguishable from a faithful one: a reader sees requested 500 / verified 500
+ * and concludes a 500-wide screen was asked for. Recording the declared preset is what makes
+ * "the preset width did not render" legible in the bundle.
+ */
+export function declaredScreenForRender(preset, presetName, rendered) {
+    if (preset.width === rendered[0] && preset.height === rendered[1])
+        return undefined;
+    return { width: preset.width, height: preset.height, preset: presetName };
+}
+/**
+ * Verify the desktop screen geometry IN-SANDBOX (the per-lane device claim is checked, never
+ * assumed). A parseable mismatch fails closed. Unavailable/unparseable evidence is returned as
+ * an explicit warning: the lane may still run, but its bundle records only the requested screen
+ * and never upgrades that request into a verified measurement.
+ */
+export async function inspectDesktopScreenGeometry(args) {
+    let out = "";
+    try {
+        const result = await e2bShell(args.desktop).run("xdpyinfo 2>/dev/null | grep -i dimensions || true", { requestTimeoutMs: args.requestTimeoutMs });
+        out = result.stdout.trim();
+    }
+    catch {
+        return {
+            warning: `Desktop screen geometry could not be measured for participant ${args.participantId}; requested geometry remains unverified.`,
+        };
+    }
+    const match = out.match(/(\d+)\s*x\s*(\d+)\s*pixels/i);
+    if (!match) {
+        return {
+            warning: `Desktop screen geometry could not be parsed for participant ${args.participantId}; requested geometry remains unverified.`,
+        };
+    }
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    const [expectedWidth, expectedHeight] = args.requestedScreen;
+    if (width === expectedWidth && height === expectedHeight) {
+        return { verified: { width, height, source: "xdpyinfo" } };
+    }
+    return {
+        verified: { width, height, source: "xdpyinfo" },
+        error: `HUMANISH_CUA_LAB_DEVICE_GEOMETRY: participant ${args.participantId} requested a ${expectedWidth}x${expectedHeight} desktop but xdpyinfo reports ${width}x${height} in-sandbox; the participant's device geometry is unverified (fail-closed).`,
+    };
+}
+/**
+ * Read the running browser's actual outer-window bounds and CSS layout viewport through the
+ * already-enabled local Chrome DevTools endpoint. The returned values come from `window.*` in
+ * the target page; requested E2B resolution is deliberately not an input to this function.
+ * Missing channels report their reason via `onUnavailable`, so the geometry warning can name
+ * the cause (a dead CDP endpoint, no python3) instead of only the symptom. Returns `undefined`
+ * only when neither channel could be measured.
+ * Outer bounds and CSS dimensions are independent channels: a background page can report zero
+ * outer dimensions while still reporting a CSS viewport. Final captures follow the active tab;
+ * launch captures and emulation attribution keep the pinned target.
+ */
+export function makeChromeDesktopGeometryObserver(desktop, requestTimeoutMs, endpoint, options = {}) {
+    const { targetId, onUnavailable, prefer = "pinned" } = options;
+    const shell = e2bShell(desktop);
+    return async () => {
+        const result = await shell.run(chromeCdpProbeCommand({
+            ...endpoint,
+            ...(targetId === undefined ? {} : { targetId }),
+            prefer,
+            mode: "geometry",
+        }), { requestTimeoutMs, timeoutMs: 5_000 });
+        if (result.exitCode !== 0) {
+            onUnavailable?.(`probe exited ${result.exitCode}: ${failureTail(result.stderr || result.stdout)}`);
+            return undefined;
+        }
+        const parsed = parseChromeCdpProbeOutput(result.stdout);
+        if (parsed.unavailable !== undefined) {
+            onUnavailable?.(parsed.unavailable);
+            return undefined;
+        }
+        const browserWindow = isMeasuredRect(parsed.browserWindow)
+            ? { ...parsed.browserWindow, source: "cdp" }
+            : undefined;
+        const viewport = isMeasuredViewport(parsed.viewport)
+            ? { ...parsed.viewport, source: "cdp" }
+            : undefined;
+        if (browserWindow === undefined && viewport === undefined) {
+            onUnavailable?.("the page reported no usable window or viewport dimensions");
+            return undefined;
+        }
+        if (browserWindow === undefined)
+            onUnavailable?.("the page reported no usable outer-window dimensions");
+        if (viewport === undefined)
+            onUnavailable?.("the page reported no usable CSS viewport dimensions");
+        return {
+            ...(browserWindow === undefined ? {} : { browserWindow }),
+            ...(viewport === undefined ? {} : { viewport }),
+            ...(parsed.targetId === undefined ? {} : { targetId: parsed.targetId }),
+        };
+    };
+}
+function isMeasuredRect(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (Number.isFinite(record.x) &&
+        Number.isFinite(record.y) &&
+        isPositiveMeasurement(record.width) &&
+        isPositiveMeasurement(record.height));
+}
+function isMeasuredViewport(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (isPositiveMeasurement(record.width) &&
+        isPositiveMeasurement(record.height) &&
+        isPositiveMeasurement(record.deviceScaleFactor));
+}
+function isPositiveMeasurement(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+async function measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs) {
+    const result = await e2bShell(desktop).run([
+        "set -euo pipefail",
+        `win=${shellQuote(windowId)}`,
+        // Older xdotool builds translate parent-relative offsets twice. With window
+        // decorations that falsely reports a visible client as clipped, triggering
+        // fullscreen and hiding the participant's address bar. Read root-relative
+        // client coordinates directly; never substitute emulated CDP outer bounds.
+        'LC_ALL=C xwininfo -id "$win" -stats 2>/dev/null',
+    ].join("\n"), { requestTimeoutMs, timeoutMs: 5_000 });
+    if (result.exitCode !== 0)
+        return undefined;
+    return parseXwininfoGeometry(result.stdout);
+}
+/** Root-relative physical client bounds from xwininfo's C-locale stats. */
+export function parseXwininfoGeometry(output) {
+    const read = (label) => {
+        const matches = [...output.matchAll(new RegExp(`^\\s*${label}:\\s*(-?\\d+)\\s*$`, "gm"))];
+        if (matches.length !== 1)
+            return undefined;
+        const value = Number(matches[0][1]);
+        return Number.isSafeInteger(value) ? value : undefined;
+    };
+    const x = read("Absolute upper-left X");
+    const y = read("Absolute upper-left Y");
+    const width = read("Width");
+    const height = read("Height");
+    const mapStates = [...output.matchAll(/^\s*Map State:\s*(\S+)\s*$/gm)];
+    if (mapStates.length !== 1 || mapStates[0][1] !== "IsViewable")
+        return undefined;
+    if (x === undefined ||
+        y === undefined ||
+        width === undefined ||
+        height === undefined ||
+        width <= 0 ||
+        height <= 0) {
+        return undefined;
+    }
+    return { x, y, width, height, source: "xwininfo" };
+}
+/** Physical X client bounds, never the page's emulated window.outerWidth/Height. */
+function isBrowserWindowContained(bounds, [width, height]) {
+    return (bounds.x >= 0 &&
+        bounds.y >= 0 &&
+        bounds.x + bounds.width <= width &&
+        bounds.y + bounds.height <= height);
+}
+/** Bounded repair. Resizing can clear a window-manager maximize state and move the
+ * client origin as decorations return, so remeasure before a second adjustment. */
+async function fitBrowserWindowWithinDesktop(desktop, windowId, resolution, requestTimeoutMs) {
+    const run = (command) => e2bShell(desktop)
+        .run(["set -euo pipefail", `win=${shellQuote(windowId)}`, command].join("\n"), {
+        requestTimeoutMs,
+        timeoutMs: 5_000,
+    })
+        .catch(() => undefined);
+    await run('xdotool windowmove "$win" 0 0');
+    await desktop.wait(250).catch(() => undefined);
+    const moved = await measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs).catch(() => undefined);
+    if (moved === undefined)
+        return moved;
+    let resized = moved;
+    // Resizing alone cannot fix an offscreen client origin. The window manager
+    // can also center a minimum-width client at a negative x on a narrow screen.
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        if (isBrowserWindowContained(resized, resolution))
+            return resized;
+        const width = resolution[0] - resized.x;
+        const height = resolution[1] - resized.y;
+        if (resized.x < 0 || resized.y < 0 || width <= 0 || height <= 0)
+            break;
+        await run(`xdotool windowsize "$win" ${width} ${height}`);
+        await desktop.wait(250).catch(() => undefined);
+        const measured = await measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs).catch(() => undefined);
+        if (measured === undefined)
+            return measured;
+        resized = measured;
+    }
+    if (resized === undefined || isBrowserWindowContained(resized, resolution))
+        return resized;
+    // Chrome's minimum client width can equal the whole desktop. Window-manager
+    // borders then make a decorated window impossible to contain, even after a
+    // successful move/resize. Request fullscreen once and prove the physical result.
+    // xprop/xdotool ship with the desktop template; wmctrl is not required.
+    // Check state first so the fullscreen shortcut cannot toggle an existing state off.
+    await run([
+        'state=$(xprop -id "$win" _NET_WM_STATE)',
+        'case "$state" in',
+        "  *_NET_WM_STATE_FULLSCREEN*) ;;",
+        '  *) xdotool windowactivate --sync "$win"; xdotool key --clearmodifiers F11 ;;',
+        "esac",
+    ].join("\n"));
+    // The fullscreen animation may report its new origin before its final width.
+    // Give the window manager a bounded settling window, keeping missing reads unverified.
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        await desktop.wait(250).catch(() => undefined);
+        const measured = await measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs).catch(() => undefined);
+        if (measured === undefined || isBrowserWindowContained(measured, resolution))
+            return measured;
+        resized = measured;
+    }
+    return resized;
+}
+/** Hosted-browser geometry capture shared by the per-lane and shared-world routes. */
+export async function captureDesktopBrowserGeometry(args) {
+    const warnings = [];
+    let browserWindowId = args.browserWindowId;
+    if (browserWindowId === undefined && args.browserFamily !== "unknown") {
+        browserWindowId = await findVisibleBrowserWindowId(args.desktop, args.requestTimeoutMs, args.browserFamily, args.launchIdentity).catch((error) => {
+            warnings.push(`Browser window lookup failed for participant ${args.participantId}: ${redactText(toErrorMessage(error))}`);
+            return undefined;
+        });
+    }
+    let physicalWindow;
+    if (browserWindowId !== undefined) {
+        if (args.resize !== false) {
+            await fillDesktopBrowserWindow(args.desktop, browserWindowId, args.requestedScreen, args.requestTimeoutMs);
+            // Let the window manager apply the resize before querying both X and page layout geometry.
+            await args.desktop.wait(250).catch(() => undefined);
+        }
+        physicalWindow = await measureBrowserWindowWithXwininfo(args.desktop, browserWindowId, args.requestTimeoutMs).catch(() => undefined);
+    }
+    else {
+        warnings.push(`Browser window bounds could not be measured for participant ${args.participantId}; the live stream will use the full desktop.`);
+    }
+    let unusable;
+    if (physicalWindow !== undefined &&
+        !isBrowserWindowContained(physicalWindow, args.requestedScreen)) {
+        const before = physicalWindow;
+        if (args.resize !== false && browserWindowId !== undefined) {
+            physicalWindow = await fitBrowserWindowWithinDesktop(args.desktop, browserWindowId, args.requestedScreen, args.requestTimeoutMs);
+            if (physicalWindow === undefined) {
+                // Keep the last measured bad state; a missing observation cannot prove a successful fix.
+                physicalWindow = before;
+                unusable = `Physical browser containment could not be verified after correction for participant ${args.participantId}; the last measured window was clipped.`;
+            }
+            else if (isBrowserWindowContained(physicalWindow, args.requestedScreen)) {
+                warnings.push(`Browser window clipping corrected for participant ${args.participantId}; physical bounds are ${physicalWindow.width}x${physicalWindow.height} at (${physicalWindow.x}, ${physicalWindow.y}).`);
+            }
+        }
+        if (unusable === undefined && !isBrowserWindowContained(physicalWindow, args.requestedScreen)) {
+            unusable = `Browser window is outside the captured ${args.requestedScreen[0]}x${args.requestedScreen[1]} desktop for participant ${args.participantId}: physical bounds ${physicalWindow.width}x${physicalWindow.height} at (${physicalWindow.x}, ${physicalWindow.y}), right=${physicalWindow.x + physicalWindow.width}, bottom=${physicalWindow.y + physicalWindow.height}.`;
+        }
+        if (unusable !== undefined)
+            warnings.push(unusable);
+    }
+    if (physicalWindow === undefined) {
+        warnings.push(`Physical browser containment is unverified for participant ${args.participantId}; X window bounds could not be measured. Page-reported outer dimensions can be emulated and do not prove physical visibility.`);
+    }
+    let cdpUnavailable;
+    const chromeGeometry = args.browserFamily === "chromium"
+        ? await makeChromeDesktopGeometryObserver(args.desktop, args.requestTimeoutMs, {
+            ...(args.launchIdentity?.cdpPort === undefined
+                ? {}
+                : { cdpPort: args.launchIdentity.cdpPort }),
+            ...(args.launchIdentity?.profileDir === undefined
+                ? {}
+                : { profileDir: args.launchIdentity.profileDir }),
+            targetUrl: args.targetUrl,
+        }, {
+            targetId: args.browserTargetId,
+            onUnavailable: (reason) => {
+                cdpUnavailable = reason;
+            },
+            prefer: args.pagePreference ?? "pinned",
+        })().catch((error) => {
+            cdpUnavailable = toErrorMessage(error);
+            return undefined;
+        })
+        : undefined;
+    const browserWindow = physicalWindow ?? chromeGeometry?.browserWindow;
+    const viewport = chromeGeometry?.viewport;
+    // The fill check reads the X window when it was measured: under mobile emulation (#221) the
+    // page's window.outerWidth reports the EMULATED screen (414), which is not a fill failure.
+    const fillBounds = physicalWindow;
+    if (!browserWindow) {
+        warnings.push(`Browser outer bounds could not be measured for participant ${args.participantId}.`);
+    }
+    else if (unusable === undefined &&
+        fillBounds !== undefined &&
+        (fillBounds.x !== 0 ||
+            fillBounds.y !== 0 ||
+            fillBounds.width !== args.requestedScreen[0] ||
+            fillBounds.height !== args.requestedScreen[1])) {
+        warnings.push(`Browser window fill did not reach the requested ${args.requestedScreen[0]}x${args.requestedScreen[1]} screen for participant ${args.participantId}; measured physical bounds are ${fillBounds.width}x${fillBounds.height} at (${fillBounds.x}, ${fillBounds.y}).`);
+    }
+    if (!viewport) {
+        // Name the cause, not only the symptom: the same dead DevTools channel that loses the viewport
+        // loses every url/text observation, and a reader of the bundle should learn that here (#514).
+        const cause = cdpUnavailable === undefined ? "" : ` DevTools probe: ${redactText(cdpUnavailable)}.`;
+        warnings.push(args.browserFamily === "firefox"
+            ? `Browser CSS viewport measurement is unavailable in Firefox for participant ${args.participantId}; stream.viewport is omitted instead of reading a different browser's CDP endpoint.`
+            : `Browser CSS viewport could not be measured for participant ${args.participantId}; stream.viewport is omitted instead of copying the requested screen resolution.${cause}`);
+    }
+    return {
+        ...(unusable === undefined ? {} : { unusable }),
+        ...(browserWindowId === undefined ? {} : { browserWindowId }),
+        ...(chromeGeometry?.targetId === undefined ? {} : { browserTargetId: chromeGeometry.targetId }),
+        ...(browserWindow === undefined ? {} : { browserWindow }),
+        ...(viewport === undefined ? {} : { viewport }),
+        warnings,
+    };
+}

package/dist/substrates/e2b/desktop-media.d.ts

@@ -0,0 +1,29 @@
+import { startDesktopMedia } from "../../guest/desktop-media.js";
+import type { E2BDesktopSandbox } from "./sdk.js";
+import type { LabDesktopMedia } from "../../lab/types.js";
+/** The same worker and conversation contract, transported by the hosted SDK's stdin/stdout. */
+export declare function startE2BDesktopMedia(options: {
+    desktop: E2BDesktopSandbox;
+    media: LabDesktopMedia;
+    signal: AbortSignal;
+    onTerminal(): void;
+    requestTimeoutMs: number;
+}): Promise<Awaited<ReturnType<typeof startDesktopMedia>>>;
+export interface DesktopMediaEvidence {
+    camera?: {
+        source: "synthetic" | "file";
+        file: string;
+    };
+    microphone?: {
+        source: "speech";
+    };
+    permission: "prompt" | "granted";
+    flags: string[];
+}
+/**
+ * Put the declared camera feed in the sandbox and return the Chromium flags that present it as a
+ * capture device (#509). Fails CLOSED: a feed that cannot be produced (no ffmpeg on the image, an
+ * unreadable host file) is named before the browser launches, because a participant told it has
+ * a camera and finds none reports the instrument's gap as the product's.
+ */
+export declare function prepareDesktopMedia(desktop: E2BDesktopSandbox, media: LabDesktopMedia, permission: "prompt" | "granted", cwd: string, requestTimeoutMs: number, readHostFile?: (absolutePath: string) => Promise<Buffer>): Promise<DesktopMediaEvidence>;

package/dist/substrates/e2b/desktop-media.js

@@ -0,0 +1,151 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { startDesktopMedia } from "../../guest/desktop-media.js";
+import { failureTail, toErrorMessage } from "../../evidence/redaction.js";
+import { runOrThrow } from "../shell.js";
+import { e2bShell } from "./shell.js";
+/** The same worker and conversation contract, transported by the hosted SDK's stdin/stdout. */
+export async function startE2BDesktopMedia(options) {
+    if (options.media.camera !== undefined)
+        throw new Error("Hosted speech cannot be combined with a synthetic camera.");
+    let handle;
+    let closing = false;
+    const env = {
+        PATH: "/usr/local/bin:/usr/bin:/bin",
+        HOME: "/home/user",
+        USER: "user",
+        LOGNAME: "user",
+        LANG: "C.UTF-8",
+        XDG_RUNTIME_DIR: "/tmp/humanish-media-runtime",
+    };
+    return startDesktopMedia({
+        media: options.media,
+        env,
+        signal: options.signal,
+        onTerminal: options.onTerminal,
+        transport: {
+            async start(callbacks) {
+                // A background run returns a process handle and never throws on exit, so it bypasses
+                // the Shell: the worker's stdin and lifetime need the handle.
+                handle = await options.desktop.commands.run("node /opt/humanish/media/guest-media-worker.js", {
+                    background: true,
+                    stdin: true,
+                    envs: { ...callbacks.env },
+                    timeoutMs: 0,
+                    requestTimeoutMs: options.requestTimeoutMs,
+                    onStdout: (data) => callbacks.data(Buffer.from(data)),
+                    onStderr: () => { },
+                });
+                if (!handle.sendStdin || !handle.closeStdin || !handle.kill || !handle.wait) {
+                    await handle.kill?.();
+                    throw new Error("Hosted speech needs an E2B SDK with streaming command stdin support.");
+                }
+                void handle.wait().then(() => {
+                    if (!closing)
+                        callbacks.exit();
+                }, () => {
+                    if (!closing)
+                        callbacks.exit();
+                });
+            },
+            async write(data) {
+                if (closing || !handle?.sendStdin)
+                    throw new Error("The hosted speech worker is closed.");
+                await handle.sendStdin(data, { requestTimeoutMs: options.requestTimeoutMs });
+            },
+            async close() {
+                if (closing)
+                    return;
+                closing = true;
+                if (!handle)
+                    return;
+                await handle.closeStdin?.({ requestTimeoutMs: options.requestTimeoutMs }).catch(() => { });
+                let timer;
+                try {
+                    await Promise.race([
+                        handle.wait?.().catch(() => { }),
+                        new Promise((resolve) => {
+                            timer = setTimeout(() => {
+                                void handle
+                                    ?.kill?.()
+                                    .catch(() => { })
+                                    .finally(resolve);
+                            }, 2000);
+                        }),
+                    ]);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            },
+        },
+    });
+}
+/** Where a lane's synthetic camera feed lives inside the sandbox: a tmpfs the sandbox user can
+ *  write, and a path that contains neither /tmp/ nor /home/, which the public-safety scan reads
+ *  as an operator's local path (this one is the harness's own and belongs in the bundle). */
+const SANDBOX_MEDIA_DIR = "/dev/shm/humanish-media";
+const SANDBOX_CAMERA_PATH = `${SANDBOX_MEDIA_DIR}/camera.y4m`;
+/** The synthetic feed: ffmpeg's test pattern, 640x480 at 10 fps, six seconds (about 28 MB of
+ *  raw Y4M on the tmpfs), looped by Chrome's fake capture device. */
+const SYNTHETIC_CAMERA_COMMAND = `mkdir -p ${SANDBOX_MEDIA_DIR} && ffmpeg -y -loglevel error -f lavfi -i testsrc=size=640x480:rate=10 -t 6 -pix_fmt yuv420p ${SANDBOX_CAMERA_PATH}`;
+/**
+ * Put the declared camera feed in the sandbox and return the Chromium flags that present it as a
+ * capture device (#509). Fails CLOSED: a feed that cannot be produced (no ffmpeg on the image, an
+ * unreadable host file) is named before the browser launches, because a participant told it has
+ * a camera and finds none reports the instrument's gap as the product's.
+ */
+export async function prepareDesktopMedia(desktop, media, permission, cwd, requestTimeoutMs, readHostFile = (absolutePath) => readFile(absolutePath)) {
+    if (media.microphone !== undefined) {
+        if (media.microphone.source !== "speech")
+            throw new Error("Microphone source-file injection is unsupported; use source: speech.");
+        if (media.camera !== undefined)
+            throw new Error("Hosted synthetic cameras cannot be combined with speech.");
+        // The lane starts and admits the speech worker before launching the browser.
+        return {
+            microphone: { source: "speech" },
+            permission,
+            flags: permission === "granted" ? ["--use-fake-ui-for-media-stream"] : [],
+        };
+    }
+    const flags = [];
+    let camera;
+    const shell = e2bShell(desktop);
+    if (media.camera !== undefined) {
+        if (media.camera.source === "synthetic") {
+            const made = await shell.run(SYNTHETIC_CAMERA_COMMAND, {
+                requestTimeoutMs,
+                timeoutMs: 60_000,
+            });
+            if (made.exitCode !== 0) {
+                throw new Error(`the synthetic camera feed could not be generated on this desktop image (ffmpeg exited ${made.exitCode}: ${failureTail(made.stderr || made.stdout)}); give execution.desktop.media.camera.source a .y4m file instead`);
+            }
+            camera = { source: "synthetic", file: SANDBOX_CAMERA_PATH };
+        }
+        else {
+            const absolutePath = path.resolve(cwd, media.camera.source);
+            let bytes;
+            try {
+                bytes = await readHostFile(absolutePath);
+            }
+            catch (error) {
+                throw new Error(`execution.desktop.media.camera.source could not be read (${toErrorMessage(error)})`);
+            }
+            if (bytes.length > 64 * 1024 * 1024) {
+                throw new Error(`execution.desktop.media.camera.source is ${bytes.length} bytes; the camera feed is capped at 64 MiB`);
+            }
+            await runOrThrow(shell, `mkdir -p ${SANDBOX_MEDIA_DIR}`, {
+                requestTimeoutMs,
+                timeoutMs: 15_000,
+            });
+            const payload = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+            // An ArrayBuffer goes to the machine as an octet stream.
+            await shell.writeFile(SANDBOX_CAMERA_PATH, payload, { requestTimeoutMs });
+            camera = { source: "file", file: SANDBOX_CAMERA_PATH };
+        }
+        flags.push("--use-fake-device-for-media-stream", `--use-file-for-fake-video-capture=${SANDBOX_CAMERA_PATH}`);
+    }
+    if (permission === "granted")
+        flags.push("--use-fake-ui-for-media-stream");
+    return { ...(camera === undefined ? {} : { camera }), permission, flags };
+}

package/dist/substrates/e2b/desktop-recording.d.ts

@@ -0,0 +1,18 @@
+import { type Writable } from "node:stream";
+import { type DesktopRecordingMetadata } from "../../evidence/desktop-recording-types.js";
+import type { E2BDesktopSandbox } from "./sdk.js";
+interface RecordingOptions {
+    desktop: E2BDesktopSandbox;
+    width: number;
+    height: number;
+    audio: boolean;
+    pulseEnv?: Readonly<Record<string, string>>;
+    requestTimeoutMs: number;
+}
+export interface E2BDesktopRecording {
+    readonly env: Readonly<Record<string, string>>;
+    finish(destination: Writable): Promise<DesktopRecordingMetadata>;
+}
+/** Starts the shared FFmpeg recipe through E2B's command transport; retrieval remains host-owned. */
+export declare function startE2BDesktopRecording(options: RecordingOptions): Promise<E2BDesktopRecording>;
+export {};