@oh-my-pi/pi-ai 17.4.0 → 17.4.2

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

@@ -71,6 +71,8 @@ export interface AuthRetryKeyState {
     refreshedCurrent: boolean;
     /** Whether the legacy non-usage auth path already switched to one sibling. */
     legacyAuthSwitchUsed: boolean;
+    /** Whether this operation already replayed once after an explicit token-refresh request. */
+    tokenRefreshReplayUsed?: boolean;
     /** Total outbound attempts accepted for this logical operation, including the initial request. */
     attempts: number;
 }
@@ -83,9 +85,11 @@ export declare function resolveNextAuthRetryKey(state: AuthRetryKeyState, resolv
  *   retry (identical to the legacy static-key path).
  * - A resolver → initial `attempt`, then resolver-driven retries until the
  *   applicable policy is exhausted, the resolver declines or cycles, or the
- *   operation reaches {@link AUTH_RETRY_MAX_ATTEMPTS}. Ordinary 401/auth
- *   failures retain one refresh-same plus one sibling switch; 403/usage-limit
- *   failures rotate directly through distinct siblings.
+ *   operation reaches {@link AUTH_RETRY_MAX_ATTEMPTS}. An explicit typed
+ *   token-refresh request gets exactly one refresh-current replay and never
+ *   enters sibling rotation. Ordinary 401/auth failures retain one
+ *   refresh-same plus one sibling switch; 403/usage-limit failures rotate
+ *   directly through distinct siblings.
  *
  * Used by non-streaming consumers (image generation, web search, completion
  * helpers). The streaming driver in `stream.ts` implements the same policy with
@@ -134,6 +138,7 @@ export interface WithOAuthAccessOptions {
  * `projectId`, `enterpriseUrl`) instead of bare API-key bytes.
  *
  * - initial → `getOAuthAccess` (or `opts.seed`).
+ * - typed token-refresh request → one forced refresh-current replay, then stop.
  * - 401/auth failure → one `getOAuthAccess` with `forceRefresh: true` for the
  *   current account, then sibling rotation.
  * - 403/usage-limit failure → `rotateSessionCredential` directly, without a

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

@@ -742,6 +742,15 @@ export declare class AuthStorage {
      * Remove a runtime API key override.
      */
     removeRuntimeApiKey(provider: string): void;
+    /**
+     * Install a runtime usage provider override (not persisted to disk).
+     *
+     * Runtime overrides are checked before the configured resolver, including its
+     * built-in fallback. Removing the override restores that resolver unchanged.
+     */
+    setRuntimeUsageProvider(provider: Provider, usageProvider: UsageProvider, apiKey?: string): void;
+    /** Remove a runtime usage provider override and restore configured/default resolution. */
+    removeRuntimeUsageProvider(provider: Provider): void;
     /**
      * Register a per-provider API key sourced from user configuration
      * (e.g. `models.yml` `providers.<name>.apiKey`). Higher priority than

package/dist/types/dialect/qwen-xml.d.ts

@@ -0,0 +1,6 @@
+import type { InbandScanEvent, InbandScanner } from "./types.js";
+export declare class QwenXmlInbandScanner implements InbandScanner {
+    #private;
+    feed(chunk: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}

package/dist/types/error/auth-classify.d.ts

@@ -8,13 +8,13 @@ export declare function isDefinitiveOAuthFailure(errorMsg: string): boolean;
 /** Whether an upstream response explicitly says the supplied OAuth bearer was invalidated. */
 export declare function isInvalidatedOAuthTokenError(error: unknown): boolean;
 /**
- * Whether an upstream failure should rotate to a sibling credential: a hard
- * `401`, a `403` (token valid but access denied — plan, model policy, or org
- * restriction a sibling account may not share), an account-scoped policy
- * denial such as Codex `cyber_policy`, a body-classified usage limit (Codex
- * `usage_limit_reached`, Anthropic account rate-limit, Google
- * `resource_exhausted`, OpenAI `insufficient_quota`, …), or a bare `429`
- * whose payload did not preserve a richer quota code. Transient 429s
- * (`Too many requests`, per-minute caps) stay in the upstream-backoff lane.
+ * Whether an upstream failure should retry through the credential resolver: a
+ * typed token-refresh request, a hard `401`, a `403` (token valid but access
+ * denied — plan, model policy, or org restriction a sibling account may not
+ * share), an account-scoped policy denial such as Codex `cyber_policy`, a
+ * body-classified usage limit (Codex `usage_limit_reached`, Anthropic account
+ * rate-limit, Google `resource_exhausted`, OpenAI `insufficient_quota`, …), or
+ * a bare `429` whose payload did not preserve a richer quota code. Transient
+ * 429s (`Too many requests`, per-minute caps) stay in the upstream-backoff lane.
  */
 export declare function isAuthRetryableError(error: unknown): boolean;

package/dist/types/error/oauth.d.ts

@@ -33,7 +33,8 @@ export interface OAuthErrorOptions {
 /**
  * A failure inside an interactive OAuth / device-code login flow. The `kind`
  * pinpoints the stage. Timeout/polling are classified transient; everything
- * else is a hard auth failure so the credential layer does not silently retry.
+ * else is a hard auth failure. The auth-retry classifier separately treats
+ * `token-refresh` as an explicit request to refresh and replay once.
  */
 export declare class OAuthError extends Error {
     readonly kind: OAuthErrorKind;

package/dist/types/providers/cursor/exec-modern.d.ts

@@ -17,7 +17,7 @@ import type { ToolResultMessage } from "../../types.js";
  * virtual registry. Re-exported here because this is where the frame builders
  * and their translation are consumed together.
  */
-export { omitUndefinedArgs, piEscapeRegexLiteral, piGrepSkip, piJoinPath, piLimit, piLsPath, piReadDisplayPath, piReadPath, piReadPathHasRange, piTimeout, } from "../cursor-pi-args.js";
+export { cursorEditOwnedReadPath, cursorRawReadPath, omitUndefinedArgs, piEscapeRegexLiteral, piGrepSkip, piJoinPath, piLimit, piLsPath, piReadDisplayPath, piReadPath, piReadPathHasRange, piTimeout, } from "../cursor-pi-args.js";
 /** Flatten a tool result's content into the single `output` string the Pi frames carry. */
 export declare function piOutputText(toolResult: ToolResultMessage): string;
 /**

package/dist/types/providers/cursor-pi-args.d.ts

@@ -42,6 +42,27 @@ export declare function piReadPath(readPath: string, offset?: number, limit?: nu
  * the coding-agent read tool; the selector remains embedded in the path.
  */
 export declare function piReadPathHasRange(readPath: string): boolean;
+/**
+ * Force a Cursor exec read onto `read`'s verbatim `:raw` selector.
+ *
+ * Native `editToolCall` (StrReplace) materializes via `readArgs` then
+ * `writeArgs`. The server treats the read result as file bytes and writes
+ * them back. A hashline-formatted native read (`[path#TAG]` + `LINE:`
+ * prefixes) poisons that cycle: the write would persist the markup.
+ * `:raw` is the existing selector that drops both. A path that already
+ * carries `raw` is left alone; a range-only selector gets `raw` inserted
+ * so the range still applies without the gutter.
+ */
+export declare function cursorRawReadPath(readPath: string): string;
+/**
+ * Path the edit-owned materialization read should execute.
+ *
+ * Range is composed first (`piReadPath` already uses `:raw` for a range),
+ * then a whole-file path is forced onto `:raw`. The caller must drop
+ * `offset`/`limit` after this so the bridge's `piReadPath` cannot append a
+ * second `:raw` onto the already-composed selector.
+ */
+export declare function cursorEditOwnedReadPath(readPath: string, offset?: number, limit?: number): string | null;
 /**
  * The same range as {@link piReadPath}, rendered for a transcript block rather
  * than for execution.

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

@@ -1,5 +1,5 @@
 import http2 from "node:http2";
-import type { McpToolDefinition } from "@oh-my-pi/pi-catalog/discovery/cursor-proto";
+import type { CursorRule, McpToolDefinition } from "@oh-my-pi/pi-catalog/discovery/cursor-proto";
 import { type AgentServerMessage, type ConversationStateStructure } from "@oh-my-pi/pi-catalog/discovery/cursor-proto";
 import { type JsonValue } from "@oh-my-pi/pi-catalog/discovery/protobuf";
 import type { AssistantMessage, Context, CursorExecHandlerResult, CursorExecHandlers, CursorExecPairing, CursorTodoSyncHandler, CursorToolResultHandler, Message, Model, StreamFunction, StreamOptions, TextContent, ThinkingContent, Tool, ToolCall, ToolResultMessage } from "../types.js";
@@ -12,6 +12,8 @@ export interface CursorOptions extends StreamOptions {
     conversationId?: string;
     execHandlers?: CursorExecHandlers;
     onToolResult?: CursorToolResultHandler;
+    /** Wire model id selected after thinking-effort routing (`resolveWireModelId`). */
+    wireModelId?: string;
 }
 /**
  * Maps an opaque HTTP/2 negotiation failure into an actionable error.
@@ -32,7 +34,7 @@ export type ToolCallState = ToolCall & {
     [kStreamingBlockIndex]: number;
     [kStreamingPartialJson]?: string;
     [kStreamingLastParseLen]?: number;
-    [kStreamingBlockKind]: "mcp" | "todo" | "cursor-exec" | "connect-scm" | "web-fetch";
+    [kStreamingBlockKind]: "mcp" | "todo" | "cursor-exec" | "cursor-edit" | "connect-scm" | "web-fetch";
     [kStreamingEnvelopeId]?: string;
     [kCursorExecResolved]?: true;
 };
@@ -57,6 +59,17 @@ export interface BlockState {
     openToolCalls: Map<string, ToolCallState>;
     /** MCP call IDs synthesized from exec frames before their redundant streamed block arrives. */
     resolvedMcpToolCallIds: Set<string>;
+    /**
+     * Native `editToolCall` (StrReplace) ids whose materialization `readArgs` /
+     * `writeArgs` must stay raw and must not synthesize extra transcript blocks.
+     *
+     * Optional so existing test harnesses stay valid. Both the interaction
+     * envelope `call_id` and the inner `toolCallId` are recorded — exec frames
+     * pair on the inner id.
+     */
+    editOwnedToolCallIds?: Set<string>;
+    /** Edit blocks whose write already persisted a `toolResult`. */
+    pairedEditToolCallIds?: Set<string>;
     firstTokenTime: number | undefined;
     setTextBlock: (b: (TextContent & {
         [kStreamingBlockIndex]: number;
@@ -79,7 +92,7 @@ export interface UsageState {
     sawTokenDelta: boolean;
 }
 /** Exported for tests: drives one Cursor server message through the stream (exec waits mark the stream busy). */
-export declare function handleServerMessage(msg: AgentServerMessage, output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState, blobStore: Map<string, Uint8Array>, h2Request: http2.ClientHttp2Stream, execHandlers: CursorExecHandlers | undefined, onToolResult: CursorToolResultHandler | undefined, usageState: UsageState, requestContextTools: McpToolDefinition[], onConversationCheckpoint?: (checkpoint: ConversationStateStructure) => void): Promise<void>;
+export declare function handleServerMessage(msg: AgentServerMessage, output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState, blobStore: Map<string, Uint8Array>, h2Request: http2.ClientHttp2Stream, execHandlers: CursorExecHandlers | undefined, onToolResult: CursorToolResultHandler | undefined, usageState: UsageState, requestContextTools: McpToolDefinition[], requestContextRules?: CursorRule[], onConversationCheckpoint?: (checkpoint: ConversationStateStructure) => void): Promise<void>;
 /**
  * Exported for tests: verifies handler is invoked with correct `this` when passed as bound.
  *
@@ -191,6 +204,13 @@ export declare function mergeCursorMcpToolCallArgs(streamed: Record<string, unkn
 export declare function synthesizeCursorExecToolCall(output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState, toolCallId: string, toolName: string, args: Record<string, unknown>): void;
 /** Exported for tests: drives one Cursor interaction update through the streaming state machine. */
 export declare function processInteractionUpdate(update: any, output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState, usageState: UsageState): void;
+/**
+ * Cursor AgentService reconstructs the model prompt from `requestContext.rules`,
+ * not from the client-supplied `rootPromptMessagesJson` system blobs. Map each
+ * OMP system-prompt entry to a global CursorRule so always-apply rules survive
+ * that reconstruction.
+ */
+export declare function buildCursorRequestContextRules(systemPrompt: readonly string[] | undefined): CursorRule[];
 export declare function buildMcpToolDefinitions(tools: Tool[] | undefined): McpToolDefinition[];
 /**
  * Build `ConversationStateStructure.rootPromptMessagesJson` blob IDs for the

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

@@ -42,9 +42,15 @@ export interface Part {
     thought?: boolean;
     thoughtSignature?: string;
     inlineData?: InlineDataPart;
+    fileData?: FileDataPart;
     functionCall?: FunctionCallPart;
     functionResponse?: FunctionResponsePart;
 }
+/** Remote media reference; the backend fetches `fileUri` server-side. */
+export interface FileDataPart {
+    fileUri: string;
+    mimeType?: string;
+}
 /** Conversation turn. Roles: `"user"`, `"model"`, optionally absent for system instructions. */
 export interface Content {
     role?: string;

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

@@ -118,6 +118,8 @@ export interface MockModelOptions {
     id?: string;
     /** Provider string used in the returned AssistantMessage. Defaults to `"mock"`. */
     provider?: string;
+    /** Base URL reported by the model. Defaults to `"mock://"`. */
+    baseUrl?: string;
     /** A sequence of responses, one per call. Accepts arrays, generators, or any iterable. */
     responses?: MockResponseSource;
     /** Fallback handler used when `responses` is exhausted. */
@@ -141,7 +143,7 @@ export declare class MockModel implements Model<MockApi> {
     readonly name: string;
     readonly api: MockApi;
     readonly provider: string;
-    readonly baseUrl = "mock://";
+    readonly baseUrl: string;
     readonly reasoning: boolean;
     readonly input: ("text" | "image")[];
     readonly cost: Model["cost"];

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

@@ -520,7 +520,12 @@ export interface SequentialCutoffSummaryState {
 export declare function createSequentialCutoffSummaryState(): SequentialCutoffSummaryState;
 /** Chooses final reasoning text without making sequential-cutoff results disagree with emitted deltas. */
 export declare function finalizeReasoningThinking(item: ResponseReasoningItem, streamedThinking: string, cutoff?: SequentialCutoffSummaryState): string;
-export declare function appendReasoningSummaryTextDelta(item: ResponseReasoningItem, block: ThinkingContent, delta: string, stream: AssistantMessageEventStream, output: AssistantMessage, contentIndex: number): void;
+export declare function appendReasoningSummaryTextDelta(item: ResponseReasoningItem, block: ThinkingContent, delta: string, stream: AssistantMessageEventStream, output: AssistantMessage, contentIndex: number, summaryIndex?: number): void;
+/**
+ * Applies a completed reasoning-summary snapshot, including providers that omit
+ * the preceding summary-part event.
+ */
+export declare function applyReasoningSummaryTextDone(item: ResponseReasoningItem, block: ThinkingContent, text: string, summaryIndex: number, stream: AssistantMessageEventStream, output: AssistantMessage, contentIndex: number): void;
 export declare function appendReasoningSummaryPartDone(item: ResponseReasoningItem, block: ThinkingContent, stream: AssistantMessageEventStream, output: AssistantMessage, contentIndex: number): void;
 /**
  * Applies an atomic `response.reasoning_summary_text.done` snapshot.

package/dist/types/registry/oauth/google-antigravity.d.ts

@@ -1,13 +1,9 @@
 import type { OAuthController, OAuthCredentials } from "./types.js";
+/** Cloud Code Assist metadata sent by native Antigravity control-plane requests. */
 export declare const ANTIGRAVITY_LOAD_CODE_ASSIST_METADATA: Readonly<{
     ideType: "ANTIGRAVITY";
 }>;
-export interface AntigravityOnboardMetadata {
-    ide_type: string;
-    ide_version: string;
-    ide_name: string;
-}
-export declare function getAntigravityOnboardMetadata(): AntigravityOnboardMetadata;
+/** Authenticate an Antigravity account and resolve its Cloud Code Assist project. */
 export declare function loginAntigravity(ctrl: OAuthController): Promise<OAuthCredentials>;
 /**
  * Refresh Antigravity token

package/dist/types/registry/oauth/index.d.ts

@@ -19,10 +19,9 @@ export declare function getOAuthProvider(id: OAuthProviderId): OAuthProviderInte
  */
 export declare function unregisterOAuthProviders(sourceId: string): void;
 /**
- * Refresh token for any OAuth provider.
- * Saves the new credentials and returns the new access token.
+ * Refresh a built-in OAuth grant, cancelling provider work when refresh ownership ends.
  */
-export declare function refreshOAuthToken(provider: OAuthProvider, credentials: OAuthCredentials): Promise<OAuthCredentials>;
+export declare function refreshOAuthToken(provider: OAuthProvider, credentials: OAuthCredentials, signal?: AbortSignal): Promise<OAuthCredentials>;
 /**
  * Build API-key bytes for a provider from an already-fresh OAuth credential.
  *

package/dist/types/registry/oauth/types.d.ts

@@ -80,7 +80,8 @@ export interface OAuthProviderInterface {
     readonly name: string;
     readonly sourceId?: string;
     login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials | string>;
-    refreshToken?(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+    /** Refresh a stored grant; the signal bounds provider network work to refresh ownership. */
+    refreshToken?(credentials: OAuthCredentials, signal?: AbortSignal): Promise<OAuthCredentials>;
     getApiKey?(credentials: OAuthCredentials): string;
     /** Store resulting OAuth credentials under a different provider id. */
     readonly storeCredentialsAs?: string;

package/dist/types/registry/oauth/xai-oauth.d.ts

@@ -41,6 +41,6 @@ export declare function loginXAIOAuth(ctrl: OAuthController): Promise<OAuthCrede
  * Refresh an xAI OAuth access token using a stored refresh_token.
  *
  * Re-runs OIDC discovery and re-validates the token endpoint before sending
- * the stored refresh token.
+ * the stored refresh token. Caller cancellation aborts every network request.
  */
-export declare function refreshXAIOAuthToken(refreshToken: string, fetchOverride?: FetchImpl): Promise<OAuthCredentials>;
+export declare function refreshXAIOAuthToken(refreshToken: string, fetchOverride?: FetchImpl, signal?: AbortSignal): Promise<OAuthCredentials>;

package/dist/types/registry/registry.d.ts

@@ -325,7 +325,7 @@ declare const ALL: ({
     readonly id: "xai-oauth";
     readonly name: "xAI Grok OAuth (SuperGrok or X Premium+)";
     readonly login: (cb: import("./oauth/index.js").OAuthLoginCallbacks) => Promise<import("./oauth/index.js").OAuthCredentials>;
-    readonly refreshToken: (credentials: import("./oauth/index.js").OAuthCredentials) => Promise<import("./oauth/index.js").OAuthCredentials>;
+    readonly refreshToken: (credentials: import("./oauth/index.js").OAuthCredentials, signal?: AbortSignal) => Promise<import("./oauth/index.js").OAuthCredentials>;
 } | {
     readonly id: "xiaomi";
     readonly name: "Xiaomi MiMo";

package/dist/types/registry/types.d.ts

@@ -64,7 +64,8 @@ export interface ProviderDefinition {
     /** Provider-owned authentication and endpoint setup for model discovery. */
     readonly prepareModelDiscovery?: ProviderModelDiscoveryPreparer;
     readonly login?: (callbacks: OAuthLoginCallbacks) => Promise<OAuthCredentials | string>;
-    readonly refreshToken?: (credentials: OAuthCredentials) => Promise<OAuthCredentials>;
+    /** Refresh a stored grant; the signal bounds provider network work to refresh ownership. */
+    readonly refreshToken?: (credentials: OAuthCredentials, signal?: AbortSignal) => Promise<OAuthCredentials>;
     readonly getApiKey?: (credentials: OAuthCredentials) => string;
     /** Store OAuth credentials under a different provider id (e.g. `openai-codex-device` ⇒ `openai-codex`). */
     readonly storeCredentialsAs?: string;

package/dist/types/registry/xai-oauth.d.ts

@@ -3,5 +3,5 @@ export declare const xaiOauthProvider: {
     readonly id: "xai-oauth";
     readonly name: "xAI Grok OAuth (SuperGrok or X Premium+)";
     readonly login: (cb: OAuthLoginCallbacks) => Promise<OAuthCredentials>;
-    readonly refreshToken: (credentials: OAuthCredentials) => Promise<OAuthCredentials>;
+    readonly refreshToken: (credentials: OAuthCredentials, signal?: AbortSignal) => Promise<OAuthCredentials>;
 };

package/dist/types/types.d.ts

@@ -317,6 +317,8 @@ export interface StreamOptions {
     providerSessionState?: Map<string, ProviderSessionState>;
     /** Canonical Codex compaction classification; ignored by other providers. */
     codexCompaction?: CodexCompactionRequestContext;
+    /** Codex Code Mode tool exposure snapshot emitted as `tool_namespaces_info` turn metadata; ignored by other providers. */
+    toolNamespacesInfo?: unknown;
     /**
      * Optional per-provider concurrent request cap for LLM stream calls. Keys are
      * provider ids (`model.provider`); positive numeric values cap in-flight
@@ -540,6 +542,13 @@ export interface AnthropicServerToolContent {
         [key: string]: unknown;
     };
 }
+/** Provider-native uploaded file reference for image reuse without retransmitting bytes. */
+export interface ProviderFileReference {
+    provider: "openai" | "anthropic" | "google";
+    id?: string;
+    uri?: string;
+    expiresAt?: number;
+}
 export interface ImageContent {
     type: "image";
     data: string;
@@ -550,6 +559,18 @@ export interface ImageContent {
      * default `auto` downscale). Providers without a detail knob ignore it.
      */
     detail?: "auto" | "low" | "high" | "original";
+    /** Provider-native file reference preferred only by its matching provider. */
+    providerFile?: ProviderFileReference;
+    /**
+     * Optional https mirror of `data`, served by a caller-run blob server.
+     * Providers whose API fetches remote images send this URL instead of the
+     * base64 payload; every other provider ignores it. `data` remains the
+     * source of truth — the URL must serve exactly those bytes, and callers
+     * are responsible for keeping it stable across turns (prefix caches hash
+     * the URL string, and Anthropic silently forgets images when a resent
+     * turn differs byte-wise).
+     */
+    url?: string;
 }
 export type ComputerAction = {
     type: "click";

package/dist/types/utils/stream-markup-healing.d.ts

@@ -11,7 +11,7 @@ export interface HealedToolCall {
     readonly name: string;
     readonly arguments: string;
 }
-export type StreamMarkupHealingPattern = "kimi" | "dsml" | "thinking";
+export type StreamMarkupHealingPattern = "kimi" | "dsml" | "qwen" | "thinking";
 export interface StreamMarkupHealingOptions {
     readonly pattern: StreamMarkupHealingPattern;
 }

package/package.json

@@ -1,10 +1,10 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.4.0",
+	"version": "17.4.2",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
-	"author": "Can Boluk",
+	"author": "Stencil Labs, Inc.",
 	"contributors": [
 		"Mario Zechner"
 	],
@@ -37,10 +37,10 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "17.4.0",
-		"@oh-my-pi/pi-catalog": "17.4.0",
-		"@oh-my-pi/pi-utils": "17.4.0",
-		"@oh-my-pi/pi-wire": "17.4.0"
+		"@oh-my-pi/omptype": "17.4.2",
+		"@oh-my-pi/pi-catalog": "17.4.2",
+		"@oh-my-pi/pi-utils": "17.4.2",
+		"@oh-my-pi/pi-wire": "17.4.2"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"
@@ -52,6 +52,8 @@
 		"src",
 		"README.md",
 		"CHANGELOG.md",
+		"LICENSE",
+		"THIRD-PARTY-NOTICES.txt",
 		"dist/types"
 	],
 	"exports": {

package/src/auth-retry.ts

@@ -130,6 +130,8 @@ export interface AuthRetryKeyState {
 	refreshedCurrent: boolean;
 	/** Whether the legacy non-usage auth path already switched to one sibling. */
 	legacyAuthSwitchUsed: boolean;
+	/** Whether this operation already replayed once after an explicit token-refresh request. */
+	tokenRefreshReplayUsed?: boolean;
 	/** Total outbound attempts accepted for this logical operation, including the initial request. */
 	attempts: number;
 }
@@ -140,6 +142,7 @@ export function createAuthRetryKeyState(initialKey: string): AuthRetryKeyState {
 		lastKey: initialKey,
 		refreshedCurrent: false,
 		legacyAuthSwitchUsed: false,
+		tokenRefreshReplayUsed: false,
 		attempts: 1,
 	};
 }
@@ -161,6 +164,14 @@ export async function resolveNextAuthRetryKey(
 ): Promise<string | undefined> {
 	if (signal?.aborted) return undefined;
 	if (state.attempts >= AUTH_RETRY_MAX_ATTEMPTS) return undefined;
+	if (error instanceof AIError.OAuthError && error.kind === "token-refresh") {
+		if (state.tokenRefreshReplayUsed) return undefined;
+		state.tokenRefreshReplayUsed = true;
+		const refreshed = await resolveRetryKey(resolver, false, error, signal, state.lastKey);
+		state.refreshedCurrent = true;
+		if (signal?.aborted || refreshed === undefined) return undefined;
+		return acceptRetryKey(state, refreshed, true);
+	}
 	const directRotation = isDirectCredentialRotationError(error);
 	if (!directRotation) {
 		if (state.legacyAuthSwitchUsed) return undefined;
@@ -207,9 +218,11 @@ async function runOAuthAttempt<T>(
  *   retry (identical to the legacy static-key path).
  * - A resolver → initial `attempt`, then resolver-driven retries until the
  *   applicable policy is exhausted, the resolver declines or cycles, or the
- *   operation reaches {@link AUTH_RETRY_MAX_ATTEMPTS}. Ordinary 401/auth
- *   failures retain one refresh-same plus one sibling switch; 403/usage-limit
- *   failures rotate directly through distinct siblings.
+ *   operation reaches {@link AUTH_RETRY_MAX_ATTEMPTS}. An explicit typed
+ *   token-refresh request gets exactly one refresh-current replay and never
+ *   enters sibling rotation. Ordinary 401/auth failures retain one
+ *   refresh-same plus one sibling switch; 403/usage-limit failures rotate
+ *   directly through distinct siblings.
  *
  * Used by non-streaming consumers (image generation, web search, completion
  * helpers). The streaming driver in `stream.ts` implements the same policy with
@@ -296,6 +309,7 @@ export interface WithOAuthAccessOptions {
  * `projectId`, `enterpriseUrl`) instead of bare API-key bytes.
  *
  * - initial → `getOAuthAccess` (or `opts.seed`).
+ * - typed token-refresh request → one forced refresh-current replay, then stop.
  * - 401/auth failure → one `getOAuthAccess` with `forceRefresh: true` for the
  *   current account, then sibling rotation.
  * - 403/usage-limit failure → `rotateSessionCredential` directly, without a
@@ -331,6 +345,7 @@ export async function withOAuthAccess<T>(
 	let attemptCount = 1;
 	let legacyAuthSwitchUsed = false;
 	let refreshedCurrent = false;
+	let tokenRefreshReplayUsed = false;
 	let attemptResult = await runOAuthAttempt(lastAccess, attempt, isAuthError);
 	if (attemptResult.ok) return attemptResult.result;
 
@@ -338,6 +353,29 @@ export async function withOAuthAccess<T>(
 	while (true) {
 		let next: OAuthAccess | undefined;
 		if (signal?.aborted || attemptCount >= AUTH_RETRY_MAX_ATTEMPTS) break;
+		const tokenRefreshReplay = lastError instanceof AIError.OAuthError && lastError.kind === "token-refresh";
+		if (tokenRefreshReplay) {
+			if (tokenRefreshReplayUsed) break;
+			tokenRefreshReplayUsed = true;
+			refreshedCurrent = true;
+			try {
+				next = await storage.getOAuthAccess(provider, sessionId, { forceRefresh: true, signal });
+			} catch {
+				next = undefined;
+			}
+			if (signal?.aborted || !next) break;
+			const bearer = next.accessToken;
+			if (attemptedBearers.has(bearer) || attemptCount >= AUTH_RETRY_MAX_ATTEMPTS) break;
+			attemptedCredentialIdentities.add(oauthCredentialIdentity(next));
+			attemptedBearers.add(bearer);
+			attemptCount += 1;
+			lastAccess = next;
+			attemptResult = await runOAuthAttempt(next, attempt, isAuthError);
+			if (attemptResult.ok) return attemptResult.result;
+			lastError = attemptResult.error;
+			continue;
+		}
+
 		const directRotation = isDirectCredentialRotationError(lastError);
 		if (!directRotation) {
 			if (legacyAuthSwitchUsed) break;