humanish 0.125.0 → 0.127.0

package/dist/study/arrivals.js

@@ -1,9 +1,11 @@
 // When each participant of a computer-use or shared-world run starts, and on computer use when it
 // ends. A study may give each participant an offset from the moment the run starts its participants
 // (`participants[].startAfterMs`) and, on computer use, an end on the same clock
-// (`participants[].endAfterMs`), with a wind-down before it in which each turn tells the
-// participant the time left (`windDownMs`). The plan simulates the start queue to report the schedule and
-// when the last session ends at the latest; the routes start their participants through
+// (`participants[].endAfterMs`) or a cap on its own session (`maxSessionMs`), with a wind-down
+// before either in which each turn tells the participant the time left (`windDownMs`). Each
+// participant's ParticipantSchedule resolves those fields once; everything that reads a
+// participant's time reads the schedule. The plan simulates the start queue to report the schedule
+// and when the last session ends at the latest; the routes start their participants through
 // runOnSchedule, which waits for each one's time and then for a free slot. A participant's desktop
 // is created when it starts, so a late start holds no sandbox before then.
 import { setTimeout as delay } from "node:timers/promises";
@@ -22,8 +24,8 @@ export function isStartAfterMs(value) {
         value >= 0 &&
         value <= LATEST_START_AFTER_MS);
 }
-/** How long before its end a participant is told the time left, unless it declares `windDownMs`. */
-export const DEFAULT_WIND_DOWN_MS = 10 * 60_000;
+/** The longest default wind-down: 10 minutes is enough to wrap up what a participant is doing. */
+const MAX_DEFAULT_WIND_DOWN_MS = 10 * 60_000;
 /**
  * Room a scheduled participant's session keeps past its end for the turn in flight and the closing
  * report. The loop ends the session at the end; this keeps the session's own time limit, and the
@@ -32,13 +34,18 @@ export const DEFAULT_WIND_DOWN_MS = 10 * 60_000;
 const SCHEDULED_END_ROOM_MS = 5 * 60_000;
 /**
  * Why a participant's declared end cannot run, or undefined: an end that is not a whole number of
- * milliseconds up to 24 hours, one at or before its start, or a wind-down that is not a whole
- * number of milliseconds or has no end. `path` names the entry, as in "participants[1]".
+ * milliseconds up to 24 hours, one at or before its start, a cap that is not a whole number of
+ * milliseconds from 1 to 24 hours, a cap beside an end, or a wind-down that is not a whole number
+ * of milliseconds or has neither. `path` names the entry, as in "participants[1]".
  */
 export function windowReason(entry, path) {
-    const { endAfterMs, windDownMs } = entry;
-    if (windDownMs !== undefined && endAfterMs === undefined)
-        return `${path}.windDownMs is how long before its endAfterMs a participant is told the time left, so it needs ${path}.endAfterMs. Add the end, or remove windDownMs.`;
+    const { endAfterMs, maxSessionMs, windDownMs } = entry;
+    if (maxSessionMs !== undefined && endAfterMs !== undefined)
+        return `${path} sets both endAfterMs and maxSessionMs. endAfterMs holds the participant until a set time, and maxSessionMs lets it end its session sooner, up to a cap, so a participant takes one of them. Keep endAfterMs for one that stays until a set time, or maxSessionMs for one that may leave when it is done.`;
+    if (maxSessionMs !== undefined && !(isStartAfterMs(maxSessionMs) && maxSessionMs > 0))
+        return `${path}.maxSessionMs must be a whole number of milliseconds from 1 to ${LATEST_START_AFTER_MS} (24 hours): the longest the participant's session lasts, counted from its start.`;
+    if (windDownMs !== undefined && endAfterMs === undefined && maxSessionMs === undefined)
+        return `${path}.windDownMs is how long before its endAfterMs or maxSessionMs a participant is told the time left, so it needs one of them. Add an end, or remove windDownMs.`;
     if (windDownMs !== undefined && !isStartAfterMs(windDownMs))
         return `${path}.windDownMs must be a whole number of milliseconds from 0 to ${LATEST_START_AFTER_MS} (24 hours): how long before its end the participant is told the time left.`;
     if (endAfterMs === undefined)
@@ -53,58 +60,120 @@ export function windowReason(entry, path) {
     return undefined;
 }
 /**
- * A participant's session budget: with a declared end, its window plus SCHEDULED_END_ROOM_MS in
- * place of the study's `sessionMs` (execution.timeoutMs or its default); else `sessionMs`.
+ * The schedule of a participants entry that windowReason accepts. A cap wins over an end, which
+ * windowReason refuses beside it anyway.
  */
-export function participantSessionMs(participant, sessionMs) {
-    if (participant.endAfterMs === undefined)
-        return sessionMs;
-    return participant.endAfterMs - (participant.startAfterMs ?? 0) + SCHEDULED_END_ROOM_MS;
+export function participantSchedule(entry) {
+    const start = entry.startAfterMs === undefined ? {} : { startAfterMs: entry.startAfterMs };
+    if (entry.maxSessionMs !== undefined)
+        return {
+            ...start,
+            end: { kind: "session_cap", ...endTiming(entry.maxSessionMs, entry.windDownMs) },
+        };
+    if (entry.endAfterMs === undefined)
+        return start;
+    const windowMs = entry.endAfterMs - (entry.startAfterMs ?? 0);
+    return {
+        ...start,
+        end: {
+            kind: "scheduled_end",
+            endAfterMs: entry.endAfterMs,
+            ...endTiming(windowMs, entry.windDownMs),
+        },
+    };
 }
 /**
- * When a participant that was due at `scheduledAt` (runOnSchedule's ScheduledStart) ends, on the
- * same clock, or undefined when it declares no end. A participant that waited for a slot still ends
- * at its declared time.
+ * A window's wind-down and session budget. Without a declared `windDownMs` the wind-down is a
+ * quarter of the window, at most 10 minutes. A fixed 10 minutes covered the whole of a window of
+ * 10 minutes or less, so a short session was told its end from the first turn. A quarter leaves
+ * most of a short session without a countdown, and a window of 40 minutes or more keeps the 10
+ * minutes.
  */
-export function scheduledEndAt(participant, scheduledAt) {
-    if (participant.endAfterMs === undefined)
-        return undefined;
+function endTiming(windowMs, windDownMs) {
     return {
-        atMs: scheduledAt - (participant.startAfterMs ?? 0) + participant.endAfterMs,
-        windDownMs: participant.windDownMs ?? DEFAULT_WIND_DOWN_MS,
+        windowMs,
+        windDownMs: windDownMs ?? Math.min(MAX_DEFAULT_WIND_DOWN_MS, Math.floor(windowMs / 4)),
+        sessionMs: windowMs + SCHEDULED_END_ROOM_MS,
     };
 }
 /**
- * Why the sandbox of the first participant whose window passes `ceilingMs` cannot live that long,
- * or undefined. Its deadline is its session (participantSessionMs) plus `headroomMs`, what the
- * route adds to a session for setup and teardown (sandboxHeadroomMs).
+ * The schedule a rerun gives a participant: it starts with the rerun, and a scheduled end keeps its
+ * time on the rerun's clock and its wind-down, so its window runs from the rerun's start.
+ */
+export function startingWithTheRun(schedule) {
+    const { end } = schedule;
+    if (end === undefined)
+        return {};
+    if (end.kind === "session_cap")
+        return { end };
+    return participantSchedule({ endAfterMs: end.endAfterMs, windDownMs: end.windDownMs });
+}
+/**
+ * A participant's own session budget and sandbox deadline. With an end or a cap it is the end's
+ * `sessionMs`, and the sandbox keeps the study sandbox's headroom over the study session on top;
+ * without one, the study's own.
  */
-export function windowDeadlineRefusal(participants, sandbox, ceilingMs) {
+export function participantSession(schedule, study) {
+    const sessionMs = schedule.end?.sessionMs ?? study.sessionMs;
+    return { sessionMs, sandboxMs: study.sandboxMs - study.sessionMs + sessionMs };
+}
+/**
+ * How a participant that was due at `scheduledAt` (runOnSchedule's ScheduledStart) ends, or
+ * undefined without an end or a cap. A scheduled end comes its window after the participant's
+ * time, which is its `endAfterMs` on the run's clock, even when it waited for a slot; a cap is
+ * whole from wherever its session starts.
+ */
+export function participantEnd(schedule, scheduledAt) {
+    const { end } = schedule;
+    if (end === undefined)
+        return undefined;
+    if (end.kind === "session_cap")
+        return { kind: "session_cap", afterMs: end.windowMs, windDownMs: end.windDownMs };
+    return { kind: "scheduled_end", atMs: scheduledAt + end.windowMs, windDownMs: end.windDownMs };
+}
+/**
+ * Why the sandbox of the first participant whose window or cap passes `ceilingMs` cannot live that
+ * long, or undefined. Its deadline is its participantSession's, from the study's session budget and
+ * sandbox deadline.
+ */
+export function windowDeadlineRefusal(participants, study, ceilingMs) {
     const inMinutes = (ms) => Math.round(ms / 60_000);
-    for (const participant of participants) {
-        if (participant.endAfterMs === undefined)
+    for (const { id, schedule } of participants) {
+        const { end } = schedule;
+        if (end === undefined)
             continue;
-        const deadlineMs = participantSessionMs(participant, sandbox.sessionMs) + sandbox.headroomMs;
+        const deadlineMs = participantSession(schedule, study).sandboxMs;
         if (deadlineMs <= ceilingMs)
             continue;
-        const name = participant.id === undefined ? "A participant" : `Participant "${participant.id}"`;
-        return `${name} works from +${formatDuration(participant.startAfterMs ?? 0)} to +${formatDuration(participant.endAfterMs)}, so its sandbox needs a ${inMinutes(deadlineMs)}m deadline: the window, ${inMinutes(SCHEDULED_END_ROOM_MS)}m for its closing report and ${inMinutes(sandbox.headroomMs)}m to set up and tear down. A sandbox may not live longer than ${ceilingMs / 60_000}m. Shorten its window.${ceilingAdvice(deadlineMs)}`;
+        const works = end.kind === "scheduled_end"
+            ? `works from +${formatDuration(schedule.startAfterMs ?? 0)} to +${formatDuration(end.endAfterMs)}`
+            : `may work for up to ${formatDuration(end.windowMs)}`;
+        const window = end.kind === "scheduled_end" ? "window" : "cap";
+        return `Participant "${id}" ${works}, so its sandbox needs a ${inMinutes(deadlineMs)}m deadline: the ${window}, ${inMinutes(SCHEDULED_END_ROOM_MS)}m for its closing report and ${inMinutes(study.sandboxMs - study.sessionMs)}m to set up and tear down. A sandbox may not live longer than ${ceilingMs / 60_000}m. Shorten its ${window}.${ceilingAdvice(deadlineMs)}`;
     }
     return undefined;
 }
 /**
- * Each participant's window for `study check`, when any participant declares an end: when it starts
- * and ends and when it is first told the time left, or when it starts and its session budget.
+ * Each participant's window for `study check`, when any participant declares an end or a cap: when
+ * it starts and ends and when it is first told the time left, when it starts and its cap and how
+ * far into its session it is first told the time left, or when it starts and the study's
+ * `sessionMs`.
  */
 export function describeWindows(participants, sessionMs) {
-    if (!participants.some((participant) => participant.endAfterMs !== undefined))
+    if (participants.every((participant) => participant.schedule.end === undefined))
         return undefined;
-    const windows = participants.map((participant) => {
-        const start = `${participant.id ?? "participant"} from +${formatDuration(participant.startAfterMs ?? 0)}`;
-        if (participant.endAfterMs === undefined)
+    const windows = participants.map(({ id, schedule }) => {
+        const startAfterMs = schedule.startAfterMs ?? 0;
+        const start = `${id} from +${formatDuration(startAfterMs)}`;
+        const { end } = schedule;
+        if (end === undefined)
             return `${start} for up to ${formatDuration(sessionMs)}`;
-        const told = Math.max(participant.startAfterMs ?? 0, participant.endAfterMs - (participant.windDownMs ?? DEFAULT_WIND_DOWN_MS));
-        return `${start} to +${formatDuration(participant.endAfterMs)}, told the time left from +${formatDuration(told)}`;
+        if (end.kind === "session_cap") {
+            const told = Math.max(0, end.windowMs - end.windDownMs);
+            return `${start} until it ends itself or for up to ${formatDuration(end.windowMs)}, told the time left from ${formatDuration(told)} into its session`;
+        }
+        const told = Math.max(startAfterMs, end.endAfterMs - end.windDownMs);
+        return `${start} to +${formatDuration(end.endAfterMs)}, told the time left from +${formatDuration(told)}`;
     });
     return `${windows.join("; ")}.`;
 }
@@ -126,34 +195,42 @@ export function rosterStartsReason(roster) {
     return undefined;
 }
 /**
- * The schedule a roster's declared offsets give under the queue (`undefined` is 0: the participant
- * starts with the run). Participants start in schedule order, by offset and then roster position,
- * each at its time or when a slot frees, whichever is later; this is the rule runOnSchedule
- * follows. `sessionsMs` gives a participant with a declared end its own session budget
- * (participantSessionMs); the others hold their slot for `queue.sessionMs`.
+ * The schedule a roster's participants give under the queue. Participants start in schedule order,
+ * by offset and then roster position, each at its time or when a slot frees, whichever is later;
+ * this is the rule runOnSchedule follows. A participant with an end or a cap holds its slot for its
+ * own session budget, and the others for `queue.sessionMs`. A participant whose slot would free
+ * only at or after its scheduled end takes none: the run skips it (pastEndReason).
  */
-export function planArrivals(offsets, queue, sessionsMs = []) {
-    const due = offsets.map((offset) => offset ?? 0);
-    const session = (index) => sessionsMs[index] ?? queue.sessionMs;
-    const starts = queueStarts(due, queue, session);
+export function planArrivals(schedules, queue) {
+    return simulateQueue(schedules, queue).arrivals;
+}
+/** planArrivals, and the roster indexes of the participants the run would skip. */
+function simulateQueue(schedules, queue) {
+    const due = schedules.map((schedule) => schedule.startAfterMs ?? 0);
+    const sessionsMs = schedules.map((schedule) => schedule.end?.sessionMs ?? queue.sessionMs);
+    const session = (index) => sessionsMs[index];
+    const { starts, skipped } = queueStarts(schedules, due, queue, session);
+    const skips = new Set(skipped);
+    const started = starts.flatMap((_, index) => (skips.has(index) ? [] : [index]));
     let waiting = 0;
     let longestWaitMs = 0;
-    for (const [index, start] of starts.entries()) {
-        const waitMs = start - due[index];
+    for (const index of started) {
+        const waitMs = starts[index] - due[index];
         if (waitMs > 0)
             waiting += 1;
         longestWaitMs = Math.max(longestWaitMs, waitMs);
     }
-    return {
-        declared: offsets.some((offset) => offset !== undefined),
+    const arrivals = {
+        declared: schedules.some((schedule) => schedule.startAfterMs !== undefined),
         firstStartMs: Math.min(...due),
         lastStartMs: Math.max(...due),
-        peak: mostAtOnce(starts, session),
+        peak: mostAtOnce(started.map((index) => [starts[index], session(index)])),
         waiting,
         longestWaitMs,
-        lastEndMs: Math.max(...starts.map((start, index) => start + session(index))),
+        lastEndMs: Math.max(...started.map((index) => starts[index] + session(index))),
         sessionMs: queue.sessionMs,
     };
+    return { arrivals, skipped };
 }
 /**
  * The plan's schedule, after a "schedule:" label: the first and last start, and how many run at
@@ -169,21 +246,43 @@ export function describeArrivals(arrivals) {
  * A planner's arrival plan for its participants under the start queue, and the warnings the plan
  * records about it. A participant's desktop is created when it starts, so on computer use a late
  * start adds nothing to any sandbox's deadline; the provisioned shared world checks its app's
- * sandbox with servedScheduleRefusal. `lowered` is the warning that the E2B plan's limit runs the
- * roster in waves.
+ * sandbox with servedScheduleRefusal. `lowered` is participantsAtOnce's warning that the E2B plan's
+ * limit or HUMANISH_CUA_MAX_CONCURRENCY runs the roster in waves.
  */
 export function planStarts(participants, queue, lowered) {
-    const arrivals = planArrivals(participants.map((participant) => participant.startAfterMs), queue, participants.map((participant) => participantSessionMs(participant, queue.sessionMs)));
-    return { arrivals, warnings: startQueueWarnings(arrivals, queue, lowered) };
+    const { arrivals, skipped } = simulateQueue(participants.map((participant) => participant.schedule), queue);
+    const ids = skipped.map((index) => participants[index].id);
+    return { arrivals, warnings: startQueueWarnings(arrivals, ids, queue, lowered) };
 }
 // A roster that starts together keeps `lowered`. A declared schedule spreads its participants
-// itself, so it is warned only when it holds someone past their time, with `lowered` beside that
-// when the limit is the reason.
-function startQueueWarnings(arrivals, queue, lowered) {
-    if (!arrivals.declared || arrivals.waiting === 0)
-        return !arrivals.declared && lowered ? [lowered] : [];
-    const late = `${plural(arrivals.waiting, "participant")} would start after their time when every session uses its ${formatDuration(arrivals.sessionMs)} budget, the latest by ${formatDuration(arrivals.longestWaitMs)}: the run starts at most ${queue.slots} at once and holds the next one until a slot frees.`;
-    return lowered === undefined ? [late] : [late, lowered];
+// itself, so it is warned only when it holds someone past their time or skips someone, with
+// `lowered` beside that when the limit is the reason.
+function startQueueWarnings(arrivals, skipped, queue, lowered) {
+    const budget = `when every session uses its ${formatDuration(arrivals.sessionMs)} budget`;
+    const atMost = `the run starts at most ${queue.slots} at once`;
+    const late = `${plural(arrivals.waiting, "participant")} would start after their time ${budget}, the latest by ${formatDuration(arrivals.longestWaitMs)}: ${atMost} and holds the next one until a slot frees.`;
+    const one = skipped.length === 1;
+    const names = skipped.map((id) => `"${id}"`);
+    const who = one
+        ? `Participant ${names[0]}`
+        : `${skipped.length} participants (${names.join(", ")})`;
+    const skip = `${who} would still be waiting for a free slot at ${one ? "its" : "their"} end (participants[].endAfterMs) ${budget}, so the run would skip ${one ? "it without creating its desktop" : "them without creating their desktops"}: ${atMost}. Let more participants run at once, or give ${one ? "it" : "them"} a later end.`;
+    const held = arrivals.waiting > 0 || skipped.length > 0;
+    return [
+        ...(arrivals.declared && arrivals.waiting > 0 ? [late] : []),
+        ...(skipped.length > 0 ? [skip] : []),
+        ...(lowered !== undefined && (!arrivals.declared || held) ? [lowered] : []),
+    ];
+}
+/**
+ * Why a participant whose start comes at `nowMs` is skipped, or undefined: its scheduled end came
+ * while it waited, so its session would end before it began. The plan's simulation applies the
+ * same rule (planArrivals).
+ */
+export function pastEndReason(end, nowMs) {
+    if (end?.kind !== "scheduled_end" || nowMs < end.atMs)
+        return undefined;
+    return "skipped: its scheduled end (participants[].endAfterMs) came while it waited to start, so its session would have ended before it began; no desktop was created";
 }
 /**
  * Why a sandbox that serves the app until the last participant ends, the provisioned shared
@@ -217,8 +316,9 @@ function scheduleOrder(due) {
     return due.map((_, index) => index).sort((a, b) => due[a] - due[b] || a - b);
 }
 /** Each participant's start in roster order, when each session holds its slot for `session(index)`. */
-function queueStarts(due, queue, session) {
+function queueStarts(schedules, due, queue, session) {
     const starts = [...due];
+    const skipped = [];
     const queued = scheduleOrder(due).filter((index) => index !== queue.ownSlot);
     const pooled = queue.ownSlot === undefined ? queue.slots : queue.slots - 1;
     // When each slot is next free; a participant takes the one that frees first.
@@ -227,16 +327,21 @@ function queueStarts(due, queue, session) {
         const slot = free.indexOf(Math.min(...free));
         const start = Math.max(due[index], free[slot]);
         starts[index] = start;
-        free[slot] = start + session(index);
+        const end = schedules[index]?.end;
+        if (end?.kind === "scheduled_end" && start >= end.endAfterMs)
+            skipped.push(index);
+        else
+            free[slot] = start + session(index);
     }
-    return starts;
+    return { starts, skipped };
 }
-function mostAtOnce(starts, session) {
+/** The most sessions running at once, each given as its start and how long it holds its slot. */
+function mostAtOnce(sessions) {
     // An end sorts before a start at the same instant: that slot is free again.
-    const changes = starts
-        .flatMap((start, index) => [
+    const changes = sessions
+        .flatMap(([start, ms]) => [
         { at: start, by: 1 },
-        { at: start + session(index), by: -1 },
+        { at: start + ms, by: -1 },
     ])
         .sort((a, b) => a.at - b.at || a.by - b.by);
     let live = 0;

package/dist/study/bundle-estimate.d.ts

@@ -1,8 +1,8 @@
 import type { DwellWindow } from "../actors/stop-conditions.js";
-/** One participant as the plan has it: when it starts and ends, and its dwell window. */
+import type { ParticipantSchedule } from "./arrivals.js";
+/** One participant as the plan has it: its schedule and its dwell window. */
 export interface EstimatedParticipant {
-    readonly startAfterMs?: number;
-    readonly endAfterMs?: number;
+    readonly schedule: ParticipantSchedule;
     readonly limits: {
         readonly dwell?: DwellWindow;
     };
@@ -11,8 +11,10 @@ export interface EstimatedParticipant {
 export interface BundleEstimate {
     /** run.json, which analysis reads whole. */
     readonly runFileBytes: number;
-    /** The largest file: observer/observer-data.json, or the Observer page for a small run. */
-    readonly largestFileBytes: number;
+    /** The largest participant trace file, which analysis also reads whole. */
+    readonly largestTraceBytes: number;
+    /** observer/index.html, which verify reads whole. */
+    readonly observerPageBytes: number;
     /** Every file, screenshots included. */
     readonly totalBytes: number;
     /** Files and folders in the run folder, as the public-safety scan counts them. */
@@ -33,15 +35,15 @@ export interface BundleEstimate {
 }
 /**
  * The bundle a live run of `participants` leaves, each in its session of `sessionMs` unless it
- * declares an end. A participant with an end works its whole window; one without is counted for
- * the measured open session above, or its budget when that is shorter. Each takes a model turn at
- * the measured pace, and a dwell window adds a frame every `everyMs` for its length, cut to the
- * session, and the frame after it.
+ * declares an end or a cap. A participant with an end works its whole window; one without ends
+ * itself, so it is counted for the measured open session above, or its budget (its cap, else
+ * `sessionMs`) when that is shorter. Each takes a model turn at the measured pace, and a dwell
+ * window adds a frame every `everyMs` for its length, cut to the session, and the frame after it.
  */
 export declare function estimateBundle(participants: readonly EstimatedParticipant[], sessionMs: number): BundleEstimate;
 /**
  * The warning for a run whose estimate passes a limit, or undefined: each limit it passes, what the
- * estimate counted, how high it runs, and what to change.
+ * estimate counted, and what to change.
  */
 export declare function bundleLimitReason(estimate: BundleEstimate): string | undefined;
 /** The estimate beside the limits, for `study check`. */