humanish 0.116.0 → 0.118.0

package/CHANGELOG.md

@@ -8,6 +8,46 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.118.0: Up to 100 participants, E2B concurrent sandboxes, study check plans like run, analysis range (2026-10-09)
+
+humanish 0.118.0 lets a computer-use study have up to 100 participants, up from 16, holds a
+shared-world study to the same 100, and runs them within the number of sandboxes the E2B plan runs
+at once. The new setting `HUMANISH_E2B_MAX_CONCURRENT_SANDBOXES` gives that number (20 when unset,
+E2B Hobby's limit; Pro runs 100). A study with more participants than that runs them in waves, an
+`execution.concurrency` above it is refused before any sandbox is created, and `doctor` shows it. A
+live run of more than 16 participants records its automatic analysis as skipped with
+`AUTOMATIC_ANALYSIS_PARTICIPANT_LIMIT`, because one analysis reads at most 16 participants. `study
+check` now plans a study the way `humanish run` does and fails a study the run refuses, and a
+shared-world or scripted clone study whose sandbox deadline passes the ceiling is refused at plan
+time. The analysis line that `run`, `study check` and the TUI print ends its expected range at the
+largest run admission admits (`$0.75 to $2.83` for one participant at the default $3 cap, where it
+read `$3.79`) and states the rule as admission applies it. An in-process `local-app` run records
+`subject.source: local-app`, a desktop-cli dry run names its product, and `verify` names an unlisted
+folder and the 10,000-entry stop in their own sentences. In `humanish tui`, the key legend says what
+Enter and Esc do while an action is armed, a study's median cost includes its analyses, and Esc
+after entering a key returns to the screen the keys were opened from.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.118.0)
+
+## 0.117.0: Long participant waits, OpenAI wait length, serve.build fails fast, TUI confirmations (2026-10-09)
+
+humanish 0.117.0 lets a participant wait through a long hosted study, gives an OpenAI
+participant's wait a usable length, and fails a broken `serve.build` within seconds. A
+participant's wait longer than one desktop call now lasts as long as it asked, up to the new study
+field `actor.maxWaitMs` (1 second to 10 minutes; 2 minutes by default, 30 seconds on a desktop with
+speech), and goes to the desktop in steps of at most 30 seconds. A Codex participant's longer wait
+was cut to 30 seconds before. An `openai-computer-use` participant's `wait` names no duration and
+lasted half a second on a hosted desktop; it now lasts `actor.idleWaitMs` (5 seconds by default) in
+a turn that only waits, and 500 ms after an action in the same turn. The participant's `actor.json`
+records these lengths as `waitSettings`. A `serve.install`, `serve.build` or seed step that bash
+cannot parse fails within seconds with bash's error, where the run waited out the step's limit (10
+minutes for `serve.build`), and a failed `serve.build` on the computer-use route has its own error
+code. In `humanish tui`, a two-Enter confirmation ends when the cursor leaves it. The terminal
+route's check after its sandbox kill carries the run's E2B key, and browser Back in the Observer
+clears a stale saved-moment message.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.117.0)
+
 ## 0.116.0: Hosted keyboard input, E2B sandbox ceiling, bounded run reads, run header, TUI live starts (2026-10-09)
 
 humanish 0.116.0 delivers a hosted participant's arrow keys and punctuation, lets the operator

package/dist/actors/codex/restricted-participant-policy.d.ts

@@ -10,8 +10,6 @@ export declare const PARTICIPANT_LIMITS: Readonly<{
     narration: 2000;
     output: number;
     actions: 4;
-    /** The longest wait one action lasts; a longer one is shortened to it. */
-    waitMs: 30000;
     requestMs: 180000;
     cleanupMs: 5000;
 }>;

package/dist/actors/codex/restricted-participant-policy.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { BROWSER_CONTROL_LIMITS, browserControlActionSchema, browserOnlyControlActionSchema, validateBrowserControlAction, } from "../../browser-control/protocol.js";
+import { participantActionSchema, participantSpeechActionSchema, } from "../../browser-control/protocol.js";
 import { closingReportSchema, strictOutputSchema, } from "../closing-report.js";
 /** The declared profile. A participant replaces cliVersion with its detected CLI release, or with
  * this host's newest qualified release before its first launch. */
@@ -21,15 +21,13 @@ export const PARTICIPANT_LIMITS = Object.freeze({
     narration: 2000,
     output: 256 * 1024,
     actions: 4,
-    /** The longest wait one action lasts; a longer one is shortened to it. */
-    waitMs: BROWSER_CONTROL_LIMITS.waitMs,
     requestMs: 180_000,
     cleanupMs: 5000,
 });
 const toolInput = (speechEnabled) => z.strictObject({
     narration: z.string().max(PARTICIPANT_LIMITS.narration),
     actions: z
-        .array(speechEnabled ? browserControlActionSchema : browserOnlyControlActionSchema)
+        .array(speechEnabled ? participantSpeechActionSchema : participantActionSchema)
         .min(1)
         .max(PARTICIPANT_LIMITS.actions),
 });
@@ -43,41 +41,15 @@ const participantFinal = z.strictObject({
     ...closingReportSchema.shape,
 });
 export const PARTICIPANT_FINAL_SCHEMA = strictOutputSchema(participantFinal);
-/**
- * Shorten each wait longer than one browser-control request may wait. A failed tool call ends the
- * native run, so a wait that asks too much would otherwise end the whole session.
- */
-function shortenWaits(value) {
-    const actions = value?.actions;
-    if (typeof value !== "object" || !Array.isArray(actions))
-        return { value, shortened: [] };
-    const shortened = [];
-    const limit = PARTICIPANT_LIMITS.waitMs;
-    const next = actions.map((action, index) => {
-        const wait = action;
-        if (wait?.kind !== "wait" ||
-            typeof wait.ms !== "number" ||
-            !Number.isFinite(wait.ms) ||
-            wait.ms <= limit)
-            return action;
-        shortened.push({ index, requestedMs: wait.ms, ms: limit });
-        return { ...wait, ms: limit };
-    });
-    return shortened.length === 0
-        ? { value, shortened }
-        : { value: { ...value, actions: next }, shortened };
-}
 /** humanish tool arguments, validated before the shared executor sees a batch. */
 export function parseParticipantTool(value, speechEnabled = false) {
     if (Buffer.byteLength(JSON.stringify(value) ?? "") > PARTICIPANT_LIMITS.output)
         throw new Error("invalid_response");
-    const { value: admitted, shortened } = shortenWaits(value);
-    const v = toolInput(speechEnabled).parse(admitted);
+    const v = toolInput(speechEnabled).parse(value);
     if (Buffer.byteLength(v.narration) > PARTICIPANT_LIMITS.narration)
         throw new Error("invalid_response");
     return {
-        actions: v.actions.map(validateBrowserControlAction),
-        ...(shortened.length === 0 ? {} : { shortenedWaits: shortened }),
+        actions: v.actions,
         pendingSafetyChecks: [],
         done: false,
         ...(v.narration ? { message: v.narration } : {}),

package/dist/actors/codex/restricted-participant.d.ts

@@ -17,6 +17,11 @@ export interface RestrictedParticipantOptions {
     reasoningEffort?: ReasoningEffort;
     /** Admit speech actions and heard-speaker evidence for a speech-capable desktop only. */
     speechEnabled?: boolean;
+    /**
+     * The study's actor.maxWaitMs, which the loop applies and the tool description states. Default
+     * defaultMaxWaitMs(speechEnabled), the same default the loop applies.
+     */
+    maxWaitMs?: number;
 }
 /** What doctor's hosted-participant check found, before any turn. */
 export interface ParticipantReadiness {

package/dist/actors/codex/restricted-participant.js

@@ -3,6 +3,7 @@ import { defaultCodexCliVersion, untestedOperatorReleaseWarning } from "./codex-
 import { IMPRESSIONS_ASK, } from "../computer-use/loop.js";
 import { ComputerUseProviderError, isComputerUseProviderError, } from "../computer-use/provider-error.js";
 import { validateBrowserControlPng, validateHeardSpeech } from "../../browser-control/protocol.js";
+import { defaultMaxWaitMs } from "../computer-use/wait.js";
 import { createRestrictedCodexSession, } from "./restricted-session.js";
 import { PARTICIPANT_PROFILE, PARTICIPANT_LIMITS as L, PARTICIPANT_FINAL_SCHEMA, participantToolSchema, parseParticipantTool, parseParticipantFinal, } from "./restricted-participant-policy.js";
 import { truncatedFrameWarning, unknownNotificationsWarning } from "./restricted-notifications.js";
@@ -40,7 +41,7 @@ function deferred() {
     return { promise, resolve, reject };
 }
 // prose-check: model prompt (Codex reads this tool description, not a person)
-const toolDescription = (speechEnabled) => `Act on the participant's browser through humanish. Submit one to four UI actions${speechEnabled ? ", including speak when you need to reply aloud," : ""} and a short public comment; never private reasoning. humanish returns a JSON STRING with execution acknowledgments${speechEnabled ? ", speech heard from the actual participant speaker sink," : ""} and a fresh screenshot. In Code Mode use: const r = JSON.parse(await tools.humanish_ui({narration: "...", actions: [...]})); text({acknowledgments: r.acknowledgments${speechEnabled ? ", heardSpeech: r.heardSpeech" : ""}, contextHint: r.contextHint, closing: r.closing}); image(r.imageUrl). Call serially and inspect each returned screenshot${speechEnabled ? " and heardSpeech array" : ""} before deciding what to do next. A wait action lasts at most ${L.waitMs} ms; a longer wait is shortened to ${L.waitMs} ms, so wait longer with another call.${speechEnabled ? " Use speak only after the visible UI shows that you joined the call and your microphone is unmuted; it sends audio into that call." : ""} Acknowledged input does not prove an application outcome. If closing is true, stop calling tools and give your final account.`;
+const toolDescription = (speechEnabled, maxWaitMs) => `Act on the participant's browser through humanish. Submit one to four UI actions${speechEnabled ? ", including speak when you need to reply aloud," : ""} and a short public comment; never private reasoning. humanish returns a JSON STRING with execution acknowledgments${speechEnabled ? ", speech heard from the actual participant speaker sink," : ""} and a fresh screenshot. In Code Mode use: const r = JSON.parse(await tools.humanish_ui({narration: "...", actions: [...]})); text({acknowledgments: r.acknowledgments${speechEnabled ? ", heardSpeech: r.heardSpeech" : ""}, contextHint: r.contextHint, closing: r.closing}); image(r.imageUrl). Call serially and inspect each returned screenshot${speechEnabled ? " and heardSpeech array" : ""} before deciding what to do next. A wait action lasts at most ${maxWaitMs} ms; a longer wait is shortened to ${maxWaitMs} ms, so wait longer with another call.${speechEnabled ? " Use speak only after the visible UI shows that you joined the call and your microphone is unmuted; it sends audio into that call." : ""} Acknowledged input does not prove an application outcome. If closing is true, stop calling tools and give your final account.`;
 const participantInstructions = (prompt, speechEnabled) => `${prompt}\n\nYou are the study participant throughout this conversation, including its closing account. Use only the supplied screenshots and humanish_ui tool to interact. The tool returns a JSON string: parse it, inspect acknowledgments${speechEnabled ? " and heardSpeech captured from the actual participant speaker sink" : ""}, and display imageUrl with Code Mode image(). Do not print the image data URL as text. Keep your persona and earlier observations throughout the session.${speechEnabled ? " A speak action plays into the participant microphone; use it only after the visible UI shows that you joined the call and the microphone is unmuted." : ""} Speak publicly about your experience, never reveal private reasoning. Completed inputs do not prove application outcomes; verify on the next screenshot. When the task ends, return only the required final JSON with outcome, summary, frictionReports and impressions. Report observed confusion and recovered mistakes as well as blockers. ${IMPRESSIONS_ASK} Do not invent observations.`;
 /** Turns and failures from the native run, handed in order to the next provider request. */
 class ParticipantEvents {
@@ -191,7 +192,7 @@ function participantSession(options, speechEnabled, effort, call) {
             reasoningEffort: effort,
             tool: {
                 name: "humanish_ui",
-                description: toolDescription(speechEnabled),
+                description: toolDescription(speechEnabled, options.maxWaitMs ?? defaultMaxWaitMs(speechEnabled)),
                 inputSchema: participantToolSchema(speechEnabled),
                 call,
             },

package/dist/actors/computer-use/actor.d.ts

@@ -38,6 +38,10 @@ export interface CuaActorSessionOptions {
     acknowledgeSafetyChecks?: (checks: CuaSafetyCheck[]) => CuaSafetyCheck[] | null;
     idleSteps?: number;
     noProgressSteps?: number;
+    /** The longest one wait action lasts, forwarded to the loop. See LoopRunOptions.maxWaitMs. */
+    maxWaitMs?: number;
+    /** How long a wait with no duration lasts in an idle turn. See LoopRunOptions.idleWaitMs. */
+    idleWaitMs?: number;
     /**
      * Redact persisted screenshots (blur+downscale). Default `false`: full fidelity for local use.
      * Set true for unowned subjects or share-as-is bundles. The provider always sees raw frames.

package/dist/actors/computer-use/actor.js

@@ -31,6 +31,8 @@ export async function runCuaActorSession(options) {
         ...(options.signal === undefined ? {} : { signal: options.signal }),
         ...(options.idleSteps === undefined ? {} : { idleSteps: options.idleSteps }),
         ...(options.noProgressSteps === undefined ? {} : { noProgressSteps: options.noProgressSteps }),
+        ...(options.maxWaitMs === undefined ? {} : { maxWaitMs: options.maxWaitMs }),
+        ...(options.idleWaitMs === undefined ? {} : { idleWaitMs: options.idleWaitMs }),
         ...(options.acknowledgeSafetyChecks === undefined
             ? {}
             : { acknowledgeSafetyChecks: options.acknowledgeSafetyChecks }),

package/dist/actors/computer-use/loop/actions.d.ts

@@ -1,5 +1,5 @@
 import type { LoopSession } from "./session.js";
-import type { CuaAction, CuaTurnRequest, ShortenedWait } from "./types.js";
+import type { CuaAction, CuaTurnRequest } from "./types.js";
 /** A public-safe one-line action label. Never includes raw typed text. */
 export declare function describeCuaAction(action: CuaAction): string;
 /**
@@ -16,8 +16,8 @@ export interface ActionBatch {
     /** Host input acknowledgements for the provider's next request. */
     readonly execution: NonNullable<CuaTurnRequest["previousExecution"]>;
     /**
-     * Guidance for the next request, set when the provider shortened a wait or a pre-dispatch
-     * rejection stopped the batch.
+     * Guidance for the next request, set when the loop shortened a wait or a pre-dispatch rejection
+     * stopped the batch.
      */
     readonly hint: string | undefined;
 }
@@ -26,4 +26,4 @@ export interface ActionBatch {
  * leaves the desktop usable; a failed desktop command skips its action; any other failure ends
  * the session.
  */
-export declare function runActionBatch(session: LoopSession, actions: readonly CuaAction[], shortenedWaits?: readonly ShortenedWait[]): Promise<ActionBatch>;
+export declare function runActionBatch(session: LoopSession, actions: readonly CuaAction[]): Promise<ActionBatch>;

package/dist/actors/computer-use/loop/actions.js

@@ -3,6 +3,7 @@ import { commandFailureInfo, isCommandExitError } from "../../../substrates/comm
 import { ComputerUseExecutorError, isComputerUseExecutorError, } from "../executor-error.js";
 import { CuaAbortError, CuaDeadlineError, CuaStallError, raceCallBound, raceSessionDeadline, requestScope, } from "./race.js";
 import { notice } from "./trace.js";
+import { planWait } from "../wait.js";
 // The participant's actions: their public labels, what counts as a material action, and how one
 // turn's batch is dispatched to the desktop.
 /** Click/scroll coordinates are bucketed to this many pixels before fingerprinting, so a one-pixel
@@ -109,31 +110,31 @@ function rejectedActionHint(title, reason) {
     const remedy = reason === undefined ? "" : ` ${REJECTION_REMEDIES[reason]}`;
     return `Your action (${title}) was rejected before dispatch. No input from that action or the rest of its batch was sent.${remedy} Choose your next action from the fresh screenshot; do not assume the rejected action succeeded.`;
 }
-function shortenedWaitHint(wait) {
-    return `Your wait of ${wait.requestedMs}ms was shortened to ${wait.ms}ms, the longest one wait action lasts. To keep waiting, send another wait.`;
-}
-/** Record a wait the provider shortened, and return the participant's note about it. */
-function recordShortenedWait(session, title, wait) {
-    session.trace.record("notice", () => notice("warn", "wait shortened", `action: ${title}; requested: ${wait.requestedMs}ms; waited: ${wait.ms}ms, the longest one wait action lasts; the session continued`));
-    return shortenedWaitHint(wait);
+/** Record a wait the loop shortened, and return the participant's note about it. */
+function recordShortenedWait(session, title, requestedMs) {
+    const ms = session.waits.maxWaitMs;
+    session.trace.record("notice", () => notice("warn", "wait shortened", `action: ${title}; requested: ${requestedMs}ms; waited: ${ms}ms, the longest one wait action lasts (actor.maxWaitMs); the session continued`));
+    return `Your wait of ${requestedMs}ms was shortened to ${ms}ms, the longest one wait action lasts. To keep waiting, send another wait.`;
 }
 /**
  * Dispatch one turn's actions in order. A declared pre-dispatch rejection stops the batch and
  * leaves the desktop usable; a failed desktop command skips its action; any other failure ends
  * the session.
  */
-export async function runActionBatch(session, actions, shortenedWaits = []) {
+export async function runActionBatch(session, actions) {
     const execution = { actions: [] };
     const { actionHistory, trace } = session;
     const notes = [];
     const hint = () => (notes.length === 0 ? undefined : notes.join(" "));
-    for (const [index, action] of actions.entries()) {
+    const idleTurn = isIdleTurn(actions);
+    for (const [index, requested] of actions.entries()) {
         if (session.signal?.aborted)
             throw new CuaAbortError();
+        const wait = requested.kind === "wait" ? planWait(session.waits, requested.ms, idleTurn) : undefined;
+        const action = wait === undefined ? requested : { kind: "wait", ms: wait.ms };
         const title = describeCuaAction(action);
-        const shortened = shortenedWaits.find((wait) => wait.index === index);
-        if (shortened !== undefined)
-            notes.push(recordShortenedWait(session, title, shortened));
+        if (wait?.shortenedFromMs !== undefined)
+            notes.push(recordShortenedWait(session, title, wait.shortenedFromMs));
         actionHistory.lastActionTitle = title;
         actionHistory.recentActionTitles.push(title);
         if (actionHistory.recentActionTitles.length > RECENT_ACTION_TITLES)
@@ -146,7 +147,7 @@ export async function runActionBatch(session, actions, shortenedWaits = []) {
         session.phase = `executing ${title}`;
         let status;
         try {
-            status = await dispatchAction(session, action, title);
+            status = await dispatchAction(session, action, title, wait?.steps);
         }
         catch (error) {
             const declared = isComputerUseExecutorError(error)
@@ -201,17 +202,23 @@ function countAttempt(session, action, title, status) {
 }
 /**
  * Execute one action. Idle actions only look: a `wait` that hangs inside the SDK has in
- * effect waited, so a stalled one is skipped with a notice and loses nothing the participant
- * chose. An action is recorded as completed only after execute() resolves.
+ * effect waited, so a stalled one is skipped with a notice, its remaining steps are not sent, and
+ * it loses nothing the participant chose. An action is recorded as completed only after every
+ * desktop call it takes resolves. A wait is sent as `waitSteps`, its planWait steps.
  */
-async function dispatchAction(session, action, title) {
+async function dispatchAction(session, action, title, waitSteps) {
     if (!isIdleAction(action)) {
         await executeAction(session, action, title);
         return "completed";
     }
-    const boundMs = session.observationTimeoutMs + (action.kind === "wait" ? (action.ms ?? 0) : 0);
+    const calls = waitSteps?.map((ms) => ({ kind: "wait", ms })) ?? [action];
     try {
-        await executeAction(session, action, title, boundMs);
+        for (const call of calls) {
+            if (session.signal?.aborted)
+                throw new CuaAbortError();
+            const boundMs = session.observationTimeoutMs + (call.kind === "wait" ? (call.ms ?? 0) : 0);
+            await executeAction(session, call, title, boundMs);
+        }
         return "completed";
     }
     catch (error) {

package/dist/actors/computer-use/loop/session.d.ts

@@ -5,6 +5,7 @@ import type { DebriefTrigger, Stop } from "./ending.js";
 import { TraceRecorder } from "./trace.js";
 import type { CuaExecutor, CuaProvider, CuaSafetyCheck, LoopRunOptions } from "./types.js";
 import { UsageLedger } from "./usage.js";
+import { type WaitSettings } from "../wait.js";
 export type ScreenshotRef = NonNullable<ActorTraceItem["screenshotRef"]>;
 /**
  * The options with no default, read once at entry and passed through. Defaulted options and
@@ -34,6 +35,8 @@ export declare class LoopSession {
     readonly timeoutMs: number;
     readonly idleSteps: number;
     readonly noProgressSteps: number;
+    /** How long each wait lasts: the study's wait fields or their defaults. */
+    readonly waits: WaitSettings;
     readonly redactScreenshots: boolean;
     readonly now: () => number;
     readonly acknowledgeSafetyChecks: (checks: CuaSafetyCheck[]) => CuaSafetyCheck[] | null;

package/dist/actors/computer-use/loop/session.js

@@ -1,6 +1,7 @@
 import { TaskTracker } from "../../../study/tasks.js";
 import { TraceRecorder } from "./trace.js";
 import { UsageLedger } from "./usage.js";
+import { resolveWaitSettings } from "../wait.js";
 // The state one loop session shares across its phases: the options as read at entry, the session
 // clock, the trace being recorded, the usage ledger, and what the participant has done so far.
 // Waiting is a legitimate strategy. A persona verifying a sign-up by email polls its inbox
@@ -24,6 +25,8 @@ export class LoopSession {
     timeoutMs;
     idleSteps;
     noProgressSteps;
+    /** How long each wait lasts: the study's wait fields or their defaults. */
+    waits;
     redactScreenshots;
     // Injected functions are wrapped so they are called without a receiver, as plain functions.
     now;
@@ -67,7 +70,7 @@ export class LoopSession {
     scrubText;
     constructor(options) {
         // Read once, in this order: a caller mutating its options object mid-run changes nothing.
-        const { instructions, provider, executor, persona, redaction, timeoutMs, now, signal, idleSteps = DEFAULT_IDLE_STEPS, noProgressSteps = DEFAULT_NO_PROGRESS_STEPS, acknowledgeSafetyChecks = () => null, redactScreenshots = false, scrubText = (text) => text, writeScreenshot = async (name) => `screenshots/${name}`, stopWhen, dwell, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), tasks, maxUsd, overRunBudget, estimateTurnCostUsd, requireReportedUsageForSpendCap = false, onObservedUrl, onMessage, onScreenshot, onTrace, } = options;
+        const { instructions, provider, executor, persona, redaction, timeoutMs, now, signal, idleSteps = DEFAULT_IDLE_STEPS, noProgressSteps = DEFAULT_NO_PROGRESS_STEPS, maxWaitMs, idleWaitMs, acknowledgeSafetyChecks = () => null, redactScreenshots = false, scrubText = (text) => text, writeScreenshot = async (name) => `screenshots/${name}`, stopWhen, dwell, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), tasks, maxUsd, overRunBudget, estimateTurnCostUsd, requireReportedUsageForSpendCap = false, onObservedUrl, onMessage, onScreenshot, onTrace, } = options;
         this.settings = {
             instructions,
             persona,
@@ -89,6 +92,11 @@ export class LoopSession {
         this.timeoutMs = timeoutMs;
         this.idleSteps = idleSteps;
         this.noProgressSteps = noProgressSteps;
+        this.waits = resolveWaitSettings({
+            maxWaitMs,
+            idleWaitMs,
+            speechEnabled: executor.speechEnabled === true,
+        });
         this.redactScreenshots = redactScreenshots;
         this.now = () => now();
         this.acknowledgeSafetyChecks = (checks) => acknowledgeSafetyChecks(checks);

package/dist/actors/computer-use/loop/trace.js

@@ -123,6 +123,7 @@ export function loopResult(session, stop, debrief) {
                         : { maxOutputTokens: provider.modelSettings.maxOutputTokens }),
                 },
             }),
+        waitSettings: { ...session.waits },
         counts,
         items: recorder.items,
         ...(session.actionHistory.affordances.length > 0

package/dist/actors/computer-use/loop/types.d.ts

@@ -55,15 +55,6 @@ export type CuaAction = {
 } | {
     kind: "screenshot";
 };
-/** A wait action whose duration the provider shortened before the loop dispatched it. */
-export interface ShortenedWait {
-    /** The action's index in its turn. */
-    index: number;
-    /** What the participant asked for. */
-    requestedMs: number;
-    /** What the action waits: the `ms` it carries. */
-    ms: number;
-}
 /** A captured desktop state: the (optional) frame plus a coarse signature for progress. */
 export interface CuaObservation {
     /**
@@ -171,11 +162,6 @@ export interface CuaTurn {
     message?: string;
     /** Actions to perform this turn. Empty means the model is done. */
     actions: CuaAction[];
-    /**
-     * Waits the provider shortened to the longest wait its desktop accepts, by index into
-     * `actions`. The loop records each one and tells the participant on its next request.
-     */
-    shortenedWaits?: ReadonlyArray<ShortenedWait>;
     /** Safety checks the provider flagged this turn. Non-empty pauses the run. */
     pendingSafetyChecks: CuaSafetyCheck[];
     /** Token accounting for this turn, if available. */
@@ -304,6 +290,22 @@ export interface CuaLoopOptions {
     idleSteps?: number;
     /** No-progress streak that trips the backstop. Default 20. */
     noProgressSteps?: number;
+    /**
+     * The longest one `wait` action lasts, in ms: the study's actor.maxWaitMs. A longer wait is
+     * shortened to it, the trace records a `wait shortened` notice, and the participant is told on its
+     * next request. A wait longer than one desktop call carries is sent in steps. A whole number from
+     * 1000 to 600000; any other value throws a RangeError before the session starts. Default
+     * defaultMaxWaitMs: 120000, or 30000 when the executor is speechEnabled.
+     */
+    maxWaitMs?: number;
+    /**
+     * How long a `wait` that names no duration lasts, in ms, when its turn only waits or takes
+     * screenshots: the study's actor.idleWaitMs. After an action in the same turn such a wait lasts
+     * 500 ms. A whole number from 1000 to 600000 and no longer than an explicit maxWaitMs; any other
+     * value throws a RangeError before the session starts. Default 5000. The session never applies
+     * more than its maxWaitMs, and the trace records the applied lengths as `waitSettings`.
+     */
+    idleWaitMs?: number;
     /**
      * If the model flags safety checks, decide which to acknowledge. Returning the
      * list proceeds (the acks are echoed back on the next turn's request); returning

package/dist/actors/computer-use/loop.d.ts

@@ -1,5 +1,5 @@
 import type { CuaLoopOptions, CuaLoopResult, LoopRunOptions } from "./loop/types.js";
-export type { CuaAction, CuaExecutor, CuaLiveMetadata, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaSpendGate, CuaTurn, CuaTurnRequest, ShortenedWait, } from "./loop/types.js";
+export type { CuaAction, CuaExecutor, CuaLiveMetadata, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaSpendGate, CuaTurn, CuaTurnRequest, } from "./loop/types.js";
 export { describeCuaAction } from "./loop/actions.js";
 export { stableProgressKey } from "./loop/backstop.js";
 export { IMPRESSIONS_ASK } from "./loop/impressions.js";

package/dist/actors/computer-use/loop.js

@@ -133,7 +133,7 @@ async function runTurns(session, conversation) {
                 ? { ...ended, debriefTrigger: { kind: "participant_end", observation } }
                 : ended;
         }
-        const batch = await runActionBatch(session, turn.actions, turn.shortenedWaits);
+        const batch = await runActionBatch(session, turn.actions);
         conversation.previousExecution = batch.execution;
         const checkpoint = await observer.checkpoint(turnNumber);
         if ("stop" in checkpoint)

package/dist/actors/computer-use/wait.d.ts

@@ -0,0 +1,74 @@
+import type { ActorWaitSettings } from "../contract.js";
+export declare const CUA_WAIT_LIMITS: Readonly<{
+    /**
+     * The longest wait one desktop call is given. A browser-control request must be answered within
+     * its 35 s deadline, and a hosted desktop runs a wait as a sandbox command that times out after
+     * 60 s, so the loop sends a longer wait as consecutive steps of at most this.
+     */
+    stepMs: 30000;
+    /**
+     * The longest one wait action lasts when a study does not set actor.maxWaitMs and the desktop
+     * has no speech (defaultMaxWaitMs). Two minutes covers waiting in a lobby or for an email to
+     * arrive, and the participant still sees a fresh screenshot at least that often.
+     */
+    defaultMaxMs: 120000;
+    /**
+     * How long a wait that names no duration lasts in a turn that only waits or takes screenshots,
+     * when a study does not set actor.idleWaitMs. OpenAI's computer-use `wait` names no duration. A
+     * participant told to wait about a minute sent ten in one turn, which lasts 50 s at this length;
+     * one wait a turn makes a one-minute wait about six turns.
+     */
+    defaultIdleMs: 5000;
+    /**
+     * How long a wait that names no duration lasts after the participant acts in the same turn, so
+     * the screen can settle before the next screenshot. Nearly every OpenAI computer-use wait follows
+     * a click or keypress this way, so a longer one would slow every run.
+     */
+    settleMs: 500;
+    /** The smallest actor.maxWaitMs or actor.idleWaitMs a study may set. */
+    leastMs: 1000;
+    /** The largest actor.maxWaitMs or actor.idleWaitMs a study may set. */
+    mostMs: 600000;
+}>;
+/** The wait lengths one session applies; the trace records them as `waitSettings`. */
+export type WaitSettings = Readonly<ActorWaitSettings>;
+/** One wait as the desktop runs it. */
+export interface PlannedWait {
+    /** How long the wait lasts. */
+    readonly ms: number;
+    /** The desktop calls it takes, in order, each at most CUA_WAIT_LIMITS.stepMs. */
+    readonly steps: readonly number[];
+    /** What the participant asked for, when that was longer than maxWaitMs. */
+    readonly shortenedFromMs?: number;
+}
+/**
+ * The longest one wait action lasts when a study does not set actor.maxWaitMs. On a desktop with
+ * speech, heard speech reaches the participant only with a screenshot, and the desktop session ends
+ * when more utterances arrive between two screenshots than it holds. A wait takes no screenshot, so
+ * there the default keeps one wait to one desktop call.
+ */
+export declare function defaultMaxWaitMs(speechEnabled: boolean): number;
+/**
+ * Why these wait fields cannot run, or null. `prefix` names their owner in the message: `actor.`
+ * in a study file, empty for loop options.
+ */
+export declare function waitFieldsReason(fields: {
+    readonly maxWaitMs?: unknown;
+    readonly idleWaitMs?: unknown;
+}, prefix: string): string | null;
+/**
+ * The wait lengths a session applies: the study's values, or their defaults. The idle wait never
+ * outlasts the longest wait, which on a desktop with speech defaults to 30 s. Throws a RangeError
+ * for fields waitFieldsReason refuses.
+ */
+export declare function resolveWaitSettings(options: {
+    readonly maxWaitMs?: number | undefined;
+    readonly idleWaitMs?: number | undefined;
+    readonly speechEnabled: boolean;
+}): WaitSettings;
+/**
+ * How long one wait lasts and the desktop calls it takes. A wait that names no duration lasts
+ * idleWaitMs when its turn only waits or takes screenshots (`idleTurn`), and settleWaitMs after an
+ * action. A longer wait than maxWaitMs is shortened to it. 70 s is sent as 30 s, 30 s and 10 s.
+ */
+export declare function planWait(settings: WaitSettings, requestedMs: number | undefined, idleTurn: boolean): PlannedWait;

package/dist/actors/computer-use/wait.js

@@ -0,0 +1,100 @@
+// How long one participant wait action lasts, for every provider and desktop. A study sets the
+// longest (actor.maxWaitMs) and how long a wait that names no duration lasts while the participant
+// only waits (actor.idleWaitMs). The loop asks planWait for each wait and sends it to the desktop
+// in steps one desktop call carries.
+export const CUA_WAIT_LIMITS = Object.freeze({
+    /**
+     * The longest wait one desktop call is given. A browser-control request must be answered within
+     * its 35 s deadline, and a hosted desktop runs a wait as a sandbox command that times out after
+     * 60 s, so the loop sends a longer wait as consecutive steps of at most this.
+     */
+    stepMs: 30_000,
+    /**
+     * The longest one wait action lasts when a study does not set actor.maxWaitMs and the desktop
+     * has no speech (defaultMaxWaitMs). Two minutes covers waiting in a lobby or for an email to
+     * arrive, and the participant still sees a fresh screenshot at least that often.
+     */
+    defaultMaxMs: 120_000,
+    /**
+     * How long a wait that names no duration lasts in a turn that only waits or takes screenshots,
+     * when a study does not set actor.idleWaitMs. OpenAI's computer-use `wait` names no duration. A
+     * participant told to wait about a minute sent ten in one turn, which lasts 50 s at this length;
+     * one wait a turn makes a one-minute wait about six turns.
+     */
+    defaultIdleMs: 5_000,
+    /**
+     * How long a wait that names no duration lasts after the participant acts in the same turn, so
+     * the screen can settle before the next screenshot. Nearly every OpenAI computer-use wait follows
+     * a click or keypress this way, so a longer one would slow every run.
+     */
+    settleMs: 500,
+    /** The smallest actor.maxWaitMs or actor.idleWaitMs a study may set. */
+    leastMs: 1_000,
+    /** The largest actor.maxWaitMs or actor.idleWaitMs a study may set. */
+    mostMs: 600_000,
+});
+/** A whole number of milliseconds within the range actor.maxWaitMs and actor.idleWaitMs accept. */
+function isWaitMs(value) {
+    return (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= CUA_WAIT_LIMITS.leastMs &&
+        value <= CUA_WAIT_LIMITS.mostMs);
+}
+/**
+ * The longest one wait action lasts when a study does not set actor.maxWaitMs. On a desktop with
+ * speech, heard speech reaches the participant only with a screenshot, and the desktop session ends
+ * when more utterances arrive between two screenshots than it holds. A wait takes no screenshot, so
+ * there the default keeps one wait to one desktop call.
+ */
+export function defaultMaxWaitMs(speechEnabled) {
+    return speechEnabled ? CUA_WAIT_LIMITS.stepMs : CUA_WAIT_LIMITS.defaultMaxMs;
+}
+const FIELDS = [
+    ["maxWaitMs", "the longest one wait action lasts"],
+    ["idleWaitMs", "how long a wait with no duration lasts while the participant only waits"],
+];
+/**
+ * Why these wait fields cannot run, or null. `prefix` names their owner in the message: `actor.`
+ * in a study file, empty for loop options.
+ */
+export function waitFieldsReason(fields, prefix) {
+    for (const [name, meaning] of FIELDS) {
+        if (fields[name] !== undefined && !isWaitMs(fields[name]))
+            return `${prefix}${name}, ${meaning}, must be a whole number of milliseconds from ${CUA_WAIT_LIMITS.leastMs} to ${CUA_WAIT_LIMITS.mostMs}.`;
+    }
+    const { maxWaitMs, idleWaitMs } = fields;
+    if (typeof maxWaitMs === "number" && typeof idleWaitMs === "number" && idleWaitMs > maxWaitMs)
+        return `${prefix}idleWaitMs (${idleWaitMs}) is longer than ${prefix}maxWaitMs (${maxWaitMs}), the longest one wait action lasts. Lower ${prefix}idleWaitMs or raise ${prefix}maxWaitMs.`;
+    return null;
+}
+/**
+ * The wait lengths a session applies: the study's values, or their defaults. The idle wait never
+ * outlasts the longest wait, which on a desktop with speech defaults to 30 s. Throws a RangeError
+ * for fields waitFieldsReason refuses.
+ */
+export function resolveWaitSettings(options) {
+    const reason = waitFieldsReason(options, "");
+    if (reason !== null)
+        throw new RangeError(reason);
+    const maxWaitMs = options.maxWaitMs ?? defaultMaxWaitMs(options.speechEnabled);
+    return {
+        maxWaitMs,
+        idleWaitMs: Math.min(options.idleWaitMs ?? CUA_WAIT_LIMITS.defaultIdleMs, maxWaitMs),
+        settleWaitMs: CUA_WAIT_LIMITS.settleMs,
+    };
+}
+/**
+ * How long one wait lasts and the desktop calls it takes. A wait that names no duration lasts
+ * idleWaitMs when its turn only waits or takes screenshots (`idleTurn`), and settleWaitMs after an
+ * action. A longer wait than maxWaitMs is shortened to it. 70 s is sent as 30 s, 30 s and 10 s.
+ */
+export function planWait(settings, requestedMs, idleTurn) {
+    const askedMs = requestedMs ?? (idleTurn ? settings.idleWaitMs : settings.settleWaitMs);
+    const ms = Math.min(askedMs, settings.maxWaitMs);
+    const { stepMs } = CUA_WAIT_LIMITS;
+    const steps = [];
+    for (let left = ms; left > stepMs; left -= stepMs)
+        steps.push(stepMs);
+    steps.push(ms - steps.length * stepMs);
+    return { ms, steps, ...(askedMs > ms ? { shortenedFromMs: askedMs } : {}) };
+}