humanish 0.139.1 → 0.140.0

package/dist/cli/run-findings.js

@@ -0,0 +1,106 @@
+// The end of a live run's output: what its automatic analysis left, read from the run once and
+// written both ways. The human output gets the analysis line, then the top findings or the command
+// that gets them; `--json` gets the same message and command on `automaticAnalysis`, and a bounded
+// `findings` summary when the analysis left findings.
+import { cwdFlag, readRunFindings } from "./findings.js";
+import { formatFindingsSummary } from "./findings-text.js";
+import { cli } from "./invocation.js";
+import { analysisOutcomeText, wantsJson, writeResult } from "./io.js";
+/** At most this many findings go in `run --json`; `review --json` has every one. */
+const TOP_FINDINGS = 5;
+function findingsSummary(view, review, observerPath) {
+    return {
+        analysisId: view.analysisId,
+        status: view.status,
+        count: view.findings.length,
+        designFindingCount: view.designFindings === null ? null : view.designFindings.length,
+        top: view.findings.slice(0, TOP_FINDINGS).map((finding) => ({
+            id: finding.id,
+            title: finding.title,
+            headline: finding.headline,
+            impact: finding.impact,
+            confidence: finding.confidence,
+            participants: finding.affected.map((participant) => participant.streamId),
+        })),
+        review,
+        observer: observerPath === undefined ? null : `${observerPath}#/report`,
+        path: view.path,
+    };
+}
+/** What the run's analysis left: the message, the command, the human lines and any findings. */
+async function readRunReport(cwd, result, deps) {
+    const outcome = result.automaticAnalysis;
+    if (outcome === undefined || result.runId === undefined || result.runId === "not-created")
+        return undefined;
+    const outcomeLine = `analysis: ${analysisOutcomeText(outcome)}`;
+    const plain = {
+        message: `The automatic analysis was ${analysisOutcomeText(outcome)}.`,
+        nextCommand: null,
+        lines: [outcomeLine],
+    };
+    // A dry run left no evidence, and its own output names the live run.
+    if (outcome.reason === "AUTOMATIC_ANALYSIS_DRY_RUN")
+        return plain;
+    const analysisId = outcome.result?.analysisId;
+    const finished = outcome.state === "complete" || outcome.state === "partial";
+    let view;
+    try {
+        view = await readRunFindings(cwd, result.runId, finished ? analysisId : undefined, deps);
+    }
+    catch {
+        return plain;
+    }
+    const rejected = outcome.result?.rejectedOutputPath;
+    const rejectedLine = rejected
+        ? [
+            `analysis: ${outcome.result?.error?.code ?? "rejected"}; the rejected output is kept locally at ${rejected}`,
+        ]
+        : [];
+    const review = cli(`review --run ${view.runId}${cwdFlag(cwd)}`);
+    if (finished && (view.state === "ready" || view.state === "stale"))
+        return {
+            message: view.message,
+            nextCommand: review,
+            lines: [outcomeLine, ...rejectedLine, ...formatFindingsSummary(view, review)],
+            findings: findingsSummary(view, review, result.observer?.observerPath),
+        };
+    // The line reads "analysis: skipped because ...", as it does without the view.
+    const said = view.message.replace(/^The automatic analysis (?:was )?/, "");
+    return {
+        message: view.message,
+        nextCommand: view.next,
+        lines: [
+            `analysis: ${said}`,
+            ...rejectedLine,
+            ...(view.next === null ? [] : [`next: ${view.next}`]),
+        ],
+    };
+}
+/**
+ * Writes a finished run's result. After the route's own output it says what the automatic
+ * analysis did and the command a person runs next; when the analysis left findings, the top ones.
+ * `--json` carries the same message and command on `automaticAnalysis` and the findings summary
+ * as `findings`. A run with no analysis record is written as writeResult writes it.
+ */
+export async function writeRunResult(command, io, cwd, result, formatHuman, deps = {}) {
+    const report = await readRunReport(cwd, result, deps);
+    if (report === undefined || result.automaticAnalysis === undefined) {
+        writeResult(command, io, result, formatHuman);
+        return;
+    }
+    if (!wantsJson(command)) {
+        writeResult(command, io, result, formatHuman, report.lines);
+        return;
+    }
+    writeResult(command, io, {
+        ...result,
+        automaticAnalysis: {
+            ...result.automaticAnalysis,
+            message: report.message,
+            nextCommand: report.nextCommand,
+        },
+        ...(report.findings === undefined ? {} : { findings: report.findings }),
+    }, 
+    // JSON output never calls the human formatter.
+    () => "");
+}

package/dist/guest/bootstrap.d.ts

@@ -3,6 +3,7 @@ import type { Duplex } from "node:stream";
 import { type BrowserControlIdentity } from "../browser-control/protocol.js";
 import { createBrowserControlClient } from "../browser-control/client.js";
 import { type GuestMediaConfig } from "./media-config.js";
+import { type GuestDisplayConfig } from "./display-config.js";
 export declare const GUEST_BOOTSTRAP_VERSION = 1;
 export declare const GUEST_BOOTSTRAP_LIMITS: Readonly<{
     bytes: number;
@@ -18,7 +19,7 @@ export declare const GUEST_BOOTSTRAP_LIMITS: Readonly<{
 /** Same entry authority as the local desktop's opaque app-port forward. */
 export declare function validateGuestInitialUrl(value: string): string;
 export declare function guestReadyTimeoutMs(initialUrl?: string): number;
-export declare function encodeGuestBootstrap(identity: BrowserControlIdentity, ready?: boolean, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig): Buffer;
+export declare function encodeGuestBootstrap(identity: BrowserControlIdentity, ready?: boolean, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig, display?: GuestDisplayConfig): Buffer;
 export declare function parseGuestBootstrap(bytes: Buffer, revision: string, ready?: boolean): BrowserControlIdentity;
 /** Own the first frame and continue refusing early bytes until synchronous handoff. */
 export declare class GuestBootstrapReader {
@@ -31,6 +32,7 @@ export declare class GuestBootstrapReader {
     initialUrl: string | undefined;
     media: GuestMediaConfig | undefined;
     recording: DesktopRecordingConfig | undefined;
+    display: GuestDisplayConfig | undefined;
     private resolve;
     private reject;
     private readonly header;
@@ -52,4 +54,4 @@ export declare class GuestBootstrapReader {
     close(): void;
 }
 /** Fixed preface on an already acquired Firecracker stream; no path discovery/retry. */
-export declare function connectGuestBootstrap(stream: Duplex, identity: BrowserControlIdentity, signal: AbortSignal, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig): Promise<ReturnType<typeof createBrowserControlClient>>;
+export declare function connectGuestBootstrap(stream: Duplex, identity: BrowserControlIdentity, signal: AbortSignal, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig, display?: GuestDisplayConfig): Promise<ReturnType<typeof createBrowserControlClient>>;

package/dist/guest/bootstrap.js

@@ -3,9 +3,10 @@ import { validateBrowserControlIdentity, sameBrowserControlIdentity, } from "../
 import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.js";
 import { createBrowserControlClient } from "../browser-control/client.js";
 import { guestMediaConfigSchema } from "./media-config.js";
+import { guestDisplayConfigSchema } from "./display-config.js";
 export const GUEST_BOOTSTRAP_VERSION = 1;
 export const GUEST_BOOTSTRAP_LIMITS = Object.freeze({
-    bytes: 65_536 + 1024,
+    bytes: 65_536 + 2048,
     readyBytes: 1024,
     initialUrlBytes: 65_536,
     admissionMs: 5000,
@@ -42,7 +43,7 @@ export function guestReadyTimeoutMs(initialUrl) {
             ? 0
             : GUEST_BOOTSTRAP_LIMITS.navigationMs + GUEST_BOOTSTRAP_LIMITS.paintMs));
 }
-function canonical(identity, ready, initialUrl, media, recording) {
+function canonical(identity, ready, initialUrl, media, recording, display) {
     const { generation, challenge, runtimeRevision } = validateBrowserControlIdentity(identity);
     const fixed = { generation, challenge, runtimeRevision };
     if (initialUrl !== undefined && (ready || validateGuestInitialUrl(initialUrl) !== initialUrl))
@@ -52,6 +53,8 @@ function canonical(identity, ready, initialUrl, media, recording) {
     if (recording !== undefined &&
         (ready || !desktopRecordingConfigSchema.safeParse(recording).success))
         throw refused();
+    if (display !== undefined && (ready || !guestDisplayConfigSchema.safeParse(display).success))
+        throw refused();
     return JSON.stringify(ready
         ? { version: 1, ready: true, identity: fixed }
         : {
@@ -62,10 +65,11 @@ function canonical(identity, ready, initialUrl, media, recording) {
             ...(recording === undefined
                 ? {}
                 : { recording: desktopRecordingConfigSchema.parse(recording) }),
+            ...(display === undefined ? {} : { display: guestDisplayConfigSchema.parse(display) }),
         });
 }
-export function encodeGuestBootstrap(identity, ready = false, initialUrl, media, recording) {
-    const bytes = Buffer.from(canonical(identity, ready, initialUrl, media, recording));
+export function encodeGuestBootstrap(identity, ready = false, initialUrl, media, recording, display) {
+    const bytes = Buffer.from(canonical(identity, ready, initialUrl, media, recording, display));
     if (bytes.length > (ready ? GUEST_BOOTSTRAP_LIMITS.readyBytes : GUEST_BOOTSTRAP_LIMITS.bytes))
         throw refused();
     const frame = Buffer.alloc(4 + bytes.length);
@@ -89,16 +93,18 @@ function parseBootstrap(bytes, revision, ready) {
         const initialUrl = "initialUrl" in value ? value.initialUrl : undefined;
         const media = "media" in value ? guestMediaConfigSchema.parse(value.media) : undefined;
         const recording = "recording" in value ? desktopRecordingConfigSchema.parse(value.recording) : undefined;
+        const display = "display" in value ? guestDisplayConfigSchema.parse(value.display) : undefined;
         if (initialUrl !== undefined && typeof initialUrl !== "string")
             throw refused();
         if (identity.runtimeRevision !== revision ||
-            canonical(identity, ready, initialUrl, media, recording) !== bytes.toString("ascii"))
+            canonical(identity, ready, initialUrl, media, recording, display) !== bytes.toString("ascii"))
             throw refused();
         return {
             identity,
             ...(initialUrl === undefined ? {} : { initialUrl }),
             ...(media === undefined ? {} : { media }),
             ...(recording === undefined ? {} : { recording }),
+            ...(display === undefined ? {} : { display }),
         };
     }
     catch {
@@ -116,6 +122,7 @@ export class GuestBootstrapReader {
     initialUrl;
     media;
     recording;
+    display;
     resolve;
     reject;
     header = Buffer.alloc(4);
@@ -190,6 +197,7 @@ export class GuestBootstrapReader {
                 this.initialUrl = parsed.initialUrl;
                 this.media = parsed.media;
                 this.recording = parsed.recording;
+                this.display = parsed.display;
                 this.admitted = true;
                 clearTimeout(this.timer);
                 this.resolve(parsed.identity);
@@ -244,9 +252,9 @@ export class GuestBootstrapReader {
     }
 }
 /** Fixed preface on an already acquired Firecracker stream; no path discovery/retry. */
-export async function connectGuestBootstrap(stream, identity, signal, initialUrl, media, recording) {
+export async function connectGuestBootstrap(stream, identity, signal, initialUrl, media, recording, display) {
     validateBrowserControlIdentity(identity);
-    const request = encodeGuestBootstrap(identity, false, initialUrl, media, recording);
+    const request = encodeGuestBootstrap(identity, false, initialUrl, media, recording, display);
     await new Promise((resolve, reject) => {
         let bytes = Buffer.alloc(0), done = false;
         const timer = setTimeout(() => finish(new ComputerUseExecutorError("deadline_exceeded", "not_dispatched")), GUEST_BOOTSTRAP_LIMITS.connectMs);

package/dist/guest/display-config.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+/** The screen a guest starts when the bootstrap names none. */
+export declare const DEFAULT_GUEST_SCREEN: Readonly<{
+    width: 960;
+    height: 720;
+}>;
+/**
+ * The screens a guest admits. The narrowest is the narrowest window Chromium renders; the widest
+ * is the widest device preset. At 1920×1200 an uncompressed 24-bit frame is 6.9 MB, so every
+ * capture fits the 8 MiB browser-control PNG limit. Below 480 pixels high the page area under
+ * Chromium's toolbar is too short to use.
+ */
+export declare const GUEST_SCREEN_LIMITS: Readonly<{
+    minWidth: 500;
+    maxWidth: 1920;
+    minHeight: 480;
+    maxHeight: 1200;
+}>;
+/** One participant's Xvfb screen, and the mobile emulation its pages get, if any. */
+export declare const guestDisplayConfigSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    mobileEmulation: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        deviceScaleFactor: z.ZodNumber;
+        touch: z.ZodBoolean;
+        userAgent: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type GuestDisplayConfig = z.infer<typeof guestDisplayConfigSchema>;

package/dist/guest/display-config.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { MIN_DESKTOP_RENDER_WIDTH } from "../study/device-presets.js";
+/** The screen a guest starts when the bootstrap names none. */
+export const DEFAULT_GUEST_SCREEN = Object.freeze({ width: 960, height: 720 });
+/**
+ * The screens a guest admits. The narrowest is the narrowest window Chromium renders; the widest
+ * is the widest device preset. At 1920×1200 an uncompressed 24-bit frame is 6.9 MB, so every
+ * capture fits the 8 MiB browser-control PNG limit. Below 480 pixels high the page area under
+ * Chromium's toolbar is too short to use.
+ */
+export const GUEST_SCREEN_LIMITS = Object.freeze({
+    minWidth: MIN_DESKTOP_RENDER_WIDTH,
+    maxWidth: 1920,
+    minHeight: 480,
+    maxHeight: 1200,
+});
+const side = (max) => z.number().int().min(1).max(max);
+/** One participant's Xvfb screen, and the mobile emulation its pages get, if any. */
+export const guestDisplayConfigSchema = z
+    .object({
+    width: z.number().int().min(GUEST_SCREEN_LIMITS.minWidth).max(GUEST_SCREEN_LIMITS.maxWidth),
+    height: z.number().int().min(GUEST_SCREEN_LIMITS.minHeight).max(GUEST_SCREEN_LIMITS.maxHeight),
+    mobileEmulation: z
+        .object({
+        width: side(GUEST_SCREEN_LIMITS.maxWidth),
+        height: side(GUEST_SCREEN_LIMITS.maxHeight),
+        deviceScaleFactor: z.number().positive().max(4),
+        touch: z.boolean(),
+        // The bootstrap frame is ASCII; a launch flag carries it too.
+        userAgent: z.string().regex(/^[\x20-\x7e]{1,512}$/),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();

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

@@ -1,5 +1,6 @@
 import { type Stats } from "node:fs";
 import { type BrowserContext, type Page } from "playwright-core";
+import { type GuestDisplayConfig } from "./display-config.js";
 import type { GuestRuntimeDesktop } from "./runtime.js";
 import type { GuestMediaConfig } from "./media-config.js";
 import { type GuestDesktopMediaOptions } from "./desktop-media.js";
@@ -10,7 +11,7 @@ export declare const GUEST_RUNTIME_PATHS: Readonly<{
     run: "/run/humanish";
     home: "/home/humanish";
 }>;
-export type GuestRuntimePhase = "layout" | "xauthority" | "display" | "window_manager" | "media" | "recording" | "browser" | "sandbox" | "focus" | "fixture" | "navigation";
+export type GuestRuntimePhase = "layout" | "xauthority" | "display" | "window_manager" | "media" | "recording" | "browser" | "sandbox" | "emulation" | "focus" | "fixture" | "navigation";
 /** Initial document only: do not wait for app data, subresources or network idle. */
 export declare function navigateGuestInitialPage(page: Pick<Page, "goto" | "waitForFunction">, initialUrl: string, signal: AbortSignal): Promise<void>;
 /** /run/humanish and /home/humanish: real directories private to the guest user. */
@@ -19,7 +20,11 @@ export declare function isPrivateGuestDirectory(stat: Pick<Stats, "isDirectory"
 export declare function isPinnedOpenboxConfig(stat: Pick<Stats, "isFile" | "uid" | "gid" | "nlink" | "size" | "mode">): boolean;
 /** chrome://sandbox must report every namespace and seccomp feature and the overall verdict. */
 export declare function isAdequatelySandboxed(report: string): boolean;
-export declare function chromiumLaunchArgs(media: GuestMediaConfig | undefined): string[];
+/**
+ * The window leaves 20 pixels above and below it on the participant's screen. A mobile participant's
+ * user agent and touch flags reach every page and worker; CDP emulation sets the viewport.
+ */
+export declare function chromiumLaunchArgs(media: GuestMediaConfig | undefined, display?: GuestDisplayConfig): string[];
 /** The devices to start; the permission policy only changes Chromium's flags. */
 export declare function desktopMediaRequest(media: GuestMediaConfig): GuestDesktopMediaOptions["media"];
 /** Audio needs Pulse, which only the microphone path starts. */
@@ -27,7 +32,7 @@ export declare function recorderAudio(recording: DesktopRecordingConfig, media:
     audioSources: DesktopRecordingAudioSource[];
     pulseReady: boolean;
 };
-/** Fixed guest layout with an optional admitted initial loopback app URL. */
+/** Fixed guest layout with an optional admitted initial loopback app URL and participant screen. */
 export declare function createGuestRuntimeDesktop(options: {
     signal: AbortSignal;
     onTerminal(): void;
@@ -35,6 +40,7 @@ export declare function createGuestRuntimeDesktop(options: {
     initialUrl?: string;
     media?: GuestMediaConfig;
     recording?: DesktopRecordingConfig;
+    display?: GuestDisplayConfig;
 }): Promise<GuestRuntimeDesktop & {
     readonly owner: {
         context: BrowserContext;

package/dist/guest/runtime-desktop.js

@@ -3,6 +3,8 @@ 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 { DEFAULT_GUEST_SCREEN } from "./display-config.js";
+import { mobileEmulationCommands, mobileEmulationLaunchFlags, } from "../study/mobile-emulation.js";
 import { createGuestDesktopNativeTools } from "./desktop-native.js";
 import { createGuestChromiumText } from "./chromium-text.js";
 import { createGuestBrowserTools } from "./browser-tools.js";
@@ -33,16 +35,18 @@ const GUEST_RUNTIME_ENV = Object.freeze({
     TMPDIR: "/tmp",
 });
 const CONFIG_SHA = "4ae1c52eab748a3624b3948ce792647be258caba70c8c72038b9a43be6459552";
-const XVFB_ARGS = Object.freeze([
-    ":0",
-    "-screen",
-    "0",
-    "960x720x24",
-    "-nolisten",
-    "tcp",
-    "-auth",
-    GUEST_RUNTIME_ENV.XAUTHORITY,
-]);
+function xvfbArgs(screen) {
+    return [
+        ":0",
+        "-screen",
+        "0",
+        `${screen.width}x${screen.height}x24`,
+        "-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. */
@@ -86,10 +90,16 @@ 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) {
+/**
+ * The window leaves 20 pixels above and below it on the participant's screen. A mobile participant's
+ * user agent and touch flags reach every page and worker; CDP emulation sets the viewport.
+ */
+export function chromiumLaunchArgs(media, display) {
+    const screen = display ?? DEFAULT_GUEST_SCREEN;
     return [
-        "--window-size=960,680",
+        `--window-size=${screen.width},${screen.height - 40}`,
         "--window-position=0,20",
+        ...mobileEmulationLaunchFlags(display?.mobileEmulation),
         "--disable-background-networking",
         "--disable-component-update",
         "--no-first-run",
@@ -162,12 +172,12 @@ async function waitForDisplay(processes, signal, check) {
     throw setupFailed();
 }
 /** A recorder that fails to start leaves the desktop usable; finishRecording reports it. */
-async function startGuestRecorder(recording, media, env, signal) {
+async function startGuestRecorder(recording, media, screen, env, signal) {
     try {
         return await startDesktopRecorder({
             display: ":0",
-            width: 960,
-            height: 720,
+            width: screen.width,
+            height: screen.height,
             outputPath: RECORDING_PATH,
             env,
             signal,
@@ -178,7 +188,7 @@ async function startGuestRecorder(recording, media, env, signal) {
         return undefined;
     }
 }
-async function launchGuestBrowser(state, media, check) {
+async function launchGuestBrowser(state, media, display, check) {
     state.pendingContext = chromium.launchPersistentContext(`${GUEST_RUNTIME_PATHS.home}/browser`, {
         executablePath: "/usr/bin/chromium",
         headless: false,
@@ -186,7 +196,7 @@ async function launchGuestBrowser(state, media, check) {
         viewport: null,
         env: state.recorder?.env ?? state.media?.env ?? GUEST_RUNTIME_ENV,
         timeout: 25_000,
-        args: chromiumLaunchArgs(media),
+        args: chromiumLaunchArgs(media, display),
     });
     // A browser that finishes launching after the stop is closed here; teardown may not see it.
     void state.pendingContext.then((browser) => {
@@ -216,6 +226,25 @@ async function verifyBrowserSandbox(context, page, check) {
     check();
     return report;
 }
+/** Sends the emulation commands over a page session that stays attached, so they hold. */
+async function emulateOn(context, page, request) {
+    const session = await context.newCDPSession(page);
+    for (const { method, params } of mobileEmulationCommands(request))
+        // Playwright types send by protocol method; these names come from the fixed list.
+        await session.send(method, params);
+}
+/**
+ * Emulate a phone on the launch page before it navigates, so the first document loads with the
+ * phone's viewport, touch and user agent. Tabs opened later get the same overrides when they open;
+ * a tab that closes before that is left alone.
+ */
+async function emulateMobile(browser, request, check) {
+    await emulateOn(browser.context, browser.page, request);
+    check();
+    browser.context.on("page", (page) => {
+        void emulateOn(browser.context, page, request).catch(() => { });
+    });
+}
 /** Text actions run only while the browser window that setup saw still has focus. */
 function focusGuard(native, window) {
     return async (actionSignal) => {
@@ -223,7 +252,7 @@ function focusGuard(native, window) {
             throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
     };
 }
-async function createGuestExecutorFor(state, browser, signal, onTerminal, check) {
+async function createGuestExecutorFor(state, browser, screen, signal, onTerminal, check) {
     const native = createGuestDesktopNativeTools({
         display: ":0",
         temporaryDirectory: `${GUEST_RUNTIME_PATHS.run}/capture`,
@@ -236,8 +265,8 @@ async function createGuestExecutorFor(state, browser, signal, onTerminal, check)
         assertFocusedWindow: focusGuard(native, window),
     });
     return createGuestDesktopExecutor({
-        width: 960,
-        height: 720,
+        width: screen.width,
+        height: screen.height,
         tools: createGuestBrowserTools(native, state.content),
         authoritySignal: signal,
         onTerminal,
@@ -329,10 +358,11 @@ function closeGuestRuntimeDesktop(state, processes, controller, detach) {
     controller.abort();
     return state.closing;
 }
-/** Fixed guest layout with an optional admitted initial loopback app URL. */
+/** Fixed guest layout with an optional admitted initial loopback app URL and participant screen. */
 export async function createGuestRuntimeDesktop(options) {
     if (options.initialUrl !== undefined)
         validateGuestInitialUrl(options.initialUrl);
+    const screen = options.display ?? DEFAULT_GUEST_SCREEN;
     const controller = new AbortController();
     const signal = AbortSignal.any([options.signal, controller.signal]);
     const state = { stopping: false };
@@ -363,7 +393,7 @@ export async function createGuestRuntimeDesktop(options) {
         progress("xauthority");
         await authorizeDisplay(processes, check);
         progress("display");
-        processes.spawn("/usr/bin/Xvfb", XVFB_ARGS, undefined, true);
+        processes.spawn("/usr/bin/Xvfb", xvfbArgs(screen), 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);
@@ -381,15 +411,19 @@ export async function createGuestRuntimeDesktop(options) {
         if (options.recording !== undefined) {
             progress("recording");
             const env = state.media?.env ?? GUEST_RUNTIME_ENV;
-            state.recorder = await startGuestRecorder(options.recording, options.media, env, signal);
+            state.recorder = await startGuestRecorder(options.recording, options.media, screen, env, signal);
             check();
         }
         progress("browser");
-        const browser = await launchGuestBrowser(state, options.media, check);
+        const browser = await launchGuestBrowser(state, options.media, options.display, check);
         progress("sandbox");
         const sandboxReport = await verifyBrowserSandbox(browser.context, browser.page, check);
+        if (options.display?.mobileEmulation !== undefined) {
+            progress("emulation");
+            await emulateMobile(browser, options.display.mobileEmulation, check);
+        }
         progress("focus");
-        const executor = await createGuestExecutorFor(state, browser, signal, options.onTerminal, check);
+        const executor = await createGuestExecutorFor(state, browser, screen, signal, options.onTerminal, check);
         if (options.initialUrl !== undefined) {
             progress("navigation");
             await navigateGuestInitialPage(browser.page, options.initialUrl, signal);

package/dist/guest/runtime.d.ts

@@ -1,6 +1,7 @@
 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 { GuestDisplayConfig } from "./display-config.js";
 import type { DesktopRecordingConfig, DesktopRecordingMetadata } from "../evidence/desktop-recording-types.js";
 export interface GuestRuntimeDesktop {
     executor: CuaExecutor;
@@ -18,7 +19,7 @@ export interface GuestRuntimeOptions {
     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>;
+    createDesktop(signal: AbortSignal, onTerminal: () => void, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig, display?: GuestDisplayConfig): Promise<GuestRuntimeDesktop>;
 }
 /** One admitted desktop and one dispatcher. The owner retains physical teardown. */
 export declare function runGuestRuntime(options: GuestRuntimeOptions): Promise<{

package/dist/guest/runtime.js

@@ -83,7 +83,7 @@ export async function runGuestRuntime(options) {
             void close();
         }, guestReadyTimeoutMs(reader.initialUrl));
         options.marker("A");
-        preparing = options.createDesktop(authority, terminal, reader.initialUrl, reader.media, reader.recording);
+        preparing = options.createDesktop(authority, terminal, reader.initialUrl, reader.media, reader.recording, reader.display);
         desktop = await Promise.race([
             preparing,
             new Promise((_, reject) => {

package/dist/guest-runtime-main.js

@@ -27,12 +27,13 @@ try {
             if (writeSync(Number(markerFd), value) !== 1)
                 throw new Error();
         },
-        createDesktop: (signal, onTerminal, initialUrl, media, recording) => createGuestRuntimeDesktop({
+        createDesktop: (signal, onTerminal, initialUrl, media, recording, display) => createGuestRuntimeDesktop({
             signal,
             onTerminal,
             ...(initialUrl === undefined ? {} : { initialUrl }),
             ...(media === undefined ? {} : { media }),
             ...(recording === undefined ? {} : { recording }),
+            ...(display === undefined ? {} : { display }),
         }),
     });
     const result = await runtime.closed;

package/dist/routes/computer-use/e2b-desktop/fidelity.js

@@ -2,18 +2,17 @@
 // browser-state observer that watches it for drift, and the final browser geometry.
 import { redactText, toErrorMessage } from "../../../evidence/redaction.js";
 import { readDetachedLog } from "../../../substrates/detached.js";
-import { applyMobileEmulation, DEFAULT_MOBILE_USER_AGENT, makeChromeBrowserStateObserver, } from "../../../substrates/e2b/desktop-cdp.js";
+import { applyMobileEmulation, makeChromeBrowserStateObserver, } from "../../../substrates/e2b/desktop-cdp.js";
+import { mobileEmulationLaunchFlags, participantMobileEmulation, } from "../../../study/mobile-emulation.js";
 import { captureDesktopBrowserGeometry } from "../../../substrates/e2b/desktop-geometry.js";
 import { e2bShell } from "../../../substrates/e2b/shell.js";
+/** The participant's emulation request; see participantMobileEmulation for who gets one. */
+function emulationFor(residual, spec) {
+    return participantMobileEmulation(residual.execution?.desktop?.fidelity, spec.planned.device.preset);
+}
 /** Only participants on a mobile preset are emulated; the flags go on the browser command line. */
 export function mobileLaunchFlags(residual, spec) {
-    const requested = residual.execution?.desktop?.fidelity;
-    if (!requested?.mobileEmulation || !spec.planned.device.preset.isMobile)
-        return [];
-    return [
-        `--user-agent=${requested.userAgent ?? DEFAULT_MOBILE_USER_AGENT}`,
-        ...(requested.touch === false ? [] : ["--touch-events=enabled"]),
-    ];
+    return mobileEmulationLaunchFlags(emulationFor(residual, spec));
 }
 /** The launched browser's DevTools address, as far as the launch recorded it. */
 export function cdpEndpoint(identity, targetUrl) {
@@ -33,24 +32,18 @@ export function cdpEndpoint(identity, targetUrl) {
  */
 export async function applyParticipantMobileFidelity(args) {
     const { spec, deps } = args;
-    const request = deps.residual.execution?.desktop?.fidelity;
+    const request = emulationFor(deps.residual, spec);
     const none = {
         applied: undefined,
         emulatedTargetId: undefined,
         holderName: undefined,
     };
-    if (!request?.mobileEmulation || !spec.planned.device.preset.isMobile)
+    if (request === undefined)
         return none;
     if (args.browserFamily !== "chromium") {
         throw new Error(`execution.desktop.fidelity.mobileEmulation needs Chrome or Chromium for participant ${spec.planned.id}; the launched browser family is ${args.browserFamily}. Set execution.desktop.browser: chrome.`);
     }
-    const applied = await applyMobileEmulation(args.desktop, deps.requestTimeoutMs, cdpEndpoint(args.launchIdentity, args.targetUrl), {
-        width: spec.planned.device.preset.width,
-        height: spec.planned.device.preset.height,
-        deviceScaleFactor: request.deviceScaleFactor ?? spec.planned.device.preset.deviceScaleFactor,
-        touch: request.touch ?? true,
-        userAgent: request.userAgent ?? DEFAULT_MOBILE_USER_AGENT,
-    }, {
+    const applied = await applyMobileEmulation(args.desktop, deps.requestTimeoutMs, cdpEndpoint(args.launchIdentity, args.targetUrl), request, {
         targetId: args.targetId,
         ...(args.network === undefined ? {} : { network: args.network.request }),
     });