humanish 0.136.1 → 0.138.0

package/dist/run/reclaim.js

@@ -1,14 +1,16 @@
 // `humanish reclaim`: stop an interrupted run's sandboxes and report what happened to each. It
 // finds them three ways: the exact ids the run journaled at create time (sandbox-receipts.ndjson),
 // the ids a create in this process reported before its receipt landed (the signal handler only),
-// and E2B's list of sandboxes tagged with the run's owner tags (sandboxOwnerTags), which covers a
-// sandbox whose id never reached the run. The list is filtered server-side by the run's tags and
+// and each provider's list of sandboxes tagged with the run's owner tags (sandboxOwnerTags), which
+// covers a sandbox whose id never reached the run. Every sandbox is acted on through the provider
+// its receipt or owner line names: E2B, or Modal (src/substrates/modal/sandbox.ts). The list is filtered server-side by the run's tags and
 // each result is checked against every tag again, so it can only return this run's sandboxes; an
 // account-wide operation once destroyed unrelated infrastructure. Kills run concurrently, and
 // reclaim-receipt.json is written before the first kill and after each one, so an exit at any
-// point leaves a record of every sandbox not yet confirmed gone. `--check` asks E2B the same
-// questions and kills nothing.
+// point leaves a record of every sandbox not yet confirmed gone. `--check` asks the providers the
+// same questions and kills nothing.
 import { e2bAccount, e2bConnection } from "../substrates/e2b/connection.js";
+import { modalAccount } from "../substrates/modal/sandbox.js";
 import { E2B_DEBUG_ENV, e2bDebugMode, loadE2BDesktopModule, } from "../substrates/e2b/sdk.js";
 import { readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
 import { discardPreflightJournal, listPreflightJournals, preflightReclaimDecision, } from "./preflight-receipts.js";
@@ -261,6 +263,45 @@ function unreadableMessage(file, refusal) {
     const kept = file === SANDBOX_RECEIPTS_ARTIFACT ? "the receipts were kept" : "the receipt was kept";
     return `${refusalText(file, refusal)}. Nothing was killed and ${kept}; check the file, then run reclaim again.`;
 }
+/**
+ * The account for each provider the run's journal names, or the message that stops reclaim when
+ * one it needs cannot be reached. A run with no record and creates in flight is an E2B run unless
+ * its owner line says otherwise, as every run was before Modal.
+ */
+async function reachProviders(receipts, owners, hooks) {
+    const env = hooks.env ?? process.env;
+    const recorded = new Set([
+        ...receipts.map((receipt) => receipt.provider),
+        ...owners.map((owner) => owner.provider),
+    ]);
+    // A create this process began counts too: its receipt and owner line may not have landed.
+    for (const provider of hooks.creates?.providers() ?? [])
+        recorded.add(provider);
+    const needsE2B = recorded.has("e2b") || (hooks.creates !== undefined && !recorded.has("modal"));
+    // E2B's SDK lists by tag as well as killing by id, so it is needed even with no receipt. Without
+    // it, an E2B receipt cannot be acted on; with no E2B receipt, only the tag search is lost.
+    const accounts = {};
+    const unavailable = {};
+    try {
+        const module = await (hooks.loadModule ?? loadE2BDesktopModule)();
+        accounts.e2b = e2bAccount(module, e2bConnection(env));
+    }
+    catch (error) {
+        unavailable.e2b = `Cannot load @e2b/desktop to reach E2B: ${redactText(toErrorMessage(error))}`;
+        if (needsE2B)
+            return unavailable.e2b;
+    }
+    // Modal is reached only for a run that recorded a Modal sandbox or owner line.
+    if (recorded.has("modal")) {
+        try {
+            accounts.modal = await (hooks.loadModalAccount ?? modalAccount)(env);
+        }
+        catch (error) {
+            return `Cannot reach Modal: ${redactText(toErrorMessage(error))}`;
+        }
+    }
+    return { accounts, unavailable, recorded, needsE2B };
+}
 /**
  * Find and stop (or, for `--check`, look up) every sandbox one directory owns: its receipts, the
  * creates this process reported, and E2B's tagged list, each once by exact id.
@@ -277,19 +318,10 @@ async function reclaimRoot(root, label, hooks, warnings) {
     const owners = parseSandboxOwners(journal, label);
     const check = hooks.check === true;
     const requestTimeoutMs = hooks.requestTimeoutMs ?? 60_000;
-    // The SDK lists by tag as well as killing by id, so it is needed even with no receipt. Without
-    // it, an E2B receipt cannot be acted on; with no E2B receipt, only the tag search is lost.
-    let e2b;
-    let moduleError;
-    try {
-        const module = await (hooks.loadModule ?? loadE2BDesktopModule)();
-        e2b = e2bAccount(module, e2bConnection(hooks.env ?? process.env));
-    }
-    catch (error) {
-        moduleError = `Cannot load @e2b/desktop to reach E2B: ${redactText(toErrorMessage(error))}`;
-        if (receipts.some((receipt) => receipt.provider === "e2b") || hooks.creates !== undefined)
-            return { kind: "module-unavailable", receiptCount: receipts.length, message: moduleError };
-    }
+    const reached = await reachProviders(receipts, owners, hooks);
+    if (typeof reached === "string")
+        return { kind: "module-unavailable", receiptCount: receipts.length, message: reached };
+    const { accounts, unavailable, recorded, needsE2B } = reached;
     // An earlier reclaim may have killed a sandbox no receipt names (the signal handler's creates
     // and tag finds). Its outcome is carried forward, so a later reclaim never erases that record.
     const earlier = check ? [] : await earlierOutcomes(root, label);
@@ -297,7 +329,7 @@ async function reclaimRoot(root, label, hooks, warnings) {
     if (!Array.isArray(earlier))
         return { kind: "unreadable", message: unreadableMessage(RECLAIM_RECEIPT_ARTIFACT, earlier) };
     const set = targetSet({
-        e2b,
+        accounts,
         check,
         requestTimeoutMs,
         earlier,
@@ -312,38 +344,53 @@ async function reclaimRoot(root, label, hooks, warnings) {
         if (replaying)
             replayed.set(sandbox.sandboxId, sandbox);
         else
-            set.add("e2b", sandbox.sandboxId, sandbox.participantId, "create", sandbox.released);
+            set.add(sandbox.provider, sandbox.sandboxId, sandbox.participantId, "create", sandbox.released);
     });
     replaying = false;
     for (const receipt of receipts) {
-        const released = receipt.provider === "e2b" && replayed.get(receipt.sandboxId)?.released;
+        const create = replayed.get(receipt.sandboxId);
+        const released = create?.provider === receipt.provider && create.released;
         set.add(receipt.provider, receipt.sandboxId, receipt.laneId, "receipt", released === true);
     }
     for (const sandbox of replayed.values())
-        set.add("e2b", sandbox.sandboxId, sandbox.participantId, "create", sandbox.released);
+        set.add(sandbox.provider, sandbox.sandboxId, sandbox.participantId, "create", sandbox.released);
     await set.start();
     if (hooks.creates !== undefined)
         await settledWithin(hooks.creates.settled, hooks.createsWaitMs);
-    // The tags the run recorded before each create, and this directory's own: a copied or moved
-    // run directory computes other tags than the ones its sandboxes carry.
-    const search = await searchTagSets(e2b, [...owners, sandboxOwnerTags(root)], {
-        requestTimeoutMs,
-        unavailable: moduleError ?? "no E2B SDK",
-    });
+    // Each provider is searched with the tags the run recorded for it before each create, and with
+    // this directory's own: a copied or moved run directory computes other tags than the ones its
+    // sandboxes carry. E2B is searched unless the journal names only Modal, as before Modal existed.
+    const providers = [
+        ...(needsE2B || !recorded.has("modal") ? ["e2b"] : []),
+        ...(accounts.modal === undefined ? [] : ["modal"]),
+    ];
+    const searches = await Promise.all(providers.map(async (provider) => {
+        const tagSets = [
+            ...owners.filter((owner) => owner.provider === provider).map((owner) => owner.tags),
+            sandboxOwnerTags(root),
+        ];
+        const result = await searchTagSets(accounts[provider], tagSets, {
+            requestTimeoutMs,
+            unavailable: unavailable[provider] ?? `no ${provider} account`,
+        });
+        return { provider, result };
+    }));
     let found = 0;
-    for (const listed of search.sandboxes) {
-        const metadata = listed.metadata ?? {};
-        const participant = metadata.participantId ?? metadata.kind ?? "unknown";
-        if (set.add("e2b", listed.sandboxId, participant, "tag"))
-            found += 1;
-    }
+    for (const { provider, result } of searches)
+        for (const listed of result.sandboxes) {
+            const metadata = listed.metadata ?? {};
+            const participant = metadata.participantId ?? metadata.kind ?? "unknown";
+            if (set.add(provider, listed.sandboxId, participant, "tag"))
+                found += 1;
+        }
+    const search = searches.find(({ result }) => result.status !== "done")?.result ?? searches[0].result;
     const tagSearch = {
         status: search.status,
         found,
         ...(search.detail === undefined ? {} : { detail: search.detail }),
     };
     if (search.status !== "done")
-        warnings.push(`Could not search E2B for sandboxes tagged with ${label}: ${search.detail ?? search.status}. A sandbox whose id never reached a receipt would not be found.`);
+        warnings.push(`Could not search for sandboxes tagged with ${label}: ${search.detail ?? search.status}. A sandbox whose id never reached a receipt would not be found.`);
     // A create that reports its id while the search or a kill is still running is killed too.
     await set.drain();
     unwatch?.();

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

@@ -1,5 +1,5 @@
 import type { PreparedOutputRoot } from "./contained-output.js";
-import type { SandboxOwnerTags } from "./sandbox-receipts.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 {
     constructor();
@@ -7,6 +7,7 @@ export declare class SandboxCreateRefusedError extends Error {
 /** One sandbox a create in this process reported, and what its route did with it. */
 export interface CreatedSandbox {
     sandboxId: string;
+    provider: SandboxProviderId;
     /** The participant or subject label the receipt also records. */
     participantId: string;
     /** True once the route's own release confirmed the sandbox gone. */
@@ -32,14 +33,14 @@ export interface SandboxCreateTicket {
     settled(): void;
 }
 /** Register a create for `root`. Throws SandboxCreateRefusedError once the directory is stopping. */
-export declare function beginSandboxCreate(root: PreparedOutputRoot, participantId: string): SandboxCreateTicket;
+export declare function beginSandboxCreate(root: PreparedOutputRoot, participantId: string, provider: SandboxProviderId): SandboxCreateTicket;
 /**
- * Run `write` once per directory and return its promise to every caller. Creates that start
+ * Run `write` once per directory and provider and return its promise to every caller. Creates that start
  * together then resume in the order they called, so the order they reach the provider does not
  * depend on which file append finishes first. A write that reports failure is forgotten, so the
  * next create tries again.
  */
-export declare function recordSandboxOwnerOnce(root: PreparedOutputRoot, write: () => Promise<boolean>): Promise<void>;
+export declare function recordSandboxOwnerOnce(root: PreparedOutputRoot, provider: SandboxProviderId, write: () => Promise<boolean>): Promise<void>;
 /** What the signal handler holds after stopping a directory's creates. */
 export interface StoppedSandboxCreates {
     /**
@@ -51,6 +52,8 @@ export interface StoppedSandboxCreates {
     settled: Promise<void>;
     /** How many of those creates have not settled yet. */
     inFlight(): number;
+    /** The providers creates began on, including those whose id has not arrived. */
+    providers(): ReadonlySet<SandboxProviderId>;
 }
 /**
  * Stop `root`'s creates: any create that starts from now on is refused. Called synchronously when

package/dist/run/sandbox-creates.js

@@ -36,6 +36,8 @@ function directoryFor(root) {
         return existing;
     const created = {
         stopping: false,
+        ownerLines: new Map(),
+        providers: new Set(),
         created: new Map(),
         inFlight: new Set(),
         listeners: new Set(),
@@ -73,10 +75,11 @@ export function sandboxOwnerTags(root) {
     return { tool: "humanish", runId: path.basename(where), runKey };
 }
 /** Register a create for `root`. Throws SandboxCreateRefusedError once the directory is stopping. */
-export function beginSandboxCreate(root, participantId) {
+export function beginSandboxCreate(root, participantId, provider) {
     const directory = directoryFor(root);
     if (directory.stopping)
         throw new SandboxCreateRefusedError();
+    directory.providers.add(provider);
     let settle;
     const done = new Promise((resolve) => {
         settle = resolve;
@@ -87,7 +90,7 @@ export function beginSandboxCreate(root, participantId) {
         created(sandboxId) {
             if (directory.created.has(sandboxId))
                 return;
-            const sandbox = { sandboxId, participantId, released: false };
+            const sandbox = { sandboxId, provider, participantId, released: false };
             directory.created.set(sandboxId, sandbox);
             for (const listener of directory.listeners)
                 listener(sandbox);
@@ -104,17 +107,21 @@ export function beginSandboxCreate(root, participantId) {
     };
 }
 /**
- * Run `write` once per directory and return its promise to every caller. Creates that start
+ * Run `write` once per directory and provider and return its promise to every caller. Creates that start
  * together then resume in the order they called, so the order they reach the provider does not
  * depend on which file append finishes first. A write that reports failure is forgotten, so the
  * next create tries again.
  */
-export function recordSandboxOwnerOnce(root, write) {
-    const directory = directoryFor(root);
-    const pending = (directory.ownerLine ??= write().then((written) => {
-        if (!written && directory.ownerLine === pending)
-            delete directory.ownerLine;
-    }));
+export function recordSandboxOwnerOnce(root, provider, write) {
+    const { ownerLines } = directoryFor(root);
+    const existing = ownerLines.get(provider);
+    if (existing !== undefined)
+        return existing;
+    const pending = write().then((written) => {
+        if (!written && ownerLines.get(provider) === pending)
+            ownerLines.delete(provider);
+    });
+    ownerLines.set(provider, pending);
     return pending;
 }
 /**
@@ -136,5 +143,6 @@ export function stopSandboxCreates(root) {
         },
         settled: Promise.all(pending).then(() => undefined),
         inFlight: () => pending.filter((create) => directory.inFlight.has(create)).length,
+        providers: () => directory.providers,
     };
 }

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

@@ -1,7 +1,9 @@
 import { type PreparedOutputRoot } from "./contained-output.js";
 export declare const SANDBOX_RECEIPTS_ARTIFACT = "sandbox-receipts.ndjson";
 /** The providers humanish allocates sandboxes from. Reclaim dispatches on this id. */
-export type SandboxProviderId = "e2b";
+export type SandboxProviderId = "e2b" | "modal";
+/** Whether this humanish can act on sandboxes from `provider`. */
+export declare function isSandboxProviderId(provider: string): provider is SandboxProviderId;
 export interface SandboxReceipt {
     at: string;
     /** The participant or subject label the sandbox belongs to (public-safe token). */
@@ -31,18 +33,24 @@ export declare function appendedSandboxIds(root: PreparedOutputRoot): string[];
  */
 export declare function appendSandboxReceipt(root: PreparedOutputRoot, receipt: SandboxReceipt): Promise<boolean>;
 /** Append one owner line; false when the write failed, which never fails the create. */
-export declare function appendSandboxOwner(root: PreparedOutputRoot, owner: SandboxOwnerTags): Promise<boolean>;
+export declare function appendSandboxOwner(root: PreparedOutputRoot, owner: SandboxOwnerTags, provider: SandboxProviderId): Promise<boolean>;
 /** The owner tags every sandbox carries; sandboxOwnerTags in src/run/sandbox-creates.ts. */
 export type SandboxOwnerTags = {
     tool: "humanish";
     runId: string;
     runKey: string;
 };
+/** One owner line: the provider searched and the tags searched for. */
+export interface SandboxOwner {
+    provider: SandboxProviderId;
+    tags: SandboxOwnerTags;
+}
 /**
  * The owner tag sets a journal's owner lines record for the run named `runId`. Only a complete
- * tuple counts: provider e2b, `tool: humanish`, this run's id and a well-formed key, and nothing
- * else. A partial or foreign line would widen reclaim's search past this run, so it is skipped.
+ * tuple counts: a provider this version knows, `tool: humanish`, this run's id and a well-formed
+ * key, and nothing else. A partial or foreign line would widen reclaim's search past this run, so
+ * it is skipped.
  */
-export declare function parseSandboxOwners(text: string, runId: string): SandboxOwnerTags[];
+export declare function parseSandboxOwners(text: string, runId: string): SandboxOwner[];
 /** Parse a receipts file leniently: a torn final line (crash mid-append) drops, valid lines keep. */
 export declare function parseSandboxReceipts(text: string): ParsedSandboxReceipt[];

package/dist/run/sandbox-receipts.js

@@ -6,6 +6,11 @@
 import { appendFile } from "node:fs/promises";
 import { prepareContainedOutputFile } from "./contained-output.js";
 export const SANDBOX_RECEIPTS_ARTIFACT = "sandbox-receipts.ndjson";
+const SANDBOX_PROVIDERS = new Set(["e2b", "modal"]);
+/** Whether this humanish can act on sandboxes from `provider`. */
+export function isSandboxProviderId(provider) {
+    return SANDBOX_PROVIDERS.has(provider);
+}
 /**
  * The ids this process has receipted for each run directory, kept even when the append fails, so
  * the run's other records can still be scrubbed of them. Keyed by the directory's identity, so a
@@ -51,9 +56,9 @@ export async function appendSandboxReceipt(root, receipt) {
     }
 }
 /** Append one owner line; false when the write failed, which never fails the create. */
-export async function appendSandboxOwner(root, owner) {
+export async function appendSandboxOwner(root, owner, provider) {
     try {
-        const line = { at: new Date().toISOString(), provider: "e2b", owner };
+        const line = { at: new Date().toISOString(), provider, owner };
         const filePath = await prepareContainedOutputFile(root, SANDBOX_RECEIPTS_ARTIFACT);
         // The leading newline ends a line an earlier append left torn, so this record parses.
         await appendFile(filePath, `\n${JSON.stringify(line)}\n`, "utf8");
@@ -68,8 +73,9 @@ export async function appendSandboxOwner(root, owner) {
 const RUN_KEY = /^[0-9a-f]{16}$/;
 /**
  * The owner tag sets a journal's owner lines record for the run named `runId`. Only a complete
- * tuple counts: provider e2b, `tool: humanish`, this run's id and a well-formed key, and nothing
- * else. A partial or foreign line would widen reclaim's search past this run, so it is skipped.
+ * tuple counts: a provider this version knows, `tool: humanish`, this run's id and a well-formed
+ * key, and nothing else. A partial or foreign line would widen reclaim's search past this run, so
+ * it is skipped.
  */
 export function parseSandboxOwners(text, runId) {
     const owners = new Map();
@@ -80,13 +86,19 @@ export function parseSandboxOwners(text, runId) {
         try {
             const parsed = JSON.parse(trimmed);
             const owner = parsed.owner;
-            if (parsed.provider !== "e2b" || owner === null || typeof owner !== "object")
+            const provider = parsed.provider;
+            if (typeof provider !== "string" || !isSandboxProviderId(provider))
+                continue;
+            if (owner === null || typeof owner !== "object")
                 continue;
             if (Object.keys(owner).length !== 3 || owner.tool !== "humanish" || owner.runId !== runId)
                 continue;
             if (typeof owner.runKey !== "string" || !RUN_KEY.test(owner.runKey))
                 continue;
-            owners.set(owner.runKey, { tool: "humanish", runId, runKey: owner.runKey });
+            owners.set(JSON.stringify([provider, owner.runKey]), {
+                provider,
+                tags: { tool: "humanish", runId, runKey: owner.runKey },
+            });
         }
         catch {
             // A torn line: skip it.

package/dist/run/streams.d.ts

@@ -1,5 +1,6 @@
 import type { CodexAppServerTrace } from "../actors/codex/app-server-trace.js";
 import type { ActorStatus, ActorTrace, ActorTraceItem } from "../actors/contract.js";
+import type { BrowserNetworkIndex } from "../evidence/browser-network.js";
 import type { RunDesktopRecording } from "../evidence/desktop-recording-types.js";
 export type RunStreamKind = "ui" | "browser" | "terminal" | "tui" | "codex-ui" | "artifact" | "summary";
 export type RunSimulationStatus = "queued" | "preparing" | "running" | "passed" | "abandoned" | "incomplete" | "complete" | "blocked" | "timed_out" | "failed" | "contract_proof_only";
@@ -310,6 +311,12 @@ export interface RunStream {
     };
     completion?: RunStreamCompletion;
     recording?: RunDesktopRecording;
+    /**
+     * The participant's browser network log, when its study set `execution.network`: where the
+     * file is, what binds it, and why records are missing. The shape guard does not read it; verify
+     * checks it with the file (src/verify/network.ts).
+     */
+    network?: BrowserNetworkIndex;
     artifacts: Array<{
         label: string;
         path: string;

package/dist/study/composition-rules.js

@@ -258,15 +258,15 @@ function desktopCliValidationReason(config) {
     return null;
 }
 // terminal-product route: a real autonomous agent studies a CLI/product from public surfaces inside
-// an E2B shell. Fail-closed (claims match mechanism: a field that cannot act on this route is a
-// parse error): a registered terminal actor only, execution.target e2b-terminal or absent (absent
-// defaults to e2b-terminal, the only target where an in-sandbox agent runs), one participant until
-// fan-out lands.
+// a hosted shell. Fail-closed (claims match mechanism: a field that cannot act on this route is a
+// parse error): a registered terminal actor only, execution.target e2b-terminal, modal-terminal or
+// absent (absent defaults to e2b-terminal), one participant until fan-out lands.
 function terminalValidationReason(config) {
     if (config.subject.source === "terminal-product") {
         const type = config.actor?.type ?? "";
-        if (config.execution?.target !== undefined && config.execution.target !== "e2b-terminal") {
-            return "A terminal-product subject runs its agent in an E2B shell. Set `execution.target: e2b-terminal` or omit it; `local` and `e2b-desktop` are not supported.";
+        const target = config.execution?.target;
+        if (target !== undefined && target !== "e2b-terminal" && target !== "modal-terminal") {
+            return "A terminal-product subject runs its agent in a hosted shell. Set `execution.target` to e2b-terminal or modal-terminal, or omit it for e2b-terminal; `local` and `e2b-desktop` are not supported.";
         }
         if (!actorResolvesToTerminal(type)) {
             return `actor.type must be a registered terminal actor for terminal-product subjects (one of: ${registeredTerminalActors().join(", ")}). Got "${type}".`;
@@ -275,10 +275,11 @@ function terminalValidationReason(config) {
             return "Terminal fan-out to more than one participant is not supported yet; set participants to 1.";
         }
     }
-    else if (config.execution?.target === "e2b-terminal") {
-        // e2b-terminal is the terminal-product substrate only. Any other source declaring it is a
-        // mis-config: reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
-        return "`execution.target: e2b-terminal` requires `subject.source: terminal-product` with a registered terminal actor.";
+    else if (config.execution?.target === "e2b-terminal" ||
+        config.execution?.target === "modal-terminal") {
+        // The terminal targets are the terminal-product substrates only. Any other source declaring one
+        // is a mis-config: reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
+        return `\`execution.target: ${config.execution.target}\` requires \`subject.source: terminal-product\` with a registered terminal actor.`;
     }
     else if (actorResolvesToTerminal(config.actor?.type)) {
         // A registered terminal actor on a non-terminal-product subject: rejected, never ignored (the

package/dist/study/config.js

@@ -39,7 +39,7 @@ import { invalid, optionalStr, str } from "./parse/values.js";
 import { isComputerUseComposition, routeOf } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
 import { ID_PATTERN, STUDY_SCHEMA, } from "./types.js";
-import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, smtpValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "./validation.js";
+import { automaticAnalysisRouteReason, desktopMediaValidationReason, networkCaptureValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, smtpValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "./validation.js";
 import { forwardDeclaredWarnings, inertFieldLabels, inertFieldPaths } from "./warnings.js";
 import { plural } from "../run/text.js";
 /**
@@ -228,6 +228,9 @@ function checkStudyConfig(config) {
     const mediaReason = desktopMediaValidationReason(config);
     if (mediaReason)
         return invalid(mediaReason);
+    const networkReason = networkCaptureValidationReason(config);
+    if (networkReason)
+        return invalid(networkReason);
     const outputLimitReason = outputTokenLimitValidationReason(config);
     if (outputLimitReason)
         return invalid(outputLimitReason);

package/dist/study/doctor.js

@@ -279,7 +279,7 @@ async function realEmailCheck(connection, keys, args) {
 /** How the participant authenticates: the terminal model key, or a local agent's login. */
 async function participantChecks(config, route, keys, local, args, checkAccount) {
     if (route === "terminal") {
-        const key = keys.find((name) => name !== "E2B_API_KEY");
+        const key = keys.find((name) => name === "CODEX_API_KEY" || name === "OPENAI_API_KEY");
         return [
             {
                 name: "terminal model authentication",

package/dist/study/keys.d.ts

@@ -187,6 +187,9 @@ export declare const EXECUTION: {
         transport: true;
         doNotTrack: true;
     };
+    network: {
+        origins: true;
+    };
     desktop: {
         template: true;
         browser: true;

package/dist/study/keys.js

@@ -119,6 +119,8 @@ export const EXECUTION = {
     completionTimeoutMs: true,
     egressAllow: true,
     terminal: { stdin: true, transport: true, doNotTrack: true },
+    // true or false, or a mapping whose keys are checked here.
+    network: { origins: true },
     desktop: {
         template: true,
         browser: true,

package/dist/study/parse/comms.js

@@ -1,4 +1,4 @@
-import { invalid, posInt, str } from "./values.js";
+import { exactOrigin, invalid, posInt, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
 // Fail-loud (never silently swallow a comms setting): a malformed `comms` block returns a parse
 // failure rather than being dropped.
@@ -104,25 +104,6 @@ function parseEmailConnection(raw) {
     }
     return { ok: true, value };
 }
-/** The origin of an http(s) URL with no credentials, path, query or fragment, else undefined. */
-function exactOrigin(input) {
-    if (typeof input !== "string")
-        return undefined;
-    try {
-        const url = new URL(input);
-        return ["http:", "https:"].includes(url.protocol) &&
-            !url.username &&
-            !url.password &&
-            url.pathname === "/" &&
-            !url.search &&
-            !url.hash
-            ? url.origin
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 /** `comms.email.external`: the catch the adopter runs, its inbox and the env var holding its token. */
 function parseExternalCatch(raw) {
     if (raw === undefined)

package/dist/study/parse/execution.js

@@ -1,7 +1,7 @@
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { DEVICE_PRESET_NAMES, isDevicePresetName } from "../device-presets.js";
 import { isExactRuntimeVersion } from "../../routes/terminal/runtime.js";
-import { invalid, nonNegNumber, posInt, str } from "./values.js";
+import { exactOrigin, invalid, nonNegNumber, posInt, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
 import { scanEncodedText } from "../../evidence/encoded-text.js";
 export function parseExecution(raw) {
@@ -14,8 +14,11 @@ export function parseExecution(raw) {
     const execution = {};
     if (raw.target !== undefined) {
         const target = str(raw.target);
-        if (target !== "local" && target !== "e2b-desktop" && target !== "e2b-terminal") {
-            return invalid("`execution.target` must be local, e2b-desktop, or e2b-terminal.");
+        if (target !== "local" &&
+            target !== "e2b-desktop" &&
+            target !== "e2b-terminal" &&
+            target !== "modal-terminal") {
+            return invalid("`execution.target` must be local, e2b-desktop, e2b-terminal, or modal-terminal.");
         }
         execution.target = target;
     }
@@ -34,6 +37,11 @@ export function parseExecution(raw) {
     }
     if (desktopResult.value)
         execution.desktop = desktopResult.value;
+    const network = parseNetwork(raw.network);
+    if (!network.ok)
+        return network;
+    if (network.value !== undefined)
+        execution.network = network.value;
     const terminalResult = parseTerminal(raw.terminal);
     if (!terminalResult.ok) {
         return terminalResult;
@@ -71,6 +79,30 @@ export function parseExecution(raw) {
     }
     return { ok: true, value: Object.keys(execution).length > 0 ? execution : undefined };
 }
+/** `execution.network`: true, false, or `{ origins }`. False reads as absent. */
+function parseNetwork(raw) {
+    if (raw === undefined || raw === false)
+        return { ok: true, value: undefined };
+    if (raw === true)
+        return { ok: true, value: true };
+    if (!isRecord(raw))
+        return invalid("`execution.network` must be true, false, or a mapping with `origins`: the origins whose requests are kept beside the target's.");
+    if (raw.origins === undefined)
+        return { ok: true, value: {} };
+    if (!Array.isArray(raw.origins) || raw.origins.length > 16)
+        return invalid("`execution.network.origins` must list at most 16 exact http(s) origins, such as https://api.example.com.");
+    const origins = [];
+    for (const entry of raw.origins) {
+        const origin = exactOrigin(entry);
+        if (origin === undefined)
+            return invalid("`execution.network.origins` accepts exact http(s) origins without credentials, path, query or fragment, such as https://api.example.com.");
+        // The network log's index records each origin, so one verify would flag is refused here.
+        if (scanEncodedText(origin).sensitive)
+            return invalid("`execution.network.origins` has an origin that looks like a secret or a local path, and the run records each origin in its network log index. List the origin of the API or asset host only.");
+        origins.push(origin);
+    }
+    return { ok: true, value: { origins: [...new Set(origins)] } };
+}
 function parseTerminal(raw) {
     if (raw === undefined) {
         return { ok: true, value: undefined };

package/dist/study/parse/values.d.ts

@@ -14,3 +14,8 @@ export declare function posInt(value: unknown): number | undefined;
 /** A non-negative finite number (0 allowed; caps default to 0 = no-spend). Accepts a numeric
  *  string too, since YAML scalars can arrive as strings. */
 export declare function nonNegNumber(value: unknown): number | undefined;
+/**
+ * The origin of an http(s) URL with no credentials, path, query or fragment, else undefined. The
+ * origin lists `comms.email.allowedOrigins` and `execution.network.origins` take this rule.
+ */
+export declare function exactOrigin(input: unknown): string | undefined;

package/dist/study/parse/values.js

@@ -60,3 +60,25 @@ export function nonNegNumber(value) {
     }
     return undefined;
 }
+/**
+ * The origin of an http(s) URL with no credentials, path, query or fragment, else undefined. The
+ * origin lists `comms.email.allowedOrigins` and `execution.network.origins` take this rule.
+ */
+export function exactOrigin(input) {
+    if (typeof input !== "string")
+        return undefined;
+    try {
+        const url = new URL(input);
+        return ["http:", "https:"].includes(url.protocol) &&
+            !url.username &&
+            !url.password &&
+            url.pathname === "/" &&
+            !url.search &&
+            !url.hash
+            ? url.origin
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}