humanish 0.106.0 → 0.107.0

package/dist/lab/persona-resolve.d.ts

@@ -13,7 +13,7 @@ export declare function resolveCommittedPersona(projectRoot: PreparedSelectedOut
     warnings: string[];
 }>;
 /**
- * Resolve every distinct persona id a run will use, once, before lane specs are built. Returning a
+ * Resolve every distinct persona id a run will use, once, before participant specs are built. Returning a
  * map keeps the plan builder PURE (it is exported npm surface and asserted pure by tests): the
  * async file reads happen here, and the composer only does a lookup.
  */
@@ -22,8 +22,8 @@ export declare function resolveCommittedPersonas(projectRoot: PreparedSelectedOu
     warnings: string[];
 }>;
 /**
- * Every persona id a lab config could put on a browser lane: the per-lane roster when one is
- * declared, otherwise the actor-level persona that every fan-out lane inherits.
+ * Every persona id a lab config could put on a browser participant: the roster when one is
+ * declared, otherwise the actor-level persona that every fan-out participant inherits.
  */
 export declare function labPersonaIds(config: {
     actors?: readonly Pick<LabActor, "persona" | "lanes">[];

package/dist/lab/persona-resolve.js

@@ -6,7 +6,7 @@ import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../ru
 import { digestText, redactText } from "../evidence/redaction.js";
 import { realpath } from "node:fs/promises";
 import { rosterOf } from "./parse/actors.js";
-/** Persona ids are file-name segments, never paths: the same grammar the terminal lane enforces. */
+/** Persona ids are file-name segments, never paths: the same grammar the terminal route enforces. */
 const PERSONA_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 /** Title-case an id for the fallback display name (`skeptical-power-user` -> `Skeptical Power User`). */
 export function personaTitleFromId(personaId) {
@@ -65,7 +65,7 @@ export async function resolveCommittedPersona(projectRoot, personaId) {
     };
 }
 /**
- * Resolve every distinct persona id a run will use, once, before lane specs are built. Returning a
+ * Resolve every distinct persona id a run will use, once, before participant specs are built. Returning a
  * map keeps the plan builder PURE (it is exported npm surface and asserted pure by tests): the
  * async file reads happen here, and the composer only does a lookup.
  */
@@ -81,8 +81,8 @@ export async function resolveCommittedPersonas(projectRoot, personaIds) {
     return { personas, warnings };
 }
 /**
- * Every persona id a lab config could put on a browser lane: the per-lane roster when one is
- * declared, otherwise the actor-level persona that every fan-out lane inherits.
+ * Every persona id a lab config could put on a browser participant: the roster when one is
+ * declared, otherwise the actor-level persona that every fan-out participant inherits.
  */
 export function labPersonaIds(config) {
     const ids = [];

package/dist/lab/persona.js

@@ -1,4 +1,5 @@
 import { digestText, redactText } from "../evidence/redaction.js";
+import { isRecord } from "../run/type-guards.js";
 export const PERSONA_BACKGROUND_MAX_BYTES = 32 * 1024;
 const PERSONA_COMPILER_VERSION = 2;
 export class PersonaConfigError extends Error {
@@ -18,9 +19,6 @@ const PERSONA_FIELDS = new Set([
     "constraints",
 ]);
 const TRAIT_FIELDS = new Set(["patience", "technical_confidence", "accessibility_needs"]);
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function cleanText(value) {
     return value
         .replace(/\r\n?/g, "\n")

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

@@ -1,4 +1,3 @@
-import type { RunLabProvenance } from "../run/status.js";
 import type { Brain, ComputerUsePlan, NonEmpty, PlannedAnalysis, ProvisionedSubject, Requirement } from "./plan-types.js";
 import type { LabConfig } from "./types.js";
 export type Base = Omit<ComputerUsePlan, "route" | "actor" | "runner" | "concurrency" | "sessionBudgetMs" | "sandboxMs" | "caps" | "rerun">;
@@ -13,10 +12,15 @@ export declare function desktopRequirements(config: LabConfig, args: {
     externalCatch: boolean;
 }): Requirement[];
 export declare function brainOf(config: LabConfig, callerProvider: boolean): Brain;
+/** The brain of a run whose provider the library caller supplies. */
+export declare function callerBrainOf(config: LabConfig): Extract<Brain, {
+    kind: "caller";
+}>;
+/** The model a participant's spend is priced at when its provider reports none. */
+export declare function pricedModel(brain: Brain): string;
 /** The fields every plan shares, from a config whose analysis already resolved. */
 export declare function planBase(config: LabConfig, input: {
     readonly dryRun: boolean;
-    readonly lab?: RunLabProvenance;
     readonly analysis?: {
         readonly config?: PlannedAnalysis["config"] | undefined;
         readonly preferLargerOutput?: boolean | undefined;

package/dist/lab/plan-base.js

@@ -1,10 +1,13 @@
 // What every route planner shares: the plan fields common to all routes, the frozen residual config,
 // and the requirement and subject helpers.
 import { DEFAULT_OPENAI_CU_MODEL } from "../actors/computer-use/openai-provider.js";
-function deepFreeze(value) {
-    if (typeof value === "object" && value !== null) {
+// A YAML alias can make a parsed record contain itself (an inline persona that names its own
+// anchor), and structuredClone keeps the cycle, so each object is frozen once.
+function deepFreeze(value, frozen = new WeakSet()) {
+    if (typeof value === "object" && value !== null && !frozen.has(value)) {
+        frozen.add(value);
         for (const child of Object.values(value))
-            deepFreeze(child);
+            deepFreeze(child, frozen);
         Object.freeze(value);
     }
     return value;
@@ -85,10 +88,23 @@ export function desktopRequirements(config, args) {
 export function brainOf(config, callerProvider) {
     const actor = config.actors[0];
     if (callerProvider)
-        return { kind: "caller" };
+        return callerBrainOf(config);
+    const declared = declaredModelOf(config);
     if (actor?.type === "local-agent")
-        return { kind: "local-agent", agent: actor.localAgent ?? "codex" };
-    return { kind: "openai", model: actor?.model ?? DEFAULT_OPENAI_CU_MODEL };
+        return { kind: "local-agent", agent: actor.localAgent ?? "codex", ...declared };
+    return { kind: "openai", model: actor?.model ?? DEFAULT_OPENAI_CU_MODEL, ...declared };
+}
+/** The brain of a run whose provider the library caller supplies. */
+export function callerBrainOf(config) {
+    return { kind: "caller", ...declaredModelOf(config) };
+}
+function declaredModelOf(config) {
+    const model = config.actors[0]?.model;
+    return model === undefined ? {} : { declaredModel: model };
+}
+/** The model a participant's spend is priced at when its provider reports none. */
+export function pricedModel(brain) {
+    return brain.declaredModel ?? DEFAULT_OPENAI_CU_MODEL;
 }
 /** The fields every plan shares, from a config whose analysis already resolved. */
 export function planBase(config, input) {
@@ -96,7 +112,6 @@ export function planBase(config, input) {
     return {
         labId: config.id,
         ...(config.title === undefined ? {} : { title: config.title }),
-        ...(input.lab === undefined ? {} : { lab: input.lab }),
         residual: residualOf(config),
         dryRun: input.dryRun,
         ...(analysis === undefined

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

@@ -5,7 +5,7 @@ import type { LabTask } from "./tasks.js";
 import type { LabConfig } from "./types.js";
 /** Who one participant is. Every route with participants carries this record. */
 export interface Participant {
-    /** Declared roster id, else `lane-NN` (independent lanes) or `role-NN` (shared-world seats). */
+    /** Declared roster id, else `lane-NN` (independent participants) or `role-NN` (shared-world participants). */
     readonly id: string;
     /** 0-based position in the roster. Bundle `sim-NNN` and `stream-NNN` ids derive from it. */
     readonly index: number;
@@ -30,7 +30,7 @@ interface DesktopParticipant extends Participant {
         readonly preset: DevicePreset;
         readonly resolution: [number, number];
     };
-    /** Lane value, else actor value, else absent (the provider default is recorded in the trace). */
+    /** The `lanes[]` entry's value, else actor value, else absent (the provider default is recorded in the trace). */
     readonly limits: {
         readonly stopWhen?: StopWhen;
         readonly dwell?: DwellWindow;
@@ -38,10 +38,10 @@ interface DesktopParticipant extends Participant {
         readonly maxOutputTokens?: number;
     };
 }
-/** Only independent computer-use lanes consume a task protocol and a per-lane target. */
+/** Only independent computer-use participants consume a task protocol and their own target. */
 export interface ComputerUseParticipant extends DesktopParticipant {
     readonly tasks?: readonly LabTask[];
-    /** app-url fan-out only: this lane's own entry URL; absent means the subject URL. */
+    /** app-url fan-out only: this participant's own entry URL; absent means the subject URL. */
     readonly targetUrl?: string;
 }
 /** A seat on a provisioned plane: an optional same-origin path under `serve.url`. */
@@ -68,7 +68,7 @@ export type SharedWorldRoster = {
 /** One shared-world participant on either plane. */
 export type SharedWorldParticipant = ProvisionedParticipant | ExternalPublicParticipant;
 /**
- * The lanes of a computer-use lab: the declared roster, else `count` identical lanes. A count
+ * The participants of a computer-use lab: the declared roster, else `count` identical ones. A count
  * override (`--count`) applies only when no roster is declared.
  */
 export declare function computerUseParticipants(config: LabConfig, countOverride?: number): ComputerUseParticipant[];

package/dist/lab/plan-participants.js

@@ -1,5 +1,5 @@
 // Who takes part in a lab: one record per participant, built from the declared roster or a count.
-// Computer-use lanes and shared-world seats share the desktop fields; each kind adds its own.
+// Computer-use and shared-world participants share the desktop fields; each kind adds its own.
 import { resolveParticipantDevice } from "./device-presets.js";
 import { isSharedWorldComposition, participantIdAt } from "./routing.js";
 import { focusOf, rosterOf } from "./parse/actors.js";
@@ -35,7 +35,7 @@ function desktopParticipant(config, entry, index, kind, focus) {
     };
 }
 /**
- * The lanes of a computer-use lab: the declared roster, else `count` identical lanes. A count
+ * The participants of a computer-use lab: the declared roster, else `count` identical ones. A count
  * override (`--count`) applies only when no roster is declared.
  */
 export function computerUseParticipants(config, countOverride) {

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

@@ -11,7 +11,10 @@ import type { ComputerUseParticipant, ExternalPublicParticipant, ProvisionedPart
 import type { LabConfig, LabExecutionTerminal, LabRuntimeAuth, LabScenarioCaps, LabSubjectProduct, LabSubjectServe, LabSubjectState, LabSubjectStateCheckpoint } from "./types.js";
 export type NonEmpty<T> = readonly [T, ...T[]];
 type AtLeastTwo<T> = readonly [T, T, ...T[]];
-/** Something a route checks right before acquisition. Doctor, the TUI and preflight list the same set. */
+/**
+ * Something a route checks right before acquisition. Preflight refuses on, and doctor and the TUI
+ * report, the keys and subject env listed here, through src/lab/requirements.ts.
+ */
 export type Requirement = {
     readonly kind: "key";
     readonly name: "OPENAI_API_KEY" | "E2B_API_KEY";
@@ -39,7 +42,12 @@ export type Requirement = {
     readonly kind: "external-catch";
     readonly url: string;
 };
-/** Config fields no plan field decides. Routes read nothing else from the config. */
+/**
+ * Config fields no plan field decides. After admission, computer use reads the config only to pass
+ * it to the caller's createProvider and inProcess executor; its planner, refusal envelopes and local
+ * VM study read it before a plan exists. Shared world, terminal and scripted still read some config
+ * fields at run time.
+ */
 export type ResidualConfig = Pick<LabConfig, "comms" | "policies" | "personas" | "defaults" | "review"> & {
     readonly execution?: Pick<NonNullable<LabConfig["execution"]>, "desktop" | "target">;
     readonly subject: Pick<LabConfig["subject"], "clone" | "localTree" | "repos" | "envValues">;
@@ -73,15 +81,23 @@ interface PreviewPlan extends PlanBase {
     /** A safe integer of at least 1. */
     readonly participantCount: number;
 }
-/** The model driving a desktop participant. `caller` is the library caller's buildProvider. */
+/**
+ * The model driving a desktop participant. `caller` is the library caller's createProvider.
+ * `declaredModel` is actors[0].model as the lab wrote it, absent when undeclared: the providers
+ * take it as written, and spend is priced at it, else the default (pricedModel). An openai
+ * brain's `model` is the one its provider runs, with that default applied.
+ */
 export type Brain = {
     readonly kind: "openai";
     readonly model: string;
+    readonly declaredModel?: string;
 } | {
     readonly kind: "local-agent";
     readonly agent: LocalAgentId;
+    readonly declaredModel?: string;
 } | {
     readonly kind: "caller";
+    readonly declaredModel?: string;
 };
 export type ProvisionedSubject = {
     readonly kind: "clone";
@@ -99,6 +115,11 @@ export interface AppUrlSubject {
     readonly kind: "app-url";
     readonly appUrl: string;
     readonly publicTargets: boolean;
+    /**
+     * A `subject.serve.url` declared on this subject, which the parser refuses and only a library
+     * config can carry. Participants map links to it back to their own app.
+     */
+    readonly serveUrl?: string;
 }
 /**
  * Supported subject and desktop pairings. The local VM also takes public targets: the route runs
@@ -111,6 +132,8 @@ export type ComputerUseRunner = {
     readonly subject: AppUrlSubject | ProvisionedSubject | {
         readonly kind: "desktop-cli";
         readonly product: LabSubjectProduct;
+        /** As on AppUrlSubject: a library config's declared `subject.serve.url`. */
+        readonly serveUrl?: string;
     };
 } | {
     readonly desktop: "local-vm";
@@ -121,9 +144,9 @@ export type ComputerUseRunner = {
 /** The caller's executor and provider together; one participant. */
  | {
     readonly desktop: "in-process";
-    readonly brain: {
-        readonly kind: "caller";
-    };
+    readonly brain: Extract<Brain, {
+        kind: "caller";
+    }>;
     readonly participants: readonly [ComputerUseParticipant];
     readonly subject: AppUrlSubject | {
         readonly kind: "local-app";
@@ -193,7 +216,10 @@ export type TerminalPlan = PlanBase & {
     readonly mission?: string;
     readonly runtime: {
         readonly version?: string;
-        readonly model?: string;
+        /** Passed to Codex as `--model` on every run, so the bundle can name and price it. */
+        readonly model: string;
+        /** `declared` by the lab's actor, or humanish's participant default. */
+        readonly modelSource: "declared" | "humanish_default";
         readonly reasoningEffort?: ReasoningEffort;
         readonly auth?: LabRuntimeAuth;
     };

package/dist/lab/plan.d.ts

@@ -1,17 +1,9 @@
-import type { RunLabOptions } from "../run-lab.js";
+import type { InternalRunLabOptions } from "../run-lab.js";
+import type { LabDeps } from "./lab-deps.js";
 import type { PlanResult } from "./plan-types.js";
 import type { LabConfig } from "./types.js";
 /** The five execution paths a lab can take. */
 export type LabRoute = "preview" | "computer-use" | "shared-world" | "terminal" | "scripted";
-/** A route's older name, kept in `LabOutcome.backend` and the preflight result's `backend`. */
-export type LabBackend = "synthetic" | "cua" | "scripted" | "terminal" | "concurrent-shared-world";
-/** The backend name older callers and wire fields use for a route. */
-export declare function backendOf(route: LabRoute): LabBackend;
-/**
- * The backend a config runs on: `routeOf`, under its older name.
- * @deprecated Use `routeOf`, and `backendOf` for the older backend name. This goes in the next minor.
- */
-export declare function selectLabBackend(config: LabConfig): LabBackend;
 /**
  * The route a config takes. It never refuses: a config no route can run still gets the route
  * whose own checks refuse it with the most precise reason.
@@ -24,4 +16,4 @@ export declare function resolveLabDryRun(config: LabConfig, override: boolean |
  * makes every refusal that route makes, in the route's order and with its codes and messages; the
  * route's exported runner calls the same planner.
  */
-export declare function planLab(config: LabConfig, options: RunLabOptions): PlanResult;
+export declare function planLab(config: LabConfig, options: InternalRunLabOptions, deps?: LabDeps): PlanResult;

package/dist/lab/plan.js

@@ -1,10 +1,9 @@
 // The route decision. A lab's route follows from its composition (subject.source,
 // execution.target, the first actor's registered lane, subject.topology), never from a declared
-// kind. This is the only function that decides it; backendOf maps its answer to the older
-// backend names.
+// kind. This is the only function that decides it.
 import { resolveAutomaticAnalysis } from "../analysis/automatic-config.js";
-import { planComputerUseLab } from "../routes/computer-use/plan.js";
-import { planScriptedLab } from "../routes/scripted/plan.js";
+import { callerDrivingOf, planComputerUseLab } from "../routes/computer-use/plan.js";
+import { injectedBrowser, planScriptedLab } from "../routes/scripted/plan.js";
 import { planSharedWorldLab } from "../routes/shared-world/plan.js";
 import { planTerminalLab } from "../routes/terminal/plan.js";
 import { localBrowserDefaults } from "../substrates/local/runtime-config.js";
@@ -12,24 +11,6 @@ import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
 import { planBase } from "./plan-base.js";
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
 import { automaticAnalysisRouteReason, taskProtocolValidationReason } from "./validation.js";
-const BACKENDS = {
-    preview: "synthetic",
-    "computer-use": "cua",
-    "shared-world": "concurrent-shared-world",
-    terminal: "terminal",
-    scripted: "scripted",
-};
-/** The backend name older callers and wire fields use for a route. */
-export function backendOf(route) {
-    return BACKENDS[route];
-}
-/**
- * The backend a config runs on: `routeOf`, under its older name.
- * @deprecated Use `routeOf`, and `backendOf` for the older backend name. This goes in the next minor.
- */
-export function selectLabBackend(config) {
-    return backendOf(routeOf(config));
-}
 /**
  * The route a config takes. It never refuses: a config no route can run still gets the route
  * whose own checks refuse it with the most precise reason.
@@ -43,8 +24,8 @@ export function routeOf(config) {
     // route refuses the actor instead of another route running something else.
     if (isTerminalProductComposition(config) || source === "terminal-product")
         return "terminal";
-    // Checked before computer use: the same composition without the topology declaration runs as
-    // independent lanes.
+    // Checked before computer use: the same composition without the topology declaration runs
+    // independent participants.
     if (isSharedWorldComposition(config))
         return "shared-world";
     // A CLI studied at a desktop is a computer-use study whose subject is a terminal window.
@@ -115,42 +96,37 @@ function planPreview(config, options, input) {
  * makes every refusal that route makes, in the route's order and with its codes and messages; the
  * route's exported runner calls the same planner.
  */
-export function planLab(config, options) {
+export function planLab(config, options, deps = {}) {
     const lab = localBrowserDefaults(config);
-    const input = {
-        dryRun: resolveLabDryRun(lab, options.dryRun, true) ?? true,
-        ...(options.lab === undefined ? {} : { lab: options.lab }),
-    };
-    const result = planRoute(routeOf(config), lab, options, input);
+    const input = { dryRun: resolveLabDryRun(lab, options.dryRun, true) ?? true };
+    const result = planRoute(routeOf(config), lab, options, input, deps);
     if (!result.ok)
         return result;
-    return { ok: true, planned: { plan: result.plan } };
+    // The manifest the CLI resolved (#455) enters the plan here and nowhere else; the routes read
+    // plan.lab for the run's status record and bundle.
+    const plan = options.lab === undefined ? result.plan : { ...result.plan, lab: options.lab };
+    return { ok: true, planned: { plan } };
 }
-function planRoute(route, lab, options, input) {
+function planRoute(route, lab, options, input, deps) {
     switch (route) {
         case "preview":
             return planPreview(lab, options, input);
         case "computer-use":
             return planComputerUseLab(lab, {
                 ...input,
-                ...(options.cuaHooks === undefined ? {} : { hooks: options.cuaHooks }),
+                hasRunSession: deps.runSession !== undefined,
+                driving: callerDrivingOf(options),
                 ...(options.count === undefined ? {} : { countOverride: options.count }),
                 ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
             });
         case "shared-world":
             return planSharedWorldLab(lab, {
                 ...input,
-                ...(options.sharedWorldHooks === undefined ? {} : { hooks: options.sharedWorldHooks }),
+                hasRunSession: deps.runSession !== undefined,
             });
         case "terminal":
-            return planTerminalLab(lab, {
-                ...input,
-                ...(options.terminalHooks === undefined ? {} : { hooks: options.terminalHooks }),
-            });
+            return planTerminalLab(lab, { ...input, hasCostProbe: deps.costProbe !== undefined });
         case "scripted":
-            return planScriptedLab(lab, {
-                ...input,
-                ...(options.scriptedHooks === undefined ? {} : { hooks: options.scriptedHooks }),
-            });
+            return planScriptedLab(lab, { ...input, injectedBrowser: injectedBrowser(deps) });
     }
 }

package/dist/lab/preflight-result.js

@@ -1,6 +1,5 @@
 // The preflight result a run returns, built from its context. preflight.ts and the probes in
 // preflight-probes.ts both finish through these, so they live below both.
-import { backendOf } from "./plan.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { digestText } from "../evidence/redaction.js";
 export const LAB_PREFLIGHT_SCHEMA = "humanish.lab-preflight-result.v1";
@@ -17,7 +16,6 @@ export function finalize(ctx, args) {
         labId: ctx.labId,
         origin: ctx.origin,
         path: ctx.path,
-        backend: backendOf(ctx.route),
         route: ctx.route,
         reachability: ctx.reachability,
         checks,

package/dist/lab/preflight.d.ts

@@ -2,7 +2,6 @@ import type { AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
 import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
 import { type LabConfig } from "./types.js";
 import { LAB_PREFLIGHT_SCHEMA } from "./preflight-result.js";
-import type { LabBackend } from "./plan.js";
 import { type LabRoute } from "./plan.js";
 import { type LabResolveFailure } from "./discover.js";
 export type LabPreflightReachabilityMode = "metadata" | "public-preview" | "sandbox-loopback" | "prepared-host";
@@ -46,8 +45,6 @@ export interface LabPreflightResult {
     labId?: string;
     origin?: string;
     path?: string;
-    /** The route's older name; `route` is the current one. */
-    backend?: LabBackend;
     route?: LabRoute;
     reachability: LabPreflightReachabilityMode;
     checks: LabPreflightCheck[];

package/dist/lab/preflight.js

@@ -48,7 +48,7 @@ export async function runLabPreflight(options) {
         hooks: options.hooks ?? {},
         checks: [
             { name: "lab manifest", ok: true, message: `resolved ${resolved.origin} lab manifest` },
-            { name: "backend", ok: true, message: `selected the ${route} route` },
+            { name: "route", ok: true, message: `selected the ${route} route` },
         ],
         targets: collectTargets(resolved.config),
         sandbox: { created: false },

package/dist/lab/requirements.d.ts

@@ -0,0 +1,20 @@
+import type { LabPlan, Requirement } from "./plan-types.js";
+/** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
+export declare function missingKeys(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
+/** The subject env names the requirements list and `env` lacks, in declaration order. */
+export declare function missingSubjectEnv(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
+/**
+ * The provider keys the requirements name, in plan order. A `key-one-of` names the first of its
+ * keys that `isPresent` reports, else OPENAI_API_KEY.
+ */
+export declare function requiredKeys(requirements: readonly Requirement[], isPresent: (name: string) => boolean): string[];
+/** The subject env names the requirements list, in declaration order. */
+export declare function requiredSubjectEnv(requirements: readonly Requirement[]): string[];
+/**
+ * The provider keys a live run of `plan` is known to read: its `key` and `key-one-of` names, its
+ * subject env, the external catch's token variable, ANTHROPIC_API_KEY for a Claude Code
+ * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `lab run` prints a
+ * key-source line for these only. Discovery still fills every key it finds: other readers, such as
+ * a declared scorer's host code, are not in the plan.
+ */
+export declare function keyNamesOf(plan: LabPlan): ReadonlySet<string>;

package/dist/lab/requirements.js

@@ -0,0 +1,54 @@
+/** Provider keys in the order the routes name them in a refusal. */
+const KEY_ORDER = ["OPENAI_API_KEY", "E2B_API_KEY"];
+const present = (env, name) => (env[name]?.trim() ?? "") !== "";
+/** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
+export function missingKeys(requirements, env) {
+    const required = new Set(requirements.flatMap((requirement) => (requirement.kind === "key" ? [requirement.name] : [])));
+    return KEY_ORDER.filter((name) => required.has(name) && !present(env, name));
+}
+/** The subject env names the requirements list and `env` lacks, in declaration order. */
+export function missingSubjectEnv(requirements, env) {
+    return requiredSubjectEnv(requirements).filter((name) => !present(env, name));
+}
+/**
+ * The provider keys the requirements name, in plan order. A `key-one-of` names the first of its
+ * keys that `isPresent` reports, else OPENAI_API_KEY.
+ */
+export function requiredKeys(requirements, isPresent) {
+    return requirements.flatMap((requirement) => {
+        if (requirement.kind === "key")
+            return [requirement.name];
+        if (requirement.kind === "key-one-of")
+            return [requirement.names.find(isPresent) ?? requirement.names[1]];
+        return [];
+    });
+}
+/** The subject env names the requirements list, in declaration order. */
+export function requiredSubjectEnv(requirements) {
+    return requirements.flatMap((requirement) => requirement.kind === "subject-env" ? requirement.names : []);
+}
+/**
+ * The provider keys a live run of `plan` is known to read: its `key` and `key-one-of` names, its
+ * subject env, the external catch's token variable, ANTHROPIC_API_KEY for a Claude Code
+ * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `lab run` prints a
+ * key-source line for these only. Discovery still fills every key it finds: other readers, such as
+ * a declared scorer's host code, are not in the plan.
+ */
+export function keyNamesOf(plan) {
+    const names = new Set();
+    for (const requirement of plan.requirements) {
+        if (requirement.kind === "key")
+            names.add(requirement.name);
+        if (requirement.kind === "key-one-of" || requirement.kind === "subject-env")
+            for (const name of requirement.names)
+                names.add(name);
+        if (requirement.kind === "local-agent" && requirement.agent === "claude")
+            names.add("ANTHROPIC_API_KEY");
+    }
+    const catchToken = plan.residual.comms?.email?.external?.authTokenEnv;
+    if (catchToken !== undefined)
+        names.add(catchToken);
+    if (plan.analysis !== undefined && plan.analysis.config.provider !== "codex")
+        names.add("OPENAI_API_KEY");
+    return names;
+}

package/dist/lab/route-inputs.d.ts

@@ -1,17 +1,28 @@
-import type { RunLabOptions } from "../run-lab.js";
+import type { InternalRunLabOptions } from "../run-lab.js";
+import type { RunScorerProvenance } from "../run/bundle.js";
+import { type AdapterScorerModule } from "./adapter-scorer-loader.js";
+import type { LabDeps } from "./lab-deps.js";
+import type { LabEvent } from "./run-lab-events.js";
 import type { ComputerUseRunInput } from "../routes/computer-use/types.js";
 import type { ScriptedRunInput } from "../routes/scripted/types.js";
 import type { SharedWorldRunInput } from "../routes/shared-world/types.js";
 import type { TerminalRunInput } from "../routes/terminal/types.js";
-export declare function computerUseInput(options: RunLabOptions): ComputerUseRunInput;
-export declare function scriptedInput(options: RunLabOptions): ScriptedRunInput;
-export declare function terminalInput(options: RunLabOptions): TerminalRunInput;
-export declare function sharedWorldInput(options: RunLabOptions): SharedWorldRunInput;
+export declare function computerUseInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): ComputerUseRunInput;
+export declare function scriptedInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): ScriptedRunInput;
+export declare function terminalInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): TerminalRunInput;
+export declare function sharedWorldInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): SharedWorldRunInput;
 /** A scorer the CLI loads after the route's local checks, and the provenance it stamps on the run. */
-export type LateScorer = Pick<RunLabOptions, "scorer" | "scorerProvenance">;
-/** The computer-use input with a scorer loaded after admission (see withLateScorer). */
-export declare function computerUseInputWithScorer(input: ComputerUseRunInput, late: LateScorer | undefined): ComputerUseRunInput;
-/** The shared-world input with a scorer loaded after admission (see withLateScorer). */
-export declare function sharedWorldInputWithScorer(input: SharedWorldRunInput, late: LateScorer | undefined): SharedWorldRunInput;
-/** The terminal input with a scorer loaded after admission. Terminal runs take no deriveArtifacts. */
-export declare function terminalInputWithScorer(input: TerminalRunInput, late: LateScorer | undefined): TerminalRunInput;
+export type LateScorer = Pick<InternalRunLabOptions, "scorer" | "scorerProvenance">;
+/** Narrows RunLabOptions.scorer to the context the route passes (adapter-scorer-loader.ts). */
+type NarrowScorer<S> = (scorer: AdapterScorerModule) => S;
+/**
+ * A route's input with a scorer loaded after admission, and the scorer's provenance, as if the
+ * caller had passed them up front. The rest of the input is the one the route's checks admitted.
+ */
+export declare function withLateScorer<S, I extends {
+    scorer?: S;
+    scorerProvenance?: RunScorerProvenance;
+}>(input: I, late: LateScorer | undefined, narrow: NarrowScorer<S>): I;
+/** Reports a LabEvent to onEvent without waiting (normalizeRunLabOptions builds it). */
+type LabEmit = (event: LabEvent) => void;
+export {};