humanish 0.106.1 → 0.108.0

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

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

@@ -11,7 +11,7 @@
 export function asRecord(value) {
     return typeof value === "object" && value !== null ? value : {};
 }
-function asArray(value) {
+export function asArray(value) {
     return Array.isArray(value) ? value : [];
 }
 function asNumber(value) {
@@ -165,9 +165,9 @@ export function parseOpenAiResponse(raw) {
                 const callId = optionalString(item.call_id);
                 if (callId !== undefined)
                     callIds.push(callId);
-                // The live Responses API returns the actions as an ARRAY (`item.actions`); a single
-                // computer_call can carry several. (An older/alt shape used a singular `item.action` —
-                // supported as a fallback.) Reading only `item.action` silently dropped EVERY action,
+                // The live Responses API returns the actions as an array (`item.actions`); a single
+                // computer_call can carry several. (An older/alt shape used a singular `item.action`,
+                // supported as a fallback.) Reading only `item.action` silently dropped every action,
                 // which made the loop see zero actions and stop on a false `goal_satisfied`.
                 const rawActions = Array.isArray(item.actions)
                     ? item.actions
@@ -209,9 +209,9 @@ export function parseOpenAiResponse(raw) {
     // Of the input tokens, how many the provider served from its prompt cache. This loop threads
     // state with previous_response_id and re-sends a growing warm prefix every turn, so most input on
     // a long session is a cache hit billed at a fraction of the full rate. Not reading it made every
-    // cost line materially overstate the bill (#391).
+    // cost line materially overstate the bill.
     const usageCachedInput = optionalNumber(asRecord(usageRecord.input_tokens_details).cached_tokens);
-    // GPT-5.6+ bills cache WRITES (1.25x input) and reports them here; older models omit the field.
+    // GPT-5.6+ bills cache writes (1.25x input) and reports them here; older models omit the field.
     const usageCacheWriteInput = optionalNumber(asRecord(usageRecord.input_tokens_details).cache_write_tokens);
     const usage = usageInput === undefined && usageOutput === undefined
         ? undefined
@@ -253,12 +253,12 @@ function sharedRequestFields(ctx) {
         // instructions, a provider that does not fully retain prior state can drift
         // into asking the operator what to do.
         instructions: ctx.instructions,
-        // The Responses API `computer` tool takes no display/environment fields — the model infers
+        // The Responses API `computer` tool takes no display/environment fields; the model infers
         // resolution from the screenshots it is sent. (Sending display_* returns a 400
         // "Unknown parameter tools[0].display_width", confirmed against the live API 2026-06.)
         tools: [{ type: "computer" }],
         truncation: "auto",
-        // `summary` asks for the provider-SANCTIONED reasoning summary items (#427) — the
+        // `summary` asks for the provider-sanctioned reasoning summary items; the
         // capture side never scrapes or reconstructs raw chain-of-thought. Parsed by
         // parseOpenAiResponse into turn.reasoning; the loop records them as redacted
         // `kind: "reasoning"` trace items.
@@ -267,6 +267,7 @@ function sharedRequestFields(ctx) {
             ...(ctx.reasoningSummary === undefined ? {} : { summary: ctx.reasoningSummary }),
         },
         ...(ctx.safetyIdentifier === undefined ? {} : { safety_identifier: ctx.safetyIdentifier }),
+        ...(ctx.stateless === true ? { store: false, include: ["reasoning.encrypted_content"] } : {}),
     };
 }
 /**
@@ -284,32 +285,35 @@ export function buildInitialRequest(ctx, screenshot) {
     const maxOutputTokens = Math.min(ctx.maxOutputTokens ?? FIRST_TURN_OUTPUT_LIMIT, FIRST_TURN_OUTPUT_LIMIT);
     return {
         ...sharedRequestFields({ ...ctx, maxOutputTokens }),
-        input: [
-            {
-                role: "user",
-                content: [
-                    { type: "input_text", text: ctx.instructions },
-                    ...(screenshot === undefined
-                        ? []
-                        : [
-                            {
-                                type: "input_image",
-                                image_url: `data:image/png;base64,${screenshot.toString("base64")}`,
-                            },
-                        ]),
-                ],
-            },
-        ],
+        input: [openingMessage(ctx.instructions, screenshot)],
     };
 }
+/** One input message, read as the words of `sender`: the user, the developer, or the model itself. */
+export function inputMessage(sender, content) {
+    return { role: sender, content: [...content] };
+}
+/** The first request's only input item: the instructions and, when there is one, the first screen. */
+export function openingMessage(instructions, screenshot) {
+    return inputMessage("user", [
+        { type: "input_text", text: instructions },
+        ...(screenshot === undefined
+            ? []
+            : [
+                {
+                    type: "input_image",
+                    image_url: `data:image/png;base64,${screenshot.toString("base64")}`,
+                },
+            ]),
+    ]);
+}
 /**
  * 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.
  */
@@ -335,19 +339,17 @@ export function buildCallOutput(callId, screenshot, acknowledged) {
             : {}),
     };
 }
-// Turn an optional context-hint string into an input item array (or empty).
-function hintItems(contextHint) {
-    return contextHint
-        ? [{ role: "user", content: [{ type: "input_text", text: contextHint }] }]
-        : [];
+/** An optional context hint as input items (none when there is no hint). */
+export function hintItems(contextHint) {
+    return contextHint ? [inputMessage("user", [{ type: "input_text", text: contextHint }])] : [];
 }
 /**
  * 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 function buildContinuationRequest(args) {
     const { ctx, previousResponseId, callOutputs, contextHint, explicitContextItems } = args;

package/dist/actors/contract.d.ts

@@ -4,32 +4,32 @@ import type { TaskFunnel } from "../lab/tasks.js";
 import { type CuaProviderFailurePhase } from "./computer-use/provider-error.js";
 export declare const ACTOR_TRACE_SCHEMA = "humanish.actor-trace.v1";
 /**
- * How a session ended, from the point of view of the STUDY rather than the harness.
+ * How a session ended, from the point of view of the study rather than the harness.
  *
  * The distinction matters because two of these are participant outcomes and the rest are not. A
  * participant who abandons a task is the single most valuable thing a usability study produces, and
- * recording that as `failed` — as this type used to force — reads as the instrument breaking. See
+ * recording that as `failed` reads as the instrument breaking. See
  * docs/principles/three-roles.md.
  *
  * - `passed`      the participant reached the goal
- * - `abandoned`   the participant stopped trying. A FINDING, not a malfunction
+ * - `abandoned`   the participant stopped trying. A finding, not a malfunction
  * - `incomplete`  the session ended (time or budget) before the goal was reached
  * - `blocked`     the participant could not proceed: an approval the run could not give, or a
- *                 blocker they described in their own final words (#476)
+ *                 blocker they described in their own final words
  * - `timed_out`   the session hit its deadline with no productive activity at all
- * - `failed`      the HARNESS failed: a dead sandbox, a provider error, a broken artifact
+ * - `failed`      the harness failed: a dead sandbox, a provider error, a broken artifact
  */
 export declare const ACTOR_STATUSES: readonly ["passed", "abandoned", "incomplete", "blocked", "timed_out", "failed"];
 export type ActorStatus = (typeof ACTOR_STATUSES)[number];
 /**
- * What the PARTICIPANT said happened, in a field rather than a paragraph (#570). Providers whose
+ * What the participant said happened, in a field rather than a paragraph. Providers whose
  * reply is schema-constrained (the local-agent routes) fill it on their final turn; a free-text
- * provider leaves it absent and the lane falls back to reading the closing message. `reached`:
+ * provider leaves it absent and the route falls back to reading the closing message. `reached`:
  * the task is finished. `blocked`: something in the app stopped the participant. `not_reached`:
  * the participant stopped for another reason (gave up, ran out of ideas).
  */
 export type ParticipantDeclaredOutcome = "reached" | "not_reached" | "blocked";
-/** Statuses that describe what happened to a PARTICIPANT rather than a harness malfunction. Verify
+/** Statuses that describe what happened to a participant rather than a harness malfunction. Verify
  *  treats these as study results, so a run whose evidence is sound is not called untrustworthy just
  *  because a persona gave up. */
 export declare const PARTICIPANT_OUTCOME_STATUSES: readonly ActorStatus[];
@@ -62,11 +62,11 @@ export interface ActorTraceItem {
         redaction: "blurred" | "ocr_scrubbed" | "none";
     };
     text?: string;
-    /** When the item was recorded (ISO-8601), from the loop's injected clock. Additive
-     *  (#441): items from older bundles and non-stamping producers lack it, so every
+    /** When the item was recorded (ISO-8601), from the loop's injected clock. Additive:
+     *  items from older bundles and non-stamping producers lack it, so every
      *  consumer must treat absence as "timing unknown", never as t=0. */
     at?: string;
-    /** Structured pointer coordinates for click-like `ui_action` items (#441) — the
+    /** Structured pointer coordinates for click-like `ui_action` items: the
      *  recorded fact the Observer's pins previously re-parsed out of the title text. */
     coord?: {
         x: number;
@@ -83,13 +83,13 @@ export interface ActorCapabilities {
     inProcessTools: boolean;
     license: "open" | "source-available" | "proprietary";
     /**
-     * WHERE this actor's runtime key lives, per the placement rule (invariants-and-defaults.md):
-     * "keys live where the keyed process runs — and nowhere else." Registry metadata the engine
-     * enforces, NOT a code convention.
+     * Where this actor's runtime key lives, per the placement rule (invariants-and-defaults.md):
+     * "keys live where the keyed process runs, and nowhere else." Registry metadata the engine
+     * enforces, not a code convention.
      *   - "external" (the implicit default for every existing actor): the keyed process (e.g. a
-     *     computer-use provider loop) runs OUTSIDE any sandbox, so its key never enters one.
+     *     computer-use provider loop) runs outside any sandbox, so its key never enters one.
      *   - "in-sandbox-command-scoped": the keyed process is an agent-harness-under-test that runs
-     *     INSIDE the sandbox; its runtime key is injected ONLY into the per-command `envs` of that
+     *     inside the sandbox; its runtime key is injected only into the per-command `envs` of that
      *     invocation (never `Sandbox.create({envs})`, which is sandbox-global), the key is presumed
      *     exfiltratable, and the blast radius is bounded by key scoping + a spend budget.
      * Absent === "external". On the shipped terminal-product live route, the engine enforces this
@@ -115,18 +115,18 @@ export interface ActorPersonaRef {
 export interface ActorTokenUsage {
     input?: number;
     output?: number;
-    /** Of `input`, how many tokens were served from the provider's prompt cache. Optional and
-     *  HONESTLY ABSENT: a provider that does not report it leaves this undefined rather than
-     *  reporting 0, because 0 and "unknown" price very differently (#391). */
+    /** Of `input`, how many tokens were served from the provider's prompt cache. Optional. A
+     *  provider that does not report it leaves this undefined rather than
+     *  reporting 0, because 0 and "unknown" price very differently. */
     cachedInput?: number;
-    /** Of `input`, how many tokens were newly WRITTEN to the provider's prompt cache
+    /** Of `input`, how many tokens were newly written to the provider's prompt cache
      *  (OpenAI 5.6+ bills these at a surcharge and reports `cache_write_tokens`). Same
-     *  honestly-absent discipline as `cachedInput` (#334). */
+     *  absent-when-unreported rule as `cachedInput`. */
     cacheWriteInput?: number;
     /** Per model-inference request usage, in request order. One provider interaction can contain
      *  several inferences around native tool calls. A provider that re-prices whole requests past
      *  an input-size threshold can only be priced exactly from these sizes; totals cannot say which
-     *  requests crossed. Additive and honestly absent on producers that do not record it (#334). */
+     *  requests crossed. Additive, and absent on producers that do not record it. */
     turns?: Array<{
         input?: number;
         cachedInput?: number;
@@ -137,12 +137,13 @@ export interface ActorTokenUsage {
     costUsd?: number;
 }
 /**
- * Codex CLI releases a recorded account profile may name. Append-only: a release can leave the
- * launch lists in codex/qualified-versions.ts, but saved bundles naming it stay readable.
+ * The oldest Codex CLI release a recorded account profile may name. Readers accept every stable
+ * `MAJOR.MINOR.PATCH` release from it on, so a saved bundle stays readable whichever release
+ * recorded it; launch admission (codex/codex-admission.ts) alone decides what runs.
  */
-export declare const RECORDED_CODEX_CLI_VERSIONS: readonly ["0.154.0", "0.157.1", "0.159.2", "0.159.3", "0.160.0"];
-export type RecordedCodexCliVersion = (typeof RECORDED_CODEX_CLI_VERSIONS)[number];
-export declare function isRecordedCodexCliVersion(value: unknown): value is RecordedCodexCliVersion;
+export declare const RECORDED_CODEX_CLI_FLOOR = "0.154.0";
+/** A stable release at or above the floor. Parts compare as digit strings, exact at any length. */
+export declare function isRecordedCodexCliVersion(value: unknown): value is string;
 /** Requested execution profile; per-request verification is recorded separately. */
 export interface ActorExecutionProfile {
     schema: "humanish.actor-execution-profile.v1";
@@ -151,7 +152,8 @@ export interface ActorExecutionProfile {
     billing: "account-unknown";
     requestedModel: string;
     reasoningEffort: import("./reasoning-effort.js").ReasoningEffort;
-    cliVersion: RecordedCodexCliVersion;
+    /** A stable release at or above RECORDED_CODEX_CLI_FLOOR. */
+    cliVersion: string;
     toolPolicy: "restricted-codex-v1" | "codex-ui-tools-v1";
     participantSchema: "humanish.restricted-participant-turn.v1" | "humanish.codex-ui-tool.v1";
     memoryPolicy: "recent-eight-16k-v1" | "continuing-thread-v1";
@@ -193,11 +195,44 @@ export interface ActorRuntimeProvenance {
     observedVersion?: string;
     versionStatus: "unobserved" | "verified" | "failed";
     requestedModel?: string;
-    modelStatus: "declared" | "runtime_default_unobserved";
+    /** Where requestedModel came from. Bundles written before humanish always passed a model record
+     *  `runtime_default_unobserved`, with no requestedModel. */
+    modelStatus: "declared" | "humanish_default" | "runtime_default_unobserved";
     requestedReasoningEffort?: string;
     /** Codex turn.completed aggregates requests; it cannot establish per-request pricing tiers. */
     usageGranularity: "runtime_turn";
 }
+/**
+ * How a provider carried the conversation between its requests. `threaded`: the provider's server
+ * kept it (OpenAI previous_response_id). `explicit_context`: the server kept none (a
+ * zero-data-retention org, or zeroDataRetention set), so each request carried it from the client
+ * within a token budget, with the oldest turns summarized as text once it passed the budget.
+ */
+export interface ActorConversation {
+    /** The mode of the session's last request. */
+    mode: "threaded" | "explicit_context";
+    /** Why the session used explicit_context: configured, or the org rejected server-side state. */
+    explicitReason?: "configured" | "zdr_rejection";
+    /** When a threaded session switched to explicit_context (ISO-8601), and on which request. */
+    switchedAt?: string;
+    switchedAtRequest?: number;
+    /**
+     * Earlier turns the latest explicit_context request no longer carried whole, to stay within the
+     * budget: written as lines of a text note, or only counted once the note reached its cap. Their
+     * screenshots were dropped. 0 when no explicit_context request summarized any.
+     */
+    summarizedTurns: number;
+    /**
+     * Per participant request, in order: its mode and, in explicit_context, what it carried and its
+     * estimated input. `tokenUsage.turns` has each request's billed input.
+     */
+    requests: Array<{
+        mode: "threaded" | "explicit_context";
+        carriedExchanges?: number;
+        carriedScreenshots?: number;
+        estimatedInputTokens?: number;
+    }>;
+}
 export interface ActorTrace {
     schema: typeof ACTOR_TRACE_SCHEMA;
     provider: string;
@@ -205,6 +240,8 @@ export interface ActorTrace {
     executionProfile?: ActorExecutionProfile;
     providerRequests?: ActorProviderRequest[];
     historyTurnsOmitted?: number;
+    /** How the provider carried the conversation; present for the OpenAI computer-use provider. */
+    conversation?: ActorConversation;
     runtime?: ActorRuntimeProvenance;
     protocol: ActorProtocol;
     lane: ActorRunKind;
@@ -229,15 +266,15 @@ export interface ActorTrace {
         model?: string;
     };
     /**
-     * ADDITIVE + OPTIONAL record of HOW the model was asked to run (humanish.model-settings.v1,
-     * #497). `ids.model` says which model; this says the reasoning effort the request actually
-     * carried. Present on lanes whose provider declares settings; absent everywhere else and on
+     * Additive + optional record of how the model was asked to run (humanish.model-settings.v1).
+     * `ids.model` says which model; this says the reasoning effort the request actually
+     * carried. Present on traces whose provider declares settings; absent everywhere else and on
      * every pre-existing bundle, and its absence is tolerated by verify.
      *
      * It exists because effort was a silent constant: unreachable from a lab, so every run took the
-     * provider default. Effort is part of WHO the participant was, not of how the instrument was
+     * provider default. Effort is part of who the participant was, not of how the instrument was
      * tuned (docs/principles/actor-fidelity.md), so a trace that does not carry it is a result with
-     * half its sample description missing — and two such traces cannot honestly be compared.
+     * half its sample description missing, and two such traces cannot be compared.
      */
     modelSettings?: {
         reasoningEffort: string;
@@ -245,29 +282,29 @@ export interface ActorTrace {
     };
     counts: Record<string, number>;
     /**
-     * ADDITIVE + OPTIONAL affordance record (humanish.affordance-use.v1, #369): which KIND of route
-     * this actor took — pointer, keyboard, url-navigation, script-execution, devtools,
-     * browser-internal, observation — as per-class counts over the run's dispatched actions.
-     * Present on computer-use lanes that dispatched at least one action; absent elsewhere and on
+     * Additive + optional affordance record (humanish.affordance-use.v1): which kind of route
+     * this actor took (pointer, keyboard, url-navigation, script-execution, devtools,
+     * browser-internal, observation), as per-class counts over the run's dispatched actions.
+     * Present on computer-use traces that dispatched at least one action; absent elsewhere and on
      * every pre-existing bundle (its absence is tolerated by verify). The harness records the class
-     * and states NO verdict: whether a class is faithful depends on the population the study
+     * and states no verdict: whether a class is faithful depends on the population the study
      * declares, which is product semantics and belongs to the adopter's scorer. See
      * docs/principles/actor-fidelity.md.
      */
     affordanceUse?: AffordanceUse;
     /**
-     * ADDITIVE + OPTIONAL task funnel (humanish.task-funnel.v1, #414): how far this participant got
+     * Additive + optional task funnel (humanish.task-funnel.v1): how far this participant got
      * through the lab's declared protocol, corroborated per task by observations rather than by the
      * actor's own narration. Present only when the lab declared `tasks` and the session ran; absent
-     * on every pre-existing bundle and on dry-run contract bundles (honest absence — a funnel that
+     * on every pre-existing bundle and on dry-run contract bundles (a funnel that
      * was never measured is not an empty funnel). Its absence is tolerated by verify.
      */
     taskFunnel?: TaskFunnel;
     /**
-     * ADDITIVE + OPTIONAL (#570): the outcome the participant declared on its final turn, when its
+     * Additive + optional: the outcome the participant declared on its final turn, when its
      * provider's reply carries the field. Absent on free-text providers and on every older bundle.
-     * The lane reads this before it reads the closing paragraph; three regex patches in one month
-     * (#453, #549, #565) each fixed a false refusal and each left the next shape unhandled.
+     * The route reads this before it reads the closing paragraph; three regex patches in one month
+     * each fixed a false refusal and each left the next shape unhandled.
      */
     declaredOutcome?: ParticipantDeclaredOutcome;
     /** Closing report after a harness-owned stop. Does not change task outcomes or permit actions. */
@@ -287,13 +324,13 @@ export interface ActorTrace {
      *  Known tokenUsage remains usable as a partial total. Absence is not proof of completeness. */
     interactionUsageIncomplete?: true;
     /**
-     * ADDITIVE + OPTIONAL token-derived cost ESTIMATE for this lane (humanish.actor-estimated-cost.v1).
-     * Distinct from `tokenUsage.costUsd`, which is RESERVED for a real provider-returned charge: a
+     * Additive + optional token-derived cost estimate for this trace (humanish.actor-estimated-cost.v1).
+     * Distinct from `tokenUsage.costUsd`, which is reserved for a real provider-returned charge: a
      * bare `costUsd` always means "the provider billed this", while `estimatedCost.estimatedCostUsd`
-     * is a rate-table multiply named honestly as an estimate (invariant 6). Absent on the Codex
-     * app-server and scripted lanes and on every pre-existing bundle; the terminal lane records a
+     * is a rate-table multiply named as an estimate, so the claim matches the mechanism. Absent on the Codex
+     * app-server and scripted traces and on every pre-existing bundle; the terminal trace records a
      * null estimate. Its absence is tolerated by verify (fail-open on display). A `null`
-     * estimatedCostUsd is DECLARED ABSENT (unknown rate / no usage), never 0.
+     * estimatedCostUsd is declared absent (unknown rate / no usage), never 0.
      */
     estimatedCost?: ActorEstimatedCost;
     capabilities: ActorCapabilities;