humanish 0.106.0 → 0.107.0

package/dist/lab/route-inputs.js

@@ -1,95 +1,92 @@
-// What each route's run takes from runLab's options: the shared run settings, the route's own
-// hook bag, the automatic-analysis hooks and the declared scorer's provenance.
-import { HOOK_MEMBERS, withHookOverrides } from "./bag-overrides.js";
-import { scorerHooks } from "./run-lab-options.js";
-export function computerUseInput(options) {
+// What each route's run takes from runLab'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) {
     return {
         ...analysisOf(options),
         cwd: options.cwd,
-        // CLI --count overrides the homogeneous fan-out lane count (a declared roster's length wins).
+        // CLI --count overrides the homogeneous fan-out participant count (a declared roster's length wins).
         ...(options.count === undefined ? {} : { countOverride: options.count }),
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.onObserverReady === undefined ? {} : { onObserverReady: options.onObserverReady }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
         ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
-        ...(options.cuaHooks === undefined ? {} : { hooks: options.cuaHooks }),
-        ...scorerOf(options),
+        ...(options.env === undefined ? {} : { env: options.env }),
+        ...(options.prepareDesktop === undefined ? {} : { prepareDesktop: options.prepareDesktop }),
+        ...(options.createProvider === undefined ? {} : { createProvider: options.createProvider }),
+        ...(options.inProcess === undefined ? {} : { inProcess: options.inProcess }),
+        ...(options.localVm === undefined ? {} : { localVm: options.localVm }),
+        ...observersOf(options, emit),
+        deps,
+        ...scorerOf(options, browserRouteScorer),
     };
 }
-export function scriptedInput(options) {
+export function scriptedInput(options, deps, emit) {
     return {
         ...analysisOf(options),
+        ...(emit === undefined ? {} : { emit }),
         cwd: options.cwd,
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
-        ...(options.scriptedHooks === undefined ? {} : { hooks: options.scriptedHooks }),
+        ...(options.env === undefined ? {} : { env: options.env }),
+        ...(options.prepareDesktop === undefined ? {} : { prepareDesktop: options.prepareDesktop }),
+        deps,
     };
 }
-export function terminalInput(options) {
+export function terminalInput(options, deps, emit) {
     return {
         ...analysisOf(options),
+        ...(emit === undefined ? {} : { emit }),
         cwd: options.cwd,
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
-        ...(options.terminalHooks === undefined ? {} : { hooks: options.terminalHooks }),
-        ...scorerOf(options),
+        ...(options.env === undefined ? {} : { env: options.env }),
+        deps,
+        ...scorerOf(options, terminalRouteScorer),
     };
 }
-export function sharedWorldInput(options) {
+export function sharedWorldInput(options, deps, emit) {
     return {
         ...analysisOf(options),
         cwd: options.cwd,
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.onObserverReady === undefined ? {} : { onObserverReady: options.onObserverReady }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
-        ...(options.sharedWorldHooks === undefined ? {} : { hooks: options.sharedWorldHooks }),
-        ...scorerOf(options),
+        ...(options.env === undefined ? {} : { env: options.env }),
+        ...(options.prepareDesktop === undefined ? {} : { prepareDesktop: options.prepareDesktop }),
+        ...observersOf(options, emit),
+        deps,
+        ...scorerOf(options, browserRouteScorer),
     };
 }
-/** The computer-use input with a scorer loaded after admission (see withLateScorer). */
-export function computerUseInputWithScorer(input, late) {
-    const hooks = late?.scorer === undefined ? undefined : scorerHooks(late.scorer);
-    return withLateScorer(input, HOOK_MEMBERS.cua, hooks, late);
-}
-/** The shared-world input with a scorer loaded after admission (see withLateScorer). */
-export function sharedWorldInputWithScorer(input, late) {
-    const hooks = late?.scorer === undefined ? undefined : scorerHooks(late.scorer);
-    return withLateScorer(input, HOOK_MEMBERS.sharedWorld, hooks, late);
-}
-/** The terminal input with a scorer loaded after admission. Terminal runs take no deriveArtifacts. */
-export function terminalInputWithScorer(input, late) {
-    const scorer = late?.scorer;
-    const hooks = scorer === undefined
-        ? undefined
-        : {
-            ...(scorer.score === undefined ? {} : { score: scorer.score }),
-            ...(scorer.deriveFeedback === undefined ? {} : { deriveFeedback: scorer.deriveFeedback }),
-        };
-    return withLateScorer(input, HOOK_MEMBERS.terminal, hooks, late);
-}
 /**
- * `input` with the scorer's hooks over its hook bag, as normalizeRunLabOptions maps a scorer the
- * caller passes up front, and the scorer's provenance. The bag is wrapped, never rebuilt, so the
- * members the route's checks already read stay the same objects.
+ * 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.
  */
-function withLateScorer(input, declared, hooks, late) {
+export function withLateScorer(input, late, narrow) {
     if (late === undefined)
         return input;
     return {
         ...input,
-        ...(hooks === undefined
-            ? {}
-            : { hooks: withHookOverrides(input.hooks, declared, hooks) }),
+        ...(late.scorer === undefined ? {} : { scorer: narrow(late.scorer) }),
         ...(late.scorerProvenance === undefined ? {} : { scorerProvenance: late.scorerProvenance }),
     };
 }
+/** The caller's stream callback and the run's event emitter, for the routes that report them. */
+function observersOf(options, emit) {
+    return {
+        ...(options.onStream === undefined ? {} : { onStream: options.onStream }),
+        ...(emit === undefined ? {} : { emit }),
+    };
+}
 function analysisOf(options) {
-    return options.automaticAnalysis === undefined
-        ? {}
-        : { automaticAnalysis: options.automaticAnalysis };
+    return options.analysisSignal === undefined ? {} : { analysisSignal: options.analysisSignal };
 }
-function scorerOf(options) {
-    return options.scorerProvenance === undefined
-        ? {}
-        : { scorerProvenance: options.scorerProvenance };
+function scorerOf(options, narrow) {
+    return {
+        ...(options.scorer === undefined ? {} : { scorer: narrow(options.scorer) }),
+        ...(options.scorerProvenance === undefined
+            ? {}
+            : { scorerProvenance: options.scorerProvenance }),
+    };
 }

package/dist/lab/routing.d.ts

@@ -9,13 +9,13 @@ export declare function registeredScriptedBrowserActors(): string[];
 export declare function actorResolvesToTerminal(type: string | undefined): boolean;
 export declare function registeredTerminalActors(): string[];
 /**
- * The declared fan-out lane count on the computer-use route: a `lanes[]` roster's length, else
+ * The declared fan-out participant count on the computer-use route: a `lanes[]` roster's length, else
  * a homogeneous `count`, else 1. The single source of truth shared by the parser, the engine,
- * and the pre-flight plan so the lane count is computed ONE way everywhere.
+ * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
 export declare function cuaLaneCount(config: LabConfig): number;
 /**
- * A participant's id: its declared roster id, else `lane-NN` (independent lanes) or `role-NN`
+ * 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
  * runs.
@@ -26,21 +26,33 @@ export declare function participantIdAt(index: number, declared: string | undefi
  * 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 lane arrived. Behavior-preserving for every parse-valid config —
+ * 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.)
  */
 export declare function isComputerUseComposition(config: LabConfig): boolean;
 /**
  * True when this config routes to the SHARED-WORLD backend (#164): a clone or local-tree subject
- * on a hosted desktop whose first actor resolves to a computer-use actor AND that declares the
+ * 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 cua 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
+ * 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.
  */
 export declare function isSharedWorldComposition(config: LabConfig): boolean;
+/** The getHost provisioned-subject shared-world shape (clone/local-tree served + exposed in-sandbox). */
+export declare function isProvisionedSharedWorldComposition(config: LabConfig): 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
+ * 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
+ * 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).
+ */
+export declare function isExternalPublicSharedWorldComposition(config: LabConfig): 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
@@ -62,20 +74,3 @@ export declare function isProvisionedScriptedBrowserComposition(config: LabConfi
  * the single source of truth for routeOf and the warning logic.
  */
 export declare function isTerminalProductComposition(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToComputerUse(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToSharedWorld(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToProvisionedSharedWorld(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToExternalPublicSharedWorld(config: LabConfig): boolean;
-/**
- * @deprecated Every shared-world study runs its participants at once since the sequential
- * shared-world route was removed. Use `routeOf`; this alias goes in the next minor.
- */
-export declare function routesToConcurrentSharedWorld(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToScriptedBrowser(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToTerminalProduct(config: LabConfig): boolean;

package/dist/lab/routing.js

@@ -1,6 +1,6 @@
 import { actorRegistry } from "../actors/registry.js";
 import { isLoopbackUrl } from "./parse/subject.js";
-// Hard cap on fan-out lanes (per the ratified design). No HUMANISH_MAX_LANES escape above this
+// 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;
 // Run kinds whose evidence is the participant's screenshots. An actor that declares it produces none
@@ -45,9 +45,9 @@ export function registeredTerminalActors() {
     return registeredActorsOn("terminal");
 }
 /**
- * The declared fan-out lane count on the computer-use route: a `lanes[]` roster's length, else
+ * The declared fan-out participant count on the computer-use route: a `lanes[]` roster's length, else
  * a homogeneous `count`, else 1. The single source of truth shared by the parser, the engine,
- * and the pre-flight plan so the lane count is computed ONE way everywhere.
+ * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
 export function cuaLaneCount(config) {
     const actor = config.actors[0];
@@ -57,7 +57,7 @@ export function cuaLaneCount(config) {
     return actor?.count ?? 1;
 }
 /**
- * A participant's id: its declared roster id, else `lane-NN` (independent lanes) or `role-NN`
+ * 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
  * runs.
@@ -70,7 +70,7 @@ export function participantIdAt(index, declared, kind) {
  * 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 lane arrived. Behavior-preserving for every parse-valid config —
+ * 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.)
  */
@@ -81,7 +81,7 @@ export function isComputerUseComposition(config) {
         return actorResolvesToComputerUse(config.actors[0]?.type);
     }
     // desktop-cli hands the participant a terminal instead of a served page (#495), but it is the
-    // same lane: same desktop, same actor, same prompt fields. Leaving it out of this predicate told
+    // 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.
     if (config.subject.source === "desktop-cli") {
@@ -96,33 +96,33 @@ export function isComputerUseComposition(config) {
 }
 /**
  * True when this config routes to the SHARED-WORLD backend (#164): a clone or local-tree subject
- * on a hosted desktop whose first actor resolves to a computer-use actor AND that declares the
+ * 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 cua 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
+ * 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.
  */
 export function isSharedWorldComposition(config) {
     return (isProvisionedSharedWorldComposition(config) || isExternalPublicSharedWorldComposition(config));
 }
 /** The getHost provisioned-subject shared-world shape (clone/local-tree served + exposed in-sandbox). */
-function isProvisionedSharedWorldComposition(config) {
+export function isProvisionedSharedWorldComposition(config) {
     return ((config.subject.source === "clone" || config.subject.source === "local-tree") &&
         config.subject.topology === "shared-world" &&
         config.execution?.target === "e2b-desktop" &&
         actorResolvesToComputerUse(config.actors[0]?.type));
 }
 /**
- * The EXTERNAL-PUBLIC shared-world shape (#164 phase 2): a real PUBLIC deployment used DIRECTLY as
+ * 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
- * e2b-desktop + `policies.allowPublicTargets: true`. NO getHost, NO clone, NO subject sandbox, NO
+ * 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
  * half-declared external-public config still routes here to get its precise fail-closed reason
- * rather than silently downgrading to the per-lane cua route).
+ * rather than silently downgrading to the per-participant cua route).
  */
-function isExternalPublicSharedWorldComposition(config) {
+export function isExternalPublicSharedWorldComposition(config) {
     return (config.subject.source === "app-url" &&
         config.subject.topology === "shared-world" &&
         config.execution?.target === "e2b-desktop" &&
@@ -179,36 +179,3 @@ export function isProvisionedScriptedBrowserComposition(config) {
 export function isTerminalProductComposition(config) {
     return (config.subject.source === "terminal-product" && actorResolvesToTerminal(config.actors[0]?.type));
 }
-// The package's older names for these predicates. routeOf is the route decision; each of these
-// says whether a config composes that route with a registered actor of its kind.
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export function routesToComputerUse(config) {
-    return isComputerUseComposition(config);
-}
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export function routesToSharedWorld(config) {
-    return isSharedWorldComposition(config);
-}
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export function routesToProvisionedSharedWorld(config) {
-    return isProvisionedSharedWorldComposition(config);
-}
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export function routesToExternalPublicSharedWorld(config) {
-    return isExternalPublicSharedWorldComposition(config);
-}
-/**
- * @deprecated Every shared-world study runs its participants at once since the sequential
- * shared-world route was removed. Use `routeOf`; this alias goes in the next minor.
- */
-export function routesToConcurrentSharedWorld(config) {
-    return isSharedWorldComposition(config);
-}
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export function routesToScriptedBrowser(config) {
-    return isScriptedBrowserComposition(config);
-}
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export function routesToTerminalProduct(config) {
-    return isTerminalProductComposition(config);
-}

package/dist/lab/run-lab-events.d.ts

@@ -1,6 +1,7 @@
 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 { RunLabOptions } from "../run-lab.js";
+import type { InternalRunLabOptions } from "../run-lab.js";
 import type { LabRoute } from "./plan.js";
 import type { LabConfig } from "./types.js";
 /** One participant, as the options' callbacks see it. */
@@ -46,11 +47,11 @@ export type LabEvent = {
 };
 /**
  * The literal values to scrub from an onEvent warning: the provider keys and the declared subject
- * env from every env the run could read (the `env` option, each bag's env, process.env), and the
+ * env from every env the run could read (the `env` option and process.env), and the
  * 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: RunLabOptions, forwardedEnv: Readonly<Record<string, string | undefined>> | undefined): string[];
+export declare function knownSecretValues(config: LabConfig, options: InternalRunLabOptions, 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`.
@@ -58,12 +59,6 @@ export declare function knownSecretValues(config: LabConfig, options: RunLabOpti
 export declare function labEventEmitter(onEvent: ((event: LabEvent) => void | Promise<void>) | undefined, warnings: string[], secretValues: () => string[]): ((event: LabEvent) => 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 hooks pass it, with the route's own field names. */
-type HookParticipant = {
-    laneId: string;
-    laneIndex: number;
-    laneCount: number;
-};
-export declare const participantOf: (participant: HookParticipant) => ParticipantRef;
+/** 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 {};

package/dist/lab/run-lab-events.js

@@ -4,20 +4,12 @@
 import { redactText, scrubLiterals, toErrorMessage } from "../evidence/redaction.js";
 /**
  * The literal values to scrub from an onEvent warning: the provider keys and the declared subject
- * env from every env the run could read (the `env` option, each bag's env, process.env), and the
+ * env from every env the run could read (the `env` option and process.env), and the
  * analysis API key. A callback can hold any of them, and its warning is appended after the route
  * sanitized its own.
  */
 export function knownSecretValues(config, options, forwardedEnv) {
-    const sources = [
-        forwardedEnv,
-        options.env,
-        options.cuaHooks?.env,
-        options.scriptedHooks?.env,
-        options.terminalHooks?.env,
-        options.sharedWorldHooks?.env,
-        process.env,
-    ];
+    const sources = [forwardedEnv, options.env, process.env];
     const names = ["OPENAI_API_KEY", "E2B_API_KEY", "CODEX_API_KEY", ...(config.subject.env ?? [])];
     const values = new Set();
     const add = (value) => {
@@ -28,7 +20,6 @@ export function knownSecretValues(config, options, forwardedEnv) {
     for (const env of sources)
         for (const name of names)
             add(env?.[name]);
-    add(options.automaticAnalysis?.deps?.apiKey);
     return [...values];
 }
 /**
@@ -77,6 +68,7 @@ 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,

package/dist/lab/run-lab-homes.d.ts

@@ -0,0 +1,64 @@
+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";
+/** What `createProvider` receives for each participant. */
+export interface ProviderContext {
+    readonly config: LabConfig;
+    readonly participant: ParticipantRef;
+    readonly executor: CuaExecutor;
+}
+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;
+        appUrl: string;
+    }) => Promise<CuaExecutor>;
+}
+export type StreamEvent = 
+/** Runtime only: `url` carries an auth key and must never be persisted. */
+{
+    type: "ready";
+    participantId: string;
+    sandboxId: string;
+    simId: string;
+    streamId: string;
+    url: string;
+} | {
+    type: "ended";
+    participantId: string;
+    simId: string;
+    streamId: string;
+};
+/** The options with a typed home, common to every route. */
+export interface RunLabHomes {
+    /** Keys and subject env for the run. Defaults to process.env. */
+    env?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Scores the assembled evidence: computer use, shared world and terminal. A scorer written for
+     * one context passes through `browserScorer` or `terminalScorer`; one that narrows `ctx` at
+     * runtime passes as it is.
+     */
+    scorer?: AdapterScorerModule;
+    /** E2B only. Runs after the sandbox exists and before provisioning, once per target. */
+    prepareDesktop?: (desktop: E2BDesktopSandbox, target: SetupTarget) => Promise<void>;
+    /**
+     * 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>;
+    /** 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 = {
+    inProcess?: undefined;
+    createProvider?: ProviderFactory;
+} | {
+    inProcess: InProcessDriver;
+    createProvider: ProviderFactory;
+};

package/dist/lab/run-lab-homes.js

@@ -0,0 +1,3 @@
+// The public RunLabOptions 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/lab/run-lab-options.d.ts

@@ -1,82 +1,28 @@
-import type { CuaExecutor, CuaProvider } from "../actors/computer-use/loop.js";
-import { type CuaActorLabHooks } from "../routes/computer-use/types.js";
-import type { E2BDesktopSandbox } from "../substrates/e2b/sdk.js";
-import type { AdapterScorerModule } from "./adapter-scorer-loader.js";
-import type { LabOutcome, RunLabOptions } from "../run-lab.js";
+import type { InternalRunLabOptions, LabOutcome, RunLabOptions } from "../run-lab.js";
 import { type LabRoute } from "./plan.js";
 import type { LabConfig } from "./types.js";
-import { type LabEvent, type ParticipantRef, type SetupTarget } from "./run-lab-events.js";
-/** What `createProvider` receives for each participant. */
-export interface ProviderContext {
-    readonly config: LabConfig;
-    readonly participant: ParticipantRef;
-    readonly executor: CuaExecutor;
-}
-type ProviderFactory = (ctx: ProviderContext) => Promise<CuaProvider>;
-type StreamEvent = 
-/** Runtime only: `url` carries an auth key and must never be persisted. */
-{
-    type: "ready";
-    participantId: string;
-    sandboxId: string;
-    simId: string;
-    streamId: string;
-    url: string;
-} | {
-    type: "ended";
-    participantId: string;
-    simId: string;
-    streamId: string;
-};
-/** The options with a typed home, common to every route. */
-export interface RunLabHomes {
-    /** Keys and subject env for the run. Defaults to process.env. */
-    env?: Readonly<Record<string, string | undefined>>;
-    /** Scores the assembled evidence: computer use, shared world and terminal. */
-    scorer?: AdapterScorerModule;
-    /** E2B only. Runs after the sandbox exists and before provisioning, once per target. */
-    prepareDesktop?: (desktop: E2BDesktopSandbox, target: SetupTarget) => Promise<void>;
-    /**
-     * 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>;
-    /** 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 = {
-    inProcess?: undefined;
-    createProvider?: ProviderFactory;
-} | {
-    inProcess: {
-        executor: (ctx: {
-            config: LabConfig;
-            appUrl: string;
-        }) => Promise<CuaExecutor>;
-    };
-    createProvider: ProviderFactory;
-};
+import { type LabEvent } from "./run-lab-events.js";
 type Refusal = {
     ok: false;
-    code: "HUMANISH_LAB_OPTION_CONFLICT" | "HUMANISH_LAB_OPTION_UNSUPPORTED";
+    code: "HUMANISH_LAB_OPTION_UNSUPPORTED";
     message: string;
 };
 type Normalized = {
     ok: true;
-    /** The options with every new field mapped into the old bags and removed. */
-    options: RunLabOptions;
+    /** The options the route reads: onEvent removed, env copied. */
+    options: InternalRunLabOptions;
     /** Filled by onEvent failures while the run runs; runLab 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: LabEvent) => void) | undefined;
 };
+/** The refusal for a field a JavaScript caller passed that RunLabOptions no longer has. */
+export declare function removedOptionRefusal(options: RunLabOptions): Refusal | undefined;
 /**
- * Refuse what the route cannot honor, then map the new options into the old bags. Nothing here
- * touches the filesystem, so a refusal leaves no run directory, receipt or sandbox.
+ * 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 normalizeRunLabOptions(config: LabConfig, route: LabRoute, options: RunLabOptions): Normalized | Refusal;
-export declare function scorerHooks(scorer: AdapterScorerModule): Pick<CuaActorLabHooks, "score" | "deriveFeedback" | "deriveArtifacts">;
+export declare function normalizeRunLabOptions(config: LabConfig, route: LabRoute, options: InternalRunLabOptions): Normalized | Refusal;
 /** A refusal in the route's own result envelope, before any run exists. */
 export declare function optionRefusalOutcome(config: LabConfig, route: LabRoute, options: RunLabOptions, refusal: Refusal): LabOutcome;
 export {};