humanish 0.106.1 → 0.108.0

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

@@ -7,13 +7,13 @@ 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).
+ * 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.
  */
@@ -46,7 +46,7 @@ export declare const RETRY_AFTER_CAP_MS = 60000;
  * Parse a Retry-After header (delay-seconds or an HTTP-date) into milliseconds from `now`;
  * undefined when absent or unreadable. OpenAI's 2026-09-02 change added `429 slow_down` and
  * `503 server_is_overloaded`, both of which may carry it; a fixed 200/400/800 ms backoff against
- * a 20 s hint burns every retry inside the hint and ends the lane for nothing.
+ * a 20 s hint burns every retry inside the hint and ends the participant's session for nothing.
  */
 export declare function retryAfterMs(value: string | null | undefined, now: number): number | undefined;
 /**
@@ -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.
  */

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

@@ -1,7 +1,8 @@
 import { validClosingReport } from "./loop.js";
 import { CuaAdmissionLimitError, isCuaAdmissionLimitError } from "./admission-limit.js";
 import { CuaPromptRefusedError } from "./provider-error.js";
-import { acceptReply, debriefRequestBody, turnRequestBody, } from "./openai-requests.js";
+import { CarriedConversation } from "./openai-context.js";
+import { acceptReply, ConversationRecord, debriefRequestBody, turnInputItems, turnRequestBody, } from "./openai-requests.js";
 import { asRecord, optionalString, parseOpenAiResponse, } from "./openai-wire.js";
 import { redactText } from "../../evidence/redaction.js";
 import { isMaxOutputTokens } from "../output-token-limit.js";
@@ -10,35 +11,35 @@ import { OPENAI_RESPONSES_URL } from "../openai-endpoint.js";
 // A public-safe re-derivation of the OpenAI Responses API computer-use provider,
 // behind the CuaProvider port from src/actors/computer-use/loop.ts. The pure wire mapping
 // (openAiActionToCua, parseOpenAiResponse and the request builders) is in openai-wire.ts.
-// This module is the live shim: createOpenAiResponsesProvider does a RAW POST to the
+// This module is the live shim: createOpenAiResponsesProvider does a raw POST to the
 // Responses endpoint (no SDK dependency) through an injectable FetchLike seam, so the retry,
 // ZDR fallback, and state threading are testable with a fake.
 //
 // Public-safety invariants (this is an OSS repo): the apiKey only ever appears in
 // the Authorization header, never in a returned object, thrown error, or comment.
 // Request bodies (which carry base64 screenshots and the persona instructions)
-// and screenshots are never logged or returned; nextTurn returns ONLY a CuaTurn,
+// and screenshots are never logged or returned; nextTurn returns only a CuaTurn,
 // and the engine handles redaction of CuaTurn fields downstream. Error messages
 // carry the HTTP status only, never the response body (it can echo the input).
 //
-// Wire capture (fixture provenance). The 0.6.1 parser incident — the parser read
+// Wire capture (fixture provenance). In the 0.6.1 parser incident, the parser read
 // `computer_call.action` (singular) while the live API returns `actions` (array),
-// and the hand-written fixtures encoded the SAME wrong shape, so tests passed in
-// lockstep with the bug while every live action was silently dropped — taught us
-// that deterministic fixtures must derive from CAPTURED live wire shapes, never
+// and the hand-written fixtures encoded the same wrong shape, so tests passed in
+// lockstep with the bug while every live action was silently dropped. It taught us
+// that deterministic fixtures must derive from captured live wire shapes, never
 // from memory. Setting HUMANISH_CUA_WIRE_CAPTURE_DIR makes the live shim persist
-// each successful Responses RESPONSE body into that directory as pretty-printed
+// each successful Responses response body into that directory as pretty-printed
 // JSON, one file per provider call in call order (wire-001.json, wire-002.json,
 // ...), for refreshing fixtures. The capture seam is:
-//  - OPT-IN: unset (or empty) env means zero behavior change — nothing is written;
-//  - RESPONSE-side only: request bodies carry base64 screenshots and the persona
-//    instructions and are NEVER captured; non-ok response bodies can echo the
+//  - Opt-in: unset (or empty) env means zero behavior change, and nothing is written;
+//  - Response-side only: request bodies carry base64 screenshots and the persona
+//    instructions and are never captured; non-ok response bodies can echo the
 //    request and are never captured either;
-//  - REDACTED: every string field (keys and values) passes through the shared
+//  - Redacted: every string field (keys and values) passes through the shared
 //    redactText (src/evidence/redaction.ts) before writing, so a secret-shaped echo in a
 //    response cannot persist to disk.
 // Point the env var at a gitignored path (e.g. under .humanish/): raw captures must
-// never be committed — fixtures derived from them must be minimal, hand-reviewed
+// never be committed; fixtures derived from them must be minimal, hand-reviewed
 // excerpts checked into tests deliberately.
 export const OPENAI_RESPONSES_CU_CAPABILITIES = {
     headless: true,
@@ -52,12 +53,12 @@ export const OPENAI_RESPONSES_CU_CAPABILITIES = {
 };
 // The flagship 5.6-generation tier ("gpt-5.6" is OpenAI's alias for this exact id; the
 // computer-use guide's own examples run on it). Explicit tier id so trace provenance and the
-// rate-table key stay stable if OpenAI repoints the alias (#334).
+// rate-table key stay stable if OpenAI repoints the alias.
 export 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).
+ * to be able to say what will actually run.
  */
 export const DEFAULT_OPENAI_CU_REASONING_EFFORT = "medium";
 // ---------------------------------------------------------------------------
@@ -66,7 +67,7 @@ export const DEFAULT_OPENAI_CU_REASONING_EFFORT = "medium";
 /** The opt-in gate for response wire capture: a directory path, or unset for off. */
 export 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.
  */
@@ -93,7 +94,7 @@ export const RETRY_AFTER_CAP_MS = 60_000;
  * Parse a Retry-After header (delay-seconds or an HTTP-date) into milliseconds from `now`;
  * undefined when absent or unreadable. OpenAI's 2026-09-02 change added `429 slow_down` and
  * `503 server_is_overloaded`, both of which may carry it; a fixed 200/400/800 ms backoff against
- * a 20 s hint burns every retry inside the hint and ends the lane for nothing.
+ * a 20 s hint burns every retry inside the hint and ends the participant's session for nothing.
  */
 export function retryAfterMs(value, now) {
     if (value === null || value === undefined)
@@ -109,7 +110,7 @@ export function retryAfterMs(value, now) {
     return Math.max(0, at - now);
 }
 /**
- * The provider error codes a lane's reason may name. Read from a non-ok body, which is never
+ * The provider error codes a participant's reason may name. Read from a non-ok body, which is never
  * kept or logged (it can echo the input); only a code on this list crosses over.
  */
 const NAMED_PROVIDER_ERROR_CODES = [
@@ -222,7 +223,7 @@ function defaultDelay(ms) {
 function isAbortError(error) {
     return error instanceof Error && error.name === "AbortError";
 }
-// Opt-in response wire capture (see module header): an undefined directory means OFF and zero
+// Opt-in response wire capture (see module header): an undefined directory means off and zero
 // behavior change. The counter is per-provider, so file order is call order.
 function createWireCapture(captureDir) {
     let captureCount = 0;
@@ -237,7 +238,7 @@ function createWireCapture(captureDir) {
     };
     return {
         prepareNext,
-        // Fails loud: a silent capture failure would mean missing turns in a fixture refresh — the
+        // Fails loud: a silent capture failure would mean missing turns in a fixture refresh: the
         // exact "fixtures drift from the wire" pathology capture exists to prevent.
         record: async (raw) => {
             if (captureDir === undefined)
@@ -252,7 +253,7 @@ function createWireCapture(captureDir) {
 }
 // POST the JSON body and return the parsed JSON on success. Retries on
 // transient statuses (408/409/429/>=500). Maps a ZDR-policy 400 to a typed
-// ZdrError; any other non-ok status throws with the STATUS ONLY (never the
+// ZdrError; any other non-ok status throws with the status only (never the
 // body, which can echo the input/screenshot).
 async function postResponse(transport, body, signal, retries, interaction, spend) {
     // Preflight the deterministic next capture leaf before any network side
@@ -300,7 +301,7 @@ async function postResponse(transport, body, signal, retries, interaction, spend
         }
         if (res.ok) {
             const parsed = await res.json();
-            // Capture AFTER ok and BEFORE parse-to-CuaTurn: responses only, never the
+            // Capture after ok and before parse-to-CuaTurn: responses only, never the
             // request (screenshots/instructions) and never a non-ok body (input echo).
             await transport.capture.record(parsed);
             return parsed;
@@ -353,7 +354,7 @@ async function postResponse(transport, body, signal, retries, interaction, spend
  * 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.
  */
@@ -379,10 +380,11 @@ export function createOpenAiResponsesProvider(options) {
     const state = {
         lastResponseId: undefined,
         pendingCallIds: [],
-        lastOutputItems: [],
+        replies: 0,
+        conversation: new CarriedConversation(),
         mode: options.zeroDataRetention ? "explicit_context" : "previous_response_id",
         // Latches to undefined (stop asking) for the rest of the session when the
-        // account/model rejects the summary request — see OpenAiResponsesProviderOptions.
+        // account/model rejects the summary request; see OpenAiResponsesProviderOptions.
         reasoningSummary: options.reasoningSummary === "off" ? undefined : (options.reasoningSummary ?? "auto"),
     };
     const transport = {
@@ -396,15 +398,16 @@ export function createOpenAiResponsesProvider(options) {
         },
     };
     const post = (body, signal, retries = maxRetries, interaction = true, spend) => postResponse(transport, body, signal, retries, interaction, spend);
+    const record = new ConversationRecord(options.zeroDataRetention === true, options.now ?? Date.now);
     // POST with the recoverable-policy latches: a ZDR rejection switches to explicit-context mode; a
     // reasoning-summary rejection latches summaries off. Each latch can flip only once, so the loop
     // is bounded; anything else rethrows. The body is rebuilt per attempt so a flipped latch shows.
-    const postTurn = async (req, signal, spend) => {
+    const postTurn = async (req, sent, signal, spend) => {
         if (options.singleDispatch === true)
-            return post(turnRequestBody(settings, state, req), signal, 0);
+            return post(turnRequestBody(settings, state, req, sent), signal, 0);
         for (;;) {
             try {
-                return await post(turnRequestBody(settings, state, req), signal, maxRetries, true, spend);
+                return await post(turnRequestBody(settings, state, req, sent), signal, maxRetries, true, spend);
             }
             catch (error) {
                 if (error instanceof SummaryRejectionError && state.reasoningSummary !== undefined) {
@@ -412,6 +415,7 @@ export function createOpenAiResponsesProvider(options) {
                     continue;
                 }
                 if (error instanceof ZdrError && state.mode !== "explicit_context") {
+                    record.switched();
                     state.mode = "explicit_context";
                     continue;
                 }
@@ -421,12 +425,15 @@ export function createOpenAiResponsesProvider(options) {
     };
     const requestTurn = async (req, signal, closing = false, spend) => {
         await capture.prepareNext();
+        const sent = turnInputItems(state, req);
         // A closing report makes exactly one request: no HTTP or policy-latch retries.
         const raw = closing
-            ? await post(debriefRequestBody(settings, state, req), signal, 0, false)
-            : await postTurn(req, signal, spend);
+            ? await post(debriefRequestBody(settings, state, req, sent), signal, 0, false)
+            : await postTurn(req, sent, signal, spend);
+        if (!closing)
+            record.requested(state, sent);
         const parsed = parseOpenAiResponse(raw);
-        acceptReply(state, parsed, closing);
+        acceptReply(state, parsed, closing, sent);
         if (closing) {
             // Refusals, incomplete output, malformed JSON, and invalid shapes remain no-report results.
             // Never promote raw JSON or a fallback paragraph into a structured finding.
@@ -445,14 +452,14 @@ export function createOpenAiResponsesProvider(options) {
     return {
         id: "openai-responses-cu",
         version: model,
-        // The effort the wire actually carries, not the one the lab asked for — the provider defaults
-        // an absent request to "medium", and the trace has to say what produced it (#497).
+        // The effort the wire actually carries, not the one the lab asked for: the provider defaults
+        // an absent request to "medium", and the trace has to say what produced it.
         modelSettings: {
             reasoningEffort,
             ...(maxOutputTokens === undefined ? {} : { maxOutputTokens }),
         },
         capabilities: OPENAI_RESPONSES_CU_CAPABILITIES,
-        // This is a VISION provider: nextTurn sends the screenshot as the computer_call_output, so
+        // This is a vision provider: nextTurn sends the screenshot as the computer_call_output, so
         // it cannot reason over a screenshot-less observation. The loop reads this to fail closed
         // (harness_error) when a state-only executor is paired with it (provider-authoring contract).
         requiresFrame: true,
@@ -461,8 +468,12 @@ export function createOpenAiResponsesProvider(options) {
             return interactionUsageIncomplete;
         },
         nextTurn: (req, signal, spend) => requestTurn(req, signal, false, spend),
-        // Stateless mode retains only the latest output packet, not the whole session needed for
-        // retrospective claims. This getter follows both configured ZDR and a runtime policy latch.
+        get conversation() {
+            return record.snapshot(state);
+        },
+        // An explicit-context conversation summarizes its oldest turns past its budget, so it may not
+        // hold the whole session a retrospective report needs. This getter follows both configured
+        // ZDR and a runtime policy latch.
         get debrief() {
             return state.mode === "explicit_context" || state.lastResponseId === undefined
                 ? undefined

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

@@ -1,5 +1,7 @@
 import type { CuaTurnRequest } from "./loop.js";
 import type { ReasoningEffort } from "../reasoning-effort.js";
+import type { ActorConversation } from "../contract.js";
+import { CarriedConversation } from "./openai-context.js";
 import { type OpenAiReasoningSummary, type ParsedOpenAiResponse } from "./openai-wire.js";
 /** Request settings fixed for a provider's whole session. */
 export interface OpenAiRequestSettings {
@@ -13,23 +15,47 @@ export interface OpenAiConversationState {
     lastResponseId: string | undefined;
     /** computer_call ids the next request owes an output for. */
     pendingCallIds: string[];
-    /** The last reply's output items, resent in explicit-context mode. */
-    lastOutputItems: unknown[];
+    /** Accepted replies so far; the next request is number `replies + 1`. */
+    replies: number;
+    /** The whole conversation, which explicit-context requests carry within its token budget. */
+    conversation: CarriedConversation;
     /** explicit_context after a zero-data-retention rejection or when configured. */
     mode: "previous_response_id" | "explicit_context";
     /** Undefined once the account or model rejected reasoning summaries. */
     reasoningSummary: OpenAiReasoningSummary | undefined;
 }
 /**
- * The body of the next participant request: the opening request with the first screen, or a
- * continuation that answers each pending computer_call with the latest screenshot.
+ * The items the next request adds to the conversation: the opening message with the first
+ * screen, or an output for each pending computer_call with the latest screenshot and any hint.
+ * Built once per turn, so every attempt at the request and the accepted reply see the same items.
  */
-export declare function turnRequestBody(settings: OpenAiRequestSettings, state: OpenAiConversationState, req: CuaTurnRequest): Record<string, unknown>;
+export declare function turnInputItems(state: OpenAiConversationState, req: CuaTurnRequest): readonly unknown[];
+/**
+ * The body of the next participant request: the opening request, or a continuation carrying
+ * `sent` (turnInputItems). A threaded continuation names the previous response; an
+ * explicit-context one carries the conversation ahead of `sent`.
+ */
+export declare function turnRequestBody(settings: OpenAiRequestSettings, state: OpenAiConversationState, req: CuaTurnRequest, sent: readonly unknown[]): Record<string, unknown>;
 /** The body of the read-only closing report: no tools, a small output limit, a strict schema. */
-export declare function debriefRequestBody(settings: OpenAiRequestSettings, state: OpenAiConversationState, req: CuaTurnRequest): Record<string, unknown>;
+export declare function debriefRequestBody(settings: OpenAiRequestSettings, state: OpenAiConversationState, req: CuaTurnRequest, sent: readonly unknown[]): Record<string, unknown>;
 /**
- * Move the conversation on to an accepted reply. A participant reply cut off by the output limit
- * is set aside, so the next request is the same one again (outputLimitRetry); its actions never
- * run, so no call output is owed for them.
+ * Move the conversation on to an accepted reply to a request that added `sent`. A participant
+ * reply cut off by the output limit is set aside, so the next request is the same one again
+ * (outputLimitRetry); its actions never run, so no call output is owed for them.
  */
-export declare function acceptReply(state: OpenAiConversationState, parsed: ParsedOpenAiResponse, closing: boolean): void;
+export declare function acceptReply(state: OpenAiConversationState, parsed: ParsedOpenAiResponse, closing: boolean, sent: readonly unknown[]): void;
+/** The trace's account of how a session carried its conversation (ActorConversation). */
+export declare class ConversationRecord {
+    private readonly now;
+    private explicitReason;
+    private switchedAt;
+    private switchedAtRequest;
+    private summarizedTurns;
+    private readonly requests;
+    constructor(configured: boolean, now: () => number);
+    /** The organization rejected server-side state, so the request being sent is explicit_context. */
+    switched(): void;
+    /** A participant request just went out with `sent` after the carried conversation. */
+    requested(state: OpenAiConversationState, sent: readonly unknown[]): void;
+    snapshot(state: OpenAiConversationState): ActorConversation;
+}