humanish 0.107.0 → 0.109.0

package/dist/{lab → study}/requirements.d.ts

@@ -1,4 +1,4 @@
-import type { LabPlan, Requirement } from "./plan-types.js";
+import type { StudyPlan, Requirement } from "./plan-types.js";
 /** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
 export declare function missingKeys(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
 /** The subject env names the requirements list and `env` lacks, in declaration order. */
@@ -13,8 +13,8 @@ export declare function requiredSubjectEnv(requirements: readonly Requirement[])
 /**
  * The provider keys a live run of `plan` is known to read: its `key` and `key-one-of` names, its
  * subject env, the external catch's token variable, ANTHROPIC_API_KEY for a Claude Code
- * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `lab run` prints a
+ * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `run` prints a
  * key-source line for these only. Discovery still fills every key it finds: other readers, such as
  * a declared scorer's host code, are not in the plan.
  */
-export declare function keyNamesOf(plan: LabPlan): ReadonlySet<string>;
+export declare function keyNamesOf(plan: StudyPlan): ReadonlySet<string>;

package/dist/{lab → study}/requirements.js

@@ -30,7 +30,7 @@ export function requiredSubjectEnv(requirements) {
 /**
  * The provider keys a live run of `plan` is known to read: its `key` and `key-one-of` names, its
  * subject env, the external catch's token variable, ANTHROPIC_API_KEY for a Claude Code
- * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `lab run` prints a
+ * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `run` prints a
  * key-source line for these only. Discovery still fills every key it finds: other readers, such as
  * a declared scorer's host code, are not in the plan.
  */

package/dist/study/route-inputs.d.ts

@@ -0,0 +1,28 @@
+import type { InternalRunStudyOptions } from "../run-study.js";
+import type { RunScorerProvenance } from "../run/bundle.js";
+import { type AdapterScorerModule } from "./adapter-scorer-loader.js";
+import type { StudyDeps } from "./study-deps.js";
+import type { StudyEvent } from "./run-study-events.js";
+import type { ComputerUseRunInput } from "../routes/computer-use/types.js";
+import type { ScriptedRunInput } from "../routes/scripted/types.js";
+import type { SharedWorldRunInput } from "../routes/shared-world/types.js";
+import type { TerminalRunInput } from "../routes/terminal/types.js";
+export declare function computerUseInput(options: InternalRunStudyOptions, deps: StudyDeps, emit: StudyEmit | undefined): ComputerUseRunInput;
+export declare function scriptedInput(options: InternalRunStudyOptions, deps: StudyDeps, emit: StudyEmit | undefined): ScriptedRunInput;
+export declare function terminalInput(options: InternalRunStudyOptions, deps: StudyDeps, emit: StudyEmit | undefined): TerminalRunInput;
+export declare function sharedWorldInput(options: InternalRunStudyOptions, deps: StudyDeps, emit: StudyEmit | undefined): SharedWorldRunInput;
+/** A scorer the CLI loads after the route's local checks, and the provenance it stamps on the run. */
+export type LateScorer = Pick<InternalRunStudyOptions, "scorer" | "scorerProvenance">;
+/** Narrows RunStudyOptions.scorer to the context the route passes (adapter-scorer-loader.ts). */
+type NarrowScorer<S> = (scorer: AdapterScorerModule) => S;
+/**
+ * A route's input with a scorer loaded after admission, and the scorer's provenance, as if the
+ * caller had passed them up front. The rest of the input is the one the route's checks admitted.
+ */
+export declare function withLateScorer<S, I extends {
+    scorer?: S;
+    scorerProvenance?: RunScorerProvenance;
+}>(input: I, late: LateScorer | undefined, narrow: NarrowScorer<S>): I;
+/** Reports a StudyEvent to onEvent without waiting (normalizeRunStudyOptions builds it). */
+type StudyEmit = (event: StudyEvent) => void;
+export {};

package/dist/{lab → study}/route-inputs.js

@@ -1,4 +1,4 @@
-// What each route's run takes from runLab's options: the shared run settings, the typed options
+// What each route's run takes from runStudyWith's options: the shared run settings, the typed options
 // the route reads, the event emitter, the test seams and the declared scorer's provenance.
 import { browserRouteScorer, terminalRouteScorer, } from "./adapter-scorer-loader.js";
 export function computerUseInput(options, deps, emit) {

package/dist/{lab → study}/routing.d.ts

@@ -1,10 +1,10 @@
-import type { LabConfig } from "./types.js";
-export declare const MAX_CUA_LANES = 16;
+import type { StudyConfig } from "./types.js";
+export declare const MAX_COMPUTER_USE_PARTICIPANTS = 16;
 export declare function actorResolvesToComputerUse(type: string | undefined): boolean;
 export declare function registeredComputerUseActors(): string[];
 export declare function actorResolvesToScriptedBrowser(type: string | undefined): boolean;
 export declare function registeredScriptedBrowserActors(): string[];
-/** True when `type` resolves to a registered terminal actor (the "terminal" lane). Exported so
+/** True when `type` resolves to a registered terminal actor (the "terminal" run kind). Exported so
  *  the engine + tests can resolve the dispatch the same way the parser does. */
 export declare function actorResolvesToTerminal(type: string | undefined): boolean;
 export declare function registeredTerminalActors(): string[];
@@ -13,64 +13,70 @@ export declare function registeredTerminalActors(): string[];
  * a homogeneous `count`, else 1. The single source of truth shared by the parser, the engine,
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
-export declare function cuaLaneCount(config: LabConfig): number;
+export declare function computerUseParticipantCount(config: StudyConfig): number;
 /**
  * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`
- * (shared-world seats) from its 0-based position. The parser's filled email recipients and the
- * routes that name participants both call this, so a filled recipient names a participant that
+ * (shared-world participants) from its 0-based position. The parser's filled email recipients and
+ * the routes that name participants both call this, so a filled recipient names a participant that
  * runs.
  */
 export declare function participantIdAt(index: number, declared: string | undefined, kind: "lane" | "seat"): string;
 /**
- * True when this config routes to the computer-use backend: an app-url subject whose first
- * actor resolves to a registered computer-use actor, or a clone subject on a hosted desktop
- * whose first actor does. Single source of truth — routeOf and the warning logic
- * both use it. (The app-url branch used to be unconditionally true; it narrowed when the
- * scripted-browser route arrived. Behavior-preserving for every parse-valid config —
- * routeOf keeps a bare app-url fallback to the cua backend so library-API configs
- * with unknown actors still hit its fail-closed ACTOR_UNSUPPORTED.)
+ * True when this config routes to the computer-use backend: an app-url subject whose first actor
+ * resolves to a registered computer-use actor, or a clone subject on a hosted desktop whose first
+ * actor does. Single source of truth: routeOf and the warning logic both use it. (The app-url
+ * branch also checks the first actor, so a scripted-browser actor routes elsewhere. routeOf keeps a
+ * bare app-url fallback to the computer-use route so library-API configs with unknown actors still
+ * hit its fail-closed ACTOR_UNSUPPORTED.)
  */
-export declare function isComputerUseComposition(config: LabConfig): boolean;
+export declare function isComputerUseComposition(config: StudyConfig): boolean;
 /**
- * True when this config routes to the SHARED-WORLD backend (#164): a clone or local-tree subject
+ * True when this config routes to the shared-world route: a clone or local-tree subject
  * on a hosted desktop whose first actor resolves to a computer-use actor and that declares the
  * `shared-world` topology. Mirror of isComputerUseComposition; the single source of truth shared by
- * routeOf (which checks it before the cua route) and the warning logic. Every
+ * routeOf (which checks it before the computer-use route) and the warning logic. Every
  * shared-world study runs its participants at once (`execution.concurrency` >= 2). The same
  * clone/local-tree × e2b-desktop × computer-use composition without `topology: shared-world` stays per-lane-worlds
- * (the cua route) — the topology declaration is the override switch.
+ * (the computer-use route); the topology declaration is the override switch.
  */
-export declare function isSharedWorldComposition(config: LabConfig): boolean;
+export declare function isSharedWorldComposition(config: StudyConfig): boolean;
 /** The getHost provisioned-subject shared-world shape (clone/local-tree served + exposed in-sandbox). */
-export declare function isProvisionedSharedWorldComposition(config: LabConfig): boolean;
+export declare function isProvisionedSharedWorldComposition(config: StudyConfig): boolean;
 /**
- * The external-public shared-world shape (#164 phase 2): a real public deployment used directly as
- * the shared plane — `source: app-url` + `topology: shared-world` + a computer-use actor on
+ * The external-public shared-world shape: a real public deployment used directly as
+ * the shared plane: `source: app-url` + `topology: shared-world` + a computer-use actor on
  * e2b-desktop + `policies.allowPublicTargets: true`. No getHost, no clone, no subject sandbox, no
  * seed. The operator-ownership attestation `subject.publicTarget` is required (validated in
- * externalPublicSharedWorldValidationReason, not here — this predicate is the router only, so a
+ * externalPublicSharedWorldValidationReason, not here; this predicate is the router only, so a
  * half-declared external-public config still routes here to get its precise fail-closed reason
- * rather than silently downgrading to the per-participant cua route).
+ * rather than silently downgrading to the per-participant computer-use route).
  */
-export declare function isExternalPublicSharedWorldComposition(config: LabConfig): boolean;
+export declare function isExternalPublicSharedWorldComposition(config: StudyConfig): boolean;
 /**
- * Resolve a shared-world seat's entry URL from `serve.url` + a role's `entry` (relative path or
- * same-origin absolute URL). Returns null when the combination is not a same-origin loopback URL
- * (the load-bearing public-safety boundary — a seat only ever drives the in-sandbox app).
+ * Resolve a shared-world participant's entry URL from `serve.url` and its roster entry's `entry`
+ * (a relative path or a same-origin absolute URL). Returns null when the result is not a
+ * same-origin loopback URL, so a participant only ever drives the in-sandbox app.
  */
-export declare function resolveSeatUrl(serveUrl: string, entry: string | undefined): string | null;
+export declare function resolveEntryUrl(serveUrl: string, entry: string | undefined): string | null;
 /**
  * True when this config routes to the scripted-browser backend: an app-url subject whose
  * first actor resolves to a registered scripted-browser actor (execution.target local or
- * absent — the parse layer enforces that pairing). Mirror of isComputerUseComposition; the single
+ * absent; the parse layer enforces that pairing). Mirror of isComputerUseComposition; the single
  * source of truth for routeOf and the warning logic.
  */
-export declare function isScriptedBrowserComposition(config: LabConfig): boolean;
-export declare function isProvisionedScriptedBrowserComposition(config: LabConfig): boolean;
+export declare function isScriptedBrowserComposition(config: StudyConfig): boolean;
+export declare function isProvisionedScriptedBrowserComposition(config: StudyConfig): boolean;
 /**
  * True when this config routes to the terminal-product backend: a terminal-product subject whose
- * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent —
+ * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent;
  * the parse layer enforces that pairing). Mirror of isComputerUseComposition/isScriptedBrowserComposition;
  * the single source of truth for routeOf and the warning logic.
  */
-export declare function isTerminalProductComposition(config: LabConfig): boolean;
+export declare function isTerminalProductComposition(config: StudyConfig): boolean;
+/** The five execution paths a study can take. */
+export type StudyRoute = "preview" | "computer-use" | "shared-world" | "terminal" | "scripted";
+/**
+ * The route a config takes. It never refuses: a config no route can run still gets the route
+ * whose own checks refuse it with the most precise reason.
+ */
+export declare function routeOf(config: StudyConfig): StudyRoute;

package/dist/{lab → study}/routing.js

@@ -1,8 +1,8 @@
 import { actorRegistry } from "../actors/registry.js";
 import { isLoopbackUrl } from "./parse/subject.js";
-// Hard cap on fan-out participants (per the ratified design). No HUMANISH_MAX_LANES escape above this
-// until a reference panel demands it — N concurrent paid desktops is real money.
-export const MAX_CUA_LANES = 16;
+// Hard cap on computer-use participants. No setting raises it: each participant is a paid desktop,
+// and they all run at once.
+export const MAX_COMPUTER_USE_PARTICIPANTS = 16;
 // Run kinds whose evidence is the participant's screenshots. An actor that declares it produces none
 // cannot run on them: a code-only actor would claim a GUI flow it only reached through a shell.
 const SCREENSHOT_RUN_KINDS = new Set([
@@ -36,7 +36,7 @@ export function actorResolvesToScriptedBrowser(type) {
 export function registeredScriptedBrowserActors() {
     return registeredActorsOn("scripted-browser");
 }
-/** True when `type` resolves to a registered terminal actor (the "terminal" lane). Exported so
+/** True when `type` resolves to a registered terminal actor (the "terminal" run kind). Exported so
  *  the engine + tests can resolve the dispatch the same way the parser does. */
 export function actorResolvesToTerminal(type) {
     return actorResolvesTo(type, "terminal");
@@ -49,7 +49,7 @@ export function registeredTerminalActors() {
  * a homogeneous `count`, else 1. The single source of truth shared by the parser, the engine,
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
-export function cuaLaneCount(config) {
+export function computerUseParticipantCount(config) {
     const actor = config.actors[0];
     if (actor?.lanes !== undefined) {
         return actor.lanes.length;
@@ -58,29 +58,28 @@ export function cuaLaneCount(config) {
 }
 /**
  * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`
- * (shared-world seats) from its 0-based position. The parser's filled email recipients and the
- * routes that name participants both call this, so a filled recipient names a participant that
+ * (shared-world participants) from its 0-based position. The parser's filled email recipients and
+ * the routes that name participants both call this, so a filled recipient names a participant that
  * runs.
  */
 export function participantIdAt(index, declared, kind) {
     return declared ?? `${kind === "seat" ? "role" : "lane"}-${String(index + 1).padStart(2, "0")}`;
 }
 /**
- * True when this config routes to the computer-use backend: an app-url subject whose first
- * actor resolves to a registered computer-use actor, or a clone subject on a hosted desktop
- * whose first actor does. Single source of truth — routeOf and the warning logic
- * both use it. (The app-url branch used to be unconditionally true; it narrowed when the
- * scripted-browser route arrived. Behavior-preserving for every parse-valid config —
- * routeOf keeps a bare app-url fallback to the cua backend so library-API configs
- * with unknown actors still hit its fail-closed ACTOR_UNSUPPORTED.)
+ * True when this config routes to the computer-use backend: an app-url subject whose first actor
+ * resolves to a registered computer-use actor, or a clone subject on a hosted desktop whose first
+ * actor does. Single source of truth: routeOf and the warning logic both use it. (The app-url
+ * branch also checks the first actor, so a scripted-browser actor routes elsewhere. routeOf keeps a
+ * bare app-url fallback to the computer-use route so library-API configs with unknown actors still
+ * hit its fail-closed ACTOR_UNSUPPORTED.)
  */
 export function isComputerUseComposition(config) {
     // local-app drives the cua loop in-process (a custom executor + a non-vision provider), so it
-    // routes to the cua backend exactly like an app-url subject with a computer-use actor.
+    // routes to the computer-use route exactly like an app-url subject with a computer-use actor.
     if (config.subject.source === "app-url" || config.subject.source === "local-app") {
         return actorResolvesToComputerUse(config.actors[0]?.type);
     }
-    // desktop-cli hands the participant a terminal instead of a served page (#495), but it is the
+    // desktop-cli hands the participant a terminal instead of a served page, but it is the
     // same route: same desktop, same actor, same prompt fields. Leaving it out of this predicate told
     // adopters their mission and persona were inert on the one route whose whole point is that a
     // person reads a screen.
@@ -95,13 +94,13 @@ export function isComputerUseComposition(config) {
         actorResolvesToComputerUse(config.actors[0]?.type));
 }
 /**
- * True when this config routes to the SHARED-WORLD backend (#164): a clone or local-tree subject
+ * True when this config routes to the shared-world route: a clone or local-tree subject
  * on a hosted desktop whose first actor resolves to a computer-use actor and that declares the
  * `shared-world` topology. Mirror of isComputerUseComposition; the single source of truth shared by
- * routeOf (which checks it before the cua route) and the warning logic. Every
+ * routeOf (which checks it before the computer-use route) and the warning logic. Every
  * shared-world study runs its participants at once (`execution.concurrency` >= 2). The same
  * clone/local-tree × e2b-desktop × computer-use composition without `topology: shared-world` stays per-lane-worlds
- * (the cua route) — the topology declaration is the override switch.
+ * (the computer-use route); the topology declaration is the override switch.
  */
 export function isSharedWorldComposition(config) {
     return (isProvisionedSharedWorldComposition(config) || isExternalPublicSharedWorldComposition(config));
@@ -114,13 +113,13 @@ export function isProvisionedSharedWorldComposition(config) {
         actorResolvesToComputerUse(config.actors[0]?.type));
 }
 /**
- * The external-public shared-world shape (#164 phase 2): a real public deployment used directly as
- * the shared plane — `source: app-url` + `topology: shared-world` + a computer-use actor on
+ * The external-public shared-world shape: a real public deployment used directly as
+ * the shared plane: `source: app-url` + `topology: shared-world` + a computer-use actor on
  * e2b-desktop + `policies.allowPublicTargets: true`. No getHost, no clone, no subject sandbox, no
  * seed. The operator-ownership attestation `subject.publicTarget` is required (validated in
- * externalPublicSharedWorldValidationReason, not here — this predicate is the router only, so a
+ * externalPublicSharedWorldValidationReason, not here; this predicate is the router only, so a
  * half-declared external-public config still routes here to get its precise fail-closed reason
- * rather than silently downgrading to the per-participant cua route).
+ * rather than silently downgrading to the per-participant computer-use route).
  */
 export function isExternalPublicSharedWorldComposition(config) {
     return (config.subject.source === "app-url" &&
@@ -130,11 +129,11 @@ export function isExternalPublicSharedWorldComposition(config) {
         config.policies?.allowPublicTargets === true);
 }
 /**
- * Resolve a shared-world seat's entry URL from `serve.url` + a role's `entry` (relative path or
- * same-origin absolute URL). Returns null when the combination is not a same-origin loopback URL
- * (the load-bearing public-safety boundary — a seat only ever drives the in-sandbox app).
+ * Resolve a shared-world participant's entry URL from `serve.url` and its roster entry's `entry`
+ * (a relative path or a same-origin absolute URL). Returns null when the result is not a
+ * same-origin loopback URL, so a participant only ever drives the in-sandbox app.
  */
-export function resolveSeatUrl(serveUrl, entry) {
+export function resolveEntryUrl(serveUrl, entry) {
     if (entry === undefined || entry === "") {
         return isLoopbackUrl(serveUrl) ? serveUrl : null;
     }
@@ -156,7 +155,7 @@ export function resolveSeatUrl(serveUrl, entry) {
 /**
  * True when this config routes to the scripted-browser backend: an app-url subject whose
  * first actor resolves to a registered scripted-browser actor (execution.target local or
- * absent — the parse layer enforces that pairing). Mirror of isComputerUseComposition; the single
+ * absent; the parse layer enforces that pairing). Mirror of isComputerUseComposition; the single
  * source of truth for routeOf and the warning logic.
  */
 export function isScriptedBrowserComposition(config) {
@@ -172,10 +171,42 @@ export function isProvisionedScriptedBrowserComposition(config) {
 }
 /**
  * True when this config routes to the terminal-product backend: a terminal-product subject whose
- * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent —
+ * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent;
  * the parse layer enforces that pairing). Mirror of isComputerUseComposition/isScriptedBrowserComposition;
  * the single source of truth for routeOf and the warning logic.
  */
 export function isTerminalProductComposition(config) {
     return (config.subject.source === "terminal-product" && actorResolvesToTerminal(config.actors[0]?.type));
 }
+/**
+ * The route a config takes. It never refuses: a config no route can run still gets the route
+ * whose own checks refuse it with the most precise reason.
+ */
+export function routeOf(config) {
+    const source = config.subject.source;
+    // A scripted-browser actor on a loopback app or a provisioned clone replays committed steps.
+    if (isScriptedBrowserComposition(config))
+        return "scripted";
+    // A terminal-product subject goes to the terminal route even with an unregistered actor, so that
+    // route refuses the actor instead of another route running something else.
+    if (isTerminalProductComposition(config) || source === "terminal-product")
+        return "terminal";
+    // Checked before computer use: the same composition without the topology declaration runs
+    // independent participants.
+    if (isSharedWorldComposition(config))
+        return "shared-world";
+    // A CLI studied at a desktop is a computer-use study whose subject is a terminal window.
+    if (source === "desktop-cli")
+        return "computer-use";
+    // Every other app-url, clone, local-app or local-tree config goes to computer use, including
+    // ones with an unknown actor: that route refuses the actor, where the preview route would run
+    // no participant at all.
+    if (isComputerUseComposition(config) ||
+        source === "app-url" ||
+        source === "clone" ||
+        source === "local-app" ||
+        source === "local-tree")
+        return "computer-use";
+    // this-repo runs the synthetic preview.
+    return "preview";
+}

package/dist/{lab/run-lab-events.d.ts → study/run-study-events.d.ts}

@@ -1,9 +1,8 @@
 import type { CuaParticipantPlan } from "../routes/computer-use/types.js";
-import type { PhaseParticipant } from "./lab-deps.js";
 import type { SubjectPhaseEvent } from "../subject/steps.js";
-import type { InternalRunLabOptions } from "../run-lab.js";
-import type { LabRoute } from "./plan.js";
-import type { LabConfig } from "./types.js";
+import type { InternalRunStudyOptions } from "../run-study.js";
+import type { StudyRoute } from "./plan.js";
+import type { StudyConfig } from "./types.js";
 /** One participant, as the options' callbacks see it. */
 export interface ParticipantRef {
     readonly id: string;
@@ -20,12 +19,12 @@ export type SetupTarget = {
 };
 /**
  * What a run reports while it runs. `plan` comes from computer use only; the other routes run from
- * the lab plan but do not emit it. `subject-phase` comes from computer use (participant target)
+ * the study plan but do not emit it. `subject-phase` comes from computer use (participant target)
  * and shared world (subject target).
  */
-export type LabEvent = {
+export type StudyEvent = {
     type: "plan";
-    route: LabRoute;
+    route: StudyRoute;
     participants: readonly {
         id: string;
         persona: string;
@@ -51,14 +50,12 @@ export type LabEvent = {
  * analysis API key. A callback can hold any of them, and its warning is appended after the route
  * sanitized its own.
  */
-export declare function knownSecretValues(config: LabConfig, options: InternalRunLabOptions, forwardedEnv: Readonly<Record<string, string | undefined>> | undefined): string[];
+export declare function knownSecretValues(config: StudyConfig, options: InternalRunStudyOptions, forwardedEnv: Readonly<Record<string, string | undefined>> | undefined): string[];
 /**
  * The emitter the route hook bags call, or undefined without onEvent. It calls onEvent and never
  * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secretValues`.
  */
-export declare function labEventEmitter(onEvent: ((event: LabEvent) => void | Promise<void>) | undefined, warnings: string[], secretValues: () => string[]): ((event: LabEvent) => void) | undefined;
+export declare function studyEventEmitter(onEvent: ((event: StudyEvent) => void | Promise<void>) | undefined, warnings: string[], secretValues: () => string[]): ((event: StudyEvent) => void) | undefined;
 /** The computer-use participant plan as a `plan` event: ids, personas, devices and digests. */
-export declare function planEvent(plan: CuaParticipantPlan): LabEvent;
-/** A participant as the route reports a phase for it, renamed to the event's field names. */
-export declare const participantOf: (participant: PhaseParticipant) => ParticipantRef;
-export declare function phaseEvent(event: SubjectPhaseEvent, target: SetupTarget): LabEvent;
+export declare function planEvent(plan: CuaParticipantPlan): StudyEvent;
+export declare function phaseEvent(event: SubjectPhaseEvent, target: SetupTarget): StudyEvent;

package/dist/{lab/run-lab-events.js → study/run-study-events.js}

@@ -1,5 +1,5 @@
-// What a run reports through RunLabOptions.onEvent, and how a callback failure becomes a run
-// warning. normalizeRunLabOptions (run-lab-options.ts) builds the emitter and hands it to the
+// What a run reports through RunStudyOptions.onEvent, and how a callback failure becomes a run
+// warning. normalizeRunStudyOptions (run-study-options.ts) builds the emitter and hands it to the
 // route hook bags it maps; the event values are built here.
 import { redactText, scrubLiterals, toErrorMessage } from "../evidence/redaction.js";
 /**
@@ -26,7 +26,7 @@ export function knownSecretValues(config, options, forwardedEnv) {
  * The emitter the route hook bags call, or undefined without onEvent. It calls onEvent and never
  * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secretValues`.
  */
-export function labEventEmitter(onEvent, warnings, secretValues) {
+export function studyEventEmitter(onEvent, warnings, secretValues) {
     if (onEvent === undefined)
         return undefined;
     return (event) => {
@@ -68,12 +68,6 @@ export function planEvent(plan) {
         })),
     };
 }
-/** A participant as the route reports a phase for it, renamed to the event's field names. */
-export const participantOf = (participant) => ({
-    id: participant.laneId,
-    index: participant.laneIndex,
-    count: participant.laneCount,
-});
 export function phaseEvent(event, target) {
     return {
         type: "subject-phase",

package/dist/{lab/run-lab-homes.d.ts → study/run-study-homes.d.ts}

@@ -1,11 +1,11 @@
 import type { CuaExecutor, CuaProvider } from "../actors/computer-use/loop.js";
 import type { E2BDesktopSandbox } from "../substrates/e2b/sdk.js";
 import type { AdapterScorerModule } from "./adapter-scorer-loader.js";
-import type { LabEvent, ParticipantRef, SetupTarget } from "./run-lab-events.js";
-import type { LabConfig } from "./types.js";
+import type { StudyEvent, ParticipantRef, SetupTarget } from "./run-study-events.js";
+import type { StudyConfig } from "./types.js";
 /** What `createProvider` receives for each participant. */
 export interface ProviderContext {
-    readonly config: LabConfig;
+    readonly config: StudyConfig;
     readonly participant: ParticipantRef;
     readonly executor: CuaExecutor;
 }
@@ -13,27 +13,29 @@ export type ProviderFactory = (ctx: ProviderContext) => Promise<CuaProvider>;
 /** The caller's executor for an in-process run, built once for the run's single participant. */
 export interface InProcessDriver {
     executor: (ctx: {
-        config: LabConfig;
+        config: StudyConfig;
         appUrl: string;
     }) => Promise<CuaExecutor>;
 }
-export type StreamEvent = 
-/** Runtime only: `url` carries an auth key and must never be persisted. */
-{
-    type: "ready";
+interface StreamEventIds {
     participantId: string;
-    sandboxId: string;
-    simId: string;
+    /**
+     * The id of this participant's entry in run.json `simulations[]` (`sim-001`), which
+     * `streams[].simId` also holds.
+     */
+    recordId: string;
     streamId: string;
+}
+export type StreamEvent = (StreamEventIds & {
+    type: "ready";
+    sandboxId: string;
+    /** Runtime only: carries an auth key and must never be persisted. */
     url: string;
-} | {
+}) | (StreamEventIds & {
     type: "ended";
-    participantId: string;
-    simId: string;
-    streamId: string;
-};
+});
 /** The options with a typed home, common to every route. */
-export interface RunLabHomes {
+export interface RunStudyHomes {
     /** Keys and subject env for the run. Defaults to process.env. */
     env?: Readonly<Record<string, string | undefined>>;
     /**
@@ -48,17 +50,18 @@ export interface RunLabHomes {
      * Passive. Never awaited; a throw or a rejected promise becomes a run warning. It observes and
      * changes no output: subject phases still go to stderr.
      */
-    onEvent?: (event: LabEvent) => void | Promise<void>;
+    onEvent?: (event: StudyEvent) => void | Promise<void>;
     /** Awaited after a participant's live stream starts, and again after its sandbox is gone. */
     onStream?: (event: StreamEvent) => Promise<void> | void;
     /** Cancels post-run analysis only. */
     analysisSignal?: AbortSignal;
 }
 /** Brain and in-process driving. An in-process executor needs a provider: it returns no frame. */
-export type RunLabDriving = {
+export type RunStudyDriving = {
     inProcess?: undefined;
     createProvider?: ProviderFactory;
 } | {
     inProcess: InProcessDriver;
     createProvider: ProviderFactory;
 };
+export {};

package/dist/{lab/run-lab-homes.js → study/run-study-homes.js}

@@ -1,3 +1,3 @@
-// The public RunLabOptions homes that every route reads: env, scorer, prepareDesktop, onEvent,
+// The public RunStudyOptions homes that every route reads: env, scorer, prepareDesktop, onEvent,
 // onStream and analysisSignal, and the brain and in-process driving computer use takes.
 export {};

package/dist/study/run-study-options.d.ts

@@ -0,0 +1,28 @@
+import type { InternalRunStudyOptions, StudyOutcome, RunStudyOptions } from "../run-study.js";
+import { type StudyRoute } from "./plan.js";
+import type { StudyConfig } from "./types.js";
+import { type StudyEvent } from "./run-study-events.js";
+type Refusal = {
+    ok: false;
+    code: "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED";
+    message: string;
+};
+type Normalized = {
+    ok: true;
+    /** The options the route reads: onEvent removed, env copied. */
+    options: InternalRunStudyOptions;
+    /** Filled by onEvent failures while the run runs; runStudyWith appends them to the result. */
+    warnings: string[];
+    /** Calls onEvent and never waits for it, or undefined without onEvent. The routes report through it. */
+    emit: ((event: StudyEvent) => void) | undefined;
+};
+/** The refusal for a field a JavaScript caller passed that RunStudyOptions no longer has. */
+export declare function removedOptionRefusal(options: RunStudyOptions): Refusal | undefined;
+/**
+ * Refuse what the route cannot honor, copy env, and build the emitter onEvent receives through.
+ * Nothing here touches the filesystem, so a refusal leaves no run directory, receipt or sandbox.
+ */
+export declare function normalizeRunStudyOptions(config: StudyConfig, route: StudyRoute, options: InternalRunStudyOptions): Normalized | Refusal;
+/** A refusal in the route's own result envelope, before any run exists. */
+export declare function optionRefusalOutcome(config: StudyConfig, route: StudyRoute, options: RunStudyOptions, refusal: Refusal): StudyOutcome;
+export {};