humanish 0.122.0 → 0.124.0

package/dist/run/streams.d.ts

@@ -142,6 +142,18 @@ export interface RunDesktopGeometry {
     /** Public-safe geometry measurement/fill warnings retained with the stream evidence. */
     warnings?: string[];
 }
+/**
+ * A stream's trace file in a v2 run.json: the actor trace with its items and the stream's
+ * screenshot entries as `artifacts`. `bytes` and `sha256` bind the file to run.json; `items` and
+ * `screenshots` are what it holds, so a reader can list them without opening it.
+ */
+export interface StreamTraceIndex {
+    path: string;
+    bytes: number;
+    sha256: string;
+    items: number;
+    screenshots: number;
+}
 /** The original participant-facing assignment, before runtime access/coordination details. */
 export interface RunParticipantAssignment {
     mission: string;
@@ -189,6 +201,12 @@ export interface RunStream {
      *  and never persisted into bundles; declared here because the served observer-data carries it
      *  and the client is typed against this contract. */
     liveEnded?: boolean;
+    /**
+     * Set by a reader that shows the run (displayedTraces in src/run/stream-trace.ts) when the loader
+     * refused this participant's trace: the reason. Runtime-only and never persisted; the stream then
+     * carries none of the refused items.
+     */
+    traceUnavailable?: string;
     /**
      * Browser CSS layout viewport. Deterministic browser adapters may declare and render this
      * exactly; hosted-desktop CUA producers set it only from a runtime measurement. Historical
@@ -234,6 +252,8 @@ export interface RunStream {
         turnId?: string;
     };
     actor?: ActorTrace;
+    /** Present in a v2 run.json on each stream with an actor: where its items and screenshots are. */
+    trace?: StreamTraceIndex;
     /**
      * Mid-run partial actor evidence: the redacted trace items recorded so far,
      * flushed while a live participant is still running so the attached Observer's timeline can

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

@@ -0,0 +1,48 @@
+import type { DwellWindow } from "../actors/stop-conditions.js";
+/** One participant as the plan has it: when it starts and ends, and its dwell window. */
+export interface EstimatedParticipant {
+    readonly startAfterMs?: number;
+    readonly endAfterMs?: number;
+    readonly limits: {
+        readonly dwell?: DwellWindow;
+    };
+}
+/** A run's estimated bundle, and the scan's limit for its participants. */
+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;
+    /** Every file, screenshots included. */
+    readonly totalBytes: number;
+    /** Files and folders in the run folder, as the public-safety scan counts them. */
+    readonly entries: number;
+    /** The most entries the scan reads in a run of these participants (runEntryLimit). */
+    readonly entryLimit: number;
+    /** What the estimate assumed, for its messages. */
+    readonly basis: {
+        readonly participants: number;
+        /** Participants with a declared end, counted for their whole window, and the longest window. */
+        readonly scheduled: number;
+        readonly longestWindowMs: number;
+        /** Participants without one, and how long each is counted at most. */
+        readonly open: number;
+        readonly openMs: number;
+        readonly dwell: boolean;
+    };
+}
+/**
+ * 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.
+ */
+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.
+ */
+export declare function bundleLimitReason(estimate: BundleEstimate): string | undefined;
+/** The estimate beside the limits, for `study check`. */
+export declare function describeBundle(estimate: BundleEstimate): string;

package/dist/study/bundle-estimate.js

@@ -0,0 +1,159 @@
+// How large a computer-use run's bundle grows, estimated from its plan before anything runs, and
+// whether it would pass a limit a later command holds it to: analysis reads a run.json of at most
+// EVIDENCE_LIMITS.sourceBytes, verify reads no file larger than RUN_ARTIFACT_MAX_BYTES, and the
+// public-safety scan visits at most runEntryLimit(participants) files and folders.
+import { EVIDENCE_LIMITS } from "../analysis/analysis-limits.js";
+import { RUN_ARTIFACT_MAX_BYTES } from "../run/contained-output.js";
+import { formatDuration } from "../run/projection.js";
+import { plural } from "../run/text.js";
+import { runEntryLimit } from "../verify/scan-limit.js";
+// Measured on 2026-10-12. Live: the hosted computer-use bundles kept on the maintainer's machine,
+// 219 runs since 2026-10-01 for run.json's size (a least-squares fit gave 372 bytes a run, 14,368
+// a participant and 2,423 a turn), and for the pace the 42 participant sessions of 5 minutes or
+// more among every kept run since August. Synthetic: runStudyWith on fake desktops, with the live median
+// of about 270 characters of reasoning and message a turn, from 10 to 2,000 turns and from 1 to
+// 16 participants. An adopter's 39-minute run grew run.json about 7 KB a minute for a participant
+// working the whole window; these rates give 12.6 KB, so the estimate errs high, and a limit it
+// passes is a warning.
+const RATES = Object.freeze({
+    /** run.json bytes a minute of the one long live participant measured: the adopter's run. */
+    measuredLongRunBytesPerMinute: 7_000,
+    /** run.json bytes for the run itself: its header, study and scenario. */
+    runBytes: 400,
+    /** run.json bytes for each participant before its turns: its records, events and cost lines. */
+    participantBytes: 14_400,
+    /** run.json bytes a model turn adds. Synthetic: 2,094 to 2,125 a turn over 10 to 2,000 turns. */
+    turnBytes: 2_100,
+    /** run.json bytes a dwell frame adds. Synthetic: 6,247 for 10 frames and the frame after. */
+    frameBytes: 570,
+    /** Seconds between model turns: the median of the 42 long live sessions was 10.3. */
+    secondsPerTurn: 10,
+    /**
+     * How long a participant with no declared end is counted, at most its session budget. It ends
+     * when it finishes its mission: 90 % of 974 live sessions ended within 184 s.
+     */
+    openSessionMs: 3 * 60_000,
+    /** observer-data.json bytes beyond run.json's for each participant: 0.9 to 2.6 KB live. */
+    observerDataParticipantBytes: 2_600,
+    /** observer/index.html: the page, and a share of run.json it embeds (synthetic, 10 to 2,000 turns). */
+    observerPageBytes: 1_190_000,
+    observerPageShare: 0.62,
+    /** A desktop screenshot: the median of 249 live PNG frames was 108,565 bytes. */
+    screenshotBytes: 110_000,
+    /** Run files and folders besides the participants': run.json, status, review, events, receipts, the Observer, analysis. */
+    runEntries: 20,
+    /** A participant's entries besides its turn screenshots: its trace file, its screenshot folder, its first frame. */
+    participantEntries: 3,
+});
+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.
+ */
+export function estimateBundle(participants, sessionMs) {
+    let turns = 0;
+    let frames = 0;
+    let longestWindowMs = 0;
+    const openMs = Math.min(sessionMs, RATES.openSessionMs);
+    for (const participant of participants) {
+        const windowMs = participant.endAfterMs === undefined
+            ? undefined
+            : participant.endAfterMs - (participant.startAfterMs ?? 0);
+        if (windowMs !== undefined)
+            longestWindowMs = Math.max(longestWindowMs, windowMs);
+        turns += Math.ceil((windowMs ?? openMs) / (RATES.secondsPerTurn * 1000));
+        const dwell = participant.limits.dwell;
+        if (dwell !== undefined)
+            frames += Math.floor(Math.min(dwell.ms, windowMs ?? sessionMs) / dwell.everyMs) + 1;
+    }
+    const count = participants.length;
+    const runFileBytes = RATES.runBytes +
+        count * RATES.participantBytes +
+        turns * RATES.turnBytes +
+        frames * RATES.frameBytes;
+    const observerDataBytes = runFileBytes + count * RATES.observerDataParticipantBytes;
+    const pageBytes = RATES.observerPageBytes + Math.round(RATES.observerPageShare * runFileBytes);
+    const screenshots = count + turns + frames;
+    const scheduled = participants.filter((participant) => participant.endAfterMs !== undefined);
+    return {
+        runFileBytes,
+        largestFileBytes: Math.max(observerDataBytes, pageBytes),
+        // Each participant's trace file holds about what its stream holds in run.json.
+        totalBytes: 2 * runFileBytes + observerDataBytes + pageBytes + screenshots * RATES.screenshotBytes,
+        entries: RATES.runEntries + count * RATES.participantEntries + turns + frames,
+        entryLimit: runEntryLimit(count),
+        basis: {
+            participants: count,
+            scheduled: scheduled.length,
+            longestWindowMs,
+            open: count - scheduled.length,
+            openMs,
+            dwell: frames > 0,
+        },
+    };
+}
+/**
+ * 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.
+ */
+export function bundleLimitReason(estimate) {
+    const passed = [
+        ...(estimate.runFileBytes > EVIDENCE_LIMITS.sourceBytes
+            ? [
+                `This study's run.json may grow to about ${mib(estimate.runFileBytes)}, past the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads.`,
+            ]
+            : []),
+        ...(estimate.largestFileBytes > RUN_ARTIFACT_MAX_BYTES
+            ? [
+                `Its largest file, observer/observer-data.json, may grow to about ${mib(estimate.largestFileBytes)}, past the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads in one file.`,
+            ]
+            : []),
+        ...(estimate.entries > estimate.entryLimit
+            ? [
+                `It may hold about ${count(estimate.entries)} files and folders, past the ${count(estimate.entryLimit)} the public-safety scan reads in a run of ${plural(estimate.basis.participants, "participant")}.`,
+            ]
+            : []),
+    ];
+    if (passed.length === 0)
+        return undefined;
+    const { scheduled, longestWindowMs, open, openMs, dwell } = estimate.basis;
+    const counted = [
+        ...(scheduled > 0
+            ? [
+                `${plural(scheduled, "participant")} working their declared windows of up to ${formatDuration(longestWindowMs)}`,
+            ]
+            : []),
+        ...(open > 0
+            ? [
+                `${scheduled > 0 ? open : plural(open, "participant")} for up to ${formatDuration(openMs)} each`,
+            ]
+            : []),
+    ];
+    const changes = [
+        ...(scheduled > 0 ? ["shorten the longest windows (participants[].endAfterMs)"] : []),
+        ...(dwell ? ["shorten the dwell window (dwell.ms) or capture less often (dwell.everyMs)"] : []),
+    ];
+    const split = "split the participants across studies";
+    const advice = changes.length === 0 ? split : `${changes.join(", ")}, or ${split}`;
+    const perMinute = (RATES.turnBytes * 60) / RATES.secondsPerTurn;
+    return [
+        ...passed,
+        `The estimate counts ${counted.join(" and ")}, at a model turn every ${formatDuration(RATES.secondsPerTurn * 1000)} that adds about ${(RATES.turnBytes / 1000).toFixed(1)} KB.`,
+        `It runs high, about ${(perMinute / RATES.measuredLongRunBytesPerMinute).toFixed(1)} times the one long live run measured, so the run goes ahead.`,
+        `To stay under the limit, ${advice}.`,
+    ].join(" ");
+}
+/** The estimate beside the limits, for `study check`. */
+export function describeBundle(estimate) {
+    return `run.json about ${mib(estimate.runFileBytes)} of the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads; largest file about ${mib(estimate.largestFileBytes)} of the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads; about ${count(estimate.entries)} files and folders of the ${count(estimate.entryLimit)} the public-safety scan reads; about ${mib(estimate.totalBytes, 0)} in all. Participants with a declared end are counted for their whole window and the others for up to ${formatDuration(estimate.basis.openMs)}, at a model turn every ${formatDuration(RATES.secondsPerTurn * 1000)}.`;
+}
+function mib(bytes, digits = 1) {
+    const value = bytes / MIB;
+    return `${Number.isInteger(value) ? value : value.toFixed(digits)} MiB`;
+}
+function count(value) {
+    return value.toLocaleString("en-US");
+}

package/dist/study/doctor.js

@@ -172,6 +172,10 @@ export async function studySetupChecks(args) {
             keys: [],
             checks: [...checks, { name: "live route", ok: false, message: planned.refusal.message }],
         };
+    // A plan warning, such as a bundle estimated past a limit, is a note: the run still goes ahead.
+    for (const warning of planned.planned.plan.warnings ?? [])
+        if (!resolved.warnings.includes(warning))
+            checks.push({ name: "plan", ok: true, status: "note", message: warning });
     const requirements = planned.planned.plan.requirements;
     const keys = requiredKeys(requirements, args.keyPresent);
     // This flag controls the hosted desktop SDK check as well as its API key.

package/dist/study/plan-types.d.ts

@@ -6,6 +6,7 @@ import type { ScriptedRefusal } from "../routes/scripted/plan.js";
 import type { TerminalRefusal } from "../routes/terminal/plan.js";
 import type { RunStudyProvenance } from "../run/study-provenance.js";
 import type { ArrivalPlan } from "./arrivals.js";
+import type { BundleEstimate } from "./bundle-estimate.js";
 import type { ComputerUseRefusal } from "../routes/computer-use/plan.js";
 import type { SharedWorldRefusal } from "../routes/shared-world/plan.js";
 import type { ComputerUseParticipant, ExternalPublicParticipant, ProvisionedParticipant } from "./plan-participants.js";
@@ -275,6 +276,8 @@ export interface ScriptedPlan extends PlanBase {
 export type StudyPlan = PreviewPlan | ComputerUsePlan | SharedWorldPlan | TerminalPlan | ScriptedPlan;
 interface PlannedStudy {
     readonly plan: StudyPlan;
+    /** A computer-use plan's estimated bundle, which planStudy checked against the bundle limits. */
+    readonly bundle?: BundleEstimate;
 }
 /**
  * The error a route returns before a run starts: the route, its error code and a message. Each

package/dist/study/plan.js

@@ -9,11 +9,13 @@ import { planTerminalStudy } from "../routes/terminal/plan.js";
 import { concurrentSandboxes, sandboxCeiling, } from "../substrates/e2b/lifetime.js";
 import { localBrowserDefaults } from "../substrates/local/runtime-config.js";
 import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
+import { bundleLimitReason, estimateBundle } from "./bundle-estimate.js";
 import { planBase } from "./plan-base.js";
 import { routeOf } from "./routing.js";
 import { automaticAnalysisRouteReason, taskProtocolValidationReason } from "./validation.js";
 import { declaredParticipantCount } from "./study-fields.js";
 import { recordedStudyWarnings } from "./warnings.js";
+import { plural } from "../run/text.js";
 export { routeOf } from "./routing.js";
 /** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
 export function resolveStudyDryRun(config, override, fallback) {
@@ -81,15 +83,53 @@ export function planStudy(config, options, deps = {}) {
     const result = planRoute(routeOf(config), study, options, input, deps, e2b);
     if (!result.ok)
         return result;
+    const bundle = plannedBundle(result.plan);
     // The manifest the CLI resolved enters the plan here and nowhere else; the routes read
     // plan.study for the run's status record and bundle, and plan.warnings for its bundle events.
-    const warnings = [...recordedStudyWarnings(study), ...(result.plan.warnings ?? [])];
+    const closing = closingReportWarning(result.plan);
+    const warnings = [
+        ...recordedStudyWarnings(study),
+        ...(result.plan.warnings ?? []),
+        ...(bundle.warning === undefined ? [] : [bundle.warning]),
+        ...(closing === undefined ? [] : [closing]),
+    ];
     const plan = {
         ...result.plan,
         ...(options.study === undefined ? {} : { study: options.study }),
         ...(warnings.length === 0 ? {} : { warnings }),
     };
-    return { ok: true, planned: { plan } };
+    return {
+        ok: true,
+        planned: { plan, ...(bundle.estimate === undefined ? {} : { bundle: bundle.estimate }) },
+    };
+}
+/**
+ * The bundle a computer-use plan's participants leave, each session at the plan's budget, and the
+ * warning for a live plan whose estimate passes a bundle limit. A dry run records no turns.
+ */
+function plannedBundle(plan) {
+    if (plan.route !== "computer-use")
+        return {};
+    const estimate = estimateBundle(plan.runner.participants, plan.sessionBudgetMs);
+    const warning = plan.dryRun ? undefined : bundleLimitReason(estimate);
+    return warning === undefined ? { estimate } : { estimate, warning };
+}
+/**
+ * The warning for participants with a scheduled end on Claude as a local-agent participant model.
+ * Its session has no read-only closing request, so each such participant ends with the scheduled
+ * end as its reason and no account of its session.
+ */
+function closingReportWarning(plan) {
+    if (plan.route !== "computer-use")
+        return undefined;
+    const { brain } = plan.runner;
+    if (brain.kind !== "local-agent" || brain.agent !== "claude")
+        return undefined;
+    const scheduled = plan.runner.participants.filter((participant) => participant.endAfterMs !== undefined).length;
+    if (scheduled === 0)
+        return undefined;
+    const subject = scheduled === 1 ? "it ends" : "each ends";
+    return `${plural(scheduled, "participant")} ${scheduled === 1 ? "has" : "have"} a scheduled end (participants[].endAfterMs), and Claude as a local-agent participant model cannot be asked for a closing report, so ${subject} with the scheduled end as its reason and no closing account. A computer-use model (actor.type: openai-computer-use) or Codex (actor.localAgent: codex) writes one.`;
 }
 function planRoute(route, study, options, input, deps, e2b) {
     const { sandboxCeiling } = e2b;

package/dist/study/preflight.js

@@ -7,6 +7,7 @@ import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./prefli
 import { digest, fail, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
 import { planStudy, routeOf } from "./plan.js";
 import { describeArrivals, describeWindows } from "./arrivals.js";
+import { describeBundle } from "./bundle-estimate.js";
 import { resolveStudyManifest } from "./discover.js";
 import { participantList } from "./study-fields.js";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
@@ -81,6 +82,13 @@ export async function runStudyPreflight(options) {
     const windows = windowsCheck(planned.planned.plan);
     if (windows !== undefined)
         ctx.checks.push(windows);
+    const bundle = planned.planned.bundle;
+    if (bundle !== undefined)
+        ctx.checks.push({ name: "bundle size", ok: true, message: describeBundle(bundle) });
+    // The plan's warnings, which the run records; the study file's own are already listed.
+    for (const warning of planned.planned.plan.warnings ?? [])
+        if (!ctx.warnings.includes(warning))
+            ctx.warnings.push(warning);
     const machine = machineCheck(ctx.config);
     // A local study's app and desktops run on this machine, so the hosted probes do not apply.
     if (reachability !== "metadata" && isLocalBrowserStudy(ctx.config))