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

package/CHANGELOG.md

@@ -2,7 +2,31 @@
 
 ## [Unreleased]
 
+## [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 +3298,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-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

@@ -430,6 +430,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) | ({
@@ -581,6 +592,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.
      */

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";

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

package/dist/types/utils/http-inspector.d.ts

@@ -15,7 +15,6 @@ export type CapturedHttpErrorResponse = {
 };
 export declare function appendRawHttpRequestDumpFor400(message: string, error: unknown, dump: RawHttpRequestDump | undefined): Promise<string>;
 export declare function finalizeErrorMessage(error: unknown, rawRequestDump: RawHttpRequestDump | undefined, capturedErrorResponse?: CapturedHttpErrorResponse): Promise<string>;
-export declare function withHttpStatus(error: unknown, status: number): Error;
 /**
  * Rewrite error message for GitHub Copilot request failures.
  * Must run AFTER finalizeErrorMessage since it replaces the message entirely.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "15.11.3",
+	"version": "15.11.4",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,8 +38,8 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-catalog": "15.11.3",
-		"@oh-my-pi/pi-utils": "15.11.3",
+		"@oh-my-pi/pi-catalog": "15.11.4",
+		"@oh-my-pi/pi-utils": "15.11.4",
 		"openai": "^6.39.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/auth-retry.ts

@@ -1,4 +1,5 @@
 import { extractHttpStatusFromError } from "@oh-my-pi/pi-utils";
+import type { OAuthAccess } from "./auth-storage";
 import { isUsageLimitError } from "./rate-limit-utils";
 
 /**
@@ -139,3 +140,99 @@ export async function withAuth<T>(
 
 	throw lastError;
 }
+
+/**
+ * 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 async function withOAuthAccess<T>(
+	storage: OAuthAccessSource,
+	provider: string,
+	attempt: (access: OAuthAccess) => Promise<T>,
+	opts?: WithOAuthAccessOptions,
+): Promise<T> {
+	const isAuthError = opts?.isAuthError ?? isAuthRetryableError;
+	const { sessionId, signal } = opts ?? {};
+
+	let lastAccess = opts?.seed ?? (await storage.getOAuthAccess(provider, sessionId, { signal }));
+	if (!lastAccess) {
+		throw new Error(opts?.missingAccessMessage ?? `No OAuth credential available for provider: ${provider}`);
+	}
+
+	const resolveStep = async (lastChance: boolean, error: unknown): Promise<OAuthAccess | undefined> => {
+		try {
+			if (!lastChance) return await storage.getOAuthAccess(provider, sessionId, { forceRefresh: true, signal });
+			await storage.rotateSessionCredential(provider, sessionId, { error, signal });
+			return await storage.getOAuthAccess(provider, sessionId, { signal });
+		} catch {
+			return undefined;
+		}
+	};
+
+	let lastError: unknown;
+	try {
+		return await attempt(lastAccess);
+	} catch (error) {
+		if (!isAuthError(error)) throw error;
+		lastError = error;
+	}
+
+	for (const lastChance of AUTH_RETRY_STEPS) {
+		const next = await resolveStep(lastChance, lastError);
+		if (!next || next.accessToken === lastAccess.accessToken) continue;
+		lastAccess = next;
+		try {
+			return await attempt(next);
+		} catch (error) {
+			if (!isAuthError(error)) throw error;
+			lastError = error;
+		}
+	}
+
+	throw lastError;
+}