humanish 0.104.3 → 0.106.0

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

@@ -0,0 +1,321 @@
+import { createE2BParticipantDesktop } from "./e2b-desktop/desktop.js";
+import { createInProcessDesktop } from "./in-process-desktop.js";
+import path from "node:path";
+import { cuaParticipantDiagnostics } from "./diagnostics.js";
+import { mapWithConcurrency } from "../../run/concurrency.js";
+import { assertScreenshotEvidence, stripPngMetadataChunks } from "../../evidence/image.js";
+import { redactText, toErrorMessage } from "../../evidence/redaction.js";
+import { assertSafeOutputPathSegment, writeContainedOutputFile, } from "../../run/contained-output.js";
+import { participantOutcomeOk } from "./participant-facts.js";
+import { closeParticipantModel, judgeParticipantSession, participantSessionOptions, recordParticipantTrace, startParticipantModel, } from "./participant-model.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 function makeParticipantWriteScreenshot(artifactRoot, spec, screenshots) {
+    if (spec.screenshotDir) {
+        assertSafeOutputPathSegment(spec.screenshotDir, "Screenshot participant id");
+    }
+    const dirParts = spec.screenshotDir ? ["screenshots", spec.screenshotDir] : ["screenshots"];
+    const relPrefix = spec.screenshotDir
+        ? path.posix.join("screenshots", spec.screenshotDir)
+        : "screenshots";
+    return async (name, bytes) => {
+        assertSafeOutputPathSegment(name, "Screenshot name");
+        const rel = path.posix.join(relPrefix, name);
+        // Evidence holds image data only, whatever the executor's frames carried.
+        const frame = stripPngMetadataChunks(bytes);
+        assertScreenshotEvidence(rel, frame);
+        await writeContainedOutputFile(artifactRoot, path.join(...dirParts, name), frame);
+        screenshots.push(rel);
+        return rel;
+    };
+}
+/** A blocked lane outcome (pipeline gate / fail-fast skipped it before it ran). */
+function skippedOutcome(spec, reason) {
+    return {
+        spec,
+        killed: false,
+        streamUrlPresent: false,
+        screenshots: [],
+        stateStepRecords: [],
+        phaseRecords: [],
+        warnings: [],
+        skippedReason: reason,
+        noEngagement: false,
+        selfReportedBlocker: false,
+        reportedFriction: false,
+        harnessError: false,
+    };
+}
+/** 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 async function runCuaParticipant(spec, deps) {
+    let model = {};
+    const warnings = [];
+    const screenshots = [];
+    const writeScreenshot = makeParticipantWriteScreenshot(deps.artifactRoot, spec, screenshots);
+    let session;
+    let sessionError;
+    let providerCleanupError;
+    let provisioned = false;
+    let signaled = false;
+    const signal = (ok) => {
+        if (!signaled && deps.signalProvisioned) {
+            signaled = true;
+            deps.signalProvisioned(ok);
+        }
+    };
+    const desktop = deps.createDesktop?.(spec, warnings, deps.artifactRoot) ??
+        createE2BParticipantDesktop(spec, deps, warnings);
+    try {
+        await desktop.prepare();
+        const ready = await desktop.openSession();
+        model = await startParticipantModel(spec, deps, ready.executor);
+        // World is ready: release the pipeline gate so the remaining lanes may start.
+        provisioned = true;
+        signal(true);
+        session = await deps.runSession(participantSessionOptions(spec, deps, ready, model.provider, writeScreenshot));
+    }
+    catch (error) {
+        sessionError = redactText(deps.scrubKnownValues(toErrorMessage(error)));
+    }
+    finally {
+        // A provider whose cleanup is unconfirmed fails the run as an execution, apart from how the
+        // session ended: a session that passed stays a passed participant.
+        if (await closeParticipantModel(model, warnings)) {
+            providerCleanupError = "Model provider cleanup is unconfirmed.";
+        }
+        try {
+            if (!provisioned)
+                signal(false);
+        }
+        finally {
+            await desktop.finalize({
+                failed: sessionError !== undefined || providerCleanupError !== undefined || session === undefined,
+            });
+        }
+    }
+    if (session)
+        await recordParticipantTrace(spec, deps, session, warnings);
+    const { noEngagement, selfReportedBlocker, reportedFriction } = judgeParticipantSession(session, deps, warnings);
+    // A provider-cleanup failure still trips fail-fast and counts in the lane summary's harness errors.
+    const harnessError = sessionError !== undefined ||
+        providerCleanupError !== undefined ||
+        session?.completionReason === "harness_error";
+    const { released, ...desktopEvidence } = desktop.snapshot();
+    return {
+        spec,
+        ...(session ? { session } : {}),
+        ...(sessionError === undefined ? {} : { sessionError }),
+        ...(providerCleanupError === undefined ? {} : { providerCleanupError }),
+        ...desktopEvidence,
+        killed: released,
+        screenshots,
+        warnings,
+        noEngagement,
+        selfReportedBlocker,
+        reportedFriction,
+        harnessError,
+    };
+}
+/**
+ * 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 async function runCuaParticipants(runs, deps, concurrency, runParticipant = runCuaParticipant) {
+    const failFast = { tripped: false, reason: "" };
+    let resolveGate;
+    let rejectGate;
+    const gate = new Promise((resolve, reject) => {
+        resolveGate = resolve;
+        rejectGate = () => reject(new Error("gate"));
+    });
+    // The gate is rejected on lane-0 provisioning failure; swallow the unhandled rejection if no
+    // later lane ever awaits it (concurrency could let lane 0 finish alone).
+    gate.catch(() => undefined);
+    const outcomes = await mapWithConcurrency(runs, concurrency, async (spec, index) => {
+        if (index > 0) {
+            try {
+                await gate;
+            }
+            catch {
+                return skippedOutcome(spec, `skipped: participant ${runs[0]?.planned.id ?? "lane-01"} failed to provision its world (pipeline gate)`);
+            }
+        }
+        if (failFast.tripped) {
+            return skippedOutcome(spec, `skipped: ${failFast.reason}`);
+        }
+        // The lane runner is TOTAL (#342): every exit path returns a recorded outcome. Without this
+        // guard, one lane's late throw (e.g. its trace write hitting ENOSPC after its own sandbox was
+        // already torn down) rejected the whole map while sibling workers kept launching sandboxes
+        // nobody would ever record — the run spent money and then reported nothing.
+        let outcome;
+        try {
+            outcome = await runParticipant(spec, {
+                ...deps,
+                ...(index === 0
+                    ? {
+                        signalProvisioned: (ok) => {
+                            if (ok) {
+                                resolveGate?.();
+                            }
+                            else {
+                                rejectGate?.();
+                            }
+                        },
+                    }
+                    : {}),
+            });
+        }
+        catch (error) {
+            // Lane 0 may have thrown before signaling the provisioning gate — release the followers as
+            // blocked rather than leaving them awaiting a gate that will never settle.
+            if (index === 0)
+                rejectGate?.();
+            const detail = redactText(toErrorMessage(error));
+            outcome = {
+                spec,
+                killed: false,
+                streamUrlPresent: false,
+                screenshots: [],
+                stateStepRecords: [],
+                phaseRecords: [],
+                warnings: [],
+                noEngagement: false,
+                selfReportedBlocker: false,
+                reportedFriction: false,
+                harnessError: true,
+                sessionError: `participant runner threw outside the session guard: ${detail}`,
+            };
+        }
+        if (outcome.harnessError && !failFast.tripped) {
+            failFast.tripped = true;
+            failFast.reason = `a prior participant (${outcome.spec.planned.id}) ended in a harness error (fail-fast)`;
+        }
+        return outcome;
+    });
+    return { outcomes, ...(failFast.tripped ? { failFastReason: failFast.reason } : {}) };
+}
+/** Project one lane outcome (or a dry-run contract spec) into the public CuaParticipantResult. */
+export function toParticipantResult(spec, outcome, subject, dryRun) {
+    const base = {
+        id: 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 }),
+        index: spec.planned.index + 1,
+        persona: spec.persona.id,
+        device: spec.planned.device.name,
+        resolution: spec.planned.device.resolution,
+        subject,
+    };
+    if (!outcome || dryRun) {
+        return {
+            ...base,
+            status: "contract_proof_only",
+            ok: dryRun,
+            diagnostics: cuaParticipantDiagnostics({ dryRun }),
+        };
+    }
+    if (outcome.skippedReason !== undefined) {
+        return {
+            ...base,
+            status: "blocked",
+            ok: false,
+            diagnostics: cuaParticipantDiagnostics({ dryRun, skipped: true }),
+            skippedReason: outcome.skippedReason,
+            error: { code: "HUMANISH_CUA_LAB_FAILED", message: outcome.skippedReason },
+        };
+    }
+    const session = outcome.session;
+    const participantOk = participantOutcomeOk(outcome, dryRun);
+    const status = session ? session.status : "failed";
+    return {
+        ...base,
+        status,
+        ok: participantOk,
+        diagnostics: cuaParticipantDiagnostics({
+            dryRun,
+            executionError: outcome.sessionError !== undefined,
+            noEngagement: outcome.noEngagement,
+            ...(session
+                ? {
+                    session: {
+                        status: session.status,
+                        completionReason: session.completionReason,
+                        ...(session.trace.stopCause === undefined
+                            ? {}
+                            : { stopCause: session.trace.stopCause }),
+                    },
+                }
+                : {}),
+        }),
+        ...(session
+            ? {
+                session: {
+                    status: session.status,
+                    completionReason: session.completionReason,
+                    ...(session.trace.stopCause === undefined
+                        ? {}
+                        : { stopCause: session.trace.stopCause }),
+                    reason: session.reason,
+                    screenshots: outcome.screenshots.length,
+                },
+            }
+            : {}),
+        ...(outcome.sandboxId === undefined
+            ? {}
+            : {
+                sandbox: {
+                    sandboxId: outcome.sandboxId,
+                    killed: outcome.killed,
+                    streamUrlPresent: outcome.streamUrlPresent,
+                },
+            }),
+        ...(participantOk
+            ? {}
+            : {
+                error: {
+                    code: outcome.failureCode ?? "HUMANISH_CUA_LAB_FAILED",
+                    message: outcome.sessionError ??
+                        (outcome.noEngagement
+                            ? "Actor took no actions and produced no message (likely a blank/still-loading screen); not a credible goal_satisfied."
+                            : outcome.selfReportedBlocker
+                                ? "Actor reported goal_satisfied while its final message described a blocker or asked for missing instructions; not a credible pass."
+                                : session?.completionReason === "harness_error"
+                                    ? `Computer-use session ended with a harness error: ${session.reason}`
+                                    : session?.status !== "passed"
+                                        ? `Computer-use session ended with ${session?.status ?? "unknown"}: ${session?.reason ?? "no terminal reason"}`
+                                        : "Computer-use lab did not produce a terminal session."),
+                },
+            }),
+    };
+}
+/**
+ * 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 async function runAllCuaParticipants(runs, deps, participantPlan, inProcessRoute) {
+    if (inProcessRoute) {
+        // The caller's executor stands in for a desktop, and the shared runner drives the participant.
+        const outcome = await runCuaParticipant(runs[0], {
+            ...deps,
+            createDesktop: () => createInProcessDesktop(deps),
+        });
+        return { outcomes: [outcome], failFastReason: undefined };
+    }
+    if (runs.length === 1)
+        return { outcomes: [await runCuaParticipant(runs[0], deps)], failFastReason: undefined };
+    const ran = await runCuaParticipants([...runs], deps, participantPlan.concurrency);
+    return { outcomes: ran.outcomes, failFastReason: ran.failFastReason };
+}

package/dist/routes/computer-use/legacy-lane-spec.d.ts

@@ -0,0 +1,62 @@
+import type { ActorPersonaRef } from "../../actors/contract.js";
+import type { ReasoningEffort } from "../../actors/reasoning-effort.js";
+import type { DwellWindow, StopWhen } from "../../actors/stop-conditions.js";
+import type { DevicePreset } from "../../lab/device-presets.js";
+import type { LabTask } from "../../lab/tasks.js";
+import type { RunStream } from "../../run/streams.js";
+import type { DesktopParticipantRun } from "./types.js";
+/**
+ * A lane as the deprecated cuaHooks.buildProvider and cuaHooks.createDesktopLane receive it: a flat
+ * copy of a DesktopParticipantRun.
+ * @deprecated Use RunLabOptions.createProvider, which receives a ParticipantRef. Removed with the
+ * compatibility section in the next minor.
+ */
+export interface CuaLaneSpec {
+    laneId: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+    /** 0-based. */
+    laneIndex: number;
+    simId: string;
+    streamId: string;
+    persona: ActorPersonaRef;
+    instructions: string;
+    /** Redacted original composed prompt for legacy study context; execution uses instructions. */
+    evidenceInstructions?: string;
+    /** Original declarative assignment, separate from runtime-composed instructions. */
+    assignment?: RunStream["assignment"];
+    /** App-url fan-out only: this lane's explicit browser target; absent falls back to deps.appUrl. */
+    targetUrl?: string;
+    /** Deterministic harness-owned completion guard. Lane-level override, else actor default. */
+    stopWhen?: StopWhen;
+    /** A declared observation window (#510). Lane-level override, else actor default. */
+    dwell?: DwellWindow;
+    /**
+     * How hard this lane's model is asked to think. Lane-level override, else the actor default,
+     * else absent — and absent means the provider's own default, which the trace records as the
+     * resolved value rather than as nothing (#497).
+     */
+    reasoningEffort?: ReasoningEffort;
+    maxOutputTokens?: number;
+    /** The lab's declared protocol (#414). Every lane runs the SAME protocol — that is what makes the
+     *  per-task rates comparable across participants. Goals are already composed into `instructions`;
+     *  this carries the full tasks so the loop can corroborate completion, and the criteria never
+     *  reach the prompt. */
+    tasks?: readonly LabTask[];
+    /** Per-lane override of the CUA idle backstop (consecutive screenshot/wait turns before gave_up).
+     *  Absent falls back to the loop default. Raised for a lane whose job includes a long LEGITIMATE
+     *  wait (e.g. a shared-world HOST idling in the waiting room while followers provision + join). */
+    idleSteps?: number;
+    /** Per-lane override of the non-idle no-progress backstop; see idleSteps. */
+    noProgressSteps?: number;
+    deviceName: string;
+    devicePreset: DevicePreset;
+    resolution: [number, number];
+    /** "" for N=1 (screenshots/<name>); the laneId for N>1 (screenshots/<laneId>/<name>). */
+    screenshotDir: string;
+    /** "actor.json" for N=1; "actors/<streamId>.json" for N>1. */
+    traceArtifactPath: string;
+}
+/** The flat hook view of one participant run. Called only where a caller's hook receives a lane. */
+export declare function legacyHookSpecOf(run: DesktopParticipantRun): CuaLaneSpec;

package/dist/routes/computer-use/legacy-lane-spec.js

@@ -0,0 +1,39 @@
+// Translation module: legacy lane spellings stay only in modules like this one, so the rest of the
+// route reads participants. CuaActorLabHooks is public API in the deprecated compatibility section, and two of its hooks,
+// buildProvider and createDesktopLane, receive a lane. They keep receiving this flat record until
+// the next minor removes the section. Internally a lane is a DesktopParticipantRun.
+/** The flat hook view of one participant run. Called only where a caller's hook receives a lane. */
+export function legacyHookSpecOf(run) {
+    const { planned } = run;
+    const { labels, limits, device } = planned;
+    return {
+        laneId: planned.id,
+        ...(labels.actorType === undefined ? {} : { actorType: labels.actorType }),
+        ...(labels.surface === undefined ? {} : { surface: labels.surface }),
+        ...(labels.caseGroup === undefined ? {} : { caseGroup: labels.caseGroup }),
+        laneIndex: planned.index,
+        simId: run.recordId,
+        streamId: run.streamId,
+        persona: run.persona,
+        instructions: run.instructions,
+        ...(run.evidenceInstructions === undefined
+            ? {}
+            : { evidenceInstructions: run.evidenceInstructions }),
+        ...(run.evidenceAssignment === undefined ? {} : { assignment: run.evidenceAssignment }),
+        ...(planned.targetUrl === undefined ? {} : { targetUrl: planned.targetUrl }),
+        ...(limits.stopWhen === undefined ? {} : { stopWhen: limits.stopWhen }),
+        ...(limits.dwell === undefined ? {} : { dwell: limits.dwell }),
+        ...(limits.reasoningEffort === undefined ? {} : { reasoningEffort: limits.reasoningEffort }),
+        ...(limits.maxOutputTokens === undefined ? {} : { maxOutputTokens: limits.maxOutputTokens }),
+        ...(planned.tasks === undefined ? {} : { tasks: planned.tasks }),
+        ...(run.backstop?.idleSteps === undefined ? {} : { idleSteps: run.backstop.idleSteps }),
+        ...(run.backstop?.noProgressSteps === undefined
+            ? {}
+            : { noProgressSteps: run.backstop.noProgressSteps }),
+        deviceName: device.name,
+        devicePreset: device.preset,
+        resolution: device.resolution,
+        screenshotDir: run.screenshotDir,
+        traceArtifactPath: run.traceArtifactPath,
+    };
+}

package/dist/routes/computer-use/live-flush.d.ts

@@ -0,0 +1,42 @@
+import type { ActorTokenUsage, ActorTraceItem } from "../../actors/contract.js";
+import type { CuaLiveMetadata } from "../../actors/computer-use/loop.js";
+import { type ObserverResult } from "../../observer/render.js";
+import type { RunBundle } from "../../run/bundle.js";
+import type { CuaActorLabHooks, DesktopParticipantRun } from "./types.js";
+export interface LiveTraceFlush {
+    /** Record a participant's recorded-so-far items; the bundle rewrite follows on the flush
+     *  schedule. */
+    flush: (participantId: string, items: readonly ActorTraceItem[], usage?: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
+    /** Stop flushing, clear the timer and wait for an in-flight write. Call it on every exit. */
+    stop: () => Promise<void>;
+}
+/**
+ * Incremental live flush (#441): as each lane's loop reports its recorded-so-far items,
+ * rewrite the in-progress bundle with per-stream `liveActor` partials so the attached
+ * Observer's 5s poll sees the timeline grow. Throttled (one write per interval, trailing
+ * write guaranteed). `write` is the run's `writeSnapshot`, which serializes writes and refuses
+ * any snapshot once the final write began, so a late flush cannot resurrect the in-progress
+ * bundle. A flush failure is swallowed: mid-run observability must never break the run itself.
+ */
+export declare function startLiveTraceFlush(args: {
+    bundle: RunBundle;
+    participantRuns: readonly DesktopParticipantRun[];
+    /** The model the running usage prices at. Usage without its model is not a cost. */
+    model: string;
+    /** Publishes one in-progress bundle: the run's `writeSnapshot`. */
+    write: (bundle: RunBundle) => Promise<void>;
+}): LiveTraceFlush;
+/**
+ * The live desktop views (runtime stream URLs) lanes report, attached to whichever Observer shows
+ * the run. The URLs carry auth, so they live in memory and on the Observer result, never in run
+ * artifacts.
+ */
+export declare function trackRuntimeStreams(hooks: CuaActorLabHooks): {
+    hooks: CuaActorLabHooks;
+    /** From now on, keep this live Observer's stream list current. */
+    showIn: (observer: ObserverResult & {
+        ok: true;
+    }) => void;
+    /** Give the final Observer every stream the run reported. */
+    attachFinal: (observer: ObserverResult) => void;
+};

package/dist/routes/computer-use/live-flush.js

@@ -0,0 +1,154 @@
+import { attachObserverRuntimeStreamUrls } from "../../observer/render.js";
+import {} from "../../observer/run-routes.js";
+import { HOOK_MEMBERS, withHookOverrides } from "../../lab/bag-overrides.js";
+/**
+ * Incremental live flush (#441): as each lane's loop reports its recorded-so-far items,
+ * rewrite the in-progress bundle with per-stream `liveActor` partials so the attached
+ * Observer's 5s poll sees the timeline grow. Throttled (one write per interval, trailing
+ * write guaranteed). `write` is the run's `writeSnapshot`, which serializes writes and refuses
+ * any snapshot once the final write began, so a late flush cannot resurrect the in-progress
+ * bundle. A flush failure is swallowed: mid-run observability must never break the run itself.
+ */
+export function startLiveTraceFlush(args) {
+    const { bundle, participantRuns, model, write } = args;
+    const streamIdByParticipant = new Map(participantRuns.map((spec) => [spec.planned.id, spec.streamId]));
+    // The persona each lane is running, so the live flush can say who is in it.
+    const personaByStream = new Map(participantRuns
+        .map((spec) => [spec.streamId, spec.persona?.id])
+        .filter((entry) => typeof entry[1] === "string"));
+    const liveItemsByStream = new Map();
+    // Running token usage per lane, so a run in flight can price itself instead of reporting the
+    // cost as unknown until the moment it ends.
+    const liveUsageByStream = new Map();
+    const liveMetadataByStream = new Map();
+    let flushWriting;
+    let flushDirty = false;
+    let flushClosed = false;
+    let flushTimer;
+    let lastFlushAtMs = 0;
+    const FLUSH_MIN_INTERVAL_MS = 2_000;
+    const flushNow = async () => {
+        while (flushDirty && !flushClosed) {
+            flushDirty = false;
+            lastFlushAtMs = Date.now();
+            const updatedAt = new Date(lastFlushAtMs).toISOString();
+            const patched = {
+                ...bundle,
+                streams: bundle.streams.map((stream) => {
+                    const liveItems = liveItemsByStream.get(stream.id);
+                    return liveItems === undefined
+                        ? stream
+                        : {
+                            ...stream,
+                            liveActor: {
+                                schema: "humanish.live-actor.v1",
+                                updatedAt,
+                                // WHO is in this lane, carried while the run is live. Without it a surface
+                                // watching a live run can only name the lane, and "CUA browser — observer-live-
+                                // check" is the harness talking about itself where the participant should be.
+                                ...(personaByStream.get(stream.id) === undefined
+                                    ? {}
+                                    : { persona: { id: personaByStream.get(stream.id) } }),
+                                ...(liveUsageByStream.get(stream.id) === undefined
+                                    ? {}
+                                    : {
+                                        tokenUsage: liveUsageByStream.get(stream.id),
+                                        // The model too: usage without the rate it prices at is not a cost.
+                                        ids: { model },
+                                    }),
+                                ...liveMetadataByStream.get(stream.id),
+                                items: [...liveItems],
+                            },
+                        };
+                }),
+            };
+            try {
+                await write(patched);
+            }
+            catch {
+                // Swallowed by design; the final write is the evidence of record.
+            }
+        }
+        flushWriting = undefined;
+    };
+    const scheduleFlush = () => {
+        if (flushClosed || flushWriting !== undefined)
+            return;
+        const sinceMs = Date.now() - lastFlushAtMs;
+        if (sinceMs >= FLUSH_MIN_INTERVAL_MS) {
+            flushWriting = flushNow();
+            return;
+        }
+        if (flushTimer === undefined) {
+            flushTimer = setTimeout(() => {
+                flushTimer = undefined;
+                scheduleFlush();
+            }, FLUSH_MIN_INTERVAL_MS - sinceMs);
+            flushTimer.unref?.();
+        }
+    };
+    const flush = (participantId, items, usage, metadata) => {
+        // An empty snapshot (the initial observation on a frameless route) carries no
+        // evidence worth a disk write; the first real item triggers the first flush.
+        if (items.length === 0)
+            return;
+        const streamId = streamIdByParticipant.get(participantId);
+        if (streamId === undefined)
+            return;
+        liveItemsByStream.set(streamId, items.slice());
+        if (metadata !== undefined)
+            liveMetadataByStream.set(streamId, metadata);
+        if (usage !== undefined)
+            liveUsageByStream.set(streamId, usage);
+        flushDirty = true;
+        scheduleFlush();
+    };
+    const stop = async () => {
+        flushClosed = true;
+        if (flushTimer !== undefined) {
+            clearTimeout(flushTimer);
+            flushTimer = undefined;
+        }
+        await flushWriting;
+    };
+    return { flush, stop };
+}
+/**
+ * The live desktop views (runtime stream URLs) lanes report, attached to whichever Observer shows
+ * the run. The URLs carry auth, so they live in memory and on the Observer result, never in run
+ * artifacts.
+ */
+export function trackRuntimeStreams(hooks) {
+    let liveObserver;
+    const urls = [];
+    return {
+        // The caller's bag may be a class instance, so it is wrapped rather than spread.
+        hooks: withHookOverrides(hooks, HOOK_MEMBERS.cua, {
+            onRuntimeStreamReady: async (stream) => {
+                await hooks.onRuntimeStreamReady?.(stream);
+                urls.push({ streamId: stream.streamId, url: stream.url });
+                if (liveObserver)
+                    attachObserverRuntimeStreamUrls(liveObserver, urls);
+            },
+            onRuntimeStreamEnded: async (stream) => {
+                await hooks.onRuntimeStreamEnded?.(stream);
+                // Mark, never remove: the tile needs to KNOW the live view ended (and say so) rather than
+                // have the stream silently vanish from the overlay (#357).
+                for (const entry of urls) {
+                    if (entry.streamId === stream.streamId)
+                        entry.ended = true;
+                }
+                if (liveObserver)
+                    attachObserverRuntimeStreamUrls(liveObserver, urls);
+            },
+        }),
+        showIn: (observer) => {
+            liveObserver = observer;
+        },
+        attachFinal: (observer) => {
+            if (observer.ok && urls.length > 0) {
+                attachObserverRuntimeStreamUrls(observer, urls);
+            }
+        },
+    };
+}

package/dist/routes/computer-use/local-tree-pack.d.ts

@@ -0,0 +1,27 @@
+import type { LabConfig } from "../../lab/types.js";
+import { type LocalTreeArchive } from "../../subject/local-tree-archive.js";
+import { type CuaActorLabHooks } from "./types.js";
+/**
+ * Pack the working tree for a local-tree run and report what left the host on stderr, by counts
+ * and digest only, never paths or file names.
+ */
+export declare function packRunLocalTree(hooks: CuaActorLabHooks, config: {
+    readonly subject: Pick<LabConfig["subject"], "localTree">;
+}, cwd: string): Promise<{
+    archive: LocalTreeArchive;
+    buffer: ArrayBuffer;
+}>;
+/**
+ * Default local-tree packing implementation: createLocalTreeArchive(root, opts) on the host,
+ * then a single read of the produced archive file into an ArrayBuffer for upload. The DI seam
+ * (CuaActorLabHooks.packLocalTree) overrides this in deterministic tests so they never require
+ * tar/git.
+ */
+export declare function defaultPackLocalTree(args: {
+    root: string;
+    extraExclude?: string[];
+    maxArchiveBytes?: number;
+}): Promise<{
+    archive: LocalTreeArchive;
+    buffer: ArrayBuffer;
+}>;