humanish 0.136.1 → 0.138.0

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:
@@ -336,6 +362,8 @@ def hold(port, page, request):
             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 "")
@@ -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"]}), 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>;

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

@@ -1,5 +1,3 @@
-// Chromium DevTools on a hosted E2B desktop, reached from inside the sandbox: browser state reads
-// and mobile emulation.
 import { chromeCdpProbeCommand, parseChromeCdpProbeOutput, } from "./cdp-probe.js";
 import { failureTail, toErrorMessage } from "../../evidence/redaction.js";
 import { readDetachedLog, startDetachedProcess } from "../detached.js";
@@ -18,7 +16,7 @@ import { e2bShell } from "./shell.js";
  * url/text criteria are not being measured, instead of letting the funnel report 0/N.
  */
 export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoint, options = {}) {
-    const { targetId, onUnavailable, drift } = options;
+    const { targetId, onUnavailable, drift, onClock } = options;
     let reported = false;
     let drifted = false;
     const checkedTargets = new Set(drift === undefined ? [] : [drift.emulatedTargetId]);
@@ -68,6 +66,7 @@ export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoi
             : `the participant drove a page target other than the emulated launch tab and that page reports a ${fidelity.innerWidth} px viewport where ${drift.expectedWidth} px was requested (DPR ${fidelity.devicePixelRatio}); the mobile user agent and touch events are browser-wide, the viewport override was not re-applied to it`);
     };
     return async () => {
+        onClock?.(undefined);
         let result;
         try {
             result = await shell.run(chromeCdpProbeCommand({
@@ -85,6 +84,7 @@ export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoi
             return unavailable(`probe exited ${result.exitCode}: ${failureTail(result.stderr || result.stdout)}`);
         }
         const parsed = parseChromeCdpProbeOutput(result.stdout);
+        onClock?.(parsed.now);
         if (parsed.unavailable !== undefined)
             return unavailable(parsed.unavailable);
         if (parsed.targetId !== undefined)
@@ -103,16 +103,19 @@ export const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_
  * 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 async function applyMobileEmulation(desktop, requestTimeoutMs, endpoint, request, options = {}) {
-    const { targetId } = options;
+    const { targetId, network } = options;
     const command = (mode) => chromeCdpProbeCommand({
         ...endpoint,
         ...(targetId === undefined ? {} : { targetId }),
         prefer: "pinned",
         mode,
         emulation: request,
+        ...(mode === "hold" && network !== undefined ? { network } : {}),
     });
     const shell = e2bShell(desktop);
     const read = async () => {
@@ -178,6 +181,7 @@ export async function applyMobileEmulation(desktop, requestTimeoutMs, endpoint,
         userAgent: request.userAgent,
     };
     const emulatedTargetId = applied.targetId ?? fidelityRead.targetId;
+    const capture = applied.network === undefined ? {} : { network: applied.network };
     if (fidelityRead.fidelity === undefined) {
         warnings.push(`Mobile emulation was applied but the page's own report could not be read (${fidelityRead.unavailable ?? "no fidelity read"}); desktopGeometry.fidelity carries the request without a resolved block.`);
         return {
@@ -185,6 +189,7 @@ export async function applyMobileEmulation(desktop, requestTimeoutMs, endpoint,
             warnings,
             holderName,
             ...(emulatedTargetId === undefined ? {} : { targetId: emulatedTargetId }),
+            ...capture,
         };
     }
     const resolved = { ...fidelityRead.fidelity, source: "cdp" };
@@ -207,5 +212,82 @@ export async function applyMobileEmulation(desktop, requestTimeoutMs, endpoint,
         warnings,
         holderName,
         ...(emulatedTargetId === undefined ? {} : { targetId: emulatedTargetId }),
+        ...capture,
     };
 }
+/** The holder stops writing its events file at 32 MiB, so a read stops there too. */
+const NETWORK_EVENTS_MAX_BYTES = 32 * 1024 * 1024;
+/** How many times the capture holder's log is read for its announce, and how far apart. */
+const NETWORK_ANNOUNCE_READS = 6;
+const NETWORK_ANNOUNCE_EVERY_MS = 500;
+/**
+ * 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 async function startNetworkCapture(desktop, requestTimeoutMs, endpoint, network) {
+    const holderName = `network-capture-${Date.now().toString(36)}`;
+    await startDetachedProcess(e2bShell(desktop), {
+        name: holderName,
+        command: chromeCdpProbeCommand({ ...endpoint, prefer: "pinned", mode: "hold", network }),
+        requestTimeoutMs,
+    });
+    return holderName;
+}
+/**
+ * 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 async function readNetworkCaptureStart(desktop, requestTimeoutMs, holderName) {
+    const shell = e2bShell(desktop);
+    for (let attempt = 0; attempt < NETWORK_ANNOUNCE_READS; attempt += 1) {
+        if (attempt > 0)
+            await desktop.wait(NETWORK_ANNOUNCE_EVERY_MS).catch(() => undefined);
+        const log = await readDetachedLog(shell, holderName, requestTimeoutMs).catch(() => "");
+        const line = log.split("\n").find((candidate) => candidate.trim().startsWith("{"));
+        if (line === undefined)
+            continue;
+        const announced = parseChromeCdpProbeOutput(line);
+        return (announced.network ?? {
+            unavailable: announced.unavailable ?? "the holder announced without starting capture",
+        });
+    }
+    return {
+        unavailable: `the in-sandbox holder printed nothing within ${(NETWORK_ANNOUNCE_READS * NETWORK_ANNOUNCE_EVERY_MS) / 1000} s of the desktop settling`,
+    };
+}
+/**
+ * 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 async function readNetworkEvents(desktop, eventsPath, requestTimeoutMs) {
+    if (desktop.files.read === undefined)
+        throw new Error("this E2B SDK cannot stream a sandbox file to the host");
+    const stream = await desktop.files.read(eventsPath, {
+        format: "stream",
+        requestTimeoutMs,
+        streamIdleTimeoutMs: requestTimeoutMs,
+        signal: AbortSignal.timeout(requestTimeoutMs),
+    });
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (total < NETWORK_EVENTS_MAX_BYTES) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const chunk = Buffer.from(value.subarray(0, NETWORK_EVENTS_MAX_BYTES - total));
+            chunks.push(chunk);
+            total += chunk.length;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    const bytes = Buffer.concat(chunks);
+    // A line still being written, or one the cap cut, is dropped.
+    return bytes.subarray(0, bytes.lastIndexOf(0x0a) + 1).toString("utf8");
+}

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

@@ -1,11 +1,13 @@
 import type { E2BDesktopSandbox } from "./sdk.js";
 import { type DesktopResources } from "../../run/pricing.js";
+/** Where an allocation's size came from: E2B's report, or the size humanish asked Modal for. */
+export type DesktopResourceSource = "e2b.getInfo" | "modal.create";
 export type DesktopResourceObservation = {
     resources: DesktopResources;
-    source: "e2b.getInfo";
+    source: DesktopResourceSource;
 } | {
     reason: "metadata_unavailable" | "metadata_invalid" | "metadata_timeout";
 };
 /** Called once after the caller owns and journals the handle. Never throws or delays cleanup
  * beyond the bounded wait. Persist only resource quantities, never the raw info/connection. */
-export declare function observeDesktopResources(desktop: Pick<E2BDesktopSandbox, "getInfo">, timeoutMs?: number): Promise<DesktopResourceObservation>;
+export declare function observeDesktopResources(desktop: Pick<E2BDesktopSandbox, "getInfo">, timeoutMs?: number, source?: DesktopResourceSource): Promise<DesktopResourceObservation>;

package/dist/substrates/e2b/desktop-resources.js

@@ -1,7 +1,7 @@
 import { isDesktopResources } from "../../run/pricing.js";
 /** Called once after the caller owns and journals the handle. Never throws or delays cleanup
  * beyond the bounded wait. Persist only resource quantities, never the raw info/connection. */
-export async function observeDesktopResources(desktop, timeoutMs = 1_000) {
+export async function observeDesktopResources(desktop, timeoutMs = 1_000, source = "e2b.getInfo") {
     const controller = new AbortController();
     let timer;
     try {
@@ -16,7 +16,7 @@ export async function observeDesktopResources(desktop, timeoutMs = 1_000) {
                 });
                 const resources = { cpuCount: info?.cpuCount, memoryMiB: info?.memoryMB };
                 return isDesktopResources(resources)
-                    ? { resources, source: "e2b.getInfo" }
+                    ? { resources, source }
                     : { reason: "metadata_invalid" };
             }),
             new Promise((resolve) => {

package/dist/substrates/e2b/peer-install.js

@@ -139,7 +139,7 @@ export function desktopPeerAdvice(install, spec = "@e2b/desktop") {
             return {
                 where: ", and humanish is running from a source checkout",
                 command: "pnpm install",
-                advice: spec === "@e2b/desktop"
+                advice: spec === "@e2b/desktop" || spec === "modal"
                     ? "Run `pnpm install` in the humanish checkout, which installs it as a dev dependency."
                     : `Set ${spec} in the humanish checkout's package.json, then run \`pnpm install\` there.`,
             };

package/dist/substrates/e2b/sandbox.d.ts

@@ -1,3 +1,4 @@
+import { type SandboxProviderId } from "../../run/sandbox-receipts.js";
 import type { PreparedOutputRoot } from "../../run/contained-output.js";
 import { type DesktopReleaseResult, type OwnedDesktopAllocation } from "../desktop-session.js";
 import type { StudyConfig } from "../../study/types.js";
@@ -13,6 +14,8 @@ interface E2BSandboxReceiptTarget {
 }
 export interface E2BSandboxRequest {
     module: E2BDesktopModule;
+    /** Who `module` creates sandboxes on; receipts and owner lines name it. Defaults to e2b. */
+    provider?: SandboxProviderId;
     options: E2BDesktopCreateOptions;
     retry?: TransientRetryHooks;
     /**

package/dist/substrates/e2b/sandbox.js

@@ -9,7 +9,7 @@
 // journal at that point, so a startup error that quotes it is scrubbed from every run file.
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { beginSandboxCreate, recordSandboxOwnerOnce, SandboxCreateRefusedError, sandboxOwnerTags, } from "../../run/sandbox-creates.js";
-import { appendSandboxOwner, appendSandboxReceipt } from "../../run/sandbox-receipts.js";
+import { appendSandboxOwner, appendSandboxReceipt, } from "../../run/sandbox-receipts.js";
 import { ownDesktopAllocation, } from "../desktop-session.js";
 import { e2bAccount } from "./connection.js";
 import { E2B_DEBUG_KILL_DETAIL, E2BDesktopStartupError, e2bDebugMode, isSandboxNotFoundError, observeDesktopAllocation, } from "./sdk.js";
@@ -23,9 +23,10 @@ export function acquireE2BShellSandbox(request) {
 }
 async function acquire(request, template) {
     const { module } = request;
+    const provider = request.provider ?? "e2b";
     const target = request.receipt;
     // Refused before any provider call once the run is stopping.
-    const ticket = target === null ? undefined : beginSandboxCreate(target.root, target.participantId);
+    const ticket = target === null ? undefined : beginSandboxCreate(target.root, target.participantId, provider);
     // The receipts written when the guard reported an id, before desktop startup. A startup error
     // can quote the id and the create may never return, so the journal holds it first.
     const reported = new Map();
@@ -35,7 +36,7 @@ async function acquire(request, template) {
         // journal records them first, so reclaim knows which tags to search for.
         const owner = target === null ? undefined : sandboxOwnerTags(target.root);
         if (target !== null && owner !== undefined)
-            await recordSandboxOwnerOnce(target.root, () => appendSandboxOwner(target.root, owner));
+            await recordSandboxOwnerOnce(target.root, provider, () => appendSandboxOwner(target.root, owner, provider));
         const options = owner === undefined
             ? request.options
             : { ...request.options, metadata: { ...request.options.metadata, ...owner } };
@@ -46,7 +47,7 @@ async function acquire(request, template) {
             return appendSandboxReceipt(root, {
                 at: new Date(now()).toISOString(),
                 laneId: participantId,
-                provider: "e2b",
+                provider,
                 sandboxId,
                 ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
             });

package/dist/substrates/modal/image.d.ts

@@ -0,0 +1,9 @@
+import type { ModalClient, ModalImage } from "./sdk.js";
+/** The sandbox account commands run as, matching E2B's `user` and its home. */
+export declare const MODAL_SANDBOX_USER: {
+    readonly name: "user";
+    readonly uid: 1000;
+    readonly home: "/home/user";
+};
+/** The terminal route's image: a Debian shell with a passwordless-sudo `user`, as on E2B. */
+export declare function modalShellImage(client: ModalClient): ModalImage;

package/dist/substrates/modal/image.js

@@ -0,0 +1,36 @@
+const DEBIAN_BASE = "debian@sha256:7792b1f7702a86946cd518db72b6a407302c3e9bc1635634368b878189e8221c";
+const DEBIAN_SNAPSHOT = "20260923T083042Z";
+const SECURITY_SNAPSHOT = "20260922T123247Z";
+/** The sandbox account commands run as, matching E2B's `user` and its home. */
+export const MODAL_SANDBOX_USER = { name: "user", uid: 1000, home: "/home/user" };
+const SNAPSHOT_SOURCES = `printf 'Types: deb\\nURIs: http://snapshot.debian.org/archive/debian/${DEBIAN_SNAPSHOT}/\\nSuites: trixie trixie-updates\\nComponents: main\\nSigned-By: /usr/share/keyrings/debian-archive-keyring.gpg\\nCheck-Valid-Until: no\\n\\nTypes: deb\\nURIs: http://snapshot.debian.org/archive/debian-security/${SECURITY_SNAPSHOT}/\\nSuites: trixie-security\\nComponents: main\\nSigned-By: /usr/share/keyrings/debian-archive-keyring.gpg\\nCheck-Valid-Until: no\\n'` +
+    " > /etc/apt/sources.list.d/humanish.sources";
+// What the terminal route's steps call: the Node bootstrap's prerequisites (curl, coreutils, tar,
+// gzip, sudo), git for product installs, and python3 and unzip, which E2B's stock template has.
+const SHELL_PACKAGES = [
+    "bash",
+    "ca-certificates",
+    "curl",
+    "git",
+    "gzip",
+    "less",
+    "procps",
+    "python3",
+    "sudo",
+    "tar",
+    "unzip",
+    "xz-utils",
+];
+/** The terminal route's image: a Debian shell with a passwordless-sudo `user`, as on E2B. */
+export function modalShellImage(client) {
+    const { name, uid, home } = MODAL_SANDBOX_USER;
+    // prose-check: script
+    return client.images
+        .fromRegistry(DEBIAN_BASE)
+        .dockerfileCommands([
+        "ENV DEBIAN_FRONTEND=noninteractive",
+        `RUN rm -f /etc/apt/sources.list /etc/apt/sources.list.d/* && ${SNAPSHOT_SOURCES} && apt-get update && apt-get install -y --no-install-recommends ${SHELL_PACKAGES.join(" ")} && rm -rf /var/lib/apt/lists/*`,
+        `RUN useradd --uid ${uid} --create-home --home-dir ${home} --shell /bin/bash ${name} && printf '${name} ALL=(ALL) NOPASSWD:ALL\\n' > /etc/sudoers.d/${name} && chmod 0440 /etc/sudoers.d/${name}`,
+        `WORKDIR ${home}`,
+    ]);
+}