humanish 0.104.3 → 0.106.0

package/dist/lab/plan-participants.d.ts

@@ -0,0 +1,81 @@
+import type { DwellWindow, StopWhen } from "../actors/stop-conditions.js";
+import type { ReasoningEffort } from "../actors/reasoning-effort.js";
+import { type DevicePreset } from "./device-presets.js";
+import type { LabTask } from "./tasks.js";
+import type { LabConfig } from "./types.js";
+/** Who one participant is. Every route with participants carries this record. */
+export interface Participant {
+    /** Declared roster id, else `lane-NN` (independent lanes) or `role-NN` (shared-world seats). */
+    readonly id: string;
+    /** 0-based position in the roster. Bundle `sim-NNN` and `stream-NNN` ids derive from it. */
+    readonly index: number;
+    /** `lanes[i].persona ?? actors[0].persona`. The route compiles the committed persona file. */
+    readonly personaId: string | undefined;
+    /** The declared mission and per-participant focus. An absent mission takes the route's default. */
+    readonly assignment: {
+        readonly mission?: string;
+        readonly focus?: string;
+    };
+    /** Taxonomy labels copied to the bundle and the plan table; they change no behavior. */
+    readonly labels: {
+        readonly actorType?: string;
+        readonly surface?: string;
+        readonly caseGroup?: string;
+    };
+}
+/** A participant at a desktop: computer use and shared world. */
+interface DesktopParticipant extends Participant {
+    readonly device: {
+        readonly name: string;
+        readonly preset: DevicePreset;
+        readonly resolution: [number, number];
+    };
+    /** Lane value, else actor value, else absent (the provider default is recorded in the trace). */
+    readonly limits: {
+        readonly stopWhen?: StopWhen;
+        readonly dwell?: DwellWindow;
+        readonly reasoningEffort?: ReasoningEffort;
+        readonly maxOutputTokens?: number;
+    };
+}
+/** Only independent computer-use lanes consume a task protocol and a per-lane target. */
+export interface ComputerUseParticipant extends DesktopParticipant {
+    readonly tasks?: readonly LabTask[];
+    /** app-url fan-out only: this lane's own entry URL; absent means the subject URL. */
+    readonly targetUrl?: string;
+}
+/** A seat on a provisioned plane: an optional same-origin path under `serve.url`. */
+export interface ProvisionedParticipant extends DesktopParticipant {
+    readonly entry?: string;
+    readonly host?: never;
+    readonly tasks?: never;
+    readonly targetUrl?: never;
+}
+/** A seat on an external public plane: exactly one seat hosts the shared session. */
+export interface ExternalPublicParticipant extends DesktopParticipant {
+    readonly host: boolean;
+    readonly entry?: never;
+    readonly tasks?: never;
+    readonly targetUrl?: never;
+}
+export type SharedWorldRoster = {
+    readonly plane: "provisioned";
+    readonly participants: readonly ProvisionedParticipant[];
+} | {
+    readonly plane: "external-public";
+    readonly participants: readonly ExternalPublicParticipant[];
+};
+/** One shared-world participant on either plane. */
+export type SharedWorldParticipant = ProvisionedParticipant | ExternalPublicParticipant;
+/**
+ * The lanes of a computer-use lab: the declared roster, else `count` identical lanes. A count
+ * override (`--count`) applies only when no roster is declared.
+ */
+export declare function computerUseParticipants(config: LabConfig, countOverride?: number): ComputerUseParticipant[];
+/** The participants of a shared-world lab, one per roster entry, typed by the plane they share. */
+export declare function sharedWorldParticipants(config: LabConfig): SharedWorldRoster;
+/** The ids of the participants a computer-use or shared-world lab runs, in roster order. */
+export declare function declaredParticipantIds(config: LabConfig): string[];
+/** The entry URLs roster entries declare in place of the subject URL (computer use, app-url). */
+export declare function declaredTargets(config: LabConfig): string[];
+export {};

package/dist/lab/plan-participants.js

@@ -0,0 +1,92 @@
+// Who takes part in a lab: one record per participant, built from the declared roster or a count.
+// Computer-use lanes and shared-world seats share the desktop fields; each kind adds its own.
+import { resolveParticipantDevice } from "./device-presets.js";
+import { isSharedWorldComposition, participantIdAt } from "./routing.js";
+import { focusOf, rosterOf } from "./parse/actors.js";
+function desktopParticipant(config, entry, index, kind, focus) {
+    const actor = config.actors[0];
+    const device = resolveParticipantDevice(config, entry?.device);
+    const personaId = entry?.persona ?? actor?.persona;
+    const mission = actor?.mission;
+    const stopWhen = entry?.stopWhen ?? actor?.stopWhen;
+    const dwell = entry?.dwell ?? actor?.dwell;
+    const reasoningEffort = entry?.reasoningEffort ?? actor?.reasoningEffort;
+    const maxOutputTokens = actor?.maxOutputTokens;
+    return {
+        id: participantIdAt(index, entry?.id, kind),
+        index,
+        personaId,
+        assignment: {
+            ...(mission === undefined ? {} : { mission }),
+            ...(focus === undefined ? {} : { focus }),
+        },
+        labels: {
+            ...(entry?.actorType === undefined ? {} : { actorType: entry.actorType }),
+            ...(entry?.surface === undefined ? {} : { surface: entry.surface }),
+            ...(entry?.caseGroup === undefined ? {} : { caseGroup: entry.caseGroup }),
+        },
+        device: { name: device.name, preset: device.preset, resolution: device.resolution },
+        limits: {
+            ...(stopWhen === undefined ? {} : { stopWhen }),
+            ...(dwell === undefined ? {} : { dwell }),
+            ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+            ...(maxOutputTokens === undefined ? {} : { maxOutputTokens }),
+        },
+    };
+}
+/**
+ * The lanes of a computer-use lab: the declared roster, else `count` identical lanes. A count
+ * override (`--count`) applies only when no roster is declared.
+ */
+export function computerUseParticipants(config, countOverride) {
+    const actor = config.actors[0];
+    const roster = rosterOf(actor);
+    const count = roster ? roster.length : Math.max(1, countOverride ?? actor?.count ?? 1);
+    return Array.from({ length: count }, (_, index) => {
+        const entry = roster?.[index];
+        const focus = roster ? entry?.instruction : focusOf(actor)?.instruction;
+        return {
+            ...desktopParticipant(config, entry, index, "lane", focus),
+            ...(actor?.tasks === undefined ? {} : { tasks: actor.tasks }),
+            ...(entry?.target === undefined ? {} : { targetUrl: entry.target }),
+        };
+    });
+}
+/** The participants of a shared-world lab, one per roster entry, typed by the plane they share. */
+export function sharedWorldParticipants(config) {
+    const roster = rosterOf(config.actors[0]) ?? [];
+    const participantAt = (entry, index) => desktopParticipant(config, entry, index, "seat", entry.instruction);
+    if (config.subject.source === "app-url") {
+        return {
+            plane: "external-public",
+            participants: roster.map((entry, index) => ({
+                ...participantAt(entry, index),
+                host: entry.host === true,
+            })),
+        };
+    }
+    return {
+        plane: "provisioned",
+        participants: roster.map((entry, index) => ({
+            ...participantAt(entry, index),
+            ...(entry.entry === undefined ? {} : { entry: entry.entry }),
+        })),
+    };
+}
+/** The ids of the participants a computer-use or shared-world lab runs, in roster order. */
+export function declaredParticipantIds(config) {
+    const actor = config.actors[0];
+    const roster = rosterOf(actor);
+    const kind = isSharedWorldComposition(config) ? "seat" : "lane";
+    if (roster && roster.length > 0) {
+        return roster.map((entry, index) => participantIdAt(index, entry.id, kind));
+    }
+    const count = Math.max(1, actor?.count ?? 1);
+    return Array.from({ length: count }, (_, index) => participantIdAt(index, undefined, kind));
+}
+/** The entry URLs roster entries declare in place of the subject URL (computer use, app-url). */
+export function declaredTargets(config) {
+    return (rosterOf(config.actors[0]) ?? [])
+        .map((entry) => entry.target)
+        .filter((target) => target !== undefined);
+}

package/dist/lab/plan-types.d.ts

@@ -0,0 +1,269 @@
+import type { AnalysisConfig } from "../analysis/types.js";
+import type { LocalAgentId } from "../actors/local-agent/cli.js";
+import type { ReasoningEffort } from "../actors/reasoning-effort.js";
+import type { BrowserSurface } from "../actors/scripted-browser/types.js";
+import type { ScriptedRefusal } from "../routes/scripted/plan.js";
+import type { TerminalRefusal } from "../routes/terminal/plan.js";
+import type { RunLabProvenance } from "../run/status.js";
+import type { ComputerUseRefusal } from "../routes/computer-use/plan.js";
+import type { SharedWorldRefusal } from "../routes/shared-world/plan.js";
+import type { ComputerUseParticipant, ExternalPublicParticipant, ProvisionedParticipant } from "./plan-participants.js";
+import type { LabConfig, LabExecutionTerminal, LabRuntimeAuth, LabScenarioCaps, LabSubjectProduct, LabSubjectServe, LabSubjectState, LabSubjectStateCheckpoint } from "./types.js";
+export type NonEmpty<T> = readonly [T, ...T[]];
+type AtLeastTwo<T> = readonly [T, T, ...T[]];
+/** Something a route checks right before acquisition. Doctor, the TUI and preflight list the same set. */
+export type Requirement = {
+    readonly kind: "key";
+    readonly name: "OPENAI_API_KEY" | "E2B_API_KEY";
+}
+/** The terminal runtime key: CODEX_API_KEY, else OPENAI_API_KEY. */
+ | {
+    readonly kind: "key-one-of";
+    readonly names: readonly ["CODEX_API_KEY", "OPENAI_API_KEY"];
+}
+/** Real receiving: the key name comes from the saved connection at check time. */
+ | {
+    readonly kind: "receiving-connection";
+    readonly connection: string;
+} | {
+    readonly kind: "subject-env";
+    readonly names: NonEmpty<string>;
+} | {
+    readonly kind: "local-agent";
+    readonly agent: LocalAgentId;
+} | {
+    readonly kind: "local-vm";
+} | {
+    readonly kind: "host-browser";
+} | {
+    readonly kind: "external-catch";
+    readonly url: string;
+};
+/** Config fields no plan field decides. Routes read nothing else from the config. */
+export type ResidualConfig = Pick<LabConfig, "comms" | "policies" | "personas" | "defaults" | "review"> & {
+    readonly execution?: Pick<NonNullable<LabConfig["execution"]>, "desktop" | "target">;
+    readonly subject: Pick<LabConfig["subject"], "clone" | "localTree" | "repos" | "envValues">;
+};
+export interface PlannedAnalysis {
+    readonly config: AnalysisConfig;
+    /** "default" when the lab declared no review.analysis. */
+    readonly trigger: "default" | "explicit";
+    readonly preferLargerOutput: boolean;
+}
+interface PlanBase {
+    readonly labId: string;
+    /** The lab's declared title, which bundles record. */
+    readonly title?: string;
+    readonly lab?: RunLabProvenance;
+    /** A frozen copy owned by the plan. */
+    readonly residual: Readonly<ResidualConfig>;
+    readonly dryRun: boolean;
+    readonly analysis?: PlannedAnalysis;
+    /** Empty for a dry run. */
+    readonly requirements: readonly Requirement[];
+}
+/**
+ * The synthetic preview. planPreview refuses a count that is not a positive integer and a live
+ * request, so the plan carries only a dry run and a checked count. runDryRun still checks the
+ * project directory, which needs the file system.
+ */
+interface PreviewPlan extends PlanBase {
+    readonly route: "preview";
+    readonly dryRun: true;
+    /** A safe integer of at least 1. */
+    readonly participantCount: number;
+}
+/** The model driving a desktop participant. `caller` is the library caller's buildProvider. */
+export type Brain = {
+    readonly kind: "openai";
+    readonly model: string;
+} | {
+    readonly kind: "local-agent";
+    readonly agent: LocalAgentId;
+} | {
+    readonly kind: "caller";
+};
+export type ProvisionedSubject = {
+    readonly kind: "clone";
+    readonly repo: string;
+    readonly serve: LabSubjectServe;
+    readonly env: readonly string[];
+    readonly state?: LabSubjectState;
+} | {
+    readonly kind: "local-tree";
+    readonly serve: LabSubjectServe;
+    readonly env: readonly string[];
+    readonly state?: LabSubjectState;
+};
+export interface AppUrlSubject {
+    readonly kind: "app-url";
+    readonly appUrl: string;
+    readonly publicTargets: boolean;
+}
+/**
+ * Supported subject and desktop pairings. The local VM also takes public targets: the route runs
+ * that for a library caller, though the parser never produces it.
+ */
+export type ComputerUseRunner = {
+    readonly desktop: "e2b-desktop";
+    readonly brain: Brain;
+    readonly participants: NonEmpty<ComputerUseParticipant>;
+    readonly subject: AppUrlSubject | ProvisionedSubject | {
+        readonly kind: "desktop-cli";
+        readonly product: LabSubjectProduct;
+    };
+} | {
+    readonly desktop: "local-vm";
+    readonly brain: Brain;
+    readonly participants: NonEmpty<ComputerUseParticipant>;
+    readonly subject: AppUrlSubject;
+}
+/** The caller's executor and provider together; one participant. */
+ | {
+    readonly desktop: "in-process";
+    readonly brain: {
+        readonly kind: "caller";
+    };
+    readonly participants: readonly [ComputerUseParticipant];
+    readonly subject: AppUrlSubject | {
+        readonly kind: "local-app";
+        readonly appUrl: string;
+    };
+};
+export interface ComputerUsePlan extends PlanBase {
+    readonly route: "computer-use";
+    /** The registered computer-use actor id. */
+    readonly actor: string;
+    readonly runner: ComputerUseRunner;
+    /** Declared cap clamped to [1, participants]; the route may only lower it from env. */
+    readonly concurrency: number;
+    readonly sessionBudgetMs: number;
+    readonly sandboxMs: number;
+    readonly caps: {
+        readonly maxUsd?: number;
+        readonly maxTotalUsd?: number;
+    };
+    /** The route narrows participants after reading the source run. */
+    readonly rerun?: {
+        readonly sourceRunId: string;
+        readonly participantIds?: readonly string[];
+    };
+}
+type CheckpointedState = LabSubjectState & {
+    readonly checkpoint: NonEmpty<LabSubjectStateCheckpoint>;
+};
+export type SharedWorldPlane = {
+    readonly kind: "provisioned";
+    readonly subject: ProvisionedSubject & {
+        readonly state: CheckpointedState;
+    };
+    readonly participants: AtLeastTwo<ProvisionedParticipant>;
+} | {
+    readonly kind: "external-public";
+    readonly appUrl: string;
+    readonly owner: string;
+    readonly participants: AtLeastTwo<ExternalPublicParticipant>;
+};
+export interface SharedWorldPlan extends PlanBase {
+    readonly route: "shared-world";
+    /** The registered computer-use actor id. */
+    readonly actor: string;
+    readonly plane: SharedWorldPlane;
+    /** At least 2. */
+    readonly concurrency: number;
+    /** The declared seat session timeout; the route supplies its default. */
+    readonly sessionTimeoutMs?: number;
+    readonly brain: Extract<Brain, {
+        kind: "openai" | "local-agent";
+    }>;
+    readonly caps: {
+        readonly maxUsd?: number;
+        readonly maxTotalUsd?: number;
+    };
+}
+export type TerminalPlan = PlanBase & {
+    readonly route: "terminal";
+    /** The registered terminal actor that runs. */
+    readonly actor: string;
+    readonly product: LabSubjectProduct & {
+        readonly publicSurfaces: NonEmpty<string>;
+    };
+    /** The declared persona and mission; the route supplies its defaults. */
+    readonly personaId?: string;
+    readonly mission?: string;
+    readonly runtime: {
+        readonly version?: string;
+        readonly model?: string;
+        readonly reasoningEffort?: ReasoningEffort;
+        readonly auth?: LabRuntimeAuth;
+    };
+    /** The declared egress routing allowlist; without one the sandbox egress is unrestricted. */
+    readonly egressAllow?: readonly string[];
+    /** The declared operator stdin posture; the route defaults to "disabled". */
+    readonly stdin?: NonNullable<LabExecutionTerminal["stdin"]>;
+} & ({
+    readonly dryRun: true;
+    readonly caps?: LabScenarioCaps;
+} | {
+    readonly dryRun: false;
+    readonly caps: LabScenarioCaps & {
+        readonly maxUsd: number;
+        readonly maxMinutes: number;
+    };
+});
+export interface ScriptedPlan extends PlanBase {
+    readonly route: "scripted";
+    /** The registered scripted-browser actor id. */
+    readonly actor: string;
+    /**
+     * The loopback URL is normalized. The parser requires seed state on a clone; the route runs a
+     * library caller's clone without it, so the plan does too.
+     */
+    readonly subject: {
+        readonly kind: "loopback";
+        readonly appUrl: string;
+    } | Extract<ProvisionedSubject, {
+        readonly kind: "clone";
+    }>;
+    /** Resolved and parsed by the route, right before the run. */
+    readonly scenarioRef: string;
+    /** Empty only for a library caller's `count: 0`, which the parser refuses; that run has no sessions. */
+    readonly surfaces: readonly BrowserSurface[];
+    /** The declared persona and session timeout; the route supplies its defaults. */
+    readonly personaId?: string;
+    readonly sessionTimeoutMs?: number;
+}
+export type LabPlan = PreviewPlan | ComputerUsePlan | SharedWorldPlan | TerminalPlan | ScriptedPlan;
+interface PlannedLab {
+    readonly plan: LabPlan;
+}
+/**
+ * The error a route returns before a run starts: the route, its error code and a message. Each
+ * route's refusal extends it with what that route adds (the registered actor, where the route
+ * returns it).
+ */
+export interface RouteRefusal<Route extends string, Code extends string> {
+    readonly route: Route;
+    readonly code: Code;
+    readonly message: string;
+}
+/** A route's plan, or the refusal that stopped it before a run started. */
+export type RoutePlanResult<Plan, Refusal> = {
+    readonly ok: true;
+    readonly plan: Plan;
+} | {
+    readonly ok: false;
+    readonly refusal: Refusal;
+};
+/** The error codes the preview route returns before a run starts. */
+export type PreviewRefusalCode = "HUMANISH_LAB_COMMS_UNSUPPORTED" | "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_ANALYSIS_UNSUPPORTED" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_INVALID_SIM_COUNT" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED";
+/** Why planLab refused: the route's own code and message, as its runner returns them. */
+export type PlanRefusal = RouteRefusal<"preview", PreviewRefusalCode> | TerminalRefusal | ScriptedRefusal | ComputerUseRefusal | SharedWorldRefusal;
+export type PlanResult = {
+    readonly ok: true;
+    readonly planned: PlannedLab;
+} | {
+    readonly ok: false;
+    readonly refusal: PlanRefusal;
+};
+export {};

package/dist/lab/plan-types.js

@@ -0,0 +1,5 @@
+// The LabPlan union: what planLab decides about a lab before anything runs. Each route has its own
+// variant, and each supported subject and substrate pairing is its own case, so a combination the
+// routes refuse cannot be written down. Numeric bounds, unique ids, safe URLs and "exactly one
+// host" stay checks in planLab.
+export {};

package/dist/lab/plan.d.ts

@@ -0,0 +1,27 @@
+import type { RunLabOptions } from "../run-lab.js";
+import type { PlanResult } from "./plan-types.js";
+import type { LabConfig } from "./types.js";
+/** The five execution paths a lab can take. */
+export type LabRoute = "preview" | "computer-use" | "shared-world" | "terminal" | "scripted";
+/** A route's older name, kept in `LabOutcome.backend` and the preflight result's `backend`. */
+export type LabBackend = "synthetic" | "cua" | "scripted" | "terminal" | "concurrent-shared-world";
+/** The backend name older callers and wire fields use for a route. */
+export declare function backendOf(route: LabRoute): LabBackend;
+/**
+ * The backend a config runs on: `routeOf`, under its older name.
+ * @deprecated Use `routeOf`, and `backendOf` for the older backend name. This goes in the next minor.
+ */
+export declare function selectLabBackend(config: LabConfig): LabBackend;
+/**
+ * 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: LabConfig): LabRoute;
+/** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
+export declare function resolveLabDryRun(config: LabConfig, override: boolean | undefined, fallback: boolean | undefined): boolean | undefined;
+/**
+ * The plan a lab runs under, built without reading files, env or the network. Each route's planner
+ * makes every refusal that route makes, in the route's order and with its codes and messages; the
+ * route's exported runner calls the same planner.
+ */
+export declare function planLab(config: LabConfig, options: RunLabOptions): PlanResult;

package/dist/lab/plan.js

@@ -0,0 +1,156 @@
+// The route decision. A lab's route follows from its composition (subject.source,
+// execution.target, the first actor's registered lane, subject.topology), never from a declared
+// kind. This is the only function that decides it; backendOf maps its answer to the older
+// backend names.
+import { resolveAutomaticAnalysis } from "../analysis/automatic-config.js";
+import { planComputerUseLab } from "../routes/computer-use/plan.js";
+import { planScriptedLab } from "../routes/scripted/plan.js";
+import { planSharedWorldLab } from "../routes/shared-world/plan.js";
+import { planTerminalLab } from "../routes/terminal/plan.js";
+import { localBrowserDefaults } from "../substrates/local/runtime-config.js";
+import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
+import { planBase } from "./plan-base.js";
+import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
+import { automaticAnalysisRouteReason, taskProtocolValidationReason } from "./validation.js";
+const BACKENDS = {
+    preview: "synthetic",
+    "computer-use": "cua",
+    "shared-world": "concurrent-shared-world",
+    terminal: "terminal",
+    scripted: "scripted",
+};
+/** The backend name older callers and wire fields use for a route. */
+export function backendOf(route) {
+    return BACKENDS[route];
+}
+/**
+ * The backend a config runs on: `routeOf`, under its older name.
+ * @deprecated Use `routeOf`, and `backendOf` for the older backend name. This goes in the next minor.
+ */
+export function selectLabBackend(config) {
+    return backendOf(routeOf(config));
+}
+/**
+ * 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 as
+    // independent lanes.
+    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";
+}
+/** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
+export function resolveLabDryRun(config, override, fallback) {
+    if (override !== undefined) {
+        return override;
+    }
+    if (config.scenario?.mode === "live") {
+        return false;
+    }
+    if (config.scenario?.mode === "dry-run") {
+        return true;
+    }
+    return fallback;
+}
+/**
+ * The preview route's refusals before a run starts, in its order: real email receiving, then
+ * analysis, then tasks. Each would otherwise be silently ignored by a synthetic run.
+ */
+function planPreview(config, options, input) {
+    const refuse = (code, message) => ({
+        ok: false,
+        refusal: { route: "preview", code, message },
+    });
+    if (String(config.comms?.email?.kind) === "real")
+        return refuse("HUMANISH_LAB_COMMS_UNSUPPORTED", "Real email receiving is unsupported on the preview route. Use a supported hosted computer-use lab.");
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    if (!analysis.ok)
+        return refuse("HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
+    const unsupported = automaticAnalysisRouteReason(config);
+    if (unsupported)
+        return refuse("HUMANISH_LAB_ANALYSIS_UNSUPPORTED", unsupported);
+    const tasksReason = taskProtocolValidationReason(config);
+    if (tasksReason)
+        return refuse("HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason);
+    const participantCount = options.count ?? config.actors[0]?.count ?? 4;
+    if (!Number.isSafeInteger(participantCount) || participantCount < 1)
+        return refuse("HUMANISH_INVALID_SIM_COUNT", "count must be a positive integer.");
+    if (!input.dryRun)
+        return refuse("HUMANISH_LIVE_RUN_UNIMPLEMENTED", THIS_REPO_DRY_RUN_ONLY);
+    return {
+        ok: true,
+        plan: {
+            ...planBase(config, { ...input, analysis }),
+            route: "preview",
+            dryRun: true,
+            participantCount,
+        },
+    };
+}
+/**
+ * The plan a lab runs under, built without reading files, env or the network. Each route's planner
+ * makes every refusal that route makes, in the route's order and with its codes and messages; the
+ * route's exported runner calls the same planner.
+ */
+export function planLab(config, options) {
+    const lab = localBrowserDefaults(config);
+    const input = {
+        dryRun: resolveLabDryRun(lab, options.dryRun, true) ?? true,
+        ...(options.lab === undefined ? {} : { lab: options.lab }),
+    };
+    const result = planRoute(routeOf(config), lab, options, input);
+    if (!result.ok)
+        return result;
+    return { ok: true, planned: { plan: result.plan } };
+}
+function planRoute(route, lab, options, input) {
+    switch (route) {
+        case "preview":
+            return planPreview(lab, options, input);
+        case "computer-use":
+            return planComputerUseLab(lab, {
+                ...input,
+                ...(options.cuaHooks === undefined ? {} : { hooks: options.cuaHooks }),
+                ...(options.count === undefined ? {} : { countOverride: options.count }),
+                ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
+            });
+        case "shared-world":
+            return planSharedWorldLab(lab, {
+                ...input,
+                ...(options.sharedWorldHooks === undefined ? {} : { hooks: options.sharedWorldHooks }),
+            });
+        case "terminal":
+            return planTerminalLab(lab, {
+                ...input,
+                ...(options.terminalHooks === undefined ? {} : { hooks: options.terminalHooks }),
+            });
+        case "scripted":
+            return planScriptedLab(lab, {
+                ...input,
+                ...(options.scriptedHooks === undefined ? {} : { hooks: options.scriptedHooks }),
+            });
+    }
+}

package/dist/lab/preflight-probes.d.ts

@@ -0,0 +1,3 @@
+import type { LabPreflightResult, PreflightContext } from "./preflight.js";
+export declare function runPublicPreviewPreflight(ctx: PreflightContext): Promise<LabPreflightResult>;
+export declare function runSandboxLoopbackPreflight(ctx: PreflightContext): Promise<LabPreflightResult>;