humanish 0.107.0 → 0.109.0

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 { ComputerUseAdmissionLimitError, isComputerUseAdmissionLimitError, } from "./admission-limit.js";
+import { ComputerUsePromptRefusedError } from "./provider-error.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).
+ * 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 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.
  */
@@ -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
@@ -279,8 +280,8 @@ async function postResponse(transport, body, signal, retries, interaction, spend
         catch (error) {
             // An explicit local pre-dispatch limit is terminal. Recreate the fixed safe payload
             // rather than propagating caller-added message/context through the transport seam.
-            if (isCuaAdmissionLimitError(error))
-                throw new CuaAdmissionLimitError();
+            if (isComputerUseAdmissionLimitError(error))
+                throw new ComputerUseAdmissionLimitError();
             // Dispatch may have reached the provider. Preserve this uncertainty even when a later
             // retry succeeds or is refused locally; only that later refusal is known not to dispatch.
             // Under a spend gate the loop accounts for the attempt instead: it books a resend below
@@ -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;
@@ -316,7 +317,7 @@ async function postResponse(transport, body, signal, retries, interaction, spend
             }
             // A usage-policy flag is terminal for this prompt: typed so the loop names it, never retried.
             if (namedProviderErrorCode(bodyText) === "invalid_prompt") {
-                throw new CuaPromptRefusedError("OpenAI", "400 invalid_prompt");
+                throw new ComputerUsePromptRefusedError("OpenAI", "400 invalid_prompt");
             }
             const detail = requestRejectionDetail(bodyText);
             throw new Error(`OpenAI Responses 400${detail === undefined ? "" : ` ${detail}`}`);
@@ -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 study 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;
+}

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

@@ -1,8 +1,10 @@
-import { buildCallOutput, buildContinuationRequest, buildInitialRequest, } from "./openai-wire.js";
+import { CarriedConversation, estimateTokens } from "./openai-context.js";
+import { buildCallOutput, buildContinuationRequest, buildInitialRequest, hintItems, openingMessage, } from "./openai-wire.js";
 /** The closing report's output limit: its own cap, or the declared limit when that is lower. */
 const CLOSING_OUTPUT_LIMIT = 1024;
 function requestContext(settings, state, instructions) {
     return {
+        stateless: state.mode === "explicit_context",
         model: settings.model,
         instructions,
         reasoningEffort: settings.reasoningEffort,
@@ -17,28 +19,43 @@ function requestContext(settings, state, instructions) {
 }
 /** No reply has been accepted yet, so the next request opens the conversation. */
 function isFirstTurn(state) {
-    return state.lastResponseId === undefined && state.pendingCallIds.length === 0;
+    return state.replies === 0;
 }
 /**
- * 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 function turnRequestBody(settings, state, req) {
+export function turnInputItems(state, req) {
+    if (isFirstTurn(state))
+        return [openingMessage(req.instructions, req.observation.screenshot)];
+    return [
+        ...state.pendingCallIds.map((id) => buildCallOutput(id, req.observation.screenshot, req.acknowledgedSafetyChecks)),
+        ...hintItems(req.contextHint),
+    ];
+}
+/**
+ * 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 function turnRequestBody(settings, state, req, sent) {
     const ctx = requestContext(settings, state, req.instructions);
     if (isFirstTurn(state))
         return buildInitialRequest(ctx, req.observation.screenshot);
     return buildContinuationRequest({
         ctx,
         previousResponseId: state.lastResponseId,
-        callOutputs: state.pendingCallIds.map((id) => buildCallOutput(id, req.observation.screenshot, req.acknowledgedSafetyChecks)),
-        ...(req.contextHint === undefined ? {} : { contextHint: req.contextHint }),
-        ...(state.mode === "explicit_context" ? { explicitContextItems: state.lastOutputItems } : {}),
+        callOutputs: [...sent],
+        ...(state.mode === "explicit_context"
+            ? { explicitContextItems: state.conversation.carried() }
+            : {}),
     });
 }
 /** The body of the read-only closing report: no tools, a small output limit, a strict schema. */
-export function debriefRequestBody(settings, state, req) {
+export function debriefRequestBody(settings, state, req, sent) {
     return {
-        ...turnRequestBody(settings, state, req),
+        ...turnRequestBody(settings, state, req, sent),
         tool_choice: "none",
         max_output_tokens: Math.min(settings.maxOutputTokens ?? CLOSING_OUTPUT_LIMIT, CLOSING_OUTPUT_LIMIT),
         text: {
@@ -60,15 +77,65 @@ export function debriefRequestBody(settings, state, req) {
     };
 }
 /**
- * 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 function acceptReply(state, parsed, closing) {
+export function acceptReply(state, parsed, closing, sent) {
     if (!closing && parsed.turn.interruption === "output_limit")
         return;
     if (parsed.turn.responseId !== undefined)
         state.lastResponseId = parsed.turn.responseId;
     state.pendingCallIds = parsed.callIds;
-    state.lastOutputItems = parsed.outputItems;
+    state.replies += 1;
+    state.conversation.accept(state.replies, sent, parsed.outputItems);
+}
+/** The trace's account of how a session carried its conversation (ActorConversation). */
+export class ConversationRecord {
+    now;
+    explicitReason;
+    switchedAt;
+    switchedAtRequest;
+    summarizedTurns = 0;
+    requests = [];
+    constructor(configured, now) {
+        this.now = now;
+        if (configured)
+            this.explicitReason = "configured";
+    }
+    /** The organization rejected server-side state, so the request being sent is explicit_context. */
+    switched() {
+        this.explicitReason = "zdr_rejection";
+        this.switchedAt = new Date(this.now()).toISOString();
+        // Counted like requests[], which includes replies set aside at their output limit.
+        this.switchedAtRequest = this.requests.length + 1;
+    }
+    /** A participant request just went out with `sent` after the carried conversation. */
+    requested(state, sent) {
+        if (state.mode !== "explicit_context") {
+            this.requests.push({ mode: "threaded" });
+            return;
+        }
+        const carried = state.conversation.size();
+        // Only summaries a request carried count; the conversation also trims after the last reply.
+        this.summarizedTurns = carried.notedTurns;
+        this.requests.push({
+            mode: "explicit_context",
+            carriedExchanges: carried.exchanges,
+            carriedScreenshots: carried.screenshots,
+            estimatedInputTokens: carried.estimatedTokens + estimateTokens(sent),
+        });
+    }
+    snapshot(state) {
+        return {
+            mode: state.mode === "explicit_context" ? "explicit_context" : "threaded",
+            ...(this.explicitReason === undefined ? {} : { explicitReason: this.explicitReason }),
+            ...(this.switchedAt === undefined ? {} : { switchedAt: this.switchedAt }),
+            ...(this.switchedAtRequest === undefined
+                ? {}
+                : { switchedAtRequest: this.switchedAtRequest }),
+            summarizedTurns: this.summarizedTurns,
+            requests: this.requests.map((request) => ({ ...request })),
+        };
+    }
 }

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

@@ -1,6 +1,7 @@
 import type { CuaAction, CuaSafetyCheck, CuaTurn } from "./loop.js";
 import type { ReasoningEffort } from "../reasoning-effort.js";
 export declare function asRecord(value: unknown): Record<string, unknown>;
+export declare function asArray(value: unknown): unknown[];
 export declare function optionalString(value: unknown): string | undefined;
 /**
  * Map an OpenAI computer action object to a provider-neutral CuaAction, or null
@@ -23,11 +24,16 @@ export interface ParsedOpenAiResponse {
 export declare function parseOpenAiResponse(raw: unknown): ParsedOpenAiResponse;
 export type OpenAiReasoningSummary = "auto" | "concise" | "detailed";
 export interface OpenAiCuContext {
+    /**
+     * The server keeps no conversation (explicit_context): the request asks not to be stored and
+     * for its reasoning back in encrypted form, so the next request can carry it.
+     */
+    stateless?: boolean;
     model: string;
     instructions: string;
     reasoningEffort: ReasoningEffort;
     maxOutputTokens?: number;
-    /** When set, request provider-sanctioned reasoning summaries (#427). Absent = do not ask. */
+    /** When set, request provider-sanctioned reasoning summaries. Absent = do not ask. */
     reasoningSummary?: OpenAiReasoningSummary;
     safetyIdentifier?: string;
 }
@@ -37,14 +43,18 @@ export interface OpenAiCuContext {
  * limit when that is lower.
  */
 export declare function buildInitialRequest(ctx: OpenAiCuContext, screenshot?: Buffer): Record<string, unknown>;
+/** One input message, read as the words of `sender`: the user, the developer, or the model itself. */
+export declare function inputMessage(sender: "user" | "developer" | "assistant", content: readonly unknown[]): Record<string, unknown>;
+/** The first request's only input item: the instructions and, when there is one, the first screen. */
+export declare function openingMessage(instructions: string, screenshot?: Buffer): Record<string, unknown>;
 /**
  * Build one computer_call_output for a pending call id, carrying the latest
  * screenshot as an inline data URL. Acknowledged safety checks (if any) are
  * echoed back so the model can proceed past a check the harness approved.
  *
  * The screenshot param is `Buffer | undefined` because CuaObservation.screenshot is now
- * optional (a non-vision executor omits it). This provider is a VISION model (it sets
- * requiresFrame), so a missing frame is a hard error here — defense-in-depth: the loop's
+ * optional (a non-vision executor omits it). This provider is a vision model (it sets
+ * requiresFrame), so a missing frame is a hard error here as defense-in-depth: the loop's
  * per-turn requiresFrame guard already fails closed before this is reached, but throwing keeps
  * the mapper self-validating and isolable.
  */
@@ -52,16 +62,18 @@ export declare function buildCallOutput(callId: string, screenshot: Buffer | und
 export interface ContinuationRequestArgs {
     ctx: OpenAiCuContext;
     previousResponseId: string | undefined;
-    callOutputs: object[];
+    callOutputs: readonly unknown[];
     contextHint?: string;
     explicitContextItems?: unknown[];
 }
+/** An optional context hint as input items (none when there is no hint). */
+export declare function hintItems(contextHint: string | undefined): unknown[];
 /**
  * Build a continuation request body. Two modes:
  *  - default: thread server-side state via previous_response_id and send only the
  *    new call outputs (plus an optional hint).
- *  - explicit-context (ZDR): no previous_response_id; the prior output items are
- *    re-sent inline ahead of the new call outputs so the model has full context
- *    without the server retaining any.
+ *  - explicit-context (ZDR): no previous_response_id; the carried conversation
+ *    (openai-context.ts) is sent inline ahead of the new call outputs, so the model
+ *    has the session without the server retaining any.
  */
 export declare function buildContinuationRequest(args: ContinuationRequestArgs): Record<string, unknown>;