humanish 0.136.1 → 0.137.0

package/dist/routes/computer-use/bundle.js

@@ -101,6 +101,7 @@ function singleParticipantArgs(base, state) {
                 : "e2b-desktop",
         ...(outcome?.desktopGeometry === undefined ? {} : { desktopGeometry: outcome.desktopGeometry }),
         ...(outcome?.recording === undefined ? {} : { recording: outcome.recording }),
+        ...(outcome?.networkLog === undefined ? {} : { network: outcome.networkLog }),
         ...(outcome?.desktopFiles === undefined ? {} : { desktopFiles: outcome.desktopFiles }),
         ...(spec.planned.limits.timeZone === undefined
             ? {}

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

@@ -1,6 +1,7 @@
 import { createE2BDesktopExecutor } from "../../../substrates/e2b/desktop-executor.js";
 import { participantInbox, planParticipantComms } from "./comms.js";
 import { participantBrowserStateObserver } from "./fidelity.js";
+import { networkHooks, planParticipantNetwork } from "./network.js";
 import { acquireParticipantDesktop, placeParticipantFiles, provisionParticipantSubject, verifyParticipantScreen, } from "./prepare.js";
 import { keepParticipantScreenOn, openParticipantSurface, startParticipantMedia, startParticipantStream, } from "./start.js";
 import { desktopEvidenceOf, newParticipantState } from "./state.js";
@@ -9,6 +10,7 @@ import { participantServeUrl } from "../types.js";
 export function createE2BParticipantDesktop(spec, deps, warnings) {
     const targetUrl = spec.planned.targetUrl ?? deps.appUrl;
     const state = newParticipantState(spec);
+    state.network = planParticipantNetwork(deps, targetUrl);
     const ctx = {
         spec,
         deps,
@@ -60,6 +62,8 @@ export function createE2BParticipantDesktop(spec, deps, warnings) {
             comms: ctx.comms,
             catchReady: state.commsCatch?.deployed.ready === true,
         });
+        // Capture that started pairs each checkpoint with the time of the read before it.
+        const network = networkHooks(state.network);
         const executor = createE2BDesktopExecutor(desktop, state.launchedBrowserFamily === "chromium"
             ? {
                 observeBrowserState: participantBrowserStateObserver({
@@ -71,12 +75,14 @@ export function createE2BParticipantDesktop(spec, deps, warnings) {
                     targetId: state.browserTargetId,
                     fidelity: state.fidelity,
                     warnings,
+                    ...(network === undefined ? {} : { onClock: network.onClock }),
                 }),
             }
             : {});
         return {
             executor: allocation.open(state.speech?.wrap(executor) ?? executor).executor,
             ...(inbox === undefined ? {} : { inbox }),
+            ...(network === undefined ? {} : { onCheckpoint: network.onCheckpoint }),
         };
     }
     return {

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

@@ -1,7 +1,9 @@
 import type { ResidualConfig } from "../../../study/plan-types.js";
 import type { RunDesktopGeometry } from "../../../run/streams.js";
 import type { DesktopBrowserFamily, DesktopBrowserLaunchIdentity } from "../../../substrates/e2b/desktop-browser.js";
-import { makeChromeBrowserStateObserver } from "../../../substrates/e2b/desktop-cdp.js";
+import { makeChromeBrowserStateObserver, type ChromeCdpEndpoint } from "../../../substrates/e2b/desktop-cdp.js";
+import type { ChromeNetworkCaptureRequest } from "../../../substrates/e2b/cdp-network-capture.js";
+import type { ChromeCdpProbeResult } from "../../../substrates/e2b/cdp-probe.js";
 import { captureDesktopBrowserGeometry } from "../../../substrates/e2b/desktop-geometry.js";
 import type { E2BDesktopSandbox } from "../../../substrates/e2b/sdk.js";
 import type { E2BDesktopDeps, DesktopParticipantRun } from "../types.js";
@@ -14,6 +16,8 @@ export interface ParticipantFidelity {
 }
 /** Only participants on a mobile preset are emulated; the flags go on the browser command line. */
 export declare function mobileLaunchFlags(residual: Readonly<ResidualConfig>, spec: DesktopParticipantRun): string[];
+/** The launched browser's DevTools address, as far as the launch recorded it. */
+export declare function cdpEndpoint(identity: DesktopBrowserLaunchIdentity | undefined, targetUrl: string): ChromeCdpEndpoint;
 /**
  * Apply mobile fidelity to the launch page before the geometry capture and the participant's first
  * observation. A request that cannot be applied fails the participant closed with the reason. Only
@@ -31,6 +35,11 @@ export declare function applyParticipantMobileFidelity(args: {
     launchIdentity: DesktopBrowserLaunchIdentity | undefined;
     targetId: string | undefined;
     warnings: string[];
+    /** Request capture for the holder to start beside emulation, and where its status goes. */
+    network?: {
+        request: ChromeNetworkCaptureRequest;
+        onStart: (status: ChromeCdpProbeResult["network"]) => void;
+    };
 }): Promise<ParticipantFidelity>;
 /** The Chrome observer behind URL/text stop conditions and task criteria, watching for emulation drift. */
 export declare function participantBrowserStateObserver(args: {
@@ -42,6 +51,8 @@ export declare function participantBrowserStateObserver(args: {
     targetId: string | undefined;
     fidelity: ParticipantFidelity;
     warnings: string[];
+    /** Receives the sandbox clock of each read; see makeChromeBrowserStateObserver's onClock. */
+    onClock?: (now: number | undefined) => void;
 }): ReturnType<typeof makeChromeBrowserStateObserver>;
 /**
  * The participant's final browser geometry, measured while the sandbox is alive. A final capture that

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

@@ -16,7 +16,7 @@ export function mobileLaunchFlags(residual, spec) {
     ];
 }
 /** The launched browser's DevTools address, as far as the launch recorded it. */
-function cdpEndpoint(identity, targetUrl) {
+export function cdpEndpoint(identity, targetUrl) {
     return {
         ...(identity?.cdpPort === undefined ? {} : { cdpPort: identity.cdpPort }),
         ...(identity?.profileDir === undefined ? {} : { profileDir: identity.profileDir }),
@@ -50,8 +50,12 @@ export async function applyParticipantMobileFidelity(args) {
         deviceScaleFactor: request.deviceScaleFactor ?? spec.planned.device.preset.deviceScaleFactor,
         touch: request.touch ?? true,
         userAgent: request.userAgent ?? DEFAULT_MOBILE_USER_AGENT,
-    }, { targetId: args.targetId });
+    }, {
+        targetId: args.targetId,
+        ...(args.network === undefined ? {} : { network: args.network.request }),
+    });
     args.warnings.push(...applied.warnings);
+    args.network?.onStart(applied.network);
     return {
         applied: applied.fidelity,
         emulatedTargetId: applied.targetId,
@@ -63,6 +67,7 @@ export function participantBrowserStateObserver(args) {
     const { spec, deps, fidelity, warnings } = args;
     return makeChromeBrowserStateObserver(args.desktop, deps.requestTimeoutMs, cdpEndpoint(args.launchIdentity, args.targetUrl), {
         targetId: args.targetId,
+        ...(args.onClock === undefined ? {} : { onClock: args.onClock }),
         // Once per participant: a dark observation channel is a gap in the instrument, and the
         // funnel's "never measured" count needs this line to explain itself.
         onUnavailable: (reason) => {

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

@@ -0,0 +1,52 @@
+import { type BrowserNetworkIndex, type TurnMark } from "../../../evidence/browser-network.js";
+import type { ChromeNetworkCaptureRequest } from "../../../substrates/e2b/cdp-network-capture.js";
+import type { ChromeCdpProbeResult } from "../../../substrates/e2b/cdp-probe.js";
+import type { E2BDesktopSandbox } from "../../../substrates/e2b/sdk.js";
+import type { E2BDesktopDeps } from "../types.js";
+import type { E2BParticipantContext, E2BParticipantState } from "./state.js";
+/** One participant's capture, from the request to the collected log's index. */
+export interface ParticipantNetwork {
+    readonly request: ChromeNetworkCaptureRequest;
+    /** The capture-only holder's process name, when this participant started one. */
+    holderName: string | undefined;
+    /** Capture answered on the launch page, so the events file is worth reading at teardown. */
+    started: boolean;
+    /** The sandbox clock of the latest browser-state read, cleared when a read starts. */
+    latestRead: number | undefined;
+    readonly marks: TurnMark[];
+    /** What the stream records: no capture until the file is collected. */
+    index: BrowserNetworkIndex;
+}
+/**
+ * The participant's capture, or undefined when the study did not set execution.network. The
+ * holder keeps the participant's target origin and `execution.network.origins`.
+ */
+export declare function planParticipantNetwork(deps: E2BDesktopDeps, targetUrl: string): ParticipantNetwork | undefined;
+/**
+ * Start the capture-only holder for a participant without mobile emulation, right after the
+ * browser launched. A browser other than Chrome or Chromium has no DevTools port to record from,
+ * which is one warning.
+ */
+export declare function startParticipantNetwork(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
+/** Read the capture-only holder's announce, after the desktop settled. */
+export declare function readParticipantNetworkStart(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
+/**
+ * Record what a holder said about capture: started, or one warning with why not. A mobile holder
+ * that said nothing about it did not start it.
+ */
+export declare function noteNetworkStart(ctx: E2BParticipantContext, network: ParticipantNetwork, status: ChromeCdpProbeResult["network"]): void;
+/**
+ * The callbacks a participant whose capture started runs with, or undefined when capture did not
+ * start: the browser-state observer reports each read's sandbox clock, and each checkpoint
+ * screenshot is paired with the read before it. A read that failed leaves no mark.
+ */
+export declare function networkHooks(network: ParticipantNetwork | undefined): {
+    onClock: (now: number | undefined) => void;
+    onCheckpoint: (turnNumber: number) => void;
+} | undefined;
+/**
+ * Read the holder's events at teardown, reduce them and write the participant's network log. Runs
+ * before any other teardown evidence and never throws: a file that cannot be read or written is
+ * one warning, and the index says it was not collected.
+ */
+export declare function collectParticipantNetwork(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;

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

@@ -0,0 +1,153 @@
+// One E2B desktop participant's browser network log, when its study sets execution.network. The
+// in-sandbox DevTools holder (src/substrates/e2b/cdp-probe.ts, mode "hold") appends a line per
+// request event of the participant's Chrome to a sandbox file. A participant with mobile emulation
+// hands the capture request to the holder it already starts; any other starts a capture-only holder
+// once the browser's DevTools answer. Each checkpoint screenshot is paired with the sandbox time of
+// the browser-state read before it, and at teardown the file is read and reduced to
+// network/<participant id>.ndjson (src/evidence/browser-network.ts). Capture never changes how the
+// participant runs: each failure is one warning, and the index says why records are missing.
+import { networkIndexWithoutEvents, reduceBrowserNetwork, } from "../../../evidence/browser-network.js";
+import { redactText, toErrorMessage } from "../../../evidence/redaction.js";
+import { traceRedaction } from "../../../evidence/trace-page.js";
+import { writeContainedOutputFile } from "../../../run/contained-output.js";
+import { readRunSandboxIds } from "../../../run/sandbox-ids.js";
+import { networkCaptureOrigins } from "../../../study/study-fields.js";
+import { readNetworkCaptureStart, readNetworkEvents, startNetworkCapture, } from "../../../substrates/e2b/desktop-cdp.js";
+import { e2bShell } from "../../../substrates/e2b/shell.js";
+import { detachedProcessExited } from "../../../substrates/detached.js";
+import { cdpEndpoint } from "./fidelity.js";
+/** The sandbox file the holder appends to. Each participant has its own sandbox. */
+const NETWORK_EVENTS_PATH = "/tmp/humanish-network/events.ndjson";
+/** The trace redaction a participant's pages go through, which its network log shares. */
+function networkRedaction(deps) {
+    return traceRedaction(deps.scrubKnownValues, redactText);
+}
+/**
+ * The participant's capture, or undefined when the study did not set execution.network. The
+ * holder keeps the participant's target origin and `execution.network.origins`.
+ */
+export function planParticipantNetwork(deps, targetUrl) {
+    const extra = networkCaptureOrigins(deps.residual.execution?.network);
+    if (extra === undefined)
+        return undefined;
+    const target = URL.parse(targetUrl)?.origin;
+    const origins = [
+        ...new Set([...(target === undefined || target === "null" ? [] : [target]), ...extra]),
+    ];
+    return {
+        request: { eventsPath: NETWORK_EVENTS_PATH, origins },
+        holderName: undefined,
+        started: false,
+        latestRead: undefined,
+        marks: [],
+        index: networkIndexWithoutEvents({ origins, redact: networkRedaction(deps) }, "no-capture"),
+    };
+}
+function warnNotRecorded(ctx, reason) {
+    ctx.warnings.push(`Participant ${ctx.spec.planned.id}'s network log was not recorded: ${redactText(ctx.deps.scrubKnownValues(reason))}. The participant ran without request capture.`);
+}
+/**
+ * Start the capture-only holder for a participant without mobile emulation, right after the
+ * browser launched. A browser other than Chrome or Chromium has no DevTools port to record from,
+ * which is one warning.
+ */
+export async function startParticipantNetwork(ctx, state, desktop) {
+    const network = state.network;
+    if (network === undefined)
+        return;
+    if (state.launchedBrowserFamily !== "chromium") {
+        warnNotRecorded(ctx, `the launched browser family is ${state.launchedBrowserFamily}, and requests are recorded only from Chrome or Chromium. Set execution.desktop.browser: chrome`);
+        return;
+    }
+    try {
+        network.holderName = await startNetworkCapture(desktop, ctx.deps.requestTimeoutMs, cdpEndpoint(state.browserLaunchIdentity, ctx.targetUrl), network.request);
+    }
+    catch (error) {
+        warnNotRecorded(ctx, `the capture holder could not start (${toErrorMessage(error)})`);
+    }
+}
+/** Read the capture-only holder's announce, after the desktop settled. */
+export async function readParticipantNetworkStart(ctx, state, desktop) {
+    const network = state.network;
+    if (network?.holderName === undefined)
+        return;
+    noteNetworkStart(ctx, network, await readNetworkCaptureStart(desktop, ctx.deps.requestTimeoutMs, network.holderName));
+}
+/**
+ * Record what a holder said about capture: started, or one warning with why not. A mobile holder
+ * that said nothing about it did not start it.
+ */
+export function noteNetworkStart(ctx, network, status) {
+    if (status !== undefined && "startedAt" in status) {
+        network.started = true;
+        return;
+    }
+    warnNotRecorded(ctx, status?.unavailable ?? "the emulation holder did not report capture");
+}
+/**
+ * The callbacks a participant whose capture started runs with, or undefined when capture did not
+ * start: the browser-state observer reports each read's sandbox clock, and each checkpoint
+ * screenshot is paired with the read before it. A read that failed leaves no mark.
+ */
+export function networkHooks(network) {
+    if (network?.started !== true)
+        return undefined;
+    return {
+        onClock: (now) => {
+            network.latestRead = now;
+        },
+        onCheckpoint: (turnNumber) => {
+            if (network.latestRead !== undefined)
+                network.marks.push({ wallTime: network.latestRead, turn: turnNumber });
+        },
+    };
+}
+/**
+ * Read the holder's events at teardown, reduce them and write the participant's network log. Runs
+ * before any other teardown evidence and never throws: a file that cannot be read or written is
+ * one warning, and the index says it was not collected.
+ */
+export async function collectParticipantNetwork(ctx, state, desktop) {
+    const network = state.network;
+    if (network === undefined || !network.started)
+        return;
+    const { spec, deps } = ctx;
+    // Another participant's id the run journaled is swept from every run file at finish, so a log
+    // that named one would no longer match its index. An unreadable journal leaves the own id.
+    const journaled = await readRunSandboxIds(deps.artifactRoot).catch(() => []);
+    const capture = {
+        participantId: spec.planned.id,
+        origins: network.request.origins,
+        marks: network.marks,
+        redact: networkRedaction(deps),
+        sandboxIds: [desktop.sandboxId, ...journaled],
+    };
+    const notCollected = (error) => {
+        ctx.warnings.push(`Participant ${spec.planned.id}'s network log could not be collected: ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}. Its index records it as not collected.`);
+        network.index = networkIndexWithoutEvents(capture, "not-collected");
+    };
+    // Asked before the read, so an exited holder's file is already whole. A failed check leaves the
+    // log as complete as its own lines say.
+    const holderName = network.holderName ?? state.fidelity.holderName;
+    const holderExited = holderName !== undefined &&
+        (await detachedProcessExited(e2bShell(desktop), holderName, deps.requestTimeoutMs).catch(() => false));
+    let events;
+    try {
+        events = await readNetworkEvents(desktop, NETWORK_EVENTS_PATH, deps.requestTimeoutMs);
+    }
+    catch (error) {
+        notCollected(error);
+        return;
+    }
+    const log = await reduceBrowserNetwork({ ...capture, events, holderExited });
+    try {
+        if (log.text !== undefined && log.index.path !== undefined)
+            await writeContainedOutputFile(deps.artifactRoot, log.index.path, log.text, "utf8");
+    }
+    catch (error) {
+        notCollected(error);
+        return;
+    }
+    network.index = log.index;
+    ctx.warnings.push(...log.warnings);
+}

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

@@ -9,6 +9,7 @@ import { prepareDesktopMedia, startE2BDesktopMedia, } from "../../../substrates/
 import { startE2BDesktopRecording } from "../../../substrates/e2b/desktop-recording.js";
 import { turnOffScreenSaver } from "../../../substrates/e2b/desktop-screen.js";
 import { applyParticipantMobileFidelity, mobileLaunchFlags } from "./fidelity.js";
+import { noteNetworkStart, readParticipantNetworkStart, startParticipantNetwork, } from "./network.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;
@@ -87,8 +88,16 @@ export async function openParticipantSurface(ctx, state, desktop) {
     state.launchedBrowserFamily = browserLaunch.family;
     state.browserLaunchIdentity = browserLaunch.identity;
     state.browserLaunched = true;
-    noteDevToolsReadiness(ctx, browserLaunch.devTools, emulationFlags.length > 0);
+    const emulated = emulationFlags.length > 0;
+    noteDevToolsReadiness(ctx, browserLaunch.devTools, emulated);
+    // A mobile-emulated participant's holder captures too; any other gets a capture-only holder,
+    // started here so the settle wait covers its start.
+    if (!emulated)
+        await startParticipantNetwork(ctx, state, desktop);
     await desktop.wait(DESKTOP_SETTLE_MS).catch(() => undefined);
+    if (!emulated)
+        await readParticipantNetworkStart(ctx, state, desktop);
+    const network = state.network;
     // Mobile fidelity is applied outside startParticipantStream's best-effort catch, so a request
     // that cannot be applied fails the participant closed.
     state.fidelity = await applyParticipantMobileFidelity({
@@ -100,6 +109,14 @@ export async function openParticipantSurface(ctx, state, desktop) {
         launchIdentity: state.browserLaunchIdentity,
         targetId: state.browserTargetId,
         warnings,
+        ...(network === undefined || !emulated
+            ? {}
+            : {
+                network: {
+                    request: network.request,
+                    onStart: (status) => noteNetworkStart(ctx, network, status),
+                },
+            }),
     });
 }
 /**

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

@@ -12,6 +12,7 @@ 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 { ParticipantNetwork } from "./network.js";
 import type { CuaActorStudyErrorCode, E2BDesktopDeps, DesktopParticipantRun, SandboxReleaseFact } from "../types.js";
 /** What every step of one participant reads: its spec, the run's dependencies and where it points. */
 export interface E2BParticipantContext {
@@ -62,6 +63,8 @@ export interface E2BParticipantState {
     browserTargetId: string | undefined;
     desktopGeometry: RunDesktopGeometry;
     streamUrl: string | undefined;
+    /** The browser network log, when the study set execution.network. */
+    network: ParticipantNetwork | undefined;
 }
 export declare function newParticipantState(spec: DesktopParticipantRun): E2BParticipantState;
 /** The participant's outcome evidence, read from its state. */

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

@@ -42,6 +42,7 @@ export function newParticipantState(spec) {
             },
         },
         streamUrl: undefined,
+        network: undefined,
     };
 }
 /** The participant's outcome evidence, read from its state. */
@@ -69,5 +70,6 @@ export function desktopEvidenceOf(state) {
         ...(state.commsArtifactPath === undefined
             ? {}
             : { commsArtifactPath: state.commsArtifactPath }),
+        ...(state.network === undefined ? {} : { networkLog: state.network.index }),
     };
 }

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

@@ -1,12 +1,13 @@
-// Teardown for one E2B desktop participant: its final geometry and comms evidence are collected, then the
-// recording and speech worker, then the sandbox is released by id (or kept for debugging), with a
-// warning for every outcome that is not a confirmed release.
+// Teardown for one E2B desktop participant: its network log, final geometry and comms evidence are
+// collected, then the recording and speech worker, then the sandbox is released by id (or kept for
+// debugging), with a warning for every outcome that is not a confirmed release.
 import { collectDesktopRecording } from "../../../evidence/desktop-recording-artifact.js";
 import { redactText, toErrorMessage } from "../../../evidence/redaction.js";
 import { readE2BRelease } from "../../../substrates/e2b/sandbox.js";
 import { e2bShell } from "../../../substrates/e2b/shell.js";
 import { drainCommsEvidence } from "./comms.js";
 import { finalParticipantGeometry } from "./fidelity.js";
+import { collectParticipantNetwork } from "./network.js";
 /**
  * Each route's own keep flag gates its own participants only: a clone.keep can never leak into a
  * local-tree participant's teardown decision, and vice versa.
@@ -81,6 +82,8 @@ export async function finishE2BDesktop(ctx, state, failed) {
     const { desktop, allocation } = state;
     if (!desktop || !allocation)
         return;
+    // First and on its own: a throw from a later step cannot skip it.
+    await collectParticipantNetwork(ctx, state, desktop);
     try {
         if (state.browserLaunched) {
             state.desktopGeometry = await finalParticipantGeometry({

package/dist/routes/computer-use/fanout-records.js

@@ -125,6 +125,7 @@ function fanoutParticipantStream(args, spec, view) {
             ? {}
             : { timeZone: spec.planned.limits.timeZone }),
         ...(outcome?.recording === undefined ? {} : { recording: outcome.recording }),
+        ...(outcome?.networkLog === undefined ? {} : { network: outcome.networkLog }),
         ui: {
             route: publicTargetUrl,
             intent: `Watch participant ${spec.planned.id} (${spec.persona.id}/${spec.planned.device.name}) drive the subject app in its own hosted desktop.`,
@@ -164,6 +165,15 @@ function fanoutParticipantStream(args, spec, view) {
                     },
                 ]
                 : []),
+            ...(outcome?.networkLog?.path === undefined
+                ? []
+                : [
+                    {
+                        label: `participant ${spec.planned.id} network log`,
+                        path: outcome.networkLog.path,
+                        kind: "log",
+                    },
+                ]),
             ...screenshots.map((screenshot, screenshotIndex) => ({
                 label: `participant ${spec.planned.id} screenshot ${String(screenshotIndex + 1).padStart(2, "0")} (${screenshotMode})`,
                 path: screenshot,

package/dist/routes/computer-use/participant-desktop.d.ts

@@ -2,7 +2,10 @@ import type { CuaExecutor } from "../../actors/computer-use/loop.js";
 import type { DesktopParticipantRun, ParticipantRunOutcome } from "./types.js";
 import type { StudyCommsEmail, StudyCommsRecipient } from "../../study/types.js";
 import type { PreparedOutputRoot } from "../../run/contained-output.js";
-/** A prepared desktop supplies only participant input/observation and its inbox location. */
+/**
+ * A prepared desktop supplies participant input and observation, its inbox location, and a
+ * checkpoint callback when it keeps something per turn (the hosted desktop's network log marks).
+ */
 export interface ReadyParticipantDesktop {
     executor: CuaExecutor;
     inbox?: {
@@ -10,6 +13,8 @@ export interface ReadyParticipantDesktop {
         address?: string;
         receiving?: boolean;
     };
+    /** Called with the turn's number after each checkpoint screenshot; see LoopRunOptions. */
+    onCheckpoint?: (turnNumber: number) => void;
 }
 /** Existing bundle fields. Provider-specific facts remain optional and must be measured. */
 export type ParticipantDesktopEvidence = {
@@ -22,7 +27,7 @@ export type ParticipantDesktopEvidence = {
      * who did not pass.
      */
     desktopFailure?: string;
-} & Pick<ParticipantRunOutcome, "sandboxId" | "sandboxRelease" | "desktopDurationMs" | "desktopResources" | "streamUrlPresent" | "subjectCommit" | "desktopBrowser" | "desktopGeometry" | "stateStepRecords" | "phaseRecords" | "failureCode" | "commsArtifactPath" | "recording" | "desktopFiles">;
+} & Pick<ParticipantRunOutcome, "sandboxId" | "sandboxRelease" | "desktopDurationMs" | "desktopResources" | "streamUrlPresent" | "subjectCommit" | "desktopBrowser" | "desktopGeometry" | "stateStepRecords" | "phaseRecords" | "failureCode" | "commsArtifactPath" | "recording" | "desktopFiles" | "networkLog">;
 /**
  * The desktop one participant runs on, owned from preparation through final evidence collection.
  * Call methods sequentially: prepare, openSession, then finalize in a finally block.

package/dist/routes/computer-use/participant-model.js

@@ -89,7 +89,7 @@ export async function startParticipantModel(spec, deps, executor) {
 }
 /** The options the participant's session runs with: prompt, model settings, spend caps and callbacks. */
 export function participantSessionOptions(spec, deps, ready, provider, writeScreenshot) {
-    const { executor, inbox } = ready;
+    const { executor, inbox, onCheckpoint } = ready;
     // The fail-closed spend cap (caps.maxUsd) is wired into the loop as maxUsd + an
     // injected pure per-turn estimator keyed on the resolved model. Preflight already refused a
     // cap on an unpriced model, so the estimate is measurable whenever a cap is in force. The
@@ -159,6 +159,7 @@ export function participantSessionOptions(spec, deps, ready, provider, writeScre
                         : `study budget reached: ${crossed}; the study's participants stop before their next model request`;
                 },
             }),
+        ...(onCheckpoint === undefined ? {} : { onCheckpoint }),
         ...(deps.onObservedUrl === undefined ? {} : { onObservedUrl: deps.onObservedUrl }),
         ...(deps.onMessage === undefined ? {} : { onMessage: deps.onMessage }),
         ...(deps.onScreenshot === undefined ? {} : { onScreenshot: deps.onScreenshot }),

package/dist/routes/computer-use/plan.js

@@ -12,7 +12,7 @@ import { brainOf, callerBrainOf, planCaps, desktopRequirements, planBase, provis
 import { computerUseParticipants, declaredTargets, } from "../../study/plan-participants.js";
 import { planStarts, windowDeadlineRefusal } from "../../study/arrivals.js";
 import { computerUseParticipantCount, participantCountReason } from "../../study/routing.js";
-import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "../../study/validation.js";
+import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, networkCaptureValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "../../study/validation.js";
 import { desktopCliProductReason } from "../../study/composition-rules.js";
 import { isLocalBrowserStudy } from "../../substrates/local/runtime-config.js";
 import { boundedConcurrency, defaultSessionTimeoutMs, resolveParticipantSandboxMs, } from "./participant-runs.js";
@@ -86,6 +86,7 @@ function cuaStudyRejection(config, hasRunSession, driving, subjectRoute, ceiling
 /** A declaration this route cannot honor, for any subject or with the caller's own driver. */
 function unsupportedDeclarationReason(config, hasRunSession, driving, { inProcessRoute }) {
     const reason = desktopMediaValidationReason(config) ||
+        networkCaptureValidationReason(config, "computer-use") ||
         outputTokenLimitValidationReason(config) ||
         waitLimitValidationReason(config);
     if (reason)

package/dist/routes/computer-use/single-bundle.d.ts

@@ -1,3 +1,4 @@
+import type { BrowserNetworkIndex } from "../../evidence/browser-network.js";
 import type { RunDesktopRecording } from "../../evidence/desktop-recording-types.js";
 import type { SubjectPhaseEvent } from "../../subject/steps.js";
 import type { DesktopBrowserEvidence } from "../../substrates/e2b/desktop-browser.js";
@@ -41,6 +42,8 @@ export declare function buildSingleParticipantBundle(args: {
     /** Runtime screen/window/viewport evidence. `viewport` inside this object must be measured. */
     desktopGeometry?: RunDesktopGeometry;
     recording?: RunDesktopRecording;
+    /** The participant's browser network log index, when its study set execution.network. */
+    network?: BrowserNetworkIndex;
     /** participants[].files confirmed on the participant's desktop. */
     desktopFiles?: RunDesktopFile[];
     /** The participant's time zone, which its turns and its hosted browser used. */

package/dist/routes/computer-use/single-bundle.js

@@ -157,6 +157,7 @@ function singleStream(args, view) {
         ...(args.desktopFiles === undefined ? {} : { desktopFiles: args.desktopFiles }),
         ...(args.timeZone === undefined ? {} : { timeZone: args.timeZone }),
         ...(args.recording === undefined ? {} : { recording: args.recording }),
+        ...(args.network === undefined ? {} : { network: args.network }),
         ui: {
             route: publicAppUrl,
             intent: `Watch the computer-use actor drive the subject app ${browserPlace(args)}.`,
@@ -179,6 +180,9 @@ function singleStream(args, view) {
             ...(args.recording
                 ? [{ label: "desktop recording", path: args.recording.path, kind: "recording" }]
                 : []),
+            ...(args.network?.path === undefined
+                ? []
+                : [{ label: "network log", path: args.network.path, kind: "log" }]),
             ...args.screenshots.map((screenshot, index) => ({
                 label: `screenshot ${String(index + 1).padStart(2, "0")} (${screenshotMode})`,
                 path: screenshot,

package/dist/routes/computer-use/types.d.ts

@@ -1,6 +1,7 @@
 import type { Verdict } from "../../run/judge.js";
 import type { HostSuspensionReading } from "../../run/host-suspension.js";
 import type { LocalCapacity } from "../../substrates/local/capacity.js";
+import type { BrowserNetworkIndex } from "../../evidence/browser-network.js";
 import type { RunDesktopRecording } from "../../evidence/desktop-recording-types.js";
 import type { CuaExecutor, CuaLiveMetadata, CuaLoopResult, CuaProvider } from "../../actors/computer-use/loop.js";
 import type { CommsReceivingRun } from "../../comms/receiving.js";
@@ -481,6 +482,12 @@ export interface ParticipantRunOutcome {
      *  (humanish.comms-thread.v1), when a comms study captured mail into its in-sandbox catch. Registered
      *  in the participant's stream artifacts. Absent when no comms study ran or nothing was captured. */
     commsArtifactPath?: string;
+    /**
+     * The participant's browser network log index (humanish.browser-network.v1), when its study set
+     * execution.network: the stream's `network` field. Its `path`, when present, is registered as a
+     * log artifact.
+     */
+    networkLog?: BrowserNetworkIndex;
 }
 /** What buildCuaFanoutBundle projects into a fan-out run bundle. */
 export interface CuaFanoutBundleArgs {

package/dist/routes/scripted/plan.js

@@ -6,7 +6,7 @@ import { normalizeLocalAppUrl } from "../../actors/scripted-browser/steps.js";
 import { browserSurfaces } from "../../actors/scripted-browser/types.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { isNonEmpty, planBase, provisionedSubject } from "../../study/plan-base.js";
-import { cloneTargetValidationReason, desktopMediaValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
+import { cloneTargetValidationReason, desktopMediaValidationReason, networkCaptureValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 import { sandboxDeadlineRefusal } from "../../substrates/e2b/lifetime.js";
 // Default surface roster is 1 (desktop only): the defaults-table single-participant row governs;
 // `count: 2` is the declared override that adds the mobile surface.
@@ -40,7 +40,7 @@ export function planScriptedStudy(config, input) {
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
         return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason, beforeScope);
-    const mediaReason = desktopMediaValidationReason(config);
+    const mediaReason = desktopMediaValidationReason(config) ?? networkCaptureValidationReason(config, "scripted");
     if (mediaReason)
         return refuse("HUMANISH_SCRIPTED_SCENARIO_INVALID", mediaReason);
     const cloneTargetReason = cloneTargetValidationReason(config);

package/dist/routes/shared-world/plan.js

@@ -12,7 +12,7 @@ import { DESKTOP_FILES_ROUTE_REASON } from "../../study/desktop-files.js";
 import { participantList } from "../../study/study-fields.js";
 import { PUBLIC_TARGET_OWNER_PATTERN } from "../../study/parse/subject.js";
 import { REPO_SLUG_PATTERN } from "../../study/parse/values.js";
-import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "../../study/validation.js";
+import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, networkCaptureValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "../../study/validation.js";
 import { unpricedCapCheck } from "../../study/requirements.js";
 import { participantsAtOnce, sandboxDeadlineRefusal, sandboxHeadroomMs, } from "../../substrates/e2b/lifetime.js";
 import { boundedConcurrency } from "../computer-use/participant-runs.js";
@@ -34,7 +34,8 @@ export function planSharedWorldStudy(config, input) {
         refusal: { route: "shared-world", code, message, ...(actor === undefined ? {} : { actor }) },
     });
     const invalid = "HUMANISH_SHARED_WORLD_INVALID";
-    const mediaReason = desktopMediaValidationReason(config, false);
+    const mediaReason = desktopMediaValidationReason(config, false) ??
+        networkCaptureValidationReason(config, "shared-world");
     if (mediaReason)
         return refuse(invalid, mediaReason);
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);

package/dist/routes/terminal/plan.js

@@ -7,7 +7,7 @@ import { isReasoningEffort } from "../../actors/reasoning-effort.js";
 import { actorRegistry, isTerminalActorDescriptor } from "../../actors/registry.js";
 import { isNonEmpty, planBase } from "../../study/plan-base.js";
 import { studyUrlCredentialReason } from "../../study/url-credentials.js";
-import { desktopMediaValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
+import { desktopMediaValidationReason, networkCaptureValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 import { ceilingAdvice } from "../../substrates/e2b/lifetime.js";
 import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { terminalSandboxTimeoutMs } from "./lifetime.js";
@@ -24,7 +24,7 @@ export function planTerminalStudy(config, input) {
     });
     if (String(config.comms?.email?.kind) === "real")
         return refuse("HUMANISH_TERMINAL_SUBJECT_INVALID", "Real email receiving is unsupported on the terminal route. Use a supported hosted computer-use browser study.");
-    const mediaReason = desktopMediaValidationReason(config);
+    const mediaReason = desktopMediaValidationReason(config) ?? networkCaptureValidationReason(config, "terminal");
     if (mediaReason)
         return refuse("HUMANISH_TERMINAL_SUBJECT_INVALID", mediaReason);
     // A library caller's config skips the parser, which refuses these first.