humanish 0.0.1 → 0.15.0

package/dist/cua-actor-lab.d.ts

@@ -0,0 +1,620 @@
+import type { ActorCompletionReason, ActorPersonaRef, ActorStatus } from "./actor-contract.js";
+import { type BrowserLabAdapterHooks } from "./adapter-extension.js";
+import { type CuaActorDescriptor } from "./actor-registry.js";
+import type { CuaActorSessionOptions } from "./computer-use-actor.js";
+import type { CuaExecutor, CuaLoopResult, CuaProvider } from "./computer-use.js";
+import { type E2BDesktopModule, type E2BDesktopSandbox } from "./e2b-desktop-launch.js";
+import { type DetachedTimers } from "./e2b-detached.js";
+import { type DevicePreset } from "./device-presets.js";
+import { type LabActorLane, type LabConfig, type LabDesktopBrowser, type LabSubjectServe, type LabSubjectState } from "./lab-config.js";
+import { renderObserver, type ObserverResult } from "./observer.js";
+import { type LocalTreeArchive } from "./source-archive.js";
+import type { StopWhen } from "./stop-conditions.js";
+import { type RunBundle, type RunRerunLineage, type RunProviderResource, type RunSubjectProvenance, type RunSubjectStateStepRecord } from "./run.js";
+export declare const CUA_ACTOR_LAB_SCHEMA = "humanish.cua-lab-result.v2";
+export declare const CUA_FANOUT_STRATEGY: "per-lane-worlds";
+export declare const CUA_ACTOR_LAB_PROVIDER_METADATA: {
+    readonly mode: "cua-actor-lab";
+    readonly tool: "humanish";
+};
+export interface DesktopBrowserEvidence {
+    requested: LabDesktopBrowser;
+    resolved?: string;
+}
+export declare const SUBJECT_DIR = "/home/user/subject";
+/**
+ * One phase-boundary event from the shared subject provisioning pipeline (clone or local-tree
+ * route): started/completed pairs at each named boundary, never per poll tick (the detached
+ * primitive in e2b-detached.ts already polls every 1.5-3s internally; only the boundary itself
+ * is surfaced here). Message text is public-safe by construction: no URLs beyond the existing
+ * publicAppUrl convention, no paths, no command text. Completed events carry `ok` and
+ * `durationMs`; started events (and the fire-and-forget `subject.serve.started`) carry neither.
+ */
+export interface SubjectPhaseEvent {
+    at: string;
+    type: string;
+    ok?: boolean;
+    durationMs?: number;
+    message: string;
+}
+/**
+ * Library-level hooks. `prepareDesktop` runs after sandbox creation and before subject
+ * provisioning / browser launch — library callers use it for extra in-sandbox setup beyond
+ * what `subject.serve` declares (or to provision an app-url subject entirely). The rest are
+ * DI seams so CI drives the full path with fakes at zero network/zero spend.
+ */
+export interface CuaActorLabHooks extends BrowserLabAdapterHooks {
+    /**
+     * Runs after sandbox creation and before subject provisioning / browser launch. Widened
+     * back-compatibly with per-lane context so a library caller can provision the right app-url
+     * subject per lane (a one-arg `(desktop) => …` still satisfies the type). Called once per lane.
+     */
+    prepareDesktop?: (desktop: E2BDesktopSandbox, lane: {
+        laneId: string;
+        laneIndex: number;
+        laneCount: number;
+    }) => Promise<void>;
+    /**
+     * Pre-flight hook: receives the resolved lane plan BEFORE any sandbox or provider call (dry-run
+     * AND live). The engine also prints the plan to stderr; this seam lets tests assert it without
+     * scraping stderr. Identical plan in dry-run, marked $0.
+     */
+    onPreflight?: (plan: CuaLanePlan) => void;
+    /**
+     * Live subject-provisioning phase sink: one call per started/completed boundary (clone,
+     * upload/extract, install, build, serve start, ready, and each subject.state seed-step
+     * group). Defaults to one stderr line per event, prefixed with the lane id when laneCount > 1
+     * (single-lane emission is unconditional: single-lane silence for the whole boot is the bug
+     * this event stream closes). Override in tests to capture instead of writing to real stderr.
+     */
+    onPhase?: (event: SubjectPhaseEvent, ctx: {
+        laneId: string;
+        laneCount: number;
+    }) => void;
+    /**
+     * Runtime-only live desktop stream callback. The URL carries an auth key and must never be
+     * persisted into run artifacts; callers use it to hydrate an attached Observer server.
+     */
+    onRuntimeStreamReady?: (stream: {
+        laneId: string;
+        sandboxId: string;
+        simId: string;
+        streamId: string;
+        url: string;
+    }) => Promise<void> | void;
+    loadDesktopModule?: () => Promise<E2BDesktopModule>;
+    runSession?: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
+    /**
+     * Supply a custom executor (e.g. a window.* JS-contract bridge over an already-running local
+     * dev server). When present (with `buildProvider`), `runCuaActorLab` takes the IN-PROCESS
+     * branch: it NEVER loads the E2B module, creates a sandbox, runs prepareDesktop, provisions a
+     * clone, opens a browser, or starts a stream — so `result.sandbox` is omitted, the verifiable
+     * "no E2B SDK call" proof. The whole bundle/Observer/redaction composition below the session
+     * call is desktop-agnostic and runs unchanged. Receives the resolved config, the
+     * registry-resolved descriptor, and the entry appUrl.
+     */
+    buildExecutor?: (ctx: {
+        config: LabConfig;
+        actor: CuaActorDescriptor;
+        appUrl: string;
+    }) => Promise<CuaExecutor>;
+    /**
+     * Supply a custom provider (a "brain" reasoning over app STATE). REQUIRED alongside
+     * `buildExecutor` — the default OpenAI provider is vision-based (requiresFrame) and would fail
+     * closed against a state-only executor that returns no screenshot. (`buildProvider` ALONE is
+     * allowed — that is just a model swap on the normal E2B route.)
+     */
+    buildProvider?: (ctx: {
+        config: LabConfig;
+        actor: CuaActorDescriptor;
+    }) => Promise<CuaProvider>;
+    env?: Record<string, string | undefined>;
+    renderObserverFn?: typeof renderObserver;
+    /** Injected clock/sleep for the detached-step polling (tests only). */
+    detachedTimers?: DetachedTimers;
+    /**
+     * Local-tree packing DI seam (tests only, no npm dependency needed to exercise the route):
+     * defaults to createLocalTreeArchive(root, opts) plus a host-side read of the produced
+     * archive file into an ArrayBuffer. Called ONCE per run, before lane fan-out, on the live
+     * local-tree route; the result (archive metadata + bytes) is shared byte-identically across
+     * every fan-out lane, so one archiveSha256 describes every lane's packed content.
+     */
+    packLocalTree?: (args: {
+        root: string;
+        extraExclude?: string[];
+        maxArchiveBytes?: number;
+    }) => Promise<{
+        archive: LocalTreeArchive;
+        buffer: ArrayBuffer;
+    }>;
+}
+export interface RunCuaActorLabOptions {
+    cwd: string;
+    config: LabConfig;
+    /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
+    dryRun: boolean;
+    open?: boolean;
+    runId?: string;
+    /** CLI `--count` override for the homogeneous fan-out lane count (ignored when a `lanes`
+     *  roster is declared — a roster's length is authoritative). */
+    countOverride?: number;
+    /** Explicitly create a new run containing failed or selected lanes from a prior fan-out run. */
+    rerun?: {
+        sourceRunId: string;
+        laneIds?: string[];
+    };
+    hooks?: CuaActorLabHooks;
+    onObserverReady?: (observer: ObserverResult & {
+        ok: true;
+    }) => Promise<void> | void;
+}
+/** A lane's row in the pre-flight plan: identity + the device/persona it will drive. The prompt
+ *  text never leaks — only a sha256-16 digest of the composed instructions. */
+export interface CuaLanePlanEntry {
+    id: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+    /** 1-based display index. */
+    index: number;
+    persona: string;
+    device: string;
+    resolution: [number, number];
+    instructionDigest: string;
+    /** Present only when a lane overrides subject.appUrl; digest avoids leaking preview hosts in plan logs. */
+    targetDigest?: string;
+}
+/** The pre-flight spend/lane plan (pure; printed to stderr + recorded as a bundle event before
+ *  any sandbox or provider call; identical in dry-run, marked $0). */
+export interface CuaLanePlan {
+    strategy: typeof CUA_FANOUT_STRATEGY;
+    laneCount: number;
+    /** Effective in-flight bound (config default min(N,3), only LOWERED by the env override). */
+    concurrency: number;
+    /** ceil(laneCount / concurrency). */
+    waves: number;
+    /** Per-lane session wall-clock budget (execution.timeoutMs); there is no run-level wall clock. */
+    perLaneSessionBudgetMs: number;
+    /** Worst-case TOTAL sandbox-minutes across all lanes (each lane's full sandbox deadline). */
+    worstCaseSandboxMinutes: number;
+    /** True for a dry-run plan (no spend); the same table appears live. */
+    dryRun: boolean;
+    lanes: CuaLanePlanEntry[];
+}
+/** One lane's outcome in the result projection. ALWAYS present in `result.lanes` (length 1 at
+ *  N=1). A `blocked` lane is one the pipeline-gate / fail-fast skipped before it ran. */
+export interface CuaLaneResult {
+    id: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+    index: number;
+    persona: string;
+    device: string;
+    resolution: [number, number];
+    /** Terminal lane status; "blocked" = skipped (gate/fail-fast); "contract_proof_only" = dry-run. */
+    status: ActorStatus | "blocked" | "contract_proof_only";
+    ok: boolean;
+    session?: {
+        status: ActorStatus;
+        completionReason: ActorCompletionReason;
+        reason: string;
+        screenshots: number;
+    };
+    sandbox?: {
+        sandboxId: string;
+        killed: boolean;
+        streamUrlPresent: boolean;
+    };
+    subject: CuaSubjectProjection;
+    /** Set when the lane was skipped (pinned reason string). */
+    skippedReason?: string;
+    error?: {
+        code: CuaActorLabErrorCode;
+        message: string;
+    };
+}
+/** Aggregate counts across lanes. */
+export interface CuaLaneSummary {
+    strategy: typeof CUA_FANOUT_STRATEGY;
+    total: number;
+    /** Lanes whose own verdict is ok (terminal, engaged, no harness error). */
+    passed: number;
+    /** Lanes skipped by the pipeline gate / fail-fast. */
+    skipped: number;
+    /** Lanes that ended in a harness error. */
+    harnessErrors: number;
+    /** Lanes that returned goal_satisfied with zero engagement (hollow). */
+    hollow: number;
+    concurrency: number;
+    waves: number;
+}
+export type CuaActorLabErrorCode = "HUMANISH_CUA_LAB_FAILED" | "HUMANISH_CUA_LAB_KEYS_MISSING" | "HUMANISH_CUA_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_CUA_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_CUA_LAB_SUBJECT_INVALID" | "HUMANISH_CUA_LAB_SUBJECT_UNSAFE" | "HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER" | "HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_CUA_LAB_FANOUT_INVALID" | "HUMANISH_CUA_LAB_RERUN_INVALID" | "HUMANISH_CUA_LAB_DEVICE_GEOMETRY";
+/** Subject provenance projection (invariant 5): what the actor actually drove. */
+export interface CuaSubjectProjection {
+    source: "app-url" | "clone" | "local-tree";
+    /** Clone-route only: the (possibly redacted) owner/repo slug. */
+    repo?: string;
+    /** Cloned commit SHA (clone route) or host-side HEAD at pack time (local-tree route, when
+     *  the packed root was a git work tree). */
+    commit?: string;
+    /** Local-tree-route only: 64-hex sha256 over the sorted packed-entries list: the content
+     *  pin for a tree that cannot be commit-pinned. Absent on dry-run (nothing was packed). */
+    archiveSha256?: string;
+    /** Local-tree-route only: host-side porcelain status at pack time (true when the working
+     *  tree had uncommitted changes). Absent when the packed root was not a git work tree. */
+    dirty?: boolean;
+    /** Declared env NAMES provisioned for the subject (values never surface anywhere). */
+    envNames?: string[];
+    /** The subject's state story (seeded digests / UNPINNED external / declared-not-run /
+     *  undeclared): the same block the run bundle records. */
+    state: RunSubjectProvenance["state"];
+}
+/** The provisioned-route-only shape threaded through as buildCuaBundle's subjectProvenance arg
+ *  (clone or local-tree; an app-url subject stays undeclared, which buildCuaBundle's own
+ *  default branch already handles without this type). */
+export type CuaSubjectProvenanceArg = {
+    source: "clone";
+    repo: string;
+    commit?: string;
+    envNames: string[];
+    state: RunSubjectProvenance["state"];
+} | {
+    source: "local-tree";
+    archiveSha256?: string;
+    commit?: string;
+    dirty?: boolean;
+    envNames: string[];
+    state: RunSubjectProvenance["state"];
+};
+export interface CuaActorLabResult {
+    schema: typeof CUA_ACTOR_LAB_SCHEMA;
+    /** True when the bundle verified AND (dry-run, or the session reached a terminal verdict
+     * without a harness error). The actor's pass/fail is evidence, not the lab's exit code. */
+    ok: boolean;
+    cwd: string;
+    labId: string;
+    /** The registry-resolved actor id that ran (or would run) the session. */
+    actor: string;
+    appUrl: string;
+    dryRun: boolean;
+    runId: string;
+    session?: {
+        status: ActorStatus;
+        completionReason: ActorCompletionReason;
+        reason: string;
+        screenshots: number;
+    };
+    sandbox?: {
+        sandboxId: string;
+        killed: boolean;
+        /** The stream URL itself (carries an auth key) is runtime-only and is deliberately NOT
+         * surfaced on the result — the sandbox is already dead by the time the result exists. */
+        streamUrlPresent: boolean;
+    };
+    /** Subject provenance (invariant 5): what the actor actually drove. At N>1 this is the
+     *  unanimity-gated aggregate (top-level `commit` only when every lane resolved the same one). */
+    subject?: CuaSubjectProjection;
+    /** The pre-flight lane plan (present once lanes resolve; absent on early validation errors). */
+    plan?: CuaLanePlan;
+    /** Per-lane results — ALWAYS present once lanes resolve (length 1 at N=1). */
+    lanes?: CuaLaneResult[];
+    /** Aggregate lane counts. */
+    laneSummary?: CuaLaneSummary;
+    /** Present when this run explicitly re-executes selected lanes from a prior CUA fan-out run. */
+    rerun?: RunRerunLineage;
+    observer?: ObserverResult;
+    warnings: string[];
+    error?: {
+        code: CuaActorLabErrorCode;
+        message: string;
+    };
+}
+/** A fully-resolved fan-out lane: identity, the composed prompt, and the device geometry it
+ *  renders at. Internal — the public projection is CuaLanePlanEntry / CuaLaneResult. */
+export interface CuaLaneSpec {
+    laneId: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+    /** 0-based. */
+    laneIndex: number;
+    simId: string;
+    streamId: string;
+    persona: ActorPersonaRef;
+    instructions: string;
+    /** 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;
+    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;
+}
+/** Compose one lane's actor prompt: persona line + device line + mission + per-lane steer.
+ *  At N=1 (homogeneous, no roster) this reproduces the prior composeInstructions byte-for-byte. */
+export declare function composeLaneInstructions(args: {
+    mission: string;
+    persona?: string;
+    instruction?: string;
+    device: {
+        name: string;
+        preset: DevicePreset;
+    };
+}): {
+    instructions: string;
+    persona: ActorPersonaRef;
+};
+/**
+ * Resolve a lane's device + rendered resolution (most-specific wins, exactly as the single-lane
+ * path always has): a raw execution.desktop.resolution escape hatch (only legal when no lane
+ * sets a device — XOR enforced at parse) → the lane's named device → the run-wide
+ * execution.desktop.device → the default preset. A raw resolution is an unnamed custom desktop
+ * (non-mobile, DSF 1): we never claim a named preset's mobile/DPR for hand-set geometry.
+ */
+export declare function resolveLaneDevice(config: LabConfig, lane: LabActorLane | undefined): {
+    name: string;
+    preset: DevicePreset;
+    resolution: [number, number];
+};
+/**
+ * Pure pre-flight plan resolver (runs in dry-run AND live). Returns the lane table, the
+ * effective concurrency, the wave count, the per-lane session budget, and the worst-case total
+ * sandbox-minutes — BEFORE any sandbox or provider call. The same plan appears in dry-run,
+ * marked $0 (dryRun: true).
+ */
+export declare function resolveCuaLanePlan(config: LabConfig, opts?: {
+    countOverride?: number;
+    env?: Record<string, string | undefined>;
+    dryRun?: boolean;
+}): CuaLanePlan;
+/** Shared deps every lane runner needs (resolved once in the engine). */
+export interface CuaLaneDeps {
+    config: LabConfig;
+    descriptor: CuaActorDescriptor;
+    appUrl: string;
+    cloneRoute: boolean;
+    /** Optional so out-of-scope callers building CuaLaneDeps directly (other engines reusing
+     *  runCuaLane) do not need to know about the local-tree route; undefined behaves as false. */
+    localTreeRoute?: boolean;
+    serve?: LabSubjectServe;
+    subjectRepo?: string;
+    subjectEnvNames: string[];
+    hasGithubToken: boolean;
+    /** Local-tree route only: the once-per-run packed archive bytes, shared byte-identically
+     *  across every fan-out lane's upload step. Absent on dry-run and every other route. */
+    localTreeArchiveBuffer?: ArrayBuffer;
+    env: Record<string, string | undefined>;
+    openaiApiKey: string;
+    e2bApiKey: string;
+    requestTimeoutMs: number;
+    perLaneSandboxMs: number;
+    timeoutMs: number;
+    laneCount: number;
+    artifactRoot: string;
+    redactScreenshots: boolean;
+    scrubKnownValues: (text: string) => string;
+    runSession: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
+    hooks: CuaActorLabHooks;
+    /** Lane-0 only: signal the pipeline gate after provisioning succeeds (true) or fails (false). */
+    signalProvisioned?: (ok: boolean) => void;
+}
+/** One lane's end-to-end run outcome (internal; projected into CuaLaneResult + the bundle). */
+export interface LaneRunOutcome {
+    spec: CuaLaneSpec;
+    session?: CuaLoopResult;
+    sessionError?: string;
+    sandboxId?: string;
+    killed: boolean;
+    streamUrlPresent: boolean;
+    screenshots: string[];
+    subjectCommit?: string;
+    desktopBrowser?: DesktopBrowserEvidence;
+    stateStepRecords: RunSubjectStateStepRecord[];
+    /** Completed subject-phase records (clone/upload/extract/install/build/ready/state groups),
+     *  folded into bundle.events at build time. Empty on the in-process route (no provisioning). */
+    phaseRecords: SubjectPhaseEvent[];
+    warnings: string[];
+    /** Set when the lane was skipped by the pipeline gate / fail-fast (a pinned reason). */
+    skippedReason?: string;
+    noEngagement: boolean;
+    selfReportedBlocker: boolean;
+    harnessError: boolean;
+    failureCode?: CuaActorLabErrorCode;
+    entryKind?: "local-app";
+}
+/** 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 makeLaneWriteScreenshot(artifactRoot: string, spec: {
+    screenshotDir: string;
+}, screenshots: string[]): (name: string, bytes: Buffer) => Promise<string>;
+/**
+ * Build the xdotool command that makes a browser window fill the desktop.
+ * Exported (pure) for contract tests. A window manager can ignore Chrome's
+ * --window-size, so xdotool is the robust path: move the window to the origin,
+ * then size it to the exact desktop resolution so Observer screenshots carry no
+ * dead margin around the browser.
+ */
+export declare function buildFillDesktopWindowCommand(windowId: string, width: number, height: number): string;
+export declare function makeChromeBrowserStateObserver(desktop: E2BDesktopSandbox, requestTimeoutMs: number): () => Promise<{
+    url?: string;
+    title?: string;
+    text?: string;
+}>;
+/**
+ * Run ONE E2B desktop lane end-to-end: create the sandbox (per-lane metadata + the lane's device
+ * resolution), prepareDesktop, verify geometry, (clone+serve+seed the subject per lane), open the
+ * browser, run the session, and ALWAYS tear down THIS lane's sandbox BY ID in a finally. Never
+ * enumerates sandboxes. Extracted from the former single-lane block; at N=1 it writes the exact
+ * same artifacts (actor.json, screenshots/<name>) the bundle has always referenced.
+ */
+export declare function runCuaLane(spec: CuaLaneSpec, deps: CuaLaneDeps): Promise<LaneRunOutcome>;
+export declare function runCuaActorLab(options: RunCuaActorLabOptions): Promise<CuaActorLabResult>;
+/**
+ * Provision a clone subject inside the sandbox: clone → the shared serve pipeline
+ * (install → state(before-build) → build → state(before-start) → start → readiness
+ * probe → state(after-ready)). Returns the latest subject HEAD after successful
+ * provisioning. Throws (with a capped log tail for the caller to redact) on any failing step:
+ * the lab persists that as a failed-evidence bundle.
+ *
+ * Auth: when GITHUB_TOKEN is among the declared subject env names, the clone authenticates
+ * via an Authorization header computed IN-SANDBOX from the provisioned env: the token never
+ * appears in the script text, the process argv beyond the transient git call, the clone URL,
+ * or .git/config.
+ */
+export declare function provisionCloneSubject(desktop: E2BDesktopSandbox, args: {
+    repo: string;
+    depth: number;
+    serve: LabSubjectServe;
+    /** Declared subject state (seed steps; external declaration is provenance-only). */
+    state?: LabSubjectState;
+    hasGithubToken: boolean;
+    requestTimeoutMs: number;
+    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    scrub: (text: string) => string;
+    /** Called the moment the cloned commit resolves, so provenance survives later failures. */
+    onCommit?: (commit: string) => void;
+    /** Called the moment each state step finishes (mirrors onCommit), success or failure. */
+    onStateStep?: (record: RunSubjectStateStepRecord) => void;
+    /** Called at each phase boundary (started/completed): clone, install, build, serve start,
+     *  ready, and each subject.state seed-step group. */
+    onPhase?: (event: SubjectPhaseEvent) => void;
+} & DetachedTimers): Promise<string | undefined>;
+/**
+ * Provision a local-tree subject inside the sandbox: upload the once-per-run packed archive
+ * (identical bytes across every fan-out lane) → extract it into SUBJECT_DIR → the
+ * same shared serve pipeline provisionCloneSubject uses. Unlike the clone route there is no
+ * in-sandbox git refresh: the archive excludes .git entirely (see source-archive.ts), so
+ * subject identity is the host-side LocalTreeArchive captured at pack time, never anything
+ * resolved in-sandbox.
+ */
+export declare function provisionLocalTreeSubject(desktop: E2BDesktopSandbox, args: {
+    /** The once-per-run packed archive bytes (shared byte-identically across every lane). */
+    archiveBuffer: ArrayBuffer;
+    serve: LabSubjectServe;
+    /** Declared subject state (seed steps; external declaration is provenance-only). */
+    state?: LabSubjectState;
+    requestTimeoutMs: number;
+    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    scrub: (text: string) => string;
+    /** Called the moment each state step finishes, success or failure. */
+    onStateStep?: (record: RunSubjectStateStepRecord) => void;
+    /** Called at each phase boundary (started/completed): upload, extract, install, build,
+     *  serve start, ready, and each subject.state seed-step group. */
+    onPhase?: (event: SubjectPhaseEvent) => void;
+} & DetachedTimers): Promise<void>;
+/**
+ * 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;
+}>;
+/** sha256 hex of the exact command string, first 16 chars (the promptDigest convention). */
+export declare function commandDigestOf(command: string): string;
+/**
+ * Resolve the bundle's state marker from the declaration and what actually ran.
+ * Precedence: external declared → "unpinned" (seed records, if any, stay attached — a
+ * migrated external DB is still unpinned overall); else seed declared → "seeded" only when
+ * every declared step executed ok on a live run, otherwise "declared-not-run" (dry-run
+ * contract bundles and failed live provisioning); no declaration → "undeclared".
+ */
+export declare function resolveSubjectState(args: {
+    declared: LabSubjectState | undefined;
+    dryRun: boolean;
+    executed: RunSubjectStateStepRecord[];
+}): RunSubjectProvenance["state"];
+/**
+ * Project a computer-use session into a humanish.run-bundle.v1. The load-bearing line is
+ * `stream.actor = session.trace` — the provider-neutral ActorTrace seam the Observer renders.
+ * Exported for the bundle-builder tests.
+ */
+export declare function buildCuaBundle(args: {
+    actorId: string;
+    appUrl: string;
+    laneId?: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+    createdAt: string;
+    dryRun: boolean;
+    labId: string;
+    labTitle?: string;
+    mission: string;
+    persona: ActorPersonaRef;
+    resolution: [number, number];
+    /** Device metadata for the stream viewport (honest; isMobile/DSF are not rendered on this route). */
+    deviceScaleFactor?: number;
+    isMobile?: boolean;
+    runId: string;
+    screenshots: string[];
+    /**
+     * Capture-time screenshot policy ("blurred" when policies.redactScreenshots, else "raw").
+     * When a session ran, its trace's `redaction.screenshots` is the evidence-of-record and
+     * wins; this fallback keeps labels honest for frames written before a mid-session failure
+     * (no trace exists to testify then). Defaults to "raw" — the engine default.
+     */
+    captureRedaction?: "raw" | "blurred";
+    session?: CuaLoopResult;
+    sessionError?: string;
+    source: RunBundle["source"];
+    /** Provisioned-route provenance (clone or local-tree): what the actor actually drove (names
+     * + digests only, never values or command text), including the subject's state story. */
+    subjectProvenance?: CuaSubjectProvenanceArg;
+    /**
+     * Entry kind for the non-clone subject.declared event (invariant 5 — declare what the subject
+     * WAS). "local-app": an already-running LOCAL dev server driven in-process, un-pinnable —
+     * declared honestly as caller-provisioned/unpinned with no E2B. Absent: a plain app-url entry.
+     */
+    entryKind?: "local-app";
+    /** The custom E2B desktop template (image) this lane launched on, when configured (provenance). */
+    desktopTemplate?: string;
+    /** The configured browser choice and the command that opened, when explicitly configured. */
+    desktopBrowser?: DesktopBrowserEvidence;
+    traceArtifactPath?: string;
+    providerResources?: RunProviderResource[];
+    inProgress?: boolean;
+    /** Completed subject-phase records (clone/upload/extract/install/build/ready/state groups)
+     *  to fold into bundle.events, so run.json carries real phase timing after the fact. */
+    phaseEvents?: SubjectPhaseEvent[];
+}): RunBundle;
+/**
+ * Project N>1 fan-out lanes into a humanish.run-bundle.v1 (the evidence schema is unchanged; this
+ * is a new producer for the multi-stream shape). One sim + one stream per lane; per-lane
+ * provenance/session events; a recorded `cua-lab.fanout.plan` event (and a `cua-lab.fanout.fail-fast`
+ * event when a harness error skipped queued lanes). N-ary verify/Observer already handle multiple
+ * streams. The N=1 path NEVER reaches here (buildCuaBundle owns it, byte-stable).
+ */
+export declare function buildCuaFanoutBundle(args: {
+    specs: CuaLaneSpec[];
+    outcomes?: LaneRunOutcome[];
+    laneSubjects: CuaSubjectProjection[];
+    aggregateSubject: CuaSubjectProjection;
+    descriptor: CuaActorDescriptor;
+    appUrl: string;
+    createdAt: string;
+    dryRun: boolean;
+    config: LabConfig;
+    runId: string;
+    source: RunBundle["source"];
+    plan: CuaLanePlan;
+    rerun?: RunRerunLineage;
+    failFastReason?: string;
+    cloneRoute: boolean;
+    localTreeRoute?: boolean;
+    publicRepo?: string;
+    subjectEnvNames: string[];
+    inProgress?: boolean;
+}): RunBundle;