humanish 0.41.0 → 0.42.0

package/dist/cua-actor-lab.d.ts

@@ -8,11 +8,12 @@ import { type DetachedTimers } from "./e2b-detached.js";
 import { type DevicePreset } from "./device-presets.js";
 import { type LabActorLane, type LabCommsEmail, type LabCommsRecipient, type LabConfig, type LabDesktopBrowser, type LabSubjectServe, type LabSubjectState } from "./lab-config.js";
 import { type ResolvedPersona } from "./persona.js";
+import { type LabTask } from "./tasks.js";
 import { renderObserver, type ObserverResult } from "./observer.js";
 import { type PreparedOutputDirectory } from "./selected-output-paths.js";
 import { type LocalTreeArchive } from "./source-archive.js";
 import type { StopWhen } from "./stop-conditions.js";
-import { type RunBundle, type RunDesktopGeometry, type RunRerunLineage, type RunProviderResource, type RunCostSummary, type RunScorerProvenance, type RunSubjectProvenance, type RunSubjectStateStepRecord } from "./run.js";
+import { type RunBundle, type RunDesktopGeometry, type RunFeedbackCandidate, type RunRerunLineage, type RunProviderResource, type RunCostSummary, type RunScorerProvenance, type RunSubjectProvenance, type RunSubjectStateStepRecord } from "./run.js";
 export declare const CUA_ACTOR_LAB_SCHEMA = "humanish.cua-lab-result.v2";
 export declare const CUA_FANOUT_STRATEGY: "per-lane-worlds";
 export declare const CUA_ACTOR_LAB_PROVIDER_METADATA: {
@@ -266,7 +267,7 @@ export interface CuaLaneSummary {
     concurrency: number;
     waves: number;
 }
-export type CuaActorLabErrorCode = "HUMANISH_CUA_LAB_FAILED" | "HUMANISH_CUA_LAB_KEYS_MISSING" | "HUMANISH_CUA_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_CUA_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_CUA_LAB_SUBJECT_INVALID" | "HUMANISH_CUA_LAB_SUBJECT_UNSAFE" | "HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER" | "HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_CUA_LAB_FANOUT_INVALID" | "HUMANISH_CUA_LAB_RERUN_INVALID" | "HUMANISH_CUA_LAB_DEVICE_GEOMETRY" | "HUMANISH_CUA_LAB_UNPRICED_CAP" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
+export type CuaActorLabErrorCode = "HUMANISH_CUA_LAB_FAILED" | "HUMANISH_CUA_LAB_KEYS_MISSING" | "HUMANISH_CUA_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_CUA_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_CUA_LAB_SUBJECT_INVALID" | "HUMANISH_CUA_LAB_SUBJECT_UNSAFE" | "HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER" | "HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_CUA_LAB_FANOUT_INVALID" | "HUMANISH_CUA_LAB_RERUN_INVALID" | "HUMANISH_CUA_LAB_DEVICE_GEOMETRY" | "HUMANISH_CUA_LAB_UNPRICED_CAP" | "HUMANISH_CUA_LAB_COMMS_CATCH_UNREACHABLE" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
 /** Subject provenance projection (invariant 5): what the actor actually drove. */
 export interface CuaSubjectProjection {
     source: "app-url" | "clone" | "local-tree";
@@ -364,6 +365,11 @@ export interface CuaLaneSpec {
     targetUrl?: string;
     /** Deterministic harness-owned completion guard. Lane-level override, else actor default. */
     stopWhen?: StopWhen;
+    /** The lab's declared protocol (#414). Every lane runs the SAME protocol — that is what makes the
+     *  per-task rates comparable across participants. Goals are already composed into `instructions`;
+     *  this carries the full tasks so the loop can corroborate completion, and the criteria never
+     *  reach the prompt. */
+    tasks?: readonly LabTask[];
     /** Per-lane override of the CUA idle backstop (consecutive screenshot/wait turns before gave_up).
      *  Absent falls back to the loop default. Raised for a lane whose job includes a long LEGITIMATE
      *  wait (e.g. a shared-world HOST idling in the waiting room while followers provision + join). */
@@ -384,6 +390,9 @@ export declare function composeLaneInstructions(args: {
     mission: string;
     persona?: string;
     instruction?: string;
+    /** The lab's declared protocol (#414). Only the participant-facing `goal` halves are rendered
+     *  into the prompt; the `success` criteria never appear here. */
+    tasks?: readonly LabTask[];
     device: {
         name: string;
         preset: DevicePreset;
@@ -465,6 +474,19 @@ export declare function resolveCuaLanePlan(config: LabConfig, opts?: {
     personas?: Map<string, ResolvedPersona>;
 }): CuaLanePlan;
 /** Shared deps every lane runner needs (resolved once in the engine). */
+/**
+ * The STUDY's shared spend ledger (#299): one counter across every lane. Each lane notes its own
+ * latest running MODEL-spend estimate (monotone per lane — an estimate can only grow) and reads
+ * back the run total; the loop stops the lane the moment the total crosses the study budget.
+ * Estimated model spend only: desktop-minutes ride the cost summary, not this ledger.
+ */
+export interface CuaRunBudget {
+    maxTotalUsd: number;
+    /** Record this lane's latest running estimate (null = unpriceable, ignored) and return the
+     *  run's current total across all lanes. */
+    note(laneId: string, estimateUsd: number | null): number;
+}
+export declare function makeCuaRunBudget(maxTotalUsd: number): CuaRunBudget;
 export interface CuaLaneDeps {
     config: LabConfig;
     descriptor: CuaActorDescriptor;
@@ -491,6 +513,16 @@ export interface CuaLaneDeps {
     redactScreenshots: boolean;
     scrubKnownValues: (text: string) => string;
     runSession: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
+    /** The study's shared spend ledger, present exactly when execution.caps.maxTotalUsd is set on a
+     *  live run (#299). Preflight already refused the cap on an unpriced model. */
+    runBudget?: CuaRunBudget;
+    /** Adopter-hosted comms plane (#380): present on the app-url route when comms.email.external is
+     *  declared. Carries the parsed comms block (recipients drive the per-lane inbox instruction)
+     *  and the inbox URL the persona opens. The drain runs once at run level, not per lane. */
+    externalComms?: {
+        email: LabCommsEmail;
+        inboxUrl: string;
+    };
     /** Injected clock (ms). Used to measure the host-side E2B desktop create->teardown span so the
      *  desktop-minute cost estimate is deterministic in tests. Defaults to Date.now. */
     now: () => number;
@@ -610,6 +642,7 @@ export declare function makeChromeBrowserStateObserver(desktop: E2BDesktopSandbo
     url?: string;
     title?: string;
     text?: string;
+    scrollY?: number;
 }>;
 /**
  * Read the running browser's actual outer-window bounds and CSS layout viewport through the
@@ -771,6 +804,35 @@ export declare function buildCuaCostSummary(args: {
     }>;
     desktopMinutes: number | undefined;
 }): RunCostSummary | undefined;
+/**
+ * Feedback candidates derived from what LIVE participants actually reported (#392).
+ *
+ * A live run's feedback draft used to fall through to a dry-run template, because no browser route
+ * ever built a candidate. The candidate worth filing is the one the study produced: a participant
+ * who reported friction on the way (the most valuable thing a run captures), or one who stopped
+ * trying. A clean pass files nothing here — feedback exists to carry findings, and a run without
+ * any falls back to an honest live summary in the draft layer instead of a template.
+ *
+ * Everything quoted is already scrub+redacted — `session.reason` passes through redactNarration in
+ * the loop before it ever lands on a trace — and passes redactText again here as defense-in-depth.
+ */
+export declare function participantFeedbackCandidates(args: {
+    runId: string;
+    scenarioId: string;
+    adapterId: string;
+    /** The already-redacted study goal (what bundle.scenario.goal carries). */
+    goal: string;
+    substrate: RunFeedbackCandidate["substrate"];
+    lanes: Array<{
+        laneId: string;
+        streamId: string;
+        personaId: string;
+        session?: CuaLoopResult;
+        traceArtifactPath?: string;
+        screenshots: string[];
+        commsArtifactPath?: string;
+    }>;
+}): RunFeedbackCandidate[];
 export declare function buildCuaBundle(args: {
     actorId: string;
     appUrl: string;