humanish 0.110.3 → 0.111.0

package/dist/study/config.js

@@ -1,207 +1,233 @@
-// The normalized config, in the humanish.lab.v2 spelling: a study composes code primitives, with no
-// hardcoded study kind.
-// A humanish.study.v3 file is rewritten into this spelling first (parse/study-v3.ts), and then must
-// take the route it declares and set no field that route does not read.
+// The study parser: a humanish.study.v3 document into a StudyConfig with the file's own keys.
+// parse/front.ts checks what the document declares before its sections parse (the route, the
+// actor object, the participants or surfaces form the route takes, and the caps keys it reads). The
+// sections parse here, checkStudyConfig runs the checks that read more than one section, and the
+// study must then take the route it declares and set no field that route does not read
+// (warnings.ts). A humanish.lab.v2 document is refused; `humanish migrate` reads it
+// (migrate/v2.ts).
 //
-// Scope (read before trusting field names): the engine routes by
-// subject.source × execution.target (disambiguated by the actor's run kind where both axes
-// collide) and consumes a deliberately small set of fields:
-//   subject.source/repos/appUrl/serve/env/state/clone.{depth,fanout,keep}, actors[0].count,
-//   execution.target + execution.desktop.codexAppServer, scenario.mode,
-//   policies.redactRepos, defaults.open.
-// On the computer-use routes (app-url × e2b-desktop, and clone × e2b-desktop with a
-// computer-use actor), `actors[0].type` selects the actor: it must resolve to a registered
-// computer-use actor, and that descriptor runs the session. Those routes also consume
-// actors[0].{mission,persona,laneFocus.instruction,model,reasoningEffort}, execution.timeoutMs,
-// execution.desktop.{browser,resolution,sandboxTimeoutMs}, and (clone)
-// subject.{serve,env,state,clone.depth}.
-// On the scripted-browser route (app-url × local-or-absent, or clone × e2b-desktop, with a
-// registered scripted-browser actor), `actors[0].type` selects the actor too, and the route
-// consumes scenario.ref (required there, because the committed scenario's browser steps are what the
-// actor executes), actors[0].{persona,count}, and execution.timeoutMs. On the provisioned
-// clone slice it also consumes subject.{repos,serve,env,state,exposure,clone.depth} and
-// execution.desktop.template. actors[0].{mission,laneFocus,model} are inert on that route
-// because no model runs, and most execution.desktop.* fields remain forward-declared (device
-// presets belong to the computer-use route; scripted surfaces are the driver's own desktop/mobile
-// viewports where isMobile/DSF genuinely render via playwright emulation).
-// On the other routes those fields remain forward-declared and are not yet consumed:
-// parseStudy emits a warning listing any such field that is set, so `study show` shows
-// the truth.
+// Scope (read before trusting field names): routeOf derives the route from
+// subject.source × execution.target × the actor's run kind, with `route: shared-world` as the
+// declaration that turns a computer-use composition into a shared world. On the computer-use
+// routes (app-url × e2b-desktop or local, and clone, local-tree or desktop-cli on e2b-desktop with a
+// computer-use actor), `actor.type` must resolve to a registered computer-use actor, and that
+// descriptor runs the session. Those routes consume actor.{mission,persona,model,reasoningEffort},
+// `participants`, `caps`, execution.timeoutMs and execution.desktop.*. The scripted route
+// (app-url × local, or clone × e2b-desktop, with a registered scripted-browser actor) consumes
+// `scenario` (required: its browser steps are what the actor runs), actor.persona and `surfaces`.
+// The terminal route consumes subject.product, `caps` and execution.{terminal,runtimeAuth}.
 //
-// NOTE on actors[0].count: it carries route-specific meanings. Preview route: simCount;
-// scripted-browser route: surface roster {1 = desktop, 2 = desktop + mobile}, default 1 (the
-// defaults-table single-participant row governs; count: 2 is the declared override); computer-use
-// E2B route: the homogeneous fan-out participant count (N identical participants, each its own E2B
-// desktop), capped at 16; the in-process/local-app computer-use route stays single-participant (no
-// E2B to fan out).
-//
-// NOTE on actors[0].lanes / actors[0].roster (computer-use E2B route): a
-// differentiated fan-out roster: each `{ id?, persona?, device?, instruction?, target? }` becomes one
-// independent E2B desktop (`per-lane-worlds`, the default topology). `roster[]` is parser sugar for
-// repeated groups and is normalized into `lanes[]` before the engine sees it. `lanes|roster` XOR
-// `count` (declare a differentiated roster or a homogeneous count, never both); `lanes|roster`
-// XOR `actors[0].laneFocus` (each entry's `instruction` is the roster's steer); `lanes[].device` XOR
-// raw `execution.desktop.resolution`. `execution.concurrency` bounds in-flight participants (default:
-// the participant count, all at once; env HUMANISH_CUA_MAX_CONCURRENCY may only lower it, per invariant
-// 3). On every non-computer-use route normalized `lanes` are inert (warned). subject.clone.fanout
-// is rejected on the computer-use route. `lanes[].target` is app-url × computer-use only: an
-// absolute browser URL this participant opens instead of `subject.appUrl`; it is the generic
-// setup-produced-target handoff, not a service topology primitive.
-//
-// There is deliberately no v1 compatibility: v1 had zero real users. Breaking schema changes
-// bump the version.
+// NOTE on `participants`: a count (preview: the simulated count; computer use: N identical
+// participants, each its own desktop, capped at 16), `{ count, instruction }` (identical
+// participants with one steer), or a list of `{ id?, persona?, device?, instruction?, target? ... }`
+// entries, each its own desktop. A list entry with a `count` is a group that expands into
+// `<id>-01` to `<id>-NN`. A shared world takes a list of at least two. `participants[].device`
+// excludes a raw `execution.desktop.resolution`, and `participants[].target` is app-url computer
+// use only: an absolute browser URL this participant opens in place of `subject.appUrl`.
+// `execution.concurrency` bounds in-flight participants (default: all at once; env
+// HUMANISH_CUA_MAX_CONCURRENCY may only lower it).
 import { isLocalBrowserStudy, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
 import { isRecord } from "../run/type-guards.js";
 import { compositionReason } from "./composition-rules.js";
-import { findUnknownV2Key } from "./keys.js";
-import { parseActors, rosterOf } from "./parse/actors.js";
+import { V2_SCHEMA, V2_UNSUPPORTED_MESSAGE, v2FieldMoves } from "./migrate/v2.js";
+import { parseActorFields, parseActorType, parseParticipantEntries } from "./parse/actors.js";
 import { parseComms, recipientParticipantId } from "./parse/comms.js";
-import { parseDefaults, parseExecution, parsePersonas, parsePolicies, parseReview, parseScenario, } from "./parse/execution.js";
-import { studySpelling, studyToV2 } from "./parse/study-v3.js";
+import { parseCaps, parseDefaults, parseExecution, parsePolicies, parseReview, } from "./parse/execution.js";
+import { ACTOR_REQUIRED, readStudyFront, routeNameReason, } from "./parse/front.js";
 import { parseSubject } from "./parse/subject.js";
 import { invalid, optionalStr, str } from "./parse/values.js";
 import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
-import { ID_PATTERN, V2_SCHEMA, STUDY_SCHEMA, } from "./types.js";
-import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "./validation.js";
-import { forwardDeclaredWarnings, inertFieldLabels } from "./warnings.js";
+import { declaredParticipantCount, participantList } from "./study-fields.js";
+import { ID_PATTERN, STUDY_SCHEMA, } from "./types.js";
+import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, smtpValidationReason, taskProtocolValidationReason, } from "./validation.js";
+import { forwardDeclaredWarnings, inertFieldLabels, inertFieldPaths } from "./warnings.js";
 import { plural } from "../run/text.js";
-/** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
-export const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study, which humanish no longer reads. Convert its file with humanish migrate <path>.";
 /**
  * The package's study parser (src/index.ts) and the one discovery uses: a humanish.study.v3
  * document. It refuses a humanish.lab.v2 one with HUMANISH_STUDY_V2_UNSUPPORTED.
  */
 export function parseStudy(raw) {
-    if (isRecord(raw) && raw.schema === V2_SCHEMA)
+    if (!isRecord(raw))
+        return invalid("A study file must be a YAML object.");
+    if (raw.schema === V2_SCHEMA)
         return {
             ok: false,
             error: { code: "HUMANISH_STUDY_V2_UNSUPPORTED", message: V2_UNSUPPORTED_MESSAGE },
         };
-    return parseStudyDocument(raw);
-}
-/**
- * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
- * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
- * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
- * nothing. migrate's conversion (convert.ts) calls it directly, since it reads v2 files.
- */
-export function parseStudyDocument(raw) {
-    if (!isRecord(raw)) {
-        return invalid("A study file must be a YAML object.");
-    }
-    if (raw.schema === STUDY_SCHEMA)
-        return parseV3(raw);
-    if (raw.schema !== V2_SCHEMA) {
+    if (raw.schema !== STUDY_SCHEMA) {
         return invalid(`The study schema must be ${STUDY_SCHEMA} or ${V2_SCHEMA}.`);
     }
-    return parseV2(raw);
+    return parseStudyV3(raw);
 }
 /**
- * A v3 study parses through the v2 parser, then must take the route it declares and set no field
- * that route does not read. A v2 file gets those fields as a warning instead.
+ * Validate a humanish.study.v3 document into a StudyConfig. Pure: the caller owns file IO. Fields the
+ * route does not read refuse the study; migrate's report mode lists them in `inert` instead.
  */
-function parseV3(raw) {
-    const document = studyToV2(raw);
-    if (!document.ok)
-        return document;
-    const { route, v2, participantSource } = document.value;
-    const spell = (message) => studySpelling(message, route, participantSource);
-    const parsed = parseV2(v2);
-    if (!parsed.ok)
-        return invalid(spell(parsed.error.message));
-    const taken = routeOf(parsed.config);
-    if (taken !== route) {
-        return invalid(`This study declares route: ${route}, but its subject (source: ${parsed.config.subject.source}) and actor (type: ${parsed.config.actors[0]?.type}) take the ${taken} route. Change \`route\`, or change the subject or actor.`);
+export function parseStudyV3(raw, options = {}) {
+    const front = readStudyFront(raw, options.inert === "report");
+    if (!front.ok)
+        return front;
+    const study = parseSections(raw, front.value);
+    if (!study.ok)
+        return study;
+    const checked = checkStudyConfig(study.value);
+    if (!checked.ok)
+        return checked;
+    const { config, warnings } = checked;
+    const { route } = config;
+    const mismatch = routeMismatchReason(config);
+    if (mismatch)
+        return invalid(mismatch);
+    if (options.inert === "report") {
+        return { ok: true, config, warnings, inert: inertFieldPaths(config) };
     }
-    const inert = inertFieldLabels(parsed.config);
+    const inert = inertFieldLabels(config);
     if (inert.length > 0) {
-        return invalid(spell(`route: ${route} does not read ${inert.join(", ")}. Remove ${inert.length === 1 ? "it" : "them"}.`));
+        return invalid(`route: ${route} does not read ${inert.join(", ")}. Remove ${inert.length === 1 ? "it" : "them"}.`);
     }
-    return {
-        ok: true,
-        config: { ...parsed.config, schema: STUDY_SCHEMA },
-        warnings: parsed.warnings.map(spell),
-    };
+    return { ok: true, config, warnings };
+}
+/** Why a config's declared route is not the one its subject and actor take, or undefined. */
+function routeMismatchReason(config) {
+    const taken = routeOf(config);
+    if (taken === config.route)
+        return undefined;
+    return `This study declares route: ${config.route}, but its subject (source: ${config.subject.source}) and actor (type: ${config.actor.type}) take the ${taken} route. Change \`route\`, or change the subject or actor.`;
+}
+/**
+ * Why runStudy refuses a config a library caller passes, or undefined: a humanish.lab.v2 config,
+ * one that still sets a StudyConfig field of humanish 0.110, one with no `actor` object, and one
+ * whose `route` is not the route its subject and actor take, with parseStudy's message. A planner
+ * reads only the v3 fields, so a budget left in `execution.caps` would otherwise run uncapped.
+ */
+export function libraryConfigRefusal(config) {
+    const raw = config;
+    if (!isRecord(raw))
+        return undefined;
+    if (raw.schema === V2_SCHEMA)
+        return { code: "HUMANISH_STUDY_V2_UNSUPPORTED", message: V2_UNSUPPORTED_MESSAGE };
+    const moves = v2FieldMoves(raw);
+    if (moves.length > 0)
+        return {
+            code: "HUMANISH_STUDY_V2_UNSUPPORTED",
+            message: `This StudyConfig sets fields that humanish 0.111.0 renamed: ${moves.join("; ")}. Set the humanish.study.v3 fields, or parse the study file with parseStudy. The 0.111.0 release notes list each renamed field.`,
+        };
+    if (!isRecord(raw.actor))
+        return { code: "HUMANISH_STUDY_INVALID", message: ACTOR_REQUIRED };
+    const message = routeNameReason(raw.route) ?? routeMismatchReason(config);
+    return message === undefined ? undefined : { code: "HUMANISH_STUDY_INVALID", message };
 }
-function parseV2(raw) {
-    const unknownKey = findUnknownV2Key(raw);
-    if (unknownKey)
-        return invalid(unknownKey);
+// Each section in a fixed order, so a file with more than one error always reports the same one
+// first. migrate's checkV2 reads a v2 file's sections in this order too.
+function parseSections(raw, front) {
     const id = str(raw.id);
     if (!id || !ID_PATTERN.test(id)) {
         return invalid("The study id must be a public-safe token starting with a letter or digit (/^[A-Za-z0-9][A-Za-z0-9_.-]*$/).");
     }
-    const subjectResult = parseSubject(raw.subject);
-    if (!subjectResult.ok) {
-        return subjectResult;
-    }
-    const actorsResult = parseActors(raw.actors);
-    if (!actorsResult.ok) {
-        return actorsResult;
-    }
-    const executionResult = parseExecution(raw.execution);
-    if (!executionResult.ok) {
-        return executionResult;
-    }
-    const config = {
-        schema: V2_SCHEMA,
-        id,
-        ...optionalStr("title", raw.title),
-        ...optionalStr("description", raw.description),
-        subject: subjectResult.value,
-        actors: actorsResult.value,
-        ...(executionResult.value ? { execution: executionResult.value } : {}),
-    };
-    const personas = parsePersonas(raw.personas);
-    if (personas)
-        config.personas = personas;
-    const scenarioResult = parseScenario(raw.scenario);
-    if (!scenarioResult.ok) {
-        return scenarioResult;
-    }
-    if (scenarioResult.value)
-        config.scenario = scenarioResult.value;
+    const subject = parseSubject(raw.subject);
+    if (!subject.ok)
+        return subject;
+    const type = parseActorType(front.actor, "actor");
+    if (!type.ok)
+        return type;
+    const participants = parseParticipants(raw.participants, front.participants);
+    if (!participants.ok)
+        return participants;
+    const fields = parseActorFields(front.actor, "actor");
+    if (!fields.ok)
+        return fields;
+    const execution = parseExecution(raw.execution);
+    if (!execution.ok)
+        return execution;
+    const caps = parseCaps(raw.caps);
+    if (!caps.ok)
+        return caps;
     if (isRecord(raw.policies) &&
         raw.policies.mediaPermission !== undefined &&
         raw.policies.mediaPermission !== "prompt" &&
         raw.policies.mediaPermission !== "granted") {
         return invalid("`policies.mediaPermission` must be `prompt` (the participant answers the browser's own dialog) or `granted`.");
     }
-    const policiesResult = parsePolicies(raw.policies);
-    if (!policiesResult.ok)
-        return policiesResult;
-    if (policiesResult.value)
-        config.policies = policiesResult.value;
-    const reviewResult = parseReview(raw.review);
-    if (!reviewResult.ok)
-        return reviewResult;
-    if (reviewResult.value)
-        config.review = reviewResult.value;
-    if (raw.defaults !== undefined && isRecord(raw.defaults) && raw.defaults.open !== undefined) {
+    const policies = parsePolicies(raw.policies);
+    if (!policies.ok)
+        return policies;
+    const review = parseReview(raw.review);
+    if (!review.ok)
+        return review;
+    if (isRecord(raw.defaults) && raw.defaults.open !== undefined) {
         if (typeof raw.defaults.open !== "boolean")
             return invalid("`defaults.open` must be true or false.");
     }
     const defaults = parseDefaults(raw.defaults);
-    if (defaults)
-        config.defaults = defaults;
-    const commsResult = parseComms(raw.comms);
-    if (!commsResult.ok)
-        return commsResult;
-    if (commsResult.value)
-        config.comms = commsResult.value;
-    if (config.comms?.email?.smtp && config.subject.topology === "shared-world") {
-        return invalid("SMTP capture is not supported yet for shared-world studies. Use the default per-lane-worlds topology for SMTP, or configure supported HTTP email capture for concurrent shared-world studies.");
+    const comms = parseComms(raw.comms);
+    if (!comms.ok)
+        return comms;
+    const mode = raw.mode === "dry-run" || raw.mode === "live" ? raw.mode : undefined;
+    const { surfaces } = front;
+    const scenario = str(raw.scenario);
+    return {
+        ok: true,
+        value: {
+            schema: STUDY_SCHEMA,
+            id,
+            ...optionalStr("title", raw.title),
+            ...optionalStr("description", raw.description),
+            route: front.route,
+            ...(mode === undefined ? {} : { mode }),
+            subject: subject.value,
+            actor: { type: type.value, ...fields.value },
+            ...(participants.value === undefined ? {} : { participants: participants.value }),
+            ...(surfaces === undefined ? {} : { surfaces }),
+            ...(caps.value === undefined ? {} : { caps: caps.value }),
+            ...(execution.value === undefined ? {} : { execution: execution.value }),
+            ...(scenario === undefined ? {} : { scenario }),
+            ...(policies.value === undefined ? {} : { policies: policies.value }),
+            ...(review.value === undefined ? {} : { review: review.value }),
+            ...(defaults === undefined ? {} : { defaults }),
+            ...(comms.value === undefined ? {} : { comms: comms.value }),
+        },
+    };
+}
+// `participants` in the form the file wrote it. readStudyFront has checked the form against the
+// route and expanded each list entry that has a count; the entries parse here, each named by the
+// `participants` entry it came from. An instruction that is not a non-empty string is dropped, as
+// the v2 parser drops it.
+function parseParticipants(raw, read) {
+    if (read.entries !== undefined) {
+        const { source } = read;
+        return parseParticipantEntries(read.entries, {
+            list: "participants",
+            entry: (index) => `participants[${source[index] ?? index}]`,
+        });
     }
+    if (typeof raw === "number")
+        return { ok: true, value: read.count };
+    if (!isRecord(raw))
+        return { ok: true, value: undefined };
+    const instruction = str(read.instruction);
+    return {
+        ok: true,
+        value: {
+            ...(read.count === undefined ? {} : { count: read.count }),
+            ...(instruction === undefined ? {} : { instruction }),
+        },
+    };
+}
+/**
+ * The checks that read more than one section of a parsed config, and the defaults they fill:
+ * shared-world `execution.concurrency`, `comms.email.recipients` and the local browser's defaults.
+ */
+function checkStudyConfig(config) {
+    const smtpReason = smtpValidationReason(config);
+    if (smtpReason)
+        return invalid(smtpReason);
     const mediaReason = desktopMediaValidationReason(config);
     if (mediaReason)
         return invalid(mediaReason);
     const outputLimitReason = outputTokenLimitValidationReason(config);
     if (outputLimitReason)
         return invalid(outputLimitReason);
-    const scenarioCapsReason = scenarioCapsValidationReason(config);
-    if (scenarioCapsReason)
-        return invalid(scenarioCapsReason);
     // All-parallel default: a multi-participant study that does not declare execution.concurrency
     // runs every participant at once; the declared field is a cap the author chose, never a mode.
     // Independent computer-use participants resolve that default from the final participant count
@@ -209,7 +235,7 @@ function parseV2(raw) {
     // world's roster is fixed, so its default is filled here for the envelopes and warnings that read
     // the parsed config.
     {
-        const participantCount = rosterOf(config.actors[0])?.length ?? config.actors[0]?.count ?? 1;
+        const participantCount = participantList(config)?.length ?? declaredParticipantCount(config) ?? 1;
         if (participantCount > 1 &&
             config.execution?.concurrency === undefined &&
             isSharedWorldComposition(config)) {

package/dist/study/discover.d.ts

@@ -1,5 +1,5 @@
 import type { ActorPersonaRef } from "../actors/contract.js";
-import { type StudyConfig } from "./types.js";
+import type { StudyConfig } from "./types.js";
 declare const STUDY_LIST_SCHEMA = "humanish.study-list.v1";
 declare const STUDY_SHOW_SCHEMA = "humanish.study-show.v1";
 type StudyOrigin = "committed" | "ignored" | "explicit";

package/dist/study/discover.js

@@ -5,7 +5,7 @@ import { lstat, open, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { parse } from "yaml";
 import { parseStudy } from "./config.js";
-import { V2_SCHEMA } from "./types.js";
+import { V2_SCHEMA } from "./migrate/v2.js";
 import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
 import { isNodeError } from "../run/type-guards.js";
 import { studyFileCandidates, STUDY_DIRECTORIES } from "./files.js";

package/dist/study/doctor.js

@@ -9,6 +9,7 @@ import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/codex-admission.js";
 import { cli } from "../cli/invocation.js";
+import { actorOf } from "./study-fields.js";
 /** A ready row's message, with the schema values the launch recorded. */
 function readyMessage(message, readiness) {
     const additions = protocolAdditionsWarning(readiness.cliVersion, readiness.protocolAdditions);
@@ -151,7 +152,7 @@ export async function studySetupChecks(args) {
         {
             name: "study route",
             ok: true,
-            message: `${config.id}: ${config.actors[0]?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
+            message: `${config.id}: ${actorOf(config)?.type ?? "synthetic"} / ${route} / ${dryRun ? "dry-run (no live participant)" : "live"}`,
         },
     ];
     if (dryRun)
@@ -246,16 +247,16 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
         ];
     }
     if ((route !== "computer-use" && route !== "shared-world") ||
-        config.actors[0]?.type !== "local-agent")
+        actorOf(config)?.type !== "local-agent")
         return [];
-    const choice = config.actors[0]?.localAgent ?? "codex";
+    const choice = actorOf(config)?.localAgent ?? "codex";
     const agent = args.agents.find((entry) => entry.id === choice);
     if (local)
         return [await localCodexParticipantCheck({ env: args.env, readiness: checkAccount })];
     // A signed-in hosted Codex gets the operator handshake; its sign-in status alone does not show
     // that the operator's config, release and model admit a launch.
     if (choice === "codex" && agent?.authStatus === "authenticated")
-        return [await hostedCodexParticipantCheck(args, config.actors[0])];
+        return [await hostedCodexParticipantCheck(args, actorOf(config))];
     const outdated = agent === undefined ? undefined : localAgentVersionRefusal(agent);
     return [
         {