humanish 0.106.0 → 0.107.0

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

@@ -1,96 +1,49 @@
-// The typed homes on RunLabOptions and the one place they meet the route hook bags. runLab calls
-// normalizeRunLabOptions first: it refuses an option the route cannot honor, or a new option set
-// together with the old field it replaces, and otherwise maps each new option into the bag the
-// route reads today. Old fields pass through untouched, so they keep their exact behavior.
+// The typed homes on RunLabOptions. runLab calls normalizeRunLabOptions first: it refuses an option
+// the route cannot honor and otherwise passes the typed options to the route, with env copied and
+// onEvent turned into the emitter. The package's runLab refuses the removed bags
+// (removedOptionRefusal).
 import path from "node:path";
 import { CUA_ACTOR_LAB_SCHEMA } from "../routes/computer-use/types.js";
 import { SCRIPTED_BROWSER_LAB_SCHEMA } from "../routes/scripted/types.js";
 import { CONCURRENT_SHARED_WORLD_LAB_SCHEMA } from "../routes/shared-world/types.js";
-import { TERMINAL_PRODUCT_LAB_SCHEMA, } from "../routes/terminal/types.js";
+import { TERMINAL_PRODUCT_LAB_SCHEMA } from "../routes/terminal/types.js";
 import { isLocalBrowserLab } from "../substrates/local/runtime-config.js";
-import { defaultSharedWorldPhaseSink, defaultSubjectPhaseSink } from "../subject/steps.js";
-import { HOOK_MEMBERS, withHookOverrides } from "./bag-overrides.js";
 import { resolveLabDryRun } from "./plan.js";
-import { knownSecretValues, labEventEmitter, participantOf, phaseEvent, planEvent, } from "./run-lab-events.js";
+import { knownSecretValues, labEventEmitter } from "./run-lab-events.js";
 import { rosterOf } from "./parse/actors.js";
-const conflict = (home, old) => ({
-    ok: false,
-    code: "HUMANISH_LAB_OPTION_CONFLICT",
-    message: `RunLabOptions.${home} and ${old} are both set. ${old} is the older form of ${home}; set only ${home}.`,
-});
 const unsupported = (option, route, reason) => ({
     ok: false,
     code: "HUMANISH_LAB_OPTION_UNSUPPORTED",
     message: `RunLabOptions.${option} is not supported on the ${route} route: ${reason}`,
 });
-/**
- * Whether a caller's bag sets `key`, from its property descriptors: a data property counts when its
- * value is defined, an accessor counts without being called. Nothing the caller defined runs.
- */
-function hasMember(bag, key) {
-    for (let source = bag ?? null; source !== null && source !== Object.prototype; source = Object.getPrototypeOf(source)) {
-        const descriptor = Object.getOwnPropertyDescriptor(source, key);
-        if (descriptor !== undefined)
-            return "value" in descriptor ? descriptor.value !== undefined : true;
-    }
-    return false;
-}
-/**
- * Every old field the options set that has a new home, and whether its home is set too. Presence
- * comes from property descriptors (hasMember), so no getter of the caller's runs.
- */
-function oldFieldsInUse(options) {
-    const pairs = [
-        ["env", "cuaHooks", "env"],
-        ["env", "scriptedHooks", "env"],
-        ["env", "terminalHooks", "env"],
-        ["env", "sharedWorldHooks", "env"],
-        ["scorer", "cuaHooks", "score"],
-        ["scorer", "cuaHooks", "deriveFeedback"],
-        ["scorer", "cuaHooks", "deriveArtifacts"],
-        ["scorer", "sharedWorldHooks", "score"],
-        ["scorer", "sharedWorldHooks", "deriveFeedback"],
-        ["scorer", "sharedWorldHooks", "deriveArtifacts"],
-        ["scorer", "terminalHooks", "score"],
-        ["scorer", "terminalHooks", "deriveFeedback"],
-        ["prepareDesktop", "cuaHooks", "prepareDesktop"],
-        ["prepareDesktop", "scriptedHooks", "prepareDesktop"],
-        ["prepareDesktop", "sharedWorldHooks", "prepareDesktop"],
-        ["onEvent", "cuaHooks", "onPreflight"],
-        ["onEvent", "cuaHooks", "onPhase"],
-        ["onEvent", "sharedWorldHooks", "onPhase"],
-        ["onEvent", "automaticAnalysis", "onStart"],
-        ["onStream", "cuaHooks", "onRuntimeStreamReady"],
-        ["onStream", "cuaHooks", "onRuntimeStreamEnded"],
-        ["onStream", "sharedWorldHooks", "onRuntimeStreamReady"],
-        ["onStream", "sharedWorldHooks", "onRuntimeStreamEnded"],
-        ["analysisSignal", "automaticAnalysis.deps", "signal"],
-        ["createProvider", "cuaHooks", "buildProvider"],
-        ["inProcess", "cuaHooks", "buildExecutor"],
-        ["rerun.participantIds", "rerun", "laneIds"],
-    ];
-    const home = (name) => name === "rerun.participantIds"
-        ? options.rerun?.participantIds !== undefined
-        : options[name] !== undefined;
-    const bagOf = (name) => name === "automaticAnalysis.deps"
-        ? options.automaticAnalysis?.deps
-        : options[name];
-    return pairs
-        .filter(([, bag, member]) => hasMember(bagOf(bag), member))
-        .map(([name, bag, member]) => ({ home: name, old: `${bag}.${member}`, clash: home(name) }));
-}
-/** Old fields removed in the next minor with no replacement. They warn, and they never clash. */
-function retiredFieldsInUse(options) {
-    return hasMember(options.cuaHooks, "createDesktopLane") ? ["cuaHooks.createDesktopLane"] : [];
-}
-const warned = new Set();
-/** One DeprecationWarning per old field per process. The bags' other test seams never warn. */
-function warnDeprecated(home, old) {
-    if (warned.has(old))
-        return;
-    warned.add(old);
-    const replacement = home === undefined ? "It has no replacement." : `Use RunLabOptions.${home}.`;
-    process.emitWarning(`RunLabOptions.${old} is deprecated and is removed in the next minor. ${replacement}`, { type: "DeprecationWarning", code: "HUMANISH_RUN_LAB_OPTION_DEPRECATED" });
+// Fields RunLabOptions no longer has, and where each one's job went.
+const REMOVED_OPTIONS = {
+    cuaHooks: "Use scorer, createProvider, inProcess, prepareDesktop, env, onEvent and onStream.",
+    scriptedHooks: "Use prepareDesktop and env.",
+    terminalHooks: "Use scorer and env.",
+    sharedWorldHooks: "Use scorer, prepareDesktop, env, onEvent and onStream.",
+    automaticAnalysis: "Use onEvent (analysis-started, analysis-finished) and analysisSignal.",
+    lab: "The humanish CLI sets it.",
+    scorerProvenance: "The humanish CLI sets it.",
+};
+/** The refusal for a field a JavaScript caller passed that RunLabOptions no longer has. */
+export function removedOptionRefusal(options) {
+    // rerun.laneIds, the older name of rerun.participantIds, would otherwise be ignored, so the rerun
+    // would select every failed participant instead of the ones the caller named.
+    if (options.rerun !== undefined && Reflect.get(options.rerun, "laneIds") !== undefined)
+        return {
+            ok: false,
+            code: "HUMANISH_LAB_OPTION_UNSUPPORTED",
+            message: 'RunLabOptions.rerun.laneIds was removed. Use rerun.participantIds. See docs/contracts/schemas.md, "Library options".',
+        };
+    const field = Object.keys(REMOVED_OPTIONS).find((key) => Reflect.get(options, key) !== undefined);
+    if (field === undefined)
+        return undefined;
+    return {
+        ok: false,
+        code: "HUMANISH_LAB_OPTION_UNSUPPORTED",
+        message: `RunLabOptions.${field} was removed. ${REMOVED_OPTIONS[field]} See docs/contracts/schemas.md, "Library options".`,
+    };
 }
 /** Why the route cannot honor an option it was given, or undefined when it can. */
 function unsupportedOption(config, route, options) {
@@ -113,11 +66,8 @@ function unsupportedOption(config, route, options) {
         if (prepareDesktop !== undefined) {
             if (isLocalBrowserLab(config))
                 return unsupported("prepareDesktop", route, "a local VM study has no E2B desktop.");
-            // The run is in process when either executor home is set: inProcess or the older
-            // cuaHooks.buildExecutor. Either way no desktop exists to prepare.
-            if (inProcess !== undefined ||
-                hasMember(options.cuaHooks, "buildExecutor") ||
-                source === "local-app")
+            // An in-process run has no desktop to prepare.
+            if (inProcess !== undefined || source === "local-app")
                 return unsupported("prepareDesktop", route, "an in-process run has no desktop.");
         }
         return undefined;
@@ -133,200 +83,25 @@ function unsupportedOption(config, route, options) {
         : "this route has no E2B desktop to prepare.");
 }
 /**
- * Refuse what the route cannot honor, then map the new options into the old bags. Nothing here
- * touches the filesystem, so a refusal leaves no run directory, receipt or sandbox.
+ * Refuse what the route cannot honor, copy env, and build the emitter onEvent receives through.
+ * Nothing here touches the filesystem, so a refusal leaves no run directory, receipt or sandbox.
  */
 export function normalizeRunLabOptions(config, route, options) {
-    const inUse = oldFieldsInUse(options);
-    const clash = inUse.find((field) => field.clash);
-    if (clash)
-        return conflict(clash.home, clash.old);
     const refused = unsupportedOption(config, route, options);
     if (refused)
         return refused;
-    for (const { home, old } of inUse)
-        warnDeprecated(home, old);
-    for (const old of retiredFieldsInUse(options))
-        warnDeprecated(undefined, old);
     const warnings = [];
-    const { env, scorer, prepareDesktop, onEvent, onStream, analysisSignal, createProvider, inProcess, ...legacy } = options;
+    const { env, onEvent, ...forwarded } = options;
     // The route gets this copy, so it is the env a warning is scrubbed against, whatever the caller
     // does to its own object afterwards.
     const forwardedEnv = env === undefined ? undefined : { ...env };
     const emit = labEventEmitter(onEvent, warnings, () => knownSecretValues(config, options, forwardedEnv));
-    const normalized = { ...legacy };
-    const participantIds = options.rerun?.participantIds;
-    if (options.rerun !== undefined && participantIds !== undefined) {
-        const { participantIds: _ids, ...rerun } = options.rerun;
-        normalized.rerun = { ...rerun, laneIds: participantIds };
-    }
-    const analysis = withMapped(legacy.automaticAnalysis, HOOK_MEMBERS.analysis, {
-        ...(analysisSignal === undefined
-            ? {}
-            : { deps: { ...legacy.automaticAnalysis?.deps, signal: analysisSignal } }),
-        ...(emit === undefined
-            ? {}
-            : {
-                onStart: () => {
-                    emit({ type: "analysis-started" });
-                    return () => emit({ type: "analysis-finished" });
-                },
-            }),
-    });
-    if (analysis !== undefined)
-        normalized.automaticAnalysis = analysis;
-    const envHome = forwardedEnv === undefined ? {} : { env: forwardedEnv };
-    const scoring = scorer === undefined ? {} : scorerHooks(scorer);
-    switch (route) {
-        case "computer-use": {
-            const hooks = withMapped(legacy.cuaHooks, HOOK_MEMBERS.cua, {
-                ...envHome,
-                ...scoring,
-                ...computerUseHooks(config, {
-                    prepareDesktop,
-                    onStream,
-                    createProvider,
-                    inProcess,
-                    legacyInProcess: hasMember(legacy.cuaHooks, "buildExecutor"),
-                }, emit),
-            });
-            if (hooks !== undefined)
-                normalized.cuaHooks = hooks;
-            break;
-        }
-        case "shared-world": {
-            const hooks = withMapped(legacy.sharedWorldHooks, HOOK_MEMBERS.sharedWorld, {
-                ...envHome,
-                ...scoring,
-                ...sharedWorldHooks({ prepareDesktop, onStream }, emit),
-            });
-            if (hooks !== undefined)
-                normalized.sharedWorldHooks = hooks;
-            break;
-        }
-        case "terminal": {
-            const hooks = withMapped(legacy.terminalHooks, HOOK_MEMBERS.terminal, {
-                ...envHome,
-                ...(scorer?.score === undefined ? {} : { score: scorer.score }),
-                ...(scorer?.deriveFeedback === undefined
-                    ? {}
-                    : { deriveFeedback: scorer.deriveFeedback }),
-            });
-            if (hooks !== undefined)
-                normalized.terminalHooks = hooks;
-            break;
-        }
-        case "scripted": {
-            const hooks = withMapped(legacy.scriptedHooks, HOOK_MEMBERS.scripted, {
-                ...envHome,
-                ...(prepareDesktop === undefined
-                    ? {}
-                    : {
-                        prepareDesktop: (desktop) => prepareDesktop(desktop, { kind: "subject" }),
-                    }),
-            });
-            if (hooks !== undefined)
-                normalized.scriptedHooks = hooks;
-            break;
-        }
-        case "preview":
-            break;
-    }
-    return { ok: true, options: normalized, warnings };
-}
-/** A caller's bag with new options mapped into it. With nothing to map, it is the same object. */
-function withMapped(bag, declared, mapped) {
-    if (Object.keys(mapped).length === 0)
-        return bag;
-    return withHookOverrides(bag, declared, mapped);
-}
-export function scorerHooks(scorer) {
-    return {
-        ...(scorer.score === undefined ? {} : { score: scorer.score }),
-        ...(scorer.deriveFeedback === undefined ? {} : { deriveFeedback: scorer.deriveFeedback }),
-        ...(scorer.deriveArtifacts === undefined ? {} : { deriveArtifacts: scorer.deriveArtifacts }),
-    };
-}
-/** The route awaits what these return, so onStream keeps the old hooks' barrier and errors. */
-function streamHooks(onStream) {
-    return {
-        onRuntimeStreamReady: (stream) => onStream({
-            type: "ready",
-            participantId: stream.laneId,
-            sandboxId: stream.sandboxId,
-            simId: stream.simId,
-            streamId: stream.streamId,
-            url: stream.url,
-        }),
-        onRuntimeStreamEnded: (stream) => onStream({
-            type: "ended",
-            participantId: stream.laneId,
-            simId: stream.simId,
-            streamId: stream.streamId,
-        }),
-    };
-}
-function computerUseHooks(config, homes, emit) {
-    const { prepareDesktop, onStream, createProvider, inProcess, legacyInProcess } = homes;
-    // A local VM study and an in-process run start no E2B stream, and the local study refuses a
-    // stream hook outright, so onStream is left unset there: it is never called.
-    const streams = !isLocalBrowserLab(config) && inProcess === undefined && !legacyInProcess;
-    return {
-        ...(prepareDesktop === undefined
-            ? {}
-            : {
-                prepareDesktop: (desktop, participant) => prepareDesktop(desktop, {
-                    kind: "participant",
-                    participant: participantOf(participant),
-                }),
-            }),
-        ...(createProvider === undefined
-            ? {}
-            : {
-                buildProvider: ({ config: lab, lane: participant, laneCount, executor }) => createProvider({
-                    config: lab,
-                    participant: participantOf({ ...participant, laneCount }),
-                    executor,
-                }),
-            }),
-        ...(inProcess === undefined
-            ? {}
-            : {
-                buildExecutor: ({ config: lab, appUrl }) => inProcess.executor({ config: lab, appUrl }),
-            }),
-        ...(onStream !== undefined && streams ? streamHooks(onStream) : {}),
-        ...(emit === undefined
-            ? {}
-            : {
-                onPreflight: (plan) => emit(planEvent(plan)),
-                onPhase: (event, participant) => {
-                    defaultSubjectPhaseSink(event, participant);
-                    emit(phaseEvent(event, { kind: "participant", participant: participantOf(participant) }));
-                },
-            }),
-    };
-}
-function sharedWorldHooks(homes, emit) {
-    const { prepareDesktop, onStream } = homes;
-    return {
-        ...(prepareDesktop === undefined
-            ? {}
-            : {
-                // The provisioned plane prepares the subject sandbox with no participant, then each one.
-                prepareDesktop: (desktop, participant) => prepareDesktop(desktop, participant === undefined
-                    ? { kind: "subject" }
-                    : { kind: "participant", participant: participantOf(participant) }),
-            }),
-        ...(onStream === undefined ? {} : streamHooks(onStream)),
-        ...(emit === undefined
-            ? {}
-            : {
-                onPhase: (event) => {
-                    defaultSharedWorldPhaseSink(event);
-                    emit(phaseEvent(event, { kind: "subject" }));
-                },
-            }),
-    };
+    // Every route reads its typed options directly, and onEvent reaches it as `emit`. unsupportedOption
+    // already refused an option no route reads; the preview route reads no env.
+    const normalized = { ...forwarded };
+    if (route !== "preview" && forwardedEnv !== undefined)
+        normalized.env = forwardedEnv;
+    return { ok: true, options: normalized, warnings, emit };
 }
 /** A refusal in the route's own result envelope, before any run exists. */
 export function optionRefusalOutcome(config, route, options, refusal) {
@@ -340,13 +115,11 @@ export function optionRefusalOutcome(config, route, options, refusal) {
         case "preview":
             return {
                 route: "preview",
-                backend: "synthetic",
                 result: { schema: "humanish.run-result.v1", ok: false, cwd, warnings: [], error },
             };
         case "computer-use":
             return {
                 route: "computer-use",
-                backend: "cua",
                 result: {
                     schema: CUA_ACTOR_LAB_SCHEMA,
                     ...common,
@@ -358,7 +131,6 @@ export function optionRefusalOutcome(config, route, options, refusal) {
         case "scripted":
             return {
                 route: "scripted",
-                backend: "scripted",
                 result: {
                     schema: SCRIPTED_BROWSER_LAB_SCHEMA,
                     ...common,
@@ -370,7 +142,6 @@ export function optionRefusalOutcome(config, route, options, refusal) {
         case "terminal":
             return {
                 route: "terminal",
-                backend: "terminal",
                 result: {
                     schema: TERMINAL_PRODUCT_LAB_SCHEMA,
                     ...common,
@@ -382,7 +153,6 @@ export function optionRefusalOutcome(config, route, options, refusal) {
             const participantCount = rosterOf(config.actors[0])?.length ?? 0;
             return {
                 route: "shared-world",
-                backend: "concurrent-shared-world",
                 result: {
                     schema: CONCURRENT_SHARED_WORLD_LAB_SCHEMA,
                     ...common,

package/dist/lab/summary.d.ts

@@ -2,9 +2,9 @@ import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
 import { type KeyResolutionDeps } from "../keys/key-resolution.js";
 export declare const LAB_SUMMARY_SCHEMA = "humanish.lab-summary.v1";
 export interface LabCaps {
-    /** Per-lane blast-radius budget. */
+    /** Per-participant blast-radius budget. */
     laneUsd?: number;
-    /** Shared study budget across every lane. */
+    /** Shared study budget across every participant. */
     studyUsd?: number;
 }
 export interface LabSummary {
@@ -31,8 +31,8 @@ export interface LabSummary {
     /** The model that will actually run, override or default. */
     model?: string;
     /**
-     * The reasoning effort that will actually run, override or default — and "per-lane" when the
-     * roster declares more than one, because a single value would be a lie about half the lanes.
+     * The reasoning effort that will actually run, override or default — and `"per-lane"` when the
+     * roster declares more than one, because a single value would be a lie about half the participants.
      *
      * Shown because it was a silent constant: unreachable from a lab, so every run took the provider
      * default. A study variable you cannot see is one nobody chose (#497).
@@ -45,6 +45,11 @@ export interface LabSummary {
      */
     keysReady?: boolean;
     missingKeys?: string[];
+    /**
+     * The planner's refusal message when a live key check finds the lab will not plan, as
+     * `humanish lab run` would report it. `keysReady` is then unset: a refused plan lists no keys.
+     */
+    planRefusal?: string;
 }
 export interface ReadLabSummaryOptions {
     /** Skip the key probe (it touches vendor stores); the screen then shows no keys line. */

package/dist/lab/summary.js

@@ -10,7 +10,8 @@ import { localRuntimeStatus } from "../substrates/local/runtime.js";
 // declared is not "unlimited" and not "$0"; it is a line the screen does not draw.
 import { resolveLabDryRun } from "./plan.js";
 import { routeOf } from "./plan.js";
-import { labKeyRequirements, localCodexParticipantCheck } from "./doctor.js";
+import { localCodexParticipantCheck, planCliRun } from "./doctor.js";
+import { requiredKeys, requiredSubjectEnv } from "./requirements.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { DEFAULT_OPENAI_CU_MODEL, DEFAULT_OPENAI_CU_REASONING_EFFORT, } from "../actors/computer-use/openai-provider.js";
 import { inspectLabManifest } from "./discover.js";
@@ -20,7 +21,7 @@ import { receivingRequiredKey } from "../comms/setup.js";
 import { rosterOf } from "./parse/actors.js";
 export const LAB_SUMMARY_SCHEMA = "humanish.lab-summary.v1";
 /**
- * The effort every lane will run at, or "per-lane" when they differ. A lane that declares nothing
+ * The effort every participant will run at, or `"per-lane"` when they differ. A participant that declares nothing
  * inherits the actor's, and an actor that declares nothing gets the provider default — which is
  * reported as the resolved value, exactly as `model` reports its default rather than hiding it.
  */
@@ -60,7 +61,7 @@ function participantsOf(config) {
     const unique = [...new Set(personas)];
     if (unique.length === 0)
         return `${count} participant${count === 1 ? "" : "s"}`;
-    // Several lanes of ONE persona reads as "3 × skeptical-power-user"; genuinely different people
+    // Several participants of ONE persona reads as "3 × skeptical-power-user"; genuinely different people
     // are named, because which personas are in a study is the study's design.
     return unique.length === 1 ? `${count} × ${unique[0]}` : unique.join(" · ");
 }
@@ -87,9 +88,14 @@ export async function readLabSummary(cwd, lab, options = {}) {
     const route = routeOf(inspected.config);
     let keysReady;
     let missingKeys;
-    if (options.checkKeys === true) {
-        const dryRun = resolveLabDryRun(inspected.config, undefined, true) === true;
-        const subjectKeys = dryRun ? [] : (inspected.config.subject.env ?? []);
+    const dryRun = resolveLabDryRun(inspected.config, undefined, true) === true;
+    // A live key check reads the plan's requirements. A lab the planner refuses has none to check,
+    // so the summary reports the refusal in place of its keys.
+    const planned = options.checkKeys === true && !dryRun ? await planCliRun(inspected.config, cwd) : undefined;
+    const planRefusal = planned?.ok === false ? planned.refusal.message : undefined;
+    if (options.checkKeys === true && planned?.ok !== false) {
+        const requirements = planned?.planned.plan.requirements ?? [];
+        const subjectKeys = requiredSubjectEnv(requirements);
         const email = inspected.config.comms?.email;
         const receivingKey = !dryRun && email?.kind === "real"
             ? await receivingRequiredKey(cwd, email.connection)
@@ -109,9 +115,9 @@ export async function readLabSummary(cwd, lab, options = {}) {
                 ...(options.keyDeps === undefined ? {} : { deps: options.keyDeps }),
             }).catch(() => []);
         const present = new Set(probes.filter((probe) => probe.source !== null).map((probe) => probe.name));
-        const required = labKeyRequirements(inspected.config, route, dryRun, (name) => present.has(name));
+        const required = requiredKeys(requirements, (name) => present.has(name));
         const missing = [
-            ...new Set([...required.keys, ...subjectKeys, ...(receivingKey ? [receivingKey] : [])]),
+            ...new Set([...required, ...subjectKeys, ...(receivingKey ? [receivingKey] : [])]),
         ].filter((name) => !present.has(name));
         if (receivingKey === null)
             missing.push("email connection");
@@ -164,5 +170,6 @@ export async function readLabSummary(cwd, lab, options = {}) {
         caps: capsOf(inspected.config),
         ...(keysReady === undefined ? {} : { keysReady }),
         ...(missingKeys === undefined ? {} : { missingKeys }),
+        ...(planRefusal === undefined ? {} : { planRefusal }),
     };
 }