@agentionai/agents 1.13.0 → 1.15.0

package/dist/agents/openai/OpenAiAgent.js

@@ -107,7 +107,7 @@ function describeOpenAIError(error) {
     const body = err?.error;
     const fromBody = typeof body === "string"
         ? body
-        : (body?.message ?? body?.detail ?? undefined);
+        : body?.message ?? body?.detail ?? undefined;
     return {
         message: fromBody ?? err?.detail ?? err?.message ?? "Unknown error",
         code: typeof body === "object" ? body?.code : undefined,
@@ -171,6 +171,11 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         const reasoningEffort = config.reasoningEffort ?? vendorConfig.reasoningEffort;
         const user = config.user ?? vendorConfig.user;
         const builtInTools = config.builtInTools ?? vendorConfig.builtInTools;
+        const promptCacheKey = config.promptCacheKey ?? vendorConfig.promptCacheKey;
+        const promptCacheRetention = config.promptCacheRetention ?? vendorConfig.promptCacheRetention;
+        const includeEncryptedReasoning = config.includeEncryptedReasoning ??
+            vendorConfig.includeEncryptedReasoning ??
+            this.defaultIncludeEncryptedReasoning(config.model, baseURL);
         this.config = {
             model: config.model || "gpt-4.1-mini",
             // No default. `max_output_tokens` is optional on the Responses API, and
@@ -185,6 +190,9 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             reasoningEffort,
             user,
             builtInTools,
+            promptCacheKey,
+            promptCacheRetention,
+            includeEncryptedReasoning,
             apiKey: config.apiKey,
             baseURL,
             temperature: config.temperature,
@@ -223,7 +231,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
     /** The configured key, resolving the function form if that is what was given. */
     async resolveApiKey() {
         const key = this.config.apiKey;
-        return typeof key === "function" ? await key() : (key ?? "");
+        return typeof key === "function" ? await key() : key ?? "";
     }
     getToolDefinitions() {
         return Array.from(this.tools.values()).map((tool) => {
@@ -278,7 +286,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         const output = streamedItems;
         const outputText = output
             .filter((item) => item.type === "message")
-            .flatMap((item) => ("content" in item ? (item.content ?? []) : []))
+            .flatMap((item) => ("content" in item ? item.content ?? [] : []))
             .filter((part) => part?.type === "output_text")
             .map((part) => ("text" in part ? part.text : ""))
             .join("");
@@ -350,6 +358,95 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             },
         };
     }
+    /**
+     * Whether {@link AgentConfig.includeEncryptedReasoning} defaults to on, when
+     * the caller has not said either way.
+     *
+     * On only for OpenAI's own API *and* a model the reasoning table knows
+     * about. Asking a non-reasoning model for reasoning blobs would add a
+     * parameter it has nothing to put in; asking a third-party host behind a
+     * custom `baseURL` — a gateway, vLLM, llama.cpp — would silently start
+     * sending it a parameter it never received before, which is the opposite of
+     * the byte-identical request this default exists to preserve. A model name
+     * says nothing about the host serving it, so an OpenAI-shaped name on a proxy
+     * must not be enough on its own. Set the flag explicitly for a host that does
+     * support the round trip.
+     *
+     * `CodexAgent` overrides this: it always runs against a custom `baseURL`, and
+     * every model on that backend reasons.
+     *
+     * Called from the base constructor, so an override must depend on nothing but
+     * its arguments: the subclass's own fields are not assigned yet.
+     */
+    defaultIncludeEncryptedReasoning(model, baseURL) {
+        return baseURL === undefined && lowestReasoningEffort(model) !== undefined;
+    }
+    /**
+     * The `include` field, asking for reasoning to come back in a form that can
+     * be replayed on the next request.
+     *
+     * Omitted entirely when off, so requests stay byte-identical to what earlier
+     * versions sent. The other half of this — putting the returned items back
+     * into `input` — is `openAiTransformer`'s, fed by
+     * {@link OpenAiAgent.replayableReasoning}.
+     */
+    buildIncludeParams() {
+        return this.config.includeEncryptedReasoning
+            ? { include: ["reasoning.encrypted_content"] }
+            : {};
+    }
+    /**
+     * The `reasoning` items of a response that are worth keeping.
+     *
+     * Only items carrying `encrypted_content` qualify: the agent always sends
+     * `store: false`, so the provider has retained nothing, and an item replayed
+     * without its payload cannot be resolved — the request fails rather than
+     * silently ignoring it. A summary-only item is therefore dropped, exactly as
+     * it was before this existed.
+     *
+     * A turn that also used a **built-in tool** keeps its reasoning too. Those
+     * items (`web_search_call` and friends) are not stored, so the replayed turn
+     * is `[reasoning, reasoning, message]` where the model emitted
+     * `[reasoning, web_search_call, reasoning, message]`. That was expected to be
+     * rejected — "reasoning item without its required following item" — but it is
+     * not: probed live on 2026-09-10 against `gpt-5-nano` and `gpt-5.4-mini`, the
+     * API accepted that shape, the same reasoning item twice in a row, a
+     * reasoning item followed only by the next *user* turn, and a dangling
+     * reasoning item last in `input` with nothing after it at all. That ordering
+     * rule appears to govern the `store: true` / `previous_response_id` flow, not
+     * this one, which sends `store: false` and an explicit `input`.
+     *
+     * So the reasoning is kept. Dropping it would cost every `builtInTools` user
+     * their prompt-cache continuity to avoid a rejection that does not happen.
+     * Revisit if the API tightens.
+     */
+    replayableReasoning(response) {
+        if (!this.config.includeEncryptedReasoning)
+            return [];
+        return (response.output ?? []).filter((item) => typeof item === "object" &&
+            item !== null &&
+            item.type === "reasoning" &&
+            typeof item.encrypted_content ===
+                "string");
+    }
+    /**
+     * Prompt-caching parameters, omitted entirely when unconfigured so a request
+     * stays byte-identical to what earlier versions sent.
+     *
+     * Caching itself is automatic and needs no opt-in — these only influence
+     * which cache a request is routed to and how long the prefix stays warm. What
+     * was actually reused comes back on `lastTokenUsage.cache_read_tokens`.
+     */
+    buildCacheParams() {
+        return {
+            ...(this.config.promptCacheKey
+                ? { prompt_cache_key: this.config.promptCacheKey }
+                : {}),
+            ...(this.config.promptCacheRetention
+                ? { prompt_cache_retention: this.config.promptCacheRetention }
+                : {}),
+        };
+    }
     async process(_input) {
         return "";
     }
@@ -382,7 +479,9 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         // mid-loop. endExecution() in the finally block enforces limits once.
         this.history.beginExecution();
         try {
-            const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
+            const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries(), {
+                replayReasoning: this.config.includeEncryptedReasoning,
+            });
             this.startTurnTimer();
             const response = await this.createResponse({
                 model: this.config.model,
@@ -395,6 +494,8 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 // Note: Responses API doesn't support seed, presence_penalty, frequency_penalty, stop
                 user: this.config.user,
                 ...this.buildReasoningParams(),
+                ...this.buildCacheParams(),
+                ...this.buildIncludeParams(),
             }, { signal: options?.signal });
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
             return await this.handleResponse(response, options);
@@ -471,7 +572,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             messageOutput.type === "message" &&
             messageOutput.status === "completed") {
             // Normal text response - add to history in normalized format
-            const entry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text);
+            const entry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text, undefined, this.replayableReasoning(response));
             this.addToHistory(entry);
             this.emit(AgentEvent_1.AgentEvent.DONE, response, this.lastTokenUsage);
             // Report completion to viz
@@ -499,7 +600,11 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                     name: tc.name,
                     arguments: tc.arguments,
                 }));
-                const assistantEntry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text || "", functionCalls);
+                const assistantEntry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text || "", functionCalls, 
+                // The thinking that led to these calls: replayed on the follow-up so
+                // the model does not have to re-derive it, and so the prefix the
+                // provider caches still matches what it processed.
+                this.replayableReasoning(response));
                 this.addToHistory(assistantEntry);
                 const toolResponses = await this.handleToolUse(toolCalls, options);
                 // Add tool results to history (normalized)
@@ -509,7 +614,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 }
                 // Continue conversation
                 try {
-                    const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
+                    const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries(), { replayReasoning: this.config.includeEncryptedReasoning });
                     this.startTurnTimer();
                     const newResponse = await this.createResponse({
                         model: this.config.model,
@@ -522,6 +627,8 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                         // Note: Responses API doesn't support seed, presence_penalty, frequency_penalty, stop
                         user: this.config.user,
                         ...this.buildReasoningParams(),
+                        ...this.buildCacheParams(),
+                        ...this.buildIncludeParams(),
                     }, { signal: options?.signal });
                     this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
                     return this.handleResponse(newResponse, options);
@@ -690,9 +797,11 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         }
     }
     async *streamTurn(options) {
-        const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
+        const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries(), {
+            replayReasoning: this.config.includeEncryptedReasoning,
+        });
         this.startTurnTimer();
-        const stream = await this.client.responses.create(this.transformRequestParams({
+        const stream = (await this.client.responses.create(this.transformRequestParams({
             model: this.config.model,
             max_output_tokens: this.config.maxTokens,
             input: inputMessages,
@@ -703,7 +812,9 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             top_p: this.config.topP,
             user: this.config.user,
             ...this.buildReasoningParams("auto"),
-        }), { signal: options?.signal });
+            ...this.buildCacheParams(),
+            ...this.buildIncludeParams(),
+        }), { signal: options?.signal }));
         let completedEvent = null;
         const streamedItems = [];
         // The Responses API builds the committed turn out of `response.completed`,
@@ -784,7 +895,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                     name: tc.name,
                     arguments: tc.arguments,
                 }));
-                const assistantEntry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text || "", functionCalls);
+                const assistantEntry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text || "", functionCalls, this.replayableReasoning(response));
                 this.addToHistory(assistantEntry);
                 committed = true;
                 const toolResults = await this.handleToolUse(toolCalls, options);
@@ -795,7 +906,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             }
             else {
                 const textContent = response.output_text || "";
-                const entry = transformers_1.openAiTransformer.fromProviderMessage("assistant", textContent);
+                const entry = transformers_1.openAiTransformer.fromProviderMessage("assistant", textContent, undefined, this.replayableReasoning(response));
                 this.addToHistory(entry);
                 committed = true;
                 this.emit(AgentEvent_1.AgentEvent.DONE, response, this.lastTokenUsage);
@@ -832,12 +943,16 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         }
     }
     parseUsage(input) {
+        const inputDetails = input.input_tokens_details;
         return {
             input_tokens: input.input_tokens,
             output_tokens: input.output_tokens,
             total_tokens: input.total_tokens,
             // Reasoning tokens are already counted inside `output_tokens`.
             reasoning_tokens: input.output_tokens_details?.reasoning_tokens,
+            // Cache counts are part of `input_tokens`, not extra on top of it.
+            cache_read_tokens: inputDetails?.cached_tokens,
+            cache_write_tokens: inputDetails?.cache_write_tokens,
         };
     }
 }

package/dist/agents/openai/codex-usage.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Quota accounting for the ChatGPT-backed Codex backend.
+ *
+ * A ChatGPT subscription is not billed per request, so nothing on this path
+ * reports a dollar cost — `TokenUsage.cost_usd` stays undefined here, as it
+ * does on every provider that does not price a response itself. What a
+ * subscription spends instead is *plan allowance*, and the backend reports that
+ * on every `/responses` call as a set of `x-codex-*` headers: two rolling
+ * windows (a 5-hour "primary" and a weekly "secondary"), the plan and limit
+ * tier in force, and the pay-as-you-go credit balance that takes over once the
+ * windows are exhausted.
+ *
+ * These headers are the only source: there is no usage endpoint (`/usage`,
+ * `/rate_limits` and `/limits` all answer `403`), and `/models` returns none of
+ * them — so quota state can only be refreshed by making a real call. Values
+ * observed live against `chatgpt.com/backend-api/codex` on 2026-09-10; like the
+ * rest of that surface they are undocumented and may change without notice,
+ * which is why every field here is optional and an unparseable value is dropped
+ * rather than guessed at.
+ */
+/** One rolling usage window, as the backend reports it. */
+export interface CodexRateLimitWindow {
+    /**
+     * Percentage of the window's allowance already consumed, `0`–`100`. Requests
+     * start failing once this reaches 100 and the other window has nothing left
+     * either.
+     */
+    usedPercent: number;
+    /**
+     * Length of the rolling window in minutes — `300` (5 hours) for the primary
+     * window and `10080` (7 days) for the secondary, on the plans seen so far.
+     */
+    windowMinutes?: number;
+    /** Seconds until the window rolls over and the allowance is restored. */
+    resetAfterSeconds?: number;
+    /** Wall-clock time the window rolls over. */
+    resetAt?: Date;
+}
+/** Pay-as-you-go credit balance, used once the plan windows are exhausted. */
+export interface CodexCredits {
+    /** Remaining credits. `0` on an account that has never bought any. */
+    balance?: number;
+    /** Whether any credits are available to spend. */
+    hasCredits?: boolean;
+    /** Whether the account's credits are uncapped. */
+    unlimited?: boolean;
+}
+/**
+ * What one Codex response said about the subscription's remaining allowance —
+ * the closest thing this backend has to a cost figure.
+ */
+export interface CodexUsageLimits {
+    /** Short rolling window; `300` minutes (5 hours) on the plans seen so far. */
+    primary?: CodexRateLimitWindow;
+    /** Long rolling window; `10080` minutes (7 days) on those same plans. */
+    secondary?: CodexRateLimitWindow;
+    /** Subscription tier the request was billed against, e.g. `"plus"`. */
+    planType?: string;
+    /** Limit tier in force for this request, e.g. `"premium"`. */
+    activeLimit?: string;
+    /** Credit balance backing the account once the windows run dry. */
+    credits?: CodexCredits;
+    /**
+     * How far the primary window may run past the secondary window's pace, as a
+     * percentage. `0` where the backend imposes no such allowance.
+     */
+    primaryOverSecondaryLimitPercent?: number;
+    /** When these values were received. */
+    at: Date;
+}
+/**
+ * Read the quota state out of a Codex response's headers.
+ *
+ * @returns the limits, or `undefined` when the response carried none — which is
+ *          every response that is not a `/responses` call, including `/models`
+ *          and anything Cloudflare answered on the backend's behalf.
+ */
+export declare function parseCodexUsageLimits(headers: Headers): CodexUsageLimits | undefined;
+/**
+ * `fetch` wrapper that hands every response's headers to `onHeaders` before
+ * returning it untouched.
+ *
+ * The body is never read here — the SDK still consumes the stream itself — so
+ * this is safe to stack under `wrapErrorBodyFetch`. A throwing observer
+ * is swallowed: quota bookkeeping must never be able to fail a request.
+ */
+export declare function observeHeadersFetch(onHeaders: (headers: Headers) => void, baseFetch?: typeof fetch): typeof fetch;
+//# sourceMappingURL=codex-usage.d.ts.map

package/dist/agents/openai/codex-usage.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Quota accounting for the ChatGPT-backed Codex backend.
+ *
+ * A ChatGPT subscription is not billed per request, so nothing on this path
+ * reports a dollar cost — `TokenUsage.cost_usd` stays undefined here, as it
+ * does on every provider that does not price a response itself. What a
+ * subscription spends instead is *plan allowance*, and the backend reports that
+ * on every `/responses` call as a set of `x-codex-*` headers: two rolling
+ * windows (a 5-hour "primary" and a weekly "secondary"), the plan and limit
+ * tier in force, and the pay-as-you-go credit balance that takes over once the
+ * windows are exhausted.
+ *
+ * These headers are the only source: there is no usage endpoint (`/usage`,
+ * `/rate_limits` and `/limits` all answer `403`), and `/models` returns none of
+ * them — so quota state can only be refreshed by making a real call. Values
+ * observed live against `chatgpt.com/backend-api/codex` on 2026-09-10; like the
+ * rest of that surface they are undocumented and may change without notice,
+ * which is why every field here is optional and an unparseable value is dropped
+ * rather than guessed at.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCodexUsageLimits = parseCodexUsageLimits;
+exports.observeHeadersFetch = observeHeadersFetch;
+/** Parse a header that should hold a number, dropping anything that does not. */
+function num(headers, name) {
+    const raw = headers.get(name);
+    if (raw === null || raw.trim() === "")
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Parse a header holding a boolean. The backend writes these Python-style
+ * (`True` / `False`), so match case-insensitively and accept the JSON spelling
+ * too in case that ever changes.
+ */
+function bool(headers, name) {
+    const raw = headers.get(name)?.trim().toLowerCase();
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    return undefined;
+}
+/** Parse a `-reset-at` header, which carries seconds since the epoch. */
+function resetAt(headers, name) {
+    const seconds = num(headers, name);
+    return seconds === undefined ? undefined : new Date(seconds * 1000);
+}
+/**
+ * Parse one rolling window's headers.
+ *
+ * Returns `undefined` unless `used-percent` is present: without it there is no
+ * window to speak of, only a reset time for one that was never reported.
+ */
+function window(headers, prefix) {
+    const usedPercent = num(headers, `x-codex-${prefix}-used-percent`);
+    if (usedPercent === undefined)
+        return undefined;
+    return {
+        usedPercent,
+        windowMinutes: num(headers, `x-codex-${prefix}-window-minutes`),
+        resetAfterSeconds: num(headers, `x-codex-${prefix}-reset-after-seconds`),
+        resetAt: resetAt(headers, `x-codex-${prefix}-reset-at`),
+    };
+}
+/**
+ * Read the quota state out of a Codex response's headers.
+ *
+ * @returns the limits, or `undefined` when the response carried none — which is
+ *          every response that is not a `/responses` call, including `/models`
+ *          and anything Cloudflare answered on the backend's behalf.
+ */
+function parseCodexUsageLimits(headers) {
+    const primary = window(headers, "primary");
+    const secondary = window(headers, "secondary");
+    const planType = headers.get("x-codex-plan-type") ?? undefined;
+    const activeLimit = headers.get("x-codex-active-limit") ?? undefined;
+    const balance = num(headers, "x-codex-credits-balance");
+    const hasCredits = bool(headers, "x-codex-credits-has-credits");
+    const unlimited = bool(headers, "x-codex-credits-unlimited");
+    const primaryOverSecondaryLimitPercent = num(headers, "x-codex-primary-over-secondary-limit-percent");
+    const credits = balance === undefined && hasCredits === undefined && unlimited === undefined
+        ? undefined
+        : { balance, hasCredits, unlimited };
+    // Nothing recognised: report "no limits seen" rather than a shell of an
+    // object timestamped as if it were an answer.
+    if (!primary &&
+        !secondary &&
+        !planType &&
+        !activeLimit &&
+        !credits &&
+        primaryOverSecondaryLimitPercent === undefined) {
+        return undefined;
+    }
+    return {
+        primary,
+        secondary,
+        planType,
+        activeLimit,
+        credits,
+        primaryOverSecondaryLimitPercent,
+        at: new Date(),
+    };
+}
+/**
+ * `fetch` wrapper that hands every response's headers to `onHeaders` before
+ * returning it untouched.
+ *
+ * The body is never read here — the SDK still consumes the stream itself — so
+ * this is safe to stack under `wrapErrorBodyFetch`. A throwing observer
+ * is swallowed: quota bookkeeping must never be able to fail a request.
+ */
+function observeHeadersFetch(onHeaders, baseFetch = fetch) {
+    return async (input, init) => {
+        const res = await baseFetch(input, init);
+        try {
+            onHeaders(res.headers);
+        }
+        catch {
+            // Ignored on purpose: see above.
+        }
+        return res;
+    };
+}
+//# sourceMappingURL=codex-usage.js.map

package/dist/history/History.d.ts

@@ -3,8 +3,8 @@ import { HistoryEntry, MessageRole, MessageContent } from "./types";
 import type { ReduceOptions } from "./types";
 /** @internal — exposed for test teardown only */
 export declare function resetTokenxCache(): void;
-export type { HistoryEntry, MessageRole, MessageContent, ReduceOptions, ImageMimeType, ImageUrlContent, ImageBase64Content, ThinkingContent, } from "./types";
-export { text, toolUse, toolResult, thinking, textMessage, imageUrl, imageBase64, isTextContent, isToolUseContent, isToolResultContent, isThinkingContent, isImageUrlContent, isImageBase64Content, isImageContent, } from "./types";
+export type { HistoryEntry, MessageRole, MessageContent, ReduceOptions, ImageMimeType, ImageUrlContent, ImageBase64Content, ThinkingContent, ReasoningDetailsFormat, } from "./types";
+export { text, toolUse, toolResult, thinking, textMessage, imageUrl, imageBase64, isTextContent, isToolUseContent, isToolResultContent, isThinkingContent, isImageUrlContent, isImageBase64Content, isImageContent, reasoningDetailsFormatOf, } from "./types";
 /**
  * Metadata stored alongside each history entry.
  * Extended with summary tracking fields for the compression plugin.

package/dist/history/History.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.History = exports.isImageContent = exports.isImageBase64Content = exports.isImageUrlContent = exports.isThinkingContent = exports.isToolResultContent = exports.isToolUseContent = exports.isTextContent = exports.imageBase64 = exports.imageUrl = exports.textMessage = exports.thinking = exports.toolResult = exports.toolUse = exports.text = void 0;
+exports.History = exports.reasoningDetailsFormatOf = exports.isImageContent = exports.isImageBase64Content = exports.isImageUrlContent = exports.isThinkingContent = exports.isToolResultContent = exports.isToolUseContent = exports.isTextContent = exports.imageBase64 = exports.imageUrl = exports.textMessage = exports.thinking = exports.toolResult = exports.toolUse = exports.text = void 0;
 exports.resetTokenxCache = resetTokenxCache;
 const events_1 = __importDefault(require("events"));
 const types_1 = require("./types");
@@ -53,9 +53,22 @@ void Promise.resolve().then(() => __importStar(require("tokenx"))).then((mod) =>
 function resetTokenxCache() {
     _estimateTokenCount = (t) => Math.ceil(t.length / 4);
 }
+/**
+ * Chars per token for an opaque reasoning payload.
+ *
+ * `ThinkingContent.reasoningDetails` holds ciphertext — OpenAI's
+ * `encrypted_content`, OpenRouter's `reasoning.encrypted` — which stands in for
+ * the reasoning tokens the provider decrypts it back into, and is far longer
+ * than the tokens it represents. Running it through the text estimator counted
+ * it at roughly three times its weight, which trimmed history early for no
+ * reason. Measured on a Codex turn: 1892 chars of blob carried 156 reasoning
+ * tokens, i.e. ~12 chars per token against the ~4 a plain string averages.
+ */
+const CHARS_PER_ENCRYPTED_REASONING_TOKEN = 12;
 /**
  * Estimate token count for a content block array.
  * Image blocks use a flat 1000-token estimate (resolution-independent conservative value).
+ * Encrypted reasoning payloads get their own ratio, see above.
  * Text and tool blocks fall through to the tokenx estimator.
  */
 function estimateContentTokens(content) {
@@ -63,6 +76,13 @@ function estimateContentTokens(content) {
         if ((0, types_1.isImageContent)(block)) {
             return sum + 1000;
         }
+        if ((0, types_1.isThinkingContent)(block) && block.reasoningDetails?.length) {
+            const { reasoningDetails, ...rest } = block;
+            return (sum +
+                _estimateTokenCount(JSON.stringify(rest)) +
+                Math.ceil(JSON.stringify(reasoningDetails).length /
+                    CHARS_PER_ENCRYPTED_REASONING_TOKEN));
+        }
         return sum + _estimateTokenCount(JSON.stringify(block));
     }, 0);
 }
@@ -81,6 +101,7 @@ Object.defineProperty(exports, "isThinkingContent", { enumerable: true, get: fun
 Object.defineProperty(exports, "isImageUrlContent", { enumerable: true, get: function () { return types_2.isImageUrlContent; } });
 Object.defineProperty(exports, "isImageBase64Content", { enumerable: true, get: function () { return types_2.isImageBase64Content; } });
 Object.defineProperty(exports, "isImageContent", { enumerable: true, get: function () { return types_2.isImageContent; } });
+Object.defineProperty(exports, "reasoningDetailsFormatOf", { enumerable: true, get: function () { return types_2.reasoningDetailsFormatOf; } });
 /**
  * Manages conversation history in a provider-agnostic format.
  *
@@ -433,7 +454,8 @@ class History extends events_1.default {
     applyTrimming() {
         if (this._executing)
             return;
-        if (this.options.maxLength && this._entries.length > this.options.maxLength) {
+        if (this.options.maxLength &&
+            this._entries.length > this.options.maxLength) {
             this._entries = this._entries.slice(this._entries.length - this.options.maxLength);
             this.sanitizeToolPairs();
         }

package/dist/history/index.d.ts

@@ -1,5 +1,5 @@
 export { History, resetTokenxCache, type EntryMetadata, type ReducibleEntry, type HistoryPlugin, } from "./History";
 export { RedisHistory } from "./RedisHistory";
-export type { HistoryEntry, MessageRole, MessageContent, TextContent, ToolUseContent, ToolResultContent, ThinkingContent, ProviderMeta, ReduceOptions, } from "./types";
-export { text, toolUse, toolResult, thinking, textMessage, isTextContent, isToolUseContent, isToolResultContent, isThinkingContent, } from "./types";
+export type { HistoryEntry, MessageRole, MessageContent, TextContent, ToolUseContent, ToolResultContent, ThinkingContent, ReasoningDetailsFormat, ProviderMeta, ReduceOptions, } from "./types";
+export { text, toolUse, toolResult, thinking, textMessage, isTextContent, isToolUseContent, isToolResultContent, isThinkingContent, reasoningDetailsFormatOf, } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/history/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isThinkingContent = exports.isToolResultContent = exports.isToolUseContent = exports.isTextContent = exports.textMessage = exports.thinking = exports.toolResult = exports.toolUse = exports.text = exports.RedisHistory = exports.resetTokenxCache = exports.History = void 0;
+exports.reasoningDetailsFormatOf = exports.isThinkingContent = exports.isToolResultContent = exports.isToolUseContent = exports.isTextContent = exports.textMessage = exports.thinking = exports.toolResult = exports.toolUse = exports.text = exports.RedisHistory = exports.resetTokenxCache = exports.History = void 0;
 var History_1 = require("./History");
 Object.defineProperty(exports, "History", { enumerable: true, get: function () { return History_1.History; } });
 Object.defineProperty(exports, "resetTokenxCache", { enumerable: true, get: function () { return History_1.resetTokenxCache; } });
@@ -16,4 +16,5 @@ Object.defineProperty(exports, "isTextContent", { enumerable: true, get: functio
 Object.defineProperty(exports, "isToolUseContent", { enumerable: true, get: function () { return types_1.isToolUseContent; } });
 Object.defineProperty(exports, "isToolResultContent", { enumerable: true, get: function () { return types_1.isToolResultContent; } });
 Object.defineProperty(exports, "isThinkingContent", { enumerable: true, get: function () { return types_1.isThinkingContent; } });
+Object.defineProperty(exports, "reasoningDetailsFormatOf", { enumerable: true, get: function () { return types_1.reasoningDetailsFormatOf; } });
 //# sourceMappingURL=index.js.map

package/dist/history/transformers.d.ts

@@ -23,9 +23,18 @@ export declare const anthropicTransformer: {
 };
 export declare const openAiTransformer: {
     /**
-     * Convert normalized entries to OpenAI ResponseInputItem format
+     * Convert normalized entries to OpenAI ResponseInputItem format.
+     *
+     * `replayReasoning` defaults to on and mirrors
+     * `AgentConfig.includeEncryptedReasoning`: requesting the blobs and sending
+     * them back are one feature, so switching it off has to stop *both*.
+     * Otherwise a history that already holds blobs keeps replaying them — which
+     * is exactly the situation the flag is turned off to escape, since reasoning
+     * is tied to the model that produced it and switching models is rejected.
      */
-    toProvider(entries: HistoryEntry[]): ResponseInputItem[];
+    toProvider(entries: HistoryEntry[], options?: {
+        replayReasoning?: boolean;
+    }): ResponseInputItem[];
     /**
      * Convert OpenAI response to normalized HistoryEntry
      */
@@ -34,7 +43,7 @@ export declare const openAiTransformer: {
         call_id: string;
         name: string;
         arguments: string;
-    }>): HistoryEntry;
+    }>, reasoningItems?: unknown[]): HistoryEntry;
     /**
      * Create a tool result entry from OpenAI function call output
      */