humanish 0.107.0 → 0.109.0

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

@@ -1,8 +1,8 @@
 import type { HeardSpeech } from "../speech.js";
-import type { ActorCapabilities, ActorExecutionProfile, ActorPersonaRef, ActorSessionResult, ActorTokenUsage, ActorTrace, ActorTraceItem, ParticipantClosingReport, ParticipantDeclaredOutcome, ProviderRequestReceipt } from "../../contract.js";
+import type { ActorCapabilities, ActorConversation, ActorExecutionProfile, ActorPersonaRef, ActorSessionResult, ActorTokenUsage, ActorTrace, ActorTraceItem, ParticipantClosingReport, ParticipantDeclaredOutcome, ProviderRequestReceipt } from "../../contract.js";
 import type { RedactionHooks } from "../../../evidence/redaction.js";
 import type { DwellWindow, StopWhen } from "../../stop-conditions.js";
-import type { LabTask } from "../../../lab/tasks.js";
+import type { StudyTask } from "../../../study/tasks.js";
 import type { ReasoningEffort } from "../../reasoning-effort.js";
 /**
  * One desktop action. `heldKeys` on a pointer action are held down for the whole action and
@@ -80,7 +80,7 @@ export interface CuaObservation {
      * in-memory progress key is derived from it. A structured blob has no detectable secret shape
      * (the published-evidence scan catches only secret-shaped patterns), so it is handled like
      * stateSignature, which is never written as text either. Persisting it would need a stringified
-     * projection through redaction.redactText and the lab's scrubText, with its fields capped or
+     * projection through redaction.redactText and the run's scrubText, with its fields capped or
      * allowlisted, since pattern and literal redaction cannot sanitize an arbitrary blob.
      */
     appState?: Record<string, unknown>;
@@ -93,7 +93,7 @@ export interface CuaObservation {
     url?: string;
     /**
      * The page's vertical scroll offset (window.scrollY), when the executor can read it. Scroll
-     * position is state (#393): inside a scroll-pinned section the viewport stays visually fixed
+     * position is state: inside a scroll-pinned section the viewport stays visually fixed
      * while the participant advances, so the frame hash alone reads "no change". Runtime-only like
      * url and text: it feeds the progress key, bucketed, and is never persisted.
      */
@@ -182,7 +182,7 @@ export interface CuaTurn {
     done: boolean;
     /** Explicit provider interruption, independent of actions or participant intent. */
     interruption?: "output_limit" | "token_limit" | "incomplete" | "unexpected_status";
-    /** The participant's own word for how it ended, when its reply format carries one (#570). */
+    /** The participant's own word for how it ended, when its reply format carries one. */
     outcome?: ParticipantDeclaredOutcome;
     /** Present only for an accepted structured closing account. */
     closingReport?: ParticipantClosingReport;
@@ -193,11 +193,13 @@ export interface CuaProvider {
     readonly requestPolicy?: "fail_closed";
     readonly executionProfile?: ActorExecutionProfile | undefined;
     readonly historyTurnsOmitted?: number;
+    /** How the conversation was carried between requests, for the trace. */
+    readonly conversation?: ActorConversation;
     readonly id: string;
     readonly version?: string | undefined;
     /**
      * The request settings this provider will actually send, for the trace to record. `version` says
-     * WHICH model; this says how it was asked to run. Optional: a provider with no such settings
+     * which model; this says how it was asked to run. Optional: a provider with no such settings
      * records none, and absence stays absence rather than becoming a default nobody chose.
      */
     readonly modelSettings?: {
@@ -259,13 +261,13 @@ export interface CuaLoopOptions {
     /** Hard wall-clock runaway guard. The only count-free hard stop. */
     timeoutMs: number;
     /**
-     * Per-attempt bound on the provider call (#469), so a hung request is told apart from a
+     * Per-attempt bound on the provider call, so a hung request is told apart from a
      * participant still thinking. A stalled turn is retried once with a notice; a second stall ends
      * the participant as harness_error.
      */
     turnTimeoutMs?: number;
     /**
-     * Per-call bound on observation work (#480): executor.observe() and the idle actions (`wait`,
+     * Per-call bound on observation work: executor.observe() and the idle actions (`wait`,
      * `screenshot`), whose only job is to look. A `wait` adds its own ms to the bound. A stalled
      * observe is retried once; a stalled idle action is skipped with a notice.
      */
@@ -288,19 +290,19 @@ export interface CuaLoopOptions {
      */
     acknowledgeSafetyChecks?: (checks: CuaSafetyCheck[]) => CuaSafetyCheck[] | null;
     /**
-     * Redact (blur+downscale) persisted screenshots. Default FALSE — full-fidelity frames are
-     * retained, because the common case is a developer watching a sim of their OWN app locally
+     * Redact (blur+downscale) persisted screenshots. Default `false`: full-fidelity frames are
+     * retained, because the common case is a developer watching a sim of their own app locally
      * (gitignored .humanish), where blur destroys the core deliverable. Set true for unowned
-     * subjects or when the bundle is meant to be shared as-is. The frame sent to the PROVIDER is
+     * subjects or when the bundle is meant to be shared as-is. The frame sent to the provider is
      * always full-resolution regardless (the model must see the screen to act); this flag only
-     * governs what is PERSISTED. Publish-safety belongs at the publish boundary (commit scan / redactScreenshots), not capture.
+     * governs what is persisted. Publish-safety belongs at the publish boundary (commit scan / redactScreenshots), not capture.
      */
     redactScreenshots?: boolean;
     /**
-     * Extra literal scrub for KNOWN provisioned values (which have no detectable "shape", so
-     * pattern redaction cannot catch them), composed BEFORE redactText on every model-authored
-     * text item (reasoning, message, completion summary) and the loop error. The lab passes the
-     * env-value scrubber here so a value the MODEL narrates can never land raw in the trace.
+     * Extra literal scrub for known provisioned values (which have no detectable "shape", so
+     * pattern redaction cannot catch them), composed before redactText on every model-authored
+     * text item (reasoning, message, completion summary) and the loop error. The route passes the
+     * env-value scrubber here so a value the model narrates can never land raw in the trace.
      * Default: identity (the loop is shape-only on its own).
      */
     scrubText?: (text: string) => string;
@@ -313,7 +315,7 @@ export interface CuaLoopOptions {
      */
     stopWhen?: StopWhen;
     /**
-     * A declared observation window (#510): once its condition matches (or after the first
+     * A declared observation window: once its condition matches (or after the first
      * observation when it has none) the loop holds the page for the window, captures a frame on the
      * cadence, takes no action and requests no model turn, then hands control back or ends. Runs at
      * most once per session and never past the session budget.
@@ -322,34 +324,34 @@ export interface CuaLoopOptions {
     /** Injected pause for the dwell window's cadence; tests advance their clock through it. */
     sleep?: (ms: number) => Promise<void>;
     /**
-     * The lab's declared protocol (#414): discrete tasks whose completion is corroborated by the
+     * The study's declared protocol: discrete tasks whose completion is corroborated by the
      * same observations stopWhen reads, on the same cadence. The tracker never influences the loop's
-     * control flow — a completed task list does not stop a session (that is stopWhen's job); it only
+     * control flow: a completed task list does not stop a session (that is stopWhen's job); it only
      * records the funnel that lands on the trace. The participant-facing halves of these tasks are
-     * already IN `instructions` (composed upstream); the loop reads only the `success` criteria,
+     * already in `instructions` (composed upstream); the loop reads only the `success` criteria,
      * which never reach the prompt.
      */
-    tasks?: readonly LabTask[];
+    tasks?: readonly StudyTask[];
     /**
      * Spend cap in USD. When set, the loop stops with budget_reached as soon as the running
      * estimated spend crosses it, before the next provider turn. Absent means uncapped. maxUsd: 0
      * can still permit one model request before its reported spend trips the check. Enforcement
-     * needs an estimate, so the lab refuses a cap on an unpriced model at preflight.
+     * needs an estimate, so humanish refuses a cap on an unpriced model at preflight.
      */
     maxUsd?: number;
     /**
-     * Injected PURE per-turn cost estimator (keeps the loop free of the operator rate table and
+     * Injected pure per-turn cost estimator (keeps the loop free of the operator rate table and
      * makes the cap deterministic in tests). Given running (input, output) token totals, returns the
      * estimated USD, or null when unpriceable. Only consulted when `maxUsd` is set. A null estimate
-     * mid-run cannot trip the cap — preflight already guaranteed a rate exists, so a null here is a
+     * mid-run cannot trip the cap; preflight already guaranteed a rate exists, so a null here is a
      * vanished-rate harness condition, not a silent uncapped pass.
      */
     estimateTurnCostUsd?: (usage: ActorTokenUsage) => number | null;
     /**
-     * RUN-LEVEL spend guard (#299): called with this participant's running usage each turn, at the same
-     * point the per-participant cap is checked. Returns a human-readable reason when the STUDY's shared
+     * Run-level spend guard: called with this participant's running usage each turn, at the same
+     * point the per-participant cap is checked. Returns a human-readable reason when the study's shared
      * budget is exhausted, else null. On a non-null return the loop stops with `budget_reached`
-     * regardless of material progress — a study-level stop is a recruiting decision hitting its
+     * regardless of material progress: a study-level stop is a recruiting decision hitting its
      * limit, not this participant's runaway, so it never reads as `gave_up`.
      */
     overRunBudget?: (usage: ActorTokenUsage) => string | null;
@@ -361,6 +363,22 @@ export interface CuaLoopOptions {
      * built-in route sets it.
      */
     requireReportedUsageForSpendCap?: boolean;
+    /**
+     * Trace snapshot for a watcher: the redacted items recorded so far, with the running
+     * usage so a run can be priced in flight. Called after each checkpoint's screenshot (the initial
+     * observation and every acted turn, so a flush never shows an action without the frame before
+     * it), after each dwell frame, and after a closing request. The array is a fresh copy; its items
+     * are the objects the final trace persists. Not awaited, so a slow flush cannot stall a turn.
+     * Default: no-op.
+     */
+    onTrace?: (items: readonly ActorTraceItem[], usage: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
+}
+/**
+ * The runtime-only taps the external-public shared-world handoff (src/routes/shared-world/handoff.ts)
+ * reads the lobby code through. Internal: 0.109.0 removed them from CuaLoopOptions, and a library
+ * caller wraps the executor's `observe` or the provider's `nextTurn` instead.
+ */
+export interface LoopTaps {
     /**
      * Runtime-only URL tap: called with `observation.url` for each observation a turn may receive
      * (the initial one, each post-action one and the one after a dwell window). The loop never
@@ -368,9 +386,6 @@ export interface CuaLoopOptions {
      *
      * Built-in caller: the external-public shared-world handoff (src/routes/shared-world/handoff.ts)
      * latches the host participant's lobby URL and checks that each follower reached the same lobby.
-     *
-     * @deprecated Wrap the executor's `observe` and read `url` from each observation it returns. The
-     * next minor removes this option.
      */
     onObservedUrl?: (url: string | undefined) => void;
     /**
@@ -381,9 +396,6 @@ export interface CuaLoopOptions {
      *
      * Built-in caller: the external-public handoff scans the host's narration for the lobby code,
      * because the E2B desktop's CDP URL read behind onObservedUrl is unreliable.
-     *
-     * @deprecated Wrap the provider's `nextTurn` and read `reasoning` and `message` from each turn it
-     * returns. The next minor removes this option.
      */
     onMessage?: (text: string) => void;
     /**
@@ -393,21 +405,11 @@ export interface CuaLoopOptions {
      *
      * Built-in caller: the external-public handoff reads the lobby code off each participant's own
      * frame until that participant has one: the host's latch, or a follower's convergence observation.
-     *
-     * @deprecated Wrap the executor's `observe` and read `screenshot` from each observation it
-     * returns. The next minor removes this option.
      */
     onScreenshot?: (frame: Buffer) => void;
-    /**
-     * Trace snapshot for a watcher (#441): the redacted items recorded so far, with the running
-     * usage so a run can be priced in flight. Called after each checkpoint's screenshot (the initial
-     * observation and every acted turn, so a flush never shows an action without the frame before
-     * it), after each dwell frame, and after a closing request. The array is a fresh copy; its items
-     * are the objects the final trace persists. Not awaited, so a slow flush cannot stall a turn.
-     * Default: no-op.
-     */
-    onTrace?: (items: readonly ActorTraceItem[], usage: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
 }
+/** The loop's options inside humanish: the public ones plus the handoff's taps. */
+export type LoopRunOptions = CuaLoopOptions & LoopTaps;
 export type CuaLiveMetadata = Pick<ActorTrace, "executionProfile" | "providerRequests" | "historyTurnsOmitted">;
 /** What runComputerUseLoop returns; the public name for an actor session result. */
 export type CuaLoopResult = ActorSessionResult;

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

@@ -1,5 +1,5 @@
 import type { ActorProviderRequest, ActorTokenUsage, ProviderRequestReceipt } from "../../contract.js";
-import type { CuaProviderError } from "../provider-error.js";
+import type { ComputerUseProviderError } from "../provider-error.js";
 import type { CuaLiveMetadata, CuaProvider, CuaTurn } from "./types.js";
 type TurnUsage = NonNullable<CuaTurn["usage"]>;
 /** Turn usage with valid input and output counts, cache counts within input, and turns that add up. */
@@ -67,7 +67,7 @@ export declare class UsageLedger {
      * Book one settled single-dispatch request. A request that settles while a continuing request
      * is open belongs to that interaction, whatever kind the caller asked for.
      */
-    settle(kind: "interaction" | "debrief", receipt: ProviderRequestReceipt, usage: ActorTokenUsage | undefined, error: CuaProviderError | undefined): "interaction" | "debrief";
+    settle(kind: "interaction" | "debrief", receipt: ProviderRequestReceipt, usage: ActorTokenUsage | undefined, error: ComputerUseProviderError | undefined): "interaction" | "debrief";
     /**
      * The running usage both spend guards price: totals plus the per-inference ledger, shaped like
      * the trace's final tokenUsage so one estimator prices both. Unlike the persisted trace, where an

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

@@ -80,7 +80,7 @@ export class UsageLedger {
     cachedInput = 0;
     cacheWriteInput = 0;
     output = 0;
-    // Per model-inference usage, in order (#334): the recorded fact long-context pricing tiers
+    // Per model-inference usage, in order: the recorded fact long-context pricing tiers
     // need. A continuing native tool interaction may contain several inference requests.
     turns = [];
     /** An interaction turn arrived without complete usage, or its receipt said usage is incomplete. */
@@ -245,7 +245,7 @@ export class UsageLedger {
             input: this.input,
             output: this.output,
             // Recorded only when the provider actually reported it, so a reader can tell "no cache
-            // hits" from "this provider does not say" (#391); same for cache writes (#334).
+            // hits" from "this provider does not say"; same for cache writes.
             ...(this.cachedInput > 0 ? { cachedInput: this.cachedInput } : {}),
             ...(this.cacheWriteInput > 0 ? { cacheWriteInput: this.cacheWriteInput } : {}),
             ...(this.turns.length > 0 ? { turns: this.turns.map((turn) => ({ ...turn })) } : {}),

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

@@ -1,4 +1,4 @@
-import type { CuaLoopOptions, CuaLoopResult } from "./loop/types.js";
+import type { CuaLoopOptions, CuaLoopResult, LoopRunOptions } from "./loop/types.js";
 export type { CuaAction, CuaExecutor, CuaLiveMetadata, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaSpendGate, CuaTurn, CuaTurnRequest, } from "./loop/types.js";
 export { describeCuaAction } from "./loop/actions.js";
 export { stableProgressKey } from "./loop/backstop.js";
@@ -9,3 +9,8 @@ export { validClosingReport } from "./loop/debrief.js";
  * it is recorded; screenshots are persisted raw unless redactScreenshots is set.
  */
 export declare function runComputerUseLoop(options: CuaLoopOptions): Promise<CuaLoopResult>;
+/**
+ * runComputerUseLoop with the external-public handoff's taps (LoopTaps), which the public
+ * options no longer carry. The actor's entry.
+ */
+export declare function runComputerUseLoopWithTaps(options: LoopRunOptions): Promise<CuaLoopResult>;

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

@@ -1,4 +1,4 @@
-import { CuaProviderError } from "./provider-error.js";
+import { ComputerUseProviderError } from "./provider-error.js";
 import { runActionBatch } from "./loop/actions.js";
 import { advanceBackstop, startBackstop } from "./loop/backstop.js";
 import { requestDebrief } from "./loop/debrief.js";
@@ -20,6 +20,28 @@ export { validClosingReport } from "./loop/debrief.js";
  * it is recorded; screenshots are persisted raw unless redactScreenshots is set.
  */
 export async function runComputerUseLoop(options) {
+    refuseRemovedOptions(options);
+    return runComputerUseLoopWithTaps(options);
+}
+/** What 0.109.0 removed from CuaLoopOptions, and what a caller does instead. */
+const REMOVED_OPTIONS = {
+    onObservedUrl: "Wrap the executor's `observe` and read `url` from each observation it returns.",
+    onMessage: "Wrap the provider's `nextTurn` and read `reasoning` and `message` from each turn it returns.",
+    onScreenshot: "Wrap the executor's `observe` and read `screenshot` from each observation it returns.",
+};
+/** A JavaScript caller still passing a removed option gets an error, not a hook that never fires. */
+function refuseRemovedOptions(options) {
+    for (const [name, replacement] of Object.entries(REMOVED_OPTIONS)) {
+        if (options[name] !== undefined) {
+            throw new TypeError(`runComputerUseLoop: ${name} was removed in 0.109.0. ${replacement}`);
+        }
+    }
+}
+/**
+ * runComputerUseLoop with the external-public handoff's taps (LoopTaps), which the public
+ * options no longer carry. The actor's entry.
+ */
+export async function runComputerUseLoopWithTaps(options) {
     refuseAccountBilledCaps(options);
     const session = new LoopSession(options);
     const conversation = {
@@ -132,7 +154,7 @@ function applyBackstop(session, conversation, step, turnHints) {
 }
 function refuseAccountBilledCaps(options) {
     if (accountBillingConflicts(options.provider, options)) {
-        throw new CuaProviderError("request_rejected", {
+        throw new ComputerUseProviderError("request_rejected", {
             dispatched: false,
             usageComplete: false,
             cleanup: "confirmed",
@@ -201,7 +223,7 @@ function stopBeforeActing(session, turn, turnNumber) {
     }
     return undefined;
 }
-/** Hand the turn's narration to the onMessage hook; see CuaLoopOptions.onMessage. */
+/** Hand the turn's narration to the onMessage tap; see LoopTaps.onMessage. */
 function forwardNarration(session, turn) {
     const { onMessage } = session.settings;
     const narration = [turn.reasoning, turn.message]
@@ -241,7 +263,7 @@ function reviewSafetyChecks(session, conversation, turn) {
     const { acknowledgeSafetyChecks } = session;
     const acks = acknowledgeSafetyChecks(turn.pendingSafetyChecks);
     if (acks === null || acks.length === 0) {
-        return stops.blockedOnSafetyChecks(session.settings.redaction.redactText(turn.pendingSafetyChecks.map((check) => check.code).join(", ")));
+        return stops.blockedOnSafetyChecks(session.settings.redaction.redactText(turn.pendingSafetyChecks.map((check) => check.code).join(", ")), turn.pendingSafetyChecks.length);
     }
     conversation.acknowledgedSafetyChecks = acks;
     return undefined;

package/dist/actors/computer-use/openai-context.d.ts

@@ -0,0 +1,37 @@
+/** The estimated input a carried conversation may reach before its oldest turns are summarized. */
+export declare const CONTEXT_TOKEN_BUDGET = 64000;
+/** What the next request would carry, for the trace. */
+export interface CarriedContextSize {
+    readonly exchanges: number;
+    readonly screenshots: number;
+    readonly notedTurns: number;
+    readonly estimatedTokens: number;
+}
+export declare class CarriedConversation {
+    private readonly budget;
+    private opening;
+    private readonly exchanges;
+    /** The latest accepted reply's output items, which the next request answers. */
+    private pending;
+    private readonly notes;
+    private notesDropped;
+    private collapsedTurns;
+    constructor(budget?: number);
+    /**
+     * Record an accepted reply. `sent` is what that request added after the carried items: the
+     * opening message on the first request, then the call outputs and any hint.
+     */
+    accept(turn: number, sent: readonly unknown[], output: readonly unknown[]): void;
+    /** The items to send ahead of a request's own new items. */
+    carried(): unknown[];
+    /** The carried context's size, for the trace. */
+    size(): CarriedContextSize;
+    private trim;
+    private noteItem;
+}
+/**
+ * A rough input-token estimate: images by their size in 32-pixel patches, everything else at four
+ * characters a token. It decides when to trim, not what is billed; the trace records the billed
+ * input per request beside it.
+ */
+export declare function estimateTokens(items: readonly unknown[]): number;

package/dist/actors/computer-use/openai-context.js

@@ -0,0 +1,214 @@
+import { asArray, asRecord, inputMessage, openAiActionToCua } from "./openai-wire.js";
+// The conversation an explicit-context request carries, kept on the client because the server
+// keeps none (a zero-data-retention org, or zeroDataRetention set). Requests made while the
+// provider still threads on previous_response_id feed it too, so a switch partway through a
+// session keeps everything before the switch.
+//
+// The Responses API pairs items: every computer_call needs its computer_call_output, and a
+// reasoning item travels with the item it preceded. The conversation is therefore cut only at
+// exchange boundaries: one reply's output items together with the items that answered them.
+// When the estimate passes the budget, the opening screenshot goes first, then the oldest
+// exchanges become lines of a progress note that keeps their reasoning summaries, messages and
+// actions as text. The note is an assistant message, so text the model wrote (which can quote a
+// web page) keeps the trust it had when the model wrote it. The newest MIN_KEPT_EXCHANGES
+// exchanges are never collapsed, so a request passes the budget when they alone exceed it; the
+// trace's per-request estimate shows when that happens.
+/** The estimated input a carried conversation may reach before its oldest turns are summarized. */
+export const CONTEXT_TOKEN_BUDGET = 64_000;
+/** Exchanges always carried whole, so the model sees its latest actions with their screens. */
+const MIN_KEPT_EXCHANGES = 2;
+/** The progress note's length cap; past it, the oldest lines are counted instead of shown. */
+const NOTE_CHAR_LIMIT = 16_000;
+/** One note line's cap, so a reply with many actions cannot push the note past its own cap. */
+const LINE_CHAR_LIMIT = 1_200;
+/**
+ * Image input tokens per 32-pixel patch. The gpt-5.x and gpt-6 models bill 1.2 per patch, and at
+ * the default (auto) detail gpt-5.6 and gpt-6 keep the screenshot's own size. Models that resize
+ * to a lower patch budget bill less, so the estimate errs high for them.
+ */
+const TOKENS_PER_PATCH = 1.2;
+/** A screenshot whose size cannot be read is estimated as a 2,500-patch image. */
+const UNKNOWN_IMAGE_TOKENS = 3_000;
+export class CarriedConversation {
+    budget;
+    opening;
+    exchanges = [];
+    /** The latest accepted reply's output items, which the next request answers. */
+    pending;
+    notes = [];
+    notesDropped = 0;
+    collapsedTurns = 0;
+    constructor(budget = CONTEXT_TOKEN_BUDGET) {
+        this.budget = budget;
+    }
+    /**
+     * Record an accepted reply. `sent` is what that request added after the carried items: the
+     * opening message on the first request, then the call outputs and any hint.
+     */
+    accept(turn, sent, output) {
+        if (this.pending === undefined) {
+            this.opening = asRecord(sent[0]);
+        }
+        else {
+            this.exchanges.push({ turn: this.pending.turn, output: this.pending.output, answers: sent });
+        }
+        this.pending = { turn, output };
+        this.trim();
+    }
+    /** The items to send ahead of a request's own new items. */
+    carried() {
+        const note = this.noteItem();
+        return [
+            ...(this.opening === undefined ? [] : [this.opening]),
+            ...(note === undefined ? [] : [note]),
+            ...this.exchanges.flatMap((exchange) => [...exchange.output, ...exchange.answers]),
+            ...(this.pending?.output ?? []),
+        ];
+    }
+    /** The carried context's size, for the trace. */
+    size() {
+        const items = this.carried();
+        return {
+            exchanges: this.exchanges.length + (this.pending === undefined ? 0 : 1),
+            screenshots: items.reduce((count, item) => count + imagesOf(item).length, 0),
+            notedTurns: this.collapsedTurns,
+            estimatedTokens: estimateTokens(items),
+        };
+    }
+    trim() {
+        while (estimateTokens(this.carried()) > this.budget) {
+            if (this.opening !== undefined && imagesOf(this.opening).length > 0) {
+                this.opening = withoutImages(this.opening);
+                continue;
+            }
+            if (this.exchanges.length <= MIN_KEPT_EXCHANGES)
+                return;
+            const oldest = this.exchanges.shift();
+            this.notes.push(describeExchange(oldest));
+            this.collapsedTurns += 1;
+            while (this.notes.join("\n").length > NOTE_CHAR_LIMIT && this.notes.length > 1) {
+                this.notes.shift();
+                this.notesDropped += 1;
+            }
+        }
+    }
+    noteItem() {
+        if (this.notes.length === 0)
+            return undefined;
+        const lead = `My notes on my earlier turns in this session, oldest first. Their screenshots are no ` +
+            `longer shown; this is what I thought, said and did.` +
+            (this.notesDropped === 0 ? "" : ` (${this.notesDropped} earlier turns are not listed.)`);
+        return inputMessage("assistant", [
+            { type: "output_text", text: `${lead}\n${this.notes.join("\n")}` },
+        ]);
+    }
+}
+/** One exchange as a progress-note line: its reasoning summary, message and actions. */
+function describeExchange(exchange) {
+    const thought = [];
+    const said = [];
+    const did = [];
+    for (const raw of exchange.output) {
+        const item = asRecord(raw);
+        if (item.type === "reasoning")
+            for (const entry of asArray(item.summary)) {
+                const text = asRecord(entry).text;
+                if (typeof text === "string" && text.length > 0)
+                    thought.push(text);
+            }
+        if (item.type === "message")
+            for (const entry of asArray(item.content)) {
+                const text = asRecord(entry).text;
+                if (typeof text === "string" && text.length > 0)
+                    said.push(text);
+            }
+        if (item.type === "computer_call") {
+            const actions = Array.isArray(item.actions) ? item.actions : [item.action];
+            for (const action of actions) {
+                const mapped = openAiActionToCua(action);
+                if (mapped !== null)
+                    did.push(describeAction(mapped));
+            }
+        }
+    }
+    const parts = [
+        thought.length > 0 ? `thought: ${clip(thought.join(" "), 400)}` : undefined,
+        said.length > 0 ? `said: ${clip(said.join(" "), 300)}` : undefined,
+        did.length > 0 ? `did: ${did.join(", ")}` : undefined,
+    ].filter((part) => part !== undefined);
+    const line = `Turn ${exchange.turn}: ${parts.length > 0 ? parts.join("; ") : "no recorded output"}`;
+    return `${clip(line, LINE_CHAR_LIMIT - 1)}.`;
+}
+function describeAction(action) {
+    switch (action.kind) {
+        case "click":
+        case "double_click":
+        case "move":
+            return `${action.kind} (${action.x}, ${action.y})`;
+        case "scroll":
+            return `scroll at (${action.x}, ${action.y}) by (${action.dx}, ${action.dy})`;
+        case "type":
+            return `type ${JSON.stringify(clip(action.text, 120))}`;
+        case "keypress":
+            return `keypress ${action.keys.join("+")}`;
+        default:
+            return action.kind;
+    }
+}
+function clip(text, limit) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= limit ? flat : `${flat.slice(0, limit - 3)}...`;
+}
+/** The data URLs of the images an input item carries. */
+function imagesOf(item) {
+    const record = asRecord(item);
+    const output = asRecord(record.output);
+    const urls = [];
+    if (typeof output.image_url === "string")
+        urls.push(output.image_url);
+    for (const part of asArray(record.content)) {
+        const url = asRecord(part).image_url;
+        if (typeof url === "string")
+            urls.push(url);
+    }
+    return urls;
+}
+function withoutImages(item) {
+    return {
+        ...item,
+        content: asArray(item.content).filter((part) => asRecord(part).type !== "input_image"),
+    };
+}
+/**
+ * A rough input-token estimate: images by their size in 32-pixel patches, everything else at four
+ * characters a token. It decides when to trim, not what is billed; the trace records the billed
+ * input per request beside it.
+ */
+export function estimateTokens(items) {
+    let tokens = 0;
+    for (const item of items) {
+        const images = imagesOf(item);
+        for (const url of images)
+            tokens += imageTokens(url);
+        const text = JSON.stringify(item, (key, value) => (key === "image_url" ? "" : value));
+        tokens += Math.ceil(text.length / 4);
+    }
+    return tokens;
+}
+function imageTokens(dataUrl) {
+    const size = pngSize(dataUrl);
+    if (size === undefined)
+        return UNKNOWN_IMAGE_TOKENS;
+    const patches = Math.ceil(size.width / 32) * Math.ceil(size.height / 32);
+    return Math.ceil(patches * TOKENS_PER_PATCH);
+}
+/** A PNG's width and height, from the IHDR chunk at the start of its data URL. */
+function pngSize(dataUrl) {
+    const prefix = "data:image/png;base64,";
+    if (!dataUrl.startsWith(prefix))
+        return undefined;
+    const head = Buffer.from(dataUrl.slice(prefix.length, prefix.length + 32), "base64");
+    if (head.length < 24 || head.toString("ascii", 12, 16) !== "IHDR")
+        return undefined;
+    return { width: head.readUInt32BE(16), height: head.readUInt32BE(20) };
+}

package/dist/actors/computer-use/openai-provider.d.ts

@@ -5,15 +5,15 @@ import type { ReasoningEffort } from "../reasoning-effort.js";
 export declare const OPENAI_RESPONSES_CU_CAPABILITIES: ActorCapabilities;
 export declare const DEFAULT_OPENAI_CU_MODEL = "gpt-5.6-sol";
 /**
- * The effort a request carries when a lab declares none. Exported because a default that only
- * exists as a literal inside the provider is exactly how it stayed invisible: the lab surface has
- * to be able to say what will actually run (#497).
+ * The effort a request carries when a study declares none. Exported because a default that only
+ * exists as a literal inside the provider is exactly how it stayed invisible: the study surface has
+ * to be able to say what will actually run.
  */
 export declare const DEFAULT_OPENAI_CU_REASONING_EFFORT: ReasoningEffort;
 /** The opt-in gate for response wire capture: a directory path, or unset for off. */
 export declare const WIRE_CAPTURE_ENV = "HUMANISH_CUA_WIRE_CAPTURE_DIR";
 /**
- * Deep-copy a captured wire value with every string — object keys included —
+ * Deep-copy a captured wire value with every string (object keys included)
  * passed through the shared redactText, so a secret-shaped echo in a response
  * can never persist to disk. Pure; non-string primitives pass through unchanged.
  */
@@ -61,7 +61,7 @@ export interface OpenAiResponsesProviderOptions {
     model?: string;
     /**
      * How hard the model is asked to think per turn. Absent = the provider default below.
-     * The vocabulary is the documented union across models; SUPPORT IS MODEL-DEPENDENT, so an
+     * The vocabulary is the documented union across models; support is model-dependent, so an
      * unsupported level surfaces as the provider's own first-turn error rather than a silent
      * downgrade to something the trace would then misreport. See src/actors/reasoning-effort.ts.
      */
@@ -69,11 +69,11 @@ export interface OpenAiResponsesProviderOptions {
     /** Optional positive integer output limit per response, including reasoning. Not a spend cap. */
     maxOutputTokens?: number;
     /**
-     * Reasoning-summary capture (#427). Defaults to "auto" (the provider picks the best
+     * Reasoning-summary capture. Defaults to "auto" (the provider picks the best
      * summarizer the model supports); "off" never asks. If the account/model rejects the
      * request (e.g. an org not verified for reasoning summaries), the provider latches
-     * summaries off for the session and retries the same turn — the run degrades to
-     * exactly the pre-#427 behavior instead of failing after spend. Absence stays honest:
+     * summaries off for the session and retries the same turn; the run degrades to
+     * a run without summaries instead of failing after spend. The trace records the absence:
      * no summary means no `reasoning` trace items and `counts.reasonings` stays 0.
      */
     reasoningSummary?: OpenAiReasoningSummary | "off";
@@ -86,9 +86,12 @@ export interface OpenAiResponsesProviderOptions {
      * paid request. */
     singleDispatch?: boolean;
     delayFn?: (ms: number) => Promise<void>;
+    /** Carry the conversation on the client from the first request (explicit_context). */
     zeroDataRetention?: boolean;
+    /** The clock the trace's conversation record reads. Defaults to Date.now. */
+    now?: () => number;
     /**
-     * Environment for the wire-capture gate (HUMANISH_CUA_WIRE_CAPTURE_DIR — see the
+     * Environment for the wire-capture gate (HUMANISH_CUA_WIRE_CAPTURE_DIR; see the
      * module header). Injectable so deterministic tests control the gate without
      * mutating process.env. Defaults to process.env.
      */
@@ -100,7 +103,7 @@ export interface OpenAiResponsesProviderOptions {
  * call outputs (with the latest screenshot) and thread state via
  * previous_response_id, transparently falling back to explicit-context mode if
  * the account rejects server-side retention. Transient HTTP failures are retried
- * with exponential backoff. Returns ONLY a CuaTurn from nextTurn; nothing
+ * with exponential backoff. Returns only a CuaTurn from nextTurn; nothing
  * sensitive (the key, the request body, the screenshot, the raw response body)
  * is ever returned or logged.
  */