humanish 0.104.3 → 0.106.0

package/dist/lab/route-inputs.js

@@ -0,0 +1,95 @@
+// 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) {
+    return {
+        ...analysisOf(options),
+        cwd: options.cwd,
+        // CLI --count overrides the homogeneous fan-out lane 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),
+    };
+}
+export function scriptedInput(options) {
+    return {
+        ...analysisOf(options),
+        cwd: options.cwd,
+        ...(options.open === undefined ? {} : { open: options.open }),
+        ...(options.runId === undefined ? {} : { runId: options.runId }),
+        ...(options.scriptedHooks === undefined ? {} : { hooks: options.scriptedHooks }),
+    };
+}
+export function terminalInput(options) {
+    return {
+        ...analysisOf(options),
+        cwd: options.cwd,
+        ...(options.open === undefined ? {} : { open: options.open }),
+        ...(options.runId === undefined ? {} : { runId: options.runId }),
+        ...(options.terminalHooks === undefined ? {} : { hooks: options.terminalHooks }),
+        ...scorerOf(options),
+    };
+}
+export function sharedWorldInput(options) {
+    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),
+    };
+}
+/** 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.
+ */
+function withLateScorer(input, declared, hooks, late) {
+    if (late === undefined)
+        return input;
+    return {
+        ...input,
+        ...(hooks === undefined
+            ? {}
+            : { hooks: withHookOverrides(input.hooks, declared, hooks) }),
+        ...(late.scorerProvenance === undefined ? {} : { scorerProvenance: late.scorerProvenance }),
+    };
+}
+function analysisOf(options) {
+    return options.automaticAnalysis === undefined
+        ? {}
+        : { automaticAnalysis: options.automaticAnalysis };
+}
+function scorerOf(options) {
+    return options.scorerProvenance === undefined
+        ? {}
+        : { scorerProvenance: options.scorerProvenance };
+}

package/dist/lab/routing.d.ts

@@ -0,0 +1,81 @@
+import type { LabConfig } from "./types.js";
+export declare const MAX_CUA_LANES = 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
+ *  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[];
+/**
+ * The declared fan-out lane 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.
+ */
+export declare function cuaLaneCount(config: LabConfig): number;
+/**
+ * A participant's id: its declared roster id, else `lane-NN` (independent lanes) 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.
+ */
+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 lane 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
+ * `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
+ * 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.
+ */
+export declare function isSharedWorldComposition(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
+ * (the load-bearing public-safety boundary — a seat only ever drives the in-sandbox app).
+ */
+export declare function resolveSeatUrl(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
+ * source of truth for routeOf and the warning logic.
+ */
+export declare function isScriptedBrowserComposition(config: LabConfig): boolean;
+export declare function isProvisionedScriptedBrowserComposition(config: LabConfig): 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 —
+ * 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;
+/** @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

@@ -0,0 +1,214 @@
+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
+// 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
+// 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([
+    "computer-use",
+    "scripted-browser",
+]);
+function runsOn(capabilities, kind) {
+    return (capabilities.lanes.includes(kind) &&
+        (!SCREENSHOT_RUN_KINDS.has(kind) || capabilities.producesScreenshots));
+}
+function actorResolvesTo(type, kind) {
+    if (!type)
+        return false;
+    const descriptor = actorRegistry[type];
+    return descriptor !== undefined && runsOn(descriptor.capabilities, kind);
+}
+function registeredActorsOn(kind) {
+    return Object.values(actorRegistry)
+        .filter((entry) => runsOn(entry.capabilities, kind))
+        .map((entry) => entry.id);
+}
+export function actorResolvesToComputerUse(type) {
+    return actorResolvesTo(type, "computer-use");
+}
+export function registeredComputerUseActors() {
+    return registeredActorsOn("computer-use");
+}
+export function actorResolvesToScriptedBrowser(type) {
+    return actorResolvesTo(type, "scripted-browser");
+}
+export function registeredScriptedBrowserActors() {
+    return registeredActorsOn("scripted-browser");
+}
+/** True when `type` resolves to a registered terminal actor (the "terminal" lane). Exported so
+ *  the engine + tests can resolve the dispatch the same way the parser does. */
+export function actorResolvesToTerminal(type) {
+    return actorResolvesTo(type, "terminal");
+}
+export function registeredTerminalActors() {
+    return registeredActorsOn("terminal");
+}
+/**
+ * The declared fan-out lane 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.
+ */
+export function cuaLaneCount(config) {
+    const actor = config.actors[0];
+    if (actor?.lanes !== undefined) {
+        return actor.lanes.length;
+    }
+    return actor?.count ?? 1;
+}
+/**
+ * A participant's id: its declared roster id, else `lane-NN` (independent lanes) 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.
+ */
+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 lane 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 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.
+    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
+    // same lane: 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") {
+        return ((config.execution?.target === undefined || config.execution.target === "e2b-desktop") &&
+            actorResolvesToComputerUse(config.actors[0]?.type));
+    }
+    // local-tree packs+uploads the working tree, then serves it exactly like a computer-use clone
+    // subject: same e2b-desktop + computer-use-actor gate.
+    return ((config.subject.source === "clone" || config.subject.source === "local-tree") &&
+        config.execution?.target === "e2b-desktop" &&
+        actorResolvesToComputerUse(config.actors[0]?.type));
+}
+/**
+ * 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
+ * `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
+ * 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.
+ */
+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) {
+    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 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-lane cua route).
+ */
+function isExternalPublicSharedWorldComposition(config) {
+    return (config.subject.source === "app-url" &&
+        config.subject.topology === "shared-world" &&
+        config.execution?.target === "e2b-desktop" &&
+        actorResolvesToComputerUse(config.actors[0]?.type) &&
+        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).
+ */
+export function resolveSeatUrl(serveUrl, entry) {
+    if (entry === undefined || entry === "") {
+        return isLoopbackUrl(serveUrl) ? serveUrl : null;
+    }
+    let base;
+    let resolved;
+    try {
+        base = new URL(serveUrl);
+        resolved = new URL(entry, serveUrl);
+    }
+    catch {
+        return null;
+    }
+    if (resolved.origin !== base.origin) {
+        return null;
+    }
+    const value = resolved.toString();
+    return isLoopbackUrl(value) ? value : 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
+ * source of truth for routeOf and the warning logic.
+ */
+export function isScriptedBrowserComposition(config) {
+    return (isLocalScriptedBrowserComposition(config) || isProvisionedScriptedBrowserComposition(config));
+}
+function isLocalScriptedBrowserComposition(config) {
+    return (config.subject.source === "app-url" && actorResolvesToScriptedBrowser(config.actors[0]?.type));
+}
+export function isProvisionedScriptedBrowserComposition(config) {
+    return (config.subject.source === "clone" &&
+        config.execution?.target === "e2b-desktop" &&
+        actorResolvesToScriptedBrowser(config.actors[0]?.type));
+}
+/**
+ * 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 —
+ * 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 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

@@ -0,0 +1,69 @@
+import type { CuaParticipantPlan } from "../routes/computer-use/types.js";
+import type { SubjectPhaseEvent } from "../subject/steps.js";
+import type { RunLabOptions } from "../run-lab.js";
+import type { LabRoute } from "./plan.js";
+import type { LabConfig } from "./types.js";
+/** One participant, as the options' callbacks see it. */
+export interface ParticipantRef {
+    readonly id: string;
+    /** 0-based position in the roster. */
+    readonly index: number;
+    readonly count: number;
+}
+/** Provisioned shared world and scripted clone labs prepare the shared subject sandbox first. */
+export type SetupTarget = {
+    readonly kind: "subject";
+} | {
+    readonly kind: "participant";
+    readonly participant: ParticipantRef;
+};
+/**
+ * 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)
+ * and shared world (subject target).
+ */
+export type LabEvent = {
+    type: "plan";
+    route: LabRoute;
+    participants: readonly {
+        id: string;
+        persona: string;
+        device?: string;
+        instructionDigest: string;
+    }[];
+} | {
+    type: "subject-phase";
+    target: SetupTarget;
+    name: string;
+    message: string;
+    at: string;
+    ok?: boolean;
+    durationMs?: number;
+} | {
+    type: "analysis-started";
+} | {
+    type: "analysis-finished";
+};
+/**
+ * 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
+ * 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[];
+/**
+ * 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;
+/** 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;
+export declare function phaseEvent(event: SubjectPhaseEvent, target: SetupTarget): LabEvent;
+export {};

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

@@ -0,0 +1,95 @@
+// 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
+// route hook bags it maps; the event values are built here.
+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
+ * 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 names = ["OPENAI_API_KEY", "E2B_API_KEY", "CODEX_API_KEY", ...(config.subject.env ?? [])];
+    const values = new Set();
+    const add = (value) => {
+        const trimmed = value?.trim() ?? "";
+        if (trimmed.length >= 4)
+            values.add(trimmed);
+    };
+    for (const env of sources)
+        for (const name of names)
+            add(env?.[name]);
+    add(options.automaticAnalysis?.deps?.apiKey);
+    return [...values];
+}
+/**
+ * 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) {
+    if (onEvent === undefined)
+        return undefined;
+    return (event) => {
+        // Read before the callback runs: the callback can redefine anything on the event.
+        const type = event.type;
+        // Total: a thrown value can refuse to become a string, and nothing may escape from here.
+        const report = (error) => {
+            let detail;
+            try {
+                // Read here, not up front: a run with no failing callback never touches the env.
+                const scrub = scrubLiterals(secretValues());
+                detail = redactText(scrub(toErrorMessage(error)));
+            }
+            catch {
+                detail = "the thrown value has no message";
+            }
+            warnings.push(`RunLabOptions.onEvent failed on ${type}: ${detail}`);
+        };
+        try {
+            const returned = onEvent(event);
+            if (returned !== undefined)
+                Promise.resolve(returned).then(undefined, report);
+        }
+        catch (error) {
+            report(error);
+        }
+    };
+}
+/** The computer-use participant plan as a `plan` event: ids, personas, devices and digests. */
+export function planEvent(plan) {
+    return {
+        type: "plan",
+        route: "computer-use",
+        participants: plan.lanes.map((participant) => ({
+            id: participant.id,
+            persona: participant.persona,
+            device: participant.device,
+            instructionDigest: participant.instructionDigest,
+        })),
+    };
+}
+export const participantOf = (participant) => ({
+    id: participant.laneId,
+    index: participant.laneIndex,
+    count: participant.laneCount,
+});
+export function phaseEvent(event, target) {
+    return {
+        type: "subject-phase",
+        target,
+        name: event.type,
+        message: event.message,
+        at: event.at,
+        ...(event.ok === undefined ? {} : { ok: event.ok }),
+        ...(event.durationMs === undefined ? {} : { durationMs: event.durationMs }),
+    };
+}

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

@@ -0,0 +1,82 @@
+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 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;
+};
+type Refusal = {
+    ok: false;
+    code: "HUMANISH_LAB_OPTION_CONFLICT" | "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;
+    /** Filled by onEvent failures while the run runs; runLab appends them to the result. */
+    warnings: string[];
+};
+/**
+ * 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.
+ */
+export declare function normalizeRunLabOptions(config: LabConfig, route: LabRoute, options: RunLabOptions): Normalized | Refusal;
+export declare function scorerHooks(scorer: AdapterScorerModule): Pick<CuaActorLabHooks, "score" | "deriveFeedback" | "deriveArtifacts">;
+/** 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 {};