humanish 0.136.1 → 0.138.0

package/dist/study/plan-base.js

@@ -20,7 +20,9 @@ function residualOf(config) {
         ...(policies === undefined ? {} : { policies }),
         ...(defaults === undefined ? {} : { defaults }),
         ...(review === undefined ? {} : { review }),
-        ...(config.execution?.desktop === undefined && config.execution?.target === undefined
+        ...(config.execution?.desktop === undefined &&
+            config.execution?.target === undefined &&
+            config.execution?.network === undefined
             ? {}
             : {
                 execution: {
@@ -30,6 +32,9 @@ function residualOf(config) {
                     ...(config.execution?.target === undefined
                         ? {}
                         : { target: config.execution.target }),
+                    ...(config.execution?.network === undefined
+                        ? {}
+                        : { network: config.execution.network }),
                 },
             }),
         subject: {

package/dist/study/plan-types.d.ts

@@ -4,6 +4,7 @@ import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import type { BrowserSurface } from "../actors/scripted-browser/types.js";
 import type { ScriptedRefusal } from "../routes/scripted/plan.js";
 import type { TerminalRefusal } from "../routes/terminal/plan.js";
+import type { SandboxProviderId } from "../run/sandbox-receipts.js";
 import type { RunStudyProvenance } from "../run/study-provenance.js";
 import type { ArrivalPlan } from "./arrivals.js";
 import type { BundleEstimate } from "./bundle-estimate.js";
@@ -19,7 +20,7 @@ type AtLeastTwo<T> = readonly [T, T, ...T[]];
  */
 export type Requirement = {
     readonly kind: "key";
-    readonly name: "OPENAI_API_KEY" | "E2B_API_KEY";
+    readonly name: "OPENAI_API_KEY" | "E2B_API_KEY" | "MODAL_TOKEN_ID" | "MODAL_TOKEN_SECRET";
 }
 /** The terminal runtime key: CODEX_API_KEY, else OPENAI_API_KEY. */
  | {
@@ -51,7 +52,7 @@ export type Requirement = {
  * fields at run time.
  */
 export type ResidualConfig = Pick<StudyConfig, "comms" | "policies" | "defaults" | "review"> & {
-    readonly execution?: Pick<NonNullable<StudyConfig["execution"]>, "desktop" | "target">;
+    readonly execution?: Pick<NonNullable<StudyConfig["execution"]>, "desktop" | "target" | "network">;
     readonly subject: Pick<StudyConfig["subject"], "clone" | "localTree" | "repos" | "envValues">;
 };
 export interface PlannedAnalysis {
@@ -223,6 +224,8 @@ export interface SharedWorldPlan extends PlanBase {
 }
 export type TerminalPlan = PlanBase & {
     readonly route: "terminal";
+    /** Where the shell sandbox runs: `execution.target` modal-terminal, else E2B. */
+    readonly sandboxProvider: SandboxProviderId;
     /** The registered terminal actor that runs. */
     readonly actor: string;
     readonly product: StudySubjectProduct & {

package/dist/study/requirements.js

@@ -9,9 +9,14 @@ import { localAgentRefusal } from "../actors/local-agent/readiness.js";
 import { describeMissingKeys } from "../keys/key-resolution.js";
 import { MODEL_RATES, unpricedCapMessage } from "../run/pricing.js";
 /** Provider keys in the order the routes name them in a refusal. */
-const KEY_ORDER = ["OPENAI_API_KEY", "E2B_API_KEY"];
+const KEY_ORDER = [
+    "OPENAI_API_KEY",
+    "E2B_API_KEY",
+    "MODAL_TOKEN_ID",
+    "MODAL_TOKEN_SECRET",
+];
 const present = (env, name) => (env[name]?.trim() ?? "") !== "";
-/** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
+/** The `key` requirements whose value `env` lacks, in KEY_ORDER. */
 function missingKeys(requirements, env) {
     const required = new Set(requirements.flatMap((requirement) => (requirement.kind === "key" ? [requirement.name] : [])));
     return KEY_ORDER.filter((name) => required.has(name) && !present(env, name));

package/dist/study/routing.d.ts

@@ -69,7 +69,7 @@ export declare function isScriptedBrowserComposition(config: StudyConfig): boole
 export declare function isProvisionedScriptedBrowserComposition(config: StudyConfig): boolean;
 /**
  * True when this config routes to the terminal-product backend: a terminal-product subject whose
- * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent;
+ * first actor resolves to a registered terminal actor (execution.target e2b-terminal, modal-terminal or absent;
  * the parse layer enforces that pairing). Mirror of isComputerUseComposition/isScriptedBrowserComposition;
  * the single source of truth for routeOf and the warning logic.
  */

package/dist/study/routing.js

@@ -177,7 +177,7 @@ export function isProvisionedScriptedBrowserComposition(config) {
 }
 /**
  * True when this config routes to the terminal-product backend: a terminal-product subject whose
- * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent;
+ * first actor resolves to a registered terminal actor (execution.target e2b-terminal, modal-terminal or absent;
  * the parse layer enforces that pairing). Mirror of isComputerUseComposition/isScriptedBrowserComposition;
  * the single source of truth for routeOf and the warning logic.
  */

package/dist/study/study-fields.d.ts

@@ -1,7 +1,13 @@
-import type { StudyConfig, StudyParticipantEntry } from "./types.js";
+import type { StudyConfig, StudyNetworkCapture, StudyParticipantEntry } from "./types.js";
 /** The participants listed one by one: a `participants` list. Undefined when none is listed. */
 export declare function participantList(config: StudyConfig): readonly StudyParticipantEntry[] | undefined;
 /** The declared number of identical participants: `participants: <n>` or `participants.count`. */
 export declare function declaredParticipantCount(config: StudyConfig): number | undefined;
 /** The steer each of a counted group of participants gets: `participants.instruction`. */
 export declare function participantInstruction(config: StudyConfig): string | undefined;
+/**
+ * The origins each participant's network log keeps beside its target's
+ * (`execution.network.origins`), or undefined when capture is off: `execution.network` absent or
+ * false.
+ */
+export declare function networkCaptureOrigins(network: StudyNetworkCapture | undefined): readonly string[] | undefined;

package/dist/study/study-fields.js

@@ -17,6 +17,16 @@ export function declaredParticipantCount(config) {
 export function participantInstruction(config) {
     return isGroup(config.participants) ? config.participants.instruction : undefined;
 }
+/**
+ * The origins each participant's network log keeps beside its target's
+ * (`execution.network.origins`), or undefined when capture is off: `execution.network` absent or
+ * false.
+ */
+export function networkCaptureOrigins(network) {
+    if (network === undefined || network === false)
+        return undefined;
+    return network === true ? [] : (network.origins ?? []);
+}
 function isGroup(participants) {
     return typeof participants === "object" && participants !== null && !Array.isArray(participants);
 }

package/dist/study/types.d.ts

@@ -467,7 +467,7 @@ export interface StudyActor {
      */
     dwell?: DwellWindow;
 }
-type StudyExecutionTarget = "local" | "e2b-desktop" | "e2b-terminal";
+type StudyExecutionTarget = "local" | "e2b-desktop" | "e2b-terminal" | "modal-terminal";
 /** Terminal transport: the captured non-interactive exec stream (stdin disabled). It is not an
  *  interactive duplex PTY; labeling captured exec output "pty" would be a claim/mechanism
  *  mismatch, so this route uses "exec-stream". */
@@ -570,6 +570,15 @@ export interface StudyDesktopFidelity {
     /** Full user-agent string to present; default: a mobile Safari string. */
     userAgent?: string;
 }
+/**
+ * `execution.network`: record each browser participant's requests to `network/<id>.ndjson`.
+ * `true` keeps the requests to the participant's target origin; `origins` adds up to 16 more exact
+ * http(s) origins. Only computer-use participants in hosted Chrome or Chromium on
+ * `execution.target: e2b-desktop` read it; every other route refuses it.
+ */
+export type StudyNetworkCapture = boolean | {
+    origins?: string[];
+};
 export interface StudyExecution {
     target?: StudyExecutionTarget;
     /** Actor session wall-clock budget. Consumed on the app-url route. */
@@ -582,6 +591,8 @@ export interface StudyExecution {
      */
     concurrency?: number;
     desktop?: StudyExecutionDesktop;
+    /** Each browser participant's network log; see StudyNetworkCapture. Absent or false: off. */
+    network?: StudyNetworkCapture;
     /** `terminal-product` route: the terminal transport + stdin posture. Consumed on that route. */
     terminal?: StudyExecutionTerminal;
     /** `terminal-product` route: runtime key placement, defaulting to openai-egress, an external

package/dist/study/validation.d.ts

@@ -1,3 +1,4 @@
+import { type StudyRoute } from "./routing.js";
 import type { StudyConfig } from "./types.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
@@ -21,6 +22,13 @@ export declare function smtpValidationReason(config: StudyConfig): string | unde
  * topology may not identify the backend that is actually executing.
  */
 export declare function desktopMediaValidationReason(config: StudyConfig, supportsMedia?: boolean): string | undefined;
+/**
+ * Why a study's `execution.network` cannot run where it is going, or undefined. Only a
+ * computer-use participant in hosted Chrome or Chromium has the in-sandbox DevTools client that
+ * records requests. Enforced at parse and again by each route's planner, which passes its own
+ * route, for a library caller's config.
+ */
+export declare function networkCaptureValidationReason(config: StudyConfig, route?: StudyRoute): string | undefined;
 /** Reused by direct library runners so unsupported receiving never becomes inert configuration. */
 export declare function receivingEmailValidationReason(config: StudyConfig): string | undefined;
 /** Refuse task declarations that the selected execution path would discard.

package/dist/study/validation.js

@@ -4,8 +4,8 @@ import { waitFieldsReason } from "../actors/computer-use/wait.js";
 import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./parse/actors.js";
 import { isHttpUrl, isLoopbackUrl } from "./parse/subject.js";
 import { declaredTargets } from "./plan-participants.js";
-import { actorResolvesToComputerUse, computerUseParticipantCount, participantCountReason, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
-import { participantList } from "./study-fields.js";
+import { actorResolvesToComputerUse, computerUseParticipantCount, participantCountReason, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, routeOf, } from "./routing.js";
+import { networkCaptureOrigins, participantList } from "./study-fields.js";
 import { isStartAfterMs, rosterStartsReason, startAfterMessage, windowReason } from "./arrivals.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
@@ -206,6 +206,35 @@ export function desktopMediaValidationReason(config, supportsMedia = isComputerU
     }
     return undefined;
 }
+/**
+ * Why a study's `execution.network` cannot run where it is going, or undefined. Only a
+ * computer-use participant in hosted Chrome or Chromium has the in-sandbox DevTools client that
+ * records requests. Enforced at parse and again by each route's planner, which passes its own
+ * route, for a library caller's config.
+ */
+export function networkCaptureValidationReason(config, route = routeOf(config)) {
+    if (networkCaptureOrigins(config.execution?.network) === undefined)
+        return undefined;
+    const hosted = "only computer-use participants in hosted Chrome or Chromium on `execution.target: e2b-desktop` record their requests";
+    if (route === "terminal")
+        return "`execution.network` records each browser participant's requests, and route: terminal launches no browser: its participant works in a shell. Remove `execution.network`.";
+    if (route === "shared-world")
+        return "`execution.network` is not supported on route: shared-world yet: a shared world's lobby code sits in a page address the network log would keep, and that route keeps observed addresses only as digests. Remove `execution.network`, or run independent participants on route: computer-use.";
+    if (route === "scripted")
+        return `\`execution.network\` is not supported on route: scripted yet: ${hosted}. Remove \`execution.network\`.`;
+    if (route !== "computer-use")
+        return `\`execution.network\` is not read on route: ${route}: ${hosted}. Remove \`execution.network\`.`;
+    if (config.subject.source === "desktop-cli")
+        return "`execution.network` records each browser participant's requests, and a desktop-cli subject opens a terminal window and no browser, so there are none to record. Remove `execution.network`.";
+    if (config.subject.source === "local-app")
+        return `\`execution.network\` is not supported for a local-app subject: humanish does not launch that participant's browser, and ${hosted}. Remove \`execution.network\`.`;
+    const target = config.execution?.target;
+    if (target !== "e2b-desktop")
+        return `\`execution.network\` is not supported with \`execution.target: ${target ?? "(absent)"}\` yet: ${hosted}. Set \`execution.target: e2b-desktop\`, or remove \`execution.network\`.`;
+    if (config.execution?.desktop?.browser === "firefox")
+        return "`execution.network` needs Chrome or Chromium, and `execution.desktop.browser: firefox` launches Firefox with no DevTools port to record requests through. Set `execution.desktop.browser` to chrome, chromium or default, or remove `execution.network`.";
+    return undefined;
+}
 /** Reused by direct library runners so unsupported receiving never becomes inert configuration. */
 export function receivingEmailValidationReason(config) {
     if (config.comms?.email?.kind !== "real")

package/dist/substrates/detached.d.ts

@@ -27,6 +27,11 @@ export interface DetachedStepResult {
 }
 /** Read the capped log tail for a step (raw; caller redacts). */
 export declare function readDetachedLog(shell: Shell, name: string, requestTimeoutMs?: number): Promise<string>;
+/**
+ * Whether a process started by startDetachedProcess or runDetachedStep has exited. Its wrapper
+ * writes a status file however the command ended, a signal included.
+ */
+export declare function detachedProcessExited(shell: Shell, name: string, requestTimeoutMs?: number): Promise<boolean>;
 /**
  * Run a bounded step (install/build) detached, polling its atomic status file until it
  * exits or the budget runs out. On timeout the process group is killed and the log tail is

package/dist/substrates/detached.js

@@ -75,6 +75,15 @@ export async function readDetachedLog(shell, name, requestTimeoutMs = DEFAULT_RE
     const result = await runOrThrow(shell, `tail -c ${LOG_TAIL_BYTES} ${shellQuote(`${stepDir(name)}/log.txt`)} 2>/dev/null || true`, { requestTimeoutMs });
     return result.stdout;
 }
+/**
+ * Whether a process started by startDetachedProcess or runDetachedStep has exited. Its wrapper
+ * writes a status file however the command ended, a signal included.
+ */
+export async function detachedProcessExited(shell, name, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+    assertName(name);
+    const result = await runOrThrow(shell, `test -e ${shellQuote(`${stepDir(name)}/status`)} && echo exited || true`, { requestTimeoutMs });
+    return result.stdout.trim() === "exited";
+}
 /**
  * Run a bounded step (install/build) detached, polling its atomic status file until it
  * exits or the budget runs out. On timeout the process group is killed and the log tail is

package/dist/substrates/e2b/cdp-network-capture.d.ts

@@ -0,0 +1,23 @@
+/** The `network` field of a hold request. */
+export interface ChromeNetworkCaptureRequest {
+    /**
+     * Sandbox file the holder appends to; its folder is created. Defaults to
+     * /tmp/humanish-network/events.ndjson.
+     */
+    eventsPath?: string;
+    /** Origins, as `new URL(url).origin` writes them, whose request addresses the holder writes. */
+    origins: string[];
+}
+/**
+ * The capture half of the holder, spliced into CHROME_CDP_PROBE_PY so the shipped script stays one
+ * string. Line kinds: `start` (Network answered on the launch page), `request`, `response`,
+ * `servedFromCache`, `finished`, `failed`, `backForward` (a main-frame restore from the
+ * back-forward cache, which sends no request), `cap` (the file reached 32 MiB and writing stopped)
+ * and `exit` (the holder stopped; written in a finally). Ids are `<session>:<requestId>`, the
+ * session numbered in attach order from 0 for the launch page, because request ids repeat across
+ * renderers. `wallTime` is seconds since the epoch on the sandbox clock; `timestamp` is CDP's
+ * monotonic clock, for durations. A path longer than 4,096 characters ends at its last whole
+ * segment within them, then `/[TRUNCATED]`: the host redacts each segment, and a token cut in two
+ * can fall below the length its rules withhold.
+ */
+export declare const NETWORK_CAPTURE_PY: string;

package/dist/substrates/e2b/cdp-network-capture.js

@@ -0,0 +1,194 @@
+// What the in-sandbox holder keeps from a participant's browser traffic. The holder (cdp-probe.ts,
+// `mode: "hold"`) already owns the one long-lived DevTools socket on a hosted desktop; with a
+// network request it also enables the Network domain and appends one short JSON line per kept
+// event to a file the host reads at teardown.
+//
+// The CDP events carry headers, cookies, post data, initiator stacks and full URLs. A line copies
+// none of them: only the request id, the two clocks, method, resource type, status, cache flags,
+// error text, and an address for an allowed origin, cut at the first `?` or `#` with user info
+// removed. A request to any other origin gets a line with no address, method or type, so the host
+// can count it, and nothing more is written for it. A method or resource type that is not plain
+// letters is written as `Other`, and error text outside Chrome's `net::ERR_*` form as
+// `net::ERR_OTHER`, so no free text reaches the file.
+/** The segment a path the holder cut ends with: the marker tracePage ends a cut path with. */
+const PATH_CUT = "[TRUNCATED]";
+/**
+ * The capture half of the holder, spliced into CHROME_CDP_PROBE_PY so the shipped script stays one
+ * string. Line kinds: `start` (Network answered on the launch page), `request`, `response`,
+ * `servedFromCache`, `finished`, `failed`, `backForward` (a main-frame restore from the
+ * back-forward cache, which sends no request), `cap` (the file reached 32 MiB and writing stopped)
+ * and `exit` (the holder stopped; written in a finally). Ids are `<session>:<requestId>`, the
+ * session numbered in attach order from 0 for the launch page, because request ids repeat across
+ * renderers. `wallTime` is seconds since the epoch on the sandbox clock; `timestamp` is CDP's
+ * monotonic clock, for durations. A path longer than 4,096 characters ends at its last whole
+ * segment within them, then `/[TRUNCATED]`: the host redacts each segment, and a token cut in two
+ * can fall below the length its rules withhold.
+ */
+export const NETWORK_CAPTURE_PY = String.raw `
+NETWORK_ENABLE = {"maxTotalBufferSize": 0, "maxResourceBufferSize": 0, "maxPostDataSize": 0}
+NETWORK_EVENTS_CAP = 32 * 1024 * 1024
+# Kept free under the cap so the cap and exit lines always fit.
+NETWORK_TAIL_RESERVE = 512
+NETWORK_PATH_LIMIT = 4096
+WEB_ADDRESS = re.compile(r"^([A-Za-z][A-Za-z0-9+.-]*)://(?:[^/?#]*@)?([^/?#]*)([^?#]*)")
+NETWORK_WORD = re.compile(r"^[A-Za-z]{1,32}$")
+NETWORK_ERROR = re.compile(r"^net::ERR_[A-Z0-9_]{1,64}$")
+
+def allowed_address(url, origins):
+    """origin + path for an allowed origin, without user info, query or fragment; else None."""
+    match = WEB_ADDRESS.match(str(url or ""))
+    if not match:
+        return None
+    origin = ("%s://%s" % (match.group(1), match.group(2))).lower()
+    if origin not in origins:
+        return None
+    path = match.group(3) or "/"
+    if len(path) > NETWORK_PATH_LIMIT:
+        path = path[:path.rfind("/", 0, NETWORK_PATH_LIMIT + 1)] + "/${PATH_CUT}"
+    return origin + path
+
+def network_word(value, fallback):
+    text = str(value or "")
+    return text if NETWORK_WORD.match(text) else fallback
+
+def clock(value):
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) else None
+
+def response_fields(response):
+    fields = {}
+    if not isinstance(response, dict):
+        return fields
+    status = clock(response.get("status"))
+    if status is not None and 100 <= status <= 599:
+        fields["status"] = int(status)
+    for flag in ("fromDiskCache", "fromPrefetchCache", "fromServiceWorker"):
+        if response.get(flag) is True:
+            fields[flag] = True
+    return fields
+
+class NetworkLog:
+    """The events file of one holder. Writes go straight to the file, one line per write, so a
+    read while the holder runs sees whole lines except possibly the last."""
+    def __init__(self, request):
+        self.path = str(request.get("eventsPath") or "/tmp/humanish-network/events.ndjson")
+        self.origins = set(str(origin).rstrip("/").lower() for origin in request.get("origins") or [] if isinstance(origin, str))
+        folder = os.path.dirname(self.path)
+        if folder:
+            os.makedirs(folder, exist_ok=True)
+        self.handle = open(self.path, "ab", buffering=0)
+        self.written = os.fstat(self.handle.fileno()).st_size
+        self.capped = False
+        self.sessions = {}
+        # Ids whose current hop has an allowed address; only those get lines after the request.
+        self.open = set()
+        self.faults = 0
+
+    def session(self, session_id):
+        if session_id not in self.sessions:
+            self.sessions[session_id] = len(self.sessions)
+        return self.sessions[session_id]
+
+    def write(self, line, tail=False):
+        if self.capped and not tail:
+            return
+        data = (json.dumps({key: value for key, value in line.items() if value is not None}, separators=(",", ":")) + "\n").encode("utf-8")
+        room = NETWORK_EVENTS_CAP - (0 if tail else NETWORK_TAIL_RESERVE)
+        if self.written + len(data) > room:
+            if not tail:
+                self.capped = True
+                self.write({"e": "cap", "wallTime": time.time()}, tail=True)
+            return
+        self.handle.write(data)
+        self.written += len(data)
+
+    def event(self, method, params, session):
+        """Record one CDP event. A fault is counted, never raised: emulation must keep running."""
+        try:
+            self.record(method, params, session)
+        except Exception:
+            self.faults += 1
+
+    def record(self, method, params, session):
+        # Past the cap nothing more is written, so nothing more is tracked.
+        if self.capped:
+            return
+        if method == "Page.frameNavigated":
+            frame = params.get("frame") or {}
+            if params.get("type") == "BackForwardCacheRestore" and not frame.get("parentId"):
+                self.write({"e": "backForward", "wallTime": time.time(), "url": allowed_address(frame.get("url"), self.origins)})
+            return
+        if not str(method).startswith("Network."):
+            return
+        kind = method[len("Network."):]
+        request_id = "%d:%s" % (self.session(session), str(params.get("requestId") or "")[:64])
+        timestamp = clock(params.get("timestamp"))
+        if kind == "requestWillBeSent":
+            request = params.get("request") or {}
+            line = {"e": "request", "id": request_id, "wallTime": clock(params.get("wallTime")), "timestamp": timestamp}
+            if "redirectResponse" in params:
+                line["redirectResponse"] = response_fields(params.get("redirectResponse"))
+            address = allowed_address(request.get("url"), self.origins)
+            if address is None:
+                self.open.discard(request_id)
+            else:
+                self.open.add(request_id)
+                line["url"] = address
+                line["method"] = network_word(request.get("method"), "Other")
+                line["type"] = network_word(params.get("type"), "Other")
+            self.write(line)
+        elif request_id not in self.open:
+            return
+        elif kind == "responseReceived":
+            line = {"e": "response", "id": request_id, "timestamp": timestamp}
+            line.update(response_fields(params.get("response")))
+            self.write(line)
+        elif kind == "requestServedFromCache":
+            self.write({"e": "servedFromCache", "id": request_id})
+        elif kind == "loadingFinished":
+            self.open.discard(request_id)
+            self.write({"e": "finished", "id": request_id, "timestamp": timestamp})
+        elif kind == "loadingFailed":
+            self.open.discard(request_id)
+            error = str(params.get("errorText") or "")
+            self.write({"e": "failed", "id": request_id, "timestamp": timestamp, "errorText": error if NETWORK_ERROR.match(error) else "net::ERR_OTHER"})
+
+    def close(self, reason):
+        line = {"e": "exit", "reason": str(reason)[:200]}
+        if self.faults:
+            line["faults"] = self.faults
+        try:
+            self.write(line, tail=True)
+            self.handle.close()
+        except Exception:
+            pass
+
+def start_capture(ws, session_id, network):
+    """Network on the launch session, answered before any Emulation message goes out, so a mobile
+    participant's launch reload is captured. Returns the log, or None, and the announce field."""
+    try:
+        log = NetworkLog(network)
+    except Exception as error:
+        return None, {"unavailable": "the events file could not be opened (%s)" % type(error).__name__}
+    # Read before the call, so a request whose events queued behind the reply started after it.
+    started = time.time()
+    try:
+        reply = ws.call("Network.enable", NETWORK_ENABLE, session_id)
+    except Exception as error:
+        reply = {"error": {"message": type(error).__name__}}
+    if not isinstance(reply, dict) or "error" in reply:
+        detail = str(((reply or {}).get("error") or {}).get("message")) if isinstance(reply, dict) else "no reply"
+        log.close("Network.enable failed: %s" % detail)
+        return None, {"unavailable": "Network.enable failed on the launch page: %s" % detail}
+    try:
+        log.session(session_id)
+        log.write({"e": "start", "wallTime": started})
+    except Exception as error:
+        log.close("the start line could not be written: %s" % type(error).__name__)
+        return None, {"unavailable": "the events file could not be written (%s)" % type(error).__name__}
+    # Page events report back-forward restores; without them only those lines are missing.
+    try:
+        ws.call("Page.enable", {}, session_id)
+    except Exception:
+        pass
+    return log, {"startedAt": started}
+`;

package/dist/substrates/e2b/cdp-probe.d.ts

@@ -1,3 +1,4 @@
+import { type ChromeNetworkCaptureRequest } from "./cdp-network-capture.js";
 /** Which target to attribute when the endpoint lists several pages. */
 export type ChromeCdpPagePreference = "pinned" | "active";
 export interface ChromeCdpProbeArgs {
@@ -23,15 +24,17 @@ export interface ChromeCdpProbeArgs {
     /**
      * "state": url/title/text/scrollY. "geometry": outer window + CSS viewport. "port": resolution
      * only. "emulate": apply mobile emulation to the selected page and exit (the overrides that
-     * are session-scoped, UA / touch / DPR, lapse when the socket closes). "hold": the same over a browser-level
-     * socket, then stay attached until killed (how a participant keeps them for its whole life) and attach
-     * to every page target Chrome opens later, sending it the same overrides and a reload the moment
-     * it exists, never pausing it. "fidelity": read
+     * are session-scoped, UA / touch / DPR, lapse when the socket closes). "hold": stay attached over
+     * a browser-level socket until killed and attach to every page target Chrome opens later, never
+     * pausing it; it applies `emulation` (how a participant keeps the overrides for its whole life,
+     * with a reload on each page) and `network` capture, either or both. "fidelity": read
      * back what the page reports about itself (UA, DPR, viewport, touch), the proof for the bundle.
      */
     mode: "state" | "geometry" | "port" | "emulate" | "hold" | "fidelity";
-    /** For "emulate": what to apply. */
+    /** For "emulate" and "hold": what to apply. */
     emulation?: ChromeMobileEmulationRequest;
+    /** For "hold": capture each held page's requests to a sandbox file. */
+    network?: ChromeNetworkCaptureRequest;
 }
 /** Mobile emulation request: the CDP Emulation domain applied to one page target. */
 export interface ChromeMobileEmulationRequest {
@@ -75,6 +78,18 @@ export interface ChromeCdpProbeResult {
     applied?: string[];
     /** "fidelity": the read-back. */
     fidelity?: ChromeFidelityRead;
+    /** "hold" with `network`: when capture started on the launch page, or why it could not. */
+    network?: {
+        startedAt: number;
+    } | {
+        unavailable: string;
+    };
+    /**
+     * Seconds since the epoch on the sandbox clock when the probe printed, on every answer including
+     * an unavailable one. It is the clock CDP `wallTime` uses, so a turn mark compares with request
+     * times without host clock skew.
+     */
+    now?: number;
 }
 /**
  * The probe itself. Kept as one string so the shipped command is exactly what the tests execute