humanish 0.117.0 → 0.118.0

package/dist/study/validation.js

@@ -1,15 +1,16 @@
 import { isMaxOutputTokens } from "../actors/output-token-limit.js";
+import { MAX_RECEIVING_INBOXES } from "../comms/receiving-types.js";
 import { waitFieldsReason } from "../actors/computer-use/wait.js";
 import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./parse/actors.js";
 import { isHttpUrl, isLoopbackUrl } from "./parse/subject.js";
 import { declaredTargets } from "./plan-participants.js";
-import { actorResolvesToComputerUse, computerUseParticipantCount, MAX_COMPUTER_USE_PARTICIPANTS, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
+import { actorResolvesToComputerUse, computerUseParticipantCount, participantCountReason, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
 import { participantList } from "./study-fields.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
  * message, or null when valid. The parser enforces it, and runStudyWith checks it again for a config
- * that skipped the parser. It runs rosterStructuralValidationReason (id and device
- * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
+ * that skipped the parser. It runs rosterStructuralValidationReason (roster size, id and device
+ * validity, unique ids) first, then the route-scoped XOR, participant count and policy checks.
  */
 export function computerUseValidationReason(config) {
     const roster = participantList(config);
@@ -42,9 +43,9 @@ export function computerUseValidationReason(config) {
         }
     }
     const participantCount = computerUseParticipantCount(config);
-    if (participantCount > MAX_COMPUTER_USE_PARTICIPANTS) {
-        return `A computer-use study runs at most ${MAX_COMPUTER_USE_PARTICIPANTS} participants, and this one declares ${participantCount}. Each participant is a paid desktop and they all run at once, so no setting raises the cap; split the roster across studies.`;
-    }
+    const countReason = participantCountReason(participantCount);
+    if (countReason)
+        return countReason;
     // Public targets fan out into N independent worlds driving the same public app, which is an
     // ambiguous shared-world-ish shape, not a per-participant target swarm. Permit N>1 public runs only
     // when every roster entry declares its own target, making the adapter-owned topology explicit. But when
@@ -60,8 +61,8 @@ export function computerUseValidationReason(config) {
     return null;
 }
 /**
- * Engine-level path-token validation for configs supplied directly through the
- * public TypeScript/JavaScript API instead of parseStudy.
+ * Engine-level roster validation (its size and its ids' path tokens) for configs supplied directly
+ * through the public TypeScript/JavaScript API instead of parseStudy.
  */
 function rosterStructuralValidationReason(config) {
     const roster = participantList(config);
@@ -70,6 +71,9 @@ function rosterStructuralValidationReason(config) {
         if (!Array.isArray(roster) || roster.length === 0) {
             return "participants must be a non-empty array when set.";
         }
+        const countReason = participantCountReason(roster.length);
+        if (countReason)
+            return countReason;
         for (const [index, entry] of roster.entries()) {
             if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
                 return `participants[${index}] must be an object.`;
@@ -195,6 +199,10 @@ export function receivingEmailValidationReason(config) {
         !["app-url", "clone", "local-tree"].includes(config.subject.source)) {
         return "Real email receiving requires a hosted computer-use browser study with an app-url, clone, or local-tree subject. Scripted, terminal, desktop-cli and local-app routes are unsupported.";
     }
+    const participants = computerUseParticipantCount(config);
+    if (participants > MAX_RECEIVING_INBOXES) {
+        return `Real email receiving leases one inbox per participant, at most ${MAX_RECEIVING_INBOXES} per run, and this study has ${participants} participants. Run at most ${MAX_RECEIVING_INBOXES} participants with a real inbox, or split them across studies.`;
+    }
     if (config.actor?.type === "local-agent") {
         return "Real email receiving is unavailable for local-agent: its host process does not isolate the inbox management credential. Use a hosted first-party computer-use actor.";
     }
@@ -245,14 +253,14 @@ export function waitLimitValidationReason(config) {
 }
 /**
  * Shared-world participants share one live app, so at least two must be live at once. The
- * sequential shared-world route (`execution.concurrency: 1`) was removed in 0.106.0; the parser
- * fills an omitted concurrency with the participant count. Both callers check it after their
- * two-participant roster floor, so a one-participant roster gets the roster refusal, never this
- * one.
+ * sequential shared-world route (`execution.concurrency: 1`) was removed in 0.106.0. An omitted
+ * concurrency runs every participant, up to the E2B plan's limit, which the planner checks. Both
+ * callers check it after their two-participant roster floor, so a one-participant roster gets the
+ * roster refusal, never this one.
  */
 function sharedWorldConcurrencyReason(config) {
-    // Direct library callers skip the parser, so an omitted value defaults here exactly as the
-    // route does: to the participant count. A missing roster reads as 0 and is refused.
+    // An omitted value runs every participant, so it is checked as the participant count. A missing
+    // roster reads as 0 and is refused.
     const participants = participantList(config)?.length ?? 0;
     const concurrency = config.execution?.concurrency ?? participants;
     if (concurrency >= 2)

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

@@ -24,9 +24,80 @@ export declare function describeSandboxCeiling(ceiling: SandboxCeiling): string;
  * setting value that would admit it, when an E2B plan allows that long.
  */
 export declare function ceilingAdvice(deadlineMs: number): string;
-/** Server-side reclamation buffer past a participant's own wall-clock stop. */
-export declare const SANDBOX_TIMEOUT_BUFFER_MS: number;
-/** Room a provisioned subject adds to the sandbox deadline for clone, install, build, start and probe. */
-export declare const SUBJECT_PROVISION_BUDGET_MS: number;
+/**
+ * How many sandboxes humanish runs at once, and whether it is the default or the setting; or why
+ * the setting cannot be read.
+ */
+export type ConcurrentSandboxes = {
+    readonly ok: true;
+    readonly count: number;
+    readonly source: "default" | "setting";
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * The concurrent sandbox limit: HUMANISH_E2B_MAX_CONCURRENT_SANDBOXES when set, else 20. E2B
+ * refuses a create past the plan's limit, and neither its API nor its SDK says which plan a key is
+ * on, so the operator states it, as for the sandbox ceiling. A study that would run more desktops
+ * at once is refused or run in waves at plan time, before a create fails mid-run.
+ */
+export declare function concurrentSandboxes(env: Readonly<Record<string, string | undefined>>): ConcurrentSandboxes;
+/** The limit in use and where it came from, or why the setting cannot be read (doctor's row). */
+export declare function describeConcurrentSandboxes(limit: ConcurrentSandboxes): string;
+/**
+ * How many participants a hosted study runs at once: its `concurrency` (the declared
+ * execution.concurrency clamped to the roster, else every participant), lowered to what the plan
+ * runs. `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps
+ * for the whole run besides its participants' desktops, such as a shared world's app, and
+ * `minimum` is the fewest at once the route can run. A declared value that does not fit is a
+ * refusal naming the setting value that admits it. `lowered` is the warning a plan records when
+ * the limit holds an undeclared default to waves.
+ */
+export declare function participantsAtOnce(study: {
+    readonly concurrency: number;
+    readonly declared: boolean;
+    readonly participants: number;
+    readonly alongside?: number;
+    readonly minimum?: number;
+}, limit: ConcurrentSandboxes): {
+    readonly ok: true;
+    readonly count: number;
+    readonly lowered?: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * What a sandbox's server-side timeout adds to the session it hosts: the teardown buffer, and on a
+ * sandbox that serves the subject, the provisioning budget and each seed step's budget. A planner
+ * adds it to the session to get the deadline it checks against the ceiling, and the route adds it
+ * to set the timeout it asks E2B for.
+ */
+export declare function sandboxHeadroomMs(servedSubject?: {
+    readonly seed: readonly {
+        readonly timeoutMs?: number | undefined;
+    }[];
+}): number;
+/** A sandbox a plan will ask E2B for, as its deadline refusal describes it. */
+export interface PlannedSandbox {
+    /** How the refusal names the sandbox, as in "the subject sandbox". */
+    readonly name: string;
+    /** The session it hosts, and whether the study set it in execution.timeoutMs. */
+    readonly sessionMs: number;
+    readonly sessionDeclared: boolean;
+    /** The subject it serves, whose provisioning and seed steps add to its deadline. */
+    readonly servedSubject?: {
+        readonly seed: readonly {
+            readonly timeoutMs?: number | undefined;
+        }[];
+    } | undefined;
+}
+/**
+ * Why the sandbox's deadline, its session plus sandboxHeadroomMs, passes the `ceilingMs` ceiling,
+ * or undefined when it fits. The message shows the arithmetic, the longest execution.timeoutMs the
+ * ceiling leaves, and the setting value that would admit the study.
+ */
+export declare function sandboxDeadlineRefusal(sandbox: PlannedSandbox, ceilingMs: number): string | undefined;
 /** The timeout of one E2B API request: HUMANISH_E2B_REQUEST_TIMEOUT_MS when set, else 60 s. */
 export declare function e2bRequestTimeoutMs(env: Record<string, string | undefined>): number;

package/dist/substrates/e2b/lifetime.js

@@ -1,7 +1,10 @@
-// How long an E2B sandbox may live, and the budgets the desktop routes add to a participant's own
-// deadline when they set a sandbox's server-side timeout. A dead host process can never orphan a
-// sandbox past that timeout, so every route derives it from these values.
+// The operator's E2B plan limits humanish plans against: how long a sandbox may live and how many
+// run at once. Also the budgets the desktop routes add to a participant's own deadline when they set
+// a sandbox's server-side timeout. A dead host process can never orphan a sandbox past that
+// timeout, so every route derives it from these values.
+import { plural } from "../../run/text.js";
 import { readPositiveInt } from "../../study/parse/values.js";
+import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
 /** The setting that tells humanish how long the operator's E2B plan lets a sandbox live. */
 const SANDBOX_CEILING_SETTING = "HUMANISH_E2B_MAX_SANDBOX_MINUTES";
 /** E2B's Hobby plan ends a sandbox after 1 hour, so a key on any plan can use this ceiling. */
@@ -15,17 +18,27 @@ const LARGEST_CEILING_MINUTES = 24 * 60;
  * to stay under the ceiling, and saying so at plan time beats a provider 400 after the plan printed.
  */
 export function sandboxCeiling(env) {
-    const declared = env[SANDBOX_CEILING_SETTING]?.trim() ?? "";
-    if (declared === "")
+    const minutes = planSetting(env, SANDBOX_CEILING_SETTING, LARGEST_CEILING_MINUTES);
+    if (minutes === undefined)
         return { ok: true, ms: DEFAULT_CEILING_MINUTES * 60_000, source: "default" };
-    const minutes = /^\d+$/.test(declared) ? Number.parseInt(declared, 10) : Number.NaN;
-    if (!(minutes >= 1 && minutes <= LARGEST_CEILING_MINUTES))
+    if (typeof minutes === "string")
         return {
             ok: false,
-            message: `${SANDBOX_CEILING_SETTING} must be a whole number of minutes from 1 to ${LARGEST_CEILING_MINUTES} (got "${declared.slice(0, 40)}"). Set it to the sandbox lifetime your E2B plan allows: ${DEFAULT_CEILING_MINUTES} on Hobby, ${LARGEST_CEILING_MINUTES} on Pro. Unset, it is ${DEFAULT_CEILING_MINUTES}.`,
+            message: `${SANDBOX_CEILING_SETTING} must be a whole number of minutes from 1 to ${LARGEST_CEILING_MINUTES} (got "${minutes}"). Set it to the sandbox lifetime your E2B plan allows: ${DEFAULT_CEILING_MINUTES} on Hobby, ${LARGEST_CEILING_MINUTES} on Pro. Unset, it is ${DEFAULT_CEILING_MINUTES}.`,
         };
     return { ok: true, ms: minutes * 60_000, source: "setting" };
 }
+/**
+ * A plan setting's whole number from 1 to `largest`: undefined when unset or blank, else the
+ * number, else the value as given (cut to 40 characters) for the refusal to quote.
+ */
+function planSetting(env, name, largest) {
+    const declared = env[name]?.trim() ?? "";
+    if (declared === "")
+        return undefined;
+    const value = /^\d+$/.test(declared) ? Number.parseInt(declared, 10) : Number.NaN;
+    return value >= 1 && value <= largest ? value : declared.slice(0, 40);
+}
 /** The ceiling in use and where it came from, or why the setting cannot be read (doctor's row). */
 export function describeSandboxCeiling(ceiling) {
     if (!ceiling.ok)
@@ -45,10 +58,121 @@ export function ceilingAdvice(deadlineMs) {
         ? ` If your E2B plan allows longer sandboxes (Pro allows ${LARGEST_CEILING_MINUTES} minutes), set ${SANDBOX_CEILING_SETTING} to ${needed} or more.`
         : ` No E2B plan humanish knows allows a sandbox past ${LARGEST_CEILING_MINUTES} minutes.`;
 }
+/** The setting that tells humanish how many sandboxes the operator's E2B plan runs at once. */
+const CONCURRENCY_SETTING = "HUMANISH_E2B_MAX_CONCURRENT_SANDBOXES";
+/** E2B's Hobby plan runs 20 sandboxes at once, so a key on any plan can use this limit. */
+const DEFAULT_CONCURRENT_SANDBOXES = 20;
+/** E2B's Pro plan runs 100 at once, and add-ons raise it to 1,100. */
+const PRO_CONCURRENT_SANDBOXES = 100;
+/** Enterprise plans run tens of thousands; the setting refuses only a value no plan could mean. */
+const LARGEST_CONCURRENT_SANDBOXES = 1_000_000;
+/**
+ * The concurrent sandbox limit: HUMANISH_E2B_MAX_CONCURRENT_SANDBOXES when set, else 20. E2B
+ * refuses a create past the plan's limit, and neither its API nor its SDK says which plan a key is
+ * on, so the operator states it, as for the sandbox ceiling. A study that would run more desktops
+ * at once is refused or run in waves at plan time, before a create fails mid-run.
+ */
+export function concurrentSandboxes(env) {
+    const count = planSetting(env, CONCURRENCY_SETTING, LARGEST_CONCURRENT_SANDBOXES);
+    if (count === undefined)
+        return { ok: true, count: DEFAULT_CONCURRENT_SANDBOXES, source: "default" };
+    if (typeof count === "string")
+        return {
+            ok: false,
+            message: `${CONCURRENCY_SETTING} must be a whole number of 1 or more (got "${count}"). Set it to how many sandboxes your E2B plan runs at once: ${DEFAULT_CONCURRENT_SANDBOXES} on Hobby, ${PRO_CONCURRENT_SANDBOXES} on Pro. Unset, it is ${DEFAULT_CONCURRENT_SANDBOXES}.`,
+        };
+    return { ok: true, count, source: "setting" };
+}
+/** The limit in use and where it came from, or why the setting cannot be read (doctor's row). */
+export function describeConcurrentSandboxes(limit) {
+    if (!limit.ok)
+        return limit.message;
+    return limit.source === "setting"
+        ? `${limit.count} at once, from ${CONCURRENCY_SETTING}. A study that runs more desktops at once runs them in waves, and an execution.concurrency above it is refused before any sandbox is created.`
+        : `${limit.count} at once, E2B's Hobby limit. On a plan that runs more (Pro runs ${PRO_CONCURRENT_SANDBOXES}), set ${CONCURRENCY_SETTING} to that plan's limit.`;
+}
+/**
+ * How many participants a hosted study runs at once: its `concurrency` (the declared
+ * execution.concurrency clamped to the roster, else every participant), lowered to what the plan
+ * runs. `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps
+ * for the whole run besides its participants' desktops, such as a shared world's app, and
+ * `minimum` is the fewest at once the route can run. A declared value that does not fit is a
+ * refusal naming the setting value that admits it. `lowered` is the warning a plan records when
+ * the limit holds an undeclared default to waves.
+ */
+export function participantsAtOnce(study, limit) {
+    if (!limit.ok)
+        return limit;
+    const alongside = study.alongside ?? 0;
+    const minimum = study.minimum ?? 1;
+    const room = limit.count - alongside;
+    const needed = Math.max(study.concurrency, minimum) + alongside;
+    const raise = ` If your E2B plan runs more (Pro runs ${PRO_CONCURRENT_SANDBOXES}), set ${CONCURRENCY_SETTING} to ${needed} or more.`;
+    const app = alongside === 0
+        ? ""
+        : ` beside the ${plural(alongside, "sandbox", "sandboxes")} the study keeps for its app`;
+    if (room < minimum)
+        return {
+            ok: false,
+            message: `This study runs at least ${minimum} participants at once${app}, and ${limitText(limit)}.${raise}`,
+        };
+    if (study.concurrency <= room)
+        return { ok: true, count: study.concurrency };
+    if (study.declared)
+        return {
+            ok: false,
+            message: `execution.concurrency runs ${study.concurrency} participants at once${app}, and ${limitText(limit)}. Lower execution.concurrency to ${room} or less, or remove it to run ${room} at a time.${raise}`,
+        };
+    return {
+        ok: true,
+        count: room,
+        lowered: `This study's ${study.participants} participants run ${room} at a time${app}, because ${limitText(limit)}.${raise}`,
+    };
+}
+function limitText(limit) {
+    return limit.source === "setting"
+        ? `${CONCURRENCY_SETTING} allows ${limit.count} sandboxes at once`
+        : `humanish runs at most ${limit.count} sandboxes at once, E2B Hobby's limit, when ${CONCURRENCY_SETTING} is unset`;
+}
 /** Server-side reclamation buffer past a participant's own wall-clock stop. */
-export const SANDBOX_TIMEOUT_BUFFER_MS = 10 * 60_000;
+const SANDBOX_TIMEOUT_BUFFER_MS = 10 * 60_000;
 /** Room a provisioned subject adds to the sandbox deadline for clone, install, build, start and probe. */
-export const SUBJECT_PROVISION_BUDGET_MS = 30 * 60_000;
+const SUBJECT_PROVISION_BUDGET_MS = 30 * 60_000;
+/**
+ * What a sandbox's server-side timeout adds to the session it hosts: the teardown buffer, and on a
+ * sandbox that serves the subject, the provisioning budget and each seed step's budget. A planner
+ * adds it to the session to get the deadline it checks against the ceiling, and the route adds it
+ * to set the timeout it asks E2B for.
+ */
+export function sandboxHeadroomMs(servedSubject) {
+    if (servedSubject === undefined)
+        return SANDBOX_TIMEOUT_BUFFER_MS;
+    const seedMs = servedSubject.seed.reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0);
+    return SUBJECT_PROVISION_BUDGET_MS + seedMs + SANDBOX_TIMEOUT_BUFFER_MS;
+}
+/**
+ * Why the sandbox's deadline, its session plus sandboxHeadroomMs, passes the `ceilingMs` ceiling,
+ * or undefined when it fits. The message shows the arithmetic, the longest execution.timeoutMs the
+ * ceiling leaves, and the setting value that would admit the study.
+ */
+export function sandboxDeadlineRefusal(sandbox, ceilingMs) {
+    const headroomMs = sandboxHeadroomMs(sandbox.servedSubject);
+    const deadlineMs = sandbox.sessionMs + headroomMs;
+    if (deadlineMs <= ceilingMs)
+        return undefined;
+    const inMinutes = (ms) => Math.round(ms / 60_000);
+    const session = sandbox.sessionDeclared
+        ? `execution.timeoutMs ${inMinutes(sandbox.sessionMs)}m`
+        : `The default session budget of ${inMinutes(sandbox.sessionMs)}m`;
+    const headroom = sandbox.servedSubject === undefined
+        ? `${inMinutes(headroomMs)}m of teardown buffer`
+        : `${inMinutes(headroomMs)}m to provision and seed the subject and tear it down`;
+    const roomMinutes = Math.floor((ceilingMs - headroomMs) / 60_000);
+    const lower = roomMinutes >= 1
+        ? `Lower execution.timeoutMs to at most ${roomMinutes}m.`
+        : "The provisioning and seed step budgets alone leave no session time under it, so shorten subject.state.seed[].timeoutMs.";
+    return `${session} derives a ${inMinutes(deadlineMs)}m deadline for ${sandbox.name}, and a sandbox may not live longer than ${ceilingMs / 60_000}m. The deadline is the session budget plus ${headroom}. ${lower}${ceilingAdvice(deadlineMs)}`;
+}
 /** The timeout of one E2B API request: HUMANISH_E2B_REQUEST_TIMEOUT_MS when set, else 60 s. */
 export function e2bRequestTimeoutMs(env) {
     return readPositiveInt(env.HUMANISH_E2B_REQUEST_TIMEOUT_MS, 60_000);

package/dist/substrates/e2b/subject-sandbox.js

@@ -4,9 +4,8 @@
 // reading is one edit. What runs inside the sandbox (the caller's prepare hook, provisioning,
 // getHost) stays with each route.
 import { redactText } from "../../evidence/redaction.js";
-import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
 import { observeDesktopResources } from "./desktop-resources.js";
-import { SANDBOX_TIMEOUT_BUFFER_MS, SUBJECT_PROVISION_BUDGET_MS } from "./lifetime.js";
+import { sandboxHeadroomMs } from "./lifetime.js";
 import { acquireE2BDesktopSandbox, readE2BRelease } from "./sandbox.js";
 export class E2BSubjectSandbox {
     sandboxId;
@@ -28,10 +27,7 @@ export class E2BSubjectSandbox {
     async acquire(request) {
         const { envs } = request;
         const { warnings, scrub } = this.run;
-        const timeoutMs = request.sessionTimeoutMs +
-            SUBJECT_PROVISION_BUDGET_MS +
-            request.seed.reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0) +
-            SANDBOX_TIMEOUT_BUFFER_MS;
+        const timeoutMs = request.sessionTimeoutMs + sandboxHeadroomMs({ seed: request.seed });
         const subject = await acquireE2BDesktopSandbox({
             module: request.module,
             options: {