@agentionai/agents 1.14.0 → 1.15.0

package/dist/agents/AgentConfig.d.ts

@@ -144,10 +144,31 @@ export interface OpenAISpecificConfig {
      */
     promptCacheKey?: string;
     /**
-     * How long cached prefixes stay warm — `"24h"` opts into extended retention.
+     * How long cached prefixes stay warm — `"in_memory"` expires them within
+     * minutes, `"24h"` keeps them up to a day. Left unset the default follows
+     * your organization's data-retention policy (`"24h"` without ZDR,
+     * `"in_memory"` with it), so set it explicitly if you care either way.
      * Ignored by the ChatGPT/Codex backend, which manages its own cache.
      */
-    promptCacheRetention?: "in-memory" | "24h";
+    promptCacheRetention?: "in_memory" | "24h";
+    /**
+     * Request each turn's reasoning as an encrypted blob and replay it on every
+     * later request of the conversation, so a reasoning model keeps its own
+     * thinking across tool hops and turns instead of re-deriving it.
+     *
+     * Setting it to `false` stops both halves — nothing is requested, and blobs
+     * already in the history are not sent either, which is what makes it a way
+     * out of the model-switch rejection below.
+     *
+     * Defaults to on for models known to reason on OpenAI's own API, off
+     * otherwise — including behind a custom `baseURL`, where the host may not
+     * support the parameter. `CodexAgent` defaults it to on for every model.
+     *
+     * Reasoning blobs are tied to the model that produced them: switching models
+     * mid-conversation with a history full of them is rejected. Clear the history
+     * or turn this off when doing that.
+     */
+    includeEncryptedReasoning?: boolean;
     /**
      * Override the API base URL. Defaults to `api.openai.com/v1`; `CodexAgent`
      * defaults it to `https://chatgpt.com/backend-api/codex`, and setting it
@@ -159,6 +180,14 @@ export interface OpenAISpecificConfig {
      * `chatgpt-account-id` header.
      */
     accountId?: string;
+    /**
+     * `CodexAgent` only: conversation id sent as the `session_id` header, which
+     * is what routes requests to a shared prompt cache on that backend — setting
+     * it is how you opt into caching there. Unset by default, so the header is
+     * omitted and the request stays byte-identical; `randomUUID()` per agent
+     * gives a per-run cache, a stable id shares one across runs.
+     */
+    sessionId?: string;
     /**
      * `CodexAgent` only: client identifier sent as the `originator` header.
      * OpenAI varies the model catalog by originator.

package/dist/agents/openai/CodexAgent.d.ts

@@ -49,7 +49,57 @@ export type CodexAgentConfig = Omit<OpenAiAgentConfig, "model" | "reasoningEffor
      * @default CODEX_CLIENT_VERSION
      */
     clientVersion?: string;
+    /**
+     * Conversation identifier sent as the `session_id` header, as the Codex CLI
+     * does — **this is what makes prompt caching work on this backend**, and
+     * setting it is how you opt into that caching.
+     *
+     * Requests carrying the same value are routed together and reuse each other's
+     * cached prefix; without it the backend caches essentially nothing, however
+     * identical the prefix. Measured on 2026-09-10 with a ~9K-token prefix
+     * repeated 8 times: 0/14 calls hit the cache with no header, 12/14 hit
+     * (~98% of the prefix) with one. `prompt_cache_key`, the platform API's
+     * lever, makes no difference here.
+     *
+     * **Unset by default**, so the header is omitted entirely and a request stays
+     * byte-identical to what earlier versions sent — the same opt-in rule as
+     * {@link AgentConfig.promptCacheKey} and
+     * {@link AgentConfig.promptCacheRetention}. Caching is not free of side
+     * effects: it groups your requests server-side under an id you chose, so it
+     * is yours to turn on rather than the agent's to assume.
+     *
+     * Any stable string works; the value is opaque and only its stability
+     * matters. One id per conversation is the usual grain — `randomUUID()` per
+     * agent instance reproduces the old default:
+     *
+     * ```typescript
+     * new CodexAgent({ …, sessionId: randomUUID() })      // cache within this run
+     * new CodexAgent({ …, sessionId: conversationId })    // cache across runs
+     * ```
+     *
+     * Note it is a *header*: `session_id` in the request body is rejected with
+     * *"Unsupported parameter: session_id"*.
+     */
+    sessionId?: string;
+};
+/**
+ * Configuration a factory hands to the constructor, before the credentials it
+ * resolves are merged in.
+ */
+type CodexFactoryConfig = Omit<CodexAgentConfig, "apiKey" | "accountId"> & {
+    tokenOptions?: CodexTokenProviderOptions;
 };
+/**
+ * What a static factory needs of the class it was called on: a constructor for
+ * the concrete subclass — which is where `T` is inferred from — intersected
+ * with the sibling factory it delegates to, so an override of that runs too.
+ *
+ * `Pick<typeof CodexAgent, …>` rather than a hand-written signature: the
+ * sibling's own `this` parameter is what carries `T` through the delegation,
+ * and restating it here would erase that and pin every subclass back to the
+ * base type.
+ */
+type CodexAgentClass<T extends CodexAgent> = (new (config: CodexAgentConfig, history?: History) => T) & Pick<typeof CodexAgent, "fromCredentials">;
 /**
  * Agent for OpenAI models reached through a **ChatGPT subscription** rather
  * than a platform API key.
@@ -88,6 +138,15 @@ export declare class CodexAgent extends OpenAiAgent<OpenAIModel, CodexModelCard>
     private readonly originator;
     private readonly clientVersion;
     private readonly codexBaseURL;
+    /**
+     * The `session_id` this agent sends on every request, or `undefined` when the
+     * header is not being sent — the key the backend's prompt cache is routed by.
+     *
+     * `undefined` means prompt caching is effectively off for this agent; set
+     * {@link CodexSpecificConfig.sessionId} to opt in. Read it back to pin a
+     * later agent to the same cache.
+     */
+    readonly sessionId?: string;
     /**
      * Quota state written by the fetch wrapper installed in the constructor.
      *
@@ -126,18 +185,30 @@ export declare class CodexAgent extends OpenAiAgent<OpenAIModel, CodexModelCard>
      * Build an agent from the credentials `codex login` stored, wrapped in a
      * provider that refreshes the access token as it ages out.
      *
+     * Constructs `this`, so `MyCodexAgent.fromCodexCli(…)` returns a
+     * `MyCodexAgent` — see {@link CodexAgent.fromCredentials}.
+     *
      * @throws if no credentials are present — run `codex login` first.
      */
-    static fromCodexCli(config: Omit<CodexAgentConfig, "apiKey" | "accountId"> & {
+    static fromCodexCli<T extends CodexAgent>(this: CodexAgentClass<T>, config: CodexFactoryConfig & {
         /** Read `auth.json` from somewhere other than `$CODEX_HOME`. */
         codexHome?: string;
-        /** Forwarded to {@link createCodexTokenProvider}. */
-        tokenOptions?: CodexTokenProviderOptions;
-    }, history?: History): Promise<CodexAgent>;
-    /** Build an agent from credentials obtained however you like. */
-    static fromCredentials(credentials: CodexCredentials, config: Omit<CodexAgentConfig, "apiKey" | "accountId"> & {
-        tokenOptions?: CodexTokenProviderOptions;
-    }, history?: History): CodexAgent;
+    }, history?: History): Promise<T>;
+    /**
+     * Build an agent from credentials obtained however you like.
+     *
+     * Instantiates `this` rather than `CodexAgent`, so a subclass gets its own
+     * type back and its overrides actually run. Hard-coding the class here made
+     * `class MyCodexAgent extends CodexAgent` silently produce a plain
+     * `CodexAgent` — no error, no override, and nothing to see until an
+     * experiment came back saying the change under test had no effect.
+     */
+    static fromCredentials<T extends CodexAgent>(this: new (config: CodexAgentConfig, history?: History) => T, credentials: CodexCredentials, config: CodexFactoryConfig, history?: History): T;
+    /**
+     * Every model on this backend reasons, and this is what the Codex CLI itself
+     * does, so the encrypted-reasoning round trip is on unless turned off.
+     */
+    protected defaultIncludeEncryptedReasoning(): boolean;
     /** This backend refuses `stream: false` outright. */
     protected get forceStreaming(): boolean;
     /**
@@ -166,4 +237,5 @@ export declare class CodexAgent extends OpenAiAgent<OpenAIModel, CodexModelCard>
      */
     listModels(): Promise<ModelInfo<CodexModelCard>[]>;
 }
+export {};
 //# sourceMappingURL=CodexAgent.d.ts.map

package/dist/agents/openai/CodexAgent.js

@@ -45,6 +45,9 @@ class CodexAgent extends OpenAiAgent_1.OpenAiAgent {
         const accountId = config.accountId ?? vendorConfig.accountId;
         const originator = config.originator ?? vendorConfig.originator ?? codex_auth_1.CODEX_ORIGINATOR;
         const baseURL = config.baseURL ?? vendorConfig.baseURL ?? codex_auth_1.CODEX_BASE_URL;
+        // No generated fallback: caching is opt-in, so an unset id means the header
+        // is not sent at all.
+        const sessionId = config.sessionId ?? vendorConfig.sessionId;
         // Filled by the fetch wrapper below and adopted as `this.limits` once
         // `super()` has run.
         const limits = {};
@@ -60,6 +63,11 @@ class CodexAgent extends OpenAiAgent_1.OpenAiAgent {
                 ...(accountId ? { "chatgpt-account-id": accountId } : {}),
                 "OpenAI-Beta": "responses=experimental",
                 originator,
+                // Opt-in. Stable for the life of the agent: the backend keys its
+                // prompt cache on this, and drops to ~0% hit rate without it. Omitted
+                // entirely when unset, so the request is byte-identical to one sent
+                // before this existed.
+                ...(sessionId ? { session_id: sessionId } : {}),
                 // Every Codex request is a stream; the SDK would send
                 // `application/json`, which no reference client does.
                 Accept: "text/event-stream",
@@ -86,8 +94,11 @@ class CodexAgent extends OpenAiAgent_1.OpenAiAgent {
         this.accountId = accountId;
         this.originator = originator;
         this.clientVersion =
-            config.clientVersion ?? vendorConfig.clientVersion ?? codex_auth_1.CODEX_CLIENT_VERSION;
+            config.clientVersion ??
+                vendorConfig.clientVersion ??
+                codex_auth_1.CODEX_CLIENT_VERSION;
         this.codexBaseURL = baseURL;
+        this.sessionId = sessionId;
     }
     /**
      * What the most recent response said about the subscription's remaining
@@ -119,16 +130,29 @@ class CodexAgent extends OpenAiAgent_1.OpenAiAgent {
      * Build an agent from the credentials `codex login` stored, wrapped in a
      * provider that refreshes the access token as it ages out.
      *
+     * Constructs `this`, so `MyCodexAgent.fromCodexCli(…)` returns a
+     * `MyCodexAgent` — see {@link CodexAgent.fromCredentials}.
+     *
      * @throws if no credentials are present — run `codex login` first.
      */
     static async fromCodexCli(config, history) {
         const credentials = await (0, codex_auth_1.loadCodexCredentials)(config.codexHome);
-        return CodexAgent.fromCredentials(credentials, config, history);
+        // `this`, not `CodexAgent`: routed through the subclass so an override of
+        // `fromCredentials` is not skipped either.
+        return this.fromCredentials(credentials, config, history);
     }
-    /** Build an agent from credentials obtained however you like. */
+    /**
+     * Build an agent from credentials obtained however you like.
+     *
+     * Instantiates `this` rather than `CodexAgent`, so a subclass gets its own
+     * type back and its overrides actually run. Hard-coding the class here made
+     * `class MyCodexAgent extends CodexAgent` silently produce a plain
+     * `CodexAgent` — no error, no override, and nothing to see until an
+     * experiment came back saying the change under test had no effect.
+     */
     static fromCredentials(credentials, config, history) {
         const tokens = (0, codex_auth_1.createCodexTokenProvider)(credentials, config.tokenOptions);
-        return new CodexAgent({
+        return new this({
             ...config,
             // The function form: the SDK re-invokes it before every request, so a
             // long run outlives the ~1h token.
@@ -136,6 +160,13 @@ class CodexAgent extends OpenAiAgent_1.OpenAiAgent {
             accountId: credentials.accountId,
         }, history);
     }
+    /**
+     * Every model on this backend reasons, and this is what the Codex CLI itself
+     * does, so the encrypted-reasoning round trip is on unless turned off.
+     */
+    defaultIncludeEncryptedReasoning() {
+        return true;
+    }
     /** This backend refuses `stream: false` outright. */
     get forceStreaming() {
         return true;

package/dist/agents/openai/OpenAiAgent.d.ts

@@ -59,13 +59,56 @@ export type AgentConfig<M extends OpenAIModel = OpenAIModel> = Omit<BaseAgentCon
      */
     promptCacheKey?: string;
     /**
-     * How long cached prefixes stay warm. `"24h"` opts into extended retention;
-     * the default (`undefined`, i.e. the API's `in-memory`) expires a prefix
-     * within minutes.
+     * Ask for each turn's reasoning to come back as an encrypted, replayable
+     * blob (`include: ["reasoning.encrypted_content"]`), and send those blobs
+     * back on every later request of the conversation.
+     *
+     * Both halves matter, and both happen here: requesting the blobs without
+     * replaying them changes nothing, and replaying is only possible because the
+     * agent runs with `store: false`, which leaves the provider holding no
+     * reasoning of its own.
+     *
+     * Why it is worth the bytes on a reasoning model: the model's own thinking is
+     * part of what it saw when it decided to call a tool, so dropping it between
+     * hops makes the model re-derive it — and, because the replayed prefix no
+     * longer matches what was processed last turn, breaks the prompt cache from
+     * the first turn onward.
+     *
+     * Setting it to `false` stops both halves too: nothing is requested, and
+     * blobs already sitting in the history are not replayed either. That is what
+     * makes turning it off a way out of the model-switch rejection below, rather
+     * than a half-measure that keeps sending the old model's reasoning.
+     *
+     * Defaults to on for models known to reason (see
+     * {@link OPENAI_REASONING_SUPPORT}) *on OpenAI's own API*, and off otherwise
+     * — including behind a custom `baseURL`, since a model name says nothing
+     * about whether the host serving it accepts the parameter. So a non-reasoning
+     * model such as `gpt-4.1-mini`, and any gateway or local server, sends a
+     * byte-identical request. Set it explicitly for a model too new to be in that
+     * table, or for a compatible host.
+     *
+     * Reasoning blobs are tied to the model that produced them: switching models
+     * mid-conversation with a history full of them is rejected. Clear the history
+     * or turn this off when doing that.
+     */
+    includeEncryptedReasoning?: boolean;
+    /**
+     * How long cached prefixes stay warm. `"in_memory"` expires a prefix after
+     * minutes of inactivity (an hour at the outside); `"24h"` keeps it up to a
+     * day.
+     *
+     * Left unset, the default is your organization's data-retention policy, not
+     * a fixed value: orgs *without* ZDR default to `"24h"`, orgs *with* ZDR to
+     * `"in_memory"`. Set it explicitly to stop prefixes being retained for a day
+     * without having to enable ZDR account-wide.
+     *
+     * `gpt-5.5` and later accept only `"24h"` here, and the field is deprecated
+     * upstream in favour of `prompt_cache_options.ttl` — the two are independent
+     * (this is a *maximum* retention policy, `ttl` a *minimum* lifetime).
      *
      * Ignored by the ChatGPT/Codex backend, which manages its own cache.
      */
-    promptCacheRetention?: "in-memory" | "24h";
+    promptCacheRetention?: "in_memory" | "24h";
 };
 /**
  * Lowest `reasoning.effort` the given model accepts, used to resolve
@@ -86,16 +129,19 @@ export declare function lowestReasoningEffort(model: string | undefined): Reason
 /**
  * `usage.input_tokens_details` as the wire actually carries it.
  *
- * The SDK's `ResponseUsage.InputTokensDetails` declares `cached_tokens` alone,
- * but the ChatGPT/Codex backend also reports `cache_write_tokens` (observed
- * live on 2026-09-10). Declared here rather than cast at the use site, and
- * every field optional because a non-OpenAI host behind this SDK may report
- * neither.
+ * The SDK declares both counts on `ResponseUsage.InputTokensDetails` as of
+ * `openai` 7.x (6.x had `cached_tokens` alone, though the ChatGPT/Codex backend
+ * already reported `cache_write_tokens` — observed live on 2026-09-10). What it
+ * gets wrong for our purposes is that it types them as *required*: a
+ * non-OpenAI host behind this SDK — llama.cpp, vLLM, a gateway — may report
+ * one, the other, or neither. Restating them as optional keeps `parseUsage`
+ * from trusting a number that isn't there, and keeps `undefined` ("provider
+ * said nothing") distinct from `0` ("nothing was cached").
  */
 export type OpenAIInputTokensDetails = {
     /** Prompt tokens served from cache. */
     cached_tokens?: number;
-    /** Prompt tokens written to cache. Codex backend only. */
+    /** Prompt tokens written to cache. On `gpt-5.6`+ these bill at 1.25x input. */
     cache_write_tokens?: number;
 };
 /**
@@ -230,6 +276,63 @@ export declare class OpenAiAgent<M extends OpenAIModel = OpenAIModel, TModelCard
      * emits `response.reasoning_summary_text.delta` events when it is set.
      */
     private buildReasoningParams;
+    /**
+     * 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.
+     */
+    protected defaultIncludeEncryptedReasoning(model: string | undefined, baseURL: string | undefined): boolean;
+    /**
+     * 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}.
+     */
+    private buildIncludeParams;
+    /**
+     * 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.
+     */
+    protected replayableReasoning(response: Response): unknown[];
     /**
      * Prompt-caching parameters, omitted entirely when unconfigured so a request
      * stays byte-identical to what earlier versions sent.

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,
@@ -173,6 +173,9 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         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
@@ -189,6 +192,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             builtInTools,
             promptCacheKey,
             promptCacheRetention,
+            includeEncryptedReasoning,
             apiKey: config.apiKey,
             baseURL,
             temperature: config.temperature,
@@ -227,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) => {
@@ -282,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("");
@@ -354,6 +358,77 @@ 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.
@@ -404,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,
@@ -418,6 +495,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 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);
@@ -494,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
@@ -522,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)
@@ -532,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,
@@ -546,6 +628,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                         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);
@@ -714,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,
@@ -728,7 +813,8 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             user: this.config.user,
             ...this.buildReasoningParams("auto"),
             ...this.buildCacheParams(),
-        }), { signal: options?.signal });
+            ...this.buildIncludeParams(),
+        }), { signal: options?.signal }));
         let completedEvent = null;
         const streamedItems = [];
         // The Responses API builds the committed turn out of `response.completed`,
@@ -809,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);
@@ -820,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);

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

package/dist/history/transformers.js

@@ -10,17 +10,33 @@ const types_1 = require("./types");
 // =============================================================================
 // Anthropic Transformer
 // =============================================================================
+/**
+ * Whether a thinking block is one Anthropic itself produced, and so can be sent
+ * back to it.
+ *
+ * Anthropic signs every thinking block it emits (or returns it redacted), and
+ * rejects one whose signature does not verify — an empty string included. Other
+ * providers' reasoning reaches this transformer whenever a `History` is shared
+ * between agents, which the docs recommend: OpenAI's carries a summary and an
+ * encrypted payload but no signature, so it has to be dropped rather than
+ * replayed under an empty one.
+ */
+function isAnthropicThinkingBlock(block) {
+    return block.redactedData !== undefined || block.signature !== undefined;
+}
 exports.anthropicTransformer = {
     /**
      * Convert normalized entries to Anthropic MessageParam format
      */
     toProvider(entries) {
-        return entries
+        return (entries
             .filter((entry) => entry.role !== "system") // Anthropic handles system separately
             .map((entry) => {
             const role = entry.role === "assistant" ? "assistant" : "user";
             // Convert content blocks to Anthropic's ContentBlockParam
-            const content = entry.content.map((block) => {
+            const content = entry.content
+                .filter((block) => !(0, types_1.isThinkingContent)(block) || isAnthropicThinkingBlock(block))
+                .map((block) => {
                 if ((0, types_1.isTextContent)(block)) {
                     return { type: "text", text: block.text };
                 }
@@ -72,7 +88,12 @@ exports.anthropicTransformer = {
                 throw new Error(`Unknown content type: ${block.type}`);
             });
             return { role, content };
-        });
+        })
+            // Dropping a foreign thinking block can empty a turn that held nothing
+            // else (a reasoning-only assistant entry). Anthropic rejects a message
+            // with no content, and there is nothing left to say, so drop the message
+            // too. Tool pairs are unaffected: a thinking-only entry has no tool_use.
+            .filter((message) => message.content.length > 0));
     },
     /**
      * Convert Anthropic response content to normalized HistoryEntry
@@ -139,12 +160,48 @@ function toOpenAiId(originalId) {
     idMappingToOpenAi.set(originalId, newId);
     return newId;
 }
+function isOpenAiReasoningItem(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.type === "reasoning");
+}
+/**
+ * The reasoning items stored on an assistant entry, in the order they were
+ * received.
+ *
+ * They ride on `ThinkingContent.reasoningDetails` — the same passthrough slot
+ * OpenRouter's `reasoning_details` uses — because they have to survive the round
+ * trip untouched and there is nothing to model.
+ */
+function openAiReasoningItems(entry) {
+    return entry.content
+        .filter(types_1.isThinkingContent)
+        .filter((block) => (0, types_1.reasoningDetailsFormatOf)(block) === "openai.responses")
+        .flatMap((block) => block.reasoningDetails ?? [])
+        .filter(isOpenAiReasoningItem);
+}
+/** Human-readable text of a reasoning item's summary, for display in history. */
+function reasoningSummaryText(items) {
+    return items
+        .flatMap((item) => item.summary ?? [])
+        .map((part) => part?.text ?? "")
+        .filter(Boolean)
+        .join("\n\n");
+}
 exports.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) {
+    toProvider(entries, options) {
         const items = [];
+        const replayReasoning = options?.replayReasoning ?? true;
         for (const entry of entries) {
             if (entry.role === "system") {
                 items.push({
@@ -157,6 +214,18 @@ exports.openAiTransformer = {
                 });
                 continue;
             }
+            // Reasoning first, before anything else this turn produced — the order
+            // the model emitted it in. The Responses API turns out not to enforce
+            // this on the `store: false` + explicit-`input` flow these agents use
+            // (probed live 2026-09-10; see `OpenAiAgent.replayableReasoning` for what
+            // was accepted), so this is fidelity to what the model produced rather
+            // than a constraint. Emitting it out of order is not known to fail, but
+            // there is no reason to.
+            if (replayReasoning) {
+                for (const item of openAiReasoningItems(entry)) {
+                    items.push(item);
+                }
+            }
             // Separate content blocks by type for OpenAI format
             const textBlocks = entry.content.filter(types_1.isTextContent);
             const toolUseBlocks = entry.content.filter(types_1.isToolUseContent);
@@ -238,8 +307,21 @@ exports.openAiTransformer = {
     /**
      * Convert OpenAI response to normalized HistoryEntry
      */
-    fromProviderMessage(role, outputText, functionCalls) {
+    fromProviderMessage(role, outputText, functionCalls, 
+    /**
+     * `reasoning` items from `response.output`, stored verbatim so the next
+     * request can replay them. Pass only items that carry `encrypted_content`:
+     * with `store: false` the provider has kept nothing of its own, so a
+     * replayed item without it cannot be resolved and the request is rejected.
+     */
+    reasoningItems) {
         const content = [];
+        const reasoning = (reasoningItems ?? []).filter(isOpenAiReasoningItem);
+        if (reasoning.length > 0) {
+            // Summary text is for humans reading the history; the payload that
+            // matters is the untouched items on `reasoningDetails`.
+            content.push((0, types_1.thinking)(reasoningSummaryText(reasoning), undefined, undefined, reasoning, "openai.responses"));
+        }
         if (outputText) {
             content.push((0, types_1.text)(outputText));
         }
@@ -553,7 +635,10 @@ exports.ollamaTransformer = {
             const toolUseBlocks = entry.content.filter(types_1.isToolUseContent);
             const toolResultBlocks = entry.content.filter(types_1.isToolResultContent);
             if (entry.role === "system") {
-                messages.push({ role: "system", content: textBlocks.map((c) => c.text).join("\n") });
+                messages.push({
+                    role: "system",
+                    content: textBlocks.map((c) => c.text).join("\n"),
+                });
                 continue;
             }
             if (entry.role === "assistant") {
@@ -579,7 +664,10 @@ exports.ollamaTransformer = {
                 }
             }
             else if (textBlocks.length > 0) {
-                messages.push({ role: "user", content: textBlocks.map((c) => c.text).join("\n") });
+                messages.push({
+                    role: "user",
+                    content: textBlocks.map((c) => c.text).join("\n"),
+                });
             }
         }
         return messages;
@@ -650,7 +738,10 @@ exports.chatCompletionsTransformer = {
             const imageBase64Blocks = entry.content.filter(types_1.isImageBase64Content);
             const hasImages = imageUrlBlocks.length > 0 || imageBase64Blocks.length > 0;
             if (entry.role === "system") {
-                messages.push({ role: "system", content: textBlocks.map((c) => c.text).join("\n") });
+                messages.push({
+                    role: "system",
+                    content: textBlocks.map((c) => c.text).join("\n"),
+                });
                 continue;
             }
             if (entry.role === "assistant") {
@@ -720,7 +811,10 @@ exports.chatCompletionsTransformer = {
                 messages.push({ role: "user", content: parts });
             }
             else if (textBlocks.length > 0) {
-                messages.push({ role: "user", content: textBlocks.map((c) => c.text).join("\n") });
+                messages.push({
+                    role: "user",
+                    content: textBlocks.map((c) => c.text).join("\n"),
+                });
             }
         }
         return messages;
@@ -807,7 +901,11 @@ function markLatestCacheBreakpoint(messages) {
         const message = messages[i];
         if (typeof message.content === "string" && message.content.length > 0) {
             message.content = [
-                { type: "text", text: message.content, cacheControl: { type: "ephemeral" } },
+                {
+                    type: "text",
+                    text: message.content,
+                    cacheControl: { type: "ephemeral" },
+                },
             ];
             return;
         }
@@ -861,7 +959,15 @@ exports.openRouterTransformer = {
                 // and Anthropic and OpenAI models reject a tool-using turn whose
                 // signature did not come back. Only set the key when there is one, so
                 // requests for non-reasoning models stay byte-identical.
-                const reasoningDetails = thinkingBlocks.flatMap((block) => block.reasoningDetails ?? []);
+                // Only OpenRouter's own blocks. A history shared with an OpenAI agent
+                // also carries Responses-API `reasoning` items in this slot, and they
+                // are not OpenRouter's to interpret — it returned 200 rather than an
+                // error when one was sent (probed live 2026-09-10, upstream
+                // `anthropic/claude-sonnet-4.5`), but forwarding another provider's
+                // opaque payload can only confuse the model or the upstream route.
+                const reasoningDetails = thinkingBlocks
+                    .filter((block) => (0, types_1.reasoningDetailsFormatOf)(block) === "openrouter")
+                    .flatMap((block) => block.reasoningDetails ?? []);
                 if (reasoningDetails.length > 0) {
                     msg.reasoningDetails = reasoningDetails;
                 }
@@ -934,7 +1040,7 @@ exports.openRouterTransformer = {
         const reasoningText = typeof message.reasoning === "string" ? message.reasoning : "";
         const reasoningDetails = message.reasoningDetails ?? [];
         if (reasoningText || reasoningDetails.length > 0) {
-            content.push((0, types_1.thinking)(reasoningText, undefined, undefined, reasoningDetails));
+            content.push((0, types_1.thinking)(reasoningText, undefined, undefined, reasoningDetails, "openrouter"));
         }
         if (typeof message.content === "string" && message.content) {
             content.push((0, types_1.text)(message.content));

package/dist/history/types.d.ts

@@ -62,9 +62,32 @@ export type ThinkingContent = {
      *
      * Nothing here reads the contents; they only have to survive the round trip,
      * so they stay untyped rather than modelling every provider's block shapes.
+     *
+     * The shapes are *not* interchangeable — see
+     * {@link ThinkingContent.reasoningDetailsFormat}.
      */
     reasoningDetails?: unknown[];
+    /**
+     * Which provider's format {@link ThinkingContent.reasoningDetails} is in.
+     *
+     * Two producers share that slot and their shapes are mutually invalid:
+     * OpenRouter's entries are tagged `reasoning.text` / `reasoning.summary` /
+     * `reasoning.encrypted`, while the OpenAI Responses API's are whole
+     * `reasoning` items. A history shared between agents therefore has to say
+     * which is which, or each transformer forwards the other's blocks and the
+     * provider rejects the request.
+     *
+     * Absent on blocks written before this field existed, which are OpenRouter's
+     * by definition — it was the only producer then. Read it through
+     * {@link reasoningDetailsFormatOf} rather than directly, so that default
+     * stays in one place.
+     */
+    reasoningDetailsFormat?: ReasoningDetailsFormat;
 };
+/**
+ * Provider formats that {@link ThinkingContent.reasoningDetails} can hold.
+ */
+export type ReasoningDetailsFormat = "openrouter" | "openai.responses";
 /**
  * Supported image MIME types across all providers
  */
@@ -207,7 +230,14 @@ export declare function toolUse(id: string, name: string, input: Record<string,
 /**
  * Create a thinking content block. Pass `redactedData` for redacted thinking.
  */
-export declare function thinking(thinkingText: string, signature?: string, redactedData?: string, reasoningDetails?: unknown[]): ThinkingContent;
+export declare function thinking(thinkingText: string, signature?: string, redactedData?: string, reasoningDetails?: unknown[], reasoningDetailsFormat?: ReasoningDetailsFormat): ThinkingContent;
+/**
+ * The format of a block's {@link ThinkingContent.reasoningDetails}.
+ *
+ * Untagged blocks are OpenRouter's: it was the only producer before the tag
+ * existed, so that is what an untagged block can only have come from.
+ */
+export declare function reasoningDetailsFormatOf(block: ThinkingContent): ReasoningDetailsFormat;
 /**
  * Create a tool result content block
  */

package/dist/history/types.js

@@ -16,6 +16,7 @@ exports.isImageContent = isImageContent;
 exports.text = text;
 exports.toolUse = toolUse;
 exports.thinking = thinking;
+exports.reasoningDetailsFormatOf = reasoningDetailsFormatOf;
 exports.toolResult = toolResult;
 exports.textMessage = textMessage;
 exports.imageUrl = imageUrl;
@@ -70,20 +71,29 @@ function toolUse(id, name, input, thoughtSignature) {
 /**
  * Create a thinking content block. Pass `redactedData` for redacted thinking.
  */
-function thinking(thinkingText, signature, redactedData, reasoningDetails) {
+function thinking(thinkingText, signature, redactedData, reasoningDetails, reasoningDetailsFormat = "openrouter") {
     // As in `toolUse()`, only set the passthrough key when there is something in
     // it, so a block stored without details serializes exactly as it did before
-    // the field existed.
+    // the field existed. The format tag rides along with the details for the same
+    // reason: it says nothing on its own.
+    const hasDetails = reasoningDetails !== undefined && reasoningDetails.length > 0;
     return {
         type: "thinking",
         thinking: thinkingText,
         signature,
         redactedData,
-        ...(reasoningDetails && reasoningDetails.length > 0
-            ? { reasoningDetails }
-            : {}),
+        ...(hasDetails ? { reasoningDetails, reasoningDetailsFormat } : {}),
     };
 }
+/**
+ * The format of a block's {@link ThinkingContent.reasoningDetails}.
+ *
+ * Untagged blocks are OpenRouter's: it was the only producer before the tag
+ * existed, so that is what an untagged block can only have come from.
+ */
+function reasoningDetailsFormatOf(block) {
+    return block.reasoningDetailsFormat ?? "openrouter";
+}
 /**
  * Create a tool result content block
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentionai/agents",
   "author": "Laurent Zuijdwijk",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Agent Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -132,7 +132,7 @@
     "jsdoc": "^4.0.4",
     "jsdoc-to-markdown": "^9.1.1",
     "nodemon": "^2.0.22",
-    "openai": "^6.16.0",
+    "openai": "^7.13.0",
     "prettier": "^2.8.7",
     "rimraf": "^4.4.1",
     "ts-jest": "^29.2.6",
@@ -153,7 +153,7 @@
     "@openrouter/sdk": "^1.2.106",
     "apache-arrow": "^18.0.0",
     "ollama": "^0.5.18",
-    "openai": "^6.16.0",
+    "openai": "^7.13.0",
     "voyageai": "^0.0.3"
   },
   "peerDependenciesMeta": {