humanish 0.107.0 → 0.109.0

package/dist/routes/scripted/setup.js

@@ -2,14 +2,15 @@
 // the E2B key and subject env of a live clone, a browser to launch) and the values the run reads
 // (the evidence URL policy, the scrubber for clone values, the persona and the session budget).
 import { realpath } from "node:fs/promises";
-import { missingKeys, missingSubjectEnv } from "../../lab/requirements.js";
+import { missingKeys, missingSubjectEnv } from "../../study/requirements.js";
 import path from "node:path";
 import { resolveBrowserCommand } from "../../actors/scripted-browser/browser-command.js";
 import { describeMissingKeys } from "../../keys/key-resolution.js";
 import { prepareSelectedOutputDirectory } from "../../run/contained-output.js";
 import { evidenceAppUrlOf } from "./plan.js";
 import { resolveScriptedScenario } from "./scenario.js";
-import { SCRIPTED_BROWSER_LAB_SCHEMA, } from "./types.js";
+import {} from "./types.js";
+import { studyResultIdentity } from "../../run/study-result.js";
 // Journey wall-clock budget per surface: 5 minutes. A scripted surface has zero model cost and
 // sandbox-seconds are pennies; a short default only truncated slow-loading subjects.
 const DEFAULT_SESSION_TIMEOUT_MS = 300_000;
@@ -27,10 +28,9 @@ export async function prepareScriptedRun(plan, input) {
     const clone = plan.subject.kind === "clone" ? plan.subject : undefined;
     const evidenceAppUrl = evidenceAppUrlOf(plan.subject);
     const failed = (code, message) => ({
-        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+        ...studyResultIdentity("scripted", plan.studyId),
         ok: false,
         cwd,
-        labId: plan.labId,
         actor: plan.actor,
         appUrl: evidenceAppUrl,
         dryRun,
@@ -58,7 +58,7 @@ export async function prepareScriptedRun(plan, input) {
     if (!scenario.ok) {
         return {
             ok: false,
-            result: failed("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", scenario.message),
+            result: failed("HUMANISH_SCRIPTED_SCENARIO_INVALID", scenario.message),
         };
     }
     const journey = scenario.journey;
@@ -67,14 +67,14 @@ export async function prepareScriptedRun(plan, input) {
     if (missing.length > 0) {
         return {
             ok: false,
-            result: failed("HUMANISH_SCRIPTED_LAB_KEYS_MISSING", `Live clone scripted-browser labs require ${missing.join(" and ")} (dry-run remains $0 and does not provision a subject). ${describeMissingKeys(missing, env)}`),
+            result: failed("HUMANISH_SCRIPTED_KEYS_MISSING", `Live clone scripted-browser studies require ${missing.join(" and ")} (dry-run remains $0 and does not provision a subject). ${describeMissingKeys(missing, env)}`),
         };
     }
     const unsetSubjectEnv = missingSubjectEnv(plan.requirements, env);
     if (unsetSubjectEnv.length > 0) {
         return {
             ok: false,
-            result: failed("HUMANISH_SCRIPTED_LAB_SUBJECT_ENV_MISSING", `Subject env values missing for live clone scripted-browser lab: ${unsetSubjectEnv.join(", ")}.`),
+            result: failed("HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING", `Subject env values missing for a live clone scripted-browser study: ${unsetSubjectEnv.join(", ")}.`),
         };
     }
     const surfaces = plan.surfaces;
@@ -93,7 +93,7 @@ export async function prepareScriptedRun(plan, input) {
         if (!resolved) {
             return {
                 ok: false,
-                result: failed("HUMANISH_SCRIPTED_LAB_BROWSER_MISSING", "No Chrome/Chromium browser command was found for the scripted-browser actor. Set HUMANISH_BROWSER_COMMAND to a browser binary playwright-core can launch."),
+                result: failed("HUMANISH_SCRIPTED_BROWSER_MISSING", "No Chrome/Chromium browser command was found for the scripted-browser actor. Set HUMANISH_BROWSER_COMMAND to a browser binary playwright-core can launch."),
             };
         }
         browserCommand = resolved;

package/dist/routes/scripted/subject.d.ts

@@ -1,9 +1,9 @@
-import type { ScriptedPlan } from "../../lab/plan-types.js";
+import type { ScriptedPlan } from "../../study/plan-types.js";
 import { type PreparedRunArtifactPaths } from "../../run/paths.js";
 import type { RunSubjectStateStepRecord } from "../../run/bundle.js";
 import { type DesktopResourceObservation } from "../../substrates/e2b/desktop-resources.js";
-import type { LabDeps } from "../../lab/lab-deps.js";
-import type { RunLabHomes } from "../../lab/run-lab-homes.js";
+import type { StudyDeps } from "../../study/study-deps.js";
+import type { RunStudyHomes } from "../../study/run-study-homes.js";
 type ScriptedCloneSubject = Extract<ScriptedPlan["subject"], {
     readonly kind: "clone";
 }>;
@@ -11,9 +11,9 @@ type ScriptedCloneSubject = Extract<ScriptedPlan["subject"], {
 export interface ScriptedSubjectInputs {
     plan: ScriptedPlan;
     clone: ScriptedCloneSubject;
-    deps: LabDeps;
+    deps: StudyDeps;
     /** Runs after the subject sandbox exists and before provisioning. */
-    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
+    prepareDesktop?: NonNullable<RunStudyHomes["prepareDesktop"]>;
     env: Readonly<Record<string, string | undefined>>;
     e2bApiKey: string;
     runPaths: PreparedRunArtifactPaths;

package/dist/routes/scripted/subject.js

@@ -1,4 +1,4 @@
-// The provisioned subject of a live clone scripted-browser lab: one E2B desktop that clones,
+// The provisioned subject of a live clone scripted-browser study: one E2B desktop that clones,
 // seeds and serves the app, exposed through a tokenless getHost URL and killed by exact id at
 // teardown.
 import { commandDigestOf } from "../../subject/state.js";
@@ -74,8 +74,8 @@ export class ScriptedSubject {
                 metadata: {
                     mode: "scripted-browser-lab",
                     tool: "humanish",
-                    labId: plan.labId,
-                    role: "subject",
+                    labId: plan.studyId,
+                    kind: "subject",
                     actor: plan.actor,
                 },
                 ...(subjectEnvNames.length > 0
@@ -115,7 +115,7 @@ export class ScriptedSubject {
             ...timers,
         });
         if (typeof subjectDesktop.getHost !== "function") {
-            throw new Error("the installed @e2b/desktop SDK does not expose getHost(port); clone scripted-browser labs require it to reach the provisioned subject");
+            throw new Error("the installed @e2b/desktop SDK does not expose getHost(port); clone scripted-browser studies require it to reach the provisioned subject");
         }
         const rawHost = subjectDesktop.getHost(servePort(clone.serve.url));
         const hostUrl = /^https?:\/\//i.test(rawHost) ? rawHost : `https://${rawHost}`;

package/dist/routes/scripted/surface-records.d.ts

@@ -10,7 +10,7 @@ export interface ScriptedSurfaceContext {
     appUrl: string;
     createdAt: string;
     journey: BrowserPersonaJourney;
-    labId: string;
+    studyId: string;
     persona: ActorPersonaRef;
     sessionError?: string;
 }

package/dist/routes/scripted/surface-records.js

@@ -18,7 +18,7 @@ export function scriptedSurfaceRecords(context, surface, index, result, screensh
             : "contract_proof_only";
     const reason = result?.reason ??
         context.sessionError ??
-        "Contract bundle only: dry-run pinned the scenario contract without launching a browser or touching the subject app.";
+        "Dry run: the scenario was pinned without launching a browser or touching the subject app.";
     const simulation = participantRecord(ids, index + 1, {
         personaId: context.persona.id,
         scenarioId: context.journey.scenarioId,
@@ -30,14 +30,14 @@ export function scriptedSurfaceRecords(context, surface, index, result, screensh
         summary: result
             ? `Scripted-browser actor (${context.actorId}) replayed ${context.journey.scenarioId} on the ${surface.id} surface; ${result.completionReason}.`
             : context.sessionError !== undefined
-                ? `Scripted lab failed before a terminal session verdict: ${context.sessionError}`
-                : `Contract participant for the scripted-browser actor (${context.actorId}) against ${context.appUrl}.`,
+                ? `The scripted run failed before a terminal session verdict: ${context.sessionError}`
+                : `Scripted-browser actor (${context.actorId}) against ${context.appUrl}; no session ran.`,
         startedAt: context.createdAt,
         updatedAt: result?.capture.capturedAt ?? context.createdAt,
     });
     const stream = participantStream(ids, {
         kind: "browser",
-        label: `${surface.label} — ${context.labId}`,
+        label: `${surface.label} · ${context.studyId}`,
         status,
         transport: "snapshot",
         updatedAt: result?.capture.capturedAt ?? context.createdAt,

package/dist/routes/scripted/surface-sessions.d.ts

@@ -1,11 +1,11 @@
 import { type ScriptedBrowserSessionOptions, type ScriptedBrowserSessionResult } from "../../actors/scripted-browser/actor.js";
-import type { ScriptedPlan } from "../../lab/plan-types.js";
+import type { ScriptedPlan } from "../../study/plan-types.js";
 import { type PreparedRunArtifactPaths } from "../../run/paths.js";
-import type { LabDeps } from "../../lab/lab-deps.js";
+import type { StudyDeps } from "../../study/study-deps.js";
 /** One session per surface, in parallel. */
 export declare function runScriptedSessions(session: Required<Pick<ScriptedBrowserSessionOptions, "appUrl" | "evidenceAppUrl" | "urlPolicy" | "journey" | "persona" | "timeoutMs" | "artifactRoot">>, run: {
     surfaces: ScriptedPlan["surfaces"];
-    deps: LabDeps;
+    deps: StudyDeps;
     browserCommand: string | undefined;
     runPaths: PreparedRunArtifactPaths;
 }): Promise<ScriptedBrowserSessionResult[]>;

package/dist/routes/scripted/types.d.ts

@@ -1,21 +1,21 @@
 import type { ActorCompletionReason, ActorStatus } from "../../actors/contract.js";
-import type { LabEvent } from "../../lab/run-lab-events.js";
+import type { StudyEvent } from "../../study/run-study-events.js";
 import type { AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
-import type { LabConfig } from "../../lab/types.js";
+import type { StudyConfig } from "../../study/types.js";
 import type { ObserverResult } from "../../observer/render.js";
 import type { RunSubjectProvenance } from "../../run/bundle.js";
-import type { LabDeps } from "../../lab/lab-deps.js";
-import type { RunLabHomes } from "../../lab/run-lab-homes.js";
-export declare const SCRIPTED_BROWSER_LAB_SCHEMA = "humanish.scripted-lab-result.v1";
-/** What a scripted run takes besides its plan. The plan carries the config, dry run and lab. */
-export type ScriptedRunInput = Omit<RunScriptedBrowserLabOptions, "config" | "dryRun" | "lab">;
-export interface RunScriptedBrowserLabOptions {
+import type { StudyDeps } from "../../study/study-deps.js";
+import type { RunStudyHomes } from "../../study/run-study-homes.js";
+import { type StudyResultIdentity } from "../../run/study-result.js";
+/** What a scripted run takes besides its plan. The plan carries the config, dry run and study. */
+export type ScriptedRunInput = Omit<RunScriptedBrowserStudyOptions, "config" | "dryRun">;
+export interface RunScriptedBrowserStudyOptions {
     /** Cancels post-run analysis only. */
     analysisSignal?: AbortSignal;
-    /** Reports the analysis window to onEvent; built by normalizeRunLabOptions. */
-    emit?: (event: LabEvent) => void;
+    /** Reports the analysis window to onEvent; built by normalizeRunStudyOptions. */
+    emit?: (event: StudyEvent) => void;
     cwd: string;
-    config: LabConfig;
+    config: StudyConfig;
     /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
     dryRun: boolean;
     open?: boolean;
@@ -23,25 +23,23 @@ export interface RunScriptedBrowserLabOptions {
     /** Keys and subject env for the run. Defaults to process.env. Values are scrubbed; names persist. */
     env?: Readonly<Record<string, string | undefined>>;
     /** Runs after a clone subject's sandbox exists and before provisioning. */
-    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
+    prepareDesktop?: NonNullable<RunStudyHomes["prepareDesktop"]>;
     /** Test seams: the browser, the session, the E2B module, timers, the renderer and the clock. */
-    deps?: LabDeps;
+    deps?: StudyDeps;
 }
-interface ScriptedBrowserLabSession {
+interface ScriptedBrowserStudySession {
     surface: string;
     status: ActorStatus;
     completionReason: ActorCompletionReason;
     reason: string;
     screenshots: number;
 }
-export interface ScriptedBrowserLabResult extends AutomaticAnalysisResult {
-    schema: typeof SCRIPTED_BROWSER_LAB_SCHEMA;
+export interface ScriptedBrowserStudyResult extends AutomaticAnalysisResult, StudyResultIdentity<"scripted"> {
     /** True when the bundle verified and (dry-run, or every session reached a terminal verdict
-     * without a harness error). The subject failing the script is successful evidence, and the lab
+     * without a harness error). The subject failing the script is successful evidence, and the run
      * does not fail for it. */
     ok: boolean;
     cwd: string;
-    labId: string;
     /** The registry-resolved actor id that ran (or would run) the sessions. */
     actor: string;
     appUrl: string;
@@ -60,11 +58,11 @@ export interface ScriptedBrowserLabResult extends AutomaticAnalysisResult {
         sourceDigest: string;
         steps: number;
     };
-    sessions: ScriptedBrowserLabSession[];
+    sessions: ScriptedBrowserStudySession[];
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_FAILED" | "HUMANISH_SCRIPTED_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_LAB_BROWSER_MISSING" | "HUMANISH_SCRIPTED_LAB_KEYS_MISSING" | "HUMANISH_SCRIPTED_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_LAB_GETHOST_UNAVAILABLE" | "HUMANISH_RUN_ID_IN_USE";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_SCRIPTED_FAILED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_BROWSER_MISSING" | "HUMANISH_SCRIPTED_KEYS_MISSING" | "HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_GETHOST_UNAVAILABLE" | "HUMANISH_RUN_ID_IN_USE";
         message: string;
     };
 }

package/dist/routes/scripted/types.js

@@ -1,2 +1,2 @@
-// The scripted-browser lab's schema constant, options and result types.
-export const SCRIPTED_BROWSER_LAB_SCHEMA = "humanish.scripted-lab-result.v1";
+// The scripted-browser study's schema constant, options and result types.
+import {} from "../../run/study-result.js";

package/dist/routes/shared-world/bundle-records.js

@@ -1,7 +1,7 @@
 // Each participant's records in a concurrent shared-world bundle: its simulation, its stream and
 // its events, projected from the actor's run result (or from the declaration on a dry run or while
 // running).
-import { participantAssignment } from "../../lab/participant-assignment.js";
+import { participantAssignment } from "../../study/participant-assignment.js";
 import { participantEvent, participantRecord, participantStream, } from "../../run/participant-records.js";
 import { declaredScreenForRender } from "../../substrates/e2b/desktop-geometry.js";
 import { publicSafeRouteLabel } from "./provenance.js";
@@ -14,7 +14,8 @@ function participantView(ctx, spec, index) {
     const session = outcome?.session;
     const screenshots = outcome?.screenshots ?? [];
     const lastScreenshot = screenshots[screenshots.length - 1];
-    // public-safe (origin redacted): external-public seats open the public plane; getHost seats a seat path.
+    // public-safe (origin redacted): external-public participants open the public plane; getHost
+    // participants open their own path.
     const route = external
         ? "[external-public-plane]"
         : publicSafeRouteLabel(args.plan.plane.participants[index]?.entry);
@@ -29,7 +30,7 @@ function participantView(ctx, spec, index) {
         outcome?.sessionError ??
         (inProgress
             ? "Actor desktop is running; the attached Observer hydrates the runtime stream URL without persisting it."
-            : "Contract actor only: dry-run produced the evidence shape without launching a desktop or spending provider tokens.");
+            : "Dry run: the evidence shape was written without launching a desktop or spending provider tokens.");
     const traceScreenshotMode = session?.trace.redaction.screenshots;
     // Include `declared` on the no-outcome fallback too (dry-run, skipped participant): otherwise an
     // absent `declared` means either "the preset rendered faithfully" or "there was no live
@@ -67,7 +68,7 @@ function sharedWorldSimulation(ctx, spec, index, view) {
     const { taxonomy, outcome, session } = view;
     return participantRecord(spec, index + 1, {
         personaId: spec.persona.id,
-        scenarioId: `concurrent-shared-world-${args.plan.labId}`,
+        scenarioId: `concurrent-shared-world-${args.plan.studyId}`,
         status: view.status,
         streamKind: "browser",
         mode: "browser-sim",
@@ -79,7 +80,7 @@ function sharedWorldSimulation(ctx, spec, index, view) {
                 ? `Persona ${spec.planned.id}${taxonomy} failed before a terminal session verdict: ${outcome.sessionError}`
                 : inProgress
                     ? `Persona ${spec.planned.id}${taxonomy} (${spec.persona.id}) is running against the shared plane.`
-                    : `Contract persona ${spec.planned.id}${taxonomy} (${spec.persona.id}) for ${args.descriptor.id} against the shared plane at ${ctx.appUrl}.`,
+                    : `Persona ${spec.planned.id}${taxonomy} (${spec.persona.id}) for ${args.descriptor.id} against the shared plane at ${ctx.appUrl}; no session ran.`,
         startedAt: args.run.createdAt,
         updatedAt: args.run.createdAt,
     });
@@ -92,7 +93,7 @@ function sharedWorldStream(ctx, spec, index, view) {
             ? {}
             : { assignment: participantAssignment(spec.evidenceAssignment) }),
         kind: "browser",
-        label: `Concurrent persona ${spec.planned.id}${taxonomy} — ${args.plan.labId}`,
+        label: `Concurrent persona ${spec.planned.id}${taxonomy} · ${args.plan.studyId}`,
         status: view.status,
         transport: "snapshot",
         updatedAt: args.run.createdAt,
@@ -116,7 +117,7 @@ function sharedWorldStream(ctx, spec, index, view) {
         desktopGeometry,
         ui: {
             route: view.route,
-            intent: `Watch persona ${spec.planned.id}${taxonomy} (${spec.persona.id}) drive the SHARED plane concurrently with the other personas.`,
+            intent: `Watch persona ${spec.planned.id}${taxonomy} (${spec.persona.id}) use the shared app at the same time as the other personas.`,
             state: view.reason,
             ...(session ? { actorStatus: session.status } : {}),
             ...(lastScreenshot ? { screenshotUrl: lastScreenshot } : {}),
@@ -137,7 +138,7 @@ function sharedWorldStream(ctx, spec, index, view) {
                 : []),
             // Run-level comms evidence belongs to the one shared app, and to no persona: register it once, on
             // the first stream, so the bundle's existence-verify + public-safety scan cover it without
-            // double-counting across seats.
+            // double-counting across participants.
             ...(index === 0 && args.commsArtifactPath
                 ? [{ label: "comms thread", path: args.commsArtifactPath, kind: "log" }]
                 : []),
@@ -170,7 +171,7 @@ function sharedWorldEvents(ctx, spec, view) {
             at: createdAt,
             level: session.status === "passed" ? "info" : "warn",
             type: `concurrent-shared-world.session.${session.completionReason}`,
-            message: `Persona ${spec.planned.id}: ${session.status} — ${session.reason}`,
+            message: `Persona ${spec.planned.id}: ${session.status} (${session.reason})`,
         });
     }
     else if (outcome?.sessionError !== undefined) {
@@ -197,7 +198,7 @@ function sharedWorldEvents(ctx, spec, view) {
             at: createdAt,
             level: "info",
             type: "concurrent-shared-world.contract.ready",
-            message: `Persona ${spec.planned.id}: dry-run contract actor ready; switch scenario.mode to live for a real concurrent session.`,
+            message: `Persona ${spec.planned.id}: dry-run actor ready; switch scenario.mode to live for a real concurrent session.`,
         });
     }
     return events;

package/dist/routes/shared-world/bundle.d.ts

@@ -1,17 +1,17 @@
 import { type RunBundle } from "../../run/bundle.js";
 import { type SharedWorldJudgment } from "../../run/judge.js";
 import { type ActorRunResult, type ConcurrentBundleArgs } from "./types.js";
-/** Max windows live at the same instant (sweep over start/end points). The honest simultaneity
+/** Max windows live at the same instant (sweep over start/end points). The simultaneity
  *  count: the participant count says how many existed; this says how many ever ran at once. */
 export declare function maxSimultaneousWindows(windows: Array<{
     startedAt: number;
     endedAt: number;
 }>): number;
 /**
- * The judgment for a shared-world bundle's inputs: how each seat ended, plus what the run observed
- * about its world: overlap, a state change under overlap on the provisioned plane, and lobby
- * convergence on the external-public plane. The bundle's verdict and the lab result's ok both read
- * it.
+ * The judgment for a shared-world bundle's inputs: how each participant ended, plus what the run
+ * observed about its world: overlap, a state change under overlap on the provisioned plane, and
+ * lobby convergence on the external-public plane. The bundle's verdict and the study result's ok
+ * both read it.
  */
 export declare function judgeSharedWorldRun(args: Omit<ConcurrentBundleArgs, "judgment">): SharedWorldJudgment;
 export declare function actorRunPassed(result: ActorRunResult | undefined): boolean;