@oh-my-pi/pi-ai 18.13.2 → 18.14.0

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

@@ -1,8 +1,11 @@
-import type { CodexCompactionContext, CodexCompactionRequestContext, Context, Model, ProviderSessionState, ServiceTier, StreamFunction, StreamOptions, Tool, ToolChoice } from "../types.js";
-import { type CodexLiteShapedBody, type CodexReasoningContext, type InputItem, type RequestBody } from "./openai-codex/request-transformer.js";
+import type { CodexCompactionRequestContext, Context, Model, ProviderSessionState, RawSseEvent, ServiceTier, StreamFunction, StreamOptions, Tool, ToolChoice } from "../types.js";
+import { type HeadersLike } from "../utils/retry-after.js";
+import { type CodexLiteShapedBody, type CodexReasoningContext, type InputItem, type ReasoningConfig, type RequestBody } from "./openai-codex/request-transformer.js";
+import { type CodexAcceptedSteer, type CodexSteerAck } from "./openai-codex/live-steering.js";
 export { createOpenAICodexCompactionRequestContext } from "./openai-codex-compaction.js";
 export { setCodexAttestationProvider } from "./openai-codex-attestation.js";
 export type { CodexAttestationProvider } from "./openai-codex-attestation.js";
+import { type OpenAIEffortControlState } from "./openai-configuration-update.js";
 import type { ResponseInput } from "./openai-responses-wire.js";
 export interface OpenAICodexResponsesOptions extends StreamOptions {
     reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
@@ -76,13 +79,7 @@ export interface OpenAICodexCompatibilityMetadata {
     clientMetadata: Record<string, string>;
     headers: Record<string, string>;
 }
-/** Live Codex session state to preserve after a successful history rewrite. */
-export interface OpenAICodexCompactionResetOptions {
-    providerSessionState?: Map<string, ProviderSessionState>;
-    sessionId?: string;
-    compaction: CodexCompactionContext;
-}
-type CodexTransport = "sse" | "websocket";
+export type CodexTransport = "sse" | "websocket";
 /** Shape of the Codex request sent on the latest provider turn. */
 export interface OpenAICodexTurnRequestDiagnostics {
     transport: "sse" | "websocket";
@@ -132,18 +129,65 @@ export interface OpenAICodexWebSocketDebugStats {
     lastPreviousResponseId?: string;
     lastTurn?: OpenAICodexTurnDiagnostics;
 }
+/**
+ * Per-session transport state shared by both transports: WebSocket turn
+ * chaining, models-etag headers, connection pooling, and debug stats. The name
+ * is historical — SSE-only sessions use it too.
+ */
+export type CodexWebSocketSessionState = {
+    sessionId: string;
+    disableWebsocket: boolean;
+    lastRequest?: RequestBody;
+    /** Last completed response; an in-progress response cannot replace the retry baseline. */
+    lastResponseId?: string;
+    lastResponseItems?: InputItem[];
+    canAppend: boolean;
+    modelsEtag?: string;
+    connection?: CodexWebSocketConnection;
+    /**
+     * Steering the server accepted on `connection` for `lastResponseId`. The
+     * next request reads the server's automatic successor or sends only the
+     * pending tool output; see {@link planSteeredRequest}.
+     */
+    acceptedSteering?: {
+        connection: CodexWebSocketConnection;
+        steers: CodexAcceptedSteer[];
+    };
+    /** The server refused steering for this session (native turn lane); later responses are not steered. */
+    steeringUnsupported?: boolean;
+    lastTransport?: CodexTransport;
+    fallbackCount: number;
+    lastFallbackAt?: number;
+    prewarmed: boolean;
+    stats: OpenAICodexWebSocketDebugStats;
+};
+interface CodexTurnStateCell {
+    value?: string;
+}
+export interface CodexProviderSessionState extends ProviderSessionState {
+    webSocketSessions: Map<string, CodexWebSocketSessionState>;
+    webSocketPublicToPrivate: Map<string, string>;
+    metadataSessions: Map<string, CodexMetadataSessionState>;
+    /** `configuration_update` effort baselines, keyed by model + session. */
+    effortControls: Map<string, OpenAIEffortControlState<ReasoningConfig["effort"]>>;
+}
 /** Request classification encoded in Codex turn metadata. */
 export type OpenAICodexRequestKind = "turn" | "prewarm" | "compaction";
+interface CodexMetadataSessionState {
+    sessionId: string;
+    threadId: string;
+    windowId: string;
+    turnId?: string;
+    turnStartedAtUnixMs?: number;
+    compactionOperationId?: string;
+    reuseTurnForNextRequest?: boolean;
+    turnStates: Map<string, CodexTurnStateCell>;
+}
 /**
  * Synthesize Codex request identity for raw provider routes such as remote
  * compaction while reusing the live session's thread, window, and turn.
  */
 export declare function createOpenAICodexCompatibilityMetadata(options: OpenAICodexCompatibilityMetadataOptions): OpenAICodexCompatibilityMetadata;
-/**
- * Invalidate Codex history-dependent transport state after compaction while
- * retaining the session identity and live connection.
- */
-export declare function resetOpenAICodexHistoryAfterCompaction(options: OpenAICodexCompactionResetOptions): void;
 /** @internal Exported for tests. */
 export declare function normalizeCodexToolChoice(choice: ToolChoice | undefined, tools?: Tool[], model?: Model<"openai-codex-responses">): string | Record<string, unknown> | undefined;
 /** Serialize normal Codex turns and V2 compaction with the same cacheable prefix. */
@@ -155,29 +199,57 @@ export declare function buildTransformedCodexRequestBody(model: Model<"openai-co
 export declare function openCodexCompactionEventStream(model: Model<"openai-codex-responses">, body: OpenAICodexCompactionBody, options: OpenAICodexCompactionStreamOptions): Promise<AsyncGenerator<Record<string, unknown>>>;
 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" | "responsesLite" | "serviceTier">): Promise<void>;
-export interface OpenAICodexTransportDetails {
-    websocketPreferred: boolean;
-    lastTransport?: CodexTransport;
-    websocketDisabled: boolean;
-    websocketConnected: boolean;
-    fallbackCount: number;
-    canAppend: boolean;
-    prewarmed: boolean;
-    hasSessionState: boolean;
-    hasTurnState: boolean;
-    lastFallbackAt?: number;
+interface CodexWebSocketRequestTimeouts {
+    idleTimeoutMs?: number;
+    firstEventTimeoutMs?: number;
+}
+/** What {@link CodexWebSocketConnection.streamRequest} puts on the wire before reading a response. */
+type CodexWebSocketExchange = {
+    send: Record<string, unknown>;
+}
+/** Read the successor the server creates from accepted steering; nothing is sent. */
+ | {
+    attachSteerIds: readonly string[];
+};
+interface CodexWebSocketConnectionOptions {
+    onHandshakeHeaders?: (headers: Headers) => void;
+    proxy?: string;
+}
+declare class CodexWebSocketConnection {
+    #private;
+    constructor(url: string, headers: Record<string, string>, options: CodexWebSocketConnectionOptions);
+    isOpen(): boolean;
+    /** True while a handshake (possibly started by another caller) is still in flight. */
+    isConnecting(): boolean;
+    /** True while a handshake or a request stream is in flight on this socket. */
+    isBusy(): boolean;
+    /** True while a request stream owns this socket. */
+    hasActiveRequest(): boolean;
+    /**
+     * Stricter variant of {@link isOpen} for the connection-pool reuse gate.
+     * Refuses sockets that have been silent past {@link CODEX_WEBSOCKET_MAX_IDLE_REUSE_MS}.
+     *
+     * Bun's `WebSocket` does not always surface server-side eviction (no
+     * `onclose`, no `onerror`), so a socket can sit in readyState OPEN long
+     * after the upstream has dropped it. Reusing such a socket sends the next
+     * `response.create` into a half-open write buffer and parks the reader
+     * until the first-event / idle timeout fires (issue #1450). Forcing a
+     * reconnect on any suspect socket trades a sub-second handshake for a
+     * 60–300 s stall.
+     */
+    isHealthyForReuse(): boolean;
+    matchesAuth(headers: Record<string, string>): boolean;
+    close(reason?: string): void;
+    connect(signal?: AbortSignal): Promise<void>;
+    streamRequest(exchange: CodexWebSocketExchange, timeouts: CodexWebSocketRequestTimeouts, signal?: AbortSignal, onSseEvent?: (event: RawSseEvent) => void, onOwned?: () => void): AsyncGenerator<Record<string, unknown>>;
+    /**
+     * Submit `response.steer` for `previousResponseId`, which must be streaming
+     * on this socket. Resolves on the server's acknowledgement.
+     */
+    steer(previousResponseId: string, input: InputItem[]): Promise<CodexSteerAck>;
+    /** True when the server failed to commit any of the accepted steering `ids`. */
+    hasFailedSteer(ids: readonly string[]): boolean;
 }
-export declare function getOpenAICodexWebSocketDebugStats(model: Model<"openai-codex-responses">, options?: {
-    sessionId?: string;
-    baseUrl?: string;
-    providerSessionState?: Map<string, ProviderSessionState>;
-}): OpenAICodexWebSocketDebugStats | undefined;
-export declare function getOpenAICodexTransportDetails(model: Model<"openai-codex-responses">, options?: {
-    sessionId?: string;
-    baseUrl?: string;
-    preferWebsockets?: boolean;
-    providerSessionState?: Map<string, ProviderSessionState>;
-}): OpenAICodexTransportDetails;
 /** Resolve a Codex Responses endpoint exactly as the chat and compaction transports do. */
 export declare function resolveCodexResponsesUrl(baseUrl: string | undefined): string;
 declare function convertMessages(model: Model<"openai-codex-responses">, context: Context): ResponseInput;
@@ -210,7 +282,8 @@ export declare class CodexWebSocketTransportError extends Error {
 declare class CodexProviderStreamError extends Error {
     readonly retryable: boolean;
     readonly code?: string;
-    constructor(message: string, retryable: boolean, code?: string);
+    readonly headers?: HeadersLike;
+    constructor(message: string, retryable: boolean, code?: string, headers?: HeadersLike);
 }
 export declare function isRetryableCodexFailureEvent(rawEvent: Record<string, unknown>): boolean;
 export declare function createCodexProviderStreamError(rawEvent: Record<string, unknown>): CodexProviderStreamError;

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

@@ -0,0 +1,43 @@
+import type { CodexCompactionContext, Model, ProviderSessionState } from "../types.js";
+import type { CodexProviderSessionState, CodexTransport, CodexWebSocketSessionState, OpenAICodexWebSocketDebugStats } from "./openai-codex-responses.js";
+/** Live Codex session state to preserve after a successful history rewrite. */
+export interface OpenAICodexCompactionResetOptions {
+    providerSessionState?: Map<string, ProviderSessionState>;
+    sessionId?: string;
+    compaction: CodexCompactionContext;
+}
+/**
+ * Invalidate Codex history-dependent transport state after compaction while
+ * retaining the session identity and live connection.
+ */
+export declare function resetOpenAICodexHistoryAfterCompaction(options: OpenAICodexCompactionResetOptions): void;
+/** Create isolated Codex transport state for a session or compaction request. */
+export declare function createCodexProviderSessionState(): CodexProviderSessionState;
+/** Return or initialize the Codex state shared by a session's streaming requests. */
+export declare function getCodexProviderSessionState(providerSessionState: Map<string, ProviderSessionState> | undefined): CodexProviderSessionState | undefined;
+/** Forget append baselines after a history rewrite without closing the live connection. */
+export declare function resetCodexWebSocketAppendState(state: CodexWebSocketSessionState): void;
+/** Current Codex transport selection and connection status for host diagnostics. */
+export interface OpenAICodexTransportDetails {
+    websocketPreferred: boolean;
+    lastTransport?: CodexTransport;
+    websocketDisabled: boolean;
+    websocketConnected: boolean;
+    fallbackCount: number;
+    canAppend: boolean;
+    prewarmed: boolean;
+    hasSessionState: boolean;
+    hasTurnState: boolean;
+    lastFallbackAt?: number;
+}
+export declare function getOpenAICodexWebSocketDebugStats(model: Model<"openai-codex-responses">, options?: {
+    sessionId?: string;
+    baseUrl?: string;
+    providerSessionState?: Map<string, ProviderSessionState>;
+}): OpenAICodexWebSocketDebugStats | undefined;
+export declare function getOpenAICodexTransportDetails(model: Model<"openai-codex-responses">, options?: {
+    sessionId?: string;
+    baseUrl?: string;
+    preferWebsockets?: boolean;
+    providerSessionState?: Map<string, ProviderSessionState>;
+}): OpenAICodexTransportDetails;

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

@@ -3,6 +3,11 @@ import type { AssistantMessage, Context, Model, ServiceTier, StreamFunction, Str
 import type { ChatCompletionMessageParam } from "./openai-chat-wire.js";
 import { type OpenAIPromptCacheOptions } from "./openai-shared.js";
 export { applyOpenRouterRoutingVariant } from "./openai-shared.js";
+/**
+ * Whether a thinking block's signature is a raw LiteLLM (Anthropic) one, not a
+ * reasoning field name or the Mistral content-parts marker.
+ */
+export declare function isLiteLLMThinkingSignature(signature: string | undefined): signature is string;
 /**
  * Identify "real progress" stream chunks vs. keepalives, role-only preambles,
  * and empty `{choices:[]}` no-ops emitted by some OpenAI-compatible endpoints.
@@ -43,4 +48,15 @@ export interface OpenAICompletionsOptions extends StreamOptions {
  */
 export declare const streamOpenAICompletions: StreamFunction<"openai-completions">;
 export declare function parseChunkUsage(rawUsage: object, model: Model<"openai-completions">, premiumRequests: number | undefined, timestamp?: number, cachedTokensHeader?: number): AssistantMessage["usage"];
+/**
+ * Whether every chat-completions request to `model` drops the thinking text of
+ * its own prior turns: neither the base compat nor its `whenThinking` view
+ * sends it. Blocks with a raw LiteLLM signature ({@link isLiteLLMThinkingSignature})
+ * still replay in `thinking_blocks`.
+ */
+export declare function completionsDropsOwnThinking(model: {
+    api?: string;
+    reasoning?: boolean;
+    compat?: Model["compat"];
+} | null | undefined): boolean;
 export declare function convertMessages(model: Model<"openai-completions">, context: Context, compat: ResolvedOpenAICompat): ChatCompletionMessageParam[];

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

@@ -0,0 +1,48 @@
+import type { Model, ProviderSessionState } from "../types.js";
+import type { OpenAIResponsesChainState, OpenAIResponsesOptions } from "./openai-responses.js";
+/** Prefix shared by Responses request state and credential-reset hooks. */
+export declare const OPENAI_RESPONSES_PROVIDER_SESSION_STATE_PREFIX = "openai-responses:";
+/**
+ * Whether the next request for `model` replays native Responses history items
+ * (encrypted reasoning, item ids), matching request construction. A session
+ * is cold, rebuilding turns from message content, from the first request on a
+ * connection-bound host (`compat.connectionBoundNativeHistory`, GitHub Copilot)
+ * and after `close()` on any host, until a response succeeds. Without session
+ * state every request replays.
+ */
+export declare function openAIResponsesReplaysNativeHistory(model: Pick<Model, "api" | "provider" | "compat"> | null | undefined, providerSessionState: Map<string, ProviderSessionState> | undefined): boolean;
+/**
+ * Set the process-wide storage default per provider id, used when a request
+ * leaves `storeResponses` unset. Hosts call this from their settings so every
+ * request follows the setting, including direct `streamSimple`/`completeSimple`
+ * side calls that do not pass per-request options. `PI_MUSE_STORE_RESPONSES`
+ * still overrides it.
+ */
+export declare function configureProviderStoreResponses(byProvider: Readonly<Record<string, boolean>> | undefined): void;
+/**
+ * Whether this request stores its result server-side. Only hosts whose rule
+ * sets `store-responses` (they finish runs after a client disconnect, so a
+ * dropped stream can be resumed) are eligible, and storage is opt-in:
+ * `options.storeResponses`, then `PI_MUSE_STORE_RESPONSES`, then the host
+ * default ({@link configureProviderStoreResponses}), else off. Privacy: stored
+ * runs retain prompts and outputs on the provider. Off also disables resume and
+ * the `previous_response_id` chaining that needs storage.
+ */
+export declare function storesResponsesServerSide(model: Model<"openai-responses">, options: OpenAIResponsesOptions | undefined): boolean;
+/** Forget server-side append baselines while preserving the chain's failure history. */
+export declare function resetOpenAIResponsesChainState(state: OpenAIResponsesChainState): void;
+/**
+ * Drop the account-bound half of every retained `openai-responses` record in
+ * `states`: the stateful `previous_response_id` chain baselines.
+ *
+ * Chaining stores the turn server-side under the account that created it, so a
+ * baseline minted by one credential is dead weight the moment the session is
+ * switched to a sibling account — the next delta request answers
+ * `Previous response not found` and burns a turn re-learning that. Everything
+ * else this record holds describes the *deployment*, not the account
+ * (strict-tools demotion, reasoning-effort fallback, native-history-replay
+ * warmup, the chaining circuit breaker), and is deliberately preserved:
+ * re-learning an endpoint's limits on every credential switch is the cost this
+ * state exists to avoid.
+ */
+export declare function resetOpenAIResponsesAccountScopedState(states: Map<string, ProviderSessionState>): void;

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

@@ -81,7 +81,7 @@ export declare function pollOpenAIResponsesResultForCompletion(args: {
     /** Sleep between polls; defaults to a real wait honoring `signal`. */
     wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
 }): Promise<Record<string, unknown> | undefined>;
-interface OpenAIResponsesProviderSessionState extends ProviderSessionState, OpenAIStrictToolsState, OpenAIReasoningEffortFallbackState {
+export interface OpenAIResponsesProviderSessionState extends ProviderSessionState, OpenAIStrictToolsState, OpenAIReasoningEffortFallbackState {
     /**
      * Replay native history items. Starts false only on connection-bound hosts;
      * `close()` clears it so the next request rebuilds history from message
@@ -97,7 +97,7 @@ interface OpenAIResponsesProviderSessionState extends ProviderSessionState, Open
 }
 /** Wire efforts a `configuration_update` can carry: every real tier, never `none`/null. */
 type ResponsesStableEffort = Exclude<ReasoningEffort, "none" | null>;
-interface OpenAIResponsesChainState {
+export interface OpenAIResponsesChainState {
     sessionId: string;
     /**
      * Wire params of the last successful turn; never carries
@@ -114,38 +114,6 @@ interface OpenAIResponsesChainState {
     /** Set once chaining is judged unsupported for this session (circuit breaker). */
     disabled: boolean;
 }
-/**
- * Whether the next request for `model` replays native Responses history items
- * (encrypted reasoning, item ids), as {@link buildParams} decides it. A session
- * is cold, rebuilding turns from message content, from the first request on a
- * connection-bound host (`compat.connectionBoundNativeHistory`, GitHub Copilot)
- * and after `close()` on any host, until a response succeeds. Without session
- * state every request replays.
- */
-export declare function openAIResponsesReplaysNativeHistory(model: Pick<Model, "api" | "provider" | "compat"> | null | undefined, providerSessionState: Map<string, ProviderSessionState> | undefined): boolean;
-/**
- * Set the process-wide storage default per provider id, used when a request
- * leaves `storeResponses` unset. Hosts call this from their settings so every
- * request follows the setting, including direct `streamSimple`/`completeSimple`
- * side calls that do not pass per-request options. `PI_MUSE_STORE_RESPONSES`
- * still overrides it.
- */
-export declare function configureProviderStoreResponses(byProvider: Readonly<Record<string, boolean>> | undefined): void;
-/**
- * Drop the account-bound half of every retained `openai-responses` record in
- * `states`: the stateful `previous_response_id` chain baselines.
- *
- * Chaining stores the turn server-side under the account that created it, so a
- * baseline minted by one credential is dead weight the moment the session is
- * switched to a sibling account — the next delta request answers
- * `Previous response not found` and burns a turn re-learning that. Everything
- * else this record holds describes the *deployment*, not the account
- * (strict-tools demotion, reasoning-effort fallback, native-history-replay
- * warmup, the chaining circuit breaker), and is deliberately preserved:
- * re-learning an endpoint's limits on every credential switch is the cost this
- * state exists to avoid.
- */
-export declare function resetOpenAIResponsesAccountScopedState(states: Map<string, ProviderSessionState>): void;
 type OpenRouterAnthropicCacheControl = {
     type: "ephemeral";
     ttl?: "1h";

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

@@ -21,7 +21,8 @@
  * Endpoint contract:
  *   POST /v1/pi/stream
  *   body:    { modelId, context, options?, stream? }   // `stream` defaults to true
- *   200 SSE: stream of `AssistantMessageEvent` (terminated by `data: [DONE]`)
+ *   200 SSE: stream of `AssistantMessageEvent` (terminated by `data: [DONE]`),
+ *            interleaved with `: keepalive` comment frames
  *   200 JSON (stream=false): { message: AssistantMessage }
  *   4xx/5xx: { error: { type, message } }
  */

package/dist/types/providers/register-builtins.d.ts

@@ -1,10 +1,10 @@
 /**
- * Built-in provider stream dispatch with shared error, cancellation, and timeout handling.
+ * First-use provider loading with shared stream error, cancellation, and timeout handling.
  */
 import type { Context, Model, OptionsForApi } from "../types.js";
 import { AssistantMessageEventStream as EventStreamImpl } from "../utils/event-stream.js";
-import * as BedrockProvider from "./amazon-bedrock.js";
-import * as CursorProvider from "./cursor.js";
+import type * as BedrockProvider from "./amazon-bedrock.js";
+import type * as CursorProvider from "./cursor.js";
 /** Install a host-supplied Bedrock transport in place of the built-in provider. */
 export declare function setBedrockProviderModule(module: Pick<typeof BedrockProvider, "streamBedrock">): void;
 /** Install a host-supplied Cursor transport in place of the built-in provider. */

package/dist/types/providers/transform-messages.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedOpenAICompat } from "@oh-my-pi/pi-catalog/types";
 import type { Api, AssistantMessage, Message, Model } from "../types.js";
 /**
  * Maximum tool-call id length the strictest replay provider accepts.
@@ -54,6 +55,14 @@ export declare function isSurvivingAssistant(msg: AssistantMessage, model?: Mode
 export declare function isAnthropicMessagesModel(model: Model): model is Model<"anthropic-messages">;
 /** Whether `turn` came from `model` itself: its own turns replay their native reasoning unchanged. */
 export declare function isSameModelTurn(turn: Pick<AssistantMessage, "provider" | "api" | "model">, model: Pick<Model, "provider" | "api" | "id">): boolean;
+/**
+ * Whether chat completions (`convertMessages`) writes the model's own past
+ * thinking under `compat`: as Mistral content parts, demoted text, or a
+ * reasoning field. Otherwise it drops it.
+ */
+export declare function completionsSendsOwnThinking(model: {
+    reasoning?: boolean;
+}, compat: Pick<ResolvedOpenAICompat, "mistralReasoningContentParts" | "requiresThinkingAsText" | "requiresReasoningContentForToolCalls" | "thinkingFormat" | "replayReasoningContent">): boolean;
 /**
  * Normalize tool call ID for cross-provider compatibility.
  * OpenAI Responses API generates IDs that are 450+ chars with special characters like `|`.

package/dist/types/utils/abort.d.ts

@@ -3,6 +3,8 @@ export interface AbortSourceTracker {
     requestSignal: AbortSignal;
     abortLocally(reason: Error): Error;
     getLocalAbortReason(): Error | undefined;
+    /** The reason the caller passed to `abort()`, read from the caller's own signal, never the racy merged one. */
+    getCallerAbortReason(): string | undefined;
     wasCallerAbort(): boolean;
 }
 /**
@@ -20,6 +22,7 @@ export declare function createAbortSourceTracker(callerSignal?: AbortSignal): Ab
 /**
  * Race a shared promise against a caller's AbortSignal without coupling the
  * underlying work to that signal. The shared promise keeps running (and caches
- * its result) even when an individual caller bails out.
+ * its result) even when an individual caller bails out, and stays observed so
+ * its later rejection is never unhandled.
  */
 export declare function raceWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.13.2",
+	"version": "18.14.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -33,7 +33,6 @@
 		"README.md",
 		"CHANGELOG.md",
 		"LICENSE",
-		"THIRD-PARTY-NOTICES.txt",
 		"dist/types"
 	],
 	"type": "module",
@@ -100,6 +99,7 @@
 			"types": "./dist/types/providers/*.d.ts",
 			"import": "./src/providers/*.ts"
 		},
+		"./providers/*.js": "./src/providers/*.ts",
 		"./providers/openai-codex/*": {
 			"types": "./dist/types/providers/openai-codex/*.d.ts",
 			"import": "./src/providers/openai-codex/*.ts"
@@ -155,16 +155,16 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.13.2",
-		"@oh-my-pi/pi-catalog": "18.13.2",
-		"@oh-my-pi/pi-natives": "18.13.2",
-		"@oh-my-pi/pi-utils": "18.13.2",
-		"@oh-my-pi/pi-wire": "18.13.2"
+		"@oh-my-pi/omptype": "18.14.0",
+		"@oh-my-pi/pi-catalog": "18.14.0",
+		"@oh-my-pi/pi-natives": "18.14.0",
+		"@oh-my-pi/pi-utils": "18.14.0",
+		"@oh-my-pi/pi-wire": "18.14.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {
-		"bun": ">=1.3.14"
+		"bun": ">=1.4.4"
 	}
 }

package/src/auth/abort.ts

@@ -3,11 +3,16 @@ import * as AIError from "../error";
 /**
  * Race `promise` against `signal`, rejecting only this caller when the signal
  * fires. The underlying promise keeps running so other awaiters on the same
- * single-flight operation aren't punished by a peer's cancel.
+ * single-flight operation aren't punished by a peer's cancel. It stays
+ * observed either way: a caller that leaves must not turn the work's later
+ * rejection into an unhandled one.
  */
 export function raceSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined, message: string): Promise<T> {
 	if (!signal) return promise;
-	if (signal.aborted) return Promise.reject(new AIError.AbortError(message));
+	if (signal.aborted) {
+		void promise.catch(() => {});
+		return Promise.reject(new AIError.AbortError(message));
+	}
 	const abort = Promise.withResolvers<never>();
 	const onAbort = (): void => abort.reject(new AIError.AbortError(message));
 	signal.addEventListener("abort", onAbort, { once: true });

package/src/auth/cascade.ts

@@ -369,6 +369,13 @@ export class KeyCascade implements KeysApi {
 		}
 	}
 
+	/** Warm selection metadata during session startup without choosing or pinning an account. */
+	async prefetchUsage(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<void> {
+		options?.signal?.throwIfAborted();
+		if (this.source(provider)?.kind !== "oauth") return;
+		await this.#deps.selector.prefetchUsage(provider, sessionId, options);
+	}
+
 	async #resolve(
 		provider: string,
 		sessionId?: string,

package/src/auth/rank.ts

@@ -111,14 +111,16 @@ function compareUsageRankedCandidatePriority(
 	const leftHot = left.primaryUsed >= PRIMARY_WINDOW_HOT_FRACTION;
 	const rightHot = right.primaryUsed >= PRIMARY_WINDOW_HOT_FRACTION;
 	if (leftHot !== rightHot) return leftHot ? 1 : -1;
-	// Usage-backed candidates outrank unmeasured ones: required-drain
-	// scores are only comparable between measured windows, and the
-	// clockless headroom fallback (0..1) must not let an account whose
+	// Configured priority is the user's order; a failed usage fetch says nothing
+	// about it, so it ranks ahead of measurement.
+	if (left.accountPriority !== right.accountPriority) return right.accountPriority - left.accountPriority;
+	// Within a priority, usage-backed candidates outrank unmeasured ones:
+	// required-drain scores are only comparable between measured windows, and
+	// the clockless headroom fallback (0..1) must not let an account whose
 	// usage fetch failed shadow a measured sibling.
 	const leftMeasured = left.usageMeasured;
 	const rightMeasured = right.usageMeasured;
 	if (leftMeasured !== rightMeasured) return leftMeasured ? -1 : 1;
-	if (left.accountPriority !== right.accountPriority) return right.accountPriority - left.accountPriority;
 	// Required drain, descending: the account whose remaining quota must
 	// burn fastest to avoid expiring unused at its reset comes first, so
 	// staggered resets land at ~100% utilization instead of stranding

package/src/auth/refresh.ts

@@ -1,3 +1,4 @@
+import { scheduler } from "node:timers/promises";
 import { isSqliteBusyError, logger, postmortem } from "@oh-my-pi/pi-utils";
 import * as AIError from "../error";
 import { getOAuthProvider, normalizeOAuthCredentialExpiry, refreshOAuthToken } from "../registry/oauth";
@@ -391,7 +392,7 @@ export class OAuthRefresher {
 	async #drainRefreshes(): Promise<void> {
 		this.#shuttingDown = true;
 		// Work tracked while draining (a lease hand-back a returning caller left behind) is waited for too.
-		while (this.#pendingRefreshes.size > 0) await Promise.allSettled([...this.#pendingRefreshes]);
+		while (this.#pendingRefreshes.size > 0) await Promise.allSettled(this.#pendingRefreshes);
 	}
 
 	async #refreshStored<T extends OAuthCredential = OAuthCredential>(
@@ -620,18 +621,19 @@ export class OAuthRefresher {
 		let keepLease = false;
 		let saved = false;
 		try {
-			let stopLeaseRenewal = false;
+			const leaseRenewalStop = new AbortController();
 			let leaseRenewalError: unknown;
-			const leaseRenewalStopped = Promise.withResolvers<void>();
 			const leaseRenewal =
 				leasedCredentialId !== undefined && leaseStore
 					? (async () => {
 							// Renew every interval; after a busy store, retry almost at once,
 							// since another full interval would outlive the lease.
 							let delayMs = OAUTH_REFRESH_LEASE_RENEW_MS;
-							while (!stopLeaseRenewal) {
-								await Promise.race([Bun.sleep(delayMs), leaseRenewalStopped.promise]);
-								if (stopLeaseRenewal) return;
+							while (!leaseRenewalStop.signal.aborted) {
+								// Stopping cancels the wait, so a finished exchange leaves no renewal
+								// timer behind to hold the process open for up to an interval.
+								await scheduler.wait(delayMs, { signal: leaseRenewalStop.signal }).catch(() => undefined);
+								if (leaseRenewalStop.signal.aborted) return;
 								let renewed: boolean;
 								try {
 									renewed = leaseStore.renewCredentialRefreshLease(
@@ -694,8 +696,7 @@ export class OAuthRefresher {
 						until: takenOverFrom.expiresAtMs + OAUTH_REFRESH_STALLED_OWNER_MS,
 					});
 					// Stop renewing first: a renewal after the hand-back would take it back.
-					stopLeaseRenewal = true;
-					leaseRenewalStopped.resolve();
+					leaseRenewalStop.abort();
 					await leaseRenewal;
 					// Never release this lease afterwards: a hand-back that landed left
 					// nothing to release, and one that did not must leave a recent owner.
@@ -754,8 +755,7 @@ export class OAuthRefresher {
 					},
 				};
 			} finally {
-				stopLeaseRenewal = true;
-				leaseRenewalStopped.resolve();
+				leaseRenewalStop.abort();
 				await leaseRenewal;
 				clearTimeout(backstop);
 			}
@@ -922,6 +922,9 @@ export class OAuthRefresher {
 			}
 		}
 		if (Date.now() + OAUTH_REFRESH_SKEW_MS < credential.expires) return credential;
+		// A caller that already left must not own a refresh that later callers join:
+		// they would inherit its cancellation instead of a credential.
+		if (signal?.aborted) throw new AIError.AbortError("credential refresh aborted");
 		if (credentialId === undefined) {
 			return this.#refreshOAuthCredentialUnshared(provider, credential, undefined, signal, reason, rejectedAccess);
 		}
@@ -1105,6 +1108,8 @@ export class OAuthRefresher {
 		if (recent && recent.credential.access !== options?.rejectedAccess) {
 			return snapshotEntry(id, recent.provider, recent.credential);
 		}
+		// A caller that already left must not own a refresh that later callers join.
+		if (signal?.aborted) throw new AIError.AbortError("credential refresh aborted");
 
 		const promise = (async () => {
 			this.#deps.pool.bump("credential-refresh-start");