humanish 0.104.3 → 0.106.0

package/dist/routes/computer-use/bundle-parts.d.ts

@@ -0,0 +1,50 @@
+import type { CuaLoopResult } from "../../actors/computer-use/loop.js";
+import { type RunFeedbackCandidate, type RunProviderResource, type RunSubjectProvenance } from "../../run/bundle.js";
+import { type ParticipantIds } from "../../run/participant-records.js";
+import { type CuaSubjectProvenanceArg, type ParticipantRunOutcome } from "./types.js";
+/** The human-readable state story appended to the provenance event (and review.md via it). */
+export declare function describeSubjectState(state: RunSubjectProvenance["state"], dryRun: boolean): string;
+/**
+ * Feedback candidates derived from what LIVE participants actually reported (#392).
+ *
+ * A live run's feedback draft used to fall through to a dry-run template, because no browser route
+ * ever built a candidate. The candidate worth filing is the one the study produced: a participant
+ * who reported friction on the way (the most valuable thing a run captures), or one who stopped
+ * trying. A clean pass files nothing here — feedback exists to carry findings, and a run without
+ * any falls back to an honest live summary in the draft layer instead of a template.
+ *
+ * Everything quoted is already scrub+redacted — participant messages and `session.reason` pass
+ * through redactNarration in the loop — and passes redactText again here as defense-in-depth.
+ */
+export declare function participantFeedbackCandidates(args: {
+    runId: string;
+    scenarioId: string;
+    adapterId: string;
+    /** The already-redacted study goal (what bundle.scenario.goal carries). */
+    goal: string;
+    substrate: RunFeedbackCandidate["substrate"];
+    participants: Array<{
+        /** The participant's plan id; it names the candidate and its idempotency key. */
+        participantId: string;
+        streamId: string;
+        personaId: string;
+        session?: CuaLoopResult;
+        traceArtifactPath?: string;
+        screenshots: string[];
+        commsArtifactPath?: string;
+    }>;
+}): RunFeedbackCandidate[];
+/** Human-readable provenance line for the single-lane subject.provenance event (invariant 5):
+ *  claims "cloned/packed and served" ONLY when it actually happened. */
+export declare function subjectProvenanceMessage(provenance: CuaSubjectProvenanceArg, publicAppUrl: string, dryRun: boolean, hasSession: boolean): string;
+export declare function providerResourcesForOutcome(args: {
+    outcome: ParticipantRunOutcome | undefined;
+    createdAt: string;
+    ids: ParticipantIds;
+    participantId: string;
+}): RunProviderResource[];
+export declare function publicSafeAppUrlLabel(url: string): string;
+/** Short id-safe suffix for a subject-phase RunEvent: drops the shared prefix/suffix so each
+ *  phase gets a distinct bundle event id (e.g. "clone", "state-before-build"). */
+export declare function phaseEventIdSuffix(type: string): string;
+export declare function digestUrl(url: string): string;

package/dist/routes/computer-use/bundle-parts.js

@@ -0,0 +1,177 @@
+// The parts both computer-use bundle shapes share: the subject-state story and provenance line,
+// feedback candidates from what live participants reported, provider-resource records, and the
+// public-safe app URL label, the URL digest and the subject-phase event id suffix. The builders are bundle.ts (the dispatcher and the judge),
+// single-bundle.ts and fanout-bundle.ts.
+import { feedbackProofCommands } from "../../feedback/proof.js";
+import { containsSensitive, digestText, redactText } from "../../evidence/redaction.js";
+import {} from "../../run/bundle.js";
+import { participantResourceIds } from "../../run/participant-records.js";
+import { resolveSelfReportedFriction } from "./self-report.js";
+import {} from "./types.js";
+/** The human-readable state story appended to the provenance event (and review.md via it). */
+export function describeSubjectState(state, dryRun) {
+    switch (state.provenance) {
+        case "seeded":
+            return `seeded (${state.seed?.length ?? 0} step(s): ${(state.seed ?? []).map((record) => record.name).join(", ")})`;
+        case "unpinned":
+            return `UNPINNED (external: ${(state.externalEnvNames ?? []).join(", ")})`;
+        case "declared-not-run":
+            return `declared, not run (${dryRun ? "dry-run contract" : "provisioning did not complete"})`;
+        case "undeclared":
+            return "undeclared";
+        case "external-public":
+            return "external-public (operator-declared, operator-owned public deployment; neither provisioned nor seeded)";
+    }
+}
+/**
+ * Feedback candidates derived from what LIVE participants actually reported (#392).
+ *
+ * A live run's feedback draft used to fall through to a dry-run template, because no browser route
+ * ever built a candidate. The candidate worth filing is the one the study produced: a participant
+ * who reported friction on the way (the most valuable thing a run captures), or one who stopped
+ * trying. A clean pass files nothing here — feedback exists to carry findings, and a run without
+ * any falls back to an honest live summary in the draft layer instead of a template.
+ *
+ * Everything quoted is already scrub+redacted — participant messages and `session.reason` pass
+ * through redactNarration in the loop — and passes redactText again here as defense-in-depth.
+ */
+export function participantFeedbackCandidates(args) {
+    const candidates = [];
+    for (const participant of args.participants) {
+        const session = participant.session;
+        if (session === undefined)
+            continue;
+        const friction = resolveSelfReportedFriction(session);
+        const abandoned = session.status === "abandoned";
+        if (friction === undefined && !abandoned)
+            continue;
+        const summary = friction !== undefined
+            ? `Participant ${participant.personaId} (${participant.participantId}) reported friction on the way through the study goal`
+            : `Participant ${participant.personaId} (${participant.participantId}) stopped before completing the study goal`;
+        const lastScreenshot = participant.screenshots[participant.screenshots.length - 1];
+        candidates.push({
+            schema: "humanish.feedback-candidate.v1",
+            id: `participant-report-${participant.participantId}`,
+            run_id: args.runId,
+            stream_id: participant.streamId,
+            adapter_id: args.adapterId,
+            scenario_id: args.scenarioId,
+            persona_id: participant.personaId,
+            actor: "computer-use",
+            substrate: args.substrate,
+            // The participant is reporting on the PRODUCT: friction and abandonment are target-app
+            // findings by the three-roles rule. A harness failure never reaches this builder — it is
+            // not a participant report.
+            failure_owner: "target-app",
+            summary,
+            expected: args.goal,
+            actual: redactText(friction ?? session.reason),
+            evidence: [
+                ...(participant.traceArtifactPath === undefined
+                    ? []
+                    : [
+                        {
+                            path: participant.traceArtifactPath,
+                            kind: "trace",
+                            note: "Full actor trace: turns, actions, and the participant's own report.",
+                        },
+                    ]),
+                ...(lastScreenshot === undefined
+                    ? []
+                    : [
+                        {
+                            path: lastScreenshot,
+                            kind: "screenshot",
+                            note: "Final screenshot at the moment the session ended.",
+                        },
+                    ]),
+                ...(participant.commsArtifactPath === undefined
+                    ? []
+                    : [
+                        {
+                            path: participant.commsArtifactPath,
+                            kind: "log",
+                            note: "Digest-only comms thread captured in-sandbox.",
+                        },
+                    ]),
+            ],
+            redaction: {
+                status: "passed",
+                notes: "Quoted participant text passed the loop's known-value scrub and pattern redaction before persisting, and redactText again here.",
+            },
+            idempotency_key: `humanish:${args.runId}:${participant.participantId}:participant-report`,
+            proposed_next_state: "study-quality-review",
+            acceptance_proof: [
+                feedbackProofCommands(args.runId).verify,
+                feedbackProofCommands(args.runId).watch,
+            ],
+        });
+    }
+    return candidates;
+}
+/** Human-readable provenance line for the single-lane subject.provenance event (invariant 5):
+ *  claims "cloned/packed and served" ONLY when it actually happened. */
+export function subjectProvenanceMessage(provenance, publicAppUrl, dryRun, hasSession) {
+    if (provenance.source === "clone") {
+        if (dryRun) {
+            return `Subject declared: clone of ${provenance.repo}, to be served at ${publicAppUrl} in-sandbox (dry-run contract; nothing cloned)`;
+        }
+        if (provenance.commit) {
+            return hasSession
+                ? `Subject cloned from ${provenance.repo}@${provenance.commit} and served at ${publicAppUrl} in-sandbox`
+                : `Subject cloned from ${provenance.repo}@${provenance.commit}; serving at ${publicAppUrl} did not complete (see session error)`;
+        }
+        return `Subject clone attempted from ${provenance.repo}; commit unresolved (provisioning failed before resolution)`;
+    }
+    if (dryRun) {
+        return `Subject declared: local working tree, to be packed and served at ${publicAppUrl} in-sandbox (dry-run contract; nothing packed)`;
+    }
+    if (provenance.archiveSha256) {
+        const dirtyLabel = provenance.dirty === true
+            ? ", dirty working tree"
+            : provenance.dirty === false
+                ? ", clean working tree"
+                : "";
+        return hasSession
+            ? `Subject packed (archiveSha256 ${provenance.archiveSha256}${dirtyLabel}) and served at ${publicAppUrl} in-sandbox`
+            : `Subject packed (archiveSha256 ${provenance.archiveSha256}${dirtyLabel}); serving at ${publicAppUrl} did not complete (see session error)`;
+    }
+    return "Subject local-tree packing attempted; archive digest unresolved (provisioning failed before resolution)";
+}
+export function providerResourcesForOutcome(args) {
+    if (args.outcome?.sandboxId === undefined) {
+        return [];
+    }
+    return [
+        {
+            schema: "humanish.provider-resource.v1",
+            provider: "e2b-desktop",
+            kind: "sandbox",
+            id: args.outcome.sandboxId,
+            owner: "humanish",
+            status: args.outcome.killed ? "killed" : "running",
+            ...participantResourceIds(args.ids, args.participantId),
+            createdAt: args.createdAt,
+            cleanup: {
+                killed: args.outcome.killed,
+                reason: args.outcome.killed
+                    ? "killed during normal participant teardown"
+                    : "not killed during normal participant teardown; cleanup may reclaim by exact recorded id",
+            },
+        },
+    ];
+}
+export function publicSafeAppUrlLabel(url) {
+    return containsSensitive(url) ? `[target-url:${digestUrl(url)}]` : url;
+}
+/** Short id-safe suffix for a subject-phase RunEvent: drops the shared prefix/suffix so each
+ *  phase gets a distinct bundle event id (e.g. "clone", "state-before-build"). */
+export function phaseEventIdSuffix(type) {
+    return type
+        .replace(/^cua-lab\.subject\./, "")
+        .replace(/\.(started|completed)$/, "")
+        .replace(/\./g, "-");
+}
+export function digestUrl(url) {
+    return digestText(url, 16);
+}

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

@@ -0,0 +1,56 @@
+import type { CuaActorDescriptor } from "../../actors/registry.js";
+import type { ComputerUsePlan } from "../../lab/plan-types.js";
+import type { RunBundle, RunRerunLineage } from "../../run/bundle.js";
+import type { RunLabProvenance } from "../../run/status.js";
+import { type Judgment } from "../../run/judge.js";
+import type { CuaParticipantPlan, DesktopParticipantRun, CuaSubjectProjection, CuaSubjectProvenanceArg, ParticipantRunOutcome } from "./types.js";
+/** What every bundle of one run shares, in progress or final. */
+export interface CuaRunBundleBase {
+    lab?: RunLabProvenance;
+    participantRuns: DesktopParticipantRun[];
+    descriptor: CuaActorDescriptor;
+    appUrl: string;
+    createdAt: string;
+    plan: ComputerUsePlan;
+    runId: string;
+    source: RunBundle["source"];
+    participantPlan: CuaParticipantPlan;
+    rerun?: RunRerunLineage;
+    redactScreenshots: boolean;
+    inProcessRoute: boolean;
+    localAppSubject: boolean;
+    cloneRoute: boolean;
+    localTreeRoute: boolean;
+    publicRepo?: string;
+    subjectEnvNames: string[];
+}
+/**
+ * The judgment for the current state of a computer-use run, by the rule for its shape: one
+ * participant (its tallied status is the verdict) or several (every lane must pass). The bundle's
+ * verdict and the lab result's ok both come from it.
+ */
+export declare function judgeComputerUseRun(base: Pick<CuaRunBundleBase, "participantRuns" | "rerun">, state: {
+    dryRun: boolean;
+    outcomes: ParticipantRunOutcome[] | undefined;
+    inProgress?: true;
+}): Judgment;
+/** The run's state a bundle is built from, in progress or final. */
+interface CuaRunBundleState {
+    judgment: Judgment;
+    dryRun: boolean;
+    outcomes: ParticipantRunOutcome[] | undefined;
+    subjects: CuaSubjectProjection[];
+    aggregateSubject: CuaSubjectProjection;
+    subjectProvenance: CuaSubjectProvenanceArg | undefined;
+    failFastReason?: string;
+    inProgress?: true;
+}
+/**
+ * The run bundle for the current state of a computer-use run. One participant without a rerun
+ * keeps the single-participant shape; a fan-out or a rerun uses the fan-out shape, which carries
+ * the participant plan and each participant's subject. Both argument mappings are here.
+ */
+export declare function buildCuaRunBundle(base: CuaRunBundleBase, state: CuaRunBundleState): RunBundle;
+/** The run's review.md: title, run, mode, gate, summary, subject, actor evidence and gaps. */
+export declare function renderCuaReviewMarkdown(bundle: RunBundle): string;
+export {};

package/dist/routes/computer-use/bundle.js

@@ -0,0 +1,184 @@
+// The computer-use route's judge and bundle builder. judgeComputerUseRun judges a run by its shape,
+// and buildCuaRunBundle sends it to the single-participant or the fan-out builder with that
+// shape's arguments. renderCuaReviewMarkdown writes review.md. shared-world/bundle.ts holds the
+// same for that route.
+import { judgeOneParticipant, judgeParticipants } from "../../run/judge.js";
+import { desktopSpanToMinutes } from "../../run/cost-summary.js";
+import { e2bDesktopTemplate } from "../../substrates/e2b/sandbox.js";
+import { providerResourcesForOutcome } from "./bundle-parts.js";
+import { participantFactsOf } from "./participant-facts.js";
+import { buildCuaFanoutBundle } from "./fanout-bundle.js";
+import { buildSingleParticipantBundle } from "./single-bundle.js";
+/** One participant without a rerun keeps the single-participant bundle shape and its rule. */
+function isOneParticipantRun(base) {
+    return base.participantRuns.length === 1 && base.rerun === undefined;
+}
+/**
+ * The judgment for the current state of a computer-use run, by the rule for its shape: one
+ * participant (its tallied status is the verdict) or several (every lane must pass). The bundle's
+ * verdict and the lab result's ok both come from it.
+ */
+export function judgeComputerUseRun(base, state) {
+    const inProgress = state.inProgress === true;
+    if (isOneParticipantRun(base)) {
+        const outcome = state.outcomes?.[0];
+        return judgeOneParticipant({
+            dryRun: state.dryRun,
+            inProgress,
+            participant: outcome === undefined ? undefined : participantFactsOf(outcome),
+        });
+    }
+    return judgeParticipants({
+        dryRun: state.dryRun,
+        inProgress,
+        expected: base.participantRuns.length,
+        participants: (state.outcomes ?? []).map(participantFactsOf),
+    });
+}
+/**
+ * The run bundle for the current state of a computer-use run. One participant without a rerun
+ * keeps the single-participant shape; a fan-out or a rerun uses the fan-out shape, which carries
+ * the participant plan and each participant's subject. Both argument mappings are here.
+ */
+export function buildCuaRunBundle(base, state) {
+    const lab = base.lab === undefined ? {} : { lab: base.lab };
+    const inProgress = state.inProgress === undefined ? {} : { inProgress: true };
+    if (isOneParticipantRun(base))
+        return buildSingleParticipantBundle(singleParticipantArgs(base, state));
+    return buildCuaFanoutBundle({
+        verdict: state.judgment.verdict,
+        ...lab,
+        specs: base.participantRuns,
+        ...(state.outcomes === undefined ? {} : { outcomes: state.outcomes }),
+        subjects: state.subjects,
+        aggregateSubject: state.aggregateSubject,
+        descriptor: base.descriptor,
+        appUrl: base.appUrl,
+        createdAt: base.createdAt,
+        dryRun: state.dryRun,
+        plan: base.plan,
+        runId: base.runId,
+        source: base.source,
+        participantPlan: base.participantPlan,
+        ...(base.rerun === undefined ? {} : { rerun: base.rerun }),
+        ...(state.failFastReason === undefined ? {} : { failFastReason: state.failFastReason }),
+        cloneRoute: base.cloneRoute,
+        localTreeRoute: base.localTreeRoute,
+        ...(base.publicRepo === undefined ? {} : { publicRepo: base.publicRepo }),
+        subjectEnvNames: base.subjectEnvNames,
+        ...inProgress,
+    });
+}
+/** The single-participant builder's arguments, from the run's base and current state. */
+function singleParticipantArgs(base, state) {
+    const spec = base.participantRuns[0];
+    const outcome = state.outcomes?.[0];
+    const { plan } = base;
+    const desktopTemplate = e2bDesktopTemplate(plan.residual);
+    return {
+        verdict: state.judgment.verdict,
+        realEmail: plan.residual.comms?.email?.kind === "real",
+        ...(base.lab === undefined ? {} : { lab: base.lab }),
+        actorId: base.descriptor.id,
+        appUrl: spec.planned.targetUrl ?? base.appUrl,
+        participantId: spec.planned.id,
+        ...(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 }),
+        createdAt: base.createdAt,
+        dryRun: state.dryRun,
+        labId: plan.labId,
+        ...(plan.title ? { labTitle: plan.title } : {}),
+        mission: spec.evidenceInstructions ?? spec.instructions,
+        ...(spec.evidenceAssignment === undefined ? {} : { assignment: spec.evidenceAssignment }),
+        persona: spec.persona,
+        resolution: spec.planned.device.resolution,
+        desktopRoute: !base.inProcessRoute,
+        substrate: base.inProcessRoute
+            ? "local-filesystem"
+            : plan.residual.execution?.target === "local"
+                ? "local-desktop"
+                : "e2b-desktop",
+        ...(outcome?.desktopGeometry === undefined ? {} : { desktopGeometry: outcome.desktopGeometry }),
+        ...(outcome?.recording === undefined ? {} : { recording: outcome.recording }),
+        isMobile: spec.planned.device.preset.isMobile,
+        runId: base.runId,
+        screenshots: outcome?.screenshots ?? [],
+        captureRedaction: base.redactScreenshots ? "blurred" : "raw",
+        ...(outcome?.session ? { session: outcome.session } : {}),
+        ...(outcome?.sessionError !== undefined ? { sessionError: outcome.sessionError } : {}),
+        ...(outcome === undefined
+            ? {}
+            : {
+                credibility: {
+                    noEngagement: outcome.noEngagement === true,
+                    selfReportedBlocker: outcome.selfReportedBlocker === true,
+                    reportedFriction: outcome.reportedFriction === true,
+                },
+            }),
+        source: base.source,
+        ...(state.inProgress === undefined ? {} : { inProgress: state.inProgress }),
+        ...(state.subjectProvenance === undefined
+            ? {}
+            : { subjectProvenance: state.subjectProvenance }),
+        ...(desktopTemplate === undefined ? {} : { desktopTemplate }),
+        ...(outcome?.desktopBrowser === undefined ? {} : { desktopBrowser: outcome.desktopBrowser }),
+        providerResources: providerResourcesForOutcome({
+            outcome,
+            createdAt: base.createdAt,
+            ids: spec,
+            participantId: spec.planned.id,
+        }),
+        ...(base.localAppSubject || base.inProcessRoute ? { entryKind: "local-app" } : {}),
+        ...(outcome?.session ? { traceArtifactPath: spec.traceArtifactPath } : {}),
+        ...(outcome?.commsArtifactPath === undefined
+            ? {}
+            : { commsArtifactPath: outcome.commsArtifactPath }),
+        ...(desktopSpanToMinutes(outcome?.desktopDurationMs) === undefined
+            ? {}
+            : { desktopMinutes: desktopSpanToMinutes(outcome?.desktopDurationMs) }),
+        ...(outcome?.sandboxId === undefined
+            ? {}
+            : {
+                desktopUsage: {
+                    participantId: spec.planned.id,
+                    minutes: desktopSpanToMinutes(outcome.desktopDurationMs),
+                    observation: outcome.desktopResources,
+                    lifetimeComplete: outcome.killed,
+                },
+            }),
+        phaseEvents: outcome?.phaseRecords ?? [],
+    };
+}
+/** The run's review.md: title, run, mode, gate, summary, subject, actor evidence and gaps. */
+export function renderCuaReviewMarkdown(bundle) {
+    const trace = bundle.streams[0]?.actor;
+    const provenance = bundle.events.find((event) => event.type === "cua-lab.subject.provenance");
+    return [
+        `# ${bundle.scenario.title}`,
+        "",
+        `- run: ${bundle.runId}`,
+        `- mode: ${bundle.mode}`,
+        `- run gate: ${bundle.review.verdict}`,
+        `- summary: ${bundle.review.summary}`,
+        ...(provenance ? [`- subject: ${provenance.message}`] : []),
+        ...(trace
+            ? [
+                `- actor: ${trace.provider} (${trace.lane}/${trace.protocol})`,
+                // Honest count: name the trace's actual screenshot mode ("raw" | "blurred"); say
+                // nothing when no frames exist ("n/a") rather than claim a redaction that never ran.
+                `- evidence: ${trace.items.length} trace item(s), ${trace.counts.screenshots ?? 0} ${trace.redaction.screenshots === "raw" || trace.redaction.screenshots === "blurred"
+                    ? `${trace.redaction.screenshots} screenshot(s)`
+                    : "screenshot(s)"}`,
+            ]
+            : []),
+        ...(bundle.review.gaps.length > 0
+            ? ["", "## Gaps", ...bundle.review.gaps.map((gap) => `- ${gap}`)]
+            : []),
+        "",
+    ].join("\n");
+}

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

@@ -0,0 +1,38 @@
+import { type ActorCompletionReason, type ActorStatus, type ActorStopCause } from "../../actors/contract.js";
+/** Diagnostic categories describe the instrument's result, never prove a target-app defect. */
+declare const CUA_DIAGNOSTIC_CATEGORIES: readonly ["preview", "participant_outcome", "session_interrupted", "execution_error", "evidence_invalid", "mixed", "unknown"];
+export type CuaDiagnosticCategory = (typeof CUA_DIAGNOSTIC_CATEGORIES)[number];
+/** Closed at both projection and telemetry boundaries. No provider messages are classified. */
+declare const CUA_DIAGNOSTIC_STOP_CAUSES: readonly ["provider_output_limit", "provider_token_limit", "time_limit", "spend_limit", "study_spend_limit", "adapter_limit", "provider_incomplete", "provider_status", "provider_refused_prompt", "harness_aborted", "usage_unreported", "unspecified_limit", "mixed", "unknown"];
+export type CuaDiagnosticStopCause = (typeof CUA_DIAGNOSTIC_STOP_CAUSES)[number];
+export interface CuaDiagnostics {
+    category: CuaDiagnosticCategory;
+    stopCause?: CuaDiagnosticStopCause;
+}
+export declare const isCuaDiagnosticCategory: (value: unknown) => value is CuaDiagnosticCategory;
+export declare const isCuaDiagnosticStopCause: (value: unknown) => value is CuaDiagnosticStopCause;
+interface SessionEnding {
+    status: ActorStatus;
+    completionReason: ActorCompletionReason;
+    stopCause?: ActorStopCause;
+}
+export declare function cuaParticipantDiagnostics(input: {
+    dryRun: boolean;
+    skipped?: boolean;
+    executionError?: boolean;
+    noEngagement?: boolean;
+    session?: SessionEnding;
+}): CuaDiagnostics;
+/** Each lane retains its details. The summary never borrows lane one's ending for other lanes. */
+export declare function summarizeCuaDiagnostics(input: {
+    dryRun: boolean;
+    evidenceInvalid: boolean;
+    participants: readonly {
+        status: string;
+        ok: boolean;
+        diagnostics?: CuaDiagnostics;
+    }[];
+}): CuaDiagnostics;
+export declare function formatCuaStopCause(cause: CuaDiagnosticStopCause): string;
+export declare function formatCuaDiagnostics(diagnostics: CuaDiagnostics): string;
+export {};

package/dist/routes/computer-use/diagnostics.js

@@ -0,0 +1,94 @@
+import { actorStopCauseLabel } from "../../actors/stop-cause.js";
+import { ACTOR_STOP_CAUSES, } from "../../actors/contract.js";
+/** Diagnostic categories describe the instrument's result, never prove a target-app defect. */
+const CUA_DIAGNOSTIC_CATEGORIES = [
+    "preview",
+    "participant_outcome",
+    "session_interrupted",
+    "execution_error",
+    "evidence_invalid",
+    "mixed",
+    "unknown",
+];
+/** Closed at both projection and telemetry boundaries. No provider messages are classified. */
+const CUA_DIAGNOSTIC_STOP_CAUSES = [
+    ...ACTOR_STOP_CAUSES,
+    "unspecified_limit",
+    "mixed",
+    "unknown",
+];
+export const isCuaDiagnosticCategory = (value) => typeof value === "string" && CUA_DIAGNOSTIC_CATEGORIES.includes(value);
+export const isCuaDiagnosticStopCause = (value) => typeof value === "string" && CUA_DIAGNOSTIC_STOP_CAUSES.includes(value);
+export function cuaParticipantDiagnostics(input) {
+    if (input.dryRun)
+        return { category: "preview" };
+    // A skipped follower never started; it has no participant ending or proved execution error.
+    if (input.skipped)
+        return { category: "unknown" };
+    if (input.executionError)
+        return { category: "execution_error" };
+    const session = input.session;
+    if (!session)
+        return { category: "unknown" };
+    if (session.stopCause !== undefined) {
+        return {
+            category: "session_interrupted",
+            stopCause: isCuaDiagnosticStopCause(session.stopCause) ? session.stopCause : "unknown",
+        };
+    }
+    if (session.completionReason === "budget_reached")
+        return { category: "session_interrupted", stopCause: "unspecified_limit" };
+    if (session.completionReason === "timed_out")
+        return { category: "session_interrupted", stopCause: "time_limit" };
+    if (session.completionReason === "actor_error" || session.completionReason === "harness_error")
+        return { category: "execution_error" };
+    if (input.noEngagement)
+        return { category: "unknown" };
+    return [
+        "goal_satisfied",
+        "turn_completed",
+        "gave_up",
+        "blocked_approval",
+        "step_failed",
+    ].includes(session.completionReason)
+        ? { category: "participant_outcome" }
+        : { category: "unknown" };
+}
+/** Each lane retains its details. The summary never borrows lane one's ending for other lanes. */
+export function summarizeCuaDiagnostics(input) {
+    if (input.evidenceInvalid)
+        return { category: "evidence_invalid" };
+    if (input.dryRun)
+        return { category: "preview" };
+    if (input.participants.length === 0)
+        return { category: "unknown" };
+    const diagnostics = input.participants.map((participant) => participant.diagnostics ?? { category: "unknown" });
+    const signatures = input.participants.map((participant, index) => JSON.stringify([
+        diagnostics[index].category,
+        diagnostics[index].stopCause,
+        participant.status,
+        participant.ok,
+    ]));
+    const endings = new Set(signatures);
+    const causes = new Set(diagnostics.map((item) => item.stopCause ?? "unknown"));
+    const hasCause = diagnostics.some((item) => item.stopCause !== undefined);
+    return {
+        category: endings.size === 1 ? diagnostics[0].category : "mixed",
+        ...(hasCause ? { stopCause: causes.size === 1 ? diagnostics[0].stopCause : "mixed" } : {}),
+    };
+}
+const categoryLabels = {
+    preview: "preview",
+    participant_outcome: "participant outcome",
+    session_interrupted: "session interrupted",
+    execution_error: "execution error",
+    evidence_invalid: "invalid evidence",
+    mixed: "mixed endings",
+    unknown: "unknown ending",
+};
+export function formatCuaStopCause(cause) {
+    return cause === "mixed" || cause === "unknown" ? cause : actorStopCauseLabel(cause);
+}
+export function formatCuaDiagnostics(diagnostics) {
+    return `${categoryLabels[diagnostics.category]}${diagnostics.stopCause ? ` (${formatCuaStopCause(diagnostics.stopCause)})` : ""}`;
+}

package/dist/routes/computer-use/e2b-desktop/comms.d.ts

@@ -0,0 +1,65 @@
+import { type OriginMap } from "../../../comms/capture-surface.js";
+import { type DeployedCommsCatch } from "../../../comms/sandbox-catch.js";
+import type { LabCommsEmail, LabConfig } from "../../../lab/types.js";
+import type { Shell } from "../../../substrates/shell.js";
+import type { ReadyParticipantDesktop } from "../participant-desktop.js";
+import type { CuaParticipantDeps, DesktopParticipantRun } from "../types.js";
+/** A lane's captured-email wiring, decided from config before the sandbox exists. */
+export interface ParticipantComms {
+    readonly email: LabCommsEmail;
+    readonly port: number;
+    readonly smtpPort: number | undefined;
+    /** The loopback URL the persona opens to read captured mail. */
+    readonly inboxUrl: string;
+    readonly originMap: OriginMap;
+    readonly surfaceRecipients: {
+        participantId: string;
+        address: string;
+    }[];
+}
+/**
+ * On an in-sandbox subject route, redirect the app's email-API sends into an in-sandbox catch
+ * (loopback) so its verification mail is CAPTURED, not sent to the internet. Undefined when the
+ * lab declares no fake email, which leaves the lane unchanged.
+ */
+export declare function planParticipantComms(config: LabConfig, targetUrl: string, inSandboxSubject: boolean): ParticipantComms | undefined;
+/** The env the subject app reads to reach the catch, injected at sandbox create so it boots with it. */
+export declare function participantCommsEnv(comms: ParticipantComms | undefined): Record<string, string>;
+/** A started catch and the stop for its inbox-surface loop. */
+export interface RunningCommsCatch {
+    readonly deployed: DeployedCommsCatch;
+    /** Stop the surface loop and wait for it; never throws. */
+    stopSurface(): Promise<void>;
+}
+/**
+ * Start the in-sandbox email catch before the subject serve, so the app's send-API base URL
+ * resolves the moment it boots. A comms-declared lab that cannot stand the catch up fails closed
+ * rather than silently sending real mail.
+ */
+export declare function startCommsCatch(shell: Shell, comms: ParticipantComms, requestTimeoutMs: number): Promise<RunningCommsCatch>;
+/** Stand up the real-email receiving surface and attach it to the lane; returns the inbox URL. */
+export declare function attachReceivingInbox(shell: Shell, spec: DesktopParticipantRun, deps: CuaParticipantDeps & {
+    receiving: NonNullable<CuaParticipantDeps["receiving"]>;
+}, targetUrl: string): Promise<string>;
+/** The inbox the persona is told about: real receiving, the captured catch, or an external inbox. */
+export declare function participantInbox(args: {
+    spec: DesktopParticipantRun;
+    deps: CuaParticipantDeps;
+    receivingInboxUrl: string | undefined;
+    comms: ParticipantComms | undefined;
+    catchReady: boolean;
+}): ReadyParticipantDesktop["inbox"];
+/**
+ * Before this lane's sandbox is torn down, drain everything the in-sandbox catch captured, route it
+ * into a host fake inbox addressed to the declared recipients, and write the digest-only thread
+ * artifact. Returns the artifact path when one was written. A drain failure is a warning and never
+ * breaks teardown: the sandbox must still be killed either way.
+ */
+export declare function drainCommsEvidence(args: {
+    shell: Shell;
+    comms: ParticipantComms;
+    deployed: DeployedCommsCatch;
+    spec: DesktopParticipantRun;
+    deps: CuaParticipantDeps;
+    warnings: string[];
+}): Promise<string | undefined>;