@oh-my-pi/pi-ai 15.3.2 → 15.4.1

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 ## [Unreleased]
 
+## [15.4.1] - 2026-05-26
+### Added
+
+- Added `isOpenAICompletionsProgressChunk` export to identify real progress chunks vs. keepalives in OpenAI completions streams
+- Added per-provider stream watchdog overrides via `getStreamIdleTimeoutMs(fallbackMs)` and `getStreamFirstEventTimeoutMs(idleTimeoutMs, fallbackMs)` to allow providers like Google Gemini CLI to extend first-event timeouts without affecting global defaults
+- Added `promptCacheKey` to `StreamOptions` and passed it through stream option mapping so callers can specify an explicit prompt-cache key separate from `sessionId`
+- Added `promptCacheKey` support to the native server option whitelist so `promptCacheKey` is accepted by `pi-native-server` streams
+- Restored the per-provider stream watchdog (`iterateWithIdleTimeout`) on top of the abortable iterator. The lazy stream forwarder in `register-builtins` now wraps every provider's event stream with the first-event + steady-state idle watchdog (`PI_STREAM_FIRST_EVENT_TIMEOUT_MS`, `PI_STREAM_IDLE_TIMEOUT_MS`; aliases honored), and Anthropic / OpenAI Completions / OpenAI Responses / Azure OpenAI Responses / Codex SSE re-emit their per-provider progress predicates so empty keepalive frames cannot keep a stalled stream alive. Reverts the partial regression from #1392 that left Codex WebSocket subagent runs hanging silently for hours when the broker dropped frames between deltas. The Codex WebSocket transport additionally now resets `lastProgressAt` only on progress events (not keepalives), giving the 300s WS-internal idle ceiling the same liveness semantics as the SSE path.
+
+### Changed
+
+- Enabled OpenAI Codex WebSocket streams to apply `streamIdleTimeoutMs` and `streamFirstEventTimeoutMs` from `StreamOptions` per request instead of fixed internal defaults
+- Changed stream idle watchdog implementation from `iterateUntilAbort` to `iterateWithIdleTimeout`, which now enforces maximum idle gaps between streamed events and distinguishes between first-event and steady-state timeouts
+- Changed Anthropic, OpenAI Responses, OpenAI Completions, Azure OpenAI Responses, and OpenAI Codex Responses providers to use the new idle-timeout iterator with per-provider progress predicates so empty keepalive frames cannot keep a stalled stream alive
+- Changed Codex WebSocket transport to reset `lastProgressAt` only on progress events (not keepalives), giving the 300s WS-internal idle ceiling the same liveness semantics as the SSE path
+- Changed Google Gemini CLI stream forwarding defaults to use a 5-minute first-event floor via per-provider lazy-stream limits to avoid premature first-event timeouts on slow startup
+- Changed OpenAI Responses and OpenAI Codex request handling to keep `sessionId` for provider routing and conversation headers while `promptCacheKey` controls the `prompt_cache_key` payload independently
+- Changed `StreamOptions.streamIdleTimeoutMs` documentation to clarify it is now wired into every built-in provider and the lazy stream forwarder, and that `streamFirstEventTimeoutMs` is honored at both the SDK-request layer and the iterator-watchdog layer
+- Changed OpenAI Responses and OpenAI Codex request handling so `sessionId` continues to drive provider routing and state while `promptCacheKey` controls the `prompt_cache_key` payload
+- Changed Google Gemini CLI stream forwarding defaults to use a 5-minute first-event floor to avoid premature first-event timeouts on slow startup
+- Changed auth-gateway request mapping to preserve incoming `prompt_cache_key` as both `promptCacheKey` and `sessionId` when routing OpenAI-compatible sessions
+- Un-deprecated `StreamOptions.streamIdleTimeoutMs`; the option is wired into every built-in provider and the lazy stream forwarder again. `streamFirstEventTimeoutMs` is now honored at both the SDK-request layer (via `createSdkStreamRequestOptions`) and the iterator-watchdog layer, in cooperation.
+
+### Removed
+
+- Removed `installH2Fetch` and the `fetch` patch that forced HTTP/2 on HTTPS requests; callers now use the default Bun `fetch` transport
+
+### Fixed
+
+- Fixed first-item timeout handling so `iterateWithIdleTimeout` no longer keeps first-event timers active after the source throws or the consumer stops before semantic progress
+- Fixed silent multi-hour hangs on Codex WebSocket subagent runs when the broker dropped frames between deltas by restoring per-provider stream watchdogs with progress-event filtering
+- Fixed z.ai/GLM-via-OpenRouter subagent stalls where no-op keepalive chunks reset the idle watchdog indefinitely by filtering non-progress items before resetting the deadline
+
+## [15.4.0] - 2026-05-26
+### Breaking Changes
+
+- Removed `findAnthropicAuth` from `anthropic-auth` and replaced store-driven auth discovery with `buildAnthropicAuthConfig`, requiring callers to provide an already-resolved API key before building Anthropic auth config
+
+### Added
+
+- Added `PI_CODEX_WEBSOCKET_FIRST_EVENT_TIMEOUT_MS` and `PI_CODEX_WEBSOCKET_IDLE_TIMEOUT_MS` options to tune Codex WebSocket timeout behavior before fallback
+- Added `AuthStorage.getOAuthAccess` to return a refreshed OAuth access token with identity metadata (`accountId`, `email`, `projectId`, `enterpriseUrl`) for callers that need bearer-token headers together
+- Added Codex WebSocket forwarding to the `onSseEvent` observer so the raw provider-stream debug viewer captures the inbound JSON frames and the outbound request frame from the WS transport using the same synthesized SSE-wire shape (`event:` + `data:` lines, prefixed with a `: ws ← <type>` (inbound) or `: ws → <type>` (outbound) comment).
+
+### Changed
+
+- Changed OAuth selection in `AuthStorage` to treat credentials as stale when they are within 60 seconds of expiry and rotate them preemptively
+- Changed Google Gemini CLI, Google Gemini usage, Antigravity usage, and Kimi usage flows to stop refreshing OAuth tokens directly and rely on `AuthStorage` for token rotation
+
+### Deprecated
+
+- Deprecated `streamIdleTimeoutMs` in `StreamOptions` as a compatibility-only field that is no longer used by providers
+
+### Removed
+
+- Removed provider-local OAuth refresh helpers from Google Gemini CLI and Google/Kimi/Antigravity usage probes, preventing direct refresh calls from those usage paths
+
+### Fixed
+
+- Dropped truncated, thinking-only assistant turns with only `thinking`/`redacted_thinking` blocks and no `text` or `tool` content during message transformation, preventing Anthropic requests from sending consecutive assistant messages after a `max_tokens`/`error`/`aborted` interruption
+- Fixed Amazon Bedrock bearer-token authentication to honor `AWS_BEARER_TOKEN_BEDROCK` before resolving AWS profiles or running `credential_process`, matching Bedrock API-key precedence. ([#1399](https://github.com/can1357/oh-my-pi/issues/1399))
+- Updated `isRetryableError` to treat Bun HTTP/2 transport errors (`HTTP2StreamReset`, `HTTP2RefusedStream`) as retryable so transient stream-reset failures can be retried
+- Fixed Codex WebSocket streaming to recover from stalled sessions by falling back to SSE when the first event or subsequent progress is delayed beyond the configured websocket timeout
+- Fixed expired OAuth handling so provider-level paths no longer attempt direct token refresh calls for expired credentials and instead rely on `AuthStorage` for rotation
+- Fixed provider streams aborting slow-but-valid first tokens or silent inter-event gaps with OMP-owned first-event/idle watchdog errors. Built-in lazy streams, OpenAI/Anthropic/Azure/Codex SSE, and Codex WebSocket streams now wait for provider output, provider/socket errors, caller aborts, or explicit request-layer timeouts instead of treating provider silence as failure ([#1392](https://github.com/can1357/oh-my-pi/issues/1392)).
+- Fixed Claude Opus 4.7 on Amazon Bedrock streaming no reasoning output (and appearing to hang on long reasoning runs) because Anthropic silently switched the adaptive-thinking display default to `"omitted"`. The Bedrock provider now sends `thinking.display = "summarized"` by default on Opus 4.7+ adaptive models and on budget-based Claude models, mirroring the existing direct-Anthropic behavior. `BedrockOptions.thinkingDisplay` (`"summarized" | "omitted"`) is exposed for callers that want to opt out, and `hideThinkingSummary` now wires through to the Bedrock case ([#1373](https://github.com/can1357/oh-my-pi/issues/1373)).
+- Fixed Cursor Composer resume/tool-continuation turns failing with `Cannot send empty user message to Cursor API`. Empty current user turns now use Cursor's `resumeAction` instead of constructing an invalid `userMessageAction` ([#1376](https://github.com/can1357/oh-my-pi/issues/1376)).
+- Fixed `pi-ai login moonshot` failing with `invalid temperature: only 1 is allowed for this model` (HTTP 400) because the API-key validator probed `kimi-k2.5` with `temperature: 0`. Moonshot login now validates against `GET /v1/models`, matching the DeepSeek/Fireworks/NanoGPT/ZenMux pattern and authenticating the key without invoking model-specific parameter restrictions.
+
 ## [15.3.2] - 2026-05-25
 ### Added
 

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

@@ -58,7 +58,7 @@ export interface AuthGatewayParsedRequestOptions {
     serviceTier?: ServiceTier;
     /** Cache retention hint derived from inbound `cache_control` markers. */
     cacheRetention?: CacheRetention;
-    /** OpenAI Responses `prompt_cache_key`; bridges to pi-ai `sessionId`. */
+    /** OpenAI Responses `prompt_cache_key`; also seeds provider routing when no separate session id exists. */
     promptCacheKey?: string;
     /** OpenAI Responses `previous_response_id` for response chaining. */
     previousResponseId?: string;

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

@@ -291,6 +291,21 @@ type AuthApiKeyOptions = {
      */
     signal?: AbortSignal;
 };
+/**
+ * Refreshed OAuth access plus identity metadata returned by
+ * {@link AuthStorage.getOAuthAccess}. Callers that authenticate via a bearer
+ * AND need the credential's identity (Codex `chatgpt-account-id`, Google
+ * `projectId`, GitHub `enterpriseUrl`) consume this shape directly; the
+ * refresh slot is deliberately omitted because rotating refresh tokens never
+ * leave {@link AuthStorage}.
+ */
+export interface OAuthAccess {
+    accessToken: string;
+    accountId?: string;
+    email?: string;
+    projectId?: string;
+    enterpriseUrl?: string;
+}
 export interface InvalidateCredentialMatchingOptions {
     signal?: AbortSignal;
     sessionId?: string;
@@ -493,6 +508,22 @@ export declare class AuthStorage {
      * 6. Fallback resolver (models.yml custom providers, last-resort)
      */
     getApiKey(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
+    /**
+     * Resolve the OAuth credential for `provider`, refreshing through the same
+     * pipeline as {@link AuthStorage.getApiKey} but returning the refreshed
+     * {@link OAuthAccess} (raw access token + identity metadata) instead of
+     * the API-key bytes.
+     *
+     * Use this when the caller needs to inject identity headers alongside the
+     * bearer (Codex `chatgpt-account-id`, Google `project`, GitHub
+     * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
+     * scenarios, prefer {@link AuthStorage.getApiKey}.
+     *
+     * Returns `undefined` when no OAuth credential is available, the
+     * credential fails to refresh, or runtime/config overrides have replaced
+     * OAuth with an explicit API key.
+     */
+    getOAuthAccess(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
     invalidateCredentialMatching(provider: string, apiKey: string, options?: InvalidateCredentialMatchingOptions): Promise<boolean>;
     invalidateCredentialMatching(provider: string, apiKey: string, signal?: AbortSignal): Promise<boolean>;
     /**

package/dist/types/index.d.ts

@@ -40,7 +40,6 @@ export * from "./usage/zai";
 export * from "./utils/anthropic-auth";
 export * from "./utils/discovery";
 export * from "./utils/event-stream";
-export * from "./utils/h2-fetch";
 export * from "./utils/oauth";
 export type { OAuthCredentials, OAuthProvider, OAuthProviderId, OAuthProviderInfo, } from "./utils/oauth/types";
 export * from "./utils/overflow";

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

@@ -8,9 +8,12 @@
  */
 import type { Effort } from "../model-thinking";
 import type { StreamFunction, StreamOptions, ThinkingBudgets } from "../types";
+export type BedrockThinkingDisplay = "summarized" | "omitted";
 export interface BedrockOptions extends StreamOptions {
     region?: string;
     profile?: string;
+    /** Amazon Bedrock API key sent as `Authorization: Bearer`, ahead of SigV4 credential resolution. */
+    bearerToken?: string;
     toolChoice?: "auto" | "any" | "none" | {
         type: "tool";
         name: string;
@@ -18,5 +21,18 @@ export interface BedrockOptions extends StreamOptions {
     reasoning?: Effort;
     thinkingBudgets?: ThinkingBudgets;
     interleavedThinking?: boolean;
+    /**
+     * Controls how Claude returns thinking content in Bedrock responses.
+     * - `"summarized"`: thinking blocks include human-readable summaries (default here).
+     * - `"omitted"`: thinking content is suppressed; the encrypted signature still
+     *   travels back for multi-turn continuity.
+     *
+     * Starting with Claude Opus 4.7 the Anthropic API default is `"omitted"`, which
+     * leaves callers waiting on a silent stream during long reasoning runs (issue
+     * #1373). We default to `"summarized"` so adaptive-thinking models that accept
+     * the field keep producing visible thinking deltas. Older adaptive-thinking
+     * models (Opus 4.6, Sonnet 4.6+) reject the field, so we omit it for them.
+     */
+    thinkingDisplay?: BedrockThinkingDisplay;
 }
 export declare const streamBedrock: StreamFunction<"bedrock-converse-stream">;

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

@@ -1,4 +1,5 @@
-import type { CursorExecHandlerResult, CursorExecHandlers, CursorToolResultHandler, StreamFunction, StreamOptions, ToolResultMessage } from "../types";
+import { type JsonValue } from "@bufbuild/protobuf";
+import type { CursorExecHandlerResult, CursorExecHandlers, CursorToolResultHandler, Message, StreamFunction, StreamOptions, ToolResultMessage } from "../types";
 export declare const CURSOR_API_URL = "https://api2.cursor.sh";
 export declare const CURSOR_CLIENT_VERSION = "cli-2026.01.09-231024f";
 export interface CursorOptions extends StreamOptions {
@@ -34,3 +35,8 @@ export declare function resolveExecHandler<TArgs, TResult>(args: TArgs, handler:
  * an empty `rootPromptMessagesJson` head.
  */
 export declare function buildCursorSystemPromptJsons(systemPrompt: readonly string[] | undefined): string[];
+/** Exported for tests: decodes Cursor history blobs built from conversation messages. */
+export declare function buildCursorHistoryForTest(messages: Message[]): {
+    rootPromptMessagesJson: unknown[];
+    turnUserMessagesJson: JsonValue[];
+};

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

@@ -163,8 +163,6 @@ export declare class MockModel implements Model<MockApi> {
     /** Reset recorded calls AND the extras queue. The constructor `responses` are NOT reset. */
     reset(): void;
 }
-/** @deprecated Use {@link MockModel}; the class IS the handle. */
-export type MockModelHandle = MockModel;
 /** Check whether `model` was produced by `createMockModel`. */
 export declare function isMockModel(model: Model<Api>): model is MockModel;
 /** Construct a mock model. */

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

@@ -2,6 +2,8 @@ import type OpenAI from "openai";
 import type { ResponseInput, ResponseInputContent, ResponseOutputItem } from "openai/resources/responses/responses";
 import { type Api, type AssistantMessage, type ImageContent, type Model, type ServiceTier, type StopReason, type StreamOptions, type TextContent, type TextSignatureV1, type ToolResultMessage } from "../types";
 import type { AssistantMessageEventStream } from "../utils/event-stream";
+export declare const OPENAI_RESPONSES_PROGRESS_EVENT_TYPES: ReadonlySet<string>;
+export declare function isOpenAIResponsesProgressEvent(event: unknown): boolean;
 export declare function encodeTextSignatureV1(id: string, phase?: TextSignatureV1["phase"]): string;
 export declare function parseTextSignature(signature: string | undefined): {
     id: string;

package/dist/types/types.d.ts

@@ -185,11 +185,17 @@ export interface StreamOptions {
      */
     metadata?: Record<string, unknown>;
     /**
-     * Optional session identifier for providers that support session-based caching.
-     * Providers can use this to enable prompt caching, request routing, or other
-     * session-aware features. Ignored by providers that don't support it.
+     * Optional session identifier for providers that support session-based
+     * routing, request affinity, or transport reuse. Providers may also use this
+     * as the prompt-cache key when `promptCacheKey` is not set.
      */
     sessionId?: string;
+    /**
+     * Optional prompt-cache identity. When set, OpenAI Responses-compatible
+     * providers use this for `prompt_cache_key` while keeping `sessionId` for
+     * provider routing / conversation headers.
+     */
+    promptCacheKey?: string;
     /**
      * Provider-scoped mutable state store for this agent session.
      * Providers can use this to persist transport/session state between turns.
@@ -205,20 +211,37 @@ export interface StreamOptions {
      */
     onResponse?: (response: ProviderResponseMetadata, model?: Model<Api>) => void | Promise<void>;
     /**
-     * Optional callback for raw Server-Sent Events as they arrive from HTTP streaming providers.
+     * Optional callback for raw Server-Sent Events as they arrive from HTTP streaming providers,
+     * plus synthesized SSE-shaped frames for the Codex WebSocket transport (one synthetic frame
+     * per JSON request/response message). WebSocket frames are tagged with a leading
+     * `: ws → <type>` (outbound) or `: ws ← <type>` (inbound) comment line in `RawSseEvent.raw`.
      *
      * Diagnostic only: provider implementations must ignore callback failures and must not
      * let observers alter stream contents.
      */
     onSseEvent?: (event: RawSseEvent, model?: Model<Api>) => void;
     /**
-     * Optional override for the first streamed event watchdog in milliseconds.
-     * Set to 0 to disable the first-event watchdog for this request.
+     * Optional override for the first-event watchdog in milliseconds. Built-in
+     * providers apply this budget twice when they can: once to the underlying
+     * SDK/request while waiting for the HTTP stream object to exist, then again
+     * in the iterator while waiting for the first semantic stream event. Set to
+     * `0` to disable both layers for this request. After the first semantic
+     * event arrives, `streamIdleTimeoutMs` governs inter-event stalls. Falls
+     * back to `PI_STREAM_FIRST_EVENT_TIMEOUT_MS` and then to a 100s default.
+     *
+     * Iterator-level honored by: every built-in provider (via the lazy-stream
+     * forwarder in `register-builtins`). SDK-request honored by:
+     * `openai-completions`, `openai-responses`, `azure-openai-responses`,
+     * `anthropic-messages`.
      */
     streamFirstEventTimeoutMs?: number;
     /**
-     * Optional override for the maximum idle gap between streamed events in milliseconds.
-     * Set to 0 to disable the inter-event idle watchdog for this request.
+     * Optional override for the maximum idle gap between streamed events in
+     * milliseconds. Once the first event arrives, this guards against silent
+     * mid-stream stalls (broker dies, half-open socket, model produces no real
+     * progress for too long). Set to `0` to disable. Falls back to
+     * `PI_STREAM_IDLE_TIMEOUT_MS` (alias: `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS`)
+     * and then to a 120s default.
      */
     streamIdleTimeoutMs?: number;
     /**

package/dist/types/utils/abortable-iterator.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Iterates a provider stream until it yields, ends, errors, or the caller aborts.
+ */
+export declare function iterateUntilAbort<T>(iterable: AsyncIterable<T>, signal?: AbortSignal): AsyncGenerator<T>;

package/dist/types/utils/anthropic-auth.d.ts

@@ -1,44 +1,31 @@
-import { type AuthCredentialStore } from "../auth-storage";
 /** Auth configuration for Anthropic */
 export interface AnthropicAuthConfig {
     apiKey: string;
     baseUrl: string;
     isOAuth: boolean;
 }
-/** OAuth credential for Anthropic API access */
-export interface AnthropicOAuthCredential {
-    type: "oauth";
-    access: string;
-    refresh?: string;
-    /** Expiry timestamp in milliseconds */
-    expires: number;
-}
+export declare function resolveAnthropicBaseUrlFromEnv(): string | undefined;
 /**
  * Checks if a token is an OAuth token by looking for sk-ant-oat prefix.
- * @param apiKey - The API key to check
- * @returns True if the token is an OAuth token
  */
 export declare function isOAuthToken(apiKey: string): boolean;
 /**
- * Finds Anthropic auth config using priority:
- *   1. ANTHROPIC_SEARCH_API_KEY / ANTHROPIC_SEARCH_BASE_URL
- *   2. ANTHROPIC_FOUNDRY_API_KEY override when Foundry mode is enabled
- *   3. OAuth in agent.db (with 5-minute expiry buffer)
- *   4. API key in agent.db
- *   5. ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL fallback
- * @param store - Optional credential store (creates one from default db path if not provided)
- * @returns The first valid auth configuration found, or null if none available
+ * Build an {@link AnthropicAuthConfig} from an already-resolved API key.
+ *
+ * `apiKey` is whatever the caller chose for `Authorization`/`x-api-key` —
+ * usually `authStorage.getApiKey("anthropic")`. `baseUrl` overrides the
+ * env-derived base; pass `undefined` to fall back to FOUNDRY/ANTHROPIC env
+ * resolution and finally `DEFAULT_BASE_URL`.
+ *
+ * `isOAuth` is derived from the token prefix so the helper stays pure: callers
+ * never have to thread the OAuth flag through their own resolution logic.
  */
-export declare function findAnthropicAuth(store?: AuthCredentialStore): Promise<AnthropicAuthConfig | null>;
+export declare function buildAnthropicAuthConfig(apiKey: string, baseUrl?: string): AnthropicAuthConfig;
 /**
  * Builds HTTP headers for Anthropic API requests (search variant).
- * @param auth - The authentication configuration
- * @returns Headers object ready for use in fetch requests
  */
 export declare function buildAnthropicSearchHeaders(auth: AnthropicAuthConfig): Record<string, string>;
 /**
  * Builds the full API URL for Anthropic messages endpoint.
- * @param auth - The authentication configuration
- * @returns The complete API URL with beta query parameter
  */
 export declare function buildAnthropicUrl(auth: AnthropicAuthConfig): string;

package/dist/types/utils/idle-iterator.d.ts

@@ -3,8 +3,12 @@
  *
  * `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is accepted as a backward-compatible alias.
  * Set `PI_STREAM_IDLE_TIMEOUT_MS=0` to disable the watchdog.
+ *
+ * Providers that legitimately stream much slower than the global default can pass
+ * `fallbackMs` to widen the floor used when neither env var nor caller option is set.
+ * Caller options still take precedence; env overrides still trump the fallback.
  */
-export declare function getStreamIdleTimeoutMs(): number | undefined;
+export declare function getStreamIdleTimeoutMs(fallbackMs?: number): number | undefined;
 /**
  * Returns the idle timeout used for OpenAI-family streaming transports.
  *
@@ -17,16 +21,14 @@ export declare function getOpenAIStreamIdleTimeoutMs(): number | undefined;
  * so the default never undershoots the steady-state idle timeout.
  *
  * Set `PI_STREAM_FIRST_EVENT_TIMEOUT_MS=0` to disable the watchdog.
+ *
+ * Providers whose first response can legitimately take longer (heavy reasoning,
+ * slow cold-start proxies) can pass `fallbackMs` to widen the floor used when
+ * neither env var nor caller option is set. Caller options still take precedence;
+ * env overrides still trump the fallback.
  */
-export declare function getStreamFirstEventTimeoutMs(idleTimeoutMs?: number): number | undefined;
-export type Watchdog = NodeJS.Timeout | undefined;
-/**
- * Starts a watchdog that aborts a request if no first stream event arrives in time.
- * Call `markFirstEventReceived()` as soon as the first event is observed.
- */
-export declare function createWatchdog(timeoutMs: number | undefined, onTimeout: () => void): Watchdog;
+export declare function getStreamFirstEventTimeoutMs(idleTimeoutMs?: number, fallbackMs?: number): number | undefined;
 export interface IdleTimeoutIteratorOptions {
-    watchdog?: Watchdog;
     idleTimeoutMs?: number;
     firstItemTimeoutMs?: number;
     errorMessage: string;

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

@@ -17,13 +17,16 @@ export declare function unregisterOAuthProviders(sourceId: string): void;
  */
 export declare function refreshOAuthToken(provider: OAuthProvider, credentials: OAuthCredentials): Promise<OAuthCredentials>;
 /**
- * Get API key for a provider from OAuth credentials.
- * Automatically refreshes expired tokens.
+ * Build API-key bytes for a provider from an already-fresh OAuth credential.
  *
- * For providers that need credential metadata at request time, returns JSON-encoded credentials
- * plus refresh/expiry metadata for proactive refresh support.
+ * Refresh is owned by AuthStorage. This helper deliberately refuses expired
+ * credentials so it cannot POST broker redaction sentinels to upstream token
+ * endpoints as a side channel.
+ *
+ * For providers that need credential metadata at request time, returns
+ * JSON-encoded credentials plus expiry metadata for diagnostics/edge guards.
  * @returns API key string, or null if no credentials
- * @throws Error if refresh fails
+ * @throws Error if the credential is expired and must be refreshed upstream
  */
 export declare function getOAuthApiKey(provider: OAuthProvider, credentials: Record<string, OAuthCredentials>): Promise<{
     newCredentials: OAuthCredentials;

package/dist/types/utils/sdk-stream-timeout.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared helpers for mapping `StreamOptions.streamFirstEventTimeoutMs` onto
+ * underlying SDK request-timeout options.
+ *
+ * The hint is intentionally not a watchdog — it just narrows the SDK's
+ * "transport timeout" window so a stuck pre-stream request fails fast
+ * instead of hanging on the default (often multi-minute) SDK timeout. Once
+ * the stream actually starts, silence is not failure; callers must abort
+ * to interrupt a quiet stream.
+ */
+/**
+ * Coerce a caller-supplied `streamFirstEventTimeoutMs` into a positive integer suitable
+ * for the SDK's `timeout` option. Returns `undefined` when the caller passed nothing,
+ * a non-finite value, or a non-positive value (preserving the SDK's default).
+ */
+export declare function resolveSdkTimeoutMs(streamFirstEventTimeoutMs: number | undefined): number | undefined;
+/**
+ * Build per-request SDK options that combine an abort signal with the optional
+ * `streamFirstEventTimeoutMs` request-timeout hint.
+ *
+ * The returned `{ signal, timeout?, maxRetries? }` shape is compatible with both
+ * OpenAI's and Anthropic's `RequestOptions` (and any other SDK that follows the
+ * Stainless conventions), so callers from any of those providers can spread the
+ * result directly into `client.X.create(params, requestOptions)`.
+ *
+ * When the hint is set, retries are forced to zero so the SDK does not silently
+ * extend the caller's explicit deadline by re-attempting after a timeout.
+ */
+export declare function createSdkStreamRequestOptions(signal: AbortSignal, streamFirstEventTimeoutMs: number | undefined): {
+    signal: AbortSignal;
+    timeout?: number;
+    maxRetries?: number;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "15.3.2",
+	"version": "15.4.1",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -43,7 +43,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-utils": "15.3.2",
+		"@oh-my-pi/pi-utils": "15.4.1",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/auth-gateway/server.ts

@@ -145,7 +145,9 @@ function buildStreamOptions(parsed: ParsedFormatRequest, api: Api, signal: Abort
 	// Client-supplied `prompt_cache_key` wins; otherwise derive a stable
 	// key from the model + system + tools so prefix caching engages on
 	// Codex-class backends across turns of the same logical conversation.
-	opts.sessionId = options.promptCacheKey ?? deriveSessionId(parsed.modelId, parsed.context);
+	const promptCacheKey = options.promptCacheKey ?? deriveSessionId(parsed.modelId, parsed.context);
+	opts.promptCacheKey = promptCacheKey;
+	opts.sessionId = promptCacheKey;
 	if (options.thinkingBudgets) {
 		opts.thinkingBudgets = { ...(opts.thinkingBudgets ?? {}), ...options.thinkingBudgets };
 	}

package/src/auth-gateway/types.ts

@@ -67,7 +67,7 @@ export interface AuthGatewayParsedRequestOptions {
 	serviceTier?: ServiceTier;
 	/** Cache retention hint derived from inbound `cache_control` markers. */
 	cacheRetention?: CacheRetention;
-	/** OpenAI Responses `prompt_cache_key`; bridges to pi-ai `sessionId`. */
+	/** OpenAI Responses `prompt_cache_key`; also seeds provider routing when no separate session id exists. */
 	promptCacheKey?: string;
 	/** OpenAI Responses `previous_response_id` for response chaining. */
 	previousResponseId?: string;