humanish 0.104.3 → 0.106.0

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

@@ -0,0 +1,316 @@
+import { isCuaExecutorError } from "../executor-error.js";
+import { isCuaPromptRefusedError, isCuaProviderError } from "../provider-error.js";
+import { CuaAbortError, CuaDeadlineError } from "./race.js";
+import { notice } from "./trace.js";
+/**
+ * Read the fixed closing line the prompt asks for (#570): the FIRST non-empty line of the
+ * participant's last message, exactly one of three phrases, punctuation and case forgiven. Anything
+ * else is absence, never a guess. Exported for tests.
+ */
+export function declaredOutcomeFromClosingLine(message) {
+    if (message === undefined)
+        return undefined;
+    const first = message
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+    if (first === undefined)
+        return undefined;
+    const normalized = first.replace(/^[*_#>\s-]+|[*_.!\s]+$/g, "").toLowerCase();
+    if (normalized === "reached the goal")
+        return "reached";
+    if (normalized === "did not reach the goal")
+        return "not_reached";
+    if (normalized === "blocked")
+        return "blocked";
+    return undefined;
+}
+/** The participant's own word for how it ended: a schema field first, then the closing line (#570). */
+export function declaredOutcomeOf(turn) {
+    return turn.outcome ?? declaredOutcomeFromClosingLine(turn.message);
+}
+/**
+ * The participant reported a natural endpoint. "not_reached" is a participant who stopped without
+ * finishing: gave_up, which tallies as abandoned. "blocked" keeps goal_satisfied here (the actor
+ * did stop on purpose) and the lane's credibility read turns it into a blocked participant, the
+ * same path a narrated blocker takes.
+ */
+export function participantEnded(turn, declaredOutcome, redactNarration) {
+    const summary = turn.message?.trim();
+    return {
+        completionReason: declaredOutcome === "not_reached" ? "gave_up" : "goal_satisfied",
+        reason: summary
+            ? redactNarration(summary)
+            : "model reported a natural endpoint with no further action",
+    };
+}
+export const harnessAborted = {
+    completionReason: "harness_error",
+    reason: "run aborted by the harness",
+    stopCause: "harness_aborted",
+};
+/**
+ * The wall-clock deadline. A session that took at least one material (non-idle) action before the
+ * cap reached its BUDGET rather than stalling; a deadline hit with zero material actions is still
+ * an honest failure (timed_out).
+ */
+export function timeLimit(session) {
+    const { timeoutMs } = session;
+    const { materialActions, turns } = session.trace.counts;
+    if (materialActions === 0) {
+        return {
+            completionReason: "timed_out",
+            reason: `wall-clock deadline reached after ${timeoutMs}ms with no material progress`,
+            stopCause: "time_limit",
+        };
+    }
+    return {
+        completionReason: "budget_reached",
+        reason: session.actionHistory.interruptedActionOutcome
+            ? `reached the ${timeoutMs}ms time budget with ${materialActions} material action attempt(s), ${turns} turn(s); the latest action outcome is uncertain`
+            : `reached the ${timeoutMs}ms time budget after productive activity (${materialActions} material action(s), ${turns} turn(s))`,
+        stopCause: "time_limit",
+    };
+}
+/**
+ * A harness spend cap interrupts the session regardless of prior activity. budget_reached maps to
+ * incomplete; zero executed actions do not establish that the participant gave up. Cite the
+ * running estimate, cap, and progress so the operator can inspect the interruption.
+ */
+export function spendLimit(session, estimate, maxUsd) {
+    const { materialActions, turns } = session.trace.counts;
+    const booked = session.usage.reservedRequests;
+    const spend = booked === 0
+        ? `estimated spend $${estimate}`
+        : `estimated spend $${estimate}, including the worst case of ${booked} lost request(s),`;
+    return {
+        completionReason: "budget_reached",
+        reason: materialActions > 0
+            ? `${spend} crossed execution.caps.maxUsd=$${maxUsd} after productive activity (${materialActions} material action(s), ${turns} turn(s)); aborted fail-closed before the next model turn`
+            : `${spend} crossed execution.caps.maxUsd=$${maxUsd} with no material progress; aborted fail-closed before the next model turn`,
+        stopCause: "spend_limit",
+    };
+}
+// Fail closed on a non-finite estimate: NaN > maxUsd is always false, so a cap fed NaN would never
+// trip.
+export const nonFiniteEstimate = {
+    completionReason: "harness_error",
+    reason: "the injected estimateTurnCostUsd returned a non-finite estimate while execution.caps.maxUsd is set; the estimator receives one ActorTokenUsage object. Failing closed instead of running uncapped.",
+};
+/** A study-level stop is a recruiting decision hitting its limit, not this participant's runaway. */
+export function studySpendLimit(reason) {
+    return { completionReason: "budget_reached", reason, stopCause: "study_spend_limit" };
+}
+// A host-authenticated provider may learn its account billing class during startup. Never price
+// that account usage from an API model rate.
+export const accountBilledCaps = {
+    completionReason: "harness_error",
+    reason: "API dollar caps and output-token limits cannot bound account-billed providers; use a finite timeout or an API-billed participant.",
+};
+const noticeEvidence = (status, title, text) => ({
+    kind: "notice",
+    body: () => notice(status, title, text),
+});
+const ADAPTER_LIMIT_REASON = "the adapter reported a local admission limit before provider dispatch; the participant did not report completion. No actions or closing request followed the refusal.";
+export const adapterLimit = {
+    completionReason: "budget_reached",
+    reason: ADAPTER_LIMIT_REASON,
+    stopCause: "adapter_limit",
+    evidence: noticeEvidence("warn", "adapter admission limit reached", ADAPTER_LIMIT_REASON),
+};
+const USAGE_UNREPORTED_REASON = "provider usage is unavailable for a request, so the declared model-spend cap cannot be established; no further or closing request was dispatched";
+export const usageUnreported = {
+    completionReason: "harness_error",
+    reason: USAGE_UNREPORTED_REASON,
+    stopCause: "usage_unreported",
+    evidence: noticeEvidence("error", "provider usage unavailable", USAGE_UNREPORTED_REASON),
+};
+/**
+ * A capped session lost a request without a reply and cannot bound what it cost: no output-token
+ * limit is set, so its worst case is the model's whole output allowance.
+ */
+export function lostRequestUnbounded(turnNumber, lost) {
+    const reason = `provider turn ${turnNumber} ${lost}; its usage is unknown and no maxOutputTokens bounds what it cost, so the declared model-spend cap cannot be established; no further or closing request was dispatched. Set actors[].maxOutputTokens so a capped session can book the worst case and retry.`;
+    return {
+        completionReason: "harness_error",
+        reason,
+        stopCause: "usage_unreported",
+        evidence: noticeEvidence("error", "provider usage unavailable", reason),
+    };
+}
+export function providerStalledTwice(turnNumber, afterMs) {
+    const reason = `provider turn ${turnNumber} stalled twice (${afterMs}ms each); the model produced no turn and the participant was ended rather than left to run out its budget`;
+    return {
+        completionReason: "harness_error",
+        reason,
+        evidence: noticeEvidence("error", "provider turn stalled twice", reason),
+    };
+}
+/**
+ * A provider can exhaust its response budget before producing visible text, or midway through an
+ * action. Never interpret either as participant completion or dispatch actions from an explicitly
+ * incomplete response.
+ */
+export function providerInterrupted(interruption) {
+    const tokenLimit = interruption === "token_limit" || interruption === "output_limit";
+    const unexpectedStatus = interruption === "unexpected_status";
+    const reason = tokenLimit
+        ? "the provider's output/context token limit interrupted this response; the participant did not report completion. No actions or closing request followed the incomplete response."
+        : unexpectedStatus
+            ? "the provider returned an unexpected noncompleted response status; the participant did not report completion. No actions or closing request followed this response."
+            : "the provider returned an explicitly incomplete response; the participant did not report completion. No actions or closing request followed the incomplete response.";
+    return {
+        completionReason: tokenLimit ? "budget_reached" : "harness_error",
+        reason,
+        stopCause: interruption === "output_limit"
+            ? "provider_output_limit"
+            : tokenLimit
+                ? "provider_token_limit"
+                : unexpectedStatus
+                    ? "provider_status"
+                    : "provider_incomplete",
+        evidence: noticeEvidence(tokenLimit ? "warn" : "error", tokenLimit
+            ? "provider token limit reached"
+            : unexpectedStatus
+                ? "unexpected provider response status"
+                : "provider response incomplete", reason),
+    };
+}
+/**
+ * Safety-check categories are provider-defined enums (e.g. "malicious_instructions"), not free
+ * text; the evidence records them (redacted for defense-in-depth) so it shows WHY the run paused.
+ */
+export function blockedOnSafetyChecks(checks) {
+    return {
+        completionReason: "blocked_approval",
+        reason: `paused on model safety check(s): ${checks}; not acknowledged`,
+        evidence: {
+            kind: "approval",
+            body: () => ({ lifecycle: "completed", status: "blocked", title: `safety check: ${checks}` }),
+        },
+    };
+}
+/**
+ * A vision provider against a screenshot-less observation is a fail-closed harness error, not a
+ * silent crash. The provider sets requiresFrame; a state-reasoning provider omits it.
+ */
+export function missingFrame(provider, observation) {
+    if (provider.requiresFrame !== true || observation.screenshot !== undefined)
+        return undefined;
+    return {
+        completionReason: "harness_error",
+        reason: `provider ${provider.id} requires a screenshot frame but the executor returned an observation with no screenshot (vision provider against a state-only executor)`,
+    };
+}
+export function stopWhenMatched(match, observation, redactNarration) {
+    return {
+        completionReason: "goal_satisfied",
+        reason: `stopWhen matched ${match.id} (${match.kinds.join("+")})`,
+        evidence: {
+            kind: "notice",
+            body: () => notice("matched", `stopWhen matched: ${match.id}`, redactNarration(`Harness stop condition matched rule ${match.id} using ${match.kinds.join(", ")}. Raw observed URL/text/appState were runtime-only and were not persisted; when a screenshot was available, the immediately preceding screenshot item is the visual evidence for the matched surface.`)),
+        },
+        debriefTrigger: { kind: "stop_when", observation },
+    };
+}
+export function dwellCompleted(heldMs, when, observation) {
+    return {
+        completionReason: "goal_satisfied",
+        reason: `dwell window complete (${heldMs}ms held ${when})`,
+        debriefTrigger: { kind: "dwell", observation },
+    };
+}
+/** The friction backstop tripped: cite the reason, the last material action and recent actions. */
+export function gaveUp(session, reason) {
+    const { lastMaterialActionTitle, recentActionTitles } = session.actionHistory;
+    const screenshotRef = session.lastScreenshotRef;
+    const details = () => [
+        `reason: ${reason}`,
+        lastMaterialActionTitle === undefined
+            ? "last material action: none"
+            : `last material action: ${lastMaterialActionTitle}`,
+        recentActionTitles.length === 0
+            ? "recent actions: none"
+            : `recent actions: ${recentActionTitles.join(" -> ")}`,
+    ].join("; ");
+    return {
+        completionReason: "gave_up",
+        reason,
+        evidence: {
+            kind: "notice",
+            body: () => ({
+                ...notice("blocked", "computer-use backstop gave up", session.redactNarration(details())),
+                ...(screenshotRef === undefined ? {} : { screenshotRef }),
+            }),
+        },
+    };
+}
+/**
+ * Classify an error that ended the session, with the diagnostics a reader needs to place it.
+ * A stop cause committed by an earlier stop that failed to record is kept.
+ */
+export function stopForError(session, error) {
+    if (error instanceof CuaDeadlineError)
+        return timeLimit(session);
+    if (error instanceof CuaAbortError)
+        return harnessAborted;
+    const redact = (text) => session.redactNarration(text);
+    const { lastActionTitle } = session.actionHistory;
+    const lastAction = () => lastActionTitle === undefined ? undefined : `last action: ${redact(lastActionTitle)}`;
+    const screenshot = session.lastScreenshotRef === undefined ? {} : { screenshotRef: session.lastScreenshotRef };
+    if (isCuaPromptRefusedError(error)) {
+        // The provider's policy decision about the prompt, not a harness fault; never resent.
+        const reason = `${error.message}; the prompt was not sent again`;
+        return {
+            completionReason: "actor_error",
+            reason,
+            stopCause: "provider_refused_prompt",
+            evidence: noticeEvidence("error", "provider refused the prompt", `phase: ${redact(session.phase)}; ${reason}`),
+        };
+    }
+    if (isCuaProviderError(error)) {
+        const reason = `participant provider error: ${error.code}${error.failurePhase ? ` during ${error.failurePhase}` : ""}; cleanup: ${error.receipt.cleanup}`;
+        return {
+            completionReason: "harness_error",
+            reason,
+            evidence: noticeEvidence("error", "participant provider error", reason),
+        };
+    }
+    if (isCuaExecutorError(error)) {
+        const detail = () => [
+            `phase: ${redact(session.phase)}`,
+            `code: ${error.code}`,
+            `disposition: ${error.disposition}`,
+            lastAction(),
+        ]
+            .filter(Boolean)
+            .join("; ");
+        return {
+            completionReason: "harness_error",
+            reason: `desktop executor error: ${error.code}; disposition: ${error.disposition}`,
+            evidence: {
+                kind: "notice",
+                body: () => ({ ...notice("error", "desktop executor error", detail()), ...screenshot }),
+            },
+        };
+    }
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const message = redact(rawMessage);
+    const reason = redact(`computer-use loop error: ${rawMessage}`);
+    const detail = () => [
+        `phase: ${redact(session.phase)}`,
+        error instanceof Error && error.name ? `error: ${redact(error.name)}` : undefined,
+        `message: ${message}`,
+        lastAction(),
+    ]
+        .filter(Boolean)
+        .join("; ");
+    return {
+        completionReason: "actor_error",
+        reason,
+        evidence: {
+            kind: "notice",
+            body: () => ({ ...notice("error", "computer-use loop error", detail()), ...screenshot }),
+        },
+    };
+}

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

@@ -0,0 +1,55 @@
+import { type Stop } from "./ending.js";
+import type { LoopSession } from "./session.js";
+import type { CuaObservation } from "./types.js";
+/** What a checkpoint found: a stop, or the observation the next turn reacts to. */
+export type Checkpoint = {
+    readonly stop: Stop;
+} | {
+    readonly observation: CuaObservation;
+    readonly hint: string | undefined;
+};
+export declare class DesktopObserver {
+    private readonly session;
+    /** New speech arrived since the provider last saw an observation. */
+    heardNewSpeech: boolean;
+    private readonly seenSpeechIds;
+    private pendingHeardSpeech;
+    private dwellDone;
+    constructor(session: LoopSession);
+    /**
+     * Observe, persist the frame, advance the task funnel, run a due dwell window, and check the
+     * harness stop conditions. Turn 0 is the initial observation, before any model turn.
+     */
+    checkpoint(turnNumber: number): Promise<Checkpoint>;
+    /**
+     * Hand an observation the next turn may react to to the runtime hooks, and note whether it
+     * carried app state. Runtime-only: the seat's live location.href goes back to the orchestrator
+     * and is never persisted.
+     */
+    private handToHooks;
+    /**
+     * Every observation that carried app state counts, including dwell frames and the final task
+     * observation, which no turn receives: they feed the task funnel, and the trace notes must say
+     * app state was observed.
+     */
+    private noteAppState;
+    /** The provider received the pending speech; collect afresh for the next observation. */
+    speechDelivered(): void;
+    /**
+     * A done turn takes no actions, so no checkpoint observes the participant's final state, and a
+     * task completed by that state would read as incomplete. One guarded observation feeds the
+     * tracker. An ordinary observe failure changes nothing (the funnel reports what it saw); an
+     * executor failure still fails the harness. No screenshot or stop check rides it, because the
+     * session is already over.
+     */
+    observeFinalTasks(turnNumber: number): Promise<void>;
+    private observeBounded;
+    /**
+     * The observation with every utterance heard since the provider last saw one. New utterances are
+     * recorded as notices; too many pending utterances fail the executor as invalid_response.
+     */
+    private withHeardSpeech;
+    private recordScreenshot;
+    private observeTasks;
+    private dwellIfDue;
+}

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

@@ -0,0 +1,246 @@
+import { evaluateStopWhen } from "../../stop-conditions.js";
+import { CuaExecutorError, isCuaExecutorError } from "../executor-error.js";
+import { CUA_SPEECH_LIMITS } from "../speech.js";
+import { dwellCompleted, missingFrame, stopWhenMatched } from "./ending.js";
+import { CuaAbortError, CuaStallError, raceCallBound } from "./race.js";
+import { notice } from "./trace.js";
+// One projection feeds BOTH the stop guard and the task tracker, so a criterion that would stop
+// the run and a criterion that completes a task can never see different evidence for one turn.
+function stopObservationOf(observation) {
+    return {
+        ...(observation.url === undefined ? {} : { url: observation.url }),
+        ...(observation.text === undefined ? {} : { text: observation.text }),
+        ...(observation.appState === undefined ? {} : { appState: observation.appState }),
+    };
+}
+const pad = (value) => value.toString().padStart(2, "0");
+export class DesktopObserver {
+    session;
+    /** New speech arrived since the provider last saw an observation. */
+    heardNewSpeech = false;
+    seenSpeechIds = new Set();
+    pendingHeardSpeech = [];
+    dwellDone = false;
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * Observe, persist the frame, advance the task funnel, run a due dwell window, and check the
+     * harness stop conditions. Turn 0 is the initial observation, before any model turn.
+     */
+    async checkpoint(turnNumber) {
+        const { session } = this;
+        const { stopWhen } = session.settings;
+        const opening = turnNumber === 0;
+        if (opening)
+            session.phase = "observing initial UI state";
+        else {
+            if (session.signal?.aborted)
+                throw new CuaAbortError();
+            session.phase = `observing UI state after turn ${turnNumber}`;
+        }
+        let observation = this.handToHooks(this.withHeardSpeech(await this.observeBounded(opening ? "initial" : `after turn ${turnNumber}`)));
+        // Fail closed before a vision provider is asked to reason over a missing frame.
+        const frameless = missingFrame(session.provider, observation);
+        if (frameless !== undefined)
+            return { stop: frameless };
+        await this.recordScreenshot(observation, opening ? "turn-00-start" : `turn-${pad(turnNumber)}`);
+        session.flush();
+        this.observeTasks(observation, turnNumber);
+        const dwell = await this.dwellIfDue(observation, turnNumber);
+        let hint;
+        if (dwell !== undefined) {
+            observation = this.handToHooks(this.withHeardSpeech(await this.observeBounded("after dwell")));
+            await this.recordScreenshot(observation, `turn-${pad(turnNumber)}-after-dwell`);
+            this.observeTasks(observation, turnNumber);
+            if (dwell.next === "stop") {
+                const when = opening ? "at the start" : `after turn ${turnNumber}`;
+                return { stop: dwellCompleted(dwell.heldMs, when, observation) };
+            }
+            // The window hands this observation to the provider, so it needs the same frame guard. A
+            // window that ends the session sends no turn; its closing request checks the frame itself.
+            const framelessAfterWindow = missingFrame(session.provider, observation);
+            if (framelessAfterWindow !== undefined)
+                return { stop: framelessAfterWindow };
+            hint = `The study held this page under observation for ${Math.round(dwell.heldMs / 1000)} seconds (a declared dwell window; you took no actions in that time). Continue the mission from the current state of the page.`;
+        }
+        const match = evaluateStopWhen(stopWhen, stopObservationOf(observation));
+        if (match) {
+            return { stop: stopWhenMatched(match, observation, (text) => session.redactNarration(text)) };
+        }
+        return { observation, hint };
+    }
+    /**
+     * Hand an observation the next turn may react to to the runtime hooks, and note whether it
+     * carried app state. Runtime-only: the seat's live location.href goes back to the orchestrator
+     * and is never persisted.
+     */
+    handToHooks(observation) {
+        const { onObservedUrl, onScreenshot } = this.session.settings;
+        onObservedUrl?.(observation.url);
+        if (observation.screenshot !== undefined)
+            onScreenshot?.(observation.screenshot);
+        this.noteAppState(observation);
+        return observation;
+    }
+    /**
+     * Every observation that carried app state counts, including dwell frames and the final task
+     * observation, which no turn receives: they feed the task funnel, and the trace notes must say
+     * app state was observed.
+     */
+    noteAppState(observation) {
+        if (observation.appState !== undefined)
+            this.session.observedAppState = true;
+    }
+    /** The provider received the pending speech; collect afresh for the next observation. */
+    speechDelivered() {
+        this.pendingHeardSpeech = [];
+        this.heardNewSpeech = false;
+    }
+    /**
+     * A done turn takes no actions, so no checkpoint observes the participant's final state, and a
+     * task completed by that state would read as incomplete. One guarded observation feeds the
+     * tracker. An ordinary observe failure changes nothing (the funnel reports what it saw); an
+     * executor failure still fails the harness. No screenshot or stop check rides it, because the
+     * session is already over.
+     */
+    async observeFinalTasks(turnNumber) {
+        if (this.session.taskTracker === undefined)
+            return;
+        try {
+            this.session.phase = "observing closing task state";
+            const final = this.withHeardSpeech(await this.observeBounded("closing"));
+            this.noteAppState(final);
+            this.observeTasks(final, turnNumber);
+        }
+        catch (error) {
+            if (isCuaExecutorError(error))
+                throw error;
+        }
+    }
+    // An executor without stallRecovery "fail_closed" gets one retry of a stalled observe (#480).
+    // One that cannot safely replay a pending request opts out, so even a shorter outer bound stops
+    // without retrying.
+    async observeBounded(label) {
+        const { session } = this;
+        const { executor } = session;
+        try {
+            return await raceCallBound(`observe (${label})`, executor.observe(), session.remaining(), session.observationTimeoutMs, session.signal);
+        }
+        catch (error) {
+            if (!(error instanceof CuaStallError))
+                throw error;
+            if (executor.stallRecovery === "fail_closed") {
+                // The outer bound says nothing about whether the still-pending request completed.
+                // The owning session will close it; this loop must not send a replacement request.
+                throw new CuaExecutorError("deadline_exceeded", "outcome_uncertain");
+            }
+            session.trace.record("notice", () => notice("warn", "observation stalled; retrying once", `${error.what} produced nothing within ${error.afterMs}ms; asking the desktop again`));
+            return await raceCallBound(`observe (${label}, retry)`, executor.observe(), session.remaining(), session.observationTimeoutMs, session.signal);
+        }
+    }
+    /**
+     * The observation with every utterance heard since the provider last saw one. New utterances are
+     * recorded as notices; too many pending utterances fail the executor as invalid_response.
+     */
+    withHeardSpeech(observation) {
+        for (const utterance of observation.heardSpeech ?? []) {
+            if (this.seenSpeechIds.has(utterance.id))
+                continue;
+            this.seenSpeechIds.add(utterance.id);
+            this.pendingHeardSpeech.push(utterance);
+            this.heardNewSpeech = true;
+            this.session.trace.record("notice", () => notice("ok", "speech heard", this.session.redactNarration(utterance.text)));
+        }
+        if (this.pendingHeardSpeech.length > CUA_SPEECH_LIMITS.utterances) {
+            throw new CuaExecutorError("invalid_response", "outcome_uncertain");
+        }
+        return this.pendingHeardSpeech.length === 0
+            ? observation
+            : { ...observation, heardSpeech: this.pendingHeardSpeech.slice() };
+    }
+    // No frame, nothing persisted: a state-driven executor returns observations without a
+    // screenshot, counts.screenshots stays 0 and redaction.screenshots reads "n/a". No empty buffer
+    // reaches disk.
+    async recordScreenshot(observation, label) {
+        const { session } = this;
+        const frame = observation.screenshot;
+        if (frame === undefined)
+            return;
+        session.phase = `writing screenshot ${label}`;
+        // Default: persist the raw frame (full fidelity, local-only). redactScreenshots flips to the
+        // publish-safe blurred thumbnail. Either way the bytes the model already saw were raw.
+        const { bytes, method } = session.redactScreenshots
+            ? await session.settings.redaction
+                .redactScreenshot(frame, { label })
+                .then((r) => ({ bytes: r.buffer, method: r.method }))
+            : { bytes: frame, method: "none" };
+        const path = await session.writeScreenshot(`${label}.png`, bytes);
+        const screenshotRef = { path, redaction: method };
+        session.lastScreenshotRef = screenshotRef;
+        session.trace.record("screenshot", () => ({
+            lifecycle: "completed",
+            title: label,
+            screenshotRef,
+        }));
+        session.trace.bump("screenshots");
+    }
+    // Evaluated BEFORE the stopWhen check each turn so a final task whose criterion coincides with
+    // the stop condition still lands in the funnel of the very turn that ends the session.
+    observeTasks(observation, turnNumber) {
+        const { taskTracker } = this.session;
+        if (taskTracker === undefined)
+            return;
+        for (const completion of taskTracker.observe(stopObservationOf(observation), turnNumber)) {
+            // The id is researcher-authored config and the kinds are rule-type names; the matched VALUES
+            // (a URL, page text) never appear here — the same discipline as the stopWhen notice.
+            this.session.trace.record("notice", () => notice("matched", `task completed: ${this.session.redactNarration(completion.id)}`, this.session.redactNarration(`turn ${turnNumber}; matched rule ${completion.matchedRuleIndex} (${completion.matchedKinds.join("+")})`)));
+        }
+    }
+    // The declared observation window (#510). The harness holds, looks, and takes nothing back to
+    // the model: no action, no turn, no tokens. It runs once, cut to whatever session budget is
+    // left, and says in the trace that the time was deliberate.
+    async dwellIfDue(observation, turnNumber) {
+        const { session } = this;
+        const { dwell, onScreenshot } = session.settings;
+        if (dwell === undefined || this.dwellDone)
+            return undefined;
+        if (dwell.when !== undefined &&
+            evaluateStopWhen(dwell.when, stopObservationOf(observation)) === undefined)
+            return undefined;
+        this.dwellDone = true;
+        const trigger = dwell.when === undefined ? "at the start" : "its condition matched";
+        const budget = Math.min(dwell.ms, Math.max(0, session.remaining() - dwell.everyMs));
+        if (budget < dwell.everyMs) {
+            session.trace.record("notice", () => notice("warn", "dwell window skipped", `${trigger} at turn ${turnNumber}, but only ${Math.max(0, session.remaining())}ms of session budget remained for a ${dwell.ms}ms window`));
+            return undefined;
+        }
+        const dwellStartedAtMs = session.now();
+        session.trace.record("notice", () => ({
+            lifecycle: "started",
+            title: "dwell window started",
+            text: `${trigger} at turn ${turnNumber}: holding ${budget}ms, a frame every ${dwell.everyMs}ms, no actions, no model turns`,
+        }));
+        let frames = 0;
+        while (session.now() - dwellStartedAtMs < budget) {
+            if (session.signal?.aborted)
+                throw new CuaAbortError();
+            await session.sleep(Math.min(dwell.everyMs, budget - (session.now() - dwellStartedAtMs)));
+            session.phase = `dwell frame ${frames + 1}`;
+            const frameObservation = this.withHeardSpeech(await this.observeBounded(`dwell frame ${frames + 1}`));
+            frames += 1;
+            if (frameObservation.screenshot !== undefined)
+                onScreenshot?.(frameObservation.screenshot);
+            this.noteAppState(frameObservation);
+            await this.recordScreenshot(frameObservation, `dwell-${pad(frames)}`);
+            session.flush();
+            this.observeTasks(frameObservation, turnNumber);
+        }
+        const heldMs = session.now() - dwellStartedAtMs;
+        session.trace.record("notice", () => notice(
+        // A window that ENDS the session is structured, harness-owned completion evidence, the
+        // same class as a matched stopWhen, and the verdict resolver reads it that way.
+        dwell.then === "stop" ? "matched" : "ok", "dwell window complete", `${frames} frame(s) over ${heldMs}ms; no model turn was requested during the window`));
+        return { next: dwell.then, heldMs };
+    }
+}

package/dist/actors/computer-use/loop/output-limit.d.ts

@@ -0,0 +1,11 @@
+import type { Stop } from "./ending.js";
+import type { LoopSession } from "./session.js";
+import type { CuaTurn } from "./types.js";
+/**
+ * A reply cut off by the output-token limit carries no participant decision: its actions never
+ * run. When the provider sets such a reply aside (outputLimitRetry), the loop books its usage,
+ * checks the spend caps and asks once more with the same request. A second cut-off reply to the
+ * same request ends the session as a provider output limit, as does a provider that cannot set
+ * the reply aside.
+ */
+export declare function retryAfterOutputLimit(session: LoopSession, turn: CuaTurn, turnNumber: number, alreadyRetried: boolean): "retry" | Stop | undefined;

package/dist/actors/computer-use/loop/output-limit.js

@@ -0,0 +1,21 @@
+import { spendStop, unknownSpendStop } from "./spend.js";
+import { notice } from "./trace.js";
+/**
+ * A reply cut off by the output-token limit carries no participant decision: its actions never
+ * run. When the provider sets such a reply aside (outputLimitRetry), the loop books its usage,
+ * checks the spend caps and asks once more with the same request. A second cut-off reply to the
+ * same request ends the session as a provider output limit, as does a provider that cannot set
+ * the reply aside.
+ */
+export function retryAfterOutputLimit(session, turn, turnNumber, alreadyRetried) {
+    if (turn.interruption !== "output_limit")
+        return undefined;
+    if (session.provider.outputLimitRetry !== true || alreadyRetried)
+        return undefined;
+    session.trace.bump("turns");
+    session.lastResponseId = turn.responseId ?? session.lastResponseId;
+    session.usage.record(turn, "interaction");
+    const output = turn.usage?.output;
+    session.trace.record("notice", () => notice("warn", "provider reply cut off by the output limit; asking again", `provider turn ${turnNumber} reached the output-token limit${output === undefined ? "" : ` after ${output} output tokens`} before any action; its actions were not run, and the same request is sent once more`));
+    return spendStop(session) ?? unknownSpendStop(session) ?? "retry";
+}

package/dist/actors/computer-use/loop/provider-call.d.ts

@@ -0,0 +1,19 @@
+import { type Stop } from "./ending.js";
+import type { LoopSession } from "./session.js";
+import type { CuaTurn, CuaTurnRequest } from "./types.js";
+export type TurnReply = {
+    readonly turn: CuaTurn;
+} | {
+    readonly stop: Stop;
+};
+/**
+ * Ask the provider for one turn. A fail_closed provider gets one single dispatch; any other is
+ * raced against turnTimeoutMs (#469) and retried once when it stalls.
+ */
+export declare function requestTurn(session: LoopSession, request: CuaTurnRequest, turnNumber: number): Promise<TurnReply>;
+/**
+ * One provider request that the provider owns through settlement: an outer race never retries
+ * it, and the loop waits a bounded grace for cleanup before booking the receipt. A continuing
+ * request may return actions before it settles; that turn is returned unbooked.
+ */
+export declare function singleDispatch(session: LoopSession, kind: "interaction" | "debrief", dispatch: (signal: AbortSignal) => Promise<CuaTurn>, boundMs: number): Promise<CuaTurn>;