humanish 0.105.0 → 0.106.0

package/dist/actors/computer-use/actor.d.ts

@@ -0,0 +1,77 @@
+import type { ActorPersonaRef, ActorTokenUsage, ActorTraceItem } from "../contract.js";
+import { type CuaExecutor, type CuaLiveMetadata, type CuaLoopResult, type CuaProvider, type CuaSafetyCheck } from "./loop.js";
+import { type E2BDesktopExecutorOptions, type E2BDesktopLike } from "../../substrates/e2b/desktop-executor.js";
+import { type OpenAiResponsesProviderOptions } from "./openai-provider.js";
+import { type RedactionHooks } from "../../evidence/redaction.js";
+import type { DwellWindow, StopWhen } from "../stop-conditions.js";
+import type { LabTask } from "../../lab/tasks.js";
+export interface CuaActorSessionOptions {
+    /** The composed mission (persona + scenario/lane instruction) handed to the model. */
+    instructions: string;
+    /** Provenance of the persona this actor embodies (id + applied traits + prompt digest). */
+    persona: ActorPersonaRef;
+    /** Hard wall-clock runaway guard — the only count-free hard stop the loop honors. */
+    timeoutMs: number;
+    signal?: AbortSignal;
+    /** Live provider construction (used when `provider` is not injected). */
+    openai?: OpenAiResponsesProviderOptions;
+    /** Live executor construction (used when `executor` is not injected). */
+    desktop?: E2BDesktopLike;
+    executorOptions?: E2BDesktopExecutorOptions;
+    /**
+     * DI seams — inject to bypass live construction (CI uses these for zero-spend tests; library
+     * callers use them to drive a state-driven, non-vision flow). NOTE: a STATE executor (one
+     * whose observe() returns no screenshot — see CuaObservation.screenshot optional) MUST be
+     * paired with a NON-vision provider (requiresFrame falsey). The default OpenAI provider is
+     * vision-based and would fail closed against a screenshot-less observation. See
+     * docs/architecture/state-driven-executor.md.
+     */
+    provider?: CuaProvider;
+    executor?: CuaExecutor;
+    redaction?: RedactionHooks;
+    now?: () => number;
+    /**
+     * Decide which model-flagged safety checks to acknowledge; returned checks are echoed back
+     * (verbatim wire triples) on the next turn's request so the model proceeds. Omitted here means
+     * the loop's own fail-closed default applies (pause on any check). No auto-ack policy ships yet.
+     */
+    acknowledgeSafetyChecks?: (checks: CuaSafetyCheck[]) => CuaSafetyCheck[] | null;
+    idleSteps?: number;
+    noProgressSteps?: number;
+    /**
+     * Redact persisted screenshots (blur+downscale). Default FALSE — full fidelity for local use.
+     * Set true for unowned subjects or share-as-is bundles. The provider always sees raw frames.
+     */
+    redactScreenshots?: boolean;
+    /** Literal scrub for known provisioned values, composed before redactText on model narration. */
+    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 stop guards evaluated between model turns. */
+    stopWhen?: StopWhen;
+    /** A declared observation window (#510), forwarded to the loop. */
+    dwell?: DwellWindow;
+    /** The lab's declared protocol; the loop records a corroborated task funnel on the trace (#414).
+     *  Only the `success` criteria are read here — the participant-facing goals are already composed
+     *  into `instructions` upstream, and the criteria never reach the prompt. */
+    tasks?: readonly LabTask[];
+    /** FAIL-CLOSED spend cap (USD) threaded to the loop; absent = uncapped. See CuaLoopOptions.maxUsd. */
+    maxUsd?: number;
+    /** Injected pure per-turn cost estimator paired with `maxUsd`. See CuaLoopOptions.estimateTurnCostUsd. */
+    estimateTurnCostUsd?: (usage: ActorTokenUsage) => number | null;
+    /** RUN-LEVEL spend guard threaded to the loop (#299). See CuaLoopOptions.overRunBudget. */
+    overRunBudget?: (usage: ActorTokenUsage) => string | null;
+    /** Stricter unknown-usage policy for capped sessions (see CuaLoopOptions); it also makes the
+     *  OpenAI provider send one HTTP dispatch per turn. Library-only. */
+    requireReportedUsageForSpendCap?: boolean;
+    /** RUNTIME-ONLY observed-URL callback threaded to the loop; see CuaLoopOptions.onObservedUrl. Used by
+     *  the concurrent shared-world handoff barrier to latch a host seat's live /lobby/CODE URL. */
+    onObservedUrl?: (url: string | undefined) => void;
+    /** RUNTIME-ONLY per-turn narration callback threaded to the loop; see CuaLoopOptions.onMessage. */
+    onMessage?: (text: string) => void;
+    /** RUNTIME-ONLY per-turn raw-frame callback threaded to the loop; see CuaLoopOptions.onScreenshot. */
+    onScreenshot?: (frame: Buffer) => void;
+    /** Per-turn trace snapshot callback threaded to the loop (#441); see CuaLoopOptions.onTrace. */
+    onTrace?: (items: readonly ActorTraceItem[], usage: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
+}
+export declare function runCuaActorSession(options: CuaActorSessionOptions): Promise<CuaLoopResult>;

package/dist/actors/computer-use/actor.js

@@ -0,0 +1,78 @@
+// The registry-facing wrapper for the OpenAI Computer Use (CUA) actor. runComputerUseLoop needs
+// fully-constructed provider/executor instances; exposing that raw through the actor registry
+// would leak adapter construction to every call site. So runCuaActorSession takes intent-level
+// fields and constructs the provider/executor internally — with DI seams (provider/executor/now)
+// so CI can drive the real loop with fakes and zero network/zero spend (mirrors how the Claude
+// adapter injects its queryFn).
+//
+// The loop already returns a fully-formed ActorTrace at result.trace, so there is no separate
+// toActorTrace mapper — runCuaActorSession returns the CuaLoopResult unchanged.
+import { runComputerUseLoop, } from "./loop.js";
+import { createE2BDesktopExecutor, } from "../../substrates/e2b/desktop-executor.js";
+import { createOpenAiResponsesProvider, } from "./openai-provider.js";
+import { defaultRedactionHooks } from "../../evidence/redaction.js";
+import { estimateActorCostForExecution } from "../../run/pricing.js";
+export async function runCuaActorSession(options) {
+    if (options.provider && options.openai?.maxOutputTokens !== undefined) {
+        throw new Error("openai.maxOutputTokens cannot be enforced by an injected provider.");
+    }
+    const strictSpend = options.requireReportedUsageForSpendCap === true &&
+        (options.maxUsd !== undefined || options.overRunBudget !== undefined);
+    const provider = options.provider ?? buildProvider(options.openai, strictSpend);
+    const executor = options.executor ?? buildExecutor(options.desktop, options.executorOptions);
+    const loopOptions = {
+        instructions: options.instructions,
+        provider,
+        executor,
+        persona: options.persona,
+        redaction: options.redaction ?? defaultRedactionHooks,
+        timeoutMs: options.timeoutMs,
+        now: options.now ?? (() => Date.now()),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.idleSteps === undefined ? {} : { idleSteps: options.idleSteps }),
+        ...(options.noProgressSteps === undefined ? {} : { noProgressSteps: options.noProgressSteps }),
+        ...(options.acknowledgeSafetyChecks === undefined
+            ? {}
+            : { acknowledgeSafetyChecks: options.acknowledgeSafetyChecks }),
+        ...(options.redactScreenshots === undefined
+            ? {}
+            : { redactScreenshots: options.redactScreenshots }),
+        ...(options.scrubText === undefined ? {} : { scrubText: options.scrubText }),
+        ...(options.writeScreenshot === undefined ? {} : { writeScreenshot: options.writeScreenshot }),
+        ...(options.stopWhen === undefined ? {} : { stopWhen: options.stopWhen }),
+        ...(options.dwell === undefined ? {} : { dwell: options.dwell }),
+        ...(options.tasks === undefined ? {} : { tasks: options.tasks }),
+        ...(options.maxUsd === undefined ? {} : { maxUsd: options.maxUsd }),
+        ...(options.estimateTurnCostUsd === undefined
+            ? {}
+            : { estimateTurnCostUsd: options.estimateTurnCostUsd }),
+        ...(options.overRunBudget === undefined ? {} : { overRunBudget: options.overRunBudget }),
+        ...(options.requireReportedUsageForSpendCap === undefined
+            ? {}
+            : { requireReportedUsageForSpendCap: options.requireReportedUsageForSpendCap }),
+        ...(options.onObservedUrl === undefined ? {} : { onObservedUrl: options.onObservedUrl }),
+        ...(options.onMessage === undefined ? {} : { onMessage: options.onMessage }),
+        ...(options.onScreenshot === undefined ? {} : { onScreenshot: options.onScreenshot }),
+        ...(options.onTrace === undefined ? {} : { onTrace: options.onTrace }),
+    };
+    const result = await runComputerUseLoop(loopOptions);
+    if (result.trace.executionProfile?.billing === "account-unknown") {
+        result.trace.estimatedCost = estimateActorCostForExecution(result.trace.tokenUsage, result.trace.ids.model, result.trace.executionProfile);
+    }
+    return result;
+}
+function buildProvider(openai, strictSpend = false) {
+    if (!openai) {
+        throw new Error("runCuaActorSession requires either `provider` (injected) or `openai` provider options.");
+    }
+    return createOpenAiResponsesProvider({
+        ...openai,
+        ...(strictSpend ? { singleDispatch: true } : {}),
+    });
+}
+function buildExecutor(desktop, executorOptions) {
+    if (!desktop) {
+        throw new Error("runCuaActorSession requires either `executor` (injected) or `desktop` to build one.");
+    }
+    return createE2BDesktopExecutor(desktop, executorOptions ?? {});
+}

package/dist/actors/computer-use/admission-limit.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A caller's adapter refused this request BEFORE provider dispatch because a configured
+ * local control limit was reached. This is an adapter declaration, not a provider response
+ * or independent transport/billing attestation. Never use it for a dispatched request whose
+ * outcome or usage is unknown. Import this class from the same humanish installation as the
+ * loop/provider; names, message text and lookalike objects are not the contract.
+ */
+export declare class CuaAdmissionLimitError extends Error {
+    constructor();
+}
+/** Internal nominal check: neither a matching payload nor a forged prototype is a declaration. */
+export declare function isCuaAdmissionLimitError(error: unknown): error is CuaAdmissionLimitError;

package/dist/actors/computer-use/admission-limit.js

@@ -0,0 +1,19 @@
+const admissionLimits = new WeakSet();
+/**
+ * A caller's adapter refused this request BEFORE provider dispatch because a configured
+ * local control limit was reached. This is an adapter declaration, not a provider response
+ * or independent transport/billing attestation. Never use it for a dispatched request whose
+ * outcome or usage is unknown. Import this class from the same humanish installation as the
+ * loop/provider; names, message text and lookalike objects are not the contract.
+ */
+export class CuaAdmissionLimitError extends Error {
+    constructor() {
+        super("The adapter refused the request before provider dispatch because a local admission limit was reached.");
+        this.name = "CuaAdmissionLimitError";
+        admissionLimits.add(this);
+    }
+}
+/** Internal nominal check: neither a matching payload nor a forged prototype is a declaration. */
+export function isCuaAdmissionLimitError(error) {
+    return typeof error === "object" && error !== null && admissionLimits.has(error);
+}

package/dist/actors/computer-use/executor-error.js

@@ -0,0 +1,48 @@
+const messages = Object.freeze({
+    executor_closed: "Desktop session is closed.",
+    executor_not_ready: "Desktop executor is not ready.",
+    executor_busy: "Desktop executor is handling another request.",
+    invalid_request: "Desktop executor rejected an invalid request.",
+    invalid_response: "Desktop executor returned an invalid response.",
+    protocol_mismatch: "Desktop executor protocol does not match.",
+    session_revoked: "Desktop executor session was revoked.",
+    transport_failed: "Desktop executor transport failed.",
+    deadline_exceeded: "Desktop executor request exceeded its deadline.",
+    action_rejected: "Desktop executor rejected the action.",
+    execution_failed: "Desktop executor could not complete the request.",
+    cancelled: "Desktop executor request was cancelled.",
+});
+export function isCuaExecutorErrorCode(value) {
+    return typeof value === "string" && Object.hasOwn(messages, value);
+}
+const executorErrors = new WeakSet();
+/**
+ * An executor's bounded failure declaration. No backend message, cause, action payload or
+ * transport details belong here. `not_dispatched` requires evidence that dispatch never
+ * began; a lost acknowledgement or partial action is `outcome_uncertain`, never a retry.
+ * Import from the same installation as the loop: names and lookalike objects do not qualify.
+ */
+export class CuaExecutorError extends Error {
+    code;
+    disposition;
+    constructor(code, disposition) {
+        if (!isCuaExecutorErrorCode(code) ||
+            (disposition !== "not_dispatched" && disposition !== "outcome_uncertain")) {
+            throw new TypeError("Invalid desktop executor error declaration.");
+        }
+        super(messages[code]);
+        this.name = "CuaExecutorError";
+        this.code = code;
+        this.disposition = disposition;
+        // Keep the values used in durable diagnostics finite even for JavaScript callers.
+        Object.defineProperties(this, {
+            code: { writable: false, configurable: false },
+            disposition: { writable: false, configurable: false },
+        });
+        executorErrors.add(this);
+    }
+}
+/** A forged prototype is not an executor declaration. */
+export function isCuaExecutorError(error) {
+    return typeof error === "object" && error !== null && executorErrors.has(error);
+}

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

@@ -0,0 +1,26 @@
+import type { LoopSession } from "./session.js";
+import type { CuaAction, CuaTurnRequest } from "./types.js";
+/** A public-safe one-line action label. Never includes raw typed text. */
+export declare function describeCuaAction(action: CuaAction): string;
+/**
+ * A public-safe fingerprint of ONE turn's actions, used only in memory to tell "trying the same
+ * thing again" from "trying something new" (#383).
+ *
+ * Never includes typed text or key contents — a `type` contributes its LENGTH, exactly as
+ * describeCuaAction does, so this can never become a keylogger. Coordinates are bucketed so that
+ * re-clicking the same control counts as a repeat while moving to a different control does not.
+ */
+export declare function actionFingerprint(actions: readonly CuaAction[]): string;
+export declare function isIdleTurn(actions: readonly CuaAction[]): boolean;
+export interface ActionBatch {
+    /** Host input acknowledgements for the provider's next request. */
+    readonly execution: NonNullable<CuaTurnRequest["previousExecution"]>;
+    /** Guidance for the next request, set when a pre-dispatch rejection stopped the batch. */
+    readonly hint: string | undefined;
+}
+/**
+ * Dispatch one turn's actions in order. A declared pre-dispatch rejection stops the batch and
+ * leaves the desktop usable; a failed desktop command skips its action; any other failure ends
+ * the session.
+ */
+export declare function runActionBatch(session: LoopSession, actions: readonly CuaAction[]): Promise<ActionBatch>;

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

@@ -0,0 +1,245 @@
+import { classifyCuaAction } from "../../affordance.js";
+import { commandFailureInfo, isCommandExitError } from "../../../substrates/command-failure.js";
+import { CuaExecutorError, isCuaExecutorError } from "../executor-error.js";
+import { CuaAbortError, CuaDeadlineError, CuaStallError, raceCallBound, raceSessionDeadline, requestScope, } from "./race.js";
+import { notice } from "./trace.js";
+// The participant's actions: their public labels, what counts as a material action, and how one
+// turn's batch is dispatched to the desktop.
+/** Click/scroll coordinates are bucketed to this many pixels before fingerprinting, so a one-pixel
+ *  jitter between two otherwise identical clicks still reads as the same attempt. */
+const ACTION_FINGERPRINT_BUCKET = 24;
+const RECENT_ACTION_TITLES = 8;
+/** The keys a pointer action holds down: key names, never typed text. */
+function heldKeysOf(action) {
+    return "heldKeys" in action && action.heldKeys !== undefined ? action.heldKeys : [];
+}
+/** The label suffix for a pointer action's held keys. */
+function heldKeysSuffix(action) {
+    const keys = heldKeysOf(action);
+    return keys.length > 0 ? ` holding ${keys.join("+")}` : "";
+}
+/** A public-safe one-line action label. Never includes raw typed text. */
+export function describeCuaAction(action) {
+    return describeAction(action) + heldKeysSuffix(action);
+}
+function describeAction(action) {
+    switch (action.kind) {
+        case "click":
+            return `click (${action.x}, ${action.y})`;
+        case "double_click":
+            return `double-click (${action.x}, ${action.y})`;
+        case "move":
+            return `move (${action.x}, ${action.y})`;
+        case "scroll":
+            return `scroll (${action.dx}, ${action.dy}) at (${action.x}, ${action.y})`;
+        case "type":
+            return `type [${action.text.length} chars]`;
+        case "speak":
+            return `speak [${action.text.length} chars]`;
+        case "keypress":
+            return `keypress ${action.keys.join("+")}`;
+        case "drag":
+            return `drag ${action.path.length} points`;
+        case "wait":
+            return action.ms === undefined ? "wait" : `wait ${action.ms}ms`;
+        case "screenshot":
+            return "screenshot";
+    }
+}
+/**
+ * A public-safe fingerprint of ONE turn's actions, used only in memory to tell "trying the same
+ * thing again" from "trying something new" (#383).
+ *
+ * Never includes typed text or key contents — a `type` contributes its LENGTH, exactly as
+ * describeCuaAction does, so this can never become a keylogger. Coordinates are bucketed so that
+ * re-clicking the same control counts as a repeat while moving to a different control does not.
+ */
+export function actionFingerprint(actions) {
+    const bucket = (value) => Math.round(value / ACTION_FINGERPRINT_BUCKET);
+    return actions
+        .map((action) => {
+        // A shift-click and a plain click on one control are different attempts.
+        const keys = heldKeysOf(action);
+        const held = keys.length > 0 ? `+${keys.join("+")}` : "";
+        switch (action.kind) {
+            case "click":
+            case "double_click":
+            case "move":
+                return `${action.kind}@${bucket(action.x)},${bucket(action.y)}${held}`;
+            case "scroll":
+                return `scroll@${bucket(action.x)},${bucket(action.y)}:${Math.sign(action.dx)},${Math.sign(action.dy)}${held}`;
+            case "type":
+                return `type:${action.text.length}`;
+            case "speak":
+                return `speak:${action.text.length}`;
+            case "keypress":
+                return `keypress:${action.keys.join("+")}`;
+            case "drag":
+                return `drag:${action.path.length}${held}`;
+            case "wait":
+                return "wait";
+            case "screenshot":
+                return "screenshot";
+        }
+    })
+        .join("|");
+}
+/** Screenshots and waits only look; every other action is the participant acting. */
+function isIdleAction(action) {
+    return action.kind === "screenshot" || action.kind === "wait";
+}
+export function isIdleTurn(actions) {
+    return actions.every(isIdleAction);
+}
+/**
+ * The material-action rule: a non-idle action counts once the desktop may have received it. An
+ * action the executor declared not dispatched, or a desktop command that failed and was skipped,
+ * is not progress. An action whose outcome is unknown (the loop stopped waiting, or it failed
+ * without a declaration) counts as an attempt. `status` is undefined when no acknowledgement was
+ * returned.
+ */
+function isMaterialAttempt(action, status) {
+    return !isIdleAction(action) && status !== "skipped" && status !== "not_dispatched";
+}
+function rejectedActionHint(title) {
+    return `Your action (${title}) was rejected before dispatch. No input from that action or the rest of its batch was sent. Choose your next action from the fresh screenshot; do not assume the rejected action succeeded.`;
+}
+/**
+ * Dispatch one turn's actions in order. A declared pre-dispatch rejection stops the batch and
+ * leaves the desktop usable; a failed desktop command skips its action; any other failure ends
+ * the session.
+ */
+export async function runActionBatch(session, actions) {
+    const execution = { actions: [] };
+    const { actionHistory, trace } = session;
+    for (const [index, action] of actions.entries()) {
+        if (session.signal?.aborted)
+            throw new CuaAbortError();
+        const title = describeCuaAction(action);
+        actionHistory.lastActionTitle = title;
+        actionHistory.recentActionTitles.push(title);
+        if (actionHistory.recentActionTitles.length > RECENT_ACTION_TITLES)
+            actionHistory.recentActionTitles.shift();
+        trace.bump("actions");
+        // Classify BEFORE execute, mirroring counts.actions: the record is of what the actor
+        // CHOSE, so an action that then fails to actuate is still an honest record of the route
+        // it reached for.
+        actionHistory.affordances.push(classifyCuaAction(action));
+        session.phase = `executing ${title}`;
+        let status;
+        try {
+            status = await dispatchAction(session, action, title);
+        }
+        catch (error) {
+            const declared = isCuaExecutorError(error)
+                ? error.disposition
+                : isCommandExitError(error)
+                    ? "skipped"
+                    : undefined;
+            if (declared !== undefined)
+                execution.actions.push({ index, status: declared });
+            countAttempt(session, action, title, declared);
+            if (isCuaExecutorError(error) &&
+                error.code === "action_rejected" &&
+                error.disposition === "not_dispatched") {
+                // Later actions may depend on this one (type, then submit). Return
+                // their full acknowledgement list and let a fresh observation decide.
+                for (let later = index + 1; later < actions.length; later++) {
+                    execution.actions.push({ index: later, status: "not_dispatched" });
+                }
+                trace.record("notice", () => notice("warn", "action rejected before dispatch", session.redactNarration(`action: ${title}; code: action_rejected; disposition: not_dispatched; remaining batch actions not dispatched: ${actions.length - index - 1}`)));
+                return { execution, hint: rejectedActionHint(title) };
+            }
+            if (isCuaExecutorError(error) || !isCommandExitError(error))
+                throw error;
+            // A skipped action changes nothing on screen, so a persistently-failing run makes no
+            // progress and still terminates honestly via the idle/no-progress backstop (gave_up),
+            // never a silent actor_error and never an infinite loop.
+            recordCommandFailure(session, title, error);
+            continue;
+        }
+        execution.actions.push({ index, status });
+        countAttempt(session, action, title, status);
+        trace.record("ui_action", () => ({
+            lifecycle: "completed",
+            title,
+            ...(action.kind === "speak" ? { text: session.redactNarration(action.text) } : {}),
+            // Structured pin coordinates (#441), exactly the click classes the Observer
+            // pins render — recorded fact instead of a title re-parse downstream.
+            ...(action.kind === "click" || action.kind === "double_click"
+                ? { coord: { x: action.x, y: action.y } }
+                : {}),
+        }));
+    }
+    return { execution, hint: undefined };
+}
+function countAttempt(session, action, title, status) {
+    if (!isMaterialAttempt(action, status))
+        return;
+    session.actionHistory.lastMaterialActionTitle = title;
+    session.trace.counts.materialActions += 1;
+}
+/**
+ * Execute one action. Idle actions only look (#480): a `wait` that hangs inside the SDK has in
+ * effect waited, so a stalled one is skipped with a notice and loses nothing the participant
+ * chose. An action is recorded as completed only after execute() resolves (#248).
+ */
+async function dispatchAction(session, action, title) {
+    if (!isIdleAction(action)) {
+        await executeAction(session, action, title);
+        return "completed";
+    }
+    const boundMs = session.observationTimeoutMs + (action.kind === "wait" ? (action.ms ?? 0) : 0);
+    try {
+        await executeAction(session, action, title, boundMs);
+        return "completed";
+    }
+    catch (error) {
+        if (!(error instanceof CuaStallError))
+            throw error;
+        session.trace.record("notice", () => notice("warn", "observation action stalled; skipped", `${error.what} produced nothing within ${error.afterMs}ms; the desktop was not asked again and the next screenshot decides`));
+        return "skipped";
+    }
+}
+async function executeAction(session, action, title, boundMs) {
+    const { signal } = session;
+    const scope = requestScope(signal);
+    try {
+        const pending = session.executor.execute(action, scope.signal);
+        if (boundMs === undefined)
+            await raceSessionDeadline(pending, session.remaining(), signal);
+        else
+            await raceCallBound(`idle action ${title}`, pending, session.remaining(), boundMs, signal);
+    }
+    catch (error) {
+        if (error instanceof CuaStallError && session.executor.stallRecovery === "fail_closed") {
+            throw new CuaExecutorError("deadline_exceeded", "outcome_uncertain");
+        }
+        if (error instanceof CuaDeadlineError || error instanceof CuaAbortError) {
+            // The loop's deadline/abort may win before the executor can report whether its
+            // write reached the desktop. Cancellation alone does not establish rollback.
+            session.actionHistory.interruptedActionOutcome = true;
+            session.trace.record("notice", () => notice("warn", "action outcome uncertain", session.redactNarration(`action: ${title}; disposition: outcome_uncertain; the loop stopped waiting before execution was acknowledged; the action was not retried`)));
+        }
+        throw error;
+    }
+    finally {
+        // A deadline also closes async executor preparation, so a late pointer read
+        // cannot actuate after the loop stopped waiting for this action.
+        scope.end();
+    }
+}
+function recordCommandFailure(session, title, error) {
+    const { exitCode, stderrTail } = commandFailureInfo(error);
+    session.trace.record("notice", () => notice("error", "action skipped: desktop command failed", 
+    // Public-safe: describeCuaAction never includes raw typed text, the exit code is a number,
+    // and the tail is only the substrate's own stderr (tailed+whitespace-collapsed); the whole
+    // line is still run through redactNarration (scrubKnownValues + pattern redaction).
+    session.redactNarration([
+        `action: ${title}`,
+        exitCode === undefined ? undefined : `exit code: ${exitCode}`,
+        stderrTail.length > 0 ? `stderr: ${stderrTail}` : undefined,
+    ]
+        .filter(Boolean)
+        .join("; "))));
+}

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

@@ -0,0 +1,42 @@
+import type { CuaAction, CuaObservation } from "./types.js";
+/**
+ * A deterministic, bounded, sorted-key projection of an appState object, used as the friction
+ * loop's progress key. Two structurally-equal states (regardless of key insertion order) map
+ * to the SAME string, so key reordering can never fabricate a progress delta; two different
+ * states map to different strings (within the caps).
+ *
+ * Correctness-load-bearing: it MUST NOT throw on a cyclic or huge input. Cycles are detected
+ * with a seen-set (a back-edge degrades to the marker "[Circular]"); depth, key count, array
+ * length, string length, and total output length are all capped so an adversarial or merely
+ * large appState degrades to a bounded value rather than crashing the loop. Pure: it never
+ * mutates the input. (See docs/architecture/state-driven-executor.md.)
+ */
+export declare function stableProgressKey(appState: Record<string, unknown>): string;
+export interface Backstop {
+    readonly progressKey: string;
+    /** The last few turns' action fingerprints, in memory only, for the #383 corroboration rule. */
+    readonly recentFingerprints: readonly string[];
+    readonly consecutiveIdle: number;
+    readonly consecutiveNoProgress: number;
+    readonly idleProgressForgivenessUsed: number;
+}
+export declare function startBackstop(observation: CuaObservation): Backstop;
+export interface BackstopLimits {
+    readonly idleSteps: number;
+    readonly noProgressSteps: number;
+}
+export interface BackstopStep {
+    readonly backstop: Backstop;
+    readonly idle: boolean;
+    readonly progressed: boolean;
+    /** Recovery nudges for the next request, before a streak trips. */
+    readonly hints: readonly string[];
+    /** The gave_up reason when a streak tripped. */
+    readonly tripReason: string | undefined;
+}
+/** Fold one acted turn and the observation after it into the backstop. */
+export declare function advanceBackstop(previous: Backstop, turn: {
+    actions: readonly CuaAction[];
+    observation: CuaObservation;
+    heardNewSpeech: boolean;
+}, limits: BackstopLimits): BackstopStep;