humanish 0.125.0 → 0.127.0

package/dist/run/stream-trace.js

@@ -8,7 +8,7 @@ import { createHash } from "node:crypto";
 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, liveItemsFromBytes, } from "./live-items.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. */
@@ -87,10 +87,10 @@ export function splitStreamTraces(bundle) {
     return { bundle: { ...bundle, schema: RUN_BUNDLE_SCHEMA, streams }, files };
 }
 function containedReader(runPaths) {
-    return async (relativePath, maxBytes, length) => {
+    return async (relativePath, maxBytes, length, start) => {
         const read = length === undefined
             ? await readContainedRegularFile(runPaths, relativePath, maxBytes)
-            : await readContainedPrefix(runPaths, relativePath, length);
+            : await readContainedPrefix(runPaths, relativePath, length, start);
         if (read.status === "missing")
             return { refused: `${relativePath} is missing` };
         if (read.status === "refused")
@@ -152,7 +152,7 @@ class LiveFileUnreadableError extends StreamTraceRefusedError {
  * 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) {
+async function readLiveItems(read, stream, maxBytes, liveAfter) {
     const live = stream.liveActor;
     if (live === undefined || isInlineLiveActor(live))
         return { stream };
@@ -168,6 +168,15 @@ async function readLiveItems(read, stream, maxBytes) {
         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 LiveFileUnreadableError(stream.id, file.refused);
@@ -175,17 +184,38 @@ async function readLiveItems(read, stream, maxBytes) {
     const joined = liveItemsFromBytes(file.bytes.subarray(0, index.bytes), index);
     if ("refused" in joined)
         return refuse(joined.refused);
-    const { itemsFile: _index, ...summary } = live;
     return {
         stream: { ...stream, liveActor: { ...summary, items: joined.items } },
-        live: { path: index.path, bytes: file.bytes.subarray(0, index.bytes) },
+        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) {
+async function readStreamTrace(read, stream, maxBytes, liveAfter) {
     const files = [];
     let joined = stream;
     if (stream.trace !== undefined) {
@@ -196,10 +226,10 @@ async function readStreamTrace(read, stream, maxBytes) {
         joined = joinTrace(stream, file.bytes);
         files.push({ path: stream.trace.path, bytes: file.bytes });
     }
-    const live = await readLiveItems(read, joined, maxBytes);
-    if (live.live !== undefined)
-        files.push(live.live);
-    return { stream: live.stream, files };
+    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
@@ -249,6 +279,11 @@ function bundleRefusal(bundle, stream, owners) {
  * 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
@@ -257,15 +292,15 @@ function bundleRefusal(bundle, stream, owners) {
 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);
+    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);
+            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 };
+    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) {
@@ -280,7 +315,7 @@ async function rereadBundle(read, runId) {
         return undefined;
     }
 }
-async function loadEveryStream(read, bundle, maxBytes) {
+async function loadEveryStream(read, bundle, maxBytes, liveAfter) {
     const owners = new Map();
     for (const stream of bundle.streams)
         if (isRecord(stream.trace)) {
@@ -290,13 +325,16 @@ async function loadEveryStream(read, bundle, maxBytes) {
     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, maxBytes);
+            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) {
@@ -306,7 +344,7 @@ async function loadEveryStream(read, bundle, maxBytes) {
             streams.push(stream);
         }
     }
-    return { bundle: { ...bundle, streams }, refused, files };
+    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

@@ -175,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;
@@ -232,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";

package/dist/study/arrivals.d.ts

@@ -6,54 +6,118 @@ import type { RunParticipantArrival } from "../run/bundle.js";
 export declare const LATEST_START_AFTER_MS: number;
 /** Whether `value` is a start offset humanish runs: whole milliseconds from 0 to 24 hours. */
 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. */
-export interface ParticipantWindow {
-    readonly id?: string;
+/**
+ * When a participant starts and how its session ends, resolved once from its participants entry
+ * when the plan builds the participant (participantSchedule). The plan, `study check`, the bundle
+ * estimate and the route read a participant's time from here.
+ */
+export interface ParticipantSchedule {
+    /** Its declared start, in ms after the run starts its participants; absent, with the run. */
     readonly startAfterMs?: number;
-    readonly endAfterMs?: number;
-    readonly windDownMs?: number;
+    /**
+     * How its session ends, when it declares `endAfterMs` or `maxSessionMs`. Without either it works
+     * up to the study's session budget.
+     */
+    readonly end?: ScheduleEnd;
+}
+/**
+ * A declared end. A `scheduled_end` is `endAfterMs` on the run's clock and holds the participant
+ * until then; a `session_cap` is `maxSessionMs` from the start of the participant's own session,
+ * which it may end sooner. `windowMs` is how long it may work: from its start to its end, or its
+ * cap. `windDownMs` is how long before the end each turn tells it the time left. `sessionMs` is its
+ * session budget and how long it holds a slot: the window plus SCHEDULED_END_ROOM_MS.
+ */
+type ScheduleEnd = {
+    readonly windowMs: number;
+    readonly windDownMs: number;
+    readonly sessionMs: number;
+} & ({
+    readonly kind: "scheduled_end";
+    readonly endAfterMs: number;
+} | {
+    readonly kind: "session_cap";
+});
+/** A participant as the schedule's readers name it. */
+export interface ScheduledParticipant {
+    readonly id: string;
+    readonly schedule: ParticipantSchedule;
 }
 /**
  * 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`.
+ * The schedule of a participants entry that windowReason accepts. A cap wins over an end, which
+ * windowReason refuses beside it anyway.
  */
-export declare function participantSessionMs(participant: ParticipantWindow, sessionMs: number): number;
+export declare function participantSchedule(entry: {
+    readonly startAfterMs?: number;
+    readonly endAfterMs?: number;
+    readonly maxSessionMs?: number;
+    readonly windDownMs?: number;
+}): ParticipantSchedule;
+/**
+ * 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 declare function startingWithTheRun(schedule: ParticipantSchedule): ParticipantSchedule;
+/**
+ * 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 declare function participantSession(schedule: ParticipantSchedule, study: {
+    readonly sessionMs: number;
+    readonly sandboxMs: number;
+}): {
+    sessionMs: number;
+    sandboxMs: 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 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 declare function participantEnd(schedule: ParticipantSchedule, 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
- * route adds to a session for setup and teardown (sandboxHeadroomMs).
+ * 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 declare function windowDeadlineRefusal(participants: readonly ParticipantWindow[], sandbox: {
+export declare function windowDeadlineRefusal(participants: readonly ScheduledParticipant[], study: {
     readonly sessionMs: number;
-    readonly headroomMs: number;
+    readonly sandboxMs: 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 the study's
+ * `sessionMs`.
  */
-export declare function describeWindows(participants: readonly ParticipantWindow[], sessionMs: number): string | undefined;
+export declare function describeWindows(participants: readonly ScheduledParticipant[], sessionMs: number): string | undefined;
 /** The refusal of a start offset that is not one, naming its `field`. */
 export declare function startAfterMessage(field: string): string;
 /**
@@ -94,13 +158,13 @@ export interface StartQueue {
     readonly ownSlot?: number;
 }
 /**
- * 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 declare function planArrivals(offsets: readonly (number | undefined)[], queue: StartQueue, sessionsMs?: readonly number[]): ArrivalPlan;
+export declare function planArrivals(schedules: readonly ParticipantSchedule[], queue: StartQueue): ArrivalPlan;
 /**
  * The plan's schedule, after a "schedule:" label: the first and last start, and how many run at
  * once at the most.
@@ -110,13 +174,19 @@ export declare function describeArrivals(arrivals: ArrivalPlan): string;
  * 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 declare function planStarts(participants: readonly ParticipantWindow[], queue: StartQueue, lowered: string | undefined): {
+export declare function planStarts(participants: readonly ScheduledParticipant[], queue: StartQueue, lowered: string | undefined): {
     arrivals: ArrivalPlan;
     warnings: string[];
 };
+/**
+ * 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 declare function pastEndReason(end: ParticipantEnd | undefined, nowMs: number): string | undefined;
 /**
  * Why a sandbox that serves the app until the last participant ends, the provisioned shared
  * world's subject sandbox, cannot live that long under `ceilingMs`; undefined when it can. Its
@@ -159,3 +229,4 @@ export declare function runOnSchedule<T, R>(items: readonly T[], options: {
     readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     readonly signal?: AbortSignal;
 }, start: (item: T, index: number, scheduled: ScheduledStart) => Promise<R>): Promise<R[]>;
+export {};