humanish 0.140.0 → 0.142.0

package/dist/study/requirements.js

@@ -6,8 +6,8 @@
 // key (`key-one-of`) stays with buildRuntimeAuth at run time, which also picks its placement.
 import { detectLocalAgents } from "../actors/local-agent/cli.js";
 import { localAgentRefusal } from "../actors/local-agent/readiness.js";
-import { describeMissingKeys } from "../keys/key-resolution.js";
-import { MODEL_RATES, unpricedCapMessage } from "../run/pricing.js";
+import { analysisKeyNames, describeMissingKeys } from "../keys/key-resolution.js";
+import { participantRate, unpricedCapMessage } from "../run/pricing.js";
 /** Provider keys in the order the routes name them in a refusal. */
 const KEY_ORDER = [
     "OPENAI_API_KEY",
@@ -45,7 +45,7 @@ export function requiredSubjectEnv(requirements) {
 /**
  * The provider keys a live run of `plan` is known to read: its `key` and `key-one-of` names, its
  * subject env, the external catch's token variable, ANTHROPIC_API_KEY for a Claude Code
- * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `run` prints a
+ * participant, and the analyst's key when automatic analysis runs on OpenAI or Gemini. `run` prints a
  * key-source line for these only. Discovery still fills every key it finds: other readers, such as
  * a declared scorer's host code, are not in the plan.
  */
@@ -63,8 +63,10 @@ export function keyNamesOf(plan) {
     const catchToken = plan.residual.comms?.email?.external?.authTokenEnv;
     if (catchToken !== undefined)
         names.add(catchToken);
-    if (plan.analysis !== undefined && plan.analysis.config.provider !== "codex")
-        names.add("OPENAI_API_KEY");
+    const analyst = plan.analysis?.config.provider;
+    if (plan.analysis !== undefined && analyst !== "codex")
+        for (const name of analysisKeyNames(analyst ?? "openai"))
+            names.add(name);
     return names;
 }
 /**
@@ -140,7 +142,7 @@ export function unpricedCapCheck(args) {
     const { caps, model } = args;
     if (caps.maxUsd === undefined && caps.maxTotalUsd === undefined)
         return undefined;
-    if (MODEL_RATES[model.trim().toLowerCase()])
+    if (participantRate(model))
         return undefined;
     return { code: args.code, message: unpricedCapMessage(model) };
 }

package/dist/study/route-inputs.js

@@ -10,6 +10,7 @@ export function computerUseInput(options, deps, emit) {
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.onObserverReady === undefined ? {} : { onObserverReady: options.onObserverReady }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
+        ...(options.ownerKey === undefined ? {} : { ownerKey: options.ownerKey }),
         ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
         ...(options.env === undefined ? {} : { env: options.env }),
         ...(options.prepareDesktop === undefined ? {} : { prepareDesktop: options.prepareDesktop }),
@@ -28,6 +29,7 @@ export function scriptedInput(options, deps, emit) {
         cwd: options.cwd,
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
+        ...(options.ownerKey === undefined ? {} : { ownerKey: options.ownerKey }),
         ...(options.env === undefined ? {} : { env: options.env }),
         ...(options.prepareDesktop === undefined ? {} : { prepareDesktop: options.prepareDesktop }),
         deps,
@@ -40,6 +42,7 @@ export function terminalInput(options, deps, emit) {
         cwd: options.cwd,
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
+        ...(options.ownerKey === undefined ? {} : { ownerKey: options.ownerKey }),
         ...(options.env === undefined ? {} : { env: options.env }),
         deps,
         ...scorerOf(options, terminalRouteScorer),
@@ -52,6 +55,7 @@ export function sharedWorldInput(options, deps, emit) {
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.onObserverReady === undefined ? {} : { onObserverReady: options.onObserverReady }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
+        ...(options.ownerKey === undefined ? {} : { ownerKey: options.ownerKey }),
         ...(options.env === undefined ? {} : { env: options.env }),
         ...(options.prepareDesktop === undefined ? {} : { prepareDesktop: options.prepareDesktop }),
         ...observersOf(options, emit),

package/dist/study/run-study-events.d.ts

@@ -19,7 +19,8 @@ export type SetupTarget = {
     readonly participant: ParticipantRef;
 };
 /**
- * What a run reports while it runs. `plan` comes from computer use only; the other routes run from
+ * What a run reports while it runs. `run-started` comes from every route that records a run, once
+ * its run id exists. `plan` comes from computer use only; the other routes run from
  * the study plan but do not emit it. `subject-phase` comes from computer use (participant target)
  * and shared world (subject target).
  */
@@ -40,6 +41,11 @@ export type StudyEvent = {
     at: string;
     ok?: boolean;
     durationMs?: number;
+}
+/** The run's directory and status.json exist: `runId` names it from here on. */
+ | {
+    type: "run-started";
+    runId: string;
 } | {
     type: "analysis-started";
 } | {
@@ -48,7 +54,7 @@ export type StudyEvent = {
 /**
  * The literal values to scrub from an onEvent warning: the provider keys and the declared subject
  * env from every env the run could read (the `env` option and process.env), and the
- * analysis API key. A callback can hold any of them, and its warning is appended after the route
+ * analysis API keys, OpenAI's and Gemini's. A callback can hold any of them, and its warning is appended after the route
  * sanitized its own.
  */
 export declare function knownSecrets(config: StudyConfig, options: InternalRunStudyOptions, forwardedEnv: Readonly<Record<string, string | undefined>> | undefined): RunSecrets;

package/dist/study/run-study-events.js

@@ -1,17 +1,24 @@
 // What a run reports through RunStudyOptions.onEvent, and how a callback failure becomes a run
 // warning. normalizeRunStudyOptions (run-study-options.ts) builds the emitter and hands it to the
 // route hook bags it maps; the event values are built here.
+import { analysisKeyNames } from "../keys/key-resolution.js";
 import { redactText, toErrorMessage } from "../evidence/redaction.js";
 import { RunSecrets } from "../run/secrets.js";
 /**
  * The literal values to scrub from an onEvent warning: the provider keys and the declared subject
  * env from every env the run could read (the `env` option and process.env), and the
- * analysis API key. A callback can hold any of them, and its warning is appended after the route
+ * analysis API keys, OpenAI's and Gemini's. A callback can hold any of them, and its warning is appended after the route
  * sanitized its own.
  */
 export function knownSecrets(config, options, forwardedEnv) {
     const sources = [forwardedEnv, options.env, process.env];
-    const names = ["OPENAI_API_KEY", "E2B_API_KEY", "CODEX_API_KEY", ...(config.subject.env ?? [])];
+    const names = [
+        "OPENAI_API_KEY",
+        "E2B_API_KEY",
+        "CODEX_API_KEY",
+        ...analysisKeyNames("gemini"),
+        ...(config.subject.env ?? []),
+    ];
     const secrets = new RunSecrets([]);
     for (const env of sources)
         for (const name of names)

package/dist/substrates/e2b/base-module.d.ts

@@ -0,0 +1,3 @@
+import { type E2BDesktopModule } from "./sdk.js";
+/** A sandbox port that creates and connects to E2B base-template sandboxes. */
+export declare function loadE2BBaseModule(): Promise<E2BDesktopModule>;

package/dist/substrates/e2b/base-module.js

@@ -0,0 +1,40 @@
+// E2B's base sandbox, the `base` template with no desktop, behind the same sandbox port as the
+// desktop, so acquire(), receipts, release and reclaim work on it unchanged. A sandbox that runs
+// humanish itself needs commands, files and one authenticated port; the desktop template would
+// start an X session nobody uses and bill its 8 vCPU.
+//
+// @e2b/desktop re-exports the e2b SDK but replaces its Sandbox with the desktop subclass, and a
+// strict install does not let humanish import `e2b`, which is only @e2b/desktop's dependency. The
+// base class is the desktop class's parent.
+import { guardDesktopSandboxCreate, importE2BDesktop, } from "./sdk.js";
+import { shellOnlySurface } from "./shell-only.js";
+/** The header E2B's proxy reads a sandbox's traffic access token from (spike, 2026-10-21). */
+const TRAFFIC_TOKEN_HEADER = "e2b-traffic-access-token";
+class E2BDesktopOnlyError extends Error {
+    constructor(what) {
+        super(`${what} needs a desktop sandbox; this E2B sandbox runs the base template.`);
+        this.name = "E2BDesktopOnlyError";
+    }
+}
+/** A sandbox port that creates and connects to E2B base-template sandboxes. */
+export async function loadE2BBaseModule() {
+    return guardDesktopSandboxCreate({ Sandbox: baseSandbox(await importE2BDesktop()) });
+}
+function baseSandbox(desktop) {
+    const Base = Object.getPrototypeOf(desktop.Sandbox);
+    if (typeof Base.create !== "function")
+        throw new Error("The installed @e2b/desktop does not extend the e2b SDK's Sandbox; update @e2b/desktop.");
+    class BaseSandbox extends Base {
+        constructor(...args) {
+            super(...args);
+            Object.assign(this, shellOnlySurface((what) => new E2BDesktopOnlyError(what)));
+        }
+        async portAccess(port) {
+            const token = this.trafficAccessToken;
+            if (token === undefined || token === "")
+                throw new Error("This E2B sandbox accepts public traffic, so it has no traffic access token. Create it with network.allowPublicTraffic set to false.");
+            return { url: `https://${this.getHost(port)}`, headers: { [TRAFFIC_TOKEN_HEADER]: token } };
+        }
+    }
+    return BaseSandbox;
+}

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

@@ -81,4 +81,4 @@ extraChromiumFlags?: readonly string[], environment?: Readonly<Record<string, st
  * from it run in that zone.
  */
 export declare function openDesktopTerminal(desktop: E2BDesktopSandbox, requestTimeoutMs: number, workdir: string | undefined, timeZone?: string): Promise<void>;
-export declare function startDesktopStream(desktop: E2BDesktopSandbox, browserWindowId: string | undefined): Promise<void>;
+export declare function startDesktopStream(desktop: E2BDesktopSandbox, browserWindowId: string | undefined, requestTimeoutMs: number): Promise<void>;

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

@@ -5,6 +5,7 @@ import { failureTail } from "../../evidence/redaction.js";
 import { isHttpUrl } from "../../study/parse/subject.js";
 import { runDetachedStep } from "../detached.js";
 import { shellQuote } from "../shell.js";
+import { externalLinkHandlerSetup } from "./desktop-handoff.js";
 import { e2bShell } from "./shell.js";
 // Settle after opening the browser or the terminal, before the first screenshot: long enough for
 // a cold browser and page load to paint (2 s captured a blank desktop; the render needs 6-9 s).
@@ -210,7 +211,8 @@ extraChromiumFlags = [], environment) {
             `target_url=${shellQuote(targetUrl)}`,
             `browser_preference=${shellQuote(requestedBrowser)}`,
             "profile_dir=",
-            `chrome_preferences_json=${shellQuote(chromiumEvidenceProfilePreferencesJson())}`,
+            `chrome_preferences_json=${shellQuote(chromiumEvidenceProfilePreferencesJson(targetUrl))}`,
+            externalLinkHandlerSetup(),
             "prepare_profile() {",
             '  profile_dir="$(mktemp -d /tmp/humanish-chrome-profile.XXXXXX)"',
             '  mkdir -p "$profile_dir/Default"',
@@ -400,15 +402,33 @@ export async function openDesktopTerminal(desktop, requestTimeoutMs, workdir, ti
         throw new Error("desktop-cli participant could not open a terminal on this desktop template");
     }
 }
-export async function startDesktopStream(desktop, browserWindowId) {
+export async function startDesktopStream(desktop, browserWindowId, requestTimeoutMs) {
     if (!browserWindowId) {
         await desktop.stream.start({ requireAuth: true });
-        return;
     }
-    try {
-        await desktop.stream.start({ requireAuth: true, windowId: browserWindowId });
+    else {
+        try {
+            await desktop.stream.start({ requireAuth: true, windowId: browserWindowId });
+        }
+        catch {
+            await desktop.stream.start({ requireAuth: true });
+        }
     }
-    catch {
-        await desktop.stream.start({ requireAuth: true });
+    await makeStreamViewOnly(desktop, requestTimeoutMs);
+}
+/**
+ * Switches the stream's VNC server to view-only and confirms it. Both providers start x11vnc
+ * without `-viewonly`, and the URL's `view_only` is a noVNC client setting, so anyone holding the
+ * URL could otherwise type into the participant's desktop. x11vnc takes the change over its X
+ * property channel and answers the query with `ans=viewonly:1`; anything else throws, and the
+ * caller treats the stream as unavailable.
+ */
+async function makeStreamViewOnly(desktop, requestTimeoutMs) {
+    const shell = e2bShell(desktop);
+    const options = { timeoutMs: 20_000, requestTimeoutMs };
+    await shell.run("x11vnc -display :0 -sync -R viewonly", options);
+    const query = await shell.run("x11vnc -display :0 -Q viewonly", options);
+    if (!/^ans=viewonly:1$/m.test(query.stdout)) {
+        throw new Error("the live stream could not be made view-only");
     }
 }

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

@@ -1,4 +1,5 @@
 import type { CuaExecutor, CuaObservation } from "../../actors/computer-use/loop.js";
+import type { ExternalHandoff } from "../../actors/computer-use/external-handoff.js";
 /**
  * The minimal slice of the @e2b/desktop Sandbox the executor depends on: a structural subset of
  * the SDK class (checked against 2.4.0), so a Sandbox satisfies it with no adapter. Methods are typed to return `Promise<void> | void` (and the
@@ -65,6 +66,12 @@ export interface E2BDesktopExecutorOptions {
      * never persists raw URL/title/text; it only uses them in memory to decide whether to stop.
      */
     observeBrowserState?: () => Promise<Pick<CuaObservation, "url" | "title" | "text" | "scrollY">>;
+    /**
+     * Optional read of the links the browser handed to another app since the last read
+     * (desktop-handoff.ts). It runs beside the browser probe and the screenshot; a read that fails
+     * leaves its links for the next one.
+     */
+    readExternalHandoffs?: () => Promise<readonly ExternalHandoff[]>;
 }
 /** The stage of a `type` action that failed. */
 export type CuaTypePhase = "desktop-write" | "text-tempfile" | "text-command";

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

@@ -151,10 +151,13 @@ export function createE2BDesktopExecutor(desktop, options = {}) {
             // Probe browser state before the screenshot so a deterministic stopWhen match
             // and its persisted frame describe the same settled surface as closely as the
             // desktop substrate allows.
+            const handoffs = options.readExternalHandoffs?.().catch(() => []);
             const browserState = await options.observeBrowserState?.().catch(() => undefined);
             const raw = await desktop.screenshot();
             const screenshot = toBuffer(raw);
+            const externalHandoffs = (await handoffs) ?? [];
             return {
+                ...(externalHandoffs.length === 0 ? {} : { externalHandoffs }),
                 screenshot,
                 stateSignature: perceptualSignature(screenshot),
                 ...(browserState?.url === undefined ? {} : { url: browserState.url }),

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

@@ -0,0 +1,22 @@
+import { type ExternalHandoff } from "../../actors/computer-use/external-handoff.js";
+import { type Shell } from "../shell.js";
+/**
+ * One stand-in, installed in `bin`, appending to `log` (a shell word). `$0` names the command it
+ * stands in for. The local guest image ships the same script
+ * (runtime/browser-guest/control/root/opt/humanish/control/bin/xdg-open).
+ */
+export declare function externalLinkStandIn(bin: string, log: string): string;
+/**
+ * Shell lines for the browser launch script, run before the browser starts: they install the
+ * stand-ins and put them first on the search path for every command the script starts after them.
+ */
+export declare function externalLinkHandlerSetup(dir?: string): string;
+/**
+ * Returns a read of the links handed off since the previous read, oldest first and at most
+ * EXTERNAL_HANDOFF_LIMITS.perObservation at a time. Reads run one at a time, so a retried
+ * observation cannot return a link twice. A line still being written is left for the next read.
+ */
+export declare function externalHandoffReader(shell: Pick<Shell, "run">, options: {
+    requestTimeoutMs: number;
+    dir?: string;
+}): () => Promise<ExternalHandoff[]>;

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

@@ -0,0 +1,86 @@
+// Links the participant's browser hands to another app (mailto:, tel:, sms:) on a hosted desktop.
+//
+// Chrome on Linux opens such a link by running `xdg-email` (mailto) or `xdg-open` (the rest) by
+// name, unless an XDG desktop portal answers on the session bus; the stock desktop runs none.
+// The stock desktop has no mail, phone or messaging app, so `xdg-open` ended in XFCE's "Choose
+// Preferred Application" dialog, which participants reported as a fault of the app under test.
+// The browser launch puts stand-ins for both commands first on the browser's search path. A stand-in
+// appends the link to a log and exits; a web or file link goes on to the desktop's own command.
+// The executor reads the log on each observation, and the participant loop records each link
+// and tells the participant what happened. Chrome's own "Open xdg-open?" prompt for tel: and
+// the other non-mailto schemes is answered by the profile preference in
+// src/evidence/browser-hygiene.ts; Chrome never prompts for mailto.
+import { EXTERNAL_HANDOFF_LIMITS, externalHandoffOf, } from "../../actors/computer-use/external-handoff.js";
+import { shellQuote } from "../shell.js";
+/** Where the stand-ins and their log live on the desktop. */
+const EXTERNAL_LINK_DIR = "/tmp/humanish-external-links";
+const LINK_LENGTH = 4096;
+/**
+ * One stand-in, installed in `bin`, appending to `log` (a shell word). `$0` names the command it
+ * stands in for. The local guest image ships the same script
+ * (runtime/browser-guest/control/root/opt/humanish/control/bin/xdg-open).
+ */
+export function externalLinkStandIn(bin, log) {
+    return [
+        "#!/bin/sh",
+        "# Installed by humanish for a study participant's browser: this desktop has no app for this",
+        "# link, so the link is written down for the study instead of opening a chooser dialog.",
+        `bin=${shellQuote(bin)}`,
+        "url=",
+        'for arg in "$@"; do case "$arg" in -*) ;; *) url=$arg; break ;; esac; done',
+        'case "$url" in',
+        "  [Hh][Tt][Tt][Pp]:*|[Hh][Tt][Tt][Pp][Ss]:*|[Ff][Ii][Ll][Ee]:*) ;;",
+        "  [A-Za-z]*:*)",
+        `    printf '%s\\n' "$(printf '%s' "$url" | tr -d '\\r\\n' | cut -c 1-${LINK_LENGTH})" >> ${log}`,
+        "    exit 0 ;;",
+        "esac",
+        // Anything else goes to the desktop's own command, found on the search path without this
+        // directory.
+        "set -f",
+        "real=",
+        "IFS=:",
+        'for entry in $PATH; do [ "$entry" = "$bin" ] || real=${real:+$real:}$entry; done',
+        'PATH=$real exec "${0##*/}" "$@"',
+        "",
+    ].join("\n");
+}
+/**
+ * Shell lines for the browser launch script, run before the browser starts: they install the
+ * stand-ins and put them first on the search path for every command the script starts after them.
+ */
+export function externalLinkHandlerSetup(dir = EXTERNAL_LINK_DIR) {
+    const bin = `${dir}/bin`;
+    return [
+        `mkdir -p ${shellQuote(bin)}`,
+        `touch ${shellQuote(`${dir}/links.log`)}`,
+        `printf '%s' ${shellQuote(externalLinkStandIn(bin, shellQuote(`${dir}/links.log`)))} > ${shellQuote(`${bin}/xdg-open`)}`,
+        `cp ${shellQuote(`${bin}/xdg-open`)} ${shellQuote(`${bin}/xdg-email`)}`,
+        `chmod 755 ${shellQuote(`${bin}/xdg-open`)} ${shellQuote(`${bin}/xdg-email`)}`,
+        `export PATH=${shellQuote(bin)}:"$PATH"`,
+    ].join("\n");
+}
+/**
+ * Returns a read of the links handed off since the previous read, oldest first and at most
+ * EXTERNAL_HANDOFF_LIMITS.perObservation at a time. Reads run one at a time, so a retried
+ * observation cannot return a link twice. A line still being written is left for the next read.
+ */
+export function externalHandoffReader(shell, options) {
+    const log = `${options.dir ?? EXTERNAL_LINK_DIR}/links.log`;
+    let consumed = 0;
+    let previous = Promise.resolve();
+    const read = async () => {
+        const result = await shell.run(`tail -n +${consumed + 1} ${shellQuote(log)} 2>/dev/null | head -n ${EXTERNAL_HANDOFF_LIMITS.perObservation}`, { requestTimeoutMs: options.requestTimeoutMs, timeoutMs: 10_000 });
+        const lines = result.stdout.split("\n");
+        lines.pop();
+        consumed += lines.length;
+        return lines.flatMap((line) => {
+            const handoff = externalHandoffOf(line);
+            return handoff === undefined ? [] : [handoff];
+        });
+    };
+    return () => {
+        const next = previous.then(read, read);
+        previous = next.catch(() => undefined);
+        return next;
+    };
+}

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

@@ -30,6 +30,12 @@ export interface E2BDesktopModule {
          * (2.38 and later) returns a paginator.
          */
         list?(options?: E2BSandboxListOptions): E2BSandboxPaginator;
+        /**
+         * A handle on a sandbox that exists, by exact id, with the same calls a create returns. Throws
+         * a SandboxNotFoundError-shaped error when the id is gone. A process that did not create the
+         * sandbox uses it to run commands there and reach its ports.
+         */
+        connect?(sandboxId: string, options?: E2BRequestOptions): Promise<E2BDesktopSandbox>;
     };
 }
 /**
@@ -84,6 +90,17 @@ export interface E2BNetworkOptions {
             headers?: Record<string, string>;
         };
     }[]>;
+    /**
+     * False makes every URL `getHost` gives answer only requests that carry the sandbox's traffic
+     * access token. E2B's own default is true.
+     */
+    allowPublicTraffic?: boolean;
+}
+/** A URL that reaches a port inside a sandbox, and the headers the provider requires on each request. */
+export interface SandboxPortAccess {
+    url: string;
+    /** Credentials: never persist or log them. */
+    headers: Record<string, string>;
 }
 /**
  * A create names its account. e2bAccount (connection.ts) gives every later call on the sandbox the
@@ -172,6 +189,11 @@ export interface E2BDesktopSandbox {
      * the concurrent backend fails closed when it is absent rather than calling a missing method.
      */
     getHost?(port: number): string;
+    /**
+     * The URL and credential headers that reach `port`, for a sandbox whose provider authenticates
+     * port traffic: an E2B sandbox created with `allowPublicTraffic: false`, or any Modal sandbox.
+     */
+    portAccess?(port: number): Promise<SandboxPortAccess>;
     screenshot(format?: "bytes"): Promise<Uint8Array>;
     wait(ms: number): Promise<void>;
     leftClick(x?: number, y?: number): Promise<void>;
@@ -202,6 +224,8 @@ export interface E2BDesktopSandbox {
     };
 }
 export declare function loadE2BDesktopModule(): Promise<E2BDesktopModule>;
+/** The optional @e2b/desktop peer as it is, or an error that says how to install it. */
+export declare function importE2BDesktop(): Promise<E2BDesktopModule>;
 export declare const DESKTOP_CREATE_CLEANUP_TIMEOUT_MS = 10000;
 /**
  * Call `observer` with the sandbox id as soon as the guarded SDK constructs the handle for a

package/dist/substrates/e2b/sdk.js

@@ -8,8 +8,12 @@
 import { protectDesktopScreenshotCleanup } from "./desktop-screenshot-cleanup.js";
 import { desktopPeerAdvice, humanishInstall } from "./peer-install.js";
 export async function loadE2BDesktopModule() {
+    return guardDesktopSandboxCreate(await importE2BDesktop());
+}
+/** The optional @e2b/desktop peer as it is, or an error that says how to install it. */
+export async function importE2BDesktop() {
     try {
-        return guardDesktopSandboxCreate((await import("@e2b/desktop")));
+        return (await import("@e2b/desktop"));
     }
     catch (error) {
         if (isMissingE2BDesktopDependency(error)) {

package/dist/substrates/e2b/shell-only.d.ts

@@ -0,0 +1,5 @@
+import type { E2BDesktopSandbox } from "./sdk.js";
+type DesktopSurface = Pick<E2BDesktopSandbox, "wait" | "launch" | "screenshot" | "leftClick" | "rightClick" | "middleClick" | "doubleClick" | "moveMouse" | "scroll" | "write" | "press" | "drag" | "stream">;
+/** Desktop calls that reject with `unsupported(what)`; `wait` still waits. */
+export declare function shellOnlySurface(unsupported: (what: string) => Error): DesktopSurface;
+export {};

package/dist/substrates/e2b/shell-only.js

@@ -0,0 +1,27 @@
+/** Desktop calls that reject with `unsupported(what)`; `wait` still waits. */
+export function shellOnlySurface(unsupported) {
+    const reject = (what) => () => Promise.reject(unsupported(what));
+    return {
+        wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        launch: reject("A desktop application launch"),
+        screenshot: reject("A desktop screenshot"),
+        leftClick: reject("Desktop input"),
+        rightClick: reject("Desktop input"),
+        middleClick: reject("Desktop input"),
+        doubleClick: reject("Desktop input"),
+        moveMouse: reject("Desktop input"),
+        scroll: reject("Desktop input"),
+        write: reject("Desktop input"),
+        press: reject("Desktop input"),
+        drag: reject("Desktop input"),
+        stream: {
+            getAuthKey: () => {
+                throw unsupported("A desktop stream");
+            },
+            getUrl: () => {
+                throw unsupported("A desktop stream");
+            },
+            start: reject("A desktop stream"),
+        },
+    };
+}

package/dist/substrates/local/runtime-release.js

@@ -1,18 +1,18 @@
 /** Updated with the verified, public runtime artifact before release. */
 const LOCAL_RUNTIME_RELEASE = {
-    url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.10.21.1/runtime-linux-amd64.tar.gz",
-    sha256: "1de53db000f661e91ff6ea9a2eb8198b08b850621cf63d8ce7c1b046f5035faf",
-    bytes: 597029770,
-    image: "sha256:c805c310b7b086276efa74ea5735e8b559457c7edba85c5c9e3ac7934e8760f2",
+    url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.10.21.3/runtime-linux-amd64.tar.gz",
+    sha256: "6fc19792e9b8f414165a73470526cc414c98d0ad368210c5e95daf29469b8dbd",
+    bytes: 597049520,
+    image: "sha256:4672388737bd7d136910fca6f8b6d99e09fbe96c13e1b100491c05444e7d267a",
 };
 /** Architecture-specific artifacts; each retains matching sources and notices. */
 export const LOCAL_RUNTIME_RELEASES = {
     amd64: LOCAL_RUNTIME_RELEASE,
     arm64: {
-        url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.10.21.2/runtime-linux-arm64.tar.gz",
-        sha256: "ea7a42e12eae3b4d9140fff41e4e3512930202f9ccbb688497b146634d1cef10",
-        bytes: 583555960,
-        image: "sha256:e21c33b4745afdb3bac6a69c76606814348032ee661228c9bfdd9c7d06591a28",
+        url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.10.21.4/runtime-linux-arm64.tar.gz",
+        sha256: "d590de49a86eabe1cd09d7556aa75b2ebd62bc2c88fe37122e2af315c478c901",
+        bytes: 583551803,
+        image: "sha256:4606122520504f7f587f52b872165e6ab900be0ba3eca933b2f6dd3b9dcde723",
     },
 };
 /** Media assets are separate so ordinary browser studies keep the smaller download. */

package/dist/substrates/modal/sandbox.js

@@ -7,6 +7,7 @@
 // default gVisor runtime sets no_new_privs on every process, so the user's sudo, which the Node
 // bootstrap and product installs run, cannot work there.
 import { E2BDesktopStartupError, reportDesktopAllocation } from "../e2b/sdk.js";
+import { shellOnlySurface } from "../e2b/shell-only.js";
 import { readBytes, readFile, runCommand, sandboxPath, wholeSeconds, writeFile, } from "./commands.js";
 import { MODAL_DESKTOP_DISPLAY, MODAL_STREAM_PORT, modalDesktopSurface, startModalDesktop, } from "./desktop.js";
 import { MODAL_SANDBOX_USER, modalDesktopImage, modalShellImage } from "./image.js";
@@ -70,9 +71,7 @@ export function modalSandboxModule(client, connection, profile) {
                 ...(options.resolution === undefined ? {} : { resolution: options.resolution }),
                 ...(options.dpi === undefined ? {} : { dpi: options.dpi }),
             });
-            const tunnels = await sandbox.tunnels(30_000);
-            const hosts = new Map(Object.entries(tunnels).map(([port, tunnel]) => [Number(port), new URL(tunnel.url).host]));
-            return modalSandboxHandle(sandbox, profile, connection, hosts);
+            return modalSandboxHandle(sandbox, profile, connection, await tunnelHosts(sandbox));
         }
         catch (error) {
             const gone = await modalSandboxes(client, connection)
@@ -82,13 +81,33 @@ export function modalSandboxModule(client, connection, profile) {
             throw new E2BDesktopStartupError(error, gone);
         }
     }
+    async function connect(sandboxId, options) {
+        const ms = options?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        let sandbox;
+        try {
+            sandbox = await within(client.sandboxes.fromId(sandboxId), ms, "a sandbox lookup");
+            if ((await within(sandbox.poll(), ms, "a sandbox poll")) !== null)
+                throw sandboxNotFound(sandboxId);
+        }
+        catch (error) {
+            throw isModalNotFoundError(error) ? sandboxNotFound(sandboxId) : error;
+        }
+        const hosts = profile.desktop === true ? await tunnelHosts(sandbox) : new Map();
+        return modalSandboxHandle(sandbox, profile, connection, hosts);
+    }
     return {
         Sandbox: {
             create: hidingTokens(connection, create),
+            connect: hidingTokens(connection, connect),
             ...modalSandboxes(client, connection),
         },
     };
 }
+/** The host of each tunnel a desktop sandbox exposes, by port. */
+async function tunnelHosts(sandbox) {
+    const tunnels = await sandbox.tunnels(30_000);
+    return new Map(Object.entries(tunnels).map(([port, tunnel]) => [Number(port), new URL(tunnel.url).host]));
+}
 /** The humanish App in the connection's environment; only a create may make it. */
 function appLookup(client, connection, createIfMissing) {
     let app;
@@ -240,6 +259,10 @@ function modalSandboxHandle(sandbox, profile, connection, hosts) {
     const run = hidingTokens(connection, (command, options) => runCommand(sandbox, command, options));
     const shell = {
         sandboxId: sandbox.sandboxId,
+        portAccess: hidingTokens(connection, async (port) => {
+            const { url, token } = await sandbox.createConnectToken({ port });
+            return { url, headers: { Authorization: `Bearer ${token}` } };
+        }),
         // Modal reports no allocation for a sandbox; the create's request is what it bills.
         getInfo: () => Promise.resolve({ cpuCount: profile.cpu * 2, memoryMB: profile.memoryMiB }),
         commands: { run },
@@ -257,31 +280,7 @@ function modalSandboxHandle(sandbox, profile, connection, hosts) {
             ...shell,
             ...modalDesktopSurface(run, hidingTokens(connection, (path) => readBytes(sandbox, path)), hosts),
         };
-    const desktopOnly = (what) => () => Promise.reject(new ModalUnsupportedError(what));
-    return {
-        ...shell,
-        wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-        launch: desktopOnly("A desktop application launch"),
-        screenshot: desktopOnly("A desktop screenshot"),
-        leftClick: desktopOnly("Desktop input"),
-        rightClick: desktopOnly("Desktop input"),
-        middleClick: desktopOnly("Desktop input"),
-        doubleClick: desktopOnly("Desktop input"),
-        moveMouse: desktopOnly("Desktop input"),
-        scroll: desktopOnly("Desktop input"),
-        write: desktopOnly("Desktop input"),
-        press: desktopOnly("Desktop input"),
-        drag: desktopOnly("Desktop input"),
-        stream: {
-            getAuthKey: () => {
-                throw new ModalUnsupportedError("A desktop stream");
-            },
-            getUrl: () => {
-                throw new ModalUnsupportedError("A desktop stream");
-            },
-            start: desktopOnly("A desktop stream"),
-        },
-    };
+    return { ...shell, ...shellOnlySurface((what) => new ModalUnsupportedError(what)) };
 }
 /** The Modal account `env` names, for release by id and reclaim. Throws when it names none. */
 export async function modalAccount(env, load = loadModalModule) {

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

@@ -51,6 +51,13 @@ export interface ModalSandbox {
     tunnels(timeoutMs?: number): Promise<Record<number, {
         url: string;
     }>>;
+    /** A URL to `port` and a token Modal's proxy requires as `Authorization: Bearer <token>`. */
+    createConnectToken(params?: {
+        port?: number;
+    }): Promise<{
+        url: string;
+        token: string;
+    }>;
 }
 export interface ModalSandboxCreateParams {
     cpu?: number;