@oh-my-pi/pi-ai 15.11.3 → 15.11.6

package/CHANGELOG.md

@@ -2,7 +2,55 @@
 
 ## [Unreleased]
 
+## [15.11.5] - 2026-06-12
+
+### Added
+
+- Added `AuthStorage.listUsageHistory` to retrieve historical usage snapshots with optional `provider` and `sinceMs` filtering
+- Added durable usage-history persistence in the sqlite auth store so successful usage reports are recorded as time-series snapshots of limit utilization for later trend inspection
+- Added `AuthStorage.redeemResetCredit` to redeem stored OpenAI Codex saved rate-limit reset credits for a target account by `credentialId`, `accountId`, or `email`
+- Added `listCodexResetCredits` and `consumeCodexResetCredit` exports for OpenAI Codex saved reset-credit listing and redemption
+- Added `resetCredits` with `availableCount` to `UsageReport` so OpenAI Codex usage data now exposes redeemable rate-limit resets
+- Added `openai-codex-reset` exports via package barrel for out-of-band tooling usage
+- Added a one-shot request-debug target that writes the next provider HTTP request JSON to an explicit path.
+
+### Changed
+
+- Changed `AuthStorage.redeemResetCredit` to invalidate cached usage data after a successful redemption so the next usage report reflects the reset immediately
+
+### Fixed
+
+- Fixed temporary credential block state so redeemed reset credits immediately make the affected account selectable again after `redeemResetCredit` succeeds
+- Fixed one-shot request-debug path handling so an explicit request log target is consumed after the next request and no longer affects subsequent calls
+- Fixed explicit request-debug path mode to create missing parent directories before writing request logs
+- Fixed explicit request-debug mode to overwrite existing `.res.log` files for the requested path instead of failing when they already exist
+- Fixed OpenAI Responses `previous_response_id` chaining on Zero Data Retention orgs: the in-provider retry classifier missed the ZDR-specific 400 ("Previous response cannot be used for this organization due to Zero Data Retention"), so chained turns kept failing every other request after a brief recovery — the chain was reset but not disabled, so the next successful full-replay turn re-armed it. The ZDR phrasing is now classified categorically: one strike disables chaining for the session (skipping the three-strike circuit breaker) and the in-call retry drops `store: true`/`previous_response_id` and replays the full transcript instead ([#2341](https://github.com/can1357/oh-my-pi/issues/2341)).
+
+## [15.11.4] - 2026-06-12
+
+### Added
+
+- Codex/Responses providers now map `end_turn: false` on the terminal stream event (Codex backend signal for "response ended, turn didn't" — commentary-only progress updates) to `stopDetails: { type: "pause_turn" }` with stopReason `"stop"`, so the agent loop can re-sample instead of ending the turn. Wired in `openai-codex-responses` and `processResponsesStream` (`openai-responses`/`azure-openai-responses`); inert for backends that never send the field.
+- Added Codex upstream protocol features to `openai-codex-responses` (tracking codex-rs as of June 2026): `onModerationMetadata` callback surfacing `response.metadata` → `openai_chatgpt_moderation_metadata` on both transports; `reasoningContext` option emitting `reasoning.context` (`auto`/`current_turn`/`all_turns`); `clientMetadata` option emitting `client_metadata` in the request body (canonical `x-codex-turn-metadata` envelope) without breaking the websocket append fast-path; and an opt-in `responsesLite` mode mirroring codex-rs — lite header on HTTP requests and the websocket upgrade, `ws_request_header_*` marker in `response.create` client metadata, lite-keyed socket pooling, image-detail stripping, forced serial tool calls, and `reasoning.context: all_turns` default. Dormant until OpenAI flips `use_responses_lite` in the model catalog.
+- Added `withOAuthAccess` — the `withAuth` counterpart for OAuth-access consumers: runs an operation through the central a/b/c auth-retry policy (resolve → force-refresh same account → rotate to a sibling) while handing the attempt the full `OAuthAccess` (bearer plus `accountId`/`projectId`/`enterpriseUrl` identity metadata). Use it instead of hand-rolled `getOAuthAccess` + fetch flows so 401s and usage-limits rotate credentials instead of failing the call.
+- Added `ProviderHttpError` — a typed HTTP error carrying `status`, `headers`, and `code` — replacing the ad-hoc `as Error & { status?... }` / `Object.assign` hacks at provider throw sites, with per-provider subclasses `CodexApiError`, `AuthGatewayError`, `GoogleApiError`, `GeminiCliApiError`, `OllamaApiError`, and `BedrockApiError`; `AnthropicApiError` now extends it. Google, Gemini CLI, Ollama, and Bedrock HTTP errors now also carry response headers, so server-suggested `retry-after` delays are visible to retry classification on those paths. The internal `withHttpStatus` helper was removed.
+- Added stateful SSE turn chaining for OpenAI Codex (on by default; disable with `PI_CODEX_STATEFUL=0` or `statefulResponses: false`): SSE requests now reuse `previous_response_id` with delta-only input instead of replaying the full transcript, mirroring the websocket fast-path via a shared transport-aware builder. Any history mutation or option change falls back to a full replay; a server-side `previous_response_not_found` (HTTP or in-stream) resets the chain and retries the turn with full context, and three consecutive stale failures disable chaining for the session.
+- Added stateful `previous_response_id` chaining to the platform OpenAI Responses provider (`openai-responses`): on by default against the official api.openai.com endpoint (forces `store: true`, which chaining requires), off for other Responses endpoints; override with `statefulResponses` or `PI_OPENAI_STATEFUL`. Chain detection compares the wire form of the conversation arguments alone — per-turn trailing scaffolding such as the GPT-5 "Juice: 0" developer item is excluded from the append-baseline prefix check and re-appended to the delta — and a rejected/stale previous response falls back to a one-shot full replay with the same circuit breaker.
+- Added `AuthStorage.getOAuthAccountIdentity()` and the `OAuthAccountIdentity` type — a read-only lookup returning the `accountId`/`email`/`projectId` of the OAuth credential a session is currently routed to, for display and metadata paths.
+
+### Changed
+
+- The GPT-5 "Juice: 0" no-reasoning developer item in `applyResponsesReasoningParams` is now gated on the resolved `compat.requiresJuiceZeroHack` flag (auto-detected from GPT-5-family model names by `@oh-my-pi/pi-catalog`, overridable per model) instead of an inline model-name check.
+
+### Fixed
+
+- Fixed websocket append fast-path to remain usable when only `client_metadata` changes between turns
+- Fixed `onModerationMetadata` handling so exceptions thrown by callback observers no longer terminate the response stream
+- Fixed local SQLite OAuth credential caches returning a stale Anthropic access token after another `omp` process refreshed and persisted the same row. `AuthStorage` now syncs the selected row from storage before returning or force-refreshing OAuth credentials, so concurrent sessions pick up peer-rotated tokens instead of surfacing a one-turn `401 Invalid authentication credentials`.
+- Fixed forced OAuth preflight refresh failures being swallowed silently in credential selection; they now emit a debug log (`OAuth preflight refresh failed`) so stale-refresh-token replays from concurrent sessions are diagnosable.
+
 ## [15.11.3] - 2026-06-11
+
 ### Fixed
 
 - Fixed GitHub Copilot long-context model requests to use the upstream `requestModelId` when calling Anthropic, OpenAI Responses, and OpenAI Completions APIs
@@ -3274,4 +3322,4 @@ _Dedicated to Peter's shoulder ([@steipete](https://twitter.com/steipete))_
 
 ## [0.9.4] - 2025-11-26
 
-Initial release with multi-provider LLM support.
+Initial release with multi-provider LLM support.

package/dist/types/auth-broker/wire-schemas.d.ts

@@ -344,6 +344,9 @@ export declare const usageResponseSchema: z.ZodObject<{
             }>>;
             notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
+        resetCredits: z.ZodOptional<z.ZodObject<{
+            availableCount: z.ZodNumber;
+        }, z.core.$strip>>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         raw: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>>;

package/dist/types/auth-retry.d.ts

@@ -1,3 +1,4 @@
+import type { OAuthAccess } from "./auth-storage";
 /**
  * Context passed to an {@link ApiKeyResolver} on each resolution attempt.
  *
@@ -70,3 +71,49 @@ export declare function withAuth<T>(key: ApiKey | undefined, attempt: (key: stri
     signal?: AbortSignal;
     missingKeyMessage?: string;
 }): Promise<T>;
+/**
+ * Minimal structural slice of `AuthStorage` consumed by {@link withOAuthAccess}.
+ * Typed structurally (and importing only the `OAuthAccess` type) so this module
+ * never takes a runtime dependency on `./auth-storage`.
+ */
+export interface OAuthAccessSource {
+    getOAuthAccess(provider: string, sessionId?: string, options?: {
+        forceRefresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<OAuthAccess | undefined>;
+    rotateSessionCredential(provider: string, sessionId: string | undefined, options?: {
+        error?: unknown;
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+}
+export interface WithOAuthAccessOptions {
+    /** Session id for credential stickiness, threaded into every resolve. */
+    sessionId?: string;
+    signal?: AbortSignal;
+    /** Override the retryable-error classifier (default {@link isAuthRetryableError}). */
+    isAuthError?: (error: unknown) => boolean;
+    /**
+     * Pre-resolved access used for the initial attempt. Callers that already
+     * resolved access for an availability gate pass it here so the helper
+     * doesn't double-resolve (mirrors the gateway resolver's `initialKey`).
+     */
+    seed?: OAuthAccess;
+    missingAccessMessage?: string;
+}
+/**
+ * {@link withAuth} for OAuth-access consumers: runs an auth-protected
+ * operation through the central a/b/c retry policy, handing the attempt the
+ * full {@link OAuthAccess} (bearer + identity metadata: `accountId`,
+ * `projectId`, `enterpriseUrl`) instead of bare API-key bytes.
+ *
+ * - initial → `getOAuthAccess` (or `opts.seed`).
+ * - step (b) → `getOAuthAccess` with `forceRefresh: true` (re-mint the SAME
+ *   account; picks up peer/broker rotations).
+ * - step (c) → `rotateSessionCredential` then re-resolve (switch to a sibling).
+ *
+ * A step is skipped when it yields no access or the same `accessToken` that
+ * just failed; non-auth errors propagate immediately. Use this instead of
+ * hand-rolled `getOAuthAccess` + fetch flows so 401s and usage-limits rotate
+ * credentials instead of failing the call.
+ */
+export declare function withOAuthAccess<T>(storage: OAuthAccessSource, provider: string, attempt: (access: OAuthAccess) => Promise<T>, opts?: WithOAuthAccessOptions): Promise<T>;

package/dist/types/auth-storage.d.ts

@@ -11,7 +11,8 @@ import { Database } from "bun:sqlite";
 import type { ApiKeyResolver } from "./auth-retry";
 import type { OAuthController, OAuthCredentials, OAuthProviderId } from "./registry/oauth/types";
 import type { Provider } from "./types";
-import type { CredentialRankingStrategy, UsageLogger, UsageProvider, UsageReport } from "./usage";
+import type { CredentialRankingStrategy, UsageHistoryEntry, UsageHistoryQuery, UsageLogger, UsageProvider, UsageReport } from "./usage";
+import { type CodexResetConsumeCode, type CodexResetCredit } from "./usage/openai-codex-reset";
 export type ApiKeyCredential = {
     type: "api_key";
     key: string;
@@ -225,6 +226,14 @@ export interface AuthCredentialStore {
     }): string | null;
     setCache(key: string, value: string, expiresAtSec: number): void;
     cleanExpiredCache(): void;
+    /**
+     * Append usage-limit snapshots for trend history. Optional: stores without
+     * durable storage (e.g. the broker remote store) omit it and recording is
+     * skipped — the broker host records into its own database instead.
+     */
+    recordUsageSnapshots?(entries: UsageHistoryEntry[]): void;
+    /** Read recorded usage-limit snapshots, oldest first. */
+    listUsageHistory?(query?: UsageHistoryQuery): UsageHistoryEntry[];
     /**
      * Optional store-supplied OAuth refresh. When present, `AuthStorage` uses
      * it before the per-provider local refresh path. `RemoteAuthCredentialStore`
@@ -430,6 +439,17 @@ export interface OAuthAccessFailure {
     enterpriseUrl?: string;
     error: string;
 }
+/**
+ * Identity of the OAuth credential a session is currently routed to. Read-only
+ * display/metadata shape: `accountId` is the provider's account UUID, `email`
+ * the user-facing login, `projectId` the GCP-style project for providers that
+ * key usage on it (Gemini CLI / Antigravity).
+ */
+export interface OAuthAccountIdentity {
+    accountId?: string;
+    email?: string;
+    projectId?: string;
+}
 export type OAuthAccessResolution = ({
     ok: true;
 } & OAuthAccess) | ({
@@ -439,6 +459,44 @@ export interface InvalidateCredentialMatchingOptions {
     signal?: AbortSignal;
     sessionId?: string;
 }
+/**
+ * Identifies which stored account to redeem a saved rate-limit reset for.
+ * Any one field is enough; `credentialId` is the most precise.
+ */
+export interface ResetCreditTarget {
+    credentialId?: number;
+    accountId?: string;
+    email?: string;
+}
+/** Outcome of {@link AuthStorage.redeemResetCredit}. */
+export interface ResetCreditRedeemOutcome {
+    /** `true` only when a reset was actually applied (`code === "reset"`). */
+    ok: boolean;
+    /**
+     * Result code. Backend codes: `reset` (success), `already_redeemed`,
+     * `no_credit`, `nothing_to_reset`. Locally-synthesized: `no_account`
+     * (target not found), `account_unavailable` (token refresh failed),
+     * `http_<status>` (unexpected HTTP).
+     */
+    code: CodexResetConsumeCode;
+    accountId?: string;
+    email?: string;
+    /** The credit that was spent (when one was). */
+    creditId?: string;
+}
+/** One stored account's live saved-reset status, from {@link AuthStorage.listResetCredits}. */
+export interface ResetCreditAccountStatus {
+    credentialId?: number;
+    accountId?: string;
+    email?: string;
+    /** Resets redeemable for this account right now (live, not cached). */
+    availableCount: number;
+    credits: CodexResetCredit[];
+    /** Whether this is the given session's active account. */
+    active: boolean;
+    /** Set when the account's token refresh or list call failed. */
+    error?: string;
+}
 /**
  * Credential storage backed by an AuthCredentialStore.
  * Reads from storage on reload(), manages round-robin credential selection,
@@ -581,6 +639,12 @@ export declare class AuthStorage {
      * Returns `undefined` when no OAuth credential carries an `accountId`.
      */
     getOAuthAccountId(provider: string, sessionId?: string): string | undefined;
+    /**
+     * Get the OAuth account identity for a provider, preferring the credential that
+     * is session-sticky for `sessionId`. This is a read-only lookup for display and
+     * metadata paths; it does not refresh tokens, rank usage, or advance selection.
+     */
+    getOAuthAccountIdentity(provider: string, sessionId?: string): OAuthAccountIdentity | undefined;
     /**
      * Get all credentials.
      */
@@ -604,6 +668,11 @@ export declare class AuthStorage {
      * Logout from a provider.
      */
     logout(provider: string): Promise<void>;
+    /**
+     * Recorded usage-limit snapshots, oldest first. Empty when the underlying
+     * store has no durable history (e.g. a broker-backed remote store).
+     */
+    listUsageHistory(query?: UsageHistoryQuery): UsageHistoryEntry[];
     ingestUsageHeaders(provider: Provider, headers: Record<string, string>, options?: {
         sessionId?: string;
         baseUrl?: string;
@@ -696,6 +765,38 @@ export declare class AuthStorage {
      * exercise each stored account exactly once.
      */
     getOAuthAccesses(provider: string, options?: AuthApiKeyOptions): Promise<OAuthAccessResolution[]>;
+    /**
+     * List saved rate-limit resets for every stored OAuth account of `provider`
+     * (Codex), fetched LIVE from the dedicated `rate-limit-reset-credits` route.
+     *
+     * This deliberately bypasses the usage-report cache: `/wham/usage` is
+     * IP-rate-limited and may serve stale (or pre-feature) snapshots when many
+     * accounts are polled, which would hide redeemable credits. One entry per
+     * account, with the session's active account flagged and unreachable
+     * accounts carrying an `error`.
+     */
+    listResetCredits(options?: {
+        provider?: string;
+        sessionId?: string;
+        baseUrlResolver?: (provider: string) => string | undefined;
+        signal?: AbortSignal;
+    }): Promise<ResetCreditAccountStatus[]>;
+    /**
+     * Redeem one saved rate-limit reset (OpenAI Codex "saved resets") for a
+     * specific stored account.
+     *
+     * Resolves a fresh access token for the target account, picks an available
+     * credit (the given `creditId`, else the first redeemable one), spends it,
+     * and invalidates the cached usage report so the next `/usage` reflects the
+     * reset. Never throws for business outcomes — inspect the returned `code`.
+     */
+    redeemResetCredit(options: {
+        target: ResetCreditTarget;
+        provider?: string;
+        creditId?: string;
+        baseUrlResolver?: (provider: string) => string | undefined;
+        signal?: AbortSignal;
+    }): Promise<ResetCreditRedeemOutcome>;
     invalidateCredentialMatching(provider: string, apiKey: string, options?: InvalidateCredentialMatchingOptions): Promise<boolean>;
     invalidateCredentialMatching(provider: string, apiKey: string, signal?: AbortSignal): Promise<boolean>;
     /**
@@ -819,6 +920,8 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     }): string | null;
     setCache(key: string, value: string, expiresAtSec: number): void;
     cleanExpiredCache(): void;
+    recordUsageSnapshots(entries: UsageHistoryEntry[]): void;
+    listUsageHistory(query?: UsageHistoryQuery): UsageHistoryEntry[];
     /**
      * Save OAuth credentials for a provider.
      * Preserves unrelated identities and replaces only the matching credential.

package/dist/types/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Structured HTTP errors thrown by provider clients.
+ *
+ * Downstream classification reads these fields structurally rather than via
+ * `instanceof`: `extractHttpStatusFromError` (pi-utils) reads `status`,
+ * `getHeadersFromError` (retry-after extraction) reads `headers`, and retry
+ * policies such as `isCopilotTransientModelError` read `code`. Per-provider
+ * subclasses exist so call sites can narrow with `instanceof` and logs carry
+ * a meaningful `error.name`.
+ */
+export interface ProviderHttpErrorOptions {
+    /** Response headers; enables `retry-after`/rate-limit extraction downstream. */
+    headers?: Headers;
+    /** Machine-readable error code from the response body (`error.code` / `error.type`). */
+    code?: string;
+    cause?: unknown;
+}
+/** Non-2xx HTTP response from a provider endpoint. */
+export declare class ProviderHttpError extends Error {
+    readonly status: number;
+    readonly headers: Headers | undefined;
+    readonly code: string | undefined;
+    constructor(message: string, status: number, options?: ProviderHttpErrorOptions);
+}

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export { type AuthGatewayBootOptions, type ModelResolver, startAuthGateway } fro
 export * from "./auth-gateway/types";
 export * from "./auth-retry";
 export * from "./auth-storage";
+export * from "./errors";
 export * from "./provider-details";
 export * from "./providers/anthropic";
 export * from "./providers/anthropic-client";
@@ -33,6 +34,7 @@ export * from "./usage/google-antigravity";
 export * from "./usage/kimi";
 export * from "./usage/minimax-code";
 export * from "./usage/openai-codex";
+export * from "./usage/openai-codex-reset";
 export * from "./usage/zai";
 export * from "./utils/anthropic-auth";
 export * from "./utils/event-stream";

package/dist/types/providers/amazon-bedrock.d.ts

@@ -7,7 +7,12 @@
  * Bun's native `HTTPS_PROXY` support.
  */
 import type { Effort } from "@oh-my-pi/pi-catalog/effort";
+import { ProviderHttpError } from "../errors";
 import type { StreamFunction, StreamOptions, ThinkingBudgets } from "../types";
+/** Non-2xx response (or in-stream exception event) from the Bedrock runtime API. */
+export declare class BedrockApiError extends ProviderHttpError {
+    readonly name = "BedrockApiError";
+}
 export type BedrockThinkingDisplay = "summarized" | "omitted";
 export interface BedrockOptions extends StreamOptions {
     region?: string;

package/dist/types/providers/anthropic-client.d.ts

@@ -1,3 +1,4 @@
+import { ProviderHttpError } from "../errors";
 import type { FetchImpl } from "../types";
 import type { MessageCreateParamsStreaming } from "./anthropic-wire";
 /** Per-request options accepted by {@link AnthropicMessages.create}. */
@@ -39,8 +40,7 @@ export interface AnthropicClientOptions {
     fetchOptions?: AnthropicFetchOptions;
 }
 /** Non-2xx response from the Anthropic API. */
-export declare class AnthropicApiError extends Error {
-    readonly status: number;
+export declare class AnthropicApiError extends ProviderHttpError {
     readonly headers: Headers;
     readonly requestId: string | null;
     constructor(status: number, message: string, headers: Headers);

package/dist/types/providers/google-gemini-cli.d.ts

@@ -1,3 +1,4 @@
+import { ProviderHttpError } from "../errors";
 import type { Context, Model, StreamFunction, StreamOptions } from "../types";
 import type { Content, FunctionCallingConfigMode, ThinkingConfig } from "./google-shared";
 import { type GoogleThinkingLevel } from "./google-shared";
@@ -6,6 +7,10 @@ import { type GoogleThinkingLevel } from "./google-shared";
  * `import { GoogleThinkingLevel } from "./google-gemini-cli"` callers keep working.
  */
 export type { GoogleThinkingLevel };
+/** Non-2xx response (or in-stream error chunk) from the Cloud Code Assist API. */
+export declare class GeminiCliApiError extends ProviderHttpError {
+    readonly name = "GeminiCliApiError";
+}
 export interface GoogleGeminiCliOptions extends StreamOptions {
     /**
      * Tool selection mode. String forms map directly to Gemini

package/dist/types/providers/google-shared.d.ts

@@ -1,12 +1,17 @@
 /**
  * Shared utilities for Google Generative AI and Google Cloud Code Assist providers.
  */
+import { ProviderHttpError } from "../errors";
 import type { AssistantMessage, Context, FetchImpl, Model, StopReason, StreamOptions, TextContent, ThinkingContent, Tool, ToolCall } from "../types";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 import { normalizeSchemaForGoogle } from "../utils/schema";
 import type { Content, FinishReason, FunctionCallingConfigMode, GenerateContentParameters, GenerateContentResponse, Part } from "./google-types";
 export type { Content, FunctionCallingConfigMode, GenerateContentParameters, GenerateContentResponse, ThinkingConfig, } from "./google-types";
 export { normalizeSchemaForGoogle };
+/** Non-2xx response (or in-stream error chunk) from the Google Generative Language / Vertex API. */
+export declare class GoogleApiError extends ProviderHttpError {
+    readonly name = "GoogleApiError";
+}
 type GoogleApiType = "google-generative-ai" | "google-gemini-cli" | "google-vertex";
 /**
  * Thinking level for Gemini 3 models. Mirrors Google's `ThinkingLevel` enum values.

package/dist/types/providers/ollama.d.ts

@@ -1,4 +1,9 @@
+import { ProviderHttpError } from "../errors";
 import type { StreamFunction, StreamOptions, ToolChoice } from "../types";
+/** Non-2xx response from the Ollama `/api/chat` endpoint. */
+export declare class OllamaApiError extends ProviderHttpError {
+    readonly name = "OllamaApiError";
+}
 export interface OllamaChatOptions extends StreamOptions {
     reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh";
     disableReasoning?: boolean;

package/dist/types/providers/openai-codex/request-transformer.d.ts

@@ -1,13 +1,20 @@
 import type { Api, Model } from "../../types";
+/** Reasoning replay scope for the Codex Responses API (`reasoning.context`). */
+export type CodexReasoningContext = "auto" | "current_turn" | "all_turns";
 export interface ReasoningConfig {
     effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
     summary?: "auto" | "concise" | "detailed";
+    context?: CodexReasoningContext;
 }
 export interface CodexRequestOptions {
     reasoningEffort?: ReasoningConfig["effort"];
     reasoningSummary?: ReasoningConfig["summary"] | null;
+    /** Explicit `reasoning.context` override. Defaults to `all_turns` under {@link CodexRequestOptions.responsesLite}, otherwise omitted (server default is `current_turn`). */
+    reasoningContext?: CodexReasoningContext;
     textVerbosity?: "low" | "medium" | "high";
     include?: string[];
+    /** Responses Lite transport contract: strips image detail and defaults `reasoning.context` to `all_turns`, mirroring codex-rs. */
+    responsesLite?: boolean;
 }
 export interface InputItem {
     id?: string | null;
@@ -40,6 +47,7 @@ export interface RequestBody {
     include?: string[];
     prompt_cache_key?: string;
     prompt_cache_retention?: "in_memory" | "24h";
+    client_metadata?: Record<string, string>;
     max_output_tokens?: number;
     max_completion_tokens?: number;
     [key: string]: unknown;

package/dist/types/providers/openai-codex/response-handler.d.ts

@@ -1,3 +1,4 @@
+import { ProviderHttpError } from "../../errors";
 export type CodexRateLimit = {
     used_percent?: number;
     window_minutes?: number;
@@ -10,8 +11,16 @@ export type CodexRateLimits = {
 export type CodexErrorInfo = {
     message: string;
     status: number;
+    /** Machine-readable error code (`error.code` or `error.type` from the response body), when present. */
+    code?: string;
     friendlyMessage?: string;
     rateLimits?: CodexRateLimits;
     raw?: string;
 };
+/** Non-2xx response from the Codex backend, with the parsed body retained. */
+export declare class CodexApiError extends ProviderHttpError {
+    readonly info: CodexErrorInfo;
+    constructor(info: CodexErrorInfo, headers?: Headers);
+    static fromResponse(response: Response): Promise<CodexApiError>;
+}
 export declare function parseCodexError(response: Response): Promise<CodexErrorInfo>;

package/dist/types/providers/openai-codex-responses.d.ts

@@ -1,16 +1,51 @@
 import type { ResponseInput } from "openai/resources/responses/responses";
 import { type Context, type Model, type ProviderSessionState, type ServiceTier, type StreamFunction, type StreamOptions, type Tool, type ToolChoice } from "../types";
+import { type CodexReasoningContext } from "./openai-codex/request-transformer";
 export interface OpenAICodexResponsesOptions extends StreamOptions {
     reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
     reasoningSummary?: "auto" | "concise" | "detailed" | null;
+    /** `reasoning.context` replay scope. Defaults to `all_turns` under {@link OpenAICodexResponsesOptions.responsesLite}, otherwise omitted (server default is `current_turn`). */
+    reasoningContext?: CodexReasoningContext;
     textVerbosity?: "low" | "medium" | "high";
     include?: string[];
     codexMode?: boolean;
     toolChoice?: ToolChoice;
     preferWebsockets?: boolean;
+    /**
+     * Enable stateful SSE turns: chain via `previous_response_id` + delta input
+     * instead of replaying the full transcript. Requires `sessionId` +
+     * `providerSessionState`. `false` vetoes the `PI_CODEX_STATEFUL` env flag.
+     */
+    statefulResponses?: boolean;
     serviceTier?: ServiceTier;
+    /**
+     * Opt into the Responses Lite transport contract. Sends
+     * `x-openai-internal-codex-responses-lite: true` on HTTP requests and on the
+     * WebSocket upgrade (the marker is connection-scoped there, so lite and
+     * non-lite turns never share a pooled socket), strips image detail from
+     * input, and defaults `reasoning.context` to `all_turns` — mirroring codex-rs.
+     */
+    responsesLite?: boolean;
+    /**
+     * Extra `client_metadata` to include in the request body on both transports.
+     * The canonical Codex envelope is `client_metadata["x-codex-turn-metadata"]`
+     * (JSON string of thread/turn identifiers); flat keys are also accepted.
+     */
+    clientMetadata?: Record<string, string>;
+    /**
+     * Invoked when the server streams a `response.metadata` event carrying
+     * ChatGPT moderation metadata (`metadata.openai_chatgpt_moderation_metadata`)
+     * for first-party presentation parity. Diagnostic observer: failures are
+     * swallowed and must not alter the stream.
+     */
+    onModerationMetadata?: (metadata: unknown) => void;
 }
 type CodexTransport = "sse" | "websocket";
+/**
+ * Per-session request-shape counters. Despite the name, these cover both
+ * transports: once stateful SSE chaining is enabled, SSE requests are counted
+ * too (the shared chained-request builder records every request it shapes).
+ */
 export interface OpenAICodexWebSocketDebugStats {
     fullContextRequests: number;
     deltaRequests: number;
@@ -21,7 +56,7 @@ export interface OpenAICodexWebSocketDebugStats {
 /** @internal Exported for tests. */
 export declare function normalizeCodexToolChoice(choice: ToolChoice | undefined, tools?: Tool[], model?: Model<"openai-codex-responses">): string | Record<string, unknown> | undefined;
 export declare const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses">;
-export declare function prewarmOpenAICodexResponses(model: Model<"openai-codex-responses">, options?: Pick<OpenAICodexResponsesOptions, "apiKey" | "headers" | "sessionId" | "signal" | "preferWebsockets" | "providerSessionState">): Promise<void>;
+export declare function prewarmOpenAICodexResponses(model: Model<"openai-codex-responses">, options?: Pick<OpenAICodexResponsesOptions, "apiKey" | "headers" | "sessionId" | "signal" | "preferWebsockets" | "providerSessionState" | "responsesLite">): Promise<void>;
 export interface OpenAICodexTransportDetails {
     websocketPreferred: boolean;
     lastTransport?: CodexTransport;

package/dist/types/providers/openai-responses-shared.d.ts

@@ -100,8 +100,12 @@ type ReasoningOptions = {
 };
 /**
  * Apply reasoning-related Responses parameters: enable encrypted reasoning content for replay,
- * set effort/summary when requested, and otherwise inject the GPT-5 "Juice: 0" no-reasoning hack.
- * Mutates `params` and may push a developer message into `messages`.
+ * set effort/summary when requested, and otherwise inject the "Juice: 0" no-reasoning hack
+ * when `model.compat.requiresJuiceZeroHack` is set (GPT-5 family by default).
+ * Mutates `params` and may push a developer message into `messages`. Returns
+ * the number of per-turn trailing scaffolding items appended to `messages`
+ * (the "Juice: 0" developer item), so callers doing stateful
+ * `previous_response_id` chaining can exclude them from append-baseline math.
  *
  * @param omitReasoningEffort - When `true`, suppresses `params.reasoning.effort` from the wire
  *   body. Set by `xai-responses.ts` via {@link OpenAIResponsesOptions.omitReasoningEffort} for
@@ -112,7 +116,7 @@ type ReasoningOptions = {
  *   without needing explicit activation. Callers that pass `options.reasoning` for such models
  *   should expect this documented downgrade: the model will reason, but at its default effort.
  */
-export declare function applyResponsesReasoningParams<P extends OpenAI.Responses.ResponseCreateParamsStreaming>(params: P, model: Model<Api>, options: ReasoningOptions | undefined, messages: ResponseInput, mapEffort?: (effort: string) => string, includeEncryptedReasoning?: boolean, omitReasoningEffort?: boolean): void;
+export declare function applyResponsesReasoningParams<P extends OpenAI.Responses.ResponseCreateParamsStreaming>(params: P, model: Model<"openai-responses" | "azure-openai-responses" | "openai-codex-responses">, options: ReasoningOptions | undefined, messages: ResponseInput, mapEffort?: (effort: string) => string, includeEncryptedReasoning?: boolean, omitReasoningEffort?: boolean): number;
 /** Populate `output.usage` from a Responses-API `response.usage` payload. Does not invoke `calculateCost`. */
 export declare function populateResponsesUsageFromResponse(output: AssistantMessage, usage: {
     input_tokens?: number | null;
@@ -125,4 +129,18 @@ export declare function populateResponsesUsageFromResponse(output: AssistantMess
         reasoning_tokens?: number | null;
     } | null;
 } | null | undefined): void;
+/**
+ * Strict-prefix delta for stateful `previous_response_id` chaining (used by the
+ * platform Responses provider and the Codex provider on both transports):
+ * returns the input items the current request appends beyond the previous
+ * request's input plus the previous response's output items, or null when the
+ * request options differ or history mutated (the chain must break). Per-turn
+ * `client_metadata` (e.g. rotating turn ids) is excluded from the option
+ * comparison; codex-rs excludes it from the same check.
+ */
+export declare function buildResponsesDeltaInput<TItem>(previous: {
+    input?: unknown;
+} | undefined, previousResponseItems: readonly TItem[] | undefined, current: {
+    input?: unknown;
+}): TItem[] | null;
 export {};

package/dist/types/providers/openai-responses.d.ts

@@ -7,6 +7,16 @@ export interface OpenAIResponsesOptions extends StreamOptions {
     reasoningSummary?: "auto" | "detailed" | "concise" | null;
     serviceTier?: ServiceTier;
     toolChoice?: ToolChoice;
+    /**
+     * Stateful turns: chain via `previous_response_id` + delta input instead of
+     * replaying the full transcript. Forces `store: true` (the platform only
+     * resolves stored responses). Defaults ON against the official OpenAI API
+     * and OFF for other Responses endpoints; `PI_OPENAI_STATEFUL` overrides the
+     * default, and `false` here vetoes everything. Requires `sessionId` +
+     * `providerSessionState`. Falls back to a full replay whenever history
+     * mutates or the server reports a stale id.
+     */
+    statefulResponses?: boolean;
     /**
      * Enforce strict tool call/result pairing when building Responses API inputs.
      * Azure OpenAI and GitHub Copilot Responses paths require tool results to match prior tool calls.

package/dist/types/providers/pi-native-client.d.ts

@@ -1,4 +1,13 @@
+import { ProviderHttpError } from "../errors";
 import type { Api, AssistantMessageEventStream as AssistantMessageEventStreamType, Context, Model, SimpleStreamOptions } from "../types";
+/**
+ * Non-2xx response from the auth-gateway `/v1/pi/stream` endpoint. `code`
+ * carries the gateway's error-type token (`authentication_error`,
+ * `rate_limit_error`, `upstream_error`, ...).
+ */
+export declare class AuthGatewayError extends ProviderHttpError {
+    constructor(message: string, status: number, headers?: Headers, code?: string);
+}
 /**
  * Stream a turn through an `omp auth-gateway` over the pi-native protocol.
  *