humanish 0.118.0 → 0.120.0

package/dist/routes/shared-world/plan.js

@@ -14,6 +14,7 @@ import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, ex
 import { unpricedCapCheck } from "../../study/requirements.js";
 import { participantsAtOnce, sandboxDeadlineRefusal, sandboxHeadroomMs, } from "../../substrates/e2b/lifetime.js";
 import { boundedConcurrency } from "../computer-use/participant-runs.js";
+import { describeArrivals, planStarts, servedScheduleRefusal, } from "../../study/arrivals.js";
 /** The registered descriptor for a planned actor; planSharedWorldStudy checked the registry. */
 export function sharedWorldDescriptorOf(actorType) {
     const descriptor = actorRegistry[actorType];
@@ -96,53 +97,31 @@ export function planSharedWorldStudy(config, input) {
     const plane = planeOf(config);
     if (plane === undefined)
         throw new Error("shared-world validation admitted a plane it cannot plan");
-    // Every participant's desktop and, on the provisioned plane, the app's own sandbox share the E2B
-    // plan's concurrent sandboxes. A shared world needs two participants live together.
-    const declared = config.execution?.concurrency;
-    const n = plane.participants.length;
-    const atOnce = participantsAtOnce({
-        concurrency: boundedConcurrency(declared, n),
-        declared: declared !== undefined,
-        participants: n,
-        alongside: plane.kind === "provisioned" ? 1 : 0,
-        minimum: 2,
-    }, input.concurrentSandboxes);
-    if (!atOnce.ok)
-        return refuse(invalid, atOnce.message, actor);
     const sessionTimeoutMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(plane, ceiling.ms);
-    // The run's longest deadline: on the provisioned plane the subject sandbox, which serves the app
-    // until every participant ends; on the external-public plane each participant's own sandbox.
-    const deadlineReason = sandboxDeadlineRefusal(plane.kind === "provisioned"
-        ? {
-            name: "the subject sandbox, which serves the app until every participant ends",
-            sessionMs: sessionTimeoutMs,
-            sessionDeclared: config.execution?.timeoutMs !== undefined,
-            servedSubject: { seed: plane.subject.state.seed ?? [] },
-        }
-        : {
-            name: "each participant's sandbox",
-            sessionMs: sessionTimeoutMs,
-            sessionDeclared: config.execution?.timeoutMs !== undefined,
-        }, ceiling.ms);
+    const starts = startsOf(plane, config.execution?.concurrency, input.concurrentSandboxes, sessionTimeoutMs);
+    if (!starts.ok)
+        return refuse(invalid, starts.message, actor);
+    const { arrivals, warnings } = starts;
+    const deadlineReason = deadlineReasonOf(plane, arrivals, {
+        sessionDeclared: config.execution?.timeoutMs !== undefined,
+        ceilingMs: ceiling.ms,
+    });
     if (deadlineReason)
         return refuse(invalid, deadlineReason, actor);
     const brain = brainOf(config, false);
     if (brain.kind === "caller")
         throw new Error("a shared-world participant has no caller brain");
-    const base = planBase(config, {
-        dryRun: input.dryRun,
-        analysis,
-        participants: n,
-    });
+    const base = planBase(config, { dryRun: input.dryRun, analysis });
     return {
         ok: true,
         plan: {
             ...base,
-            ...(atOnce.lowered === undefined ? {} : { warnings: [atOnce.lowered] }),
+            ...(warnings.length === 0 ? {} : { warnings }),
             route: "shared-world",
             actor,
             plane,
-            concurrency: atOnce.count,
+            concurrency: starts.count,
+            arrivals,
             sessionTimeoutMs,
             brain,
             caps: planCaps(config),
@@ -164,6 +143,72 @@ export function planSharedWorldStudy(config, input) {
         },
     };
 }
+/**
+ * How many participants run at once, and when each one starts. Every participant's desktop and, on
+ * the provisioned plane, the app's own sandbox share the E2B plan's concurrent sandboxes, and a
+ * shared world needs two participants live together. On the external-public plane the host runs
+ * on a slot of its own and the others queue for the rest (external-public.ts).
+ */
+function startsOf(plane, declared, limit, sessionMs) {
+    const n = plane.participants.length;
+    const atOnce = participantsAtOnce({
+        concurrency: boundedConcurrency(declared, n),
+        declared: declared !== undefined,
+        participants: n,
+        alongside: plane.kind === "provisioned" ? 1 : 0,
+        minimum: 2,
+    }, limit);
+    if (!atOnce.ok)
+        return atOnce;
+    const hostIndex = plane.participants.findIndex((participant) => participant.host === true);
+    const queue = {
+        slots: atOnce.count,
+        sessionMs,
+        ...(plane.kind === "external-public" && hostIndex >= 0 ? { ownSlot: hostIndex } : {}),
+    };
+    return {
+        ok: true,
+        count: atOnce.count,
+        ...planStarts(plane.participants, queue, atOnce.lowered),
+    };
+}
+/**
+ * Why the run's longest-lived sandbox cannot live as long as the plan needs. On the provisioned
+ * plane that is the subject sandbox, which serves the app for one session and then until the last
+ * participant ends; on the external-public plane, each participant's own sandbox, created at its
+ * start.
+ */
+function deadlineReasonOf(plane, arrivals, options) {
+    const { sessionDeclared, ceilingMs } = options;
+    const sessionMs = arrivals.sessionMs;
+    if (plane.kind !== "provisioned")
+        return sandboxDeadlineRefusal({ name: "each participant's sandbox", sessionMs, sessionDeclared }, ceilingMs);
+    const seed = plane.subject.state.seed ?? [];
+    return (sandboxDeadlineRefusal({
+        name: "the subject sandbox, which serves the app until every participant ends",
+        sessionMs,
+        sessionDeclared,
+        servedSubject: { seed },
+    }, ceilingMs) ?? servedScheduleRefusal(arrivals, { sessionMs, seed }, ceilingMs));
+}
+/**
+ * The schedule lines a shared-world run prints before it creates anything, when the study declares
+ * `participants[].startAfterMs`: the schedule, and the worst case in sandbox-minutes, which counts
+ * every participant's sandbox (its session plus the teardown buffer) and on the provisioned plane
+ * the app's sandbox until the last participant ends.
+ */
+export function sharedWorldScheduleLines(plan) {
+    const participants = plan.plane.participants.length;
+    const participantMs = participants * (plan.sessionTimeoutMs + sandboxHeadroomMs());
+    const subjectMs = plan.plane.kind === "provisioned"
+        ? plan.arrivals.lastEndMs + sandboxHeadroomMs({ seed: plan.plane.subject.state.seed ?? [] })
+        : 0;
+    return [
+        `humanish shared-world plan (${plan.studyId}): ${participants} participants, at most ${plan.concurrency} at once; worst-case ~${Math.round((participantMs + subjectMs) / 60_000)} sandbox-minutes total${plan.dryRun ? " (dry-run: $0)" : ""}.`,
+        `  schedule: ${describeArrivals(plan.arrivals)}`,
+        "",
+    ].join("\n");
+}
 // The default per-participant session budget is derived from the plane. On a provisioned plane the
 // binding constraint is the subject sandbox (it must outlive every participant: timeoutMs +
 // provisioning + seeding + teardown buffer, under the sandbox ceiling), so the derivation hands each

package/dist/routes/shared-world/provisioned.js

@@ -6,7 +6,7 @@ import { buildOriginMap } from "../../comms/capture-surface.js";
 import { deployCommsCatch, refreshInboxSurface, writeInboxSurface, } from "../../comms/sandbox-catch.js";
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { liveObserverResult } from "../../observer/live.js";
-import { mapWithConcurrency } from "../../run/concurrency.js";
+import { runOnSchedule } from "../../study/arrivals.js";
 import { provisionCloneSubject } from "../../subject/clone.js";
 import { provisionLocalTreeSubject } from "../../subject/local-tree.js";
 import { defaultSharedWorldPhaseSink } from "../../subject/steps.js";
@@ -96,7 +96,7 @@ class SubjectPlane {
         this.setup.stateSnapshots.push({ timestamp, digest: snapshot.digest });
     }
     async acquire() {
-        const { plan, deps, env, requestTimeoutMs, timeoutMs } = this.ctx;
+        const { plan, deps, env, requestTimeoutMs } = this.ctx;
         const { subjectEnvNames, commsEnv } = this.setup;
         const subjectModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
         // The one subject sandbox: headless service host (no GUI participant). The subject env is
@@ -107,7 +107,9 @@ class SubjectPlane {
             module: subjectModule,
             apiKey: this.ctx.e2bApiKey,
             requestTimeoutMs,
-            sessionTimeoutMs: timeoutMs,
+            // The app serves until the last participant ends, which a late start or a wait for a free
+            // slot puts past one session.
+            sessionTimeoutMs: plan.arrivals.lastEndMs,
             seed: planeStateOf(plan)?.seed ?? [],
             metadata: {
                 ...CONCURRENT_SHARED_WORLD_PROVIDER_METADATA,
@@ -380,15 +382,20 @@ async function publishInProgress(plane, ctx, live, setup) {
     }
     startParticipantFlush(ctx, live, inProgressBundle);
 }
-// Launch N actor sandboxes concurrently and independently (runCuaParticipant + mapWithConcurrency;
-// runCuaParticipants would add a pipeline gate and fail-fast). Each actor's window is measured on the
-// one orchestrator clock.
+// Launch N actor sandboxes independently on the study's schedule (runCuaParticipant +
+// runOnSchedule; runCuaParticipants would add a pipeline gate and fail-fast). Each actor's window is
+// measured on the one orchestrator clock.
 function runParticipants(plane, ctx, live, setup) {
     const { now } = ctx;
     const participants = ctx.plan.plane.participants;
     const { commsEmail } = setup;
     const baseActorDeps = participantRunDeps(ctx, live, ctx.scrubKnownValues);
-    return mapWithConcurrency(ctx.actorSpecs, Math.max(1, ctx.concurrency), async (spec, i) => {
+    const schedule = {
+        startAfterMs: (spec) => spec.planned.startAfterMs,
+        slots: Math.max(1, ctx.concurrency),
+        now,
+    };
+    return runOnSchedule(ctx.actorSpecs, schedule, async (spec, i, { scheduledAt }) => {
         const route = resolveActorEntryUrl(plane.getHostUrl, participants[i]?.entry);
         // Tell this persona its (getHost-reachable) inbox URL, but only when comms is live and this participant
         // has a declared recipient it can actually receive mail into (else it would stall on an empty
@@ -400,7 +407,7 @@ function runParticipants(plane, ctx, live, setup) {
         const startedAt = now();
         const outcome = await runCuaParticipant(actorSpec, { ...baseActorDeps, appUrl: route });
         const endedAt = now();
-        return { spec, outcome, startedAt, endedAt, route };
+        return { spec, outcome, scheduledAt, startedAt, endedAt, route };
     });
 }
 export async function runProvisionedPlane(ctx, live, setup) {

package/dist/routes/shared-world/route.js

@@ -23,7 +23,7 @@
 // per-delta→actor field, so causation under concurrency is structurally inexpressible.
 //
 // Capability and proof: the deterministic $0 gate proves the plumbing + the claims-match-mechanism
-// contract: the real mapWithConcurrency produces genuinely overlapping laneWindows (a rendezvous
+// contract: the real start queue (runOnSchedule) produces genuinely overlapping laneWindows (a rendezvous
 // latch in the fake session forces two participant fns in-flight while the real orchestrator clock
 // measures the windows). Every generated bundle describes only its own observations; no one run
 // establishes scale, repeatability, or adopter-harness replacement.
@@ -38,7 +38,7 @@ import {} from "../../run/run.js";
 import { RunSecrets } from "../../run/secrets.js";
 import { admitRoute, completeRefusalAnalysis, } from "../../run/route-shell.js";
 import { runExternalPublicPlane } from "./external-public.js";
-import { sharedWorldDescriptorOf } from "./plan.js";
+import { sharedWorldDescriptorOf, sharedWorldScheduleLines, } from "./plan.js";
 import { runProvisionedPlane } from "./provisioned.js";
 import { concurrentStudyFailure, finishConcurrentRun } from "./result.js";
 import { prepareConcurrentRun } from "./setup.js";
@@ -143,6 +143,9 @@ async function runPlanInScope(plan, input, config, scope) {
     const deps = input.deps ?? {};
     const env = input.env ?? process.env;
     const fail = sharedWorldFailure(plan, input);
+    // Before any sandbox or provider call, as computer use prints its participant plan.
+    if (plan.arrivals.declared)
+        process.stderr.write(sharedWorldScheduleLines(plan));
     const descriptor = sharedWorldDescriptorOf(plan.actor);
     const planeClass = plan.plane.kind === "external-public" ? "external-public" : "provisioned-getHost";
     // The provisioned plane's subject; the external-public plane has none.

package/dist/routes/shared-world/types.d.ts

@@ -138,6 +138,8 @@ export interface ConcurrentSharedWorldStudyResult extends AutomaticAnalysisResul
 export interface ActorRunResult {
     spec: DesktopParticipantRun;
     outcome: ParticipantRunOutcome;
+    /** When the schedule had it start, in epoch ms; the host of an external public app starts with the run. */
+    scheduledAt: number;
     startedAt: number;
     endedAt: number;
     route: string;

package/dist/run/bundle-shape.js

@@ -313,7 +313,16 @@ function isRunSimulation(value) {
         Array.isArray(value.streamIds) &&
         value.streamIds.every((streamId) => typeof streamId === "string") &&
         typeof value.startedAt === "string" &&
-        typeof value.updatedAt === "string");
+        typeof value.updatedAt === "string" &&
+        (value.arrival === undefined || isRunParticipantArrival(value.arrival)));
+}
+function isRunParticipantArrival(value) {
+    return (isRecord(value) &&
+        typeof value.startAfterMs === "number" &&
+        Number.isSafeInteger(value.startAfterMs) &&
+        value.startAfterMs >= 0 &&
+        (value.scheduledAt === undefined || typeof value.scheduledAt === "string") &&
+        (value.startedAt === undefined || typeof value.startedAt === "string"));
 }
 function isRunAdapterArtifact(value) {
     return (isRecord(value) &&

package/dist/run/bundle.d.ts

@@ -123,6 +123,21 @@ export interface RunSimulation {
     streamIds: string[];
     startedAt: string;
     updatedAt: string;
+    /**
+     * When a computer-use or shared-world participant was due and when it started, in a study that
+     * declares `participants[].startAfterMs`. `startAfterMs` is its offset (0 when its entry declares
+     * none), `scheduledAt` the moment the run started its participants plus that offset, and
+     * `startedAt` when its desktop was requested: later than `scheduledAt` when it waited for a free
+     * slot. A dry run records only the offset, and a participant that never started has no
+     * `startedAt`. The record's own `startedAt` above is the run's creation time.
+     */
+    arrival?: RunParticipantArrival;
+}
+/** A participant record's `arrival`. */
+export interface RunParticipantArrival {
+    startAfterMs: number;
+    scheduledAt?: string;
+    startedAt?: string;
 }
 export interface RunEvent {
     id: string;

package/dist/run/participant-records.js

@@ -29,6 +29,7 @@ export function participantRecord(ids, place, fields) {
         streamIds: [ids.streamId],
         startedAt: fields.startedAt,
         updatedAt: fields.updatedAt,
+        ...(fields.arrival === undefined ? {} : { arrival: fields.arrival }),
     };
 }
 /**

package/dist/run/route-shell.js

@@ -4,7 +4,6 @@
 // either is made here once. The preview route records no run and has no shell.
 import { completeAutomaticAnalysis } from "../analysis/automatic-completion.js";
 import { resolveAutomaticAnalysis } from "../analysis/automatic-config.js";
-import { withParticipantLimitSkip } from "../study/automatic-analysis-plan.js";
 import { runScope } from "./run.js";
 import { withTransientCommsSecrets } from "./transient-comms-secrets.js";
 /**
@@ -13,15 +12,11 @@ import { withTransientCommsSecrets } from "./transient-comms-secrets.js";
  * it takes closes the run it started, and only a run that published its final bundle is analyzed.
  */
 export async function admitRoute(shell) {
-    const complete = (input, result, finished) => 
-    // A live run of more participants than one analysis reads records the skip and starts nothing.
-    shell.analysis?.skip !== undefined && !result.dryRun
-        ? Promise.resolve(withParticipantLimitSkip(result, shell.analysis.trigger))
-        : completeAutomaticAnalysis(result, finished, shell.analysis?.config, input, {
-            ...(shell.analysis === undefined ? {} : { trigger: shell.analysis.trigger }),
-            preferLargerOutput: shell.analysis?.preferLargerOutput === true,
-            ...(shell.analysisRefusal === undefined ? {} : { refusal: shell.analysisRefusal }),
-        });
+    const complete = (input, result, finished) => completeAutomaticAnalysis(result, finished, shell.analysis?.config, input, {
+        ...(shell.analysis === undefined ? {} : { trigger: shell.analysis.trigger }),
+        preferLargerOutput: shell.analysis?.preferLargerOutput === true,
+        ...(shell.analysisRefusal === undefined ? {} : { refusal: shell.analysisRefusal }),
+    });
     const admission = await shell.admit();
     if (!admission.ok)
         return {

package/dist/run/run.js

@@ -117,13 +117,15 @@ function observerTarget(options) {
 function runPublisher(args) {
     const { options, runId, createdAt, paths, runStatus, now, admit, participantsRan } = args;
     const observer = observerTarget(options);
-    // The study's warnings join whatever events the route wrote, once, in every write.
+    // The study's warnings join whatever events the route wrote, once, in every write. A warning can
+    // quote the study file, which may name a sandbox URL a participant needs, so each goes through
+    // the redaction a run failure gets.
     const studyWarnings = (options.warnings ?? []).map((message, index) => ({
         id: `event-study-warning-${String(index + 1).padStart(3, "0")}`,
         at: createdAt,
         level: "warn",
         type: "study.warning",
-        message,
+        message: redactText(message),
     }));
     const withStudyWarnings = (events) => [
         ...events.filter((event) => !studyWarnings.some((warning) => warning.id === event.id)),

package/dist/study/arrivals.d.ts

@@ -0,0 +1,114 @@
+import type { RunParticipantArrival } from "../run/bundle.js";
+/**
+ * The latest start a study may declare: 24 hours, the longest sandbox lifetime E2B documents. It
+ * also keeps every wait under Node's timer limit of 2^31 - 1 ms, past which a timer fires at once.
+ */
+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;
+/** The refusal of a start offset that is not one, naming its `field`. */
+export declare function startAfterMessage(field: string): string;
+/**
+ * Why a roster's declared starts cannot run, or undefined. A start orders participants against
+ * each other, so it needs two or more of them, and the host of an external public app opens the
+ * session the others join, so it starts with the run.
+ */
+export declare function rosterStartsReason(roster: readonly {
+    readonly id?: string;
+    readonly startAfterMs?: number;
+    readonly host?: boolean;
+}[]): string | undefined;
+/** What the plan says about when a run's participants start, with every session at its full budget. */
+export interface ArrivalPlan {
+    /** Whether any participant declares `startAfterMs`. */
+    readonly declared: boolean;
+    /** The earliest and the latest declared start, in ms after the run starts its participants. */
+    readonly firstStartMs: number;
+    readonly lastStartMs: number;
+    /** The most participants running at once. */
+    readonly peak: number;
+    /** How many participants wait past their time for a free slot, and the longest of those waits. */
+    readonly waiting: number;
+    readonly longestWaitMs: number;
+    /** When the last session ends at the latest, in ms after the run starts its participants. */
+    readonly lastEndMs: number;
+    /** The session budget every figure above assumes each participant uses. */
+    readonly sessionMs: number;
+}
+/** How the runtime starts participants: how many run at once, and for how long at most. */
+export interface StartQueue {
+    readonly slots: number;
+    readonly sessionMs: number;
+    /**
+     * The roster index of a participant that runs on a slot of its own, outside the queue: the
+     * external-public host, which the others wait on. It counts against `slots`.
+     */
+    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.
+ */
+export declare function planArrivals(offsets: readonly (number | undefined)[], 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.
+ */
+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.
+ */
+export declare function planStarts(participants: readonly {
+    readonly startAfterMs?: number;
+}[], queue: StartQueue, lowered: string | undefined): {
+    arrivals: ArrivalPlan;
+    warnings: string[];
+};
+/**
+ * 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
+ * deadline is the schedule's `lastEndMs` plus the time to provision and seed the subject and tear
+ * it down. The session alone is checked first (sandboxDeadlineRefusal), so this names what the
+ * schedule adds: a late start or a wait for a free slot.
+ */
+export declare function servedScheduleRefusal(arrivals: ArrivalPlan, sandbox: {
+    readonly sessionMs: number;
+    readonly seed: readonly {
+        readonly timeoutMs?: number | undefined;
+    }[];
+}, ceilingMs: number): string | undefined;
+/** When a participant was due and when it started, in epoch ms. One that never started has no `startedAt`. */
+export interface ParticipantArrival {
+    readonly scheduledAt: number;
+    readonly startedAt?: number;
+}
+/** A participant's `arrival` in run.json: its offset, and on a live run when it was due and started. */
+export declare function arrivalRecord(startAfterMs: number | undefined, arrival: ParticipantArrival | undefined): RunParticipantArrival;
+/** Where a participant sits in the run's schedule when its start comes. */
+export interface ScheduledStart {
+    /** Its place in schedule order, from 0: the first participant to start has 0. */
+    readonly order: number;
+    /** Its time in epoch ms: the moment the run started its participants plus its offset. */
+    readonly scheduledAt: number;
+}
+/**
+ * Calls `start` for each item at its time, with at most `slots` calls in flight. Items start in
+ * schedule order; one whose time comes while every slot is busy waits for the next free slot. An
+ * abort of `signal` ends every wait at once, so `start` runs for the waiting items right away and
+ * decides whether to skip them. Results come back in the items' order.
+ */
+export declare function runOnSchedule<T, R>(items: readonly T[], options: {
+    readonly startAfterMs: (item: T) => number | undefined;
+    readonly slots: number;
+    /** The run's clock in epoch ms, which must advance while a start waits. Defaults to Date.now. */
+    readonly now?: () => number;
+    /** Waits `ms` or until `signal` aborts. Defaults to node:timers/promises' setTimeout. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    readonly signal?: AbortSignal;
+}, start: (item: T, index: number, scheduled: ScheduledStart) => Promise<R>): Promise<R[]>;