humanish 0.106.1 → 0.108.0

package/dist/routes/computer-use/participant-runs.d.ts

@@ -5,25 +5,25 @@ import { type RunRerunLineage } from "../../run/bundle.js";
 import type { PreparedSelectedOutputDirectory } from "../../run/contained-output.js";
 import { type CuaActorLabErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun } from "./types.js";
 export declare function defaultSessionTimeoutMs(config: LabConfig): number;
-/** Per-lane sandbox deadline (each lane owns its own desktop). Mirrors the single-lane formula
- *  verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
+/** Per-participant sandbox deadline (each one owns its own desktop). Mirrors the
+ *  single-participant formula verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
  *  or local-tree: provision budget + Σ state-step budgets) + the server-side
  *  reclamation buffer. Local-tree shares the clone route's provisioning budget: it swaps a
  *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
  *  costs the same wall-clock room either way. */
 export declare function resolveParticipantSandboxMs(config: LabConfig): number;
 /**
- * The in-flight participant bound a lab declares. Defaults to the participant count — every
+ * The in-flight participant bound a lab declares. Defaults to the participant count: every
  * declared participant runs at once, because a throttle nobody asked for silently turns "N actors
- * live" into waves (#350); total session count and spend are the same either way, only wall-clock
- * and simultaneity differ. A declared execution.concurrency is a CAP, clamped to [1, participants].
+ * live" into waves; total session count and spend are the same either way, only wall-clock
+ * and simultaneity differ. A declared execution.concurrency is a cap, clamped to [1, participants].
  * The planner records it; the route may only lower it from the environment.
  */
 export declare function boundedConcurrency(declared: number | undefined, participantCount: number): number;
 /**
- * Pure pre-flight plan resolver (runs in dry-run AND live). Returns the lane table, the
- * effective concurrency, the wave count, the per-lane session budget, and the worst-case total
- * sandbox-minutes — BEFORE any sandbox or provider call. The same plan appears in dry-run,
+ * Pure pre-flight plan resolver (runs in dry-run and live). Returns the participant table, the
+ * effective concurrency, the wave count, the per-participant session budget, and the worst-case total
+ * sandbox-minutes, before any sandbox or provider call. The same plan appears in dry-run,
  * marked $0 (dryRun: true).
  */
 export declare function resolveCuaParticipantPlan(config: LabConfig, opts?: {
@@ -32,8 +32,8 @@ export declare function resolveCuaParticipantPlan(config: LabConfig, opts?: {
     dryRun?: boolean;
     personas?: Map<string, ResolvedPersona>;
 }): CuaParticipantPlan;
-/** Print the lane plan to stderr BEFORE any sandbox/provider call (public-safe: ids, devices,
- *  digests, and budgets only — no prompt text, no secrets). */
+/** Print the participant plan to stderr before any sandbox/provider call (public-safe: ids, devices,
+ *  digests, and budgets only; no prompt text, no secrets). */
 export declare function emitPreflightPlan(participantPlan: CuaParticipantPlan, labId: string): void;
 export declare function formatParticipantPlanEntry(entry: CuaParticipantPlanEntry): string;
 /**
@@ -63,5 +63,5 @@ export declare function loadCuaParticipants(args: {
     code: CuaActorLabErrorCode;
     message: string;
 }>;
-/** Scrub known secret values from each lane's declarative snapshot before any bundle uses it. */
+/** Scrub known secret values from each participant's declarative snapshot before any bundle uses it. */
 export declare function sanitizeParticipantRuns(runs: readonly DesktopParticipantRun[], scrub: (text: string) => string): void;

package/dist/routes/computer-use/participant-runs.js

@@ -26,8 +26,8 @@ export function defaultSessionTimeoutMs(config) {
     const room = MAX_SANDBOX_MS - SUBJECT_PROVISION_BUDGET_MS - stateBudgetMs - SANDBOX_TIMEOUT_BUFFER_MS;
     return Math.max(MIN_DERIVED_SESSION_TIMEOUT_MS, Math.min(DEFAULT_APP_URL_SESSION_TIMEOUT_MS, room));
 }
-/** Per-lane sandbox deadline (each lane owns its own desktop). Mirrors the single-lane formula
- *  verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
+/** Per-participant sandbox deadline (each one owns its own desktop). Mirrors the
+ *  single-participant formula verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
  *  or local-tree: provision budget + Σ state-step budgets) + the server-side
  *  reclamation buffer. Local-tree shares the clone route's provisioning budget: it swaps a
  *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
@@ -46,18 +46,18 @@ export function resolveParticipantSandboxMs(config) {
             SANDBOX_TIMEOUT_BUFFER_MS);
 }
 /**
- * The in-flight participant bound a lab declares. Defaults to the participant count — every
+ * The in-flight participant bound a lab declares. Defaults to the participant count: every
  * declared participant runs at once, because a throttle nobody asked for silently turns "N actors
- * live" into waves (#350); total session count and spend are the same either way, only wall-clock
- * and simultaneity differ. A declared execution.concurrency is a CAP, clamped to [1, participants].
+ * live" into waves; total session count and spend are the same either way, only wall-clock
+ * and simultaneity differ. A declared execution.concurrency is a cap, clamped to [1, participants].
  * The planner records it; the route may only lower it from the environment.
  */
 export function boundedConcurrency(declared, participantCount) {
     return Math.max(1, declared === undefined ? participantCount : Math.min(Math.max(1, declared), participantCount));
 }
 /**
- * The planned bound, lowered by the env override. The override may only LOWER it (never raise
- * concurrent paid desktops — invariant 3), and a lowering is reported via envLoweredFrom so the
+ * The planned bound, lowered by the env override. The override may only lower it (never raise
+ * concurrent paid desktops), and a lowering is reported via envLoweredFrom so the
  * plan never silently disagrees with the manifest.
  */
 function envLoweredConcurrency(planned, participantCount, env) {
@@ -81,7 +81,7 @@ function plannedParticipantsOf(config, countOverride) {
         desktopCli: config.subject.source === "desktop-cli",
     };
 }
-/** Build the participant runs AND the public plan from the planned participants (pure). */
+/** Build the participant runs and the public plan from the planned participants (pure). */
 function participantRunsAndPlan(planned, opts = {}) {
     const env = opts.env ?? {};
     // Who each participant is (id, persona, focus, device, limits) comes from the plan; this adds
@@ -162,20 +162,20 @@ function participantRunsAndPlan(planned, opts = {}) {
     return { runs, participantPlan };
 }
 /**
- * Pure pre-flight plan resolver (runs in dry-run AND live). Returns the lane table, the
- * effective concurrency, the wave count, the per-lane session budget, and the worst-case total
- * sandbox-minutes — BEFORE any sandbox or provider call. The same plan appears in dry-run,
+ * Pure pre-flight plan resolver (runs in dry-run and live). Returns the participant table, the
+ * effective concurrency, the wave count, the per-participant session budget, and the worst-case total
+ * sandbox-minutes, before any sandbox or provider call. The same plan appears in dry-run,
  * marked $0 (dryRun: true).
  */
 export function resolveCuaParticipantPlan(config, opts = {}) {
     const { countOverride, ...rest } = opts;
     return participantRunsAndPlan(plannedParticipantsOf(config, countOverride), rest).participantPlan;
 }
-/** Print the lane plan to stderr BEFORE any sandbox/provider call (public-safe: ids, devices,
- *  digests, and budgets only — no prompt text, no secrets). */
+/** Print the participant plan to stderr before any sandbox/provider call (public-safe: ids, devices,
+ *  digests, and budgets only; no prompt text, no secrets). */
 export function emitPreflightPlan(participantPlan, labId) {
     const lines = [];
-    lines.push(`humanish cua fan-out plan (${labId}): ${participantPlan.laneCount} participant(s), strategy ${participantPlan.strategy}, concurrency ${participantPlan.concurrency}${participantPlan.envLoweredConcurrencyFrom === undefined ? "" : ` (lowered from ${participantPlan.envLoweredConcurrencyFrom} by ${CUA_MAX_CONCURRENCY_ENV})`}, ${participantPlan.waves} wave(s).`);
+    lines.push(`humanish computer-use fan-out plan (${labId}): ${participantPlan.laneCount} participant(s), strategy ${participantPlan.strategy}, concurrency ${participantPlan.concurrency}${participantPlan.envLoweredConcurrencyFrom === undefined ? "" : ` (lowered from ${participantPlan.envLoweredConcurrencyFrom} by ${CUA_MAX_CONCURRENCY_ENV})`}, ${participantPlan.waves} wave(s).`);
     lines.push(`  session budget ${Math.round(participantPlan.perLaneSessionBudgetMs / 1000)}s per participant; worst-case ~${participantPlan.worstCaseSandboxMinutes} sandbox-minutes total${participantPlan.dryRun ? " (dry-run: $0)" : ""}.`);
     for (const entry of participantPlan.lanes) {
         lines.push(`  - ${formatParticipantPlanEntry(entry)}`);
@@ -212,8 +212,8 @@ export async function compileParticipantPersonas(projectRoot, personaIds) {
 export async function loadCuaParticipants(args) {
     const { plan } = args;
     const { participants } = plan.runner;
-    // Compile any committed personas BEFORE planning, so the plan builder stays pure and each lane's
-    // prompt carries real behavioral directives rather than a bare `Persona: <id>.` label (#381).
+    // Compile any committed personas before planning, so the plan builder stays pure and each participant's
+    // prompt carries real behavioral directives rather than a bare `Persona: <id>.` label.
     const personas = await compileParticipantPersonas(args.projectRoot, participants.map((participant) => participant.personaId));
     const { runs: participantRuns, participantPlan } = participantRunsAndPlan({
         participants,
@@ -235,7 +235,7 @@ export async function loadCuaParticipants(args) {
         participantPlan,
     });
     if (!selected.ok) {
-        return { ok: false, code: "HUMANISH_CUA_LAB_RERUN_INVALID", message: selected.message };
+        return { ok: false, code: "HUMANISH_COMPUTER_USE_RERUN_INVALID", message: selected.message };
     }
     return {
         ok: true,
@@ -244,7 +244,7 @@ export async function loadCuaParticipants(args) {
         rerunLineage: selected.rerun,
     };
 }
-/** Scrub known secret values from each lane's declarative snapshot before any bundle uses it. */
+/** Scrub known secret values from each participant's declarative snapshot before any bundle uses it. */
 export function sanitizeParticipantRuns(runs, scrub) {
     for (const spec of runs) {
         if (spec.evidenceAssignment)

package/dist/routes/computer-use/plan.d.ts

@@ -1,14 +1,13 @@
 import { type CuaActorDescriptor } from "../../actors/registry.js";
-import type { ComputerUsePlan, RoutePlanResult, RouteRefusal } from "../../lab/plan-types.js";
-import type { LabConfig, LabSubjectServe, LabSubjectState } from "../../lab/types.js";
-import type { RunLabProvenance } from "../../run/status.js";
-import { type CuaActorLabErrorCode, type CuaActorLabHooks, type RunCuaActorLabOptions } from "./types.js";
+import type { ComputerUsePlan, ComputerUseRunner, RoutePlanResult, RouteRefusal } from "../../lab/plan-types.js";
+import type { LabConfig, LabSubjectState } from "../../lab/types.js";
+import { type CuaActorLabErrorCode, type RunCuaActorLabOptions } from "./types.js";
 /** The error a computer-use lab returns before a run starts. */
 export interface ComputerUseRefusal extends RouteRefusal<"computer-use", CuaActorLabErrorCode> {
     /**
      * Where the route returns it. "before-scope": analysis and tasks, returned before the run scope
      * with no automatic-analysis record. "in-scope": after the cwd checks. "after-personas": after
-     * the route reads committed persona files, so a persona-file error still wins over the lane cap
+     * the route reads committed persona files, so a persona-file error still wins over the participant cap
      * and in-process fan-out.
      */
     readonly stage: "before-scope" | "in-scope" | "after-personas";
@@ -18,39 +17,32 @@ export interface ComputerUseRefusal extends RouteRefusal<"computer-use", CuaActo
 export type ComputerUsePlanResult = RoutePlanResult<ComputerUsePlan, ComputerUseRefusal>;
 /** The registered descriptor for a planned actor id; planComputerUseLab checked the registry. */
 export declare function cuaDescriptorOf(actor: string): CuaActorDescriptor;
-/** Which subject route a computer-use lab takes, derived once from its config and hooks. */
-export interface CuaSubjectRoute {
-    cloneRoute: boolean;
-    /** A CLI studied at a desktop: nothing cloned, no browser, a terminal instead. */
-    desktopCliRoute: boolean;
-    localTreeRoute: boolean;
-    /**
-     * Clone and local-tree both provision the subject in-sandbox (clone via git, local-tree via
-     * pack+upload) and share the install/build/state/start/probe pipeline, so every seam that gates
-     * on "does this route provision a subject" is keyed on this union.
-     */
-    provisionedRoute: boolean;
-    localAppSubject: boolean;
-    /** A caller-supplied executor drives the subject in-process; no desktop is created. */
-    inProcessRoute: boolean;
-    serve: LabSubjectServe | undefined;
-    appUrl: string;
-    subjectRepo: string | undefined;
-    subjectEnvNames: string[];
+/** Which of the caller's driving homes, createProvider and inProcess, a run has. */
+export interface CallerDriving {
+    readonly inProcess: boolean;
+    readonly createProvider: boolean;
 }
-export declare function cuaSubjectRoute(config: LabConfig, hooks: CuaActorLabHooks): CuaSubjectRoute;
+/** The driving a computer-use run's options carry. */
+export declare function callerDrivingOf(options: {
+    readonly inProcess?: unknown;
+    readonly createProvider?: unknown;
+}): CallerDriving;
 /** The state a planned run's provisioned subject declares. Other subjects declare none. */
 export declare function cuaDeclaredState(plan: ComputerUsePlan): LabSubjectState | undefined;
-/** The route facts a planned run takes: its runner's desktop and subject. */
-export declare function cuaSubjectRouteOf(plan: ComputerUsePlan): CuaSubjectRoute;
+/** The URL a refused lab's result names, from its declaration: a provisioned subject's serve URL. */
+export declare function declaredAppUrl(config: LabConfig): string;
+/** The URL a planned run's participants open: a provisioned subject's served URL, else its own. */
+export declare function plannedAppUrl(subject: ComputerUseRunner["subject"]): string;
 /**
  * Plan a computer-use lab. It is called for any config handed to the computer-use runner, not only
  * one routeOf sends here, so a config for another route gets this route's refusal.
  */
 export declare function planComputerUseLab(config: LabConfig, input: {
     readonly dryRun: boolean;
-    readonly lab?: RunLabProvenance;
-    readonly hooks?: CuaActorLabHooks;
+    /** Whether deps.runSession is set: a caller's session runner cannot enforce maxOutputTokens. */
+    readonly hasRunSession?: boolean;
+    /** Which of the caller's driving homes are set; neither when absent. */
+    readonly driving?: CallerDriving;
     readonly countOverride?: number;
     readonly rerun?: RunCuaActorLabOptions["rerun"];
 }): ComputerUsePlanResult;

package/dist/routes/computer-use/plan.js

@@ -8,14 +8,13 @@ import { isHttpUrl, isLoopbackUrl } from "../../lab/parse/subject.js";
 import { subjectStateInvalidReason } from "../../lab/parse/subject-state.js";
 import { brainOf, callerBrainOf, capsOf, desktopRequirements, planBase, provisionedSubject, } from "../../lab/plan-base.js";
 import { computerUseParticipants, declaredTargets } from "../../lab/plan-participants.js";
-import { MAX_CUA_LANES } from "../../lab/routing.js";
-import { cloneTargetValidationReason, cuaLaneValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../lab/validation.js";
+import { MAX_COMPUTER_USE_PARTICIPANTS } from "../../lab/routing.js";
+import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../lab/validation.js";
 import { desktopCliProductReason } from "../../lab/composition-rules.js";
 import { isLocalBrowserLab } from "../../substrates/local/runtime-config.js";
 import { boundedConcurrency, defaultSessionTimeoutMs, resolveParticipantSandboxMs, } from "./participant-runs.js";
 import { MAX_SANDBOX_MS } from "../../substrates/e2b/lifetime.js";
 import {} from "./types.js";
-import { participantDesktopOf } from "./participant-desktop.js";
 /** The registered descriptor for a planned actor id; planComputerUseLab checked the registry. */
 export function cuaDescriptorOf(actor) {
     const descriptor = actorRegistry[actor];
@@ -23,7 +22,7 @@ export function cuaDescriptorOf(actor) {
         throw new Error(`planned actor "${actor}" is not a registered computer-use actor`);
     return descriptor;
 }
-export function cuaSubjectRoute(config, hooks) {
+function declaredSubjectRoute(config, driving) {
     const cloneRoute = config.subject.source === "clone";
     const localTreeRoute = config.subject.source === "local-tree";
     const provisionedRoute = cloneRoute || localTreeRoute;
@@ -34,37 +33,39 @@ export function cuaSubjectRoute(config, hooks) {
         localTreeRoute,
         provisionedRoute,
         localAppSubject: config.subject.source === "local-app",
-        inProcessRoute: hooks.buildExecutor !== undefined,
+        inProcessRoute: driving.inProcess,
         serve,
         appUrl: (provisionedRoute ? serve?.url : config.subject.appUrl) ?? "",
         subjectRepo: cloneRoute ? (config.subject.repos?.[0] ?? "") : undefined,
         subjectEnvNames: provisionedRoute ? (config.subject.env ?? []) : [],
     };
 }
+/** The driving a computer-use run's options carry. */
+export function callerDrivingOf(options) {
+    return {
+        inProcess: options.inProcess !== undefined,
+        createProvider: options.createProvider !== undefined,
+    };
+}
 /** The state a planned run's provisioned subject declares. Other subjects declare none. */
 export function cuaDeclaredState(plan) {
     const { subject } = plan.runner;
     return subject.kind === "clone" || subject.kind === "local-tree" ? subject.state : undefined;
 }
-/** The route facts a planned run takes: its runner's desktop and subject. */
-export function cuaSubjectRouteOf(plan) {
-    const { desktop, subject } = plan.runner;
-    const provisioned = subject.kind === "clone" || subject.kind === "local-tree" ? subject : undefined;
-    return {
-        cloneRoute: subject.kind === "clone",
-        desktopCliRoute: subject.kind === "desktop-cli",
-        localTreeRoute: subject.kind === "local-tree",
-        provisionedRoute: provisioned !== undefined,
-        localAppSubject: subject.kind === "local-app",
-        inProcessRoute: desktop === "in-process",
-        serve: provisioned?.serve,
-        appUrl: provisioned?.serve.url ?? ("appUrl" in subject ? subject.appUrl : ""),
-        subjectRepo: subject.kind === "clone" ? subject.repo : undefined,
-        subjectEnvNames: [...(provisioned?.env ?? [])],
-    };
+/** The URL a refused lab's result names, from its declaration: a provisioned subject's serve URL. */
+export function declaredAppUrl(config) {
+    const { subject } = config;
+    const provisioned = subject.source === "clone" || subject.source === "local-tree";
+    return (provisioned ? subject.serve?.url : subject.appUrl) ?? "";
+}
+/** The URL a planned run's participants open: a provisioned subject's served URL, else its own. */
+export function plannedAppUrl(subject) {
+    if (subject.kind === "clone" || subject.kind === "local-tree")
+        return subject.serve.url;
+    return "appUrl" in subject ? subject.appUrl : "";
 }
 const invalid = (message) => ({
-    code: "HUMANISH_CUA_LAB_SUBJECT_INVALID",
+    code: "HUMANISH_COMPUTER_USE_SUBJECT_INVALID",
     message,
 });
 /**
@@ -72,22 +73,22 @@ const invalid = (message) => ({
  * is touched. The parser enforces most of these too; the engine repeats them for library callers
  * that hand it a config directly. The groups run in this order, and each returns its first reason.
  */
-function cuaLabRejection(config, hooks, subjectRoute) {
-    return (unsupportedDeclarationReason(config, hooks, subjectRoute) ??
+function cuaLabRejection(config, hasRunSession, driving, subjectRoute) {
+    return (unsupportedDeclarationReason(config, hasRunSession, driving, subjectRoute) ??
         subjectStructureReason(config, subjectRoute) ??
         entryTargetReason(config, subjectRoute) ??
-        driverReason(config, hooks, subjectRoute) ??
+        driverReason(driving, subjectRoute) ??
         rosterShapeReason(config));
 }
 /** A declaration this route cannot honor, for any subject or with the caller's own driver. */
-function unsupportedDeclarationReason(config, hooks, { inProcessRoute }) {
+function unsupportedDeclarationReason(config, hasRunSession, driving, { inProcessRoute }) {
     const reason = desktopMediaValidationReason(config) ||
         outputTokenLimitValidationReason(config) ||
         scenarioCapsValidationReason(config);
     if (reason)
         return invalid(reason);
     if (config.actors[0]?.maxOutputTokens !== undefined &&
-        (hooks.runSession || hooks.buildProvider || hooks.buildExecutor))
+        (hasRunSession || driving.createProvider || driving.inProcess))
         return invalid("maxOutputTokens cannot be enforced by a custom runSession/provider/executor route.");
     const receivingReason = receivingEmailValidationReason(config);
     if (receivingReason)
@@ -109,7 +110,7 @@ function subjectStructureReason(config, subjectRoute) {
     if (cloneRoute &&
         (!serve || !subjectRepo || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(subjectRepo)))
         return invalid(!serve
-            ? "clone subjects on the computer-use route require `subject.serve` (start + url) — the lab serves the app in-sandbox."
+            ? "A clone subject on the computer-use route needs `subject.serve` (start and url): humanish starts the app in the sandbox before the participant opens it."
             : `subject.repos[0] must be an owner/repo slug (got "${subjectRepo ?? ""}").`);
     // A library caller that skips parseLabConfig gets the same fail-closed shape the parser
     // enforces, naming which requirement is missing.
@@ -145,45 +146,36 @@ function entryTargetReason(config, subjectRoute) {
     if (entryTargetSafe)
         return undefined;
     return {
-        code: "HUMANISH_CUA_LAB_SUBJECT_UNSAFE",
+        code: "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE",
         message: provisionedRoute || localAppSubject || !allowPublicTargets
             ? "subject.appUrl and any actors[0].lanes[].target entries must be loopback (127.0.0.1 or localhost) unless policies.allowPublicTargets is set for an app-url subject."
             : "subject.appUrl and actors[0].lanes[].target entries must be valid http(s) URLs.",
     };
 }
-/** Something to drive the subject: the caller's executor with its provider, or a local desktop. */
-function driverReason(config, hooks, { localAppSubject, inProcessRoute }) {
+/** Something to drive the subject: the caller's executor with its provider. */
+function driverReason(driving, { localAppSubject, inProcessRoute }) {
     // A custom executor needs a custom provider too: the default OpenAI provider is vision-based
     // and would fail closed against an executor that returns no screenshot.
-    if (hooks.buildExecutor !== undefined && hooks.buildProvider === undefined)
+    if (driving.inProcess && !driving.createProvider)
         return {
-            code: "HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER",
-            message: "cuaHooks.buildExecutor requires cuaHooks.buildProvider — a state-driven executor returns no screenshot, so it must be paired with a NON-vision provider (the default OpenAI computer-use provider is vision-based and would fail closed).",
+            code: "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER",
+            message: "RunLabOptions.inProcess needs RunLabOptions.createProvider: an in-process executor returns no screenshot, so it needs a provider that does not read images. The default OpenAI computer-use provider reads screenshots and would stop the session.",
         };
     // There is no built-in in-process driver for a local app.
     if (localAppSubject && !inProcessRoute)
         return {
-            code: "HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR",
+            code: "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR",
             message: "subject.source: local-app has no built-in driver. Supply one through runLab(config, { inProcess: { executor }, createProvider }); a state-driven executor needs a non-vision provider.",
         };
-    // runLab gives a local browser study its desktop lane; a direct route call or an in-process
-    // executor on the same lab has none.
-    if (config.subject.source === "app-url" &&
-        config.execution?.target === "local" &&
-        participantDesktopOf(hooks) === undefined)
-        return {
-            code: "HUMANISH_CUA_LAB_LOCAL_DESKTOP_MISSING",
-            message: "An app-url lab with execution.target: local needs a local desktop. runLab starts one; a direct route call or an in-process executor does not.",
-        };
     return undefined;
 }
-/** The lane roster, then the sandbox deadline its session budget derives. */
+/** The participant roster, then the sandbox deadline its session budget derives. */
 function rosterShapeReason(config) {
-    // Lanes XOR count/laneFocus, device XOR raw resolution, cap, unique ids,
-    // allowPublicTargets with more than one lane, clone.fanout.
-    const fanoutReason = cuaLaneValidationReason(config);
+    // `lanes` XOR `count`/`laneFocus`, device XOR raw resolution, cap, unique ids,
+    // allowPublicTargets with more than one participant, clone.fanout.
+    const fanoutReason = computerUseValidationReason(config);
     if (fanoutReason)
-        return { code: "HUMANISH_CUA_LAB_FANOUT_INVALID", message: fanoutReason };
+        return { code: "HUMANISH_COMPUTER_USE_FANOUT_INVALID", message: fanoutReason };
     // The sandbox deadline is derived from the session budget, so a lab can ask for a session that
     // cannot legally be provisioned. Show the arithmetic: the provider's own error names a limit
     // but not which knob produced it.
@@ -195,12 +187,17 @@ function rosterShapeReason(config) {
     const headroomMs = derivedSandboxMs - sessionMs;
     return invalid(`execution.timeoutMs ${Math.round(sessionMs / 60_000)}m derives a ${Math.round(derivedSandboxMs / 60_000)}m sandbox deadline, and a sandbox may not live longer than ${MAX_SANDBOX_MS / 60_000}m. The deadline is the session budget plus ${Math.round(headroomMs / 60_000)}m of provisioning and teardown headroom${provisionedRoute ? " (this route clones, installs, builds and serves the subject before the actor starts)" : ""}. Lower execution.timeoutMs to at most ${Math.round((MAX_SANDBOX_MS - headroomMs) / 60_000)}m, or set execution.desktop.sandboxTimeoutMs explicitly.`);
 }
+/** The plan's rerun: the source run and, when given, the participants to rerun. */
+function rerunPlan({ sourceRunId, participantIds, }) {
+    return { sourceRunId, ...(participantIds === undefined ? {} : { participantIds }) };
+}
 /**
  * Plan a computer-use lab. It is called for any config handed to the computer-use runner, not only
  * one routeOf sends here, so a config for another route gets this route's refusal.
  */
 export function planComputerUseLab(config, input) {
-    const hooks = input.hooks ?? {};
+    const hasRunSession = input.hasRunSession === true;
+    const driving = input.driving ?? { inProcess: false, createProvider: false };
     const refuse = (stage, code, message, actor) => ({
         ok: false,
         refusal: {
@@ -213,54 +210,57 @@ export function planComputerUseLab(config, input) {
     });
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
     if (!analysis.ok)
-        return refuse("before-scope", "HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
+        return refuse("before-scope", "HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
     const tasksReason = taskProtocolValidationReason(config, true);
     if (tasksReason)
-        return refuse("before-scope", "HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason);
+        return refuse("before-scope", "HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
     // The parser checks the actor too; a library caller skips the parser.
     const actorType = config.actors[0]?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isCuaActorDescriptor(descriptor))
-        return refuse("in-scope", "HUMANISH_CUA_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered computer-use actor.`);
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered computer-use actor.`);
     const actor = descriptor.id;
-    const rejection = cuaLabRejection(config, hooks, cuaSubjectRoute(config, hooks));
+    const rejection = cuaLabRejection(config, hasRunSession, driving, declaredSubjectRoute(config, driving));
     if (rejection)
         return refuse("in-scope", rejection.code, rejection.message, actor);
-    // A shared world runs every seat against one app; this route would run them as separate lanes.
-    // It comes after the rules above, so a shared-world config that breaks one of them, which runLab
-    // sends here, still gets that rule's message.
+    // A shared world runs every participant against one app; this route would run them as separate
+    // participants. It comes after the rules above, so a shared-world config that breaks one of them,
+    // which runLab sends here, still gets that rule's message.
     if (config.subject.topology === "shared-world")
-        return refuse("in-scope", "HUMANISH_CUA_LAB_SUBJECT_INVALID", "subject.topology: shared-world labs run every participant against one shared app on the shared-world route; runCuaActorLab runs independent participants. Run the lab with runLab or runConcurrentSharedWorld.", actor);
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", "subject.topology: shared-world labs run every participant against one shared app on the shared-world route; runCuaActorLab runs independent participants. Run the lab with runLab or runConcurrentSharedWorld.", actor);
     // The in-process route drives subject.appUrl on this machine and creates no desktop, so it would
     // skip the subject a clone, local-tree or desktop-cli lab declares.
     const source = config.subject.source;
-    if (hooks.buildExecutor !== undefined &&
+    if (driving.inProcess &&
         (source === "clone" || source === "local-tree" || source === "desktop-cli"))
-        return refuse("in-scope", "HUMANISH_CUA_LAB_SUBJECT_INVALID", `cuaHooks.buildExecutor drives subject.appUrl in this process, and a ${source} subject needs the hosted desktop the in-process route never creates. Use an app-url or local-app subject with buildExecutor, or remove buildExecutor to run on a hosted desktop.`, actor);
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", `RunLabOptions.inProcess drives subject.appUrl in this process, and a ${source} subject needs the hosted desktop the in-process route never creates. Use an app-url or local-app subject with inProcess, or remove inProcess to run on a hosted desktop.`, actor);
     // The parser's rule; without a product the desktop study fails later.
     const productReason = desktopCliProductReason(config);
     if (productReason)
-        return refuse("in-scope", "HUMANISH_CUA_LAB_SUBJECT_INVALID", productReason, actor);
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", productReason, actor);
     const participants = computerUseParticipants(config, input.countOverride);
-    if (participants.length > MAX_CUA_LANES)
-        return refuse("after-personas", "HUMANISH_CUA_LAB_FANOUT_INVALID", `Computer-use fan-out is capped at ${MAX_CUA_LANES} participants (resolved ${participants.length}); N concurrent paid desktops is real spend.`, actor);
+    if (participants.length > MAX_COMPUTER_USE_PARTICIPANTS)
+        return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", `Computer-use fan-out is capped at ${MAX_COMPUTER_USE_PARTICIPANTS} participants (resolved ${participants.length}); N concurrent paid desktops is real spend.`, actor);
     const [first, ...rest] = participants;
-    if (hooks.buildExecutor !== undefined && rest.length > 0)
-        return refuse("after-personas", "HUMANISH_CUA_LAB_FANOUT_INVALID", "Fan-out to more than one participant is not supported on the in-process route (RunLabOptions.inProcess, or the deprecated cuaHooks.buildExecutor): fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Run a single in-process participant, or fan out on the E2B route.", actor);
+    if (driving.inProcess && rest.length > 0)
+        return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", "Fan-out to more than one participant is not supported on the in-process route (RunLabOptions.inProcess): fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Run a single in-process participant, or fan out on the E2B route.", actor);
     if (first === undefined)
         throw new Error("computerUseParticipants returned no participant");
     const appUrl = config.subject.appUrl ?? "";
+    const declaredServeUrl = config.subject.serve?.url;
+    const serveUrl = declaredServeUrl === undefined ? {} : { serveUrl: declaredServeUrl };
     const appUrlSubject = {
         kind: "app-url",
         appUrl,
         publicTargets: config.policies?.allowPublicTargets === true,
+        ...serveUrl,
     };
     const product = config.subject.product;
     const hosted = source === "desktop-cli" && product !== undefined
-        ? { kind: "desktop-cli", product }
+        ? { kind: "desktop-cli", product, ...serveUrl }
         : (provisionedSubject(config) ?? appUrlSubject);
-    const brain = brainOf(config, hooks.buildProvider !== undefined);
-    const runner = hooks.buildExecutor !== undefined
+    const brain = brainOf(config, driving.createProvider);
+    const runner = driving.inProcess
         ? {
             desktop: "in-process",
             brain: callerBrainOf(config),
@@ -275,7 +275,6 @@ export function planComputerUseLab(config, input) {
     const provisioned = source === "clone" || source === "local-tree";
     const base = planBase(config, {
         dryRun: input.dryRun,
-        ...(input.lab === undefined ? {} : { lab: input.lab }),
         analysis,
     });
     return {
@@ -289,18 +288,11 @@ export function planComputerUseLab(config, input) {
             sessionBudgetMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config),
             sandboxMs: resolveParticipantSandboxMs(config),
             caps: capsOf(config),
-            ...(input.rerun === undefined
-                ? {}
-                : {
-                    rerun: {
-                        sourceRunId: input.rerun.sourceRunId,
-                        ...(input.rerun.laneIds === undefined ? {} : { participantIds: input.rerun.laneIds }),
-                    },
-                }),
+            ...(input.rerun === undefined ? {} : { rerun: rerunPlan(input.rerun) }),
             requirements: base.dryRun || runner.desktop === "in-process"
                 ? []
                 : desktopRequirements(config, {
-                    e2b: runner.desktop === "e2b-desktop" && hooks.createDesktopLane === undefined,
+                    e2b: runner.desktop === "e2b-desktop",
                     brain,
                     localVm: runner.desktop === "local-vm",
                     externalCatch: !provisioned,

package/dist/routes/computer-use/preflight.d.ts

@@ -1,6 +1,6 @@
 import type { Brain, ComputerUsePlan } from "../../lab/plan-types.js";
 import type { LabCommsExternal } from "../../lab/types.js";
-import type { CuaActorLabErrorCode, CuaActorLabHooks } from "./types.js";
+import type { CuaActorLabErrorCode } from "./types.js";
 /**
  * The first reason a live computer-use run cannot start on this machine: missing keys, a missing
  * or signed-out local agent, missing subject env, a spend cap with no price, or an unreachable
@@ -11,11 +11,9 @@ export declare function liveCuaRejection(args: {
     caps: ComputerUsePlan["caps"];
     /** The plan's brain: whether a local agent drives the participant, and the model a cap prices. */
     brain: Brain;
-    hooks: CuaActorLabHooks;
     env: Record<string, string | undefined>;
-    openaiApiKey: string;
-    e2bApiKey: string;
-    subjectEnvNames: string[];
+    /** The plan's requirements: which keys and subject env names this run needs. */
+    requirements: ComputerUsePlan["requirements"];
     externalCommsConfig: LabCommsExternal | undefined;
 }): Promise<{
     code: CuaActorLabErrorCode;