humanish 0.110.2 → 0.110.4

package/dist/study/summary.js

@@ -18,7 +18,7 @@ import { inspectStudyManifest } from "./discover.js";
 import { isComputerUseComposition } from "./routing.js";
 import { probeKeySources } from "../keys/key-resolution.js";
 import { receivingRequiredKey } from "../comms/setup.js";
-import { rosterOf } from "./parse/actors.js";
+import { actorOf, participantList, declaredParticipantCount, capsOf } from "./study-fields.js";
 export const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
 /**
  * The effort every participant will run at, or `"per-lane"` when they differ. A participant that declares nothing
@@ -26,10 +26,8 @@ export const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
  * reported as the resolved value, exactly as `model` reports its default rather than hiding it.
  */
 function reasoningEffortOf(config) {
-    const actors = config.actors;
-    const actor = actors?.[0];
-    const fallback = actor?.reasoningEffort ?? DEFAULT_OPENAI_CU_REASONING_EFFORT;
-    const roster = rosterOf(actor) ?? [];
+    const fallback = actorOf(config)?.reasoningEffort ?? DEFAULT_OPENAI_CU_REASONING_EFFORT;
+    const roster = participantList(config) ?? [];
     const resolved = new Set(roster.map((entry) => entry.reasoningEffort ?? fallback));
     if (resolved.size > 1)
         return "per-lane";
@@ -49,15 +47,14 @@ function subjectOf(config) {
 }
 /** How many participants, and who; collapsed when they are all the same persona. */
 function participantsOf(config) {
-    const actors = config.actors;
-    const actor = actors?.[0];
+    const actor = actorOf(config);
     if (actor === undefined)
         return undefined;
-    const rosterPersonas = (rosterOf(actor) ?? [])
+    const rosterPersonas = (participantList(config) ?? [])
         .map((entry) => entry.persona)
         .filter((persona) => typeof persona === "string");
     const personas = rosterPersonas.length > 0 ? rosterPersonas : actor.persona === undefined ? [] : [actor.persona];
-    const count = actor.count ?? rosterOf(actor)?.length ?? personas.length ?? 1;
+    const count = declaredParticipantCount(config) ?? participantList(config)?.length ?? personas.length ?? 1;
     const unique = [...new Set(personas)];
     if (unique.length === 0)
         return `${count} participant${count === 1 ? "" : "s"}`;
@@ -66,10 +63,10 @@ function participantsOf(config) {
     return unique.length === 1 ? `${count} × ${unique[0]}` : unique.join(" · ");
 }
 /** The computer-use caps; `execution.caps` is inert on other routes, so none is drawn there. */
-function capsOf(config) {
+function summaryCapsOf(config) {
     if (!isComputerUseComposition(config))
         return {};
-    const caps = config.execution?.caps;
+    const caps = capsOf(config, "computer-use");
     return {
         ...(typeof caps?.maxUsd === "number" ? { laneUsd: caps.maxUsd } : {}),
         ...(typeof caps?.maxTotalUsd === "number" ? { studyUsd: caps.maxTotalUsd } : {}),
@@ -84,7 +81,6 @@ export async function readStudySummary(cwd, study, options = {}) {
     if (inspected === null || !inspected.ok || inspected.config === undefined)
         return null;
     const config = inspected.config;
-    const actors = config.actors;
     const route = routeOf(inspected.config);
     let keysReady;
     let missingKeys;
@@ -128,7 +124,7 @@ export async function readStudySummary(cwd, study, options = {}) {
     // Computed once: a test-then-use pair reads as though the two calls could differ.
     const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route);
     const subject = subjectOf(config);
-    const participants = participantsOf(config);
+    const participants = participantsOf(inspected.config);
     const runtime = options.checkKeys === true && isLocalBrowserStudy(inspected.config)
         ? await localRuntimeStatus({
             ...(options.env ? { env: options.env } : {}),
@@ -138,7 +134,7 @@ export async function readStudySummary(cwd, study, options = {}) {
         : undefined;
     const participantReadiness = options.checkKeys === true &&
         isLocalBrowserStudy(inspected.config) &&
-        inspected.config.actors[0]?.type === "local-agent"
+        actorOf(inspected.config)?.type === "local-agent"
         ? await localCodexParticipantCheck({ env: options.env ?? process.env })
         : undefined;
     return {
@@ -165,9 +161,9 @@ export async function readStudySummary(cwd, study, options = {}) {
         ...(typeof config.description === "string" ? { description: config.description.trim() } : {}),
         ...(subject === undefined ? {} : { subject }),
         ...(participants === undefined ? {} : { participants }),
-        model: actors?.[0]?.model ?? DEFAULT_OPENAI_CU_MODEL,
-        reasoningEffort: reasoningEffortOf(config),
-        caps: capsOf(inspected.config),
+        model: actorOf(inspected.config)?.model ?? DEFAULT_OPENAI_CU_MODEL,
+        reasoningEffort: reasoningEffortOf(inspected.config),
+        caps: summaryCapsOf(inspected.config),
         ...(keysReady === undefined ? {} : { keysReady }),
         ...(missingKeys === undefined ? {} : { missingKeys }),
         ...(planRefusal === undefined ? {} : { planRefusal }),

package/dist/study/types.d.ts

@@ -2,6 +2,7 @@ import { type StudyAnalysis } from "../analysis/automatic-config.js";
 import type { StudyTask } from "./tasks.js";
 import type { DwellWindow, StopWhen } from "../actors/stop-conditions.js";
 import { type ReasoningEffort } from "../actors/reasoning-effort.js";
+import type { StudyRoute } from "./routing.js";
 export declare const V2_SCHEMA = "humanish.lab.v2";
 /** The study format: it declares its route, one actor, its participants and one caps block. */
 export declare const STUDY_SCHEMA = "humanish.study.v3";
@@ -805,6 +806,45 @@ export interface StudyConfig {
     defaults?: StudyDefaults;
     comms?: StudyComms;
 }
+/**
+ * A humanish.study.v3 file as src/study/parse/study.ts reads it: the declared route, one actor, its
+ * participants and one caps block. It has the keys the file has. parseStudy still returns the
+ * StudyConfig above.
+ */
+export interface StudyV3 {
+    schema: typeof STUDY_SCHEMA;
+    id: string;
+    title?: string;
+    description?: string;
+    route: StudyRoute;
+    /** Absent: a dry run. */
+    mode?: StudyScenarioMode;
+    subject: Omit<StudySubject, "topology">;
+    actor: Omit<StudyActor, "count" | "lanes" | "laneFocus">;
+    /** Preview, computer-use and shared-world, in the form the file used. */
+    participants?: StudyParticipants;
+    /** Scripted only. */
+    surfaces?: StudySurfaces;
+    /** The caps keys the route reads. */
+    caps?: StudyScenarioCaps;
+    execution?: Omit<StudyExecution, "caps">;
+    /** Scripted: a committed scenario id or path. */
+    scenario?: string;
+    policies?: StudyPolicies;
+    review?: StudyReview;
+    defaults?: StudyDefaults;
+    comms?: StudyComms;
+}
+/**
+ * A count, a count with one instruction for every participant, or a list. A list entry with a
+ * `count` is expanded into its participants, `<id>-01` to `<id>-NN`.
+ */
+type StudyParticipants = number | StudyParticipantGroup | StudyParticipantEntry[];
+interface StudyParticipantGroup {
+    count?: number;
+    instruction?: string;
+}
+type StudySurfaces = readonly ["desktop"] | readonly ["desktop", "mobile"];
 interface StudyParseSuccess {
     ok: true;
     config: StudyConfig;

package/dist/study/url-credentials.js

@@ -2,6 +2,7 @@
 // library caller's config skips the parser that refuses these first.
 import { rosterOf } from "./parse/actors.js";
 import { entryCredentialReason, urlCredentialReason } from "./parse/url-credentials.js";
+import { actorsOf } from "./study-fields.js";
 /**
  * The first URL in `config` that carries a credential, with why: the subject's app, serve and
  * public surface URLs, and each participant's target and entry.
@@ -16,7 +17,7 @@ export function studyUrlCredentialReason(config) {
             ? undefined
             : urlCredentialReason("subject.serve.url", subject.serve.url),
         ...(subject.product?.publicSurfaces ?? []).map((surface) => () => urlCredentialReason("subject.product.publicSurfaces", surface)),
-        ...config.actors.flatMap((actor) => (rosterOf(actor) ?? []).flatMap((participant, index) => [
+        ...actorsOf(config).flatMap((actor) => (rosterOf(actor) ?? []).flatMap((participant, index) => [
             () => participant.target === undefined
                 ? undefined
                 : urlCredentialReason(`participants[${index}].target`, participant.target),

package/dist/study/validation.d.ts

@@ -13,6 +13,8 @@ export declare function computerUseValidationReason(config: StudyConfig): string
  * runStudyWith takes a config that skipped the parser.
  */
 export declare function sharedWorldValidationReason(config: StudyConfig): string | null;
+/** SMTP capture runs only where each participant has its own world, so a shared world refuses it. */
+export declare function smtpValidationReason(config: StudyConfig): string | undefined;
 /**
  * Declared capture devices must be implemented by the selected execution route.
  * Unsupported backends pass false when called directly, where the declared

package/dist/study/validation.js

@@ -1,8 +1,9 @@
 import { isMaxOutputTokens } from "../actors/output-token-limit.js";
-import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN, focusOf, rosterOf, } from "./parse/actors.js";
+import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN, focusOf } from "./parse/actors.js";
 import { isHttpUrl, isLoopbackUrl } from "./parse/subject.js";
 import { declaredTargets } from "./plan-participants.js";
 import { actorResolvesToComputerUse, computerUseParticipantCount, MAX_COMPUTER_USE_PARTICIPANTS, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
+import { actorOf, actorsOf, participantList, declaredParticipantCount, declaresSharedWorld, } from "./study-fields.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
  * message, or null when valid. The parser enforces it, and runStudyWith checks it again for a config
@@ -10,8 +11,8 @@ import { actorResolvesToComputerUse, computerUseParticipantCount, MAX_COMPUTER_U
  * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
  */
 export function computerUseValidationReason(config) {
-    const actor = config.actors[0];
-    const roster = rosterOf(actor);
+    const actor = actorOf(config);
+    const roster = participantList(config);
     const structuralReason = rosterStructuralValidationReason(config);
     if (structuralReason) {
         return structuralReason;
@@ -20,10 +21,10 @@ export function computerUseValidationReason(config) {
     // inert-warned). Fan-out is declared via `actors[0].count` or `actors[0].lanes`;
     // subject.clone.fanout never applied here.
     if (config.subject.clone?.fanout !== undefined) {
-        return "`subject.clone.fanout` is not used on the computer-use route: declare fan-out with actors[0].count (homogeneous) or actors[0].lanes (a roster of participants). (No current route reads clone.fanout.)";
+        return "`subject.clone.fanout` is not used on the computer-use route: declare fan-out with participants (homogeneous) or participants (a roster of participants). (No current route reads clone.fanout.)";
     }
     if (roster !== undefined) {
-        if (actor?.count !== undefined) {
+        if (declaredParticipantCount(config) !== undefined) {
             return "Set either `actors[0].count` (identical participants) or `actors[0].lanes` (a roster of distinct participants), not both.";
         }
         if (focusOf(actor) !== undefined) {
@@ -31,18 +32,18 @@ export function computerUseValidationReason(config) {
         }
         if (config.execution?.desktop?.resolution !== undefined &&
             roster.some((entry) => entry.device !== undefined)) {
-            return "actors[0].lanes[].device and a raw execution.desktop.resolution are mutually exclusive: a per-participant device preset and a single hand-set resolution cannot both govern participant geometry.";
+            return "participants[].device and a raw execution.desktop.resolution are mutually exclusive: a per-participant device preset and a single hand-set resolution cannot both govern participant geometry.";
         }
         const targeted = roster.filter((entry) => entry.target !== undefined);
         if (targeted.length > 0) {
             if (config.subject.source !== "app-url") {
-                return "`actors[0].lanes[].target` works only on app-url computer-use studies. Clone, shared-world and local-app studies set each participant's entry URL themselves; remove `target`.";
+                return "`participants[].target` works only on app-url computer-use studies. Clone, shared-world and local-app studies set each participant's entry URL themselves; remove `target`.";
             }
             if (roster.some((entry) => entry.entry !== undefined)) {
-                return "actors[0].lanes[].target and actors[0].lanes[].entry are mutually exclusive: target is an app-url fan-out browser URL; entry is a shared-world same-origin participant path.";
+                return "participants[].target and participants[].entry are mutually exclusive: target is an app-url fan-out browser URL; entry is a shared-world same-origin participant path.";
             }
             if (targeted.length !== roster.length) {
-                return "When any actors[0].lanes[].target is declared, every participant in the roster must declare target; this keeps the setup-produced target contract explicit and prevents accidental mixed worlds.";
+                return "When any participants[].target is declared, every participant in the roster must declare target; this keeps the setup-produced target contract explicit and prevents accidental mixed worlds.";
             }
         }
     }
@@ -59,8 +60,8 @@ export function computerUseValidationReason(config) {
     if (participantCount > 1 &&
         config.policies?.allowPublicTargets === true &&
         declaredTargets(config).length === 0 &&
-        config.subject.topology !== "shared-world") {
-        return "`policies.allowPublicTargets` with more than one participant sends them all to one public app, which is a shared world. Set `subject.topology: shared-world` to run them together there, give each `actors[0].lanes[]` entry its own `target`, or run one participant.";
+        !declaresSharedWorld(config)) {
+        return "`policies.allowPublicTargets` with more than one participant sends them all to one public app, which is a shared world. Set `route: shared-world` to run them together there, give each `participants[]` entry its own `target`, or run one participant.";
     }
     return null;
 }
@@ -69,15 +70,15 @@ export function computerUseValidationReason(config) {
  * public TypeScript/JavaScript API instead of parseStudy.
  */
 function rosterStructuralValidationReason(config) {
-    const roster = rosterOf(config.actors[0]);
+    const roster = participantList(config);
     const seenIds = new Set();
     if (roster !== undefined) {
         if (!Array.isArray(roster) || roster.length === 0) {
-            return "actors[0].lanes must be a non-empty array when set.";
+            return "participants must be a non-empty array when set.";
         }
         for (const [index, entry] of roster.entries()) {
             if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-                return `actors[0].lanes[${index}] must be an object.`;
+                return `participants[${index}] must be an object.`;
             }
             const id = entry.id;
             if (id === undefined) {
@@ -86,10 +87,10 @@ function rosterStructuralValidationReason(config) {
             if (typeof id !== "string" ||
                 !PARTICIPANT_ID_PATTERN.test(id) ||
                 id.length > PARTICIPANT_ID_MAX_CHARS) {
-                return `actors[0].lanes[${index}].id must be a public-safe path token matching ${PARTICIPANT_ID_PATTERN} and at most ${PARTICIPANT_ID_MAX_CHARS} chars.`;
+                return `participants[${index}].id must be a public-safe path token matching ${PARTICIPANT_ID_PATTERN} and at most ${PARTICIPANT_ID_MAX_CHARS} chars.`;
             }
             if (seenIds.has(id)) {
-                return `actors[0].lanes ids must be unique (duplicate "${id}").`;
+                return `participants ids must be unique (duplicate "${id}").`;
             }
             seenIds.add(id);
         }
@@ -120,32 +121,38 @@ function provisionedSharedWorldStructureReason(config) {
         return structuralReason;
     }
     if (config.subject.source !== "clone" && config.subject.source !== "local-tree") {
-        return "`subject.topology: shared-world` needs `subject.source: clone` or `local-tree`, which humanish serves as one seeded app every participant uses, or `app-url` for a public deployment you own.";
+        return "`route: shared-world` needs `subject.source: clone` or `local-tree`, which humanish serves as one seeded app every participant uses, or `app-url` for a public deployment you own.";
     }
     if (config.execution?.target !== "e2b-desktop") {
-        return "`subject.topology: shared-world` requires `execution.target: e2b-desktop`: the role participants drive hosted desktop browsers against one in-sandbox app.";
+        return "`route: shared-world` requires `execution.target: e2b-desktop`: the role participants drive hosted desktop browsers against one in-sandbox app.";
     }
-    if (!actorResolvesToComputerUse(config.actors[0]?.type)) {
-        return `\`subject.topology: shared-world\` requires a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}); each role participant runs a computer-use session.`;
+    if (!actorResolvesToComputerUse(actorOf(config)?.type)) {
+        return `\`route: shared-world\` requires a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}); each role participant runs a computer-use session.`;
     }
     const serve = config.subject.serve;
     if (!serve) {
-        return "`subject.topology: shared-world` needs `subject.serve` (start and url): humanish starts one copy of the app in the sandbox, and every participant uses it.";
+        return "`route: shared-world` needs `subject.serve` (start and url): humanish starts one copy of the app in the sandbox, and every participant uses it.";
     }
-    const roster = rosterOf(config.actors[0]);
+    const roster = participantList(config);
     if (!roster || roster.length < 2) {
-        return "`subject.topology: shared-world` needs an `actors[0].lanes` roster of at least 2 participants: with one participant there is nobody to interact with.";
+        return "`route: shared-world` needs a `participants` list of at least 2 participants: with one participant there is nobody to interact with.";
     }
     if (!config.subject.state?.checkpoint || config.subject.state.checkpoint.length === 0) {
-        return "`subject.topology: shared-world` needs at least one read-only `subject.state.checkpoint` probe: the checkpoints are how the run shows that participants changed the shared app.";
+        return "`route: shared-world` needs at least one read-only `subject.state.checkpoint` probe: the checkpoints are how the run shows that participants changed the shared app.";
     }
     for (const entry of roster) {
         if (entry.entry !== undefined && resolveEntryUrl(serve.url, entry.entry) === null) {
-            return `actors[0].lanes role "${entry.id ?? "(unnamed)"}".entry must resolve same-origin (loopback) with subject.serve.url (${serve.url}); got "${entry.entry}".`;
+            return `participants role "${entry.id ?? "(unnamed)"}".entry must resolve same-origin (loopback) with subject.serve.url (${serve.url}); got "${entry.entry}".`;
         }
     }
     return null;
 }
+/** SMTP capture runs only where each participant has its own world, so a shared world refuses it. */
+export function smtpValidationReason(config) {
+    return config.comms?.email?.smtp && declaresSharedWorld(config)
+        ? "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."
+        : undefined;
+}
 /**
  * Declared capture devices must be implemented by the selected execution route.
  * Unsupported backends pass false when called directly, where the declared
@@ -153,9 +160,7 @@ function provisionedSharedWorldStructureReason(config) {
  */
 export function desktopMediaValidationReason(config, supportsMedia = isComputerUseComposition(config)) {
     if (config.execution?.desktop?.recording !== undefined &&
-        (!supportsMedia ||
-            config.subject.topology === "shared-world" ||
-            config.subject.source === "local-app")) {
+        (!supportsMedia || declaresSharedWorld(config) || config.subject.source === "local-app")) {
         return "execution.desktop.recording is supported only for computer-use participants on independent desktops. Remove the declaration or select a supported route.";
     }
     const media = config.execution?.desktop?.media;
@@ -164,7 +169,7 @@ export function desktopMediaValidationReason(config, supportsMedia = isComputerU
     if (media.microphone !== undefined && media.microphone.source !== "speech") {
         return "execution.desktop.media.microphone.source must be speech. Microphone source-file injection is unsupported.";
     }
-    if (config.subject.topology === "shared-world") {
+    if (declaresSharedWorld(config)) {
         return "execution.desktop.media is unsupported on shared-world routes; declared capture devices would not be provisioned. Use independent computer-use browser participants or remove the declaration.";
     }
     if (!supportsMedia ||
@@ -176,7 +181,7 @@ export function desktopMediaValidationReason(config, supportsMedia = isComputerU
         return "execution.desktop.media requires Chrome or Chromium; Firefox cannot receive the declared synthetic capture device. Set execution.desktop.browser: chrome or chromium.";
     }
     if (media.microphone !== undefined) {
-        if (config.actors.some((actor) => actor.type !== "local-agent" ||
+        if (actorsOf(config).some((actor) => actor.type !== "local-agent" ||
             (actor.localAgent !== undefined && actor.localAgent !== "codex"))) {
             return "Participant speech currently requires local-agent with Codex, on a local or hosted desktop.";
         }
@@ -194,7 +199,7 @@ export function receivingEmailValidationReason(config) {
         !["app-url", "clone", "local-tree"].includes(config.subject.source)) {
         return "Real email receiving requires a hosted computer-use browser study with an app-url, clone, or local-tree subject. Scripted, terminal, desktop-cli and local-app routes are unsupported.";
     }
-    if (config.actors.some((actor) => actor.type === "local-agent")) {
+    if (actorsOf(config).some((actor) => actor.type === "local-agent")) {
         return "Real email receiving is unavailable for local-agent: its host process does not isolate the inbox management credential. Use a hosted first-party computer-use actor.";
     }
     return undefined;
@@ -202,14 +207,14 @@ export function receivingEmailValidationReason(config) {
 /** Refuse task declarations that the selected execution path would discard.
  * Direct runners pass their actual support rather than trusting the config's dispatch shape. */
 export function taskProtocolValidationReason(config, supportsTasks = isComputerUseComposition(config) && !isSharedWorldComposition(config)) {
-    for (const [index, actor] of config.actors.entries()) {
+    for (const [index, actor] of actorsOf(config).entries()) {
         if (actor.tasks === undefined)
             continue;
         if (index > 0) {
             return `actors[${index}].tasks is unsupported: current runners consume only actors[0]. Use the first actor's computer-use participants for a task protocol.`;
         }
         if (!supportsTasks) {
-            return "actors[0].tasks is unsupported on this execution path. Task protocols require the computer-use route, with one world per participant; shared-world, terminal-product, scripted-browser and synthetic routes do not consume them. Remove tasks only if a mission-only study is intended.";
+            return "actor.tasks is unsupported on this execution path. Task protocols require the computer-use route, with one world per participant; shared-world, terminal-product, scripted-browser and synthetic routes do not consume them. Remove tasks only if a mission-only study is intended.";
         }
     }
     return null;
@@ -248,15 +253,15 @@ export function scenarioCapsValidationReason(config) {
 }
 /** Refuse a claimed output bound when the route cannot pass it to the first-party provider. */
 export function outputTokenLimitValidationReason(config) {
-    const actor = config.actors[0];
+    const actor = actorOf(config);
     if (actor?.maxOutputTokens === undefined)
         return null;
     if (!isMaxOutputTokens(actor.maxOutputTokens))
-        return "actors[0].maxOutputTokens must be a positive safe integer.";
+        return "actor.maxOutputTokens must be a positive safe integer.";
     if (actor.type !== "openai-computer-use" ||
         !isComputerUseComposition(config) ||
         config.subject.source === "local-app") {
-        return "actors[0].maxOutputTokens is supported only by first-party OpenAI computer-use routes; terminal, local-agent, scripted and custom in-process routes cannot enforce it.";
+        return "actor.maxOutputTokens is supported only by first-party OpenAI computer-use routes; terminal, local-agent, scripted and custom in-process routes cannot enforce it.";
     }
     return null;
 }
@@ -270,7 +275,7 @@ export function outputTokenLimitValidationReason(config) {
 function sharedWorldConcurrencyReason(config) {
     // Direct library callers skip the parser, so an omitted value defaults here exactly as the
     // route does: to the participant count. A missing roster reads as 0 and is refused.
-    const participants = rosterOf(config.actors[0])?.length ?? 0;
+    const participants = participantList(config)?.length ?? 0;
     const concurrency = config.execution?.concurrency ?? participants;
     if (concurrency >= 2)
         return null;
@@ -327,12 +332,12 @@ export function externalPublicSharedWorldValidationReason(config) {
     if (config.execution?.target !== "e2b-desktop") {
         return "the external-public shared-world route requires `execution.target: e2b-desktop`: the role participants drive hosted desktop browsers against the one public deployment.";
     }
-    if (!actorResolvesToComputerUse(config.actors[0]?.type)) {
+    if (!actorResolvesToComputerUse(actorOf(config)?.type)) {
         return `the external-public shared-world route requires a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}); each role participant runs a computer-use session.`;
     }
-    const roster = rosterOf(config.actors[0]);
+    const roster = participantList(config);
     if (!roster || roster.length < 2) {
-        return "the external-public shared-world route requires an `actors[0].lanes` roster of at least 2 roles (a single-participant shared world proves no shared session).";
+        return "the external-public shared-world route requires a `participants` list of at least 2 roles (a single-participant shared world proves no shared session).";
     }
     const sharedWorldConcurrency = sharedWorldConcurrencyReason(config);
     if (sharedWorldConcurrency)
@@ -367,7 +372,7 @@ export function externalPublicSharedWorldValidationReason(config) {
         return "`subject.clone` and `subject.repos` do not apply to an external-public shared-world study: the participants use the public deployment, so nothing is cloned. Remove them.";
     }
     if (roster.some((entry) => entry.entry !== undefined)) {
-        return "`actors[0].lanes[].entry` (the loopback same-origin participant path) is forbidden on the external-public shared-world route: there is no harness-served serve.url to resolve it against; participants open the public appUrl and reach the shared session through the real UI.";
+        return "`participants[].entry` (the loopback same-origin participant path) is forbidden on the external-public shared-world route: there is no harness-served serve.url to resolve it against; participants open the public appUrl and reach the shared session through the real UI.";
     }
     const hostEntries = roster.filter((entry) => entry.host === true);
     if (hostEntries.length !== 1) {

package/dist/study/warnings.js

@@ -2,6 +2,7 @@ import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldCo
 import { declaredParticipantIds } from "./plan-participants.js";
 import { addressedRecipients } from "./parse/comms.js";
 import { focusOf, rosterOf } from "./parse/actors.js";
+import { actorsOf, participantList, declaredParticipantCount, scenarioRefOf, } from "./study-fields.js";
 // The computer-use and terminal routes consume mission/persona/model and laneFocus.instruction (they
 // compose the agent prompt and bundle provenance); laneFocus.id/label stay inert. On the computer-use
 // E2B route actors[0].lanes is consumed (the fan-out roster).
@@ -250,7 +251,7 @@ const CONFIG_ROWS = [
     // everywhere else.
     {
         field: "scenario.ref",
-        applies: (config, routes) => Boolean(config.scenario?.ref) && !routes.scripted,
+        applies: (config, routes) => Boolean(scenarioRefOf(config)) && !routes.scripted,
     },
     { field: "scenario.inline", applies: (config) => Boolean(config.scenario?.inline) },
     // review.{scoring,milestones,vocabulary} stay forward-declared on every route.
@@ -306,7 +307,7 @@ function rowLabel(row, prefix = "") {
 export function inertFieldLabels(config) {
     const routes = routesOf(config);
     const inert = [];
-    for (const [index, actor] of config.actors.entries()) {
+    for (const [index, actor] of actorsOf(config).entries()) {
         for (const row of ACTOR_ROWS)
             if (row.applies(actor, routes))
                 inert.push(rowLabel(row, `actors[${index}].`));
@@ -323,7 +324,7 @@ export function inertFieldLabels(config) {
 export function inertFieldPaths(config) {
     const routes = routesOf(config);
     const paths = [];
-    for (const [index, actor] of config.actors.entries()) {
+    for (const [index, actor] of actorsOf(config).entries()) {
         for (const row of ACTOR_ROWS)
             if (row.applies(actor, routes))
                 paths.push(`actors[${index}].${row.field}`);
@@ -347,7 +348,7 @@ export function forwardDeclaredWarnings(config) {
     // and the cap delivers waves of M. Say so up front (inspect + dry-run + run): a green run in
     // waves is otherwise indistinguishable from the all-live run the author meant.
     {
-        const participantCount = rosterOf(config.actors[0])?.length ?? config.actors[0]?.count ?? 1;
+        const participantCount = participantList(config)?.length ?? declaredParticipantCount(config) ?? 1;
         const cap = config.execution?.concurrency;
         if (routes.cua && cap !== undefined && participantCount > 1 && cap < participantCount) {
             warnings.push(`execution.concurrency ${cap} caps a ${participantCount}-participant roster: participants run in waves of ${cap}, never all live at once. Remove execution.concurrency (the default runs all ${participantCount} participants simultaneously) or set it to ${participantCount}; declare a lower cap only to bound simultaneous paid desktops.`);

package/dist/substrates/local/runtime-config.js

@@ -1,11 +1,11 @@
-import { rosterOf } from "../../study/parse/actors.js";
+import { actorOf, actorsOf, participantList } from "../../study/study-fields.js";
 // The runtime image enforces a 30-minute lifetime; reserve setup/teardown room.
 export const LOCAL_BROWSER_LIFETIME_MS = 30 * 60_000;
 const MAX_SESSION_MS = 20 * 60_000;
 export function isLocalBrowserStudy(config) {
     return (config.subject.source === "app-url" &&
         config.execution?.target === "local" &&
-        ["local-agent", "openai-computer-use"].includes(config.actors[0]?.type ?? ""));
+        ["local-agent", "openai-computer-use"].includes(actorOf(config)?.type ?? ""));
 }
 /** Defaults for the explicitly selected local substrate; hosted configurations are untouched. */
 export function localBrowserDefaults(config) {
@@ -13,7 +13,7 @@ export function localBrowserDefaults(config) {
         return config;
     return {
         ...config,
-        actors: config.actors.map((actor) => ({
+        actors: actorsOf(config).map((actor) => ({
             ...actor,
             model: actor.model ?? "gpt-6-astra",
             reasoningEffort: actor.reasoningEffort ?? "low",
@@ -26,18 +26,18 @@ export function localBrowserDefaults(config) {
                 resolution: config.execution?.desktop?.resolution ?? [960, 720],
             },
         },
-        ...(config.review?.analysis === undefined && config.actors[0]?.type === "local-agent"
+        ...(config.review?.analysis === undefined && actorOf(config)?.type === "local-agent"
             ? { review: { ...config.review, analysis: { provider: "codex" } } }
             : {}),
     };
 }
 export function localBrowserUnsupportedReason(config) {
-    const actor = config.actors[0];
+    const actor = actorOf(config);
     const desktop = config.execution?.desktop;
     if ((config.execution?.timeoutMs ?? MAX_SESSION_MS) > MAX_SESSION_MS) {
         return "Local browser sessions currently support at most 20 minutes, within the runtime's 30-minute lifetime.";
     }
-    if (config.actors.length !== 1 ||
+    if (actorsOf(config).length !== 1 ||
         !actor ||
         (actor.type === "local-agent" && actor.localAgent !== undefined && actor.localAgent !== "codex")) {
         return "Local browser studies support only Codex local-agent or openai-computer-use participants.";
@@ -46,7 +46,7 @@ export function localBrowserUnsupportedReason(config) {
         desktop.resolution[1] !== 720 ||
         desktop.device !== undefined ||
         (desktop.browser !== undefined && !["default", "chromium"].includes(desktop.browser)) ||
-        rosterOf(actor)?.some((entry) => entry.device !== undefined) ||
+        participantList(config)?.some((entry) => entry.device !== undefined) ||
         desktop.template !== undefined ||
         desktop.sandboxTimeoutMs !== undefined) {
         return "The local browser runtime currently uses a 960×720 Chromium desktop. Omit hosted templates, device presets and sandboxTimeoutMs.";
@@ -61,7 +61,7 @@ export function localBrowserUnsupportedReason(config) {
     if (actor.type === "local-agent" &&
         (actor.model !== "gpt-6-astra" ||
             actor.reasoningEffort !== "low" ||
-            rosterOf(actor)?.some((entry) => entry.reasoningEffort !== undefined && entry.reasoningEffort !== "low") ||
+            participantList(config)?.some((entry) => entry.reasoningEffort !== undefined && entry.reasoningEffort !== "low") ||
             actor.maxOutputTokens !== undefined ||
             config.execution?.caps?.maxUsd !== undefined ||
             config.execution?.caps?.maxTotalUsd !== undefined ||
@@ -71,7 +71,7 @@ export function localBrowserUnsupportedReason(config) {
     }
     for (const target of [
         config.subject.appUrl,
-        ...(rosterOf(actor) ?? []).map((entry) => entry.target),
+        ...(participantList(config) ?? []).map((entry) => entry.target),
     ].filter(Boolean)) {
         let url;
         try {