humanish 0.124.0 → 0.126.0

package/dist/run/stream-trace.js

@@ -1,10 +1,14 @@
 // Where a participant's trace lives. A v1 run.json holds every stream's trace items and screenshot
 // entries inline. From v2 the run writer moves them into one file per stream and leaves an index
-// in run.json, so run.json stays a summary whatever the length of the sessions. Every reader that
-// needs the items loads them here, which accepts both versions and checks a file against its index.
+// in run.json, so run.json stays a summary whatever the length of the sessions. From v3 a running
+// participant's items so far are in a live file run.json indexes too (src/run/live-items.ts).
+// Every reader that needs the items loads them here, which accepts every version and checks each
+// file against its index.
 import { createHash } from "node:crypto";
-import { RUN_BUNDLE_SCHEMA } from "./bundle.js";
-import { readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
+import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V2_SCHEMA, } from "./bundle.js";
+import { isRunBundle } from "./bundle-shape.js";
+import { readContainedPrefix, readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
+import { isLiveItemsIndex, LIVE_ACTOR_SCHEMA, LIVE_ACTOR_V1_SCHEMA, liveItemsAfter, liveItemsFromBytes, } from "./live-items.js";
 import { isRunStreamArtifact, isStreamTraceIndex, isStreamTracePath } from "./stream-shape.js";
 import { isRecord } from "./type-guards.js";
 /** A trace that does not match its index, or cannot be read. The message names the stream. */
@@ -83,8 +87,10 @@ export function splitStreamTraces(bundle) {
     return { bundle: { ...bundle, schema: RUN_BUNDLE_SCHEMA, streams }, files };
 }
 function containedReader(runPaths) {
-    return async (relativePath, maxBytes) => {
-        const read = await readContainedRegularFile(runPaths, relativePath, maxBytes);
+    return async (relativePath, maxBytes, length, start) => {
+        const read = length === undefined
+            ? await readContainedRegularFile(runPaths, relativePath, maxBytes)
+            : await readContainedPrefix(runPaths, relativePath, length, start);
         if (read.status === "missing")
             return { refused: `${relativePath} is missing` };
         if (read.status === "refused")
@@ -136,15 +142,94 @@ function assertIndex(stream) {
     if (stream.actor.items !== undefined)
         throw new StreamTraceRefusedError(stream.id, "run.json holds items beside its trace index");
 }
-/** The stream with its trace joined, and the bytes it was joined from when it has an index. */
-async function readStreamTrace(read, stream, maxBytes) {
-    if (stream.trace === undefined)
+/** A live actor whose items run.json holds inline: humanish.live-actor.v1, or one with no schema. */
+const isInlineLiveActor = (live) => live.schema === LIVE_ACTOR_V1_SCHEMA || live.schema === undefined;
+/** A live file that could not be read, which a writer that moved on may have removed. */
+class LiveFileUnreadableError extends StreamTraceRefusedError {
+}
+/**
+ * The stream with its live actor's items joined from the indexed prefix of its live file, and the
+ * file's path and those bytes. A live actor with inline items (humanish.live-actor.v1) is returned
+ * as it is; bundleRefusal refuses one in a v3 run.json.
+ */
+async function readLiveItems(read, stream, maxBytes, liveAfter) {
+    const live = stream.liveActor;
+    if (live === undefined || isInlineLiveActor(live))
         return { stream };
-    assertIndex(stream);
-    const file = await read(stream.trace.path, maxBytes);
+    const refuse = (detail) => {
+        throw new StreamTraceRefusedError(stream.id, detail);
+    };
+    if (live.schema !== LIVE_ACTOR_SCHEMA)
+        refuse(`run.json records live actor schema ${String(live.schema)}, which this version does not read`);
+    const index = live.itemsFile;
+    if (!isLiveItemsIndex(index))
+        return refuse("run.json records a malformed live items index");
+    if (live.items !== undefined)
+        refuse("run.json holds in-progress items beside their live file");
+    if (index.bytes > maxBytes)
+        refuse(`${index.path} is indexed at ${index.bytes} bytes, more than the ${maxBytes} read`);
+    const { itemsFile: _index, ...summary } = live;
+    const after = liveAfter?.(index);
+    const tail = after === undefined ? undefined : await readLiveTail(read, stream, index, after);
+    if (tail !== undefined)
+        return {
+            stream: { ...stream, liveActor: { ...summary, items: tail.items } },
+            file: { path: index.path, bytes: tail.bytes },
+            read: { streamId: stream.id, index, after: after },
+        };
+    const file = await read(index.path, maxBytes, index.bytes);
     if ("refused" in file)
-        throw new StreamTraceRefusedError(stream.id, file.refused);
-    return { stream: joinTrace(stream, file.bytes), bytes: file.bytes };
+        throw new LiveFileUnreadableError(stream.id, file.refused);
+    // Only the indexed prefix: a reader that ignores `length` hands over the bytes appended since.
+    const joined = liveItemsFromBytes(file.bytes.subarray(0, index.bytes), index);
+    if ("refused" in joined)
+        return refuse(joined.refused);
+    return {
+        stream: { ...stream, liveActor: { ...summary, items: joined.items } },
+        file: { path: index.path, bytes: file.bytes.subarray(0, index.bytes) },
+        read: { streamId: stream.id, index },
+    };
+}
+/**
+ * The items of the live file `index` describes past `after`, and the bytes they were read from;
+ * undefined when the cursor does not fit the index or the file's lines, so the caller reads the
+ * whole prefix. A cursor at the indexed end reads nothing. A file the reader cannot read throws
+ * LiveFileUnreadableError, as a whole read does.
+ */
+async function readLiveTail(read, stream, index, after) {
+    if (after.bytes === 0 ||
+        after.items > index.items ||
+        after.bytes > index.bytes ||
+        (after.items === index.items) !== (after.bytes === index.bytes))
+        return undefined;
+    if (after.bytes === index.bytes)
+        return { items: [], bytes: Buffer.alloc(0) };
+    const file = await read(index.path, index.bytes - after.bytes + 1, index.bytes, after.bytes - 1);
+    if ("refused" in file)
+        throw new LiveFileUnreadableError(stream.id, file.refused);
+    const tail = file.bytes.subarray(0, index.bytes - after.bytes + 1);
+    const joined = liveItemsAfter(tail, index, after);
+    return "refused" in joined ? undefined : { items: joined.items, bytes: tail.subarray(1) };
+}
+/**
+ * The stream with its trace and live items joined, and each file's path and the bytes it was
+ * joined from.
+ */
+async function readStreamTrace(read, stream, maxBytes, liveAfter) {
+    const files = [];
+    let joined = stream;
+    if (stream.trace !== undefined) {
+        assertIndex(stream);
+        const file = await read(stream.trace.path, maxBytes);
+        if ("refused" in file)
+            throw new StreamTraceRefusedError(stream.id, file.refused);
+        joined = joinTrace(stream, file.bytes);
+        files.push({ path: stream.trace.path, bytes: file.bytes });
+    }
+    const live = await readLiveItems(read, joined, maxBytes, liveAfter);
+    if (live.file !== undefined)
+        files.push(live.file);
+    return { stream: live.stream, files, ...(live.read === undefined ? {} : { live: live.read }) };
 }
 /**
  * The stream as a v1 run.json held it: its actor with every item and every artifact entry. A
@@ -163,8 +248,10 @@ export async function loadStreamTrace(runPaths, stream, maxBytes = RUN_ARTIFACT_
  * case-insensitive file system compares them, is refused. In v2 the writer
  * indexes every actor on every write, mid-run flushes included, so a v2 actor without an index lost
  * its trace file, and inline items never come from the writer. A run still writing carries its
- * participants' items so far as `liveActor` (humanish.live-actor.v1), which no index binds; a
- * run.json whose outcome says the run finished never does, since the final write replaces it.
+ * participants' items so far as `liveActor`: inline in v2 (humanish.live-actor.v1), in a live file
+ * from v3 (humanish.live-actor.v2), so a v3 run.json with inline live items did not come from the
+ * writer. A run.json whose outcome says the run finished never carries `liveActor`, since the
+ * final write replaces it.
  */
 function bundleRefusal(bundle, stream, owners) {
     const shared = isRecord(stream.trace)
@@ -172,12 +259,16 @@ function bundleRefusal(bundle, stream, owners) {
         : undefined;
     if (shared !== undefined && shared.length > 1)
         return `run.json indexes ${String(stream.trace.path)} for participants ${shared.join(", ")} (paths that differ only in case name one file on some file systems), and a trace file belongs to one participant`;
-    if (bundle.schema !== RUN_BUNDLE_SCHEMA)
+    if (bundle.schema !== RUN_BUNDLE_SCHEMA && bundle.schema !== RUN_BUNDLE_V2_SCHEMA)
         return undefined;
     if (stream.actor !== undefined && stream.trace === undefined)
         return "run.json holds its actor and names no trace file";
     if (stream.liveActor !== undefined && bundle.outcome?.state === "finished")
         return "run.json records a finished run and still holds in-progress items";
+    if (bundle.schema === RUN_BUNDLE_SCHEMA &&
+        stream.liveActor !== undefined &&
+        isInlineLiveActor(stream.liveActor))
+        return "run.json v3 holds in-progress items inline, which the writer keeps in a live file";
     return undefined;
 }
 /**
@@ -185,11 +276,46 @@ function bundleRefusal(bundle, stream, owners) {
  * of each stream that could not be (see bundleRefusal for the rules that need the whole bundle).
  * Each refused stream is kept as run.json holds it; a reader that shows the run passes the result
  * to displayedTraces. `source` is the run's prepared paths, or a TraceFileReader. `onTrace`
- * receives each trace file's path and the bytes the stream was joined from, after they matched
- * the index, so a caller scans exactly what it reads.
+ * receives each trace and live file's path and the bytes the stream was joined from, after they
+ * matched the index, so a caller scans exactly what it reads.
+ *
+ * `liveAfter` names, for a live file's index, the prefix the caller holds already (the Observer
+ * feed's cursor). The loader then reads and joins only the items past it, checked by liveItemsAfter
+ * without the indexed sha256, and `live` records the cursor; a cursor past the index or off the
+ * file's lines gets the whole prefix, checked as always.
+ *
+ * A live file that cannot be read may have been removed by the writer after `bundle` was read: it
+ * removes a superseded generation once run.json names the next one, and every live file once the
+ * run finished. The loader then reads run.json again, once, through the same reader, and loads
+ * that bundle instead when it is a run bundle of the same run.
  */
 export async function loadStreamTraces(source, bundle, options = {}) {
     const read = typeof source === "function" ? source : containedReader(source);
+    const maxBytes = options.maxBytes ?? RUN_ARTIFACT_MAX_BYTES;
+    let loaded = await loadEveryStream(read, bundle, maxBytes, options.liveAfter);
+    if (loaded.refused.some((error) => error instanceof LiveFileUnreadableError)) {
+        const current = await rereadBundle(read, bundle.runId);
+        if (current !== undefined)
+            loaded = await loadEveryStream(read, current, maxBytes, options.liveAfter);
+    }
+    for (const file of loaded.files)
+        options.onTrace?.(file.path, file.bytes);
+    return { bundle: loaded.bundle, refused: loaded.refused, live: loaded.live };
+}
+/** run.json as it is now, when it is a run bundle of run `runId`. */
+async function rereadBundle(read, runId) {
+    const file = await read(RUN_BUNDLE_FILE, RUN_ARTIFACT_MAX_BYTES);
+    if ("refused" in file)
+        return undefined;
+    try {
+        const value = JSON.parse(file.bytes.toString("utf8"));
+        return isRunBundle(value) && value.runId === runId ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function loadEveryStream(read, bundle, maxBytes, liveAfter) {
     const owners = new Map();
     for (const stream of bundle.streams)
         if (isRecord(stream.trace)) {
@@ -198,14 +324,17 @@ export async function loadStreamTraces(source, bundle, options = {}) {
         }
     const streams = [];
     const refused = [];
+    const files = [];
+    const live = [];
     for (const stream of bundle.streams) {
         try {
             const reason = bundleRefusal(bundle, stream, owners);
             if (reason !== undefined)
                 throw new StreamTraceRefusedError(stream.id, reason);
-            const loaded = await readStreamTrace(read, stream, options.maxBytes ?? RUN_ARTIFACT_MAX_BYTES);
-            if (loaded.bytes !== undefined)
-                options.onTrace?.(stream.trace.path, loaded.bytes);
+            const loaded = await readStreamTrace(read, stream, maxBytes, liveAfter);
+            files.push(...loaded.files);
+            if (loaded.live !== undefined)
+                live.push(loaded.live);
             streams.push(loaded.stream);
         }
         catch (error) {
@@ -215,7 +344,7 @@ export async function loadStreamTraces(source, bundle, options = {}) {
             streams.push(stream);
         }
     }
-    return { bundle: { ...bundle, streams }, refused };
+    return { bundle: { ...bundle, streams }, refused, files, live };
 }
 /**
  * A loaded bundle as a reader that shows a run presents it. A refused stream keeps run.json's

package/dist/run/streams.d.ts

@@ -154,6 +154,18 @@ export interface StreamTraceIndex {
     items: number;
     screenshots: number;
 }
+/**
+ * A v3 run.json's index of a running participant's live file (src/run/live-items.ts): its path
+ * `live/<position>.<generation>.ndjson`, the generation, and the prefix written so far, as its item
+ * (line) count, byte count and sha256. The file only grows, so the prefix stays as indexed.
+ */
+export interface LiveItemsIndex {
+    path: string;
+    generation: number;
+    items: number;
+    bytes: number;
+    sha256: string;
+}
 /** The original participant-facing assignment, before runtime access/coordination details. */
 export interface RunParticipantAssignment {
     mission: string;
@@ -163,6 +175,15 @@ export interface RunParticipantAssignment {
         goal: string;
     }>;
 }
+/** One file humanish copied onto a participant's desktop before it started (participants[].files). */
+export interface RunDesktopFile {
+    /** Where it landed, relative to the desktop user's home folder. */
+    as: string;
+    /** Its size in bytes, confirmed on the desktop. */
+    size: number;
+    /** The sha256 of the bytes humanish copied, 64 hex characters. */
+    sha256: string;
+}
 export interface RunStream {
     id: string;
     simId: string;
@@ -220,6 +241,13 @@ export interface RunStream {
     };
     /** Truthful screen/window/viewport evidence for hosted desktop browser participants. */
     desktopGeometry?: RunDesktopGeometry;
+    /** The files copied onto this participant's desktop before it started. Never their contents. */
+    desktopFiles?: RunDesktopFile[];
+    /**
+     * The participant's time zone (participants[].clock, else actor.clock): its turns gave the time
+     * in it, and its hosted browser ran in it. Absent when it had none.
+     */
+    timeZone?: string;
     terminal?: {
         title: string;
         format: "ansi" | "plain";
@@ -260,10 +288,11 @@ export interface RunStream {
      * grow. It is deliberately not an ActorTrace: a running participant has no final status,
      * completionReason, or completedAt, and this shape cannot claim them. Present only on
      * `inProgress` bundles; the final write replaces it with the real `actor` and never
-     * carries it.
+     * carries it. A v3 run.json holds `humanish.live-actor.v2` with `itemsFile` in place of `items`;
+     * the trace loader (src/run/stream-trace.ts) reads the file and puts the items back.
      */
     liveActor?: {
-        schema: "humanish.live-actor.v1";
+        schema: "humanish.live-actor.v1" | "humanish.live-actor.v2";
         executionProfile?: ActorTrace["executionProfile"];
         providerRequests?: ActorTrace["providerRequests"];
         historyTurnsOmitted?: number;
@@ -273,6 +302,8 @@ export interface RunStream {
         /** When this flush was written (ISO-8601). */
         updatedAt: string;
         items: ActorTraceItem[];
+        /** In a v3 run.json, in place of `items`: the live file that holds them. */
+        itemsFile?: LiveItemsIndex;
     };
     completion?: RunStreamCompletion;
     recording?: RunDesktopRecording;

package/dist/study/arrivals.d.ts

@@ -8,41 +8,58 @@ export declare const LATEST_START_AFTER_MS: number;
 export declare function isStartAfterMs(value: unknown): value is number;
 /** How long before its end a participant is told the time left, unless it declares `windDownMs`. */
 export declare const DEFAULT_WIND_DOWN_MS: number;
-/** A participant's declared window: when it starts and when it ends, on the run's clock. */
+/**
+ * A participant's declared window: when it starts, and when it ends on the run's clock
+ * (`endAfterMs`) or at the latest after its own session started (`maxSessionMs`).
+ */
 export interface ParticipantWindow {
     readonly id?: string;
     readonly startAfterMs?: number;
     readonly endAfterMs?: number;
+    readonly maxSessionMs?: number;
     readonly windDownMs?: number;
 }
 /**
  * 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 declare function windowReason(entry: {
     readonly id?: string;
     readonly startAfterMs?: number;
     readonly endAfterMs?: unknown;
+    readonly maxSessionMs?: unknown;
     readonly windDownMs?: unknown;
 }, path: string): string | 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`.
+ * A participant's session budget: with a declared end, its window plus SCHEDULED_END_ROOM_MS, and
+ * with a cap, the cap plus the same room, in place of the study's `sessionMs` (execution.timeoutMs
+ * or its default); else `sessionMs`.
  */
 export declare function participantSessionMs(participant: ParticipantWindow, sessionMs: number): number;
 /**
- * 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.
+ * When a participant's session ends: at a time on the run's clock, or at the latest a time after
+ * its own session starts, which the route reads when the session starts.
  */
-export declare function scheduledEndAt(participant: ParticipantWindow, scheduledAt: number): {
+export type ParticipantEnd = {
+    readonly kind: "scheduled_end";
     readonly atMs: number;
     readonly windDownMs: number;
-} | undefined;
+} | {
+    readonly kind: "session_cap";
+    readonly afterMs: number;
+    readonly windDownMs: number;
+};
+/**
+ * How a participant that was due at `scheduledAt` (runOnSchedule's ScheduledStart) ends, or
+ * undefined when it declares neither an end nor a cap. A participant that waited for a slot still
+ * ends at its declared time, and still gets its whole cap.
+ */
+export declare function participantEnd(participant: ParticipantWindow, scheduledAt: number): ParticipantEnd | undefined;
 /**
- * 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
+ * Why the sandbox of the first participant whose window or cap 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).
  */
 export declare function windowDeadlineRefusal(participants: readonly ParticipantWindow[], sandbox: {
@@ -50,8 +67,9 @@ export declare function windowDeadlineRefusal(participants: readonly Participant
     readonly headroomMs: number;
 }, ceilingMs: number): string | 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 its session budget.
  */
 export declare function describeWindows(participants: readonly ParticipantWindow[], sessionMs: number): string | undefined;
 /** The refusal of a start offset that is not one, naming its `field`. */

package/dist/study/arrivals.js

@@ -32,13 +32,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,54 +58,75 @@ 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`.
+ * A participant's session budget: with a declared end, its window plus SCHEDULED_END_ROOM_MS, and
+ * with a cap, the cap plus the same room, in place of the study's `sessionMs` (execution.timeoutMs
+ * or its default); else `sessionMs`.
  */
 export function participantSessionMs(participant, sessionMs) {
+    const windowMs = declaredWindowMs(participant);
+    return windowMs === undefined ? sessionMs : windowMs + SCHEDULED_END_ROOM_MS;
+}
+/** How long a participant with a declared end or cap may work, or undefined without either. */
+function declaredWindowMs(participant) {
+    if (participant.maxSessionMs !== undefined)
+        return participant.maxSessionMs;
     if (participant.endAfterMs === undefined)
-        return sessionMs;
-    return participant.endAfterMs - (participant.startAfterMs ?? 0) + SCHEDULED_END_ROOM_MS;
+        return undefined;
+    return participant.endAfterMs - (participant.startAfterMs ?? 0);
 }
 /**
- * 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.
+ * How a participant that was due at `scheduledAt` (runOnSchedule's ScheduledStart) ends, or
+ * undefined when it declares neither an end nor a cap. A participant that waited for a slot still
+ * ends at its declared time, and still gets its whole cap.
  */
-export function scheduledEndAt(participant, scheduledAt) {
+export function participantEnd(participant, scheduledAt) {
+    const windDownMs = participant.windDownMs ?? DEFAULT_WIND_DOWN_MS;
+    if (participant.maxSessionMs !== undefined)
+        return { kind: "session_cap", afterMs: participant.maxSessionMs, windDownMs };
     if (participant.endAfterMs === undefined)
         return undefined;
     return {
+        kind: "scheduled_end",
         atMs: scheduledAt - (participant.startAfterMs ?? 0) + participant.endAfterMs,
-        windDownMs: participant.windDownMs ?? DEFAULT_WIND_DOWN_MS,
+        windDownMs,
     };
 }
 /**
- * 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
+ * Why the sandbox of the first participant whose window or cap 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).
  */
 export function windowDeadlineRefusal(participants, sandbox, ceilingMs) {
     const inMinutes = (ms) => Math.round(ms / 60_000);
     for (const participant of participants) {
-        if (participant.endAfterMs === undefined)
+        if (declaredWindowMs(participant) === undefined)
             continue;
         const deadlineMs = participantSessionMs(participant, sandbox.sessionMs) + sandbox.headroomMs;
         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 = participant.maxSessionMs === undefined
+            ? `works from +${formatDuration(participant.startAfterMs ?? 0)} to +${formatDuration(participant.endAfterMs ?? 0)}`
+            : `may work for up to ${formatDuration(participant.maxSessionMs)}`;
+        const window = participant.maxSessionMs === undefined ? "window" : "cap";
+        return `${name} ${works}, 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)}`;
     }
     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 its session budget.
  */
 export function describeWindows(participants, sessionMs) {
-    if (!participants.some((participant) => participant.endAfterMs !== undefined))
+    if (!participants.some((participant) => declaredWindowMs(participant) !== undefined))
         return undefined;
     const windows = participants.map((participant) => {
         const start = `${participant.id ?? "participant"} from +${formatDuration(participant.startAfterMs ?? 0)}`;
+        if (participant.maxSessionMs !== undefined) {
+            const told = Math.max(0, participant.maxSessionMs - (participant.windDownMs ?? DEFAULT_WIND_DOWN_MS));
+            return `${start} until it ends itself or for up to ${formatDuration(participant.maxSessionMs)}, told the time left from ${formatDuration(told)} into its session`;
+        }
         if (participant.endAfterMs === undefined)
             return `${start} for up to ${formatDuration(sessionMs)}`;
         const told = Math.max(participant.startAfterMs ?? 0, participant.endAfterMs - (participant.windDownMs ?? DEFAULT_WIND_DOWN_MS));

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

@@ -1,8 +1,9 @@
 import type { DwellWindow } from "../actors/stop-conditions.js";
-/** One participant as the plan has it: when it starts and ends, and its dwell window. */
+/** One participant as the plan has it: when it starts and ends, its cap, and its dwell window. */
 export interface EstimatedParticipant {
     readonly startAfterMs?: number;
     readonly endAfterMs?: number;
+    readonly maxSessionMs?: number;
     readonly limits: {
         readonly dwell?: DwellWindow;
     };
@@ -33,10 +34,10 @@ 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;
 /**

package/dist/study/bundle-estimate.js

@@ -48,26 +48,31 @@ const RATES = Object.freeze({
 const MIB = 1024 * 1024;
 /**
  * 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 function estimateBundle(participants, sessionMs) {
     let turns = 0;
     let frames = 0;
     let longestWindowMs = 0;
-    const openMs = Math.min(sessionMs, RATES.openSessionMs);
+    // The longest any participant without an end is counted, for the messages.
+    let openMs = Math.min(sessionMs, RATES.openSessionMs);
     for (const participant of participants) {
         const windowMs = participant.endAfterMs === undefined
             ? undefined
             : participant.endAfterMs - (participant.startAfterMs ?? 0);
+        const budgetMs = windowMs ?? participant.maxSessionMs ?? sessionMs;
+        const countedMs = windowMs ?? Math.min(budgetMs, RATES.openSessionMs);
         if (windowMs !== undefined)
             longestWindowMs = Math.max(longestWindowMs, windowMs);
-        turns += Math.ceil((windowMs ?? openMs) / (RATES.secondsPerTurn * 1000));
+        else
+            openMs = Math.max(openMs, countedMs);
+        turns += Math.ceil(countedMs / (RATES.secondsPerTurn * 1000));
         const dwell = participant.limits.dwell;
         if (dwell !== undefined)
-            frames += Math.floor(Math.min(dwell.ms, windowMs ?? sessionMs) / dwell.everyMs) + 1;
+            frames += Math.floor(Math.min(dwell.ms, budgetMs) / dwell.everyMs) + 1;
     }
     const count = participants.length;
     const runFileBytes = RATES.runBytes +

package/dist/study/desktop-files.d.ts

@@ -0,0 +1,37 @@
+import type { StudyParseFailure, StudyParticipantFile } from "./types.js";
+/**
+ * Where `participants[].files` act: the hosted desktop of an independent computer-use participant.
+ * The parser's unread-field check and the route planners give this reason.
+ */
+export declare const DESKTOP_FILES_ROUTE_REASON = "files are copied onto a hosted computer-use desktop; needs route: computer-use with execution.target: e2b-desktop";
+/** A participant's `files` list: each entry's `from` and `as`. */
+export declare function parseParticipantFiles(raw: unknown, field: string): {
+    ok: true;
+    value: StudyParticipantFile[] | undefined;
+} | StudyParseFailure;
+/** One file read on this machine for a participant's desktop. */
+export interface DesktopFile {
+    /** Where it lands, relative to the desktop user's home folder. */
+    readonly as: string;
+    /** The file's bytes, shared by every participant that receives it and uploaded as they are. */
+    readonly data: ArrayBuffer;
+    readonly size: number;
+    /** The sha256 of `data`, 64 hex characters. */
+    readonly sha256: string;
+}
+type DesktopFilesRead = {
+    readonly ok: true;
+    readonly files: ReadonlyMap<string, readonly DesktopFile[]>;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Read every participant's declared files from `folder`, the folder that holds the study file, and
+ * return them by participant id. Runs before any sandbox exists, so a refusal costs nothing.
+ */
+export declare function readDesktopFiles(folder: string, participants: readonly {
+    readonly id: string;
+    readonly files?: readonly StudyParticipantFile[];
+}[]): Promise<DesktopFilesRead>;
+export {};