humanish 0.104.3 → 0.106.0

package/dist/routes/computer-use/fanout-lanes.js

@@ -0,0 +1,302 @@
+// Each participant's records in a computer-use fan-out bundle: its simulation, its stream, its
+// subject provenance event and the events of its outcome (session, geometry warnings, phase trail).
+import { participantAssignment } from "../../lab/participant-assignment.js";
+import { participantEvent, participantRecord, participantStream, } from "../../run/participant-records.js";
+import { declaredScreenForRender } from "../../substrates/e2b/desktop-geometry.js";
+import { describeSubjectState, phaseEventIdSuffix, publicSafeAppUrlLabel } from "./bundle-parts.js";
+function fanoutParticipantView(args, spec, index) {
+    const { outcomes, plan } = args;
+    const outcome = outcomes?.[index];
+    const targetUrl = spec.planned.targetUrl ?? args.appUrl;
+    const publicTargetUrl = publicSafeAppUrlLabel(targetUrl);
+    const subject = args.subjects[index];
+    const session = outcome?.session;
+    const fallbackDeclared = declaredScreenForRender(spec.planned.device.preset, spec.planned.device.name, spec.planned.device.resolution);
+    const desktopGeometry = outcome?.desktopGeometry ?? {
+        screen: {
+            requested: {
+                width: spec.planned.device.resolution[0],
+                height: spec.planned.device.resolution[1],
+            },
+            ...(fallbackDeclared ? { declared: fallbackDeclared } : {}),
+        },
+    };
+    const screenshots = outcome?.screenshots ?? [];
+    const lastScreenshot = screenshots[screenshots.length - 1];
+    const status = args.inProgress === true && outcome === undefined
+        ? "running"
+        : outcome?.skippedReason !== undefined
+            ? "blocked"
+            : session
+                ? session.status
+                : outcome?.sessionError !== undefined
+                    ? "failed"
+                    : "contract_proof_only";
+    const reason = args.inProgress === true && outcome === undefined
+        ? "Live computer-use participant is running; stream auth URL is available only through the attached Observer server."
+        : (outcome?.skippedReason ??
+            session?.reason ??
+            outcome?.sessionError ??
+            "Contract bundle only: dry-run produced the evidence shape without launching a desktop or spending provider tokens.");
+    const traceScreenshotMode = session?.trace.redaction.screenshots;
+    const screenshotMode = traceScreenshotMode === "raw" || traceScreenshotMode === "blurred"
+        ? traceScreenshotMode
+        : plan.residual.policies?.redactScreenshots === true
+            ? "blurred"
+            : "raw";
+    return {
+        outcome,
+        publicTargetUrl,
+        subject,
+        session,
+        desktopGeometry,
+        screenshots,
+        lastScreenshot,
+        status,
+        reason,
+        screenshotMode,
+    };
+}
+function fanoutParticipantRecord(args, spec, index, view) {
+    const { plan } = args;
+    const { outcome, publicTargetUrl, session, status, reason } = view;
+    return participantRecord(spec, index + 1, {
+        personaId: spec.persona.id,
+        scenarioId: `cua-${plan.labId}`,
+        status,
+        streamKind: "browser",
+        mode: "browser-sim",
+        progress: args.inProgress === true && outcome === undefined ? 20 : 100,
+        currentStep: reason,
+        summary: session
+            ? `Participant ${spec.planned.id} (${spec.persona.id}/${spec.planned.device.name}): computer-use actor (${args.descriptor.id}) drove the subject app; ${session.completionReason}.`
+            : args.inProgress === true && outcome === undefined
+                ? `Participant ${spec.planned.id} (${spec.persona.id}/${spec.planned.device.name}): computer-use actor (${args.descriptor.id}) is driving the subject app.`
+                : outcome?.skippedReason !== undefined
+                    ? `Participant ${spec.planned.id} ${outcome.skippedReason}.`
+                    : outcome?.sessionError !== undefined
+                        ? `Participant ${spec.planned.id} failed before a terminal session verdict: ${outcome.sessionError}`
+                        : `Contract participant ${spec.planned.id} (${spec.persona.id}/${spec.planned.device.name}) for ${args.descriptor.id} against ${publicTargetUrl}.`,
+        startedAt: args.createdAt,
+        updatedAt: args.createdAt,
+    });
+}
+function fanoutParticipantStream(args, spec, view) {
+    const { plan } = args;
+    const { outcome, publicTargetUrl, session, desktopGeometry, screenshots } = view;
+    const { lastScreenshot, status, reason, screenshotMode } = view;
+    return participantStream(spec, {
+        ...(spec.evidenceAssignment === undefined
+            ? {}
+            : { assignment: participantAssignment(spec.evidenceAssignment) }),
+        ...(spec.planned.labels.actorType === undefined
+            ? {}
+            : { actorType: spec.planned.labels.actorType }),
+        ...(spec.planned.labels.surface === undefined
+            ? {}
+            : { surface: spec.planned.labels.surface }),
+        ...(spec.planned.labels.caseGroup === undefined
+            ? {}
+            : { caseGroup: spec.planned.labels.caseGroup }),
+        kind: "browser",
+        label: `CUA participant ${spec.planned.id}: ${plan.labId}`,
+        status,
+        transport: "snapshot",
+        updatedAt: args.createdAt,
+        embed: lastScreenshot
+            ? {
+                kind: "screenshot",
+                url: lastScreenshot,
+                title: `CUA desktop ${spec.planned.id} (${screenshotMode})`,
+            }
+            : { kind: "placeholder", title: `CUA desktop ${spec.planned.id}` },
+        ...(desktopGeometry.viewport === undefined
+            ? {}
+            : {
+                viewport: {
+                    width: desktopGeometry.viewport.width,
+                    height: desktopGeometry.viewport.height,
+                    deviceScaleFactor: desktopGeometry.viewport.deviceScaleFactor,
+                    isMobile: spec.planned.device.preset.isMobile,
+                },
+            }),
+        desktopGeometry,
+        ...(outcome?.recording === undefined ? {} : { recording: outcome.recording }),
+        ui: {
+            route: publicTargetUrl,
+            intent: `Watch participant ${spec.planned.id} (${spec.persona.id}/${spec.planned.device.name}) drive the subject app in its own hosted desktop.`,
+            state: reason,
+            ...(session ? { actorStatus: session.status } : {}),
+            ...(lastScreenshot ? { screenshotUrl: lastScreenshot } : {}),
+        },
+        ...(session ? { actor: session.trace } : {}),
+        artifacts: [
+            { label: "run bundle", path: "run.json", kind: "bundle" },
+            { label: "review", path: "review.md", kind: "review" },
+            { label: "events", path: "events.ndjson", kind: "events" },
+            ...(session
+                ? [
+                    {
+                        label: `participant ${spec.planned.id} actor trace`,
+                        path: spec.traceArtifactPath,
+                        kind: "trace",
+                    },
+                ]
+                : []),
+            ...(outcome?.commsArtifactPath
+                ? [
+                    {
+                        label: `participant ${spec.planned.id} comms thread`,
+                        path: outcome.commsArtifactPath,
+                        kind: "log",
+                    },
+                ]
+                : []),
+            ...(outcome?.recording
+                ? [
+                    {
+                        label: "desktop recording",
+                        path: outcome.recording.path,
+                        kind: "recording",
+                    },
+                ]
+                : []),
+            ...screenshots.map((screenshot, screenshotIndex) => ({
+                label: `participant ${spec.planned.id} screenshot ${String(screenshotIndex + 1).padStart(2, "0")} (${screenshotMode})`,
+                path: screenshot,
+                kind: "screenshot",
+            })),
+        ],
+    }, spec.planned.id);
+}
+function fanoutSubjectEvents(ctx, spec, view) {
+    const { args, nextEventId } = ctx;
+    const { publicTargetUrl, subject, session } = view;
+    const events = [];
+    const record = (event) => events.push(participantEvent(spec, event));
+    // Per-lane subject provenance (invariant 5).
+    if (args.cloneRoute && args.publicRepo) {
+        record({
+            id: nextEventId(`subject-${spec.planned.id}`),
+            at: args.createdAt,
+            level: "info",
+            type: "cua-lab.subject.provenance",
+            message: `Participant ${spec.planned.id}: ${args.dryRun
+                ? `subject declared: clone of ${args.publicRepo}, served at ${publicTargetUrl} in-sandbox (dry-run contract; nothing cloned)`
+                : subject.commit
+                    ? session
+                        ? `subject cloned from ${args.publicRepo}@${subject.commit} and served at ${publicTargetUrl} in-sandbox`
+                        : `subject cloned from ${args.publicRepo}@${subject.commit}; serving did not complete (see session error)`
+                    : `subject clone attempted from ${args.publicRepo}; commit unresolved`} (subject env names: ${args.subjectEnvNames.length > 0 ? args.subjectEnvNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(subject.state, args.dryRun)}.`,
+        });
+    }
+    else if (subject.source === "local-tree") {
+        record({
+            id: nextEventId(`subject-${spec.planned.id}`),
+            at: args.createdAt,
+            level: "info",
+            type: "cua-lab.subject.provenance",
+            message: `Participant ${spec.planned.id}: ${args.dryRun
+                ? `subject declared: local working tree, to be packed and served at ${publicTargetUrl} in-sandbox (dry-run contract; nothing packed)`
+                : subject.archiveSha256
+                    ? session
+                        ? `subject packed (archiveSha256 ${subject.archiveSha256}${subject.dirty === true ? ", dirty working tree" : subject.dirty === false ? ", clean working tree" : ""}) and served at ${publicTargetUrl} in-sandbox`
+                        : `subject packed (archiveSha256 ${subject.archiveSha256}); serving did not complete (see session error)`
+                    : "subject local-tree packing attempted; archive digest unresolved"} (subject env names: ${args.subjectEnvNames.length > 0 ? args.subjectEnvNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(subject.state, args.dryRun)}.`,
+        });
+    }
+    else {
+        record({
+            id: nextEventId(`subject-${spec.planned.id}`),
+            at: args.createdAt,
+            level: "info",
+            type: "cua-lab.subject.declared",
+            message: `Participant ${spec.planned.id}: subject app declared at ${publicTargetUrl} (loopback inside the participant's own desktop sandbox).`,
+        });
+    }
+    return events;
+}
+function fanoutOutcomeEvents(ctx, spec, view) {
+    const { args, nextEventId } = ctx;
+    const { outcome, session, desktopGeometry } = view;
+    const events = [];
+    const record = (event) => events.push(participantEvent(spec, event));
+    // Per-lane session event.
+    if (session) {
+        record({
+            id: nextEventId(`session-${spec.planned.id}`),
+            at: args.createdAt,
+            level: session.status === "passed" ? "info" : "warn",
+            type: `cua-lab.session.${session.completionReason}`,
+            message: `Participant ${spec.planned.id} ${session.status}: ${session.reason}`,
+        });
+    }
+    else if (args.inProgress === true && outcome === undefined) {
+        record({
+            id: nextEventId(`running-${spec.planned.id}`),
+            at: args.createdAt,
+            level: "info",
+            type: "cua-lab.session.running",
+            message: `Participant ${spec.planned.id}: live computer-use session is running; terminal evidence has not been written yet.`,
+        });
+    }
+    else if (outcome?.skippedReason !== undefined) {
+        record({
+            id: nextEventId(`blocked-${spec.planned.id}`),
+            at: args.createdAt,
+            level: "warn",
+            type: "cua-lab.session.blocked",
+            message: `Participant ${spec.planned.id} ${outcome.skippedReason}.`,
+        });
+    }
+    else if (outcome?.sessionError !== undefined) {
+        record({
+            id: nextEventId(`session-error-${spec.planned.id}`),
+            at: args.createdAt,
+            level: "error",
+            type: "cua-lab.session.error",
+            message: `Participant ${spec.planned.id}: ${outcome.sessionError}`,
+        });
+    }
+    else {
+        record({
+            id: nextEventId(`contract-${spec.planned.id}`),
+            at: args.createdAt,
+            level: "info",
+            type: "cua-lab.contract.ready",
+            message: `Participant ${spec.planned.id}: dry-run contract participant ready; switch scenario.mode to live for a real desktop session.`,
+        });
+    }
+    for (const warning of desktopGeometry.warnings ?? []) {
+        record({
+            id: nextEventId(`geometry-warning-${spec.planned.id}`),
+            at: args.createdAt,
+            level: "warn",
+            type: "cua-lab.geometry.warning",
+            message: warning,
+        });
+    }
+    // Persisted per-lane phase trail (real boot timing): one RunEvent per COMPLETED phase
+    // boundary this lane recorded (started events never persist here; they carry no durationMs).
+    for (const phase of outcome?.phaseRecords ?? []) {
+        record({
+            id: nextEventId(`phase-${spec.planned.id}-${phaseEventIdSuffix(phase.type)}`),
+            at: phase.at,
+            level: phase.ok === false ? "warn" : "info",
+            type: phase.type,
+            message: phase.durationMs === undefined
+                ? `Participant ${spec.planned.id}: ${phase.message}`
+                : `Participant ${spec.planned.id}: ${phase.message} (${phase.durationMs}ms)`,
+        });
+    }
+    return events;
+}
+/** One participant's simulation, stream and events, in the order the bundle records them. */
+export function fanoutParticipantRecords(ctx, spec, index) {
+    const view = fanoutParticipantView(ctx.args, spec, index);
+    return {
+        simulation: fanoutParticipantRecord(ctx.args, spec, index, view),
+        stream: fanoutParticipantStream(ctx.args, spec, view),
+        events: [...fanoutSubjectEvents(ctx, spec, view), ...fanoutOutcomeEvents(ctx, spec, view)],
+    };
+}

package/dist/routes/computer-use/in-process-desktop.d.ts

@@ -0,0 +1,17 @@
+import type { CuaActorDescriptor } from "../../actors/registry.js";
+import type { LabConfig } from "../../lab/types.js";
+import type { ParticipantDesktop } from "./participant-desktop.js";
+import type { CuaActorLabHooks } from "./types.js";
+/** What an in-process desktop reads: the caller's executor hook and the arguments it receives. */
+interface InProcessDesktopDeps {
+    config: LabConfig;
+    descriptor: CuaActorDescriptor;
+    appUrl: string;
+    hooks: Pick<CuaActorLabHooks, "buildExecutor">;
+}
+/**
+ * The caller's executor as a participant desktop. prepare acquires nothing; openSession builds the
+ * executor once; finalize is idempotent and has nothing to release; snapshot records no sandbox.
+ */
+export declare function createInProcessDesktop(deps: InProcessDesktopDeps): ParticipantDesktop;
+export {};

package/dist/routes/computer-use/in-process-desktop.js

@@ -0,0 +1,40 @@
+// The in-process route's desktop: the caller's own executor behind the four-method contract the
+// hosted and local-VM desktops implement. It acquires no sandbox, stream, subject or recording, so
+// its evidence claims none of them.
+/**
+ * The caller's executor as a participant desktop. prepare acquires nothing; openSession builds the
+ * executor once; finalize is idempotent and has nothing to release; snapshot records no sandbox.
+ */
+export function createInProcessDesktop(deps) {
+    let preparationStarted = false;
+    let opened = false;
+    let finalization;
+    return {
+        async prepare() {
+            if (preparationStarted || finalization)
+                throw new Error("Participant desktop preparation can only start once, before finalization.");
+            preparationStarted = true;
+        },
+        async openSession() {
+            if (!preparationStarted || opened || finalization)
+                throw new Error("The participant desktop must be prepared and may only be opened once, before finalization.");
+            opened = true;
+            const buildExecutor = deps.hooks.buildExecutor;
+            if (buildExecutor === undefined)
+                throw new Error("The in-process route needs hooks.buildExecutor.");
+            const executor = await buildExecutor({
+                config: deps.config,
+                actor: deps.descriptor,
+                appUrl: deps.appUrl,
+            });
+            return { executor };
+        },
+        finalize() {
+            return (finalization ??= Promise.resolve());
+        },
+        snapshot() {
+            // Nothing was acquired, so nothing is released and no sandbox fact is recorded.
+            return { released: false, streamUrlPresent: false, stateStepRecords: [], phaseRecords: [] };
+        },
+    };
+}

package/dist/routes/computer-use/lanes.d.ts

@@ -0,0 +1,35 @@
+import { type PreparedOutputRoot } from "../../run/contained-output.js";
+import type { CuaParticipantDeps, CuaParticipantPlan, CuaParticipantResult, DesktopParticipantRun, CuaSubjectProjection, ParticipantRunOutcome } from "./types.js";
+/** Build a lane's writeScreenshot closure: writes under screenshots/<screenshotDir>/ and records
+ *  the relative path the trace references (screenshots/<name> at N=1; screenshots/<laneId>/<name>
+ *  at N>1). */
+export declare function makeParticipantWriteScreenshot(artifactRoot: PreparedOutputRoot, spec: {
+    screenshotDir: string;
+}, screenshots: string[]): (name: string, bytes: Buffer) => Promise<string>;
+/** Run one participant against a prepared desktop. The adapter owns provisioning, final
+ * evidence and cleanup; this runner owns the model, trace and participant outcome. */
+export declare function runCuaParticipant(spec: DesktopParticipantRun, deps: CuaParticipantDeps): Promise<ParticipantRunOutcome>;
+/**
+ * Run N>1 E2B lanes with bounded concurrency, a pipeline gate (lane 1 provisions before the rest
+ * start), and session fail-fast on HARNESS errors only (queued lanes become `blocked` with a
+ * pinned reason + a fail-fast event; mission verdicts never trip it). Each lane tears down ITS
+ * OWN sandbox by id; nothing here ever enumerates.
+ *
+ * Exported for the #342 total-runner tests: the injectable runner lets a test make one lane
+ * THROW (the exact class the guard exists for) without a live sandbox. Production always uses
+ * the default.
+ */
+export declare function runCuaParticipants(runs: DesktopParticipantRun[], deps: Omit<CuaParticipantDeps, "signalProvisioned">, concurrency: number, runParticipant?: typeof runCuaParticipant): Promise<{
+    outcomes: ParticipantRunOutcome[];
+    failFastReason?: string;
+}>;
+/** Project one lane outcome (or a dry-run contract spec) into the public CuaParticipantResult. */
+export declare function toParticipantResult(spec: DesktopParticipantRun, outcome: ParticipantRunOutcome | undefined, subject: CuaSubjectProjection, dryRun: boolean): CuaParticipantResult;
+/**
+ * Run every lane of a live run. The in-process route drives its single lane in this process; one
+ * hosted lane runs alone; a fan-out runs at the plan's concurrency and may stop early.
+ */
+export declare function runAllCuaParticipants(runs: readonly DesktopParticipantRun[], deps: Omit<CuaParticipantDeps, "signalProvisioned">, participantPlan: CuaParticipantPlan, inProcessRoute: boolean): Promise<{
+    outcomes: ParticipantRunOutcome[];
+    failFastReason: string | undefined;
+}>;