humanish 0.105.0 → 0.106.0

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

@@ -0,0 +1,255 @@
+// The participant runs a computer-use lab drives, built before anything is created: the sandbox
+// and session budgets, the concurrency bound, each participant's prompt, bundle ids and artifact
+// paths, and the public plan printed before any sandbox or provider call. loadCuaParticipants
+// compiles the committed personas first and narrows a rerun to its selected participants.
+import { isLocalBrowserLab, LOCAL_BROWSER_LIFETIME_MS, } from "../../substrates/local/runtime-config.js";
+import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
+import { computerUseParticipants, } from "../../lab/plan-participants.js";
+import { resolveParticipant } from "../../run/participant.js";
+import {} from "../../lab/types.js";
+import { scrubPersonaBrief } from "../../lab/persona.js";
+import { redactText } from "../../evidence/redaction.js";
+import {} from "../../run/bundle.js";
+import { participantAssignment } from "../../lab/participant-assignment.js";
+import { resolveCommittedPersonas } from "../../lab/persona-resolve.js";
+import { CUA_FANOUT_STRATEGY, CUA_MAX_CONCURRENCY_ENV, DEFAULT_APP_URL_SESSION_TIMEOUT_MS, MIN_DERIVED_SESSION_TIMEOUT_MS, } from "./types.js";
+import { MAX_SANDBOX_MS, SANDBOX_TIMEOUT_BUFFER_MS, SUBJECT_PROVISION_BUDGET_MS, } from "../../substrates/e2b/lifetime.js";
+import { readPositiveInt } from "../../lab/parse/values.js";
+import { digestUrl } from "./bundle-parts.js";
+import { composeParticipantInstructions, DEFAULT_MISSION } from "./participant-prompt.js";
+import { resolveCuaRerunSelection } from "./rerun-selection.js";
+export function defaultSessionTimeoutMs(config) {
+    const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
+    if (!provisionedRoute)
+        return DEFAULT_APP_URL_SESSION_TIMEOUT_MS;
+    const stateBudgetMs = (config.subject.state?.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0);
+    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
+ *  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 function resolveParticipantSandboxMs(config) {
+    if (isLocalBrowserLab(config))
+        return LOCAL_BROWSER_LIFETIME_MS;
+    const timeoutMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config);
+    const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
+    const stateBudgetMs = provisionedRoute
+        ? (config.subject.state?.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0)
+        : 0;
+    return (config.execution?.desktop?.sandboxTimeoutMs ??
+        timeoutMs +
+            (provisionedRoute ? SUBJECT_PROVISION_BUDGET_MS + stateBudgetMs : 0) +
+            SANDBOX_TIMEOUT_BUFFER_MS);
+}
+/**
+ * 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].
+ * 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
+ * plan never silently disagrees with the manifest.
+ */
+function envLoweredConcurrency(planned, participantCount, env) {
+    const envLower = readPositiveInt(env[CUA_MAX_CONCURRENCY_ENV], 0);
+    if (envLower > 0 && envLower < planned) {
+        return {
+            bound: Math.max(1, Math.min(planned, envLower, participantCount)),
+            envLoweredFrom: planned,
+        };
+    }
+    return { bound: planned };
+}
+/** The same inputs from a config, for callers that have no plan. */
+function plannedParticipantsOf(config, countOverride) {
+    const participants = computerUseParticipants(config, countOverride);
+    return {
+        participants,
+        concurrency: boundedConcurrency(config.execution?.concurrency, participants.length),
+        sessionBudgetMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config),
+        sandboxMs: resolveParticipantSandboxMs(config),
+        desktopCli: config.subject.source === "desktop-cli",
+    };
+}
+/** 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
+    // what the route derives from it: the prompt, bundle ids and artifact paths.
+    const { participants } = planned;
+    const participantCount = participants.length;
+    const runs = participants.map((participant) => {
+        const mission = participant.assignment.mission ?? DEFAULT_MISSION;
+        const focus = participant.assignment.focus;
+        const tasks = participant.tasks;
+        const { device, personaId } = participant;
+        const resolvedPersona = personaId === undefined ? undefined : opts.personas?.get(personaId);
+        const composed = composeParticipantInstructions({
+            mission,
+            ...(tasks === undefined ? {} : { tasks }),
+            ...(personaId === undefined ? {} : { persona: personaId }),
+            ...(resolvedPersona === undefined ? {} : { resolvedPersona }),
+            ...(focus === undefined ? {} : { instruction: focus }),
+            device: { name: device.name, preset: device.preset },
+            ...(planned.desktopCli ? { surface: "desktop-cli" } : {}),
+        });
+        const run = resolveParticipant(participant, {
+            persona: composed.persona,
+            instructions: composed.instructions,
+            evidenceAssignment: {
+                mission,
+                ...(focus === undefined ? {} : { focus }),
+                ...(tasks === undefined ? {} : { tasks: tasks.map(({ id, goal }) => ({ id, goal })) }),
+            },
+        });
+        return {
+            ...run,
+            screenshotDir: participantCount === 1 ? "" : participant.id,
+            traceArtifactPath: participantCount === 1 ? "actor.json" : `actors/${run.streamId}.json`,
+        };
+    });
+    const resolved = envLoweredConcurrency(planned.concurrency, participantCount, env);
+    const concurrency = resolved.bound;
+    const { sessionBudgetMs, sandboxMs } = planned;
+    const participantPlan = {
+        strategy: CUA_FANOUT_STRATEGY,
+        laneCount: participantCount,
+        concurrency,
+        ...(resolved.envLoweredFrom === undefined
+            ? {}
+            : { envLoweredConcurrencyFrom: resolved.envLoweredFrom }),
+        waves: Math.ceil(participantCount / concurrency),
+        perLaneSessionBudgetMs: sessionBudgetMs,
+        worstCaseSandboxMinutes: Math.round((participantCount * sandboxMs) / 60_000),
+        dryRun: opts.dryRun === true,
+        lanes: runs.map((spec) => ({
+            id: spec.planned.id,
+            ...(spec.planned.labels.actorType === undefined
+                ? {}
+                : { actorType: spec.planned.labels.actorType }),
+            ...(spec.planned.labels.surface === undefined
+                ? {}
+                : { surface: spec.planned.labels.surface }),
+            ...(spec.planned.labels.caseGroup === undefined
+                ? {}
+                : { caseGroup: spec.planned.labels.caseGroup }),
+            index: spec.planned.index + 1,
+            persona: spec.persona.id,
+            device: spec.planned.device.name,
+            resolution: spec.planned.device.resolution,
+            instructionDigest: spec.persona.promptDigest,
+            ...(spec.planned.limits.reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort: spec.planned.limits.reasoningEffort }),
+            ...(spec.planned.limits.maxOutputTokens === undefined
+                ? {}
+                : { maxOutputTokens: spec.planned.limits.maxOutputTokens }),
+            ...(spec.planned.targetUrl === undefined
+                ? {}
+                : { targetDigest: digestUrl(spec.planned.targetUrl) }),
+        })),
+    };
+    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,
+ * 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). */
+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(`  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)}`);
+    }
+    process.stderr.write(`${lines.join("\n")}\n`);
+}
+export function formatParticipantPlanEntry(entry) {
+    const taxonomy = [
+        entry.actorType ? `type=${entry.actorType}` : undefined,
+        entry.surface ? `surface=${entry.surface}` : undefined,
+        entry.caseGroup ? `case=${entry.caseGroup}` : undefined,
+        entry.reasoningEffort ? `effort=${entry.reasoningEffort}` : undefined,
+    ].filter((part) => part !== undefined);
+    return `${entry.id}: persona=${entry.persona}${taxonomy.length > 0 ? ` ${taxonomy.join(" ")}` : ""} device=${entry.device} ${entry.resolution[0]}x${entry.resolution[1]} prompt#${entry.instructionDigest}${entry.targetDigest ? ` target#${entry.targetDigest}` : ""}`;
+}
+/**
+ * Compile the committed persona files the participants use, printing a warning for each one that
+ * is missing. A refusal that comes after this step reads them first, so a persona-file error still
+ * wins over it.
+ */
+export async function compileParticipantPersonas(projectRoot, personaIds) {
+    const resolution = await resolveCommittedPersonas(projectRoot, personaIds);
+    for (const warning of resolution.warnings) {
+        process.stderr.write(`humanish: ${warning}\n`);
+    }
+    return resolution.personas;
+}
+/**
+ * The participants a computer-use run drives, loaded before anything is created: committed persona
+ * files read and compiled, the pure participant table built from the plan's participants, bound
+ * and budgets (the same for dry-run and live), and a rerun narrowed to its selected participants
+ * by reading the source run.
+ */
+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).
+    const personas = await compileParticipantPersonas(args.projectRoot, participants.map((participant) => participant.personaId));
+    const { runs: participantRuns, participantPlan } = participantRunsAndPlan({
+        participants,
+        concurrency: plan.concurrency,
+        sessionBudgetMs: plan.sessionBudgetMs,
+        sandboxMs: plan.sandboxMs,
+        desktopCli: plan.runner.subject.kind === "desktop-cli",
+    }, { env: args.env, dryRun: plan.dryRun, personas });
+    const rerun = plan.rerun;
+    if (!rerun)
+        return { ok: true, participantRuns, participantPlan };
+    const selected = await resolveCuaRerunSelection({
+        cwd: args.cwd,
+        labId: plan.labId,
+        sandboxMs: plan.sandboxMs,
+        sourceRunId: rerun.sourceRunId,
+        ...(rerun.participantIds === undefined ? {} : { participantIds: [...rerun.participantIds] }),
+        participantRuns,
+        participantPlan,
+    });
+    if (!selected.ok) {
+        return { ok: false, code: "HUMANISH_CUA_LAB_RERUN_INVALID", message: selected.message };
+    }
+    return {
+        ok: true,
+        participantRuns: selected.participantRuns,
+        participantPlan: selected.participantPlan,
+        rerunLineage: selected.rerun,
+    };
+}
+/** Scrub known secret values from each lane's declarative snapshot before any bundle uses it. */
+export function sanitizeParticipantRuns(runs, scrub) {
+    for (const spec of runs) {
+        if (spec.evidenceAssignment)
+            spec.evidenceAssignment = participantAssignment(spec.evidenceAssignment, scrub);
+        spec.evidenceInstructions = redactText(scrub(spec.instructions));
+        spec.persona = scrubPersonaBrief(spec.persona, scrub);
+    }
+}

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

@@ -0,0 +1,56 @@
+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";
+/** 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
+     * and in-process fan-out.
+     */
+    readonly stage: "before-scope" | "in-scope" | "after-personas";
+    /** The registered actor id, once the registry check has passed. */
+    readonly actor?: string;
+}
+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[];
+}
+export declare function cuaSubjectRoute(config: LabConfig, hooks: CuaActorLabHooks): CuaSubjectRoute;
+/** 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;
+/**
+ * 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;
+    readonly countOverride?: number;
+    readonly rerun?: RunCuaActorLabOptions["rerun"];
+}): ComputerUsePlanResult;

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

@@ -0,0 +1,308 @@
+// The computer-use route's plan: every configuration refusal the route makes before a run starts,
+// in its order and with its codes, then the plan the run uses. What stays in the route reads
+// external state: committed personas, a rerun's source run, keys, the local agent, subject env
+// values, spend-cap prices and the comms catch.
+import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
+import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
+import { isHttpUrl, isLoopbackUrl } from "../../lab/parse/subject.js";
+import { subjectStateInvalidReason } from "../../lab/parse/subject-state.js";
+import { brainOf, 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 { 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];
+    if (!descriptor || !isCuaActorDescriptor(descriptor))
+        throw new Error(`planned actor "${actor}" is not a registered computer-use actor`);
+    return descriptor;
+}
+export function cuaSubjectRoute(config, hooks) {
+    const cloneRoute = config.subject.source === "clone";
+    const localTreeRoute = config.subject.source === "local-tree";
+    const provisionedRoute = cloneRoute || localTreeRoute;
+    const serve = config.subject.serve;
+    return {
+        cloneRoute,
+        desktopCliRoute: config.subject.source === "desktop-cli",
+        localTreeRoute,
+        provisionedRoute,
+        localAppSubject: config.subject.source === "local-app",
+        inProcessRoute: hooks.buildExecutor !== undefined,
+        serve,
+        appUrl: (provisionedRoute ? serve?.url : config.subject.appUrl) ?? "",
+        subjectRepo: cloneRoute ? (config.subject.repos?.[0] ?? "") : undefined,
+        subjectEnvNames: provisionedRoute ? (config.subject.env ?? []) : [],
+    };
+}
+/** 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 ?? [])],
+    };
+}
+const invalid = (message) => ({
+    code: "HUMANISH_CUA_LAB_SUBJECT_INVALID",
+    message,
+});
+/**
+ * The first reason a computer-use lab cannot start, checked before any sandbox, key or provider
+ * 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) ??
+        subjectStructureReason(config, subjectRoute) ??
+        entryTargetReason(config, subjectRoute) ??
+        driverReason(config, hooks, subjectRoute) ??
+        rosterShapeReason(config));
+}
+/** A declaration this route cannot honor, for any subject or with the caller's own driver. */
+function unsupportedDeclarationReason(config, hooks, { 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))
+        return invalid("maxOutputTokens cannot be enforced by a custom runSession/provider/executor route.");
+    const receivingReason = receivingEmailValidationReason(config);
+    if (receivingReason)
+        return invalid(receivingReason);
+    if (inProcessRoute && config.comms?.email?.kind === "real")
+        return invalid("Real email receiving requires hosted participant desktops.");
+    if (inProcessRoute && config.execution?.desktop?.media !== undefined)
+        return invalid("execution.desktop.media is not provisioned by a caller-supplied executor. Remove the declaration or use a hosted computer-use browser participant.");
+    if (inProcessRoute && config.execution?.desktop?.recording !== undefined)
+        return invalid("execution.desktop.recording is not provisioned by a caller-supplied executor.");
+    return undefined;
+}
+/** The subject's own shape: the clone target and repo, the local tree, and declared state. */
+function subjectStructureReason(config, subjectRoute) {
+    const { cloneRoute, localTreeRoute, provisionedRoute, serve, subjectRepo } = subjectRoute;
+    const cloneTargetReason = cloneTargetValidationReason(config);
+    if (cloneTargetReason)
+        return invalid(cloneTargetReason);
+    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."
+            : `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.
+    if (localTreeRoute && (!serve || config.execution?.target !== "e2b-desktop"))
+        return invalid(!serve
+            ? "local-tree subjects on the computer-use route require `subject.serve` (start + url): the lab packs and serves the working tree in-sandbox."
+            : "local-tree subjects require `execution.target: e2b-desktop`: the packed working tree is provisioned and served inside a hosted desktop sandbox.");
+    if (config.subject.state) {
+        const stateReason = !provisionedRoute
+            ? "`subject.state` applies only to clone subjects or local-tree subjects (the lab seeds the state it serves)."
+            : subjectStateInvalidReason(config.subject.state, config.subject.env);
+        if (stateReason)
+            return invalid(stateReason);
+    }
+    return undefined;
+}
+/**
+ * Every URL a participant opens is loopback, unless an app-url subject allows public targets. A
+ * desktop-cli study has no entry target at all (the subject is a program on the machine, not an
+ * address), so the boundary is vacuous there rather than violated by an empty string.
+ */
+function entryTargetReason(config, subjectRoute) {
+    const { desktopCliRoute, provisionedRoute, localAppSubject, appUrl } = subjectRoute;
+    if (desktopCliRoute)
+        return undefined;
+    const allowPublicTargets = config.policies?.allowPublicTargets === true;
+    const entryTargets = [appUrl, ...declaredTargets(config)];
+    const entryTargetSafe = entryTargets.every((target) => provisionedRoute || localAppSubject
+        ? isLoopbackUrl(target)
+        : allowPublicTargets
+            ? isHttpUrl(target)
+            : isLoopbackUrl(target));
+    if (entryTargetSafe)
+        return undefined;
+    return {
+        code: "HUMANISH_CUA_LAB_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 }) {
+    // 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)
+        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).",
+        };
+    // There is no built-in in-process driver for a local app.
+    if (localAppSubject && !inProcessRoute)
+        return {
+            code: "HUMANISH_CUA_LAB_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. */
+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);
+    if (fanoutReason)
+        return { code: "HUMANISH_CUA_LAB_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.
+    const derivedSandboxMs = resolveParticipantSandboxMs(config);
+    if (derivedSandboxMs <= MAX_SANDBOX_MS)
+        return undefined;
+    const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
+    const sessionMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(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.`);
+}
+/**
+ * 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 refuse = (stage, code, message, actor) => ({
+        ok: false,
+        refusal: {
+            route: "computer-use",
+            code,
+            message,
+            stage,
+            ...(actor === undefined ? {} : { actor }),
+        },
+    });
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    if (!analysis.ok)
+        return refuse("before-scope", "HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
+    const tasksReason = taskProtocolValidationReason(config, true);
+    if (tasksReason)
+        return refuse("before-scope", "HUMANISH_LAB_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.`);
+    const actor = descriptor.id;
+    const rejection = cuaLabRejection(config, hooks, cuaSubjectRoute(config, hooks));
+    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.
+    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);
+    // 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 &&
+        (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);
+    // The parser refuses this too; without a product the desktop study fails later.
+    if (source === "desktop-cli" && config.subject.product?.name === undefined)
+        return refuse("in-scope", "HUMANISH_CUA_LAB_SUBJECT_INVALID", "desktop-cli subjects need `subject.product.name` — the CLI the participant is being asked to use.", 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);
+    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 (first === undefined)
+        throw new Error("computerUseParticipants returned no participant");
+    const appUrl = config.subject.appUrl ?? "";
+    const appUrlSubject = {
+        kind: "app-url",
+        appUrl,
+        publicTargets: config.policies?.allowPublicTargets === true,
+    };
+    const product = config.subject.product;
+    const hosted = source === "desktop-cli" && product !== undefined
+        ? { kind: "desktop-cli", product }
+        : (provisionedSubject(config) ?? appUrlSubject);
+    const brain = brainOf(config, hooks.buildProvider !== undefined);
+    const runner = hooks.buildExecutor !== undefined
+        ? {
+            desktop: "in-process",
+            brain: { kind: "caller" },
+            participants: [first],
+            subject: source === "local-app" ? { kind: "local-app", appUrl } : appUrlSubject,
+        }
+        : isLocalBrowserLab(config)
+            ? { desktop: "local-vm", brain, participants: [first, ...rest], subject: appUrlSubject }
+            : { desktop: "e2b-desktop", brain, participants: [first, ...rest], subject: hosted };
+    const declared = config.execution?.concurrency;
+    const n = participants.length;
+    const provisioned = source === "clone" || source === "local-tree";
+    const base = planBase(config, {
+        dryRun: input.dryRun,
+        ...(input.lab === undefined ? {} : { lab: input.lab }),
+        analysis,
+    });
+    return {
+        ok: true,
+        plan: {
+            ...base,
+            route: "computer-use",
+            actor,
+            runner,
+            concurrency: boundedConcurrency(declared, n),
+            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 }),
+                    },
+                }),
+            requirements: base.dryRun || runner.desktop === "in-process"
+                ? []
+                : desktopRequirements(config, {
+                    e2b: runner.desktop === "e2b-desktop" && hooks.createDesktopLane === undefined,
+                    brain,
+                    localVm: runner.desktop === "local-vm",
+                    externalCatch: !provisioned,
+                }),
+        },
+    };
+}

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

@@ -0,0 +1,26 @@
+import type { ComputerUsePlan } from "../../lab/plan-types.js";
+import type { LabCommsExternal } from "../../lab/types.js";
+import { type LocalAgentId } from "../../actors/local-agent/cli.js";
+import type { CuaActorLabErrorCode, CuaActorLabHooks } 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
+ * external comms catch. Checked before any sandbox exists, because each one found later has
+ * already paid for a desktop.
+ */
+export declare function liveCuaRejection(args: {
+    caps: ComputerUsePlan["caps"];
+    /** The declared participant model; a spend cap needs its price. */
+    model: string | undefined;
+    hooks: CuaActorLabHooks;
+    env: Record<string, string | undefined>;
+    openaiApiKey: string;
+    e2bApiKey: string;
+    localAgentRoute: boolean;
+    preferredLocalAgent: LocalAgentId;
+    subjectEnvNames: string[];
+    externalCommsConfig: LabCommsExternal | undefined;
+}): Promise<{
+    code: CuaActorLabErrorCode;
+    message: string;
+} | undefined>;