humanish 0.105.0 → 0.106.0

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

@@ -0,0 +1,198 @@
+// The first half of an E2B desktop lane's preparation: acquire the sandbox, verify its screen, and
+// provision the subject. Each step fills the lane's state; a step that cannot proceed throws.
+import { redactText } from "../../../evidence/redaction.js";
+import { provisionCloneSubject } from "../../../subject/clone.js";
+import { provisionDesktopCli } from "../../../subject/desktop-cli.js";
+import { provisionLocalTreeSubject } from "../../../subject/local-tree.js";
+import { inspectDesktopScreenGeometry } from "../../../substrates/e2b/desktop-geometry.js";
+import { observeDesktopResources } from "../../../substrates/e2b/desktop-resources.js";
+import { acquireE2BDesktopSandbox, e2bDesktopTemplate } from "../../../substrates/e2b/sandbox.js";
+import { loadE2BDesktopModule } from "../../../substrates/e2b/sdk.js";
+import { e2bShell } from "../../../substrates/e2b/shell.js";
+import { attachReceivingInbox, participantCommsEnv, startCommsCatch } from "./comms.js";
+export const CUA_ACTOR_LAB_PROVIDER_METADATA = {
+    mode: "cua-actor-lab",
+    tool: "humanish",
+};
+/**
+ * Create the lane's sandbox, record its resources, run the adopter's prepare hook, and attach the
+ * lane's inbox and comms catch. Returns the sandbox, which the later steps drive.
+ */
+export async function acquireParticipantDesktop(ctx, state) {
+    const { spec, deps, warnings } = ctx;
+    const { config, subjectEnvNames, env } = deps;
+    const subjectEnvValues = config.subject.envValues ?? {};
+    // Off-app comms (#297): the base-URL env is injected at sandbox create, so the app reads it at
+    // boot; the catch starts right after create.
+    const commsEnv = participantCommsEnv(ctx.comms);
+    const desktopModule = await (deps.hooks.loadDesktopModule ?? loadE2BDesktopModule)();
+    // An explicit template wins. Speech gets the versioned media image; ordinary
+    // browser studies retain the SDK default desktop.
+    const acquired = await acquireE2BDesktopSandbox({
+        module: desktopModule,
+        options: {
+            apiKey: deps.e2bApiKey,
+            requestTimeoutMs: deps.requestTimeoutMs,
+            timeoutMs: deps.sandboxMs,
+            metadata: {
+                ...CUA_ACTOR_LAB_PROVIDER_METADATA,
+                labId: config.id,
+                simId: spec.recordId,
+                laneId: spec.planned.id,
+                laneIndex: String(spec.planned.index),
+                laneCount: String(deps.participantCount),
+            },
+            // The participant's model key never enters the sandbox (the model drives from outside).
+            // The subject's declared env names are provisioned here on the clone route.
+            // Three sources, in precedence order: committed non-secret config (subject.envValues), then
+            // secret values forwarded from the caller's environment (subject.env), then the harness's own
+            // comms wiring, which must win because only it knows the catch's address.
+            ...(subjectEnvNames.length > 0 ||
+                Object.keys(subjectEnvValues).length > 0 ||
+                Object.keys(commsEnv).length > 0
+                ? {
+                    envs: {
+                        ...subjectEnvValues,
+                        ...Object.fromEntries(subjectEnvNames.map((name) => [name, env[name]])),
+                        ...commsEnv,
+                    },
+                }
+                : {}),
+            resolution: spec.planned.device.resolution,
+            dpi: 96,
+            lifecycle: { onTimeout: "kill" },
+        },
+        template: e2bDesktopTemplate(config),
+        retry: {
+            // The default loader reclaims an acquired handle before retrying failed desktop startup.
+            // Its error names the cleanup outcome; pre-construction allocation failures remain unowned.
+            onRetry: (reason) => {
+                const named = redactText(deps.scrubKnownValues(reason));
+                warnings.push(`Sandbox create for participant ${spec.planned.id} retried once after a transient provider error (${named}).`);
+                ctx.onSubjectPhase({
+                    at: new Date(deps.now()).toISOString(),
+                    type: "cua-lab.sandbox.create.retry",
+                    message: `sandbox create retried once (${named})`,
+                });
+            },
+        },
+        // The receipt is on disk before any work, so `humanish reclaim` can kill this lane's
+        // sandbox by exact id after an interrupt.
+        receipt: { root: deps.artifactRoot, participantId: spec.planned.id, now: deps.now },
+    });
+    const desktop = acquired.sandbox;
+    state.desktop = desktop;
+    const shell = e2bShell(desktop);
+    state.allocation = acquired.allocation;
+    state.sandboxId = acquired.allocation.resourceId;
+    // The billed span starts the instant the sandbox exists.
+    state.sandboxCreatedAtMs = deps.now();
+    const desktopResources = await observeDesktopResources(desktop);
+    state.desktopResources = desktopResources;
+    if ("reason" in desktopResources) {
+        warnings.push(`Desktop resource size unavailable (${desktopResources.reason}); compute cost remains unpriced.`);
+    }
+    if (deps.hooks.prepareDesktop) {
+        await deps.hooks.prepareDesktop(desktop, {
+            laneId: spec.planned.id,
+            laneIndex: spec.planned.index,
+            laneCount: deps.participantCount,
+        });
+    }
+    if (deps.receiving) {
+        state.receivingInboxUrl = await attachReceivingInbox(shell, spec, { ...deps, receiving: deps.receiving }, ctx.targetUrl);
+        state.commsArtifactPath = "comms/receiving.json";
+    }
+    if (ctx.comms)
+        state.commsCatch = await startCommsCatch(shell, ctx.comms, deps.requestTimeoutMs);
+    return desktop;
+}
+/**
+ * Verify the lane's screen in the sandbox. A mismatch fails the lane closed unless the run records
+ * requested and verified geometry side by side.
+ */
+export async function verifyParticipantScreen(ctx, state, desktop) {
+    const { spec, deps, warnings } = ctx;
+    const screenGeometry = await inspectDesktopScreenGeometry({
+        desktop,
+        participantId: spec.planned.id,
+        requestedScreen: spec.planned.device.resolution,
+        requestTimeoutMs: deps.requestTimeoutMs,
+    });
+    if (screenGeometry.verified) {
+        state.desktopGeometry = {
+            ...state.desktopGeometry,
+            screen: { ...state.desktopGeometry.screen, verified: screenGeometry.verified },
+        };
+    }
+    if (screenGeometry.warning) {
+        warnings.push(screenGeometry.warning);
+        state.desktopGeometry = { ...state.desktopGeometry, warnings: [screenGeometry.warning] };
+    }
+    if (screenGeometry.error && deps.screenMismatchPolicy !== "record-evidence") {
+        state.failureCode = "HUMANISH_CUA_LAB_DEVICE_GEOMETRY";
+        throw new Error(screenGeometry.error);
+    }
+    if (screenGeometry.error && screenGeometry.verified) {
+        // record-evidence policy: the bundle keeps requested vs verified as separate facts and
+        // discloses the divergence instead of failing this lane's world mid-flight.
+        const mismatchWarning = deps.scrubKnownValues(`Participant ${spec.planned.id} requested a ${spec.planned.device.resolution[0]}x${spec.planned.device.resolution[1]} screen but xdpyinfo reports ${screenGeometry.verified.width}x${screenGeometry.verified.height}; recording requested vs verified separately instead of failing the participant closed.`);
+        warnings.push(mismatchWarning);
+        state.desktopGeometry = {
+            ...state.desktopGeometry,
+            warnings: [...(state.desktopGeometry.warnings ?? []), mismatchWarning],
+        };
+    }
+}
+/** Install a desktop CLI, or clone or unpack the subject and serve it, in the sandbox. */
+export async function provisionParticipantSubject(ctx, state, desktop) {
+    const { deps } = ctx;
+    const { config, cloneRoute, localTreeRoute, serve, subjectRepo } = deps;
+    const shell = e2bShell(desktop);
+    if (ctx.desktopCliRoute) {
+        // Prepare the runtime and any declared product install, UNKEYED. With install omitted,
+        // the participant discovers and installs the product from its public surfaces.
+        await provisionDesktopCli(shell, {
+            product: config.subject.product?.name ?? "",
+            ...(config.subject.product?.install === undefined
+                ? {}
+                : { install: config.subject.product.install }),
+            requestTimeoutMs: deps.requestTimeoutMs,
+            scrub: deps.scrubKnownValues,
+            onPhase: ctx.onSubjectPhase,
+        });
+    }
+    if (cloneRoute && serve && subjectRepo) {
+        state.subjectCommit = await provisionCloneSubject(shell, {
+            repo: subjectRepo,
+            depth: config.subject.clone?.depth ?? 1,
+            serve,
+            ...(config.subject.state === undefined ? {} : { state: config.subject.state }),
+            hasGithubToken: deps.hasGithubToken,
+            requestTimeoutMs: deps.requestTimeoutMs,
+            scrub: deps.scrubKnownValues,
+            onCommit: (commit) => {
+                state.subjectCommit = commit;
+            },
+            onStateStep: (record) => {
+                state.stateStepRecords.push(record);
+            },
+            onPhase: ctx.onSubjectPhase,
+            ...deps.hooks.detachedTimers,
+        });
+    }
+    else if (localTreeRoute && serve && deps.localTreeArchiveBuffer) {
+        await provisionLocalTreeSubject(shell, {
+            archiveBuffer: deps.localTreeArchiveBuffer,
+            serve,
+            ...(config.subject.state === undefined ? {} : { state: config.subject.state }),
+            requestTimeoutMs: deps.requestTimeoutMs,
+            scrub: deps.scrubKnownValues,
+            onStateStep: (record) => {
+                state.stateStepRecords.push(record);
+            },
+            onPhase: ctx.onSubjectPhase,
+            ...deps.hooks.detachedTimers,
+        });
+    }
+}

package/dist/routes/computer-use/e2b-desktop/start.d.ts

@@ -0,0 +1,14 @@
+import type { E2BDesktopSandbox } from "../../../substrates/e2b/sdk.js";
+import type { E2BParticipantContext, E2BParticipantState } from "./state.js";
+/** Start the declared speech worker and screen recording. A recording that cannot start is a warning. */
+export declare function startParticipantMedia(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
+/**
+ * Open what the participant sees: the browser at the target, with any declared camera and mobile
+ * fidelity, or a terminal window on the desktop-cli route.
+ */
+export declare function openParticipantSurface(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
+/**
+ * Measure the browser window and start the live stream. A stream that cannot start is a warning;
+ * unusable browser geometry fails the lane before any participant action.
+ */
+export declare function startParticipantStream(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;

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

@@ -0,0 +1,193 @@
+// The second half of an E2B desktop lane's preparation, and the start of its session: speech and
+// recording, then the browser or terminal the participant sees, then the live stream. Each step
+// fills the lane's state.
+import { redactText, toErrorMessage } from "../../../evidence/redaction.js";
+import { CHROME_DEVTOOLS_PORT, DESKTOP_SETTLE_MS, openDesktopBrowserTarget, openDesktopTerminal, startDesktopStream, } from "../../../substrates/e2b/desktop-browser.js";
+import { captureDesktopBrowserGeometry } from "../../../substrates/e2b/desktop-geometry.js";
+import { prepareDesktopMedia, startE2BDesktopMedia, } from "../../../substrates/e2b/desktop-media.js";
+import { startE2BDesktopRecording } from "../../../substrates/e2b/desktop-recording.js";
+import { applyParticipantMobileFidelity, mobileLaunchFlags } from "./fidelity.js";
+/** Start the declared speech worker and screen recording. A recording that cannot start is a warning. */
+export async function startParticipantMedia(ctx, state, desktop) {
+    const { spec, deps, warnings } = ctx;
+    const requestedMedia = deps.config.execution?.desktop?.media;
+    if (!ctx.desktopCliRoute && requestedMedia?.microphone?.source === "speech") {
+        state.speech = await startE2BDesktopMedia({
+            desktop,
+            media: requestedMedia,
+            signal: state.mediaStop.signal,
+            onTerminal: () => state.mediaStop.abort(),
+            requestTimeoutMs: deps.requestTimeoutMs,
+        });
+    }
+    const requestedRecording = deps.config.execution?.desktop?.recording;
+    if (requestedRecording) {
+        try {
+            state.recording = await startE2BDesktopRecording({
+                desktop,
+                width: spec.planned.device.resolution[0],
+                height: spec.planned.device.resolution[1],
+                audio: requestedRecording.audio,
+                ...(state.speech === undefined ? {} : { pulseEnv: state.speech.env }),
+                requestTimeoutMs: deps.requestTimeoutMs,
+            });
+        }
+        catch (error) {
+            warnings.push(`Desktop recording startup failed; the study continues without video: ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
+        }
+    }
+}
+/**
+ * Open what the participant sees: the browser at the target, with any declared camera and mobile
+ * fidelity, or a terminal window on the desktop-cli route.
+ */
+export async function openParticipantSurface(ctx, state, desktop) {
+    const { spec, deps, warnings, targetUrl } = ctx;
+    const { config } = deps;
+    if (ctx.desktopCliRoute) {
+        // A terminal window, opened the way the browser is opened on every other route: the
+        // participant arrives at a desktop with the thing they were asked to use already in front
+        // of them. They can still open another from the dock — that is the point of a desktop.
+        await openDesktopTerminal(desktop, deps.requestTimeoutMs, config.subject.product?.workdir);
+        await desktop.wait(DESKTOP_SETTLE_MS).catch(() => undefined);
+        return;
+    }
+    const requestedMedia = config.execution?.desktop?.media;
+    // A declared camera (#509) is in place before the browser starts: the feed is generated or
+    // uploaded first, and a feed that cannot be produced fails the lane closed here.
+    const mediaEvidence = requestedMedia === undefined
+        ? undefined
+        : await prepareDesktopMedia(desktop, requestedMedia, config.policies?.mediaPermission ?? "prompt", deps.labCwd, deps.requestTimeoutMs);
+    const emulationFlags = mobileLaunchFlags(config, spec);
+    const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser, [...emulationFlags, ...(mediaEvidence?.flags ?? [])], state.speech?.env ?? state.recording?.env);
+    state.desktopBrowser =
+        mediaEvidence === undefined
+            ? browserLaunch.evidence
+            : {
+                requested: config.execution?.desktop?.browser ?? "default",
+                ...browserLaunch.evidence,
+                media: mediaEvidence,
+            };
+    if (mediaEvidence !== undefined && browserLaunch.family !== "chromium") {
+        throw new Error(`execution.desktop.media needs Chrome or Chromium for participant ${spec.planned.id} (the fake-device flags are Chromium's); the launched browser family is ${browserLaunch.family}. Set execution.desktop.browser: chrome.`);
+    }
+    state.launchedBrowserFamily = browserLaunch.family;
+    state.browserLaunchIdentity = browserLaunch.identity;
+    state.browserLaunched = true;
+    noteDevToolsReadiness(ctx, browserLaunch.devTools, emulationFlags.length > 0);
+    await desktop.wait(DESKTOP_SETTLE_MS).catch(() => undefined);
+    // Mobile fidelity (#221) is applied outside startParticipantStream's best-effort catch, so a request
+    // that cannot be applied fails the lane closed.
+    state.fidelity = await applyParticipantMobileFidelity({
+        desktop,
+        spec,
+        deps,
+        targetUrl,
+        browserFamily: state.launchedBrowserFamily,
+        launchIdentity: state.browserLaunchIdentity,
+        targetId: state.browserTargetId,
+        warnings,
+    });
+}
+/**
+ * DevTools answering later than this after launch is recorded as a warning on the lane. Six live
+ * launches answered in 4.8-7.7 s; the reads this wait now guards used to give up at about 11 s.
+ */
+const SLOW_DEVTOOLS_MS = 10_000;
+/**
+ * Records how Chrome's DevTools port answered after launch, as a timed phase in the bundle. A
+ * device-emulated lane fails closed when the port never answered, because emulation is applied
+ * over DevTools. Other lanes continue with a warning: their DevTools reads already degrade to
+ * warnings of their own.
+ */
+function noteDevToolsReadiness(ctx, devTools, emulated) {
+    if (devTools === undefined)
+        return;
+    const { spec, deps, warnings } = ctx;
+    const endpoint = `127.0.0.1:${CHROME_DEVTOOLS_PORT}`;
+    ctx.onSubjectPhase({
+        at: new Date(deps.now()).toISOString(),
+        type: "cua-lab.browser.devtools.completed",
+        ok: devTools.state === "ready",
+        durationMs: devTools.waitedMs,
+        message: devTools.state === "ready"
+            ? `Chrome DevTools answered on ${endpoint}`
+            : `Chrome DevTools did not answer on ${endpoint}`,
+    });
+    if (devTools.state === "ready") {
+        if (devTools.waitedMs > SLOW_DEVTOOLS_MS) {
+            warnings.push(`Chrome DevTools for participant ${spec.planned.id} answered ${devTools.waitedMs} ms after launch; the browser started slowly.`);
+        }
+        return;
+    }
+    const log = devTools.logTail === ""
+        ? "the browser log was empty"
+        : `browser log: ${redactText(deps.scrubKnownValues(devTools.logTail))}`;
+    const reason = devTools.state === "exited"
+        ? `Chrome exited ${devTools.waitedMs} ms after launch, before DevTools answered on ${endpoint} (${log})`
+        : `Chrome DevTools did not answer on ${endpoint} within ${devTools.waitedMs} ms of launch while the browser process was still running (${log})`;
+    if (emulated)
+        throw new Error(`mobile emulation could not be applied: ${reason}`);
+    warnings.push(`${reason}. Browser geometry and URL/text observation for participant ${spec.planned.id} read DevTools and may be unavailable.`);
+}
+/**
+ * Measure the browser window and start the live stream. A stream that cannot start is a warning;
+ * unusable browser geometry fails the lane before any participant action.
+ */
+export async function startParticipantStream(ctx, state, desktop) {
+    const { spec, deps, warnings } = ctx;
+    try {
+        // No browser means no browser geometry, and none is invented: the CSS-viewport facts a
+        // browser reports have no counterpart in a terminal window, and an empty record shaped like
+        // a measurement would read as one. The screen geometry is still verified.
+        if (!ctx.desktopCliRoute) {
+            const browserGeometry = await captureDesktopBrowserGeometry({
+                desktop,
+                browserFamily: state.launchedBrowserFamily,
+                ...(state.browserLaunchIdentity === undefined
+                    ? {}
+                    : { launchIdentity: state.browserLaunchIdentity }),
+                participantId: spec.planned.id,
+                targetUrl: ctx.targetUrl,
+                requestedScreen: spec.planned.device.resolution,
+                requestTimeoutMs: deps.requestTimeoutMs,
+            });
+            state.initialBrowserGeometry = browserGeometry;
+            state.browserWindowId = browserGeometry.browserWindowId;
+            state.browserTargetId = browserGeometry.browserTargetId;
+        }
+        // A browser lane streams its browser window when one was found. A CLI lane has no window id
+        // and streams the whole desktop: a person studying a terminal app opens other windows, and
+        // a stream bound to the first one would quietly stop being evidence.
+        await startDesktopStream(desktop, state.browserWindowId);
+        const candidateStreamUrl = desktop.stream.getUrl({
+            authKey: desktop.stream.getAuthKey(),
+            autoConnect: true,
+            viewOnly: true,
+            resize: "scale",
+        });
+        if (typeof candidateStreamUrl === "string" && candidateStreamUrl.trim().length > 0) {
+            state.streamUrl = candidateStreamUrl;
+            await deps.hooks.onRuntimeStreamReady?.({
+                laneId: spec.planned.id,
+                sandboxId: desktop.sandboxId,
+                simId: spec.recordId,
+                streamId: spec.streamId,
+                url: candidateStreamUrl,
+            });
+        }
+        else {
+            warnings.push("Live desktop stream started but did not return a usable watch URL; Observer will fall back to screenshots.");
+        }
+    }
+    catch (error) {
+        warnings.push(`Live desktop stream unavailable (run continues; evidence still captured): ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
+    }
+    // This is outside the stream's best-effort catch: unusable geometry is a harness failure,
+    // never a participant finding about missing controls. Both per-lane and shared-world seats
+    // use this route.
+    if (state.initialBrowserGeometry?.unusable !== undefined) {
+        state.failureCode = "HUMANISH_CUA_LAB_DEVICE_GEOMETRY";
+        throw new Error(`${state.failureCode}: ${state.initialBrowserGeometry.unusable} Participant actions were not started.`);
+    }
+}

package/dist/routes/computer-use/e2b-desktop/state.d.ts

@@ -0,0 +1,65 @@
+import type { RunDesktopRecording } from "../../../evidence/desktop-recording-types.js";
+import type { RunSubjectStateStepRecord } from "../../../run/bundle.js";
+import type { RunDesktopGeometry } from "../../../run/streams.js";
+import type { SubjectPhaseEvent } from "../../../subject/steps.js";
+import type { OwnedDesktopAllocation } from "../../../substrates/desktop-session.js";
+import type { DesktopBrowserEvidence, DesktopBrowserFamily, DesktopBrowserLaunchIdentity } from "../../../substrates/e2b/desktop-browser.js";
+import { type captureDesktopBrowserGeometry } from "../../../substrates/e2b/desktop-geometry.js";
+import type { startE2BDesktopMedia } from "../../../substrates/e2b/desktop-media.js";
+import type { startE2BDesktopRecording } from "../../../substrates/e2b/desktop-recording.js";
+import type { DesktopResourceObservation } from "../../../substrates/e2b/desktop-resources.js";
+import type { E2BDesktopSandbox } from "../../../substrates/e2b/sdk.js";
+import type { ParticipantDesktopEvidence } from "../participant-desktop.js";
+import type { ParticipantComms, RunningCommsCatch } from "./comms.js";
+import type { ParticipantFidelity } from "./fidelity.js";
+import type { CuaActorLabErrorCode, CuaParticipantDeps, DesktopParticipantRun } from "../types.js";
+/** What every step of one lane reads: its spec, the run's dependencies and where it points. */
+export interface E2BParticipantContext {
+    readonly spec: DesktopParticipantRun;
+    readonly deps: CuaParticipantDeps;
+    readonly warnings: string[];
+    readonly targetUrl: string;
+    readonly desktopCliRoute: boolean;
+    readonly comms: ParticipantComms | undefined;
+    /** Records a completed phase and passes every phase to the operator's sink. */
+    readonly onSubjectPhase: (event: SubjectPhaseEvent) => void;
+}
+export interface E2BParticipantState {
+    desktop: E2BDesktopSandbox | undefined;
+    allocation: OwnedDesktopAllocation | undefined;
+    sandboxId: string | undefined;
+    /**
+     * Host-side ends of the desktop's billed span, from the injected clock: right after the sandbox
+     * exists, and after teardown on both the released and kept paths. Allocation before the handle
+     * is outside the span; a kept or unconfirmed sandbox gets an extra unknown lifetime cost line.
+     */
+    sandboxCreatedAtMs: number | undefined;
+    sandboxTornDownAtMs: number | undefined;
+    desktopResources: DesktopResourceObservation | undefined;
+    released: boolean;
+    failureCode: CuaActorLabErrorCode | undefined;
+    commsCatch: RunningCommsCatch | undefined;
+    commsArtifactPath: string | undefined;
+    receivingInboxUrl: string | undefined;
+    readonly stateStepRecords: RunSubjectStateStepRecord[];
+    /** Completed phases only (durationMs and ok are set on completed events); bundle.events keeps these. */
+    readonly phaseRecords: SubjectPhaseEvent[];
+    subjectCommit: string | undefined;
+    speech: Awaited<ReturnType<typeof startE2BDesktopMedia>> | undefined;
+    recording: Awaited<ReturnType<typeof startE2BDesktopRecording>> | undefined;
+    recordingEvidence: RunDesktopRecording | undefined;
+    readonly mediaStop: AbortController;
+    desktopBrowser: DesktopBrowserEvidence | undefined;
+    launchedBrowserFamily: DesktopBrowserFamily;
+    browserLaunchIdentity: DesktopBrowserLaunchIdentity | undefined;
+    browserLaunched: boolean;
+    fidelity: ParticipantFidelity;
+    initialBrowserGeometry: Awaited<ReturnType<typeof captureDesktopBrowserGeometry>> | undefined;
+    browserWindowId: string | undefined;
+    browserTargetId: string | undefined;
+    desktopGeometry: RunDesktopGeometry;
+    streamUrl: string | undefined;
+}
+export declare function newParticipantState(spec: DesktopParticipantRun): E2BParticipantState;
+/** The lane's outcome evidence, read from its state. */
+export declare function desktopEvidenceOf(state: E2BParticipantState): ParticipantDesktopEvidence;

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

@@ -0,0 +1,69 @@
+// What one E2B desktop lane records as it runs. The prepare, start and teardown steps fill one
+// record in order, and desktopEvidenceOf reads it for the lane's outcome.
+import { declaredScreenForRender, } from "../../../substrates/e2b/desktop-geometry.js";
+export function newParticipantState(spec) {
+    const declaredScreen = declaredScreenForRender(spec.planned.device.preset, spec.planned.device.name, spec.planned.device.resolution);
+    return {
+        desktop: undefined,
+        allocation: undefined,
+        sandboxId: undefined,
+        sandboxCreatedAtMs: undefined,
+        sandboxTornDownAtMs: undefined,
+        desktopResources: undefined,
+        released: false,
+        failureCode: undefined,
+        commsCatch: undefined,
+        commsArtifactPath: undefined,
+        receivingInboxUrl: undefined,
+        stateStepRecords: [],
+        phaseRecords: [],
+        subjectCommit: undefined,
+        speech: undefined,
+        recording: undefined,
+        recordingEvidence: undefined,
+        mediaStop: new AbortController(),
+        desktopBrowser: undefined,
+        launchedBrowserFamily: "unknown",
+        browserLaunchIdentity: undefined,
+        browserLaunched: false,
+        fidelity: { applied: undefined, emulatedTargetId: undefined, holderName: undefined },
+        initialBrowserGeometry: undefined,
+        browserWindowId: undefined,
+        browserTargetId: undefined,
+        desktopGeometry: {
+            screen: {
+                requested: {
+                    width: spec.planned.device.resolution[0],
+                    height: spec.planned.device.resolution[1],
+                },
+                ...(declaredScreen ? { declared: declaredScreen } : {}),
+            },
+        },
+        streamUrl: undefined,
+    };
+}
+/** The lane's outcome evidence, read from its state. */
+export function desktopEvidenceOf(state) {
+    // Host-side approximation of the E2B desktop's billed lifetime; feeds the desktop-minute cost
+    // estimate. Never negative.
+    const desktopDurationMs = state.sandboxCreatedAtMs !== undefined && state.sandboxTornDownAtMs !== undefined
+        ? Math.max(0, state.sandboxTornDownAtMs - state.sandboxCreatedAtMs)
+        : undefined;
+    return {
+        ...(state.sandboxId === undefined ? {} : { sandboxId: state.sandboxId }),
+        ...(desktopDurationMs === undefined ? {} : { desktopDurationMs }),
+        ...(state.desktopResources === undefined ? {} : { desktopResources: state.desktopResources }),
+        released: state.released,
+        streamUrlPresent: state.streamUrl !== undefined,
+        ...(state.subjectCommit === undefined ? {} : { subjectCommit: state.subjectCommit }),
+        ...(state.desktopBrowser === undefined ? {} : { desktopBrowser: state.desktopBrowser }),
+        ...(state.recordingEvidence === undefined ? {} : { recording: state.recordingEvidence }),
+        desktopGeometry: state.desktopGeometry,
+        stateStepRecords: state.stateStepRecords,
+        phaseRecords: state.phaseRecords,
+        ...(state.failureCode === undefined ? {} : { failureCode: state.failureCode }),
+        ...(state.commsArtifactPath === undefined
+            ? {}
+            : { commsArtifactPath: state.commsArtifactPath }),
+    };
+}

package/dist/routes/computer-use/e2b-desktop/teardown.d.ts

@@ -0,0 +1,6 @@
+import type { E2BParticipantContext, E2BParticipantState } from "./state.js";
+/**
+ * Finish a lane: collect its final geometry and comms evidence, then stop its media and release
+ * its sandbox. Evidence failures are warnings; the release always runs.
+ */
+export declare function finishE2BDesktop(ctx: E2BParticipantContext, state: E2BParticipantState, failed: boolean): Promise<void>;