@agentionai/agents 1.13.0 → 1.15.0

package/dist/agents/AgentConfig.d.ts

@@ -137,6 +137,38 @@ export interface OpenAISpecificConfig {
      * see `lib/tools/BuiltInTool.ts`.
      */
     builtInTools?: BuiltInTool[];
+    /**
+     * Cache-routing key sent as `prompt_cache_key`. Requests sharing a key are
+     * steered to the same prompt cache, raising the hit rate for a long
+     * conversation or a fleet of agents sharing a system prompt and tool belt.
+     */
+    promptCacheKey?: string;
+    /**
+     * 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";
+    /**
+     * 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
@@ -148,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/AgentEvent.d.ts

@@ -17,6 +17,12 @@ export declare class AgentEvent {
      * to history. The listener receives the `PartialTurn` that was salvaged.
      */
     static PARTIAL_TURN: string;
+    /**
+     * The provider reported how much of the account's allowance is left. Emitted
+     * by `CodexAgent`, whose backend returns rate-limit and credit headers on
+     * every response; the listener receives a `CodexUsageLimits`.
+     */
+    static USAGE_LIMITS: string;
     private defaultPrevented;
     constructor(target: BaseAgent<any>);
     preventDefault(): void;

package/dist/agents/AgentEvent.js

@@ -30,4 +30,10 @@ AgentEvent.REASONING_CHUNK = "reasoning_chunk";
  * to history. The listener receives the `PartialTurn` that was salvaged.
  */
 AgentEvent.PARTIAL_TURN = "partial_turn";
+/**
+ * The provider reported how much of the account's allowance is left. Emitted
+ * by `CodexAgent`, whose backend returns rate-limit and credit headers on
+ * every response; the listener receives a `CodexUsageLimits`.
+ */
+AgentEvent.USAGE_LIMITS = "usage_limits";
 //# sourceMappingURL=AgentEvent.js.map

package/dist/agents/BaseAgent.d.ts

@@ -41,6 +41,24 @@ export type TokenUsage = {
      * for instance, folds thinking tokens into `output_tokens`.
      */
     reasoning_tokens?: number;
+    /**
+     * Prompt tokens the provider served from its own cache instead of processing
+     * afresh — a subset of `input_tokens`, not an addition to them, and normally
+     * billed at a discount.
+     *
+     * `0` is a real answer ("nothing hit the cache"); `undefined` means the
+     * provider said nothing about caching at all.
+     */
+    cache_read_tokens?: number;
+    /**
+     * Prompt tokens this call wrote *into* the provider's cache, where the
+     * provider reports writes separately from reads. Also a subset of
+     * `input_tokens` on the OpenAI-shaped providers.
+     *
+     * Rarer than `cache_read_tokens` — of the providers wired here only the
+     * ChatGPT/Codex backend reports it, and the platform Responses API does not.
+     */
+    cache_write_tokens?: number;
     /**
      * USD billed for this usage, straight from the provider's own accounting —
      * not derived from a local price table. Undefined where the provider

package/dist/agents/BaseAgent.js

@@ -253,6 +253,8 @@ class BaseAgent extends events_1.default {
                 output_tokens: previous.output_tokens + timed.output_tokens,
                 total_tokens: previous.total_tokens + timed.total_tokens,
                 reasoning_tokens: sumOptional(previous.reasoning_tokens, timed.reasoning_tokens),
+                cache_read_tokens: sumOptional(previous.cache_read_tokens, timed.cache_read_tokens),
+                cache_write_tokens: sumOptional(previous.cache_write_tokens, timed.cache_write_tokens),
                 cost_usd: sumOptional(previous.cost_usd, timed.cost_usd),
                 timeToFirstTokenMs: sumOptional(previous.timeToFirstTokenMs, timed.timeToFirstTokenMs),
                 generationMs: sumOptional(previous.generationMs, timed.generationMs),

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

@@ -4,6 +4,7 @@ import { ResponseInputItem } from "openai/resources/responses/responses";
 import { OpenAIModel } from "../model-types";
 import { AgentConfig as OpenAiAgentConfig, OpenAiAgent } from "./OpenAiAgent";
 import { CodexCredentials, CodexModelCard, CodexTokenProviderOptions } from "./codex-auth";
+import { CodexUsageLimits } from "./codex-usage";
 /**
  * Models the ChatGPT-backed Codex backend serves.
  *
@@ -48,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.
@@ -87,23 +138,77 @@ 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.
+     *
+     * A holder object rather than a field because the wrapper is built *before*
+     * `super()` — the base constructor creates the SDK client, so the wrapper has
+     * to exist by then, and `this` is not available yet. `notify` is attached
+     * afterwards, once emitting is possible.
+     */
+    private readonly limits;
     constructor(config: CodexAgentConfig, history?: History);
+    /**
+     * What the most recent response said about the subscription's remaining
+     * allowance — this backend's answer to "what did that cost?".
+     *
+     * A ChatGPT subscription is not priced per request, so
+     * `lastTokenUsage.cost_usd` is undefined here and always will be. What a call
+     * spends is plan allowance, reported as two rolling windows (5-hourly and
+     * weekly) plus the credit balance that takes over once they are used up.
+     *
+     * Unlike `lastTokenUsage`, this is **not** reset per run: it describes the
+     * account, not the turn, so it keeps the last value seen until another call
+     * updates it. `undefined` before the first call, and after calls that carried
+     * no quota headers — `listModels()` is one, so only `execute()` /
+     * `executeStream()` refresh it. `AgentEvent.USAGE_LIMITS` fires on every
+     * update, including the ones on a failed request.
+     *
+     * @example
+     * ```typescript
+     * await agent.execute("Hello!");
+     * const limits = agent.lastUsageLimits;
+     * console.log(`${limits?.primary?.usedPercent}% of the 5h window used`);
+     * ```
+     */
+    get lastUsageLimits(): CodexUsageLimits | undefined;
     /**
      * 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;
     /**
@@ -132,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

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodexAgent = void 0;
+const AgentEvent_1 = require("../AgentEvent");
 const AgentError_1 = require("../errors/AgentError");
 const OpenAiAgent_1 = require("./OpenAiAgent");
 const codex_auth_1 = require("./codex-auth");
+const codex_usage_1 = require("./codex-usage");
 /**
  * Agent for OpenAI models reached through a **ChatGPT subscription** rather
  * than a platform API key.
@@ -43,6 +45,12 @@ 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 = {};
         // Everything host-specific is passed *into* the base constructor rather
         // than supplied by an override: the base runs before this class's fields
         // are assigned, so an override could not read them.
@@ -55,37 +63,96 @@ 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",
                 ...config.defaultHeaders,
             },
-            // This backend reports failures as `{detail: …}`, which the SDK drops
-            // on the floor — see wrapErrorBodyFetch().
-            fetch: (0, OpenAiAgent_1.wrapErrorBodyFetch)(),
+            // Two wrappers, innermost first: normalise this backend's `{detail: …}`
+            // error bodies (which the SDK otherwise drops on the floor — see
+            // wrapErrorBodyFetch()), then read the `x-codex-*` quota headers off
+            // every response on the way back out.
+            fetch: (0, codex_usage_1.observeHeadersFetch)((headers) => {
+                const parsed = (0, codex_usage_1.parseCodexUsageLimits)(headers);
+                if (!parsed)
+                    return;
+                limits.latest = parsed;
+                limits.notify?.(parsed);
+            }, (0, OpenAiAgent_1.wrapErrorBodyFetch)()),
             // Cast: the codex-specific keys (accountId, originator, clientVersion)
             // are not part of the base config, and `vendor` is supplied by it.
         }, history);
+        this.limits = limits;
+        // Only now can the wrapper emit; anything parsed before this point is still
+        // on `limits.latest`.
+        limits.notify = (usageLimits) => this.emit(AgentEvent_1.AgentEvent.USAGE_LIMITS, usageLimits);
         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
+     * allowance — this backend's answer to "what did that cost?".
+     *
+     * A ChatGPT subscription is not priced per request, so
+     * `lastTokenUsage.cost_usd` is undefined here and always will be. What a call
+     * spends is plan allowance, reported as two rolling windows (5-hourly and
+     * weekly) plus the credit balance that takes over once they are used up.
+     *
+     * Unlike `lastTokenUsage`, this is **not** reset per run: it describes the
+     * account, not the turn, so it keeps the last value seen until another call
+     * updates it. `undefined` before the first call, and after calls that carried
+     * no quota headers — `listModels()` is one, so only `execute()` /
+     * `executeStream()` refresh it. `AgentEvent.USAGE_LIMITS` fires on every
+     * update, including the ones on a failed request.
+     *
+     * @example
+     * ```typescript
+     * await agent.execute("Hello!");
+     * const limits = agent.lastUsageLimits;
+     * console.log(`${limits?.primary?.usedPercent}% of the 5h window used`);
+     * ```
+     */
+    get lastUsageLimits() {
+        return this.limits.latest;
     }
     /**
      * 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.
@@ -93,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

@@ -46,6 +46,69 @@ export type AgentConfig<M extends OpenAIModel = OpenAIModel> = Omit<BaseAgentCon
      * @see lib/tools/BuiltInTool.ts
      */
     builtInTools?: BuiltInTool[];
+    /**
+     * Cache-routing key sent as `prompt_cache_key`. Requests sharing a key are
+     * steered to the same cache, which raises the prompt-cache hit rate for a
+     * long conversation or a fleet of agents that share a system prompt and tool
+     * belt. Any stable string works — a conversation id is the usual choice.
+     *
+     * Left unset by default: caching still happens without it, this only
+     * improves the routing.
+     *
+     * @see https://platform.openai.com/docs/guides/prompt-caching
+     */
+    promptCacheKey?: string;
+    /**
+     * 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";
 };
 /**
  * Lowest `reasoning.effort` the given model accepts, used to resolve
@@ -63,6 +126,24 @@ export type AgentConfig<M extends OpenAIModel = OpenAIModel> = Omit<BaseAgentCon
  * `reasoningEffort` explicitly to override.
  */
 export declare function lowestReasoningEffort(model: string | undefined): ReasoningEffort | undefined;
+/**
+ * `usage.input_tokens_details` as the wire actually carries it.
+ *
+ * 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. On `gpt-5.6`+ these bill at 1.25x input. */
+    cache_write_tokens?: number;
+};
 /**
  * `fetch` wrapper that rewrites a non-OpenAI-shaped error body into the shape
  * the SDK can read.
@@ -195,6 +276,72 @@ 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.
+     *
+     * 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`.
+     */
+    private buildCacheParams;
     protected process(_input: string): Promise<string>;
     execute(input: string | MessageContent[], options?: ExecuteOptions): Promise<string>;
     protected handleResponse(response: Response, options?: ExecuteOptions): Promise<string>;