@jevitate/cli 0.12.0 → 0.13.0

package/dist/ux-usability/loop.d.ts

@@ -0,0 +1,15 @@
+import { type GoalBasedResult, BudgetMonitor } from "@jevitate/explore";
+import type { UsabilitySetup } from "./setup.js";
+/**
+ * Phase 2 — the act loop: the Journey prefix (if any), the budget hooks, then the model-driven loop —
+ * through the goal mission's independent adjudication when `successChecks` were given, else
+ * `explore()` — and the drained server-log transcript, Recording and transcript written.
+ */
+export declare function runUsabilityLoop(ctx: UsabilitySetup): Promise<{
+    start: import("../journey-prefix.js").AnchoredStart;
+    budget: BudgetMonitor | null;
+    adjudication: GoalBasedResult | undefined;
+    run: import("@jevitate/explore").ExploreRun;
+    serverLogRun: import("../log-correlation.js").ServerLogRuntimeResult | undefined;
+}>;
+export type UsabilityLoop = Awaited<ReturnType<typeof runUsabilityLoop>>;

package/dist/ux-usability/loop.js

@@ -0,0 +1,104 @@
+// ux-usability/loop.ts — phase 2 of `runUsabilityMission` (#500): the model-driven act loop.
+import { journeyFixtureBaseDir } from "../journey-api.js";
+import { demoOverlayOf } from "../browser-run-options.js";
+import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
+import { explore, runGoalBasedMission, InvariantMonitor, BudgetMonitor } from "@jevitate/explore";
+import { conversationConfig } from "../conversation-options.js";
+import { startFromJourney } from "../journey-prefix.js";
+import { usabilityOnSnapshot } from "./observe.js";
+/**
+ * Phase 2 — the act loop: the Journey prefix (if any), the budget hooks, then the model-driven loop —
+ * through the goal mission's independent adjudication when `successChecks` were given, else
+ * `explore()` — and the drained server-log transcript, Recording and transcript written.
+ */
+export async function runUsabilityLoop(ctx) {
+    const { opts, session, origin, serverLog, journalListener, journal, health, uxSecretCommand, fixture, capture } = ctx;
+    // #293: a journey-anchored review first replays its Journey's prefix into this very session.
+    const start = await startFromJourney(opts.journeyPrefix, session, opts.url, opts.allowlist, opts.browser);
+    const actor = CastActor.named("usability-mission").whoCan(new BrowseTheWeb(session, [...opts.allowlist]));
+    // #150 — usability's own budget wiring: a plain `InvariantMonitor` reads a budget's declared
+    // observables (the same #86/#135 read/auth/redaction machinery), but this mission folds NO
+    // invariant defects — only a budget crossing can end the run early, via the same pre-action
+    // guard / post-settle hooks `explore()` offers every mission.
+    const budgetDecls = opts.invariants?.budget ?? [];
+    const invariantMonitor = opts.invariants === undefined || budgetDecls.length === 0
+        ? null
+        : new InvariantMonitor(opts.invariants, {
+            allowlist: opts.allowlist,
+            baseUrl: opts.url,
+            ...(opts.secrets === undefined ? {} : { secrets: opts.secrets }),
+            ...(opts.invariantAuthTokens === undefined ? {} : { authTokens: opts.invariantAuthTokens }),
+        });
+    const budget = invariantMonitor === null ? null : new BudgetMonitor(budgetDecls, invariantMonitor);
+    let budgetSettledSteps = 0;
+    const exploreCfg = {
+        ...(opts.target?.timing === undefined ? {} : { timingConfig: opts.target.timing }),
+        ...(opts.target?.settle === undefined ? {} : { settle: opts.target.settle }),
+        ...(opts.target?.hangs === undefined ? {} : { hangs: opts.target.hangs }),
+        ...(opts.target?.safety === undefined ? {} : { safety: opts.target.safety }),
+        onTranscriptEntry: serverLog?.onTranscriptEntry ?? journalListener,
+        onRecording: journal.onRecording,
+        // #303 (opt-in): action deltas, with Jev's advisory relevance labels.
+        ...(opts.actionDeltas === true ? { actionDeltas: { jev: true } } : {}),
+        hostHealth: health,
+        demoOverlay: demoOverlayOf(opts.browser),
+        ...(opts.secretFields === undefined ? {} : { secretFields: opts.secretFields }),
+        ...(uxSecretCommand === undefined ? {} : { secretCommand: uxSecretCommand }),
+        ...(opts.secretCommandAttempts === undefined ? {} : { secretCommandAttempts: opts.secretCommandAttempts }),
+        actor,
+        judge: opts.judge,
+        gen: opts.gen,
+        goal: opts.job,
+        allowlist: opts.allowlist,
+        startUrl: start.url,
+        ...(start.branch === undefined ? {} : { startInPlace: true }),
+        ...(start.restart === undefined ? {} : { restartAtStart: start.restart.restartAtStart }),
+        bounds: opts.bounds,
+        secrets: opts.secrets,
+        site: origin,
+        fixture,
+        fixtureRoot: journeyFixtureBaseDir(),
+        ...conversationConfig(opts.conversation),
+        onSnapshot: usabilityOnSnapshot(ctx),
+        ...(budget === null
+            ? {}
+            : {
+                onBeforeAction: async (info) => {
+                    const g = await budget.guard(session.page, info);
+                    return g.refuse ? { refuse: true, reason: g.reason ?? "budget guard refused the action" } : { refuse: false };
+                },
+                onSettled: async () => {
+                    budgetSettledSteps += 1;
+                    // The FIRST settled snapshot (before any action) is the budget's baseline.
+                    if (budgetSettledSteps === 1) {
+                        const b = await budget.baseline(session.page);
+                        return b.crossed ? { stop: true, reason: b.reason ?? "budget observable unreadable at run start" } : { stop: false };
+                    }
+                    const r = await budget.afterSettle(session.page, budgetSettledSteps);
+                    return r.crossed ? { stop: true, reason: r.reason ?? "mission budget crossed" } : { stop: false };
+                },
+            }),
+    };
+    const brief = "usability review: pursue the stated job as a plausible first-time user, using only what is on screen";
+    // #225: `--success` is never ignored — with checks the loop runs through the goal mission's
+    // independent adjudication (the same oracle, `held`/vacuous rules and verdict as a goal run).
+    const checks = opts.successChecks ?? [];
+    const adjudication = checks.length === 0
+        ? undefined
+        : await runGoalBasedMission({
+            ...exploreCfg,
+            missionBrief: brief,
+            successChecks: checks,
+            // #225: a `done` whose check failed on a job judged done ends the run — never the whole budget.
+            stopWhenJudgedDone: true,
+            ...(opts.successWhen === undefined ? {} : { successWhen: opts.successWhen }),
+            ...(opts.allowVacuousChecks === true ? { allowVacuousChecks: true } : {}),
+        });
+    const run = adjudication?.run ?? (await explore({ ...exploreCfg, missionContext: brief }));
+    // Never blocks the mission itself: the drain wait happens AFTER `explore()` returned.
+    const serverLogRun = serverLog === undefined ? undefined : await serverLog.finish(run.transcript);
+    journal.writeRecording(run.recording);
+    journal.writeTranscript(capture.withScreenshots(serverLogRun?.transcript ?? run.transcript));
+    return { start, budget, adjudication, run, serverLogRun };
+}
+//# sourceMappingURL=loop.js.map

package/dist/ux-usability/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../../src/ux-usability/loop.ts"],"names":[],"mappings":"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"}

package/dist/ux-usability/observe.d.ts

@@ -0,0 +1,7 @@
+import { type ExploreConfig } from "@jevitate/explore";
+import type { UsabilitySetup } from "./setup.js";
+/**
+ * Phase 2a — the act loop's `onSnapshot` hook: one screen's evidence per observation, its
+ * (secret-masked) screenshot and the overflow/clipping hard signals. Never gates the loop.
+ */
+export declare function usabilityOnSnapshot(ctx: UsabilitySetup): NonNullable<ExploreConfig["onSnapshot"]>;

package/dist/ux-usability/observe.js

@@ -0,0 +1,89 @@
+// ux-usability/observe.ts — the usability act loop's per-screen observation hook (#500).
+import { clippingSummary, detectClipping, detectOverflow, shouldCheckOverflow } from "@jevitate/explore";
+import { makeSignalFinding } from "@jevitate/ux";
+import { snapshotToEvidence } from "../ux-evidence.js";
+/**
+ * Phase 2a — the act loop's `onSnapshot` hook: one screen's evidence per observation, its
+ * (secret-masked) screenshot and the overflow/clipping hard signals. Never gates the loop.
+ */
+export function usabilityOnSnapshot(ctx) {
+    const { opts, extract, session, collected, history, capture, seenOverflow, overflowFindings, secrets } = ctx;
+    return async (snap) => {
+        let visibleText = "";
+        try {
+            visibleText = await extract(session);
+        }
+        catch {
+            visibleText = ""; // best-effort; the analyzer Skips visibleText items honestly
+        }
+        const ev = snapshotToEvidence(snap, visibleText, opts.appContext, opts.job, [...history]);
+        collected.push(ev);
+        history.push({ screenId: ev.screenId, url: ev.url });
+        // #98 the step's (secret-masked) screenshot; #96 the screen's facts for the signal oracles.
+        await capture.observe(snap, visibleText);
+        // #149: horizontal-overflow hard signal — pure DOM geometry, never a model judgment.
+        // Best-effort like visibleText extraction above: a detection failure never fails the mission.
+        try {
+            const vp = session.page.viewportSize();
+            if (shouldCheckOverflow(vp?.width, opts.overflow?.checkOverflow ?? false)) {
+                const overflow = await detectOverflow(session.page, {
+                    viewport: vp ?? { width: 1280, height: 720 },
+                    ...(opts.emulation?.device === undefined ? {} : { device: opts.emulation.device }),
+                    ...(opts.overflow?.toleranceCss === undefined ? {} : { toleranceCss: opts.overflow.toleranceCss }),
+                    ...(opts.overflow?.ignoreSelectors === undefined ? {} : { ignoreSelectors: opts.overflow.ignoreSelectors }),
+                    secrets,
+                });
+                if (overflow !== null && !seenOverflow.has(overflow.fingerprint)) {
+                    seenOverflow.add(overflow.fingerprint);
+                    overflowFindings.push(makeSignalFinding({
+                        kind: "horizontal-overflow",
+                        confidence: 0.9,
+                        url: ev.url,
+                        screenId: ev.screenId,
+                        observation: `${overflow.element.descriptor} overflows the ${overflow.viewport.width}px viewport by ${overflow.overflowPx}px on ${overflow.route}.`,
+                        userImpact: "Content extends past the visible viewport; a user on this device must discover and use horizontal scrolling to see it, and may miss it entirely.",
+                        recommendation: `Constrain ${overflow.element.descriptor} to the viewport width (e.g. a responsive layout, or an explicit scroll container) at ${overflow.viewport.width}px.`,
+                        controls: [overflow.element.descriptor],
+                        evidence: {
+                            kind: "horizontal-overflow",
+                            steps: [history.length],
+                            requests: [],
+                            detail: `scrollWidth exceeds innerWidth by ${overflow.overflowPx}px at a ${overflow.viewport.width}x${overflow.viewport.height} viewport`,
+                        },
+                    }));
+                }
+                // #302: text cut off vertically (a fixed-height box, or above the page top) — one finding per element.
+                const clipped = await detectClipping(session.page, {
+                    viewport: vp ?? { width: 1280, height: 720 },
+                    ...(opts.emulation?.device === undefined ? {} : { device: opts.emulation.device }),
+                    ...(opts.overflow?.ignoreSelectors === undefined ? {} : { ignoreSelectors: opts.overflow.ignoreSelectors }),
+                    secrets,
+                });
+                for (const c of clipped) {
+                    if (seenOverflow.has(c.fingerprint))
+                        continue;
+                    seenOverflow.add(c.fingerprint);
+                    overflowFindings.push(makeSignalFinding({
+                        kind: "vertical-clipping",
+                        confidence: 0.9,
+                        url: ev.url,
+                        screenId: ev.screenId,
+                        observation: c.cause === "overflow-hidden"
+                            ? `${c.element.descriptor} cuts off its text by ${c.clippedPx}px on ${c.route}: the content is taller than the box and overflow is hidden.`
+                            : `${c.element.descriptor} is cut off ${c.clippedPx}px above the top of the page on ${c.route}.`,
+                        userImpact: "Part of the text is cut off and no scroll position shows it: a user on this device cannot read it.",
+                        recommendation: c.cause === "overflow-hidden"
+                            ? `Let ${c.element.descriptor} grow with its content (min-height instead of height), make it scrollable, or truncate on purpose with line-clamp at ${c.viewport.width}px.`
+                            : `Give the container of ${c.element.descriptor} room for its wrapped content (no fixed height, or no wrapping) at ${c.viewport.width}px.`,
+                        controls: [c.element.descriptor],
+                        evidence: { kind: "vertical-clipping", steps: [history.length], requests: [], detail: clippingSummary(c) },
+                    }));
+                }
+            }
+        }
+        catch {
+            // Best-effort: the run's own explore loop is never held up or failed by this check.
+        }
+    };
+}
+//# sourceMappingURL=observe.js.map

package/dist/ux-usability/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/ux-usability/observe.ts"],"names":[],"mappings":"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"}

package/dist/ux-usability/result.d.ts

@@ -0,0 +1,11 @@
+import type { HangFinding } from "@jevitate/explore";
+import type { RunUsabilityMissionResult } from "../ux-usability.js";
+import type { UsabilitySetup } from "./setup.js";
+import type { UsabilityLoop } from "./loop.js";
+import type { UsabilityAnalysis } from "./analysis.js";
+import type { UsabilityVerdict } from "./done-adjudication.js";
+/**
+ * Phase 6 — result: every context closed (videos finalized), the result's common fields, then the
+ * report (or the typed analysis-unavailable result), persisted and returned with its run evidence.
+ */
+export declare function writeUsabilityResult(ctx: UsabilitySetup, loop: UsabilityLoop, analysis: UsabilityAnalysis, hang: HangFinding | undefined, verdict: UsabilityVerdict): Promise<RunUsabilityMissionResult>;

package/dist/ux-usability/result.js

@@ -0,0 +1,113 @@
+// ux-usability/result.ts — phase 6 of `runUsabilityMission` (#500): the report and the typed, persisted result.
+import { writeFile } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
+import { finalizeVideos } from "../browser-run-options.js";
+import { evidenceOf, withRunEvidence } from "../defect-evidence.js";
+import { buildReport, calibrationCaveat, claimsCaveat, groundFindings, withSignalFindings } from "@jevitate/ux";
+import { NO_PRODUCT_FACTS_CAVEAT } from "../ux-product.js";
+import { resultPathFor, writeMissionResult } from "../mission-journal.js";
+import { MISSION_RESULT_SCHEMA_VERSION, advisoryDefects, defectFields } from "../result-schema.js";
+import { missionExitCode } from "../mission-exit.js";
+import { branchFields } from "../journey-prefix.js";
+import { failureWithHostStarved } from "../host-health-run.js";
+import { currentEngineInfo } from "../engine.js";
+import { triageOf } from "../explore-shared.js";
+import { serverLogResult } from "../explore-api.js";
+import { UxAnalysisFailedError } from "../ux-review.js";
+/**
+ * Phase 6 — result: every context closed (videos finalized), the result's common fields, then the
+ * report (or the typed analysis-unavailable result), persisted and returned with its run evidence.
+ */
+export async function writeUsabilityResult(ctx, loop, analysis, hang, verdict) {
+    const { opts, runCapture, videoDir, closeSession, journal, collected, screenshotDir, capture, runUsage, http5xx, secrets, minConfidence, quality, maxFindingsPerRoute, product, reportPath } = ctx;
+    const { start, run, serverLogRun, budget, adjudication } = loop;
+    const { signalFindings, friction, outcome, evidenceWritten } = analysis;
+    const { host, runOutcome, jobFailure } = verdict;
+    // #245: every context closed (videos finalized) before the result naming them is written.
+    const shotFields = await runCapture.finish();
+    const videos = await finalizeVideos(videoDir, closeSession);
+    const base = {
+        schemaVersion: MISSION_RESULT_SCHEMA_VERSION,
+        strategy: "usability",
+        target: {
+            seedUrl: start.persistUrl,
+            allowlist: [...opts.allowlist],
+            ...(opts.storageState !== undefined ? { storageStatePath: resolvePath(opts.storageState) } : {}),
+        },
+        ...branchFields(start),
+        recordingPaths: [journal.recordingPath],
+        ...videos,
+        ...shotFields,
+        resultPath: resultPathFor(journal.recordingPath),
+        hangs: hang === undefined ? [] : [hang],
+        timing: run.timing,
+        stop: run.stop,
+        outcome: run.outcome,
+        ...(run.answer === undefined ? {} : { answer: run.answer }),
+        screensObserved: collected.length,
+        transcriptPath: journal.transcriptPath,
+        screenshotDir,
+        evidencePath: evidenceWritten,
+        screenshots: capture.screenshots(),
+        sideEffects: run.sideEffects,
+        ...(run.sideEffectsTruncated === undefined ? {} : { sideEffectsTruncated: run.sideEffectsTruncated }),
+        ...(run.safetyOverrides === undefined ? {} : { safetyOverrides: run.safetyOverrides }),
+        ...(run.actionDeltas === undefined ? {} : { actionDeltas: run.actionDeltas }),
+        engine: currentEngineInfo(),
+        ...(() => {
+            const f = failureWithHostStarved(host, run.failure ?? host.failure ?? jobFailure);
+            return f === undefined ? {} : { failure: f };
+        })(),
+        ...(run.crash === undefined ? {} : { crash: run.crash }),
+        finalUrl: run.finalUrl,
+        decisions: run.decisions,
+        actions: run.actions,
+        depth: run.depth,
+        ...(runUsage === undefined ? {} : { usage: runUsage.snapshot() }),
+        ...(hang === undefined ? {} : { hang }),
+        // #142 follow-up: reported but never gates `missionOutcome`/`exitCode` — a UX finding is
+        // always advisory, and a `server-log` defect here is treated the same way. So is an HTTP 5xx
+        // hard-signal defect (#208): listed with its fingerprint (verify-fix replays it), advisory here.
+        ...serverLogResult(serverLogRun),
+        ...defectFields([
+            ...http5xx.defects(run.transcript, run.recording.pages.flatMap((p) => p.steps)[0]?.step.kind === "navigate" ? 1 : 0).map((d) => ({ ...d, advisory: true })),
+            ...advisoryDefects(serverLogRun?.defects),
+        ]),
+        ...(budget === null ? {} : { budget: budget.trajectory() }),
+        ...(adjudication === undefined
+            ? {}
+            : {
+                goalOutcome: adjudication.outcome,
+                checks: adjudication.checks,
+                ...(adjudication.warnings === undefined ? {} : { checkWarnings: adjudication.warnings }),
+            }),
+        ...host.fields,
+    };
+    if (outcome.kind === "failed") {
+        // The analysis is the review's product: without it the review is inconclusive (never a
+        // fabricated clean report) — but the run's transcript is kept, and this is a typed result.
+        const why = new UxAnalysisFailedError(outcome.reason, outcome.screenId, outcome.rubricItemId).message;
+        const missionOutcome = runOutcome === "clean" ? "inconclusive" : runOutcome;
+        const unavailable = {
+            ...base,
+            report: null,
+            reportPath: null,
+            missionOutcome,
+            exitCode: missionExitCode(missionOutcome),
+            analysisUnavailable: why,
+        };
+        // Persisted like every other mission's typed result, so MCP `get_mission_result` can read it (#117).
+        return await withRunEvidence({ ...unavailable, resultPath: writeMissionResult(journal.recordingPath, missionOutcome, unavailable.exitCode, unavailable, runUsage) }, evidenceOf(opts, secrets), triageOf(opts, serverLogRun, secrets));
+    }
+    const report = buildReport(groundFindings(withSignalFindings(outcome, signalFindings), friction), {
+        minConfidence,
+        quality,
+        maxFindingsPerRoute,
+        ...(product.facts === undefined ? { evidenceCaveats: [NO_PRODUCT_FACTS_CAVEAT] } : {}),
+        calibrationCaveats: [calibrationCaveat(opts.appContext.appClass), claimsCaveat()],
+    });
+    await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    const reviewed = { ...base, report, reportPath, missionOutcome: runOutcome, exitCode: missionExitCode(runOutcome) };
+    return await withRunEvidence({ ...reviewed, resultPath: writeMissionResult(journal.recordingPath, runOutcome, reviewed.exitCode, reviewed, runUsage) }, evidenceOf(opts, secrets), triageOf(opts, serverLogRun, secrets));
+}
+//# sourceMappingURL=result.js.map

package/dist/ux-usability/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/ux-usability/result.ts"],"names":[],"mappings":"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"}

package/dist/ux-usability/setup.d.ts

@@ -0,0 +1,75 @@
+import { type SecretCommandRunner, type TranscriptEntry } from "@jevitate/explore";
+import { type ScreenRef, type UxEvidence, type UxFinding } from "@jevitate/ux";
+import { MissionJournal } from "../mission-journal.js";
+import { Http5xxOracle } from "@jevitate/explore";
+import { UsabilityCapture } from "../usability-capture.js";
+import type { RunUsabilityMissionOptions } from "../ux-usability.js";
+/** Usability reads only a spec's `budget` (#150) — never its `invariants`/`capture` (#86/#147, not supported here). */
+export declare class UsabilityInvariantsUnsupportedError extends Error {
+    readonly code: "E_USABILITY_INVARIANTS";
+    constructor();
+}
+/**
+ * Phase 1 — set-up: every bad-input refusal BEFORE a browser opens, the run's artifact paths, the
+ * armed launch (kill switch, host sampler, browser), the capture/journal/server-log listener chain
+ * and the once-only session close. Returns the run's shared state, mutated in place by later phases.
+ */
+export declare function setUpUsabilityMission(opts: RunUsabilityMissionOptions): Promise<{
+    opts: RunUsabilityMissionOptions;
+    origin: string;
+    minConfidence: number;
+    quality: import("@jevitate/ux").QualityPolicy;
+    maxFindingsPerRoute: number;
+    fixture: string | undefined;
+    product: import("../ux-product.js").LoadedProductFacts;
+    runCapture: import("../run-screenshots.js").RunCapture;
+    portFactory: () => import("@jevitate/playwright").BrowserPort;
+    port: import("@jevitate/playwright").BrowserPort;
+    collected: UxEvidence[];
+    history: ScreenRef[];
+    overflowFindings: UxFinding[];
+    seenOverflow: Set<string>;
+    extract: (session: {
+        page: {
+            evaluate: (fn: () => string) => Promise<string>;
+        };
+    }) => Promise<string>;
+    outDir: string;
+    stamp: string;
+    reportPath: string;
+    journal: MissionJournal;
+    screenshotDir: string;
+    videoDir: string | undefined;
+    launch: {
+        storageState?: string | undefined;
+        viewport?: import("@jevitate/playwright").ViewportSize;
+        device?: string;
+        geolocation?: import("@jevitate/playwright").GeolocationSpec;
+        allowedOrigins: string[];
+        baseUrl: string;
+        executablePath?: string;
+        channel?: string;
+        args?: readonly string[];
+        slowMo?: number;
+        extensions?: readonly import("@jevitate/playwright").UnpackedExtension[];
+        resources?: import("@jevitate/playwright").ResourceLimits;
+        recordVideo?: {
+            dir: string;
+        } | undefined;
+        headless: boolean;
+    };
+    secrets: string[];
+    runUsage: import("@jevitate/ai-core").UsageLedger | undefined;
+    disarmKillSwitch: () => void;
+    health: import("@jevitate/explore").HostHealthSampler;
+    session: import("@jevitate/playwright").BrowserSession;
+    snapshotter: import("../storage-state-snapshot.js").StorageStateSnapshotter;
+    uxSecretCommand: SecretCommandRunner | undefined;
+    http5xx: Http5xxOracle;
+    capture: UsabilityCapture;
+    journalListener: (entry: TranscriptEntry, all: readonly TranscriptEntry[]) => void;
+    serverLog: import("../log-correlation.js").ServerLogRuntime | undefined;
+    closeSession: () => Promise<void>;
+}>;
+/** The run's shared state: set up once, handed to every later phase (the same objects, never copies). */
+export type UsabilitySetup = Awaited<ReturnType<typeof setUpUsabilityMission>>;