humanish 0.104.3 → 0.106.0

package/dist/actors/computer-use/loop/trace.d.ts

@@ -0,0 +1,35 @@
+import { type ActorCompletionReason, type ActorStatus, type ActorTrace, type ActorTraceItem, type ActorTraceItemKind } from "../../contract.js";
+import type { Stop } from "./ending.js";
+import type { LoopSession } from "./session.js";
+import type { CuaLoopResult } from "./types.js";
+/** A trace item's fields after its id and kind, before the recorder stamps its time. */
+export type TraceBody = Omit<ActorTraceItem, "id" | "kind" | "at">;
+/** An item to record later; its body is built only after its id is allocated. */
+export interface Evidence {
+    readonly kind: ActorTraceItemKind;
+    readonly body: () => TraceBody;
+}
+export declare function notice(status: string, title: string, text: string): TraceBody;
+export type LoopCounts = {
+    turns: number;
+    actions: number;
+    materialActions: number;
+    screenshots: number;
+    reasonings: number;
+    messages: number;
+    idleTurns: number;
+    noProgressTurns: number;
+    debriefCalls?: number;
+};
+export declare class TraceRecorder {
+    private readonly now;
+    readonly items: ActorTraceItem[];
+    readonly counts: LoopCounts;
+    private seq;
+    constructor(now: () => number);
+    record(kind: ActorTraceItemKind, body: () => TraceBody): string;
+    bump(key: keyof LoopCounts): void;
+}
+/** Exported so the participant-vs-harness distinction is pinned directly, not inferred from a run. */
+export declare function statusForCompletionReason(reason: ActorCompletionReason): ActorStatus;
+export declare function loopResult(session: LoopSession, stop: Stop, debrief: ActorTrace["debrief"]): CuaLoopResult;

package/dist/actors/computer-use/loop/trace.js

@@ -0,0 +1,140 @@
+import { summarizeAffordanceUse } from "../../affordance.js";
+import { ACTOR_TRACE_SCHEMA, } from "../../contract.js";
+export function notice(status, title, text) {
+    return { lifecycle: "completed", status, title, text };
+}
+export class TraceRecorder {
+    now;
+    items = [];
+    counts = {
+        turns: 0,
+        actions: 0,
+        materialActions: 0,
+        screenshots: 0,
+        reasonings: 0,
+        messages: 0,
+        idleTurns: 0,
+        noProgressTurns: 0,
+    };
+    seq = 0;
+    constructor(now) {
+        this.now = now;
+    }
+    // The ONE recording choke point (#441): every trace item is stamped `at` from the
+    // loop's injected clock as it is recorded, so timed playback reads recorded facts
+    // (deterministic in tests via the injected `now`). The id is allocated before the body is
+    // built, so a body that fails to build (a redaction error) still consumes its id.
+    record(kind, body) {
+        const id = `${kind}-${(this.seq += 1).toString().padStart(3, "0")}`;
+        this.items.push({ id, kind, ...body(), at: new Date(this.now()).toISOString() });
+        return id;
+    }
+    bump(key) {
+        this.counts[key] = (this.counts[key] ?? 0) + 1;
+    }
+}
+/** Exported so the participant-vs-harness distinction is pinned directly, not inferred from a run. */
+export function statusForCompletionReason(reason) {
+    switch (reason) {
+        case "goal_satisfied":
+        case "turn_completed": // turn_completed is a Codex-lane reason; this loop emits goal_satisfied
+            return "passed";
+        // A session that ran out of time or budget did not reach its goal, whatever it achieved along
+        // the way. Calling that `passed` is how a truncated study came to be reported as a green one —
+        // and why "raise the timeout" kept landing on the operator instead of on the tool. This switch
+        // is exhaustive with no default, so a new completion reason forces a compile error here.
+        case "budget_reached":
+            return "incomplete";
+        case "timed_out":
+            return "timed_out";
+        case "blocked_approval":
+            return "blocked";
+        // A participant who stopped trying is the single most valuable thing a usability study
+        // produces. Recording it as `failed` said the instrument broke, which is a different claim and
+        // a false one — see docs/principles/three-roles.md.
+        case "gave_up":
+            return "abandoned";
+        // Only the harness failing is a harness failure.
+        case "actor_error":
+        case "step_failed": // step_failed is the scripted-browser lane's reason; this loop never emits it
+        case "harness_error":
+            return "failed";
+    }
+}
+export function loopResult(session, stop, debrief) {
+    const { provider, settings, trace: recorder, usage } = session;
+    const { completionReason, reason, stopCause } = stop;
+    const completedAtMs = session.now();
+    const status = statusForCompletionReason(completionReason);
+    const ids = {};
+    if (provider.version !== undefined)
+        ids.model = provider.version;
+    // responseId is provider-authored and opaque; redact for defense-in-depth.
+    if (session.lastResponseId !== undefined)
+        ids.turnId = settings.redaction.redactText(session.lastResponseId);
+    const { counts } = recorder;
+    const screenshotNote = !(counts.screenshots > 0)
+        ? "no screenshots captured"
+        : session.redactScreenshots
+            ? `${counts.screenshots} screenshot(s) redacted to blurred thumbnails via RedactionHooks`
+            : `${counts.screenshots} full-fidelity screenshot(s) retained for local use — NOT redacted for publishing; set redactScreenshots to blur a share-as-is bundle`;
+    // Self-describing artifact (invariant 6): when any observation carried structured app state,
+    // the trace says how the loop handled it: it fed progress and task checks and was not written to
+    // the trace. The appState itself never appears in this bundle.
+    const notes = session.observedAppState
+        ? `${screenshotNote}. App state was observed each turn to drive progress detection (a state-driven executor) and was NOT written to the trace — it is a runtime-only progress input, never persisted as evidence in this slice.`
+        : screenshotNote;
+    const tokenUsage = usage.tokenUsage();
+    const trace = {
+        schema: ACTOR_TRACE_SCHEMA,
+        provider: provider.id,
+        ...usage.liveMetadata(),
+        ...(provider.version === undefined ? {} : { providerVersion: provider.version }),
+        protocol: "cua-loop",
+        lane: "computer-use",
+        persona: settings.persona,
+        redaction: {
+            status: "passed",
+            screenshots: !(counts.screenshots > 0)
+                ? "n/a"
+                : session.redactScreenshots
+                    ? "blurred"
+                    : "raw",
+            notes,
+        },
+        startedAt: new Date(session.startedAtMs).toISOString(),
+        completedAt: new Date(completedAtMs).toISOString(),
+        durationMs: completedAtMs - session.startedAtMs,
+        status,
+        completionReason,
+        ...(stopCause === undefined ? {} : { stopCause }),
+        reason,
+        ids,
+        ...(provider.modelSettings === undefined
+            ? {}
+            : {
+                modelSettings: {
+                    reasoningEffort: provider.modelSettings.reasoningEffort,
+                    ...(provider.modelSettings.maxOutputTokens === undefined
+                        ? {}
+                        : { maxOutputTokens: provider.modelSettings.maxOutputTokens }),
+                },
+            }),
+        counts,
+        items: recorder.items,
+        ...(session.actionHistory.affordances.length > 0
+            ? { affordanceUse: summarizeAffordanceUse(session.actionHistory.affordances) }
+            : {}),
+        ...(session.declaredOutcome === undefined ? {} : { declaredOutcome: session.declaredOutcome }),
+        ...(debrief === undefined ? {} : { debrief }),
+        ...(usage.interactionUsageIncomplete(session.capDeclared)
+            ? { interactionUsageIncomplete: true }
+            : {}),
+        // The funnel is present exactly when a protocol was declared — including a session that ended
+        // on turn 0, whose funnel honestly reads 0/N. No tasks declared means no funnel, not an empty one.
+        ...(session.taskTracker === undefined ? {} : { taskFunnel: session.taskTracker.funnel() }),
+        ...(tokenUsage === undefined ? {} : { tokenUsage }),
+        capabilities: provider.capabilities,
+    };
+    return { status, completionReason, reason, trace };
+}

package/dist/actors/computer-use/loop/types.d.ts

@@ -0,0 +1,404 @@
+import type { HeardSpeech } from "../speech.js";
+import type { ActorCapabilities, ActorExecutionProfile, ActorPersonaRef, ActorSessionResult, ActorTokenUsage, ActorTrace, ActorTraceItem, ParticipantClosingReport, ParticipantDeclaredOutcome, ProviderRequestReceipt } from "../../contract.js";
+import type { RedactionHooks } from "../../../evidence/redaction.js";
+import type { DwellWindow, StopWhen } from "../../stop-conditions.js";
+import type { LabTask } from "../../../lab/tasks.js";
+import type { ReasoningEffort } from "../../reasoning-effort.js";
+/**
+ * One desktop action. `heldKeys` on a pointer action are held down for the whole action and
+ * released after it, named as the provider sent them (for example `SHIFT` for a shift-click). An
+ * executor that cannot hold them refuses the action before dispatch; it never runs the action
+ * without them.
+ */
+export type CuaAction = {
+    kind: "click";
+    x: number;
+    y: number;
+    button?: "left" | "right" | "middle";
+    heldKeys?: string[];
+} | {
+    kind: "double_click";
+    x: number;
+    y: number;
+    heldKeys?: string[];
+} | {
+    kind: "move";
+    x: number;
+    y: number;
+    heldKeys?: string[];
+} | {
+    kind: "scroll";
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+    heldKeys?: string[];
+} | {
+    kind: "type";
+    text: string;
+} | {
+    kind: "keypress";
+    keys: string[];
+} | {
+    kind: "drag";
+    path: Array<{
+        x: number;
+        y: number;
+    }>;
+    heldKeys?: string[];
+} | {
+    kind: "wait";
+    ms?: number;
+} | {
+    kind: "speak";
+    text: string;
+} | {
+    kind: "screenshot";
+};
+/** A captured desktop state: the (optional) frame plus a coarse signature for progress. */
+export interface CuaObservation {
+    /**
+     * Raw PNG bytes of the current desktop. Optional: a state-driven executor omits it, and the loop
+     * persists no screenshot that turn (counts.screenshots stays 0 and redaction.screenshots reads
+     * "n/a"). A provider with requiresFrame needs it; see CuaProvider.requiresFrame.
+     */
+    screenshot?: Buffer;
+    /**
+     * A coarse, quantized signature of the visible UI used for no-progress
+     * detection. Two observations with the same signature are "no progress". The
+     * executor owns how it is computed (url, title, quantized scroll, focused
+     * element, visible controls, etc.). Required: it is the progress key when appState is absent.
+     */
+    stateSignature: string;
+    /**
+     * Structured app state (e.g. a window.app.getState() projection). When present, friction
+     * detection prefers a stable, deterministic, sorted-key JSON projection of it
+     * (stableProgressKey) as the progress key, so route/turn/modal deltas drive progress more
+     * reliably than a quantized screenshot signature can on a pixel-dense UI.
+     *
+     * Runtime-only: appState is never copied into a trace item, reason, id or count; only the
+     * in-memory progress key is derived from it. A structured blob has no detectable secret shape
+     * (the published-evidence scan catches only secret-shaped patterns), so it is handled like
+     * stateSignature, which is never written as text either. Persisting it would need a stringified
+     * projection through redaction.redactText and the lab's scrubText, with its fields capped or
+     * allowlisted, since pattern and literal redaction cannot sanitize an arbitrary blob.
+     */
+    appState?: Record<string, unknown>;
+    /**
+     * Optional browser state captured by an executor that can inspect the driven browser
+     * deterministically (for example via Chrome DevTools Protocol). These fields are runtime-only:
+     * they may drive stopWhen and progress decisions, but the loop never persists raw URL/title/text
+     * into the trace. Persisting arbitrary DOM text would make private-data leakage too easy.
+     */
+    url?: string;
+    /**
+     * The page's vertical scroll offset (window.scrollY), when the executor can read it. Scroll
+     * position is state (#393): inside a scroll-pinned section the viewport stays visually fixed
+     * while the participant advances, so the frame hash alone reads "no change". Runtime-only like
+     * url and text: it feeds the progress key, bucketed, and is never persisted.
+     */
+    scrollY?: number;
+    title?: string;
+    text?: string;
+    /** Finalized speech captured from the participant's speaker sink. */
+    heardSpeech?: HeardSpeech[];
+}
+/**
+ * A safety check the model raised. The triple is preserved verbatim from the
+ * wire: providers match acknowledgements on `id`, so fabricating or collapsing
+ * these fields would break the proceed path.
+ */
+export interface CuaSafetyCheck {
+    /** Wire id the provider matches acknowledgements on. */
+    id: string;
+    /** Provider-defined category code (e.g. "malicious_instructions"). */
+    code: string;
+    /** Human-readable explanation from the model. */
+    message: string;
+}
+export interface CuaTurnRequest {
+    /** Host input acknowledgments for the preceding proposal, never proof of app success. */
+    previousExecution?: {
+        actions: Array<{
+            index: number;
+            status: "completed" | "skipped" | "not_dispatched" | "outcome_uncertain";
+        }>;
+    };
+    /** Persona + task instruction, sent as the system-level steer (first turn). */
+    instructions: string;
+    /** The latest observation for the model to react to. */
+    observation: CuaObservation;
+    /** Opaque continuation handle from the previous turn (provider-specific). */
+    previousResponseId?: string;
+    /** Safety checks the harness chose to acknowledge, passed back to the model. */
+    acknowledgedSafetyChecks?: CuaSafetyCheck[];
+    /**
+     * Harness guidance for this request: a backstop nudge, a dwell-window note, a rejected-action
+     * note, or the closing-report instruction.
+     */
+    contextHint?: string;
+}
+/**
+ * Passed to nextTurn when a spend cap is declared. A provider that sends a request again after a
+ * dispatched attempt failed without a reply (its transport threw) calls beforeResend first. The
+ * loop books that attempt at its worst case and throws when the charge does not fit under the
+ * cap; the provider lets the error propagate and sends nothing more.
+ */
+export interface CuaSpendGate {
+    beforeResend(): void;
+}
+export interface CuaTurn {
+    /**
+     * Set on a turn from a continuing request: a single-dispatch request that returned actions and
+     * is still open. No receipt or usage is settled yet; the loop books both when it settles.
+     */
+    providerRequestPending?: true;
+    providerRequest?: ProviderRequestReceipt;
+    /** Continuation handle for the next turn. */
+    responseId?: string;
+    /** Model chain-of-thought summary, if the provider surfaces it. */
+    reasoning?: string;
+    /** Natural-language message (often the final summary on completion). */
+    message?: string;
+    /** Actions to perform this turn. Empty means the model is done. */
+    actions: CuaAction[];
+    /** Safety checks the provider flagged this turn. Non-empty pauses the run. */
+    pendingSafetyChecks: CuaSafetyCheck[];
+    /** Token accounting for this turn, if available. */
+    usage?: {
+        input?: number;
+        output?: number;
+        cachedInput?: number;
+        cacheWriteInput?: number;
+        /** Per model inference inside this provider interaction. */
+        turns?: Array<{
+            input?: number;
+            output?: number;
+            cachedInput?: number;
+            cacheWriteInput?: number;
+        }>;
+    };
+    /** True when the model reported a natural endpoint (no further action). */
+    done: boolean;
+    /** Explicit provider interruption, independent of actions or participant intent. */
+    interruption?: "output_limit" | "token_limit" | "incomplete" | "unexpected_status";
+    /** The participant's own word for how it ended, when its reply format carries one (#570). */
+    outcome?: ParticipantDeclaredOutcome;
+    /** Present only for an accepted structured closing account. */
+    closingReport?: ParticipantClosingReport;
+}
+/** The model side of the loop. Self-describes its identity and capabilities. */
+export interface CuaProvider {
+    /** Single dispatch; the promise includes owned request cleanup. No stall retry. */
+    readonly requestPolicy?: "fail_closed";
+    readonly executionProfile?: ActorExecutionProfile | undefined;
+    readonly historyTurnsOmitted?: number;
+    readonly id: string;
+    readonly version?: string | undefined;
+    /**
+     * The request settings this provider will actually send, for the trace to record. `version` says
+     * WHICH model; this says how it was asked to run. Optional: a provider with no such settings
+     * records none, and absence stays absence rather than becoming a default nobody chose.
+     */
+    readonly modelSettings?: {
+        readonly reasoningEffort: ReasoningEffort;
+        readonly maxOutputTokens?: number;
+    };
+    readonly capabilities: ActorCapabilities;
+    /**
+     * True when nextTurn needs `observation.screenshot` (a model that reasons over pixels). A
+     * provider that reasons over pixels must set it: the loop then ends a session whose executor
+     * returns no frame as `harness_error`, where the provider would otherwise fail on a blank frame.
+     * It defaults to false, so a vision provider that omits it gets no such guard; see
+     * docs/architecture/state-driven-executor.md.
+     */
+    readonly requiresFrame?: boolean;
+    /**
+     * True when a reply cut off by the output-token limit (`interruption: "output_limit"`) leaves
+     * the provider's conversation where it was, so asking again sends the same request. The loop
+     * then asks once more instead of ending the session. Absent means the session ends there.
+     */
+    readonly outputLimitRetry?: boolean;
+    /** Latched uncertainty from hidden interactive attempts (for example, a transport retry).
+     *  A later success or pre-dispatch refusal cannot make earlier unreported usage complete.
+     *  Attempts reported through a CuaSpendGate, and attempts aborted while one was given, are
+     *  the loop's to account for and are left out. */
+    readonly interactionUsageIncomplete?: boolean;
+    /** Latest known usage of the continuing request. Used only for runtime spend guards. */
+    readonly pendingRequestUsage?: CuaTurn["usage"];
+    nextTurn(req: CuaTurnRequest, signal: AbortSignal, spend?: CuaSpendGate): Promise<CuaTurn>;
+    /** Optional read-only closing report. Implementations must disable tools and make no retries. */
+    debrief?: ((req: CuaTurnRequest, signal: AbortSignal) => Promise<CuaTurn>) | undefined;
+    /** Release lane-owned model resources. Idempotent; reject if cleanup is unconfirmed. */
+    close?(): Promise<void>;
+}
+/** The desktop side of the loop. */
+export interface CuaExecutor {
+    /**
+     * A transport that cannot safely retry or skip an unacknowledged request opts out of
+     * legacy observation/idle stall recovery. Wrappers must preserve this value.
+     */
+    readonly stallRecovery?: "fail_closed";
+    /** True only when this executor can play a `speak` action into the participant microphone. */
+    readonly speechEnabled?: boolean;
+    /** Capture the current desktop frame and its state signature. */
+    observe(): Promise<CuaObservation>;
+    /**
+     * Perform one action. The optional signal ends with this action's loop wait; honor it
+     * before dispatching after async preparation. Wrappers must forward it. Cancellation
+     * does not imply an already-dispatched desktop operation can be stopped.
+     */
+    execute(action: CuaAction, signal?: AbortSignal): Promise<void>;
+}
+export interface CuaLoopOptions {
+    instructions: string;
+    provider: CuaProvider;
+    executor: CuaExecutor;
+    persona: ActorPersonaRef;
+    redaction: RedactionHooks;
+    /** Hard wall-clock runaway guard. The only count-free hard stop. */
+    timeoutMs: number;
+    /**
+     * Per-attempt bound on the provider call (#469), so a hung request is told apart from a
+     * participant still thinking. A stalled turn is retried once with a notice; a second stall ends
+     * the lane as harness_error.
+     */
+    turnTimeoutMs?: number;
+    /**
+     * Per-call bound on observation work (#480): executor.observe() and the idle actions (`wait`,
+     * `screenshot`), whose only job is to look. A `wait` adds its own ms to the bound. A stalled
+     * observe is retried once; a stalled idle action is skipped with a notice.
+     */
+    observationTimeoutMs?: number;
+    /** Injected clock (ms). Lets tests drive deadlines deterministically. */
+    now: () => number;
+    /**
+     * Cancellation. Checked before each turn, each action and each dwell frame, and raced against
+     * every provider and desktop call.
+     */
+    signal?: AbortSignal;
+    /** Idle streak (no material action) that trips the backstop. Default 24. */
+    idleSteps?: number;
+    /** No-progress streak that trips the backstop. Default 20. */
+    noProgressSteps?: number;
+    /**
+     * If the model flags safety checks, decide which to acknowledge. Returning the
+     * list proceeds (the acks are echoed back on the next turn's request); returning
+     * null/[] pauses the run (blocked_approval). Default: pause on any safety check.
+     */
+    acknowledgeSafetyChecks?: (checks: CuaSafetyCheck[]) => CuaSafetyCheck[] | null;
+    /**
+     * Redact (blur+downscale) persisted screenshots. Default FALSE — full-fidelity frames are
+     * retained, because the common case is a developer watching a sim of their OWN app locally
+     * (gitignored .humanish), where blur destroys the core deliverable. Set true for unowned
+     * subjects or when the bundle is meant to be shared as-is. The frame sent to the PROVIDER is
+     * always full-resolution regardless (the model must see the screen to act); this flag only
+     * governs what is PERSISTED. Publish-safety belongs at the publish boundary (commit scan / redactScreenshots), not capture.
+     */
+    redactScreenshots?: boolean;
+    /**
+     * Extra literal scrub for KNOWN provisioned values (which have no detectable "shape", so
+     * pattern redaction cannot catch them), composed BEFORE redactText on every model-authored
+     * text item (reasoning, message, completion summary) and the loop error. The lab passes the
+     * env-value scrubber here so a value the MODEL narrates can never land raw in the trace.
+     * Default: identity (the loop is shape-only on its own).
+     */
+    scrubText?: (text: string) => string;
+    /** Persist a screenshot (raw or redacted per redactScreenshots), returning the trace ref path. */
+    writeScreenshot?: (name: string, bytes: Buffer) => Promise<string>;
+    /**
+     * Deterministic harness-owned success guards. Evaluated after the initial observation and after
+     * every post-action observation, before another model turn is requested. This keeps a lane from
+     * wandering after the product already reached an app-visible endpoint.
+     */
+    stopWhen?: StopWhen;
+    /**
+     * A declared observation window (#510): once its condition matches (or after the first
+     * observation when it has none) the loop holds the page for the window, captures a frame on the
+     * cadence, takes no action and requests no model turn, then hands control back or ends. Runs at
+     * most once per session and never past the session budget.
+     */
+    dwell?: DwellWindow;
+    /** Injected pause for the dwell window's cadence; tests advance their clock through it. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * The lab's declared protocol (#414): discrete tasks whose completion is corroborated by the
+     * same observations stopWhen reads, on the same cadence. The tracker never influences the loop's
+     * control flow — a completed task list does not stop a session (that is stopWhen's job); it only
+     * records the funnel that lands on the trace. The participant-facing halves of these tasks are
+     * already IN `instructions` (composed upstream); the loop reads only the `success` criteria,
+     * which never reach the prompt.
+     */
+    tasks?: readonly LabTask[];
+    /**
+     * Spend cap in USD. When set, the loop stops with budget_reached as soon as the running
+     * estimated spend crosses it, before the next provider turn. Absent means uncapped. maxUsd: 0
+     * can still permit one model request before its reported spend trips the check. Enforcement
+     * needs an estimate, so the lab refuses a cap on an unpriced model at preflight.
+     */
+    maxUsd?: number;
+    /**
+     * Injected PURE per-turn cost estimator (keeps the loop free of the operator rate table and
+     * makes the cap deterministic in tests). Given running (input, output) token totals, returns the
+     * estimated USD, or null when unpriceable. Only consulted when `maxUsd` is set. A null estimate
+     * mid-run cannot trip the cap — preflight already guaranteed a rate exists, so a null here is a
+     * vanished-rate harness condition, not a silent uncapped pass.
+     */
+    estimateTurnCostUsd?: (usage: ActorTokenUsage) => number | null;
+    /**
+     * RUN-LEVEL spend guard (#299): called with this lane's running usage each turn, at the same
+     * point the per-lane cap is checked. Returns a human-readable reason when the STUDY's shared
+     * budget is exhausted, else null. On a non-null return the loop stops with `budget_reached`
+     * regardless of material progress — a study-level stop is a recruiting decision hitting its
+     * limit, not this participant's runaway, so it never reads as `gave_up`.
+     */
+    overRunBudget?: (usage: ActorTokenUsage) => string | null;
+    /**
+     * Stricter handling of unknown usage under a declared cap. Every capped session already stops
+     * before its next request once a request's usage is unknown and unbounded, and resends a lost
+     * request only when its worst case fits under the cap. With this option a reply with missing
+     * usage is not acted on, and any failed request stops the session. A library option: no
+     * built-in route sets it.
+     */
+    requireReportedUsageForSpendCap?: boolean;
+    /**
+     * Runtime-only URL tap: called with `observation.url` for each observation a turn may receive
+     * (the initial one, each post-action one and the one after a dwell window). The loop never
+     * persists the URL. Default: no-op.
+     *
+     * Built-in caller: the external-public shared-world handoff (src/routes/shared-world/handoff.ts)
+     * latches the host participant's lobby URL and checks that each follower reached the same lobby.
+     */
+    onObservedUrl?: (url: string | undefined) => void;
+    /**
+     * Runtime-only narration tap: called with the turn's reasoning and message text, joined by a
+     * newline, once per completed turn before the loop acts on it. An interrupted reply, or one cut
+     * off by the output limit, is not passed. The trace records its own redacted copy; this raw text
+     * stays in memory. Default: no-op.
+     *
+     * Built-in caller: the external-public handoff scans the host's narration for the lobby code,
+     * because the E2B desktop's CDP URL read behind onObservedUrl is unreliable.
+     */
+    onMessage?: (text: string) => void;
+    /**
+     * Runtime-only frame tap: called with each raw frame a turn may receive and each dwell-window
+     * frame, before any redaction. The buffer stays in memory; screenshot persistence is separate and
+     * follows redactScreenshots. Not awaited. Default: no-op.
+     *
+     * Built-in caller: the external-public handoff reads the lobby code off each participant's own
+     * frame until that participant has one: the host's latch, or a follower's convergence observation.
+     */
+    onScreenshot?: (frame: Buffer) => void;
+    /**
+     * Trace snapshot for a watcher (#441): the redacted items recorded so far, with the running
+     * usage so a run can be priced in flight. Called after each checkpoint's screenshot (the initial
+     * observation and every acted turn, so a flush never shows an action without the frame before
+     * it), after each dwell frame, and after a closing request. The array is a fresh copy; its items
+     * are the objects the final trace persists. Not awaited, so a slow flush cannot stall a turn.
+     * Default: no-op.
+     */
+    onTrace?: (items: readonly ActorTraceItem[], usage: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
+}
+export type CuaLiveMetadata = Pick<ActorTrace, "executionProfile" | "providerRequests" | "historyTurnsOmitted">;
+/** What runComputerUseLoop returns; the public name for an actor session result. */
+export type CuaLoopResult = ActorSessionResult;

package/dist/actors/computer-use/loop/types.js

@@ -0,0 +1 @@
+export {};