humanish 0.115.0 → 0.117.0

package/dist/actors/computer-use/loop/types.d.ts

@@ -55,15 +55,6 @@ export type CuaAction = {
 } | {
     kind: "screenshot";
 };
-/** A wait action whose duration the provider shortened before the loop dispatched it. */
-export interface ShortenedWait {
-    /** The action's index in its turn. */
-    index: number;
-    /** What the participant asked for. */
-    requestedMs: number;
-    /** What the action waits: the `ms` it carries. */
-    ms: number;
-}
 /** A captured desktop state: the (optional) frame plus a coarse signature for progress. */
 export interface CuaObservation {
     /**
@@ -171,11 +162,6 @@ export interface CuaTurn {
     message?: string;
     /** Actions to perform this turn. Empty means the model is done. */
     actions: CuaAction[];
-    /**
-     * Waits the provider shortened to the longest wait its desktop accepts, by index into
-     * `actions`. The loop records each one and tells the participant on its next request.
-     */
-    shortenedWaits?: ReadonlyArray<ShortenedWait>;
     /** Safety checks the provider flagged this turn. Non-empty pauses the run. */
     pendingSafetyChecks: CuaSafetyCheck[];
     /** Token accounting for this turn, if available. */
@@ -304,6 +290,22 @@ export interface CuaLoopOptions {
     idleSteps?: number;
     /** No-progress streak that trips the backstop. Default 20. */
     noProgressSteps?: number;
+    /**
+     * The longest one `wait` action lasts, in ms: the study's actor.maxWaitMs. A longer wait is
+     * shortened to it, the trace records a `wait shortened` notice, and the participant is told on its
+     * next request. A wait longer than one desktop call carries is sent in steps. A whole number from
+     * 1000 to 600000; any other value throws a RangeError before the session starts. Default
+     * defaultMaxWaitMs: 120000, or 30000 when the executor is speechEnabled.
+     */
+    maxWaitMs?: number;
+    /**
+     * How long a `wait` that names no duration lasts, in ms, when its turn only waits or takes
+     * screenshots: the study's actor.idleWaitMs. After an action in the same turn such a wait lasts
+     * 500 ms. A whole number from 1000 to 600000 and no longer than an explicit maxWaitMs; any other
+     * value throws a RangeError before the session starts. Default 5000. The session never applies
+     * more than its maxWaitMs, and the trace records the applied lengths as `waitSettings`.
+     */
+    idleWaitMs?: number;
     /**
      * If the model flags safety checks, decide which to acknowledge. Returning the
      * list proceeds (the acks are echoed back on the next turn's request); returning

package/dist/actors/computer-use/loop.d.ts

@@ -1,5 +1,5 @@
 import type { CuaLoopOptions, CuaLoopResult, LoopRunOptions } from "./loop/types.js";
-export type { CuaAction, CuaExecutor, CuaLiveMetadata, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaSpendGate, CuaTurn, CuaTurnRequest, ShortenedWait, } from "./loop/types.js";
+export type { CuaAction, CuaExecutor, CuaLiveMetadata, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaSpendGate, CuaTurn, CuaTurnRequest, } from "./loop/types.js";
 export { describeCuaAction } from "./loop/actions.js";
 export { stableProgressKey } from "./loop/backstop.js";
 export { IMPRESSIONS_ASK } from "./loop/impressions.js";

package/dist/actors/computer-use/loop.js

@@ -133,7 +133,7 @@ async function runTurns(session, conversation) {
                 ? { ...ended, debriefTrigger: { kind: "participant_end", observation } }
                 : ended;
         }
-        const batch = await runActionBatch(session, turn.actions, turn.shortenedWaits);
+        const batch = await runActionBatch(session, turn.actions);
         conversation.previousExecution = batch.execution;
         const checkpoint = await observer.checkpoint(turnNumber);
         if ("stop" in checkpoint)

package/dist/actors/computer-use/wait.d.ts

@@ -0,0 +1,74 @@
+import type { ActorWaitSettings } from "../contract.js";
+export declare const CUA_WAIT_LIMITS: Readonly<{
+    /**
+     * The longest wait one desktop call is given. A browser-control request must be answered within
+     * its 35 s deadline, and a hosted desktop runs a wait as a sandbox command that times out after
+     * 60 s, so the loop sends a longer wait as consecutive steps of at most this.
+     */
+    stepMs: 30000;
+    /**
+     * The longest one wait action lasts when a study does not set actor.maxWaitMs and the desktop
+     * has no speech (defaultMaxWaitMs). Two minutes covers waiting in a lobby or for an email to
+     * arrive, and the participant still sees a fresh screenshot at least that often.
+     */
+    defaultMaxMs: 120000;
+    /**
+     * How long a wait that names no duration lasts in a turn that only waits or takes screenshots,
+     * when a study does not set actor.idleWaitMs. OpenAI's computer-use `wait` names no duration. A
+     * participant told to wait about a minute sent ten in one turn, which lasts 50 s at this length;
+     * one wait a turn makes a one-minute wait about six turns.
+     */
+    defaultIdleMs: 5000;
+    /**
+     * How long a wait that names no duration lasts after the participant acts in the same turn, so
+     * the screen can settle before the next screenshot. Nearly every OpenAI computer-use wait follows
+     * a click or keypress this way, so a longer one would slow every run.
+     */
+    settleMs: 500;
+    /** The smallest actor.maxWaitMs or actor.idleWaitMs a study may set. */
+    leastMs: 1000;
+    /** The largest actor.maxWaitMs or actor.idleWaitMs a study may set. */
+    mostMs: 600000;
+}>;
+/** The wait lengths one session applies; the trace records them as `waitSettings`. */
+export type WaitSettings = Readonly<ActorWaitSettings>;
+/** One wait as the desktop runs it. */
+export interface PlannedWait {
+    /** How long the wait lasts. */
+    readonly ms: number;
+    /** The desktop calls it takes, in order, each at most CUA_WAIT_LIMITS.stepMs. */
+    readonly steps: readonly number[];
+    /** What the participant asked for, when that was longer than maxWaitMs. */
+    readonly shortenedFromMs?: number;
+}
+/**
+ * The longest one wait action lasts when a study does not set actor.maxWaitMs. On a desktop with
+ * speech, heard speech reaches the participant only with a screenshot, and the desktop session ends
+ * when more utterances arrive between two screenshots than it holds. A wait takes no screenshot, so
+ * there the default keeps one wait to one desktop call.
+ */
+export declare function defaultMaxWaitMs(speechEnabled: boolean): number;
+/**
+ * Why these wait fields cannot run, or null. `prefix` names their owner in the message: `actor.`
+ * in a study file, empty for loop options.
+ */
+export declare function waitFieldsReason(fields: {
+    readonly maxWaitMs?: unknown;
+    readonly idleWaitMs?: unknown;
+}, prefix: string): string | null;
+/**
+ * The wait lengths a session applies: the study's values, or their defaults. The idle wait never
+ * outlasts the longest wait, which on a desktop with speech defaults to 30 s. Throws a RangeError
+ * for fields waitFieldsReason refuses.
+ */
+export declare function resolveWaitSettings(options: {
+    readonly maxWaitMs?: number | undefined;
+    readonly idleWaitMs?: number | undefined;
+    readonly speechEnabled: boolean;
+}): WaitSettings;
+/**
+ * How long one wait lasts and the desktop calls it takes. A wait that names no duration lasts
+ * idleWaitMs when its turn only waits or takes screenshots (`idleTurn`), and settleWaitMs after an
+ * action. A longer wait than maxWaitMs is shortened to it. 70 s is sent as 30 s, 30 s and 10 s.
+ */
+export declare function planWait(settings: WaitSettings, requestedMs: number | undefined, idleTurn: boolean): PlannedWait;

package/dist/actors/computer-use/wait.js

@@ -0,0 +1,100 @@
+// How long one participant wait action lasts, for every provider and desktop. A study sets the
+// longest (actor.maxWaitMs) and how long a wait that names no duration lasts while the participant
+// only waits (actor.idleWaitMs). The loop asks planWait for each wait and sends it to the desktop
+// in steps one desktop call carries.
+export const CUA_WAIT_LIMITS = Object.freeze({
+    /**
+     * The longest wait one desktop call is given. A browser-control request must be answered within
+     * its 35 s deadline, and a hosted desktop runs a wait as a sandbox command that times out after
+     * 60 s, so the loop sends a longer wait as consecutive steps of at most this.
+     */
+    stepMs: 30_000,
+    /**
+     * The longest one wait action lasts when a study does not set actor.maxWaitMs and the desktop
+     * has no speech (defaultMaxWaitMs). Two minutes covers waiting in a lobby or for an email to
+     * arrive, and the participant still sees a fresh screenshot at least that often.
+     */
+    defaultMaxMs: 120_000,
+    /**
+     * How long a wait that names no duration lasts in a turn that only waits or takes screenshots,
+     * when a study does not set actor.idleWaitMs. OpenAI's computer-use `wait` names no duration. A
+     * participant told to wait about a minute sent ten in one turn, which lasts 50 s at this length;
+     * one wait a turn makes a one-minute wait about six turns.
+     */
+    defaultIdleMs: 5_000,
+    /**
+     * How long a wait that names no duration lasts after the participant acts in the same turn, so
+     * the screen can settle before the next screenshot. Nearly every OpenAI computer-use wait follows
+     * a click or keypress this way, so a longer one would slow every run.
+     */
+    settleMs: 500,
+    /** The smallest actor.maxWaitMs or actor.idleWaitMs a study may set. */
+    leastMs: 1_000,
+    /** The largest actor.maxWaitMs or actor.idleWaitMs a study may set. */
+    mostMs: 600_000,
+});
+/** A whole number of milliseconds within the range actor.maxWaitMs and actor.idleWaitMs accept. */
+function isWaitMs(value) {
+    return (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= CUA_WAIT_LIMITS.leastMs &&
+        value <= CUA_WAIT_LIMITS.mostMs);
+}
+/**
+ * The longest one wait action lasts when a study does not set actor.maxWaitMs. On a desktop with
+ * speech, heard speech reaches the participant only with a screenshot, and the desktop session ends
+ * when more utterances arrive between two screenshots than it holds. A wait takes no screenshot, so
+ * there the default keeps one wait to one desktop call.
+ */
+export function defaultMaxWaitMs(speechEnabled) {
+    return speechEnabled ? CUA_WAIT_LIMITS.stepMs : CUA_WAIT_LIMITS.defaultMaxMs;
+}
+const FIELDS = [
+    ["maxWaitMs", "the longest one wait action lasts"],
+    ["idleWaitMs", "how long a wait with no duration lasts while the participant only waits"],
+];
+/**
+ * Why these wait fields cannot run, or null. `prefix` names their owner in the message: `actor.`
+ * in a study file, empty for loop options.
+ */
+export function waitFieldsReason(fields, prefix) {
+    for (const [name, meaning] of FIELDS) {
+        if (fields[name] !== undefined && !isWaitMs(fields[name]))
+            return `${prefix}${name}, ${meaning}, must be a whole number of milliseconds from ${CUA_WAIT_LIMITS.leastMs} to ${CUA_WAIT_LIMITS.mostMs}.`;
+    }
+    const { maxWaitMs, idleWaitMs } = fields;
+    if (typeof maxWaitMs === "number" && typeof idleWaitMs === "number" && idleWaitMs > maxWaitMs)
+        return `${prefix}idleWaitMs (${idleWaitMs}) is longer than ${prefix}maxWaitMs (${maxWaitMs}), the longest one wait action lasts. Lower ${prefix}idleWaitMs or raise ${prefix}maxWaitMs.`;
+    return null;
+}
+/**
+ * The wait lengths a session applies: the study's values, or their defaults. The idle wait never
+ * outlasts the longest wait, which on a desktop with speech defaults to 30 s. Throws a RangeError
+ * for fields waitFieldsReason refuses.
+ */
+export function resolveWaitSettings(options) {
+    const reason = waitFieldsReason(options, "");
+    if (reason !== null)
+        throw new RangeError(reason);
+    const maxWaitMs = options.maxWaitMs ?? defaultMaxWaitMs(options.speechEnabled);
+    return {
+        maxWaitMs,
+        idleWaitMs: Math.min(options.idleWaitMs ?? CUA_WAIT_LIMITS.defaultIdleMs, maxWaitMs),
+        settleWaitMs: CUA_WAIT_LIMITS.settleMs,
+    };
+}
+/**
+ * How long one wait lasts and the desktop calls it takes. A wait that names no duration lasts
+ * idleWaitMs when its turn only waits or takes screenshots (`idleTurn`), and settleWaitMs after an
+ * action. A longer wait than maxWaitMs is shortened to it. 70 s is sent as 30 s, 30 s and 10 s.
+ */
+export function planWait(settings, requestedMs, idleTurn) {
+    const askedMs = requestedMs ?? (idleTurn ? settings.idleWaitMs : settings.settleWaitMs);
+    const ms = Math.min(askedMs, settings.maxWaitMs);
+    const { stepMs } = CUA_WAIT_LIMITS;
+    const steps = [];
+    for (let left = ms; left > stepMs; left -= stepMs)
+        steps.push(stepMs);
+    steps.push(ms - steps.length * stepMs);
+    return { ms, steps, ...(askedMs > ms ? { shortenedFromMs: askedMs } : {}) };
+}

package/dist/actors/contract.d.ts

@@ -256,6 +256,15 @@ export interface ActorConversation {
         estimatedInputTokens?: number;
     }>;
 }
+/** How long a computer-use participant's waits lasted, in milliseconds. */
+export interface ActorWaitSettings {
+    /** The longest one wait action lasts (actor.maxWaitMs). A longer wait is shortened to it. */
+    maxWaitMs: number;
+    /** A wait with no duration in a turn that only waits or takes screenshots (actor.idleWaitMs). */
+    idleWaitMs: number;
+    /** A wait with no duration after the participant acts in the same turn. */
+    settleWaitMs: number;
+}
 export interface ActorTrace {
     schema: typeof ACTOR_TRACE_SCHEMA;
     provider: string;
@@ -303,6 +312,11 @@ export interface ActorTrace {
         reasoningEffort: string;
         maxOutputTokens?: number;
     };
+    /**
+     * Additive + optional: the wait lengths the computer-use loop applied, defaults included. Absent
+     * on other producers and on bundles written before it was recorded.
+     */
+    waitSettings?: ActorWaitSettings;
     counts: Record<string, number>;
     /**
      * Additive + optional affordance record (humanish.affordance-use.v1): which kind of route

package/dist/actors/scripted-browser/steps.js

@@ -6,7 +6,7 @@ import os from "node:os";
 import path from "node:path";
 import { assertScreenshotEvidence, stripPngMetadataChunks } from "../../evidence/image.js";
 import { digestText, redactToSecretLabel } from "../../evidence/redaction.js";
-import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareContainedOutputFile, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../../run/contained-output.js";
+import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareContainedOutputFile, prepareSelectedOutputDirectory, readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "../../run/contained-output.js";
 import { LOOPBACK_EVIDENCE_URL_POLICY, } from "./types.js";
 export async function executeBrowserPersonaStep(args) {
     const started = Date.now();
@@ -402,11 +402,12 @@ async function captureScriptedPageScreenshot(page) {
         if (Buffer.isBuffer(returned) || returned instanceof Uint8Array) {
             return stripPngMetadataChunks(browserScreenshotBytes(returned));
         }
-        const stagedBytes = await readContainedRegularFile(stagingRoot, "capture.png");
-        if (!stagedBytes) {
+        const staged = await readContainedRegularFile(stagingRoot, "capture.png", RUN_ARTIFACT_MAX_BYTES);
+        if (staged.status === "missing")
             throw new Error("Browser screenshot did not return bytes or write a single-link staging file.");
-        }
-        return stripPngMetadataChunks(stagedBytes);
+        if (staged.status === "refused")
+            throw new Error(`Browser screenshot did not return bytes, and ${refusalText("its staging file capture.png", staged)}.`);
+        return stripPngMetadataChunks(staged.bytes);
     }
     finally {
         await assertPreparedSelectedOutputDirectory(stagingRoot)

package/dist/analysis/analysis-limits.d.ts

@@ -0,0 +1,35 @@
+/**
+ * How much an analysis result may hold, for the fields the Observer checks as well. Characters are
+ * counted as `String.length` counts them.
+ */
+export declare const ANALYSIS_LIMITS: Readonly<{
+    /** A label: a finding's title and headline, a design finding's headline and screen, or a name. */
+    labelChars: 240;
+    experienceChars: 1200;
+    noticeChars: 1500;
+    whyItMattersChars: 1000;
+    suggestionChars: 1000;
+    /** Evidence one observation or design finding may cite. */
+    evidenceRefs: 100;
+    findings: 100;
+    designFindings: 40;
+    concernReviews: 60;
+}>;
+/** Whether text holds a control character other than tab, line feed and carriage return. */
+export declare function hasControlCharacter(text: string): boolean;
+/** The parts of an analysis result the revision boundaries read. */
+interface RevisionFields {
+    readonly concernReviews?: unknown;
+    readonly designFindings?: unknown;
+    readonly findings: ReadonlyArray<{
+        readonly headline?: unknown;
+        readonly experience?: unknown;
+    }>;
+}
+/**
+ * Whether a result carries every field its prompt revision requires: concern reviews from
+ * study-evidence-5, and headlines, experiences and design findings from study-evidence-7. A prompt
+ * version without a study-evidence revision number requires none of them.
+ */
+export declare function hasRevisionFields(promptVersion: string, result: RevisionFields): boolean;
+export {};

package/dist/analysis/analysis-limits.js

@@ -0,0 +1,41 @@
+// The analysis result's limits and prompt revision boundaries, kept apart from the zod schemas in
+// validation.ts so the Observer can read them: it bundles this module, and zod stays out of its
+// page.
+/**
+ * How much an analysis result may hold, for the fields the Observer checks as well. Characters are
+ * counted as `String.length` counts them.
+ */
+export const ANALYSIS_LIMITS = Object.freeze({
+    /** A label: a finding's title and headline, a design finding's headline and screen, or a name. */
+    labelChars: 240,
+    experienceChars: 1200,
+    noticeChars: 1500,
+    whyItMattersChars: 1000,
+    suggestionChars: 1000,
+    /** Evidence one observation or design finding may cite. */
+    evidenceRefs: 100,
+    findings: 100,
+    designFindings: 40,
+    concernReviews: 60,
+});
+/** Whether text holds a control character other than tab, line feed and carriage return. */
+export function hasControlCharacter(text) {
+    return /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(text);
+}
+// The prompt revision from which a result must carry each field. A boundary stays where it is when
+// the prompt version advances, so a later prompt cannot bring back a legacy omission.
+const CONCERN_REVIEWS_FROM = 5;
+const HEADLINES_AND_DESIGN_FINDINGS_FROM = 7;
+/**
+ * Whether a result carries every field its prompt revision requires: concern reviews from
+ * study-evidence-5, and headlines, experiences and design findings from study-evidence-7. A prompt
+ * version without a study-evidence revision number requires none of them.
+ */
+export function hasRevisionFields(promptVersion, result) {
+    const revision = Number(/^study-evidence-(\d+)$/.exec(promptVersion)?.[1] ?? 0);
+    if (revision >= CONCERN_REVIEWS_FROM && result.concernReviews === undefined)
+        return false;
+    return (revision < HEADLINES_AND_DESIGN_FINDINGS_FROM ||
+        (result.designFindings !== undefined &&
+            result.findings.every((finding) => finding.headline !== undefined && finding.experience !== undefined)));
+}

package/dist/analysis/validation.js

@@ -2,12 +2,13 @@ import { validStoredCodexAnalysisConfig } from "./codex-config.js";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { ACTOR_STATUSES, ACTOR_STOP_CAUSES } from "../actors/contract.js";
+import { ANALYSIS_LIMITS, hasControlCharacter, hasRevisionFields } from "./analysis-limits.js";
 import { SHA256_HEX_PATTERN, ACTION_CAPTURE_VERSION, ANALYSIS_SCHEMA, ANALYSIS_CORRECTION_SCHEMA, } from "./types.js";
 const text = (max) => z
     .string()
     .max(max)
-    .refine((value) => !/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value), "Invalid text.");
-const label = text(240).min(1);
+    .refine((value) => !hasControlCharacter(value), "Invalid text.");
+const label = text(ANALYSIS_LIMITS.labelChars).min(1);
 const id = z
     .string()
     .min(1)
@@ -17,7 +18,7 @@ const sourceId = text(256).min(1);
 const digest = z.string().regex(SHA256_HEX_PATTERN);
 const timestamp = z.string().datetime({ offset: true });
 const sourceIds = z.array(sourceId).max(128);
-const refs = z.array(id).min(1).max(100);
+const refs = z.array(id).min(1).max(ANALYSIS_LIMITS.evidenceRefs);
 const limitations = z.array(text(2000).min(1)).max(100);
 const observationSchema = z
     .object({
@@ -32,9 +33,9 @@ const designFindingSchema = z
     id,
     headline: label,
     screen: label,
-    notice: text(1500).min(1),
-    whyItMatters: text(1000).min(1),
-    suggestion: text(1000).min(1),
+    notice: text(ANALYSIS_LIMITS.noticeChars).min(1),
+    whyItMatters: text(ANALYSIS_LIMITS.whyItMattersChars).min(1),
+    suggestion: text(ANALYSIS_LIMITS.suggestionChars).min(1),
     severity: z.enum(["minor", "moderate", "major"]),
     confidence: z.enum(["low", "medium", "high"]),
     seenByStreamIds: sourceIds.min(1),
@@ -66,7 +67,7 @@ const analysisResultSchema = z
         id,
         title: label,
         headline: label.optional(),
-        experience: text(1200).min(1).optional(),
+        experience: text(ANALYSIS_LIMITS.experienceChars).min(1).optional(),
         summary: text(4000).min(1),
         impact: z.enum(["blocked_task", "friction", "recovery", "uncertain"]),
         affectedStreamIds: sourceIds.min(1),
@@ -79,8 +80,8 @@ const analysisResultSchema = z
         priorityReason: text(2000).min(1),
     })
         .strict())
-        .max(100),
-    designFindings: z.array(designFindingSchema).max(40).optional(),
+        .max(ANALYSIS_LIMITS.findings),
+    designFindings: z.array(designFindingSchema).max(ANALYSIS_LIMITS.designFindings).optional(),
     concernReviews: z
         .array(observationSchema
         .extend({
@@ -89,7 +90,7 @@ const analysisResultSchema = z
         reason: text(2000).min(1),
     })
         .strict())
-        .max(60)
+        .max(ANALYSIS_LIMITS.concernReviews)
         .optional(),
     limitations,
 })
@@ -100,8 +101,8 @@ export const analysisResponseSchema = analysisResultSchema
     .extend({
     findings: z
         .array(analysisResultSchema.shape.findings.element.required({ headline: true, experience: true }))
-        .max(100),
-    designFindings: z.array(designFindingSchema).max(40),
+        .max(ANALYSIS_LIMITS.findings),
+    designFindings: z.array(designFindingSchema).max(ANALYSIS_LIMITS.designFindings),
 })
     .required({ concernReviews: true });
 export const analysisResultJsonSchema = z.toJSONSchema(analysisResponseSchema);
@@ -469,15 +470,7 @@ export function validateAnalysisArtifact(value) {
         (artifact.status === "complete" && !coverage.complete))
         throw new Error("ANALYSIS_STATUS_INVALID");
     if (artifact.result !== null) {
-        // Concern accounting became required with revision 5, and headlines, experiences and design
-        // findings with revision 7. Keep each boundary stable when the prompt version advances; a later
-        // prompt must not regain legacy omissions.
-        const revision = Number(/^study-evidence-(\d+)$/.exec(artifact.promptVersion)?.[1] ?? 0);
-        const result = artifact.result;
-        if ((revision >= 5 && result.concernReviews === undefined) ||
-            (revision >= 7 &&
-                (result.designFindings === undefined ||
-                    result.findings.some((finding) => finding.headline === undefined || finding.experience === undefined))))
+        if (!hasRevisionFields(artifact.promptVersion, artifact.result))
             throw new Error("ANALYSIS_RESULT_SCHEMA_INVALID");
         validateAnalysisResult({ ...artifact, images: [] }, artifact.result);
     }

package/dist/browser-control/protocol.d.ts

@@ -26,7 +26,7 @@ export interface BrowserControlIdentity {
     challenge: string;
     runtimeRevision: string;
 }
-export declare const browserOnlyControlActionSchema: z.ZodDiscriminatedUnion<readonly [z.ZodObject<{
+export declare const participantActionSchema: z.ZodPipe<z.ZodDiscriminatedUnion<readonly [z.ZodObject<{
     x: z.ZodNumber;
     y: z.ZodNumber;
     kind: z.ZodLiteral<"click">;
@@ -66,8 +66,88 @@ export declare const browserOnlyControlActionSchema: z.ZodDiscriminatedUnion<rea
     ms: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"screenshot">;
-}, z.core.$strict>], "kind">;
-export declare const browserControlActionSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[z.ZodObject<{
+}, z.core.$strict>], "kind">, z.ZodTransform<{
+    kind: "click";
+    x: number;
+    y: number;
+    button?: "left" | "right" | "middle";
+    heldKeys?: string[];
+} | {
+    kind: "double_click";
+    x: number;
+    y: number;
+    heldKeys?: string[];
+} | {
+    kind: "move";
+    x: number;
+    y: number;
+    heldKeys?: string[];
+} | {
+    kind: "scroll";
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+    heldKeys?: string[];
+} | {
+    kind: "type";
+    text: string;
+} | {
+    kind: "keypress";
+    keys: string[];
+} | {
+    kind: "drag";
+    path: Array<{
+        x: number;
+        y: number;
+    }>;
+    heldKeys?: string[];
+} | {
+    kind: "wait";
+    ms?: number;
+} | {
+    kind: "speak";
+    text: string;
+} | {
+    kind: "screenshot";
+}, {
+    kind: "type";
+    text: string;
+} | {
+    kind: "keypress";
+    keys: string[];
+} | {
+    kind: "screenshot";
+} | {
+    x: number;
+    y: number;
+    kind: "click";
+    button?: "left" | "middle" | "right" | undefined;
+} | {
+    x: number;
+    y: number;
+    kind: "double_click";
+} | {
+    x: number;
+    y: number;
+    kind: "move";
+} | {
+    x: number;
+    y: number;
+    kind: "scroll";
+    dx: number;
+    dy: number;
+} | {
+    kind: "drag";
+    path: {
+        x: number;
+        y: number;
+    }[];
+} | {
+    kind: "wait";
+    ms?: number | undefined;
+}>>;
+export declare const participantSpeechActionSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[z.ZodObject<{
     x: z.ZodNumber;
     y: z.ZodNumber;
     kind: z.ZodLiteral<"click">;
@@ -160,9 +240,6 @@ export declare const browserControlActionSchema: z.ZodPipe<z.ZodDiscriminatedUni
 } | {
     kind: "keypress";
     keys: string[];
-} | {
-    kind: "wait";
-    ms?: number | undefined;
 } | {
     kind: "screenshot";
 } | {
@@ -193,6 +270,9 @@ export declare const browserControlActionSchema: z.ZodPipe<z.ZodDiscriminatedUni
         x: number;
         y: number;
     }[];
+} | {
+    kind: "wait";
+    ms?: number | undefined;
 }>>;
 declare const observationSchema: z.ZodObject<{
     png: z.ZodString;

package/dist/browser-control/protocol.js

@@ -64,13 +64,18 @@ const dragAction = z.strictObject({
 });
 const typeAction = z.strictObject({ kind: z.literal("type"), text });
 const keypressAction = z.strictObject({ kind: z.literal("keypress"), keys: chord });
+const waitMs = z.number().finite().min(0);
+// One request carries one wait, so the wire bounds it by the request deadline.
 const waitAction = z.strictObject({
     kind: z.literal("wait"),
-    ms: z.number().finite().min(0).max(BROWSER_CONTROL_LIMITS.waitMs).optional(),
+    ms: waitMs.max(BROWSER_CONTROL_LIMITS.waitMs).optional(),
 });
+// A participant may ask for any wait: the loop shortens it to the study's longest and sends it in
+// steps the wire accepts.
+const participantWaitAction = z.strictObject({ kind: z.literal("wait"), ms: waitMs.optional() });
 const screenshotAction = z.strictObject({ kind: z.literal("screenshot") });
 const speakAction = z.strictObject({ kind: z.literal("speak"), text: speechText });
-const browserActionSchemas = [
+const participantActionSchemas = [
     clickAction,
     doubleClickAction,
     moveAction,
@@ -78,13 +83,15 @@ const browserActionSchemas = [
     typeAction,
     keypressAction,
     dragAction,
-    waitAction,
+    participantWaitAction,
     screenshotAction,
 ];
 // The Codex participant's tool schema: no held keys, so its tool surface stays as published.
-export const browserOnlyControlActionSchema = z.discriminatedUnion("kind", browserActionSchemas);
-export const browserControlActionSchema = z
-    .discriminatedUnion("kind", [...browserActionSchemas, speakAction])
+export const participantActionSchema = z
+    .discriminatedUnion("kind", participantActionSchemas)
+    .transform(toCuaAction);
+export const participantSpeechActionSchema = z
+    .discriminatedUnion("kind", [...participantActionSchemas, speakAction])
     .transform(toCuaAction);
 // What crosses the host-guest wire: the participant actions plus held keys on pointer actions,
 // which the OpenAI provider maps from its computer tool.

package/dist/cli/commands/analyze.js

@@ -6,7 +6,8 @@ import { listAnalyses } from "../../analysis/store.js";
 import { listAnalysisExecutions } from "../../analysis/store-executions.js";
 import { resolveRunPath } from "../../run/locate.js";
 import { CWD_OPTION_DESCRIPTION, discoverCliKeys, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, wantsJson, } from "../io.js";
-import { analysisFindings, formatFindings, missingRunFindings, readRunAnalysis, } from "../findings.js";
+import { analysisFindings, missingRunFindings, readRunAnalysis, } from "../findings.js";
+import { formatFindings } from "../findings-text.js";
 import { resolvePhysicalCwd } from "../../run/paths.js";
 /** Commander may collect a shared flag on the parent; only explicit values override leaf defaults. */
 function analysisSelection(options, command) {

package/dist/cli/commands/notes.js

@@ -2,9 +2,10 @@ import { renderObserver } from "../../observer/render.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../../run/locate.js";
 import { readRunNotes } from "../../run/note-files.js";
 import { byRunTime } from "../../run/note-shape.js";
-import { addRunNote, formatRunTime } from "../../run/notes.js";
+import { addRunNote } from "../../run/notes.js";
 import { runParticipantCaptions, streamParticipantIdOf } from "../../run/participant-records.js";
 import { resolvePhysicalCwd, runIdOf } from "../../run/paths.js";
+import { formatRunTime } from "../../run/run-clock.js";
 import { runNotFoundMessage } from "../../run/run-not-found.js";
 import { cli } from "../invocation.js";
 import { CWD_OPTION_DESCRIPTION, humanError, JSON_OPTION_DESCRIPTION, writeResult, } from "../io.js";