humanish 0.116.0 → 0.118.0

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

@@ -2,8 +2,8 @@ import { shellQuote } from "../shell.js";
 import { perceptualSignature } from "../../evidence/frame-signature.js";
 import { commandFailureInfo } from "../command-failure.js";
 import { ComputerUseExecutorError } from "../../actors/computer-use/executor-error.js";
+import { CUA_WAIT_LIMITS } from "../../actors/computer-use/wait.js";
 import { xdotoolChord, xdotoolHeldModifiers } from "../../guest/desktop-keys.js";
-const DEFAULT_WAIT_MS = 500;
 const DEFAULT_SCROLL_AMOUNT_PER_TICK = 100;
 const TYPE_COMMAND_TIMEOUT_MS = 15_000;
 const KEY_COMMAND_TIMEOUT_MS = 15_000;
@@ -145,7 +145,6 @@ async function typeText(desktop, text) {
  * screenshot or action is ever logged.
  */
 export function createE2BDesktopExecutor(desktop, options = {}) {
-    const defaultWaitMs = options.defaultWaitMs ?? DEFAULT_WAIT_MS;
     const scrollAmountPerTick = options.scrollAmountPerTick ?? DEFAULT_SCROLL_AMOUNT_PER_TICK;
     return {
         async observe() {
@@ -258,7 +257,8 @@ export function createE2BDesktopExecutor(desktop, options = {}) {
                 return;
             }
             case "wait":
-                await desktop.wait(action.ms ?? defaultWaitMs);
+                // The loop sends every wait with its length; planWait owns the lengths.
+                await desktop.wait(action.ms ?? CUA_WAIT_LIMITS.settleMs);
                 return;
             case "screenshot":
                 // No-op: the loop calls observe() separately to capture each frame, so

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: {