humanish 0.105.0 → 0.106.0

package/dist/actors/computer-use/loop/provider-call.js

@@ -0,0 +1,208 @@
+import { isCuaAdmissionLimitError } from "../admission-limit.js";
+import { CuaProviderError, isCuaProviderError } from "../provider-error.js";
+import { adapterLimit, providerStalledTwice, usageUnreported } from "./ending.js";
+import { CuaAbortError, CuaDeadlineError, CuaStallError, raceCallBound, requestScope, } from "./race.js";
+import { bookLostRequest, LostRequestRefused, spendGate } from "./spend.js";
+import { notice } from "./trace.js";
+import { reportedCounts, settledReceipt } from "./usage.js";
+// Asking the provider for a turn. A provider with requestPolicy "fail_closed" owns one attempt
+// through settlement and reports a receipt; any other provider is raced against the turn bound
+// and retried once when it stalls. Under a declared cap, a lost request is sent again only when
+// its worst case fits under the cap (spend.ts).
+const CUA_PROVIDER_CLEANUP_GRACE_MS = 5000;
+/**
+ * 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 async function requestTurn(session, request, turnNumber) {
+    const { provider } = session;
+    // A single-dispatch provider owns its one attempt through settlement.
+    if (provider.requestPolicy === "fail_closed") {
+        return {
+            turn: await singleDispatch(session, "interaction", (signal) => provider.nextTurn(request, signal), session.turnTimeoutMs),
+        };
+    }
+    const { signal } = session;
+    const first = requestScope(signal);
+    try {
+        return {
+            turn: await raceCallBound(`provider turn ${turnNumber}`, provider.nextTurn(request, first.signal, spendGate(session, turnNumber)), session.remaining(), session.turnTimeoutMs, signal),
+        };
+    }
+    catch (error) {
+        // Stops are concluded here, before `finally` ends the request scope, so their notices are
+        // recorded before any abort listener runs.
+        if (isCuaAdmissionLimitError(error))
+            return { stop: session.conclude(adapterLimit) };
+        if (error instanceof LostRequestRefused)
+            return { stop: session.conclude(error.stop) };
+        // A thrown request may have been billed without returning usage. Admission refusal is
+        // the explicit no-dispatch exception above; strict capped routes cannot safely retry.
+        if (session.requiresUsage) {
+            session.usage.markUnreported();
+            return { stop: session.conclude(usageUnreported) };
+        }
+        if (!(error instanceof CuaStallError)) {
+            // A provider given the spend gate leaves a request that ends this way to the loop.
+            if (session.capDeclared)
+                session.usage.markUnreported();
+            throw error;
+        }
+        if (session.capDeclared) {
+            const refused = bookLostRequest(session, turnNumber, "stalled");
+            if (refused !== undefined)
+                return { stop: session.conclude(refused) };
+        }
+        return await retryStalledTurn(session, request, turnNumber, error, first);
+    }
+    finally {
+        first.end();
+    }
+}
+async function retryStalledTurn(session, request, turnNumber, stall, stalled) {
+    // Under a cap the stalled request is already booked at its worst case.
+    if (!session.capDeclared)
+        session.usage.markUnreported();
+    session.trace.record("notice", () => notice("warn", "provider turn stalled; retrying once", `${stall.what} produced nothing within ${stall.afterMs}ms; sending the same observation again`));
+    // Two copies of a paid request must not run at once: cancel the stalled one before the retry.
+    stalled.end();
+    const retry = requestScope(session.signal);
+    try {
+        return {
+            turn: await raceCallBound(`provider turn ${turnNumber} (retry)`, session.provider.nextTurn(request, retry.signal, spendGate(session, turnNumber)), session.remaining(), session.turnTimeoutMs, session.signal),
+        };
+    }
+    catch (retryError) {
+        if (isCuaAdmissionLimitError(retryError))
+            return { stop: session.conclude(adapterLimit) };
+        if (retryError instanceof LostRequestRefused)
+            return { stop: session.conclude(retryError.stop) };
+        if (!(retryError instanceof CuaStallError)) {
+            if (session.capDeclared)
+                session.usage.markUnreported();
+            throw retryError;
+        }
+        session.usage.markUnreported();
+        return { stop: session.conclude(providerStalledTwice(turnNumber, retryError.afterMs)) };
+    }
+    finally {
+        retry.end();
+    }
+}
+/**
+ * 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 async function singleDispatch(session, kind, dispatch, boundMs) {
+    const { signal } = session;
+    const scope = requestScope(signal);
+    const settlementRef = {};
+    const pending = Promise.resolve()
+        .then(() => {
+        if (scope.signal.aborted)
+            throw new CuaProviderError("cancelled", {
+                dispatched: false,
+                usageComplete: false,
+                cleanup: "confirmed",
+            });
+        return dispatch(scope.signal);
+    })
+        .then((turn) => {
+        settlementRef.current = { turn };
+        return turn;
+    }, (error) => {
+        settlementRef.current = { error };
+        throw error;
+    });
+    void pending.catch(() => undefined);
+    let outcome;
+    try {
+        const turn = await raceCallBound(`participant ${kind}`, pending, session.remaining(), boundMs, signal);
+        outcome = { turn, continuing: isContinuingTurn(kind, turn) };
+    }
+    catch (error) {
+        outcome = { error };
+    }
+    finally {
+        scope.end();
+        if (settlementRef.current === undefined)
+            await cleanupGrace(pending);
+    }
+    if ("turn" in outcome && outcome.continuing) {
+        session.usage.markPending();
+        return outcome.turn;
+    }
+    const failure = "error" in outcome ? outcome.error : undefined;
+    const requestSettlement = settlementRef.current;
+    const providerError = isCuaProviderError(failure)
+        ? failure
+        : requestSettlement &&
+            "error" in requestSettlement &&
+            isCuaProviderError(requestSettlement.error)
+            ? requestSettlement.error
+            : undefined;
+    const turn = requestSettlement && "turn" in requestSettlement ? requestSettlement.turn : undefined;
+    const receipt = settledReceipt(providerError?.receipt ?? turn?.providerRequest);
+    const rawUsage = providerError?.usage ?? (turn?.providerRequestPending === true ? undefined : turn?.usage);
+    const usage = rawUsage === undefined ? undefined : reportedCounts(rawUsage);
+    const settledKind = session.usage.settle(kind, receipt, usage, providerError);
+    if (receipt.cleanup !== "confirmed") {
+        session.trace.record("notice", () => notice("error", "participant request cleanup unconfirmed", "The request did not confirm cleanup within the settlement boundary. No further participant request or action is admitted."));
+    }
+    if (!("error" in outcome))
+        return outcome.turn;
+    if (usage)
+        session.usage.record({ actions: [], pendingSafetyChecks: [], done: false, usage, providerRequest: receipt }, settledKind);
+    if (failure instanceof CuaAbortError || failure instanceof CuaDeadlineError)
+        throw failure;
+    if (failure instanceof CuaStallError)
+        throw new CuaProviderError("timeout", receipt, usage, providerError?.failurePhase);
+    throw providerError ?? new CuaProviderError("process_failed", receipt, usage);
+}
+/**
+ * Whether a single-dispatch turn is a valid turn from a continuing request (see
+ * CuaTurn.providerRequestPending), which carries actions only. A settled turn must carry a
+ * dispatched, cleaned-up receipt.
+ */
+function isContinuingTurn(kind, turn) {
+    if (turn.providerRequestPending === true) {
+        if (kind !== "interaction" ||
+            turn.done ||
+            turn.actions.length === 0 ||
+            turn.pendingSafetyChecks.length > 0 ||
+            turn.providerRequest !== undefined ||
+            turn.usage !== undefined ||
+            turn.interruption !== undefined ||
+            turn.closingReport !== undefined) {
+            throw new CuaProviderError("invalid_response", {
+                dispatched: "unknown",
+                usageComplete: false,
+                cleanup: "unconfirmed",
+            });
+        }
+        return true;
+    }
+    const r = turn.providerRequest;
+    if (!r ||
+        r.dispatched !== true ||
+        typeof r.usageComplete !== "boolean" ||
+        r.cleanup !== "confirmed") {
+        throw new CuaProviderError("invalid_response", { dispatched: "unknown", usageComplete: false, cleanup: "unconfirmed" }, turn.usage);
+    }
+    return false;
+}
+async function cleanupGrace(pending) {
+    let timer;
+    try {
+        await Promise.race([
+            pending.catch(() => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, CUA_PROVIDER_CLEANUP_GRACE_MS);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

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

@@ -0,0 +1,34 @@
+/** The session clock ran out before the call settled. */
+export declare class CuaDeadlineError extends Error {
+}
+/** The caller's abort signal fired before the call settled. */
+export declare class CuaAbortError extends Error {
+}
+/** A single call outlived its own bound while the session still had budget: a stall, not a deadline. */
+export declare class CuaStallError extends Error {
+    readonly what: string;
+    readonly afterMs: number;
+    constructor(what: string, afterMs: number);
+}
+/**
+ * One port call's abort signal. It follows the session signal and is aborted when the loop stops
+ * waiting on the call, because a race alone does not cancel the losing promise.
+ */
+export interface RequestScope {
+    readonly signal: AbortSignal;
+    /** Abort the call and stop following the session signal. Safe to call twice. */
+    end(): void;
+}
+export declare function requestScope(signal: AbortSignal | undefined): RequestScope;
+/**
+ * raceSessionDeadline with a second, tighter clock: the call's own bound. When the tighter clock
+ * wins the result is a CuaStallError (the caller decides whether to retry); when the session clock wins it
+ * stays a CuaDeadlineError, which the loop reads as the session deadline (timed_out or
+ * budget_reached).
+ */
+export declare function raceCallBound<T>(what: string, promise: Promise<T>, remainingMs: number, boundMs: number, signal?: AbortSignal): Promise<T>;
+/**
+ * Wait on a port promise, but stop waiting if the wall-clock budget runs out or the caller
+ * aborts. An already-settled promise always wins, so a fast op is never spuriously failed.
+ */
+export declare function raceSessionDeadline<T>(promise: Promise<T>, remainingMs: number, signal?: AbortSignal): Promise<T>;

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

@@ -0,0 +1,79 @@
+// Deadline races for port calls. A promise cannot be force-cancelled, so these stop the loop
+// waiting on it when the session clock, the call's own bound or the caller's abort signal wins.
+// The underlying call may still settle later. Distinct error classes let the loop tell a deadline
+// or abort apart from a real adapter failure.
+/** The session clock ran out before the call settled. */
+export class CuaDeadlineError extends Error {
+}
+/** The caller's abort signal fired before the call settled. */
+export class CuaAbortError extends Error {
+}
+/** A single call outlived its own bound while the session still had budget: a stall, not a deadline. */
+export class CuaStallError extends Error {
+    what;
+    afterMs;
+    constructor(what, afterMs) {
+        super(`${what} produced nothing within ${afterMs}ms`);
+        this.what = what;
+        this.afterMs = afterMs;
+    }
+}
+export function requestScope(signal) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    if (signal?.aborted)
+        controller.abort();
+    else
+        signal?.addEventListener("abort", onAbort, { once: true });
+    return {
+        signal: controller.signal,
+        end: () => {
+            signal?.removeEventListener("abort", onAbort);
+            controller.abort();
+        },
+    };
+}
+/**
+ * raceSessionDeadline with a second, tighter clock: the call's own bound. When the tighter clock
+ * wins the result is a CuaStallError (the caller decides whether to retry); when the session clock wins it
+ * stays a CuaDeadlineError, which the loop reads as the session deadline (timed_out or
+ * budget_reached).
+ */
+export async function raceCallBound(what, promise, remainingMs, boundMs, signal) {
+    const cap = Math.min(remainingMs, boundMs);
+    const boundWins = boundMs < remainingMs;
+    try {
+        return await raceSessionDeadline(promise, cap, signal);
+    }
+    catch (error) {
+        if (error instanceof CuaDeadlineError && boundWins)
+            throw new CuaStallError(what, cap);
+        throw error;
+    }
+}
+/**
+ * Wait on a port promise, but stop waiting if the wall-clock budget runs out or the caller
+ * aborts. An already-settled promise always wins, so a fast op is never spuriously failed.
+ */
+export function raceSessionDeadline(promise, remainingMs, signal) {
+    if (signal?.aborted) {
+        return Promise.reject(new CuaAbortError());
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (apply) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            apply();
+        };
+        const onAbort = () => finish(() => reject(new CuaAbortError()));
+        const timer = setTimeout(() => finish(() => reject(new CuaDeadlineError())), Math.max(0, remainingMs));
+        if (typeof timer.unref === "function")
+            timer.unref();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}

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

@@ -0,0 +1,77 @@
+import type { ActorTraceItem, ParticipantDeclaredOutcome } from "../../contract.js";
+import type { AffordanceObservation } from "../../affordance.js";
+import { TaskTracker } from "../../../lab/tasks.js";
+import type { DebriefTrigger, Stop } from "./ending.js";
+import { TraceRecorder } from "./trace.js";
+import type { CuaExecutor, CuaLoopOptions, CuaProvider, CuaSafetyCheck } from "./types.js";
+import { UsageLedger } from "./usage.js";
+export type ScreenshotRef = NonNullable<ActorTraceItem["screenshotRef"]>;
+/**
+ * The options with no default, read once at entry and passed through. Defaulted options and
+ * wrapped callbacks are fields on LoopSession instead. Callers destructure hooks to call them.
+ */
+export type LoopSettings = {
+    readonly [K in "instructions" | "persona" | "redaction" | "stopWhen" | "dwell" | "tasks" | "maxUsd" | "overRunBudget" | "estimateTurnCostUsd" | "onObservedUrl" | "onMessage" | "onScreenshot" | "onTrace"]: CuaLoopOptions[K];
+};
+/** The participant's dispatched actions, as the backstop and failure notices describe them. */
+export interface ActionHistory {
+    lastActionTitle: string | undefined;
+    lastMaterialActionTitle: string | undefined;
+    readonly recentActionTitles: string[];
+    readonly affordances: AffordanceObservation[];
+    /** The loop stopped waiting on an action before the executor acknowledged it. */
+    interruptedActionOutcome: boolean;
+}
+/**
+ * One loop session's shared state: the options as read at entry, the clock and deadline, the trace
+ * recorder, the usage ledger, the participant's action history, and the stop being concluded.
+ */
+export declare class LoopSession {
+    readonly settings: LoopSettings;
+    readonly provider: CuaProvider;
+    readonly executor: CuaExecutor;
+    readonly signal: AbortSignal | undefined;
+    readonly timeoutMs: number;
+    readonly idleSteps: number;
+    readonly noProgressSteps: number;
+    readonly redactScreenshots: boolean;
+    readonly now: () => number;
+    readonly acknowledgeSafetyChecks: (checks: CuaSafetyCheck[]) => CuaSafetyCheck[] | null;
+    readonly writeScreenshot: (name: string, bytes: Buffer) => Promise<string>;
+    readonly sleep: (ms: number) => Promise<void>;
+    /** Strict capped routes stop when a request's usage is unavailable. */
+    readonly requiresUsage: boolean;
+    /**
+     * A dollar cap or study budget is declared. Its estimate is built from reported usage, so a
+     * request whose usage is unknown and unbounded stops the session before the next one.
+     */
+    readonly capDeclared: boolean;
+    readonly startedAtMs: number;
+    readonly turnTimeoutMs: number;
+    readonly observationTimeoutMs: number;
+    readonly trace: TraceRecorder;
+    readonly usage: UsageLedger;
+    readonly taskTracker: TaskTracker | undefined;
+    readonly actionHistory: ActionHistory;
+    /** What the loop was doing, for failure notices. */
+    phase: string;
+    lastScreenshotRef: ScreenshotRef | undefined;
+    lastResponseId: string | undefined;
+    observedAppState: boolean;
+    declaredOutcome: ParticipantDeclaredOutcome | undefined;
+    /** Set by a structured stop; the debrief follows it even if the session then failed. */
+    debriefTrigger: DebriefTrigger | undefined;
+    private stopCause;
+    private readonly scrubText;
+    constructor(options: CuaLoopOptions);
+    remaining(): number;
+    redactNarration(text: string): string;
+    /** Hand a watcher the trace so far with the running usage, without waiting on it. */
+    flush(): void;
+    /**
+     * Commit a stop where it is decided: its debrief trigger and stop cause first, then its trace
+     * evidence. A failure while recording the evidence ends the session as an error that keeps
+     * both. Returns the stop without evidence, so concluding it again records nothing.
+     */
+    conclude(stop: Stop): Stop;
+}

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

@@ -0,0 +1,135 @@
+import { TaskTracker } from "../../../lab/tasks.js";
+import { TraceRecorder } from "./trace.js";
+import { UsageLedger } from "./usage.js";
+// The state one loop session shares across its phases: the options as read at entry, the session
+// clock, the trace being recorded, the usage ledger, and what the participant has done so far.
+// Waiting is a legitimate strategy. A persona verifying a sign-up by email polls its inbox
+// (screenshot, wait, screenshot, wait), and a short idle limit ends that session as gave_up before
+// the mail can arrive.
+const DEFAULT_IDLE_STEPS = 24;
+// A no-progress turn also needs a repeated action (#383), so this needs less headroom than the
+// idle limit.
+const DEFAULT_NO_PROGRESS_STEPS = 20;
+const DEFAULT_TURN_TIMEOUT_MS = 180_000;
+const DEFAULT_OBSERVATION_TIMEOUT_MS = 60_000;
+/**
+ * One loop session's shared state: the options as read at entry, the clock and deadline, the trace
+ * recorder, the usage ledger, the participant's action history, and the stop being concluded.
+ */
+export class LoopSession {
+    settings;
+    provider;
+    executor;
+    signal;
+    timeoutMs;
+    idleSteps;
+    noProgressSteps;
+    redactScreenshots;
+    // Injected functions are wrapped so they are called without a receiver, as plain functions.
+    now;
+    acknowledgeSafetyChecks;
+    writeScreenshot;
+    sleep;
+    /** Strict capped routes stop when a request's usage is unavailable. */
+    requiresUsage;
+    /**
+     * A dollar cap or study budget is declared. Its estimate is built from reported usage, so a
+     * request whose usage is unknown and unbounded stops the session before the next one.
+     */
+    capDeclared;
+    startedAtMs;
+    turnTimeoutMs;
+    observationTimeoutMs;
+    trace;
+    usage;
+    // The funnel is recorded, never consulted: task completion does not steer the loop.
+    taskTracker;
+    actionHistory = {
+        lastActionTitle: undefined,
+        lastMaterialActionTitle: undefined,
+        recentActionTitles: [],
+        affordances: [],
+        interruptedActionOutcome: false,
+    };
+    /** What the loop was doing, for failure notices. */
+    phase = "initializing computer-use loop";
+    lastScreenshotRef;
+    lastResponseId;
+    // Whether any observation carried appState. trace.ts states it in redaction.notes; the appState
+    // itself is never persisted.
+    observedAppState = false;
+    declaredOutcome;
+    /** Set by a structured stop; the debrief follows it even if the session then failed. */
+    debriefTrigger;
+    stopCause;
+    scrubText;
+    constructor(options) {
+        // Read once, in this order: a caller mutating its options object mid-run changes nothing.
+        const { instructions, provider, executor, persona, redaction, timeoutMs, now, signal, idleSteps = DEFAULT_IDLE_STEPS, noProgressSteps = DEFAULT_NO_PROGRESS_STEPS, acknowledgeSafetyChecks = () => null, redactScreenshots = false, scrubText = (text) => text, writeScreenshot = async (name) => `screenshots/${name}`, stopWhen, dwell, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), tasks, maxUsd, overRunBudget, estimateTurnCostUsd, requireReportedUsageForSpendCap = false, onObservedUrl, onMessage, onScreenshot, onTrace, } = options;
+        this.settings = {
+            instructions,
+            persona,
+            redaction,
+            stopWhen,
+            dwell,
+            tasks,
+            maxUsd,
+            overRunBudget,
+            estimateTurnCostUsd,
+            onObservedUrl,
+            onMessage,
+            onScreenshot,
+            onTrace,
+        };
+        this.provider = provider;
+        this.executor = executor;
+        this.signal = signal;
+        this.timeoutMs = timeoutMs;
+        this.idleSteps = idleSteps;
+        this.noProgressSteps = noProgressSteps;
+        this.redactScreenshots = redactScreenshots;
+        this.now = () => now();
+        this.acknowledgeSafetyChecks = (checks) => acknowledgeSafetyChecks(checks);
+        this.scrubText = (text) => scrubText(text);
+        this.writeScreenshot = (name, bytes) => writeScreenshot(name, bytes);
+        this.sleep = (ms) => sleep(ms);
+        this.capDeclared = maxUsd !== undefined || overRunBudget !== undefined;
+        this.requiresUsage = requireReportedUsageForSpendCap && this.capDeclared;
+        this.startedAtMs = now();
+        this.turnTimeoutMs = options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
+        this.observationTimeoutMs = options.observationTimeoutMs ?? DEFAULT_OBSERVATION_TIMEOUT_MS;
+        this.trace = new TraceRecorder(this.now);
+        this.usage = new UsageLedger(provider);
+        this.taskTracker = tasks !== undefined && tasks.length > 0 ? new TaskTracker(tasks) : undefined;
+    }
+    remaining() {
+        return this.timeoutMs - (this.now() - this.startedAtMs);
+    }
+    // Model-authored narration: literal-scrub known provisioned values, THEN pattern-redact.
+    // A value the model transcribes (a DB password it read on screen) has no shape, so redactText
+    // alone cannot catch it — the lab's scrubKnownValues, injected as scrubText, closes that.
+    redactNarration(text) {
+        return this.settings.redaction.redactText(this.scrubText(text));
+    }
+    /** Hand a watcher the trace so far with the running usage, without waiting on it. */
+    flush() {
+        const { onTrace } = this.settings;
+        onTrace?.(this.trace.items.slice(), this.usage.running(), this.usage.liveMetadata());
+    }
+    /**
+     * Commit a stop where it is decided: its debrief trigger and stop cause first, then its trace
+     * evidence. A failure while recording the evidence ends the session as an error that keeps
+     * both. Returns the stop without evidence, so concluding it again records nothing.
+     */
+    conclude(stop) {
+        this.debriefTrigger = stop.debriefTrigger ?? this.debriefTrigger;
+        this.stopCause = stop.stopCause ?? this.stopCause;
+        if (stop.evidence !== undefined)
+            this.trace.record(stop.evidence.kind, stop.evidence.body);
+        return {
+            completionReason: stop.completionReason,
+            reason: stop.reason,
+            ...(this.stopCause === undefined ? {} : { stopCause: this.stopCause }),
+        };
+    }
+}

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

@@ -0,0 +1,30 @@
+import type { LostRequest, Stop } from "./ending.js";
+import type { LoopSession } from "./session.js";
+import type { CuaSpendGate } from "./types.js";
+/** Thrown through the provider when a lost attempt may not be sent again; carries the stop. */
+export declare class LostRequestRefused extends Error {
+    readonly stop: Stop;
+    constructor(stop: Stop);
+}
+/**
+ * The spend caps, checked before the next provider request so a model stuck retrying cannot keep
+ * spending. The lane cap stops the session once the running estimate crosses maxUsd; a null
+ * estimate cannot trip it, because preflight guaranteed a rate. The study budget (#299) is checked
+ * next.
+ */
+export declare function spendStop(session: LoopSession): Stop | undefined;
+/**
+ * Under a declared cap, send the next request only while every earlier request's usage is known
+ * or bounded by a booked worst case. A reply without usage stops the session here, after its own
+ * actions ran and before any further spend. A turn that ends the session is not affected.
+ */
+export declare function unknownSpendStop(session: LoopSession): Stop | undefined;
+/**
+ * Book a request lost without a reply at its worst case, and say whether it may be sent again.
+ * The worst case is the latest reported request's input at the model's highest input rate plus
+ * maxOutputTokens at its output rate; the reply to the resent request later replaces that input
+ * with its own. Returns the stop when maxOutputTokens is unset or the charge does not fit.
+ */
+export declare function bookLostRequest(session: LoopSession, turnNumber: number, lost: LostRequest): Stop | undefined;
+/** The gate a capped session hands the provider for its own transport retries. */
+export declare function spendGate(session: LoopSession, turnNumber: number): CuaSpendGate | undefined;

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

@@ -0,0 +1,85 @@
+import * as stops from "./ending.js";
+import { notice } from "./trace.js";
+// The spend guards. The lane cap (maxUsd) and the study budget (overRunBudget) are priced from
+// the usage each reply reports, plus a worst-case charge booked for each request lost without a
+// reply. A request whose cost is unknown and unbounded stops a capped session before the next one.
+/** Thrown through the provider when a lost attempt may not be sent again; carries the stop. */
+export class LostRequestRefused extends Error {
+    stop;
+    constructor(stop) {
+        super(stop.reason);
+        this.stop = stop;
+    }
+}
+/**
+ * The spend caps, checked before the next provider request so a model stuck retrying cannot keep
+ * spending. The lane cap stops the session once the running estimate crosses maxUsd; a null
+ * estimate cannot trip it, because preflight guaranteed a rate. The study budget (#299) is checked
+ * next.
+ */
+export function spendStop(session) {
+    const { maxUsd, overRunBudget, estimateTurnCostUsd } = session.settings;
+    if (maxUsd !== undefined && estimateTurnCostUsd) {
+        const running = estimateTurnCostUsd(session.usage.forCap());
+        if (running !== null && !Number.isFinite(running))
+            return stops.nonFiniteEstimate;
+        if (running !== null && running > maxUsd)
+            return stops.spendLimit(session, running, maxUsd);
+    }
+    if (overRunBudget) {
+        const runStop = overRunBudget(session.usage.forCap());
+        if (runStop !== null)
+            return stops.studySpendLimit(runStop);
+    }
+    return undefined;
+}
+/**
+ * Under a declared cap, send the next request only while every earlier request's usage is known
+ * or bounded by a booked worst case. A reply without usage stops the session here, after its own
+ * actions ran and before any further spend. A turn that ends the session is not affected.
+ */
+export function unknownSpendStop(session) {
+    if (!session.capDeclared || !session.usage.unavailableForCap())
+        return undefined;
+    session.usage.markUnreported();
+    return stops.usageUnreported;
+}
+/**
+ * Book a request lost without a reply at its worst case, and say whether it may be sent again.
+ * The worst case is the latest reported request's input at the model's highest input rate plus
+ * maxOutputTokens at its output rate; the reply to the resent request later replaces that input
+ * with its own. Returns the stop when maxOutputTokens is unset or the charge does not fit.
+ */
+export function bookLostRequest(session, turnNumber, lost) {
+    const maxOutputTokens = session.provider.modelSettings?.maxOutputTokens;
+    if (maxOutputTokens === undefined) {
+        session.usage.markUnreported();
+        return stops.lostRequestUnbounded(turnNumber, lost);
+    }
+    const input = session.usage.lastReportedInput();
+    session.usage.reserve(input, maxOutputTokens);
+    const usd = session.settings.estimateTurnCostUsd?.({
+        input,
+        output: maxOutputTokens,
+        cachedInput: 0,
+        cacheWriteInput: input,
+    });
+    const charge = `${input} input tokens at the highest input rate and ${maxOutputTokens} output tokens${typeof usd === "number" ? ` ($${usd})` : ""}`;
+    const over = spendStop(session);
+    session.trace.record("notice", () => notice("warn", "worst case booked for a lost request", over === undefined
+        ? `provider turn ${turnNumber} ${lost}; its usage is unknown, so the spend cap counts ${charge}; sending the request again`
+        : `provider turn ${turnNumber} ${lost}; its usage is unknown, so the spend cap counts ${charge}, which does not fit; the request was not sent again`));
+    return over;
+}
+/** The gate a capped session hands the provider for its own transport retries. */
+export function spendGate(session, turnNumber) {
+    if (!session.capDeclared)
+        return undefined;
+    return {
+        beforeResend: () => {
+            const refused = bookLostRequest(session, turnNumber, "failed in transit");
+            if (refused !== undefined)
+                throw new LostRequestRefused(refused);
+        },
+    };
+}