humanish 0.141.0 → 0.143.0

package/dist/run/run-cost.js

@@ -77,8 +77,13 @@ function estimateText(usd, complete) {
 function analysesNoun(requests) {
     return requests === 1 ? "analysis" : `${requests} analyses`;
 }
+const BILLED_BY = {
+    openai: "OpenAI API key",
+    gemini: "Gemini API key",
+    codex: "Codex account",
+};
 function billedBy(providers) {
-    const names = providers.map((provider) => provider === "openai" ? "OpenAI API key" : "Codex account");
+    const names = providers.map((provider) => BILLED_BY[provider]);
     return names.length === 0 ? "" : ` (${names.join(" and ")})`;
 }
 /**

package/dist/run/run.d.ts

@@ -11,6 +11,12 @@ interface StartRunOptions {
     cwd: string;
     /** Caller-supplied id (`--run-id`, library `runId`); `mintRunId` runs when it is absent. */
     runId?: string | undefined;
+    /**
+     * The run key every sandbox of this run carries (16 lowercase hex), in place of the one derived
+     * from the run directory. A remote run's launcher chooses it, so its own directory and the
+     * remote one name the same sandboxes.
+     */
+    ownerKey?: string | undefined;
     mintRunId: () => string;
     mode: "dry-run" | "live";
     study?: RunStudyProvenance | undefined;
@@ -44,6 +50,8 @@ interface StartRunPlan {
 interface StartRunInput {
     /** Caller-supplied id (`--run-id`, library `runId`); one is minted from the prefix when absent. */
     readonly runId?: string | undefined;
+    /** The run key its sandboxes carry; see StartRunOptions.ownerKey. */
+    readonly ownerKey?: string | undefined;
     /** Open the Observer page once it renders. */
     readonly open?: boolean | undefined;
     /**
@@ -215,4 +223,9 @@ export declare function runScope<T>(fn: (scope: RunScope) => Promise<T>, hooks?:
     result: T;
     finished: FinishedRun | undefined;
 }>;
+/**
+ * Make `runId` the project's latest run. A published run does it as it finishes, and a remote run's
+ * launcher once the run is copied back; this is the only writer of the pointer.
+ */
+export declare function pointLatestRunAt(paths: PreparedRunArtifactPaths, runId: string, now?: () => number): Promise<void>;
 export {};

package/dist/run/run.js

@@ -20,6 +20,7 @@ import { RunSecrets } from "./secrets.js";
 import { RUN_STATUS_FILE, beginRunStatus, runStatusOutcome, } from "./status.js";
 import { readRunJsonIfExists, runJsonValue } from "./locate.js";
 import { hostSuspensionEvents, systemHostClock, } from "./host-suspension.js";
+import { pinRunOwnerKey } from "./sandbox-creates.js";
 import { splitStreamTraces } from "./stream-trace.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
@@ -203,13 +204,7 @@ function runPublisher(args) {
         return written;
     };
     const writePointer = async () => {
-        const pointer = {
-            schema: "humanish.latest-run.v1",
-            runId,
-            path: paths.relativeRunRoot,
-            updatedAt: new Date(now()).toISOString(),
-        };
-        await writePreparedRunLatestPointer(paths, json(pointer), "utf8");
+        await pointLatestRunAt(paths, runId, now);
         pointerWritten = true;
     };
     // Each running participant's items so far, appended to its live file as the flushes arrive.
@@ -326,6 +321,8 @@ export async function runScope(fn, hooks = {}) {
             const created = await createRunArtifactPaths(options.cwd, runId);
             if (!created.ok)
                 return created;
+            if (options.ownerKey !== undefined)
+                await pinRunOwnerKey(created.paths, options.ownerKey);
             // beginRunStatus reads only the mode, the study provenance, the sandboxes field and the
             // clock from the run's options.
             const runStatus = beginRunStatus(created.paths, { ...options, runId });
@@ -435,11 +432,25 @@ export async function runScope(fn, hooks = {}) {
     }
     return { result: outcome.result, finished };
 }
+/**
+ * Make `runId` the project's latest run. A published run does it as it finishes, and a remote run's
+ * launcher once the run is copied back; this is the only writer of the pointer.
+ */
+export async function pointLatestRunAt(paths, runId, now = Date.now) {
+    const pointer = {
+        schema: "humanish.latest-run.v1",
+        runId,
+        path: paths.relativeRunRoot,
+        updatedAt: new Date(now()).toISOString(),
+    };
+    await writePreparedRunLatestPointer(paths, json(pointer), "utf8");
+}
 /** Start a recorded route's run through `start`, the scope's own form, then capture its source. */
 async function startRecordedRun(start, plan, input, route) {
     const started = await start({
         cwd: route.cwd,
         runId: input.runId,
+        ownerKey: input.ownerKey,
         mintRunId: () => mintRunId(route.prefix),
         mode: plan.dryRun ? "dry-run" : "live",
         study: plan.study,

package/dist/run/sandbox-creates.d.ts

@@ -1,4 +1,4 @@
-import type { PreparedOutputRoot } from "./contained-output.js";
+import { type PreparedOutputRoot } from "./contained-output.js";
 import type { SandboxOwnerTags, SandboxProviderId } from "./sandbox-receipts.js";
 /** Refuses a sandbox create for a run directory whose process is stopping. */
 export declare class SandboxCreateRefusedError extends Error {
@@ -17,10 +17,17 @@ export interface CreatedSandbox {
  * The E2B metadata that ties a sandbox to the directory that journals it. `runId` is the
  * directory's name: the run id, or a preflight probe's id. `runKey` is a digest of the directory's
  * inode and creation time, so two projects that both use `--run-id smoke` never match each other's
- * sandboxes, and a renamed project directory still matches its own. `tool` is the owner tag every
- * route already sets.
+ * sandboxes, and a renamed project directory still matches its own. A directory whose run was given
+ * a key (pinRunOwnerKey) uses that key instead, so two directories on different machines, a remote
+ * run's and its launcher's, name the same sandboxes. `tool` is the owner tag every route already
+ * sets.
  */
 export declare function sandboxOwnerTags(root: PreparedOutputRoot): SandboxOwnerTags;
+/**
+ * Give a new run directory the run key `key` (16 lowercase hex characters) before it creates any
+ * sandbox. The file is created once and never replaced.
+ */
+export declare function pinRunOwnerKey(root: PreparedOutputRoot, key: string): Promise<void>;
 /** A create in progress; the acquire step in src/substrates/e2b/sandbox.ts holds one per create. */
 export interface SandboxCreateTicket {
     /** Whether the directory's process has started stopping; checked before each attempt. */

package/dist/run/sandbox-creates.js

@@ -8,7 +8,9 @@
 // sandbox as soon as its id arrives. The tags let `humanish reclaim` find a sandbox whose id
 // never reached this process at all.
 import { createHash } from "node:crypto";
+import { closeSync, constants, openSync, readSync } from "node:fs";
 import path from "node:path";
+import { createContainedOutputFile } from "./contained-output.js";
 /** Refuses a sandbox create for a run directory whose process is stopping. */
 export class SandboxCreateRefusedError extends Error {
     constructor() {
@@ -59,21 +61,61 @@ function idle(entry) {
         entry.inFlight.size === 0 &&
         [...entry.created.values()].every((sandbox) => sandbox.released));
 }
+/** The file in a run directory that holds a run key its launcher chose. */
+const OWNER_KEY_FILE = "owner-key";
+const OWNER_KEY = /^[0-9a-f]{16}$/;
 /**
  * The E2B metadata that ties a sandbox to the directory that journals it. `runId` is the
  * directory's name: the run id, or a preflight probe's id. `runKey` is a digest of the directory's
  * inode and creation time, so two projects that both use `--run-id smoke` never match each other's
- * sandboxes, and a renamed project directory still matches its own. `tool` is the owner tag every
- * route already sets.
+ * sandboxes, and a renamed project directory still matches its own. A directory whose run was given
+ * a key (pinRunOwnerKey) uses that key instead, so two directories on different machines, a remote
+ * run's and its launcher's, name the same sandboxes. `tool` is the owner tag every route already
+ * sets.
  */
 export function sandboxOwnerTags(root) {
     const { where, identity } = identityOf(root);
-    const runKey = createHash("sha256")
-        .update(`${identity.ino}:${identity.birthtimeNs}`)
-        .digest("hex")
-        .slice(0, 16);
+    const runKey = pinnedOwnerKey(where) ??
+        createHash("sha256")
+            .update(`${identity.ino}:${identity.birthtimeNs}`)
+            .digest("hex")
+            .slice(0, 16);
     return { tool: "humanish", runId: path.basename(where), runKey };
 }
+/**
+ * The key pinned in the run directory at `where`, if any. The file is opened without following a
+ * link, as every other file in a run directory is; a missing or malformed file pins nothing.
+ */
+function pinnedOwnerKey(where) {
+    let fd;
+    try {
+        fd = openSync(path.join(where, OWNER_KEY_FILE), constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const buffer = Buffer.alloc(64);
+        const length = readSync(fd, buffer, 0, buffer.length, 0);
+        const key = buffer.subarray(0, length).toString("utf8").trim();
+        return OWNER_KEY.test(key) ? key : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Give a new run directory the run key `key` (16 lowercase hex characters) before it creates any
+ * sandbox. The file is created once and never replaced.
+ */
+export async function pinRunOwnerKey(root, key) {
+    if (!OWNER_KEY.test(key))
+        throw new Error("A run's owner key is 16 lowercase hexadecimal characters.");
+    await createContainedOutputFile(root, OWNER_KEY_FILE, `${key}\n`);
+}
 /** Register a create for `root`. Throws SandboxCreateRefusedError once the directory is stopping. */
 export function beginSandboxCreate(root, participantId, provider) {
     const directory = directoryFor(root);

package/dist/run-study.d.ts

@@ -81,6 +81,11 @@ interface RunStudyInternals {
     scorerProvenance?: RunScorerProvenance;
     /** The local VM study's desktop, analysis gate and signal, for a local browser study. */
     localVm?: LocalVmInput;
+    /**
+     * The run key its sandboxes carry, chosen by the process that launched this run on a remote
+     * machine (the CLI's hidden `--owner-key`). Requires `runId`.
+     */
+    ownerKey?: string;
 }
 /** A run's result and the route it ran on. */
 interface RouteOutcome<R extends StudyRoute, T> {

package/dist/study/doctor.js

@@ -12,6 +12,7 @@ import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/codex-admission.js";
 import { cli } from "../cli/invocation.js";
+import { analysisKeyNames } from "../keys/key-resolution.js";
 /** A ready row's message, with the schema values the launch recorded. */
 function readyMessage(message, readiness) {
     const additions = protocolAdditionsWarning(readiness.cliVersion, readiness.protocolAdditions);
@@ -365,7 +366,7 @@ function subjectEnvChecks(names, args) {
             : "missing declared subject environment variable; provide it with --dotenv",
     }));
 }
-/** The post-run analysis: the Codex account, or the OpenAI key and the analysis cost limit. */
+/** The post-run analysis: the Codex account, or the OpenAI or Gemini key and the cost limit. */
 async function analysisCheck(analysis, args, checkAccount) {
     if (analysis.provider === "codex") {
         const readiness = await checkAccount();
@@ -382,6 +383,18 @@ async function analysisCheck(analysis, args, checkAccount) {
                 : `Codex account analysis is unavailable (${readiness.errorCode ?? "codex_unavailable"}). ${recovery} No API fallback is used; participant readiness is independent.`,
         };
     }
+    if (analysis.provider === "gemini") {
+        const names = analysisKeyNames("gemini");
+        const geminiKeyed = names.some(args.keyPresent);
+        return {
+            name: "post-run analysis",
+            ok: true,
+            ...(geminiKeyed ? {} : { status: "note" }),
+            message: geminiKeyed
+                ? `A Gemini API key is present for the separate automatic analysis request, which sends the evidence and captures to Google; model access and quota are not tested. The analysis is refused before it starts if ${admissionRule(`$${analysis.maxCostUsd}`)}; this is not a billing cap. Participant readiness is independent.`
+                : `Will be skipped: ${names.join(" and ")} are missing. The participant may run, but there will be no automatic findings report. Add it with ${cli("keys set gemini")}, or set review.analysis: false deliberately.`,
+        };
+    }
     const keyed = args.keyPresent("OPENAI_API_KEY");
     return {
         name: "post-run analysis",

package/dist/study/requirements.d.ts

@@ -10,7 +10,7 @@ export declare function requiredSubjectEnv(requirements: readonly Requirement[])
 /**
  * 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.
  */

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

@@ -54,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

@@ -402,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/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"),
+        },
+    };
+}