@agentionai/agents 1.13.0 → 1.14.0

package/dist/agents/AgentConfig.d.ts

@@ -137,6 +137,17 @@ 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 — `"24h"` opts into extended retention.
+     * Ignored by the ChatGPT/Codex backend, which manages its own cache.
+     */
+    promptCacheRetention?: "in-memory" | "24h";
     /**
      * Override the API base URL. Defaults to `api.openai.com/v1`; `CodexAgent`
      * defaults it to `https://chatgpt.com/backend-api/codex`, and setting it

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.
  *
@@ -87,7 +88,40 @@ export declare class CodexAgent extends OpenAiAgent<OpenAIModel, CodexModelCard>
     private readonly originator;
     private readonly clientVersion;
     private readonly codexBaseURL;
+    /**
+     * 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.

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,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;
+        // 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.
@@ -60,18 +65,56 @@ class CodexAgent extends OpenAiAgent_1.OpenAiAgent {
                 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;
         this.codexBaseURL = baseURL;
     }
+    /**
+     * 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.

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

@@ -46,6 +46,26 @@ 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;
+    /**
+     * 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.
+     *
+     * 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 +83,21 @@ 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'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.
+ */
+export type OpenAIInputTokensDetails = {
+    /** Prompt tokens served from cache. */
+    cached_tokens?: number;
+    /** Prompt tokens written to cache. Codex backend only. */
+    cache_write_tokens?: number;
+};
 /**
  * `fetch` wrapper that rewrites a non-OpenAI-shaped error body into the shape
  * the SDK can read.
@@ -195,6 +230,15 @@ export declare class OpenAiAgent<M extends OpenAIModel = OpenAIModel, TModelCard
      * emits `response.reasoning_summary_text.delta` events when it is set.
      */
     private buildReasoningParams;
+    /**
+     * 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>;

package/dist/agents/openai/OpenAiAgent.js

@@ -171,6 +171,8 @@ 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;
         this.config = {
             model: config.model || "gpt-4.1-mini",
             // No default. `max_output_tokens` is optional on the Responses API, and
@@ -185,6 +187,8 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             reasoningEffort,
             user,
             builtInTools,
+            promptCacheKey,
+            promptCacheRetention,
             apiKey: config.apiKey,
             baseURL,
             temperature: config.temperature,
@@ -350,6 +354,24 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             },
         };
     }
+    /**
+     * 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 "";
     }
@@ -395,6 +417,7 @@ 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(),
             }, { signal: options?.signal });
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
             return await this.handleResponse(response, options);
@@ -522,6 +545,7 @@ 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(),
                     }, { signal: options?.signal });
                     this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
                     return this.handleResponse(newResponse, options);
@@ -703,6 +727,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             top_p: this.config.topP,
             user: this.config.user,
             ...this.buildReasoningParams("auto"),
+            ...this.buildCacheParams(),
         }), { signal: options?.signal });
         let completedEvent = null;
         const streamedItems = [];
@@ -832,12 +857,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/index.d.ts

@@ -3,6 +3,7 @@ export * from "./agents/anthropic/ClaudeAgent";
 export { OpenAiAgent } from "./agents/openai/OpenAiAgent";
 export { CODEX_BASE_URL, CODEX_CLIENT_ID, CODEX_ORIGINATOR, CODEX_TOKEN_URL, codexAuthFilePath, createCodexTokenProvider, loadCodexCredentials, refreshCodexCredentials, } from "./agents/openai/codex-auth";
 export type { CodexModelCard, CodexCredentials, CodexTokenProvider, CodexTokenProviderOptions, } from "./agents/openai/codex-auth";
+export { parseCodexUsageLimits, observeHeadersFetch, type CodexUsageLimits, type CodexRateLimitWindow, type CodexCredits, } from "./agents/openai/codex-usage";
 export { CodexAgent } from "./agents/openai/CodexAgent";
 export type { CodexAgentConfig, CodexModel, CodexReasoningEffort, } from "./agents/openai/CodexAgent";
 export { MistralAgent } from "./agents/mistral/MistralAgent";

package/dist/index.js

@@ -22,7 +22,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.openRouterTransformer = exports.chatCompletionsTransformer = exports.ollamaTransformer = exports.geminiTransformer = exports.mistralTransformer = exports.openAiTransformer = exports.anthropicTransformer = exports.OpenRouterAgent = exports.OpenAICompatibleAgent = exports.LlamaCppAgent = exports.OllamaAgent = exports.GEMINI_RETIRED_MODELS = exports.GeminiAgent = exports.MistralAgent = exports.CodexAgent = exports.refreshCodexCredentials = exports.loadCodexCredentials = exports.createCodexTokenProvider = exports.codexAuthFilePath = exports.CODEX_TOKEN_URL = exports.CODEX_ORIGINATOR = exports.CODEX_CLIENT_ID = exports.CODEX_BASE_URL = exports.OpenAiAgent = void 0;
+exports.openRouterTransformer = exports.chatCompletionsTransformer = exports.ollamaTransformer = exports.geminiTransformer = exports.mistralTransformer = exports.openAiTransformer = exports.anthropicTransformer = exports.OpenRouterAgent = exports.OpenAICompatibleAgent = exports.LlamaCppAgent = exports.OllamaAgent = exports.GEMINI_RETIRED_MODELS = exports.GeminiAgent = exports.MistralAgent = exports.CodexAgent = exports.observeHeadersFetch = exports.parseCodexUsageLimits = exports.refreshCodexCredentials = exports.loadCodexCredentials = exports.createCodexTokenProvider = exports.codexAuthFilePath = exports.CODEX_TOKEN_URL = exports.CODEX_ORIGINATOR = exports.CODEX_CLIENT_ID = exports.CODEX_BASE_URL = exports.OpenAiAgent = void 0;
 // Agents
 __exportStar(require("./agents/BaseAgent"), exports);
 __exportStar(require("./agents/anthropic/ClaudeAgent"), exports);
@@ -37,6 +37,9 @@ Object.defineProperty(exports, "codexAuthFilePath", { enumerable: true, get: fun
 Object.defineProperty(exports, "createCodexTokenProvider", { enumerable: true, get: function () { return codex_auth_1.createCodexTokenProvider; } });
 Object.defineProperty(exports, "loadCodexCredentials", { enumerable: true, get: function () { return codex_auth_1.loadCodexCredentials; } });
 Object.defineProperty(exports, "refreshCodexCredentials", { enumerable: true, get: function () { return codex_auth_1.refreshCodexCredentials; } });
+var codex_usage_1 = require("./agents/openai/codex-usage");
+Object.defineProperty(exports, "parseCodexUsageLimits", { enumerable: true, get: function () { return codex_usage_1.parseCodexUsageLimits; } });
+Object.defineProperty(exports, "observeHeadersFetch", { enumerable: true, get: function () { return codex_usage_1.observeHeadersFetch; } });
 var CodexAgent_1 = require("./agents/openai/CodexAgent");
 Object.defineProperty(exports, "CodexAgent", { enumerable: true, get: function () { return CodexAgent_1.CodexAgent; } });
 var MistralAgent_1 = require("./agents/mistral/MistralAgent");

package/dist/openai.d.ts

@@ -1,7 +1,9 @@
 export * from "./core";
 export { OpenAiAgent, describeOpenAIError, wrapErrorBodyFetch, } from "./agents/openai/OpenAiAgent";
+export type { OpenAIInputTokensDetails } from "./agents/openai/OpenAiAgent";
 export { CodexAgent } from "./agents/openai/CodexAgent";
 export type { CodexAgentConfig, CodexModel, CodexReasoningEffort, } from "./agents/openai/CodexAgent";
 export { openAiTransformer } from "./history/transformers";
 export { CODEX_BASE_URL, CODEX_CLIENT_ID, CODEX_ORIGINATOR, CODEX_TOKEN_URL, codexAuthFilePath, createCodexTokenProvider, decodeJwtClaims, jwtExpiry, loadCodexCredentials, refreshCodexCredentials, type CodexCredentials, type CodexTokenProvider, type CodexTokenProviderOptions, type CodexModelCard, } from "./agents/openai/codex-auth";
+export { parseCodexUsageLimits, observeHeadersFetch, type CodexUsageLimits, type CodexRateLimitWindow, type CodexCredits, } from "./agents/openai/codex-usage";
 //# sourceMappingURL=openai.d.ts.map

package/dist/openai.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.refreshCodexCredentials = exports.loadCodexCredentials = exports.jwtExpiry = exports.decodeJwtClaims = exports.createCodexTokenProvider = exports.codexAuthFilePath = exports.CODEX_TOKEN_URL = exports.CODEX_ORIGINATOR = exports.CODEX_CLIENT_ID = exports.CODEX_BASE_URL = exports.openAiTransformer = exports.CodexAgent = exports.wrapErrorBodyFetch = exports.describeOpenAIError = exports.OpenAiAgent = void 0;
+exports.observeHeadersFetch = exports.parseCodexUsageLimits = exports.refreshCodexCredentials = exports.loadCodexCredentials = exports.jwtExpiry = exports.decodeJwtClaims = exports.createCodexTokenProvider = exports.codexAuthFilePath = exports.CODEX_TOKEN_URL = exports.CODEX_ORIGINATOR = exports.CODEX_CLIENT_ID = exports.CODEX_BASE_URL = exports.openAiTransformer = exports.CodexAgent = exports.wrapErrorBodyFetch = exports.describeOpenAIError = exports.OpenAiAgent = void 0;
 // OpenAI Agent Entry Point
 __exportStar(require("./core"), exports);
 var OpenAiAgent_1 = require("./agents/openai/OpenAiAgent");
@@ -36,4 +36,7 @@ Object.defineProperty(exports, "decodeJwtClaims", { enumerable: true, get: funct
 Object.defineProperty(exports, "jwtExpiry", { enumerable: true, get: function () { return codex_auth_1.jwtExpiry; } });
 Object.defineProperty(exports, "loadCodexCredentials", { enumerable: true, get: function () { return codex_auth_1.loadCodexCredentials; } });
 Object.defineProperty(exports, "refreshCodexCredentials", { enumerable: true, get: function () { return codex_auth_1.refreshCodexCredentials; } });
+var codex_usage_1 = require("./agents/openai/codex-usage");
+Object.defineProperty(exports, "parseCodexUsageLimits", { enumerable: true, get: function () { return codex_usage_1.parseCodexUsageLimits; } });
+Object.defineProperty(exports, "observeHeadersFetch", { enumerable: true, get: function () { return codex_usage_1.observeHeadersFetch; } });
 //# sourceMappingURL=openai.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentionai/agents",
   "author": "Laurent Zuijdwijk",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Agent Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",