humanish 0.136.0 → 0.137.0

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

package/dist/substrates/e2b/cdp-probe.js

@@ -15,6 +15,7 @@
 // of swallowing an exit code; the TypeScript side turns that into a participant warning that names the
 // consequence ("url/text criteria will read as never measured").
 import { shellQuote } from "../shell.js";
+import { NETWORK_CAPTURE_PY } from "./cdp-network-capture.js";
 /**
  * The probe itself. Kept as one string so the shipped command is exactly what the tests execute
  * (tests/substrates/e2b/cdp-probe.test.ts runs it under the real python3 against a real
@@ -272,17 +273,20 @@ def browser_ws_url(port):
         info = json.loads(response.read().decode("utf-8"))
     return str(info.get("webSocketDebuggerUrl") or "")
 
-def hold(port, page, request):
-    """Emulate the launch page and then every page target Chrome opens later, for as long as this
-    process lives. One browser-level socket with flattened sessions: the launch page is
-    attached by id and reloaded so scripts that read the UA at load see it; a target that appears
-    later is attached the moment it exists, sent the same overrides, and reloaded once after its
-    first real navigation commits (touch emulation reaches a document only when it loads under it).
+${NETWORK_CAPTURE_PY}
+def hold(port, page, request, network):
+    """Hold the launch page and every page target Chrome opens later, for as long as this process
+    lives, over one browser-level socket with flattened sessions. With an emulation request, the
+    launch page is attached by id and reloaded so scripts that read the UA at load see it; a target
+    that appears later is attached the moment it exists, sent the same overrides, and reloaded once
+    after its first real navigation commits (touch emulation reaches a document only when it loads
+    under it). Without one, nothing is emulated and nothing reloads. With a network request, every
+    held page also reports its traffic to the events file (NETWORK_CAPTURE_PY).
     Two things this loop must never do (measured on a real desktop, 2026-09-04): pause new targets
     (waitForDebuggerOnStart) and wait for their replies. A popup a participant taps open shares its
     opener's renderer, answers Emulation commands only once it runs, and a loop blocked on that
-    reply never resumed the tab (it loaded forever) and never reached the next one. Overrides are
-    sent without waiting; replies, errors included, are logged as they arrive.
+    reply never resumed the tab (it loaded forever) and never reached the next one. Commands to a
+    later target are sent without waiting; replies, errors included, are logged as they arrive.
     Prints one JSON line per attached target; the first line is the announce the lane reads."""
     launch_id = str(page.get("id") or "")
     try:
@@ -295,15 +299,36 @@ def hold(port, page, request):
     if not session_id:
         print(json.dumps({"unavailable": "Target.attachToTarget failed for the launch page"}), flush=True)
         return
-    covered = {launch_id}
-    applied, failure = apply_over(ws, request, session_id, reload=True)
-    print(json.dumps({"applied": applied, "held": failure is None, "targetId": launch_id, **({"unavailable": failure} if failure else {})}), flush=True)
-    if failure:
-        return
+    log, capture = start_capture(ws, session_id, network) if network is not None else (None, None)
+    reason = "the holder stopped"
+    try:
+        applied, failure = apply_over(ws, request, session_id, reload=True) if request else ([], None)
+        held = failure is None and (bool(request) or log is not None)
+        announce = {"applied": applied, "held": held, "targetId": launch_id}
+        if capture is not None:
+            announce["network"] = capture
+        if failure:
+            announce["unavailable"] = failure
+        print(json.dumps(announce), flush=True)
+        if not held:
+            reason = failure or "nothing to hold"
+            return
+        reason = follow_targets(ws, launch_id, request, log)
+    except Exception as error:
+        reason = "%s: %s" % (type(error).__name__, error)
+        raise
+    finally:
+        if log is not None:
+            log.close(reason)
+
+def follow_targets(ws, launch_id, request, log):
+    """The holder's loop: attach every later page target, log replies and hand each event to the
+    capture log. Returns why it ended."""
     auto = ws.call("Target.setAutoAttach", {"autoAttach": True, "waitForDebuggerOnStart": False, "flatten": True})
     if not isinstance(auto, dict) or "error" in auto:
-        print(json.dumps({"autoAttach": False, "unavailable": "Target.setAutoAttach failed; later tabs are not emulated"}), flush=True)
+        print(json.dumps({"autoAttach": False, "unavailable": "Target.setAutoAttach failed; the holder does not reach later tabs"}), flush=True)
     ws.sock.settimeout(None)
+    covered = {launch_id}
     pending = {}
     # Sessions of later targets that still owe one reload: touch emulation reaches a document only
     # when it loads under the override (measured: a popup's first document reported
@@ -314,11 +339,12 @@ def hold(port, page, request):
         try:
             message = ws.events.pop(0) if ws.events else ws.recv()
         except Exception as error:
-            print(json.dumps({"holderExit": "%s: %s" % (type(error).__name__, error)}), flush=True)
-            return
+            reason = "%s: %s" % (type(error).__name__, error)
+            print(json.dumps({"holderExit": reason}), flush=True)
+            return reason
         if message is None:
             print(json.dumps({"holderExit": "browser socket closed"}), flush=True)
-            return
+            return "browser socket closed"
         reply_id = message.get("id")
         session = message.get("sessionId")
         if reply_id in pending:
@@ -332,17 +358,19 @@ def hold(port, page, request):
                 if href and not href.startswith("about:"):
                     target_id = reload_owed.pop(session)
                     pending[ws.send("Page.reload", {}, session)] = "Page.reload"
-                    print(json.dumps({"reloaded": target_id, "url": href, "by": "href"}), flush=True)
+                    print(json.dumps({"reloaded": target_id, "by": "href"}), flush=True)
             continue
         method = message.get("method")
         params = message.get("params") or {}
+        if log is not None and method:
+            log.event(method, params, session)
         if method == "Page.frameNavigated" and session in reload_owed:
             frame = params.get("frame") or {}
             url = str(frame.get("url") or "")
             if not frame.get("parentId") and url and not url.startswith("about:"):
                 target_id = reload_owed.pop(session)
                 pending[ws.send("Page.reload", {}, session)] = "Page.reload"
-                print(json.dumps({"reloaded": target_id, "url": url}), flush=True)
+                print(json.dumps({"reloaded": target_id}), flush=True)
             continue
         if method != "Target.attachedToTarget":
             continue
@@ -351,35 +379,50 @@ def hold(port, page, request):
         target_id = str(info.get("targetId") or "")
         if info.get("type") == "page" and target_id and target_id not in covered:
             covered.add(target_id)
-            messages = emulation_messages(request, reload=False)
+            messages = emulation_messages(request, reload=False) if request else []
             for m in messages:
                 pending[ws.send(m["method"], m.get("params"), new_session)] = m["method"]
+            sent = [m["method"] for m in messages]
+            # After the overrides, so a later tab's emulation timing is what it was without capture.
+            if log is not None:
+                log.session(new_session)
+                pending[ws.send("Network.enable", NETWORK_ENABLE, new_session)] = "Network.enable"
+                sent.append("Network.enable")
             pending[ws.send("Page.enable", {}, new_session)] = "Page.enable"
             url = str(info.get("url") or "")
-            if url and not url.startswith("about:"):
+            if not request:
+                print(json.dumps({"attached": target_id, "sent": sent}), flush=True)
+            elif url and not url.startswith("about:"):
                 pending[ws.send("Page.reload", {}, new_session)] = "Page.reload"
-                print(json.dumps({"attached": target_id, "sent": [m["method"] for m in messages] + ["Page.reload"], "url": url}), flush=True)
+                print(json.dumps({"attached": target_id, "sent": sent + ["Page.reload"]}), flush=True)
             else:
                 reload_owed[new_session] = target_id
                 # Two ways to learn the first real navigation committed, whichever answers first:
                 # Page.frameNavigated (if Page.enable landed before the commit) or the page's own
                 # location.href (if it did not).
                 pending[ws.send("Runtime.evaluate", {"expression": "location.href", "returnByValue": True}, new_session)] = "href"
-                print(json.dumps({"attached": target_id, "sent": [m["method"] for m in messages], "reloadAfterNavigation": True}), flush=True)
+                print(json.dumps({"attached": target_id, "sent": sent, "reloadAfterNavigation": True}), flush=True)
         if params.get("waitingForDebugger"):
             ws.send("Runtime.runIfWaitingForDebugger", {}, new_session)
 
+def emit(answer):
+    """Print one answer line stamped with this sandbox's clock. CDP wallTime uses the same clock, so
+    a turn mark taken from it compares with request times without host skew, and the reading needs
+    nothing from the page, so a page too busy to answer still leaves a mark."""
+    answer["now"] = time.time()
+    print(json.dumps(answer))
+
 def main():
     args = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
     mode = args.get("mode") or "state"
     port = resolve_port(args)
     if mode == "port":
-        print(json.dumps({"cdpPort": port}))
+        emit({"cdpPort": port})
         return
     try:
         pages = list_pages(port)
     except Exception as error:
-        print(json.dumps({"unavailable": "CDP endpoint 127.0.0.1:%d/json unreachable (%s)" % (port, type(error).__name__)}))
+        emit({"unavailable": "CDP endpoint 127.0.0.1:%d/json unreachable (%s)" % (port, type(error).__name__)})
         return
     page = select_page(pages, args)
     # A listing with targets but no http page is usually an instant: a reload in flight, a tab
@@ -396,7 +439,7 @@ def main():
             break
         page = select_page(pages, args)
     if page is None:
-        print(json.dumps({"unavailable": "no http page among %d CDP targets on 127.0.0.1:%d" % (len(pages), port)}))
+        emit({"unavailable": "no http page among %d CDP targets on 127.0.0.1:%d" % (len(pages), port)})
         return
     # Chrome omits webSocketDebuggerUrl from /json while another DevTools client is attached to the
     # page, or for a moment after one detaches; the page socket URL is still /devtools/page/<id>.
@@ -406,29 +449,29 @@ def main():
     if mode == "emulate":
         applied, failure = emulate(ws_url, args.get("emulation") or {}) if ws_url else (None, "the page has no socket")
         if failure is not None:
-            print(json.dumps({"unavailable": failure, "applied": applied or []}))
+            emit({"unavailable": failure, "applied": applied or []})
             return
-        print(json.dumps({"applied": applied, "targetId": str(page.get("id") or "")}))
+        emit({"applied": applied, "targetId": str(page.get("id") or "")})
         return
     if mode == "hold":
         # Prints its announce line, then stays attached (and attaches to every later page target)
         # until killed.
-        hold(port, page, args.get("emulation") or {})
+        hold(port, page, args.get("emulation") or None, args.get("network"))
         return
     if mode == "fidelity":
         result = evaluate(ws_url, FIDELITY_EXPRESSION) if ws_url else None
         if not isinstance(result, dict):
-            print(json.dumps({"unavailable": "Runtime.evaluate over the page socket returned nothing"}))
+            emit({"unavailable": "Runtime.evaluate over the page socket returned nothing"})
             return
-        print(json.dumps({"fidelity": result, "targetId": str(page.get("id") or "")}))
+        emit({"fidelity": result, "targetId": str(page.get("id") or "")})
         return
     if mode == "geometry":
         result = evaluate(ws_url, GEOMETRY_EXPRESSION) if ws_url else None
         if not isinstance(result, dict):
-            print(json.dumps({"unavailable": "Runtime.evaluate over the page socket returned nothing"}))
+            emit({"unavailable": "Runtime.evaluate over the page socket returned nothing"})
             return
         result["targetId"] = str(page.get("id") or "")
-        print(json.dumps(result))
+        emit(result)
         return
     url = str(page.get("url") or "")
     title = str(page.get("title") or "")
@@ -440,7 +483,7 @@ def main():
         title = result["title"] if isinstance(result.get("title"), str) else title
         text = result["text"] if isinstance(result.get("text"), str) else ""
         scroll_y = result["scrollY"] if isinstance(result.get("scrollY"), (int, float)) else None
-    print(json.dumps({"url": url, "title": title, "text": text, "scrollY": scroll_y, "targetId": str(page.get("id") or "")}))
+    emit({"url": url, "title": title, "text": text, "scrollY": scroll_y, "targetId": str(page.get("id") or "")})
 
 main()
 `;
@@ -457,6 +500,8 @@ export function chromeCdpProbeCommand(args) {
         payload.prefer = args.prefer;
     if (args.emulation !== undefined)
         payload.emulation = args.emulation;
+    if (args.network !== undefined)
+        payload.network = args.network;
     return `python3 -c ${shellQuote(CHROME_CDP_PROBE_PY)} ${shellQuote(JSON.stringify(payload))}`;
 }
 /**
@@ -481,10 +526,17 @@ export function parseChromeCdpProbeOutput(stdout) {
     const applied = Array.isArray(record.applied)
         ? record.applied.filter((item) => typeof item === "string")
         : undefined;
+    const numberOr = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+    const now = numberOr(record.now);
+    const network = networkOf(record.network);
     if (typeof record.unavailable === "string") {
-        return { unavailable: record.unavailable, ...(applied === undefined ? {} : { applied }) };
+        return {
+            unavailable: record.unavailable,
+            ...(applied === undefined ? {} : { applied }),
+            ...(network === undefined ? {} : { network }),
+            ...(now === undefined ? {} : { now }),
+        };
     }
-    const numberOr = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
     const box = (value, keys) => {
         if (!value || typeof value !== "object")
             return undefined;
@@ -549,5 +601,17 @@ export function parseChromeCdpProbeOutput(stdout) {
             : {}),
         ...(browserWindow === undefined ? {} : { browserWindow }),
         ...(viewport === undefined ? {} : { viewport }),
+        ...(network === undefined ? {} : { network }),
+        ...(now === undefined ? {} : { now }),
     };
 }
+function networkOf(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const source = value;
+    if (typeof source.startedAt === "number" && Number.isFinite(source.startedAt))
+        return { startedAt: source.startedAt };
+    if (typeof source.unavailable === "string")
+        return { unavailable: source.unavailable };
+    return undefined;
+}

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

@@ -1,4 +1,5 @@
-import { type ChromeMobileEmulationRequest } from "./cdp-probe.js";
+import type { ChromeNetworkCaptureRequest } from "./cdp-network-capture.js";
+import { type ChromeCdpProbeResult, type ChromeMobileEmulationRequest } from "./cdp-probe.js";
 import type { RunDesktopGeometry } from "../../run/streams.js";
 import type { E2BDesktopSandbox } from "./sdk.js";
 /**
@@ -53,6 +54,12 @@ export declare function makeChromeBrowserStateObserver(desktop: E2BDesktopSandbo
     /** Called once, with the reason, on the first probe that could not read the page. */
     onUnavailable?: (reason: string) => void;
     drift?: ChromeEmulationDrift | undefined;
+    /**
+     * Called with undefined when a probe starts, then with the sandbox clock the probe printed
+     * (ChromeCdpProbeResult.now), so the caller holds the time of the latest read and never a
+     * stale one from a probe that failed.
+     */
+    onClock?: (now: number | undefined) => void;
 }): () => Promise<{
     url?: string;
     title?: string;
@@ -65,13 +72,36 @@ export declare const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhon
  * Apply mobile emulation to the participant's launch page and read back what the page reports.
  * Fails closed: a request that cannot be applied throws, because a desktop run labelled mobile is
  * the over-trust this feature exists to prevent. A read-back that cannot be taken is a warning
- * (the emulation was applied; only the proof is missing).
+ * (the emulation was applied; only the proof is missing). With `network`, the same holder also
+ * captures requests, and a capture that could not start is reported in `network` without failing
+ * the emulation.
  */
 export declare function applyMobileEmulation(desktop: E2BDesktopSandbox, requestTimeoutMs: number, endpoint: ChromeCdpEndpoint, request: ChromeMobileEmulationRequest, options?: {
     targetId?: string | undefined;
+    network?: ChromeNetworkCaptureRequest | undefined;
 }): Promise<{
     fidelity: NonNullable<RunDesktopGeometry["fidelity"]>;
     warnings: string[];
     targetId?: string;
     holderName: string;
+    /** The holder's capture status, when `network` was passed and the holder said. */
+    network?: ChromeCdpProbeResult["network"];
 }>;
+/**
+ * Start a holder that records the launch page's requests, and every later tab's, to
+ * `network.eventsPath`, for a participant without mobile emulation; applyMobileEmulation passes
+ * the request to the holder it starts. Sends no Emulation command and no reload. Returns the
+ * holder's process name, which readNetworkCaptureStart reads.
+ */
+export declare function startNetworkCapture(desktop: E2BDesktopSandbox, requestTimeoutMs: number, endpoint: ChromeCdpEndpoint, network: ChromeNetworkCaptureRequest): Promise<string>;
+/**
+ * What the capture holder announced: when capture started on the launch page, on the sandbox
+ * clock, or why it did not. Reads the holder's log up to 6 times, half a second apart by
+ * `desktop.wait`, and reports a holder that printed nothing as unavailable.
+ */
+export declare function readNetworkCaptureStart(desktop: E2BDesktopSandbox, requestTimeoutMs: number, holderName: string): Promise<NonNullable<ChromeCdpProbeResult["network"]>>;
+/**
+ * The capture holder's events file as text: whole lines only, from at most the first 32 MiB.
+ * Throws when the sandbox cannot stream files or the file cannot be read.
+ */
+export declare function readNetworkEvents(desktop: E2BDesktopSandbox, eventsPath: string, requestTimeoutMs: number): Promise<string>;