humanish 0.107.0 → 0.108.0

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

@@ -20,7 +20,7 @@ export class TraceRecorder {
     constructor(now) {
         this.now = now;
     }
-    // The ONE recording choke point (#441): every trace item is stamped `at` from the
+    // The single recording choke point: every trace item is stamped `at` from the
     // loop's injected clock as it is recorded, so timed playback reads recorded facts
     // (deterministic in tests via the injected `now`). The id is allocated before the body is
     // built, so a body that fails to build (a redaction error) still consumes its id.
@@ -40,7 +40,7 @@ export function statusForCompletionReason(reason) {
         case "turn_completed": // turn_completed is a Codex reason; this loop emits goal_satisfied
             return "passed";
         // A session that ran out of time or budget did not reach its goal, whatever it achieved along
-        // the way. Calling that `passed` is how a truncated study came to be reported as a green one —
+        // the way. Calling that `passed` is how a truncated study came to be reported as a green one,
         // and why "raise the timeout" kept landing on the operator instead of on the tool. This switch
         // is exhaustive with no default, so a new completion reason forces a compile error here.
         case "budget_reached":
@@ -51,7 +51,7 @@ export function statusForCompletionReason(reason) {
             return "blocked";
         // A participant who stopped trying is the single most valuable thing a usability study
         // produces. Recording it as `failed` said the instrument broke, which is a different claim and
-        // a false one — see docs/principles/three-roles.md.
+        // a false one; see docs/principles/three-roles.md.
         case "gave_up":
             return "abandoned";
         // Only the harness failing is a harness failure.
@@ -77,12 +77,12 @@ export function loopResult(session, stop, debrief) {
         ? "no screenshots captured"
         : session.redactScreenshots
             ? `${counts.screenshots} screenshot(s) redacted to blurred thumbnails via RedactionHooks`
-            : `${counts.screenshots} full-fidelity screenshot(s) retained for local use — NOT redacted for publishing; set redactScreenshots to blur a share-as-is bundle`;
-    // Self-describing artifact (invariant 6): when any observation carried structured app state,
+            : `${counts.screenshots} unblurred screenshot(s) kept for local use and not redacted for publishing; set redactScreenshots to blur screenshots in a bundle you plan to share`;
+    // Self-describing artifact: when any observation carried structured app state,
     // the trace says how the loop handled it: it fed progress and task checks and was not written to
     // the trace. The appState itself never appears in this bundle.
     const notes = session.observedAppState
-        ? `${screenshotNote}. App state was observed each turn to drive progress detection (a state-driven executor) and was NOT written to the trace — it is a runtime-only progress input, never persisted as evidence in this slice.`
+        ? `${screenshotNote}. App state was read each turn to detect progress (an in-process executor) and was not written to the trace: it is used only while the run is live and is never stored as evidence.`
         : screenshotNote;
     const tokenUsage = usage.tokenUsage();
     const trace = {
@@ -90,6 +90,7 @@ export function loopResult(session, stop, debrief) {
         provider: provider.id,
         ...usage.liveMetadata(),
         ...(provider.version === undefined ? {} : { providerVersion: provider.version }),
+        ...(provider.conversation === undefined ? {} : { conversation: provider.conversation }),
         protocol: "cua-loop",
         lane: "computer-use",
         persona: settings.persona,
@@ -130,8 +131,8 @@ export function loopResult(session, stop, debrief) {
         ...(usage.interactionUsageIncomplete(session.capDeclared)
             ? { interactionUsageIncomplete: true }
             : {}),
-        // The funnel is present exactly when a protocol was declared — including a session that ended
-        // on turn 0, whose funnel honestly reads 0/N. No tasks declared means no funnel, not an empty one.
+        // The funnel is present exactly when a protocol was declared, including a session that ended
+        // on turn 0, whose funnel reads 0/N. No tasks declared means no funnel, not an empty one.
         ...(session.taskTracker === undefined ? {} : { taskFunnel: session.taskTracker.funnel() }),
         ...(tokenUsage === undefined ? {} : { tokenUsage }),
         capabilities: provider.capabilities,

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

@@ -1,5 +1,5 @@
 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";
@@ -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
+     * 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.
+     * 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,11 +324,11 @@ 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 lab'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[];
@@ -338,18 +340,18 @@ export interface CuaLoopOptions {
      */
     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;
@@ -399,7 +401,7 @@ export interface CuaLoopOptions {
      */
     onScreenshot?: (frame: Buffer) => void;
     /**
-     * Trace snapshot for a watcher (#441): the redacted items recorded so far, with the running
+     * 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

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/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

@@ -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.
  */
@@ -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.
  */