@oh-my-pi/pi-ai 18.8.2 → 18.8.4

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## [Unreleased]
 
+## [18.8.4] - 2026-10-08
+
+### Breaking Changes
+
+- `AuthBrokerClient.notifyUsageStale` and `UsageLedgerStore.invalidateUsageCache` (including `RemoteAuthCredentialStore.invalidateUsageCache`) now take an optional leading `provider` argument: the signature is `(provider?: string, signal?: AbortSignal)` instead of `(signal?: AbortSignal)` ([#14761](https://github.com/can1357/oh-my-pi/pull/14761) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Added
+
+- Auth gateway route option `excludeProviders` leaves those providers' accounts out of `/v1/usage` and `/v1/credentials/check` ([#14755](https://github.com/can1357/oh-my-pi/pull/14755) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Fixed
+
+- Fixed a single-provider usage refresh from an auth broker client (`omp usage invalidate --provider`, Codex auto-redeem, a saved-reset redeem) wiping the broker's cached usage for every provider, so other accounts showed no usage on every client until their next successful probe ([#14761](https://github.com/can1357/oh-my-pi/pull/14761) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed Anthropic sessions missing the prompt cache a second time after the API dropped thinking blocks from a changed conversation ([#14748](https://github.com/can1357/oh-my-pi/pull/14748) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed Cursor logins never renewing: every refresh was rejected with "Invalid User API Key", so logins lapsed about 60 days after sign-in; a session Cursor has ended is now disabled with a re-login hint ([#14753](https://github.com/can1357/oh-my-pi/pull/14753) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed the auth broker logging caller-supplied `X-Forwarded-For` / `X-Real-IP` values and unknown request paths; peers come from the socket unless `trustProxyHeaders` is set ([#14762](https://github.com/can1357/oh-my-pi/pull/14762) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed false thinking-loop detections on Gemini, DeepSeek, and Grok when the model drafts or answers with repetitive code or markup (VRML, SVG, JSON); such output is no longer discarded and retried.
+- Fixed Cursor provider leaking conversation checkpoints, blob stores and abort listeners after requests end ([#14669](https://github.com/can1357/oh-my-pi/pull/14669) by [@H4vC](https://github.com/H4vC))
+- Fixed session-affinity pins growing without bound in long-lived gateways (now capped at 256 sessions per provider) ([#14672](https://github.com/can1357/oh-my-pi/pull/14672) by [@H4vC](https://github.com/H4vC))
+- Fixed completed Cursor turns failing with "Cursor stream ended before turnEnded" when the connection closed after the answer had fully arrived ([#14851](https://github.com/can1357/oh-my-pi/pull/14851) by [@kyle-elliott-asymptote](https://github.com/kyle-elliott-asymptote)).
+- Fixed Cursor provider errors that Cursor marks as not retryable being retried until the retry budget ran out ([#14851](https://github.com/can1357/oh-my-pi/pull/14851) by [@kyle-elliott-asymptote](https://github.com/kyle-elliott-asymptote)).
+
+## [18.8.3] - 2026-10-07
+
+### Added
+
+- Added `OAuthRefreshUnavailableError`, a retryable error that `keys.getWithCredential` and `oauth.access` reject with when every usable OAuth credential failed to refresh transiently; `keys.get` resolves `undefined` instead so availability probes move on to their next candidate ([#14843](https://github.com/can1357/oh-my-pi/pull/14843) by [@H4vC](https://github.com/H4vC))
+
+### Fixed
+
+- Fixed a single transient OAuth token-refresh failure (network blip, timeout, 5xx) ending a running session, including subagents restricted to an account pool, with a non-retryable "No API key for provider" error while the stored credential was still valid; the refresh error now surfaces and the request is retried ([#14843](https://github.com/can1357/oh-my-pi/pull/14843) by [@H4vC](https://github.com/H4vC))
+
 ## [18.8.1] - 2026-10-07
 
 ### Added
@@ -2297,67 +2329,4 @@
 - Fixed `validateToolArguments` silently accepting JSON-encoded array strings (e.g. `'["a","b"]'`) against `union(string, array<string>)` schemas — providers that double-serialize tool-call arguments (Z.AI / GLM) caused tools like `search` to receive the literal `["a","b"]` as a single path, producing zero matches (single element) or glob parse errors (multi-element). A new pre-validation pass parses JSON-array-shaped strings when the schema explicitly accepts both shapes. ([#1788](https://github.com/can1357/oh-my-pi/issues/1788))
 - Fixed Anthropic thinking summaries that arrive wrapped in literal `<thinking>` tags so advisor/raw transcript dumps do not render nested thinking tags ([#2695](https://github.com/can1357/oh-my-pi/issues/2695)).
 
-## [16.0.0] - 2026-06-15
-
-### Breaking Changes
-
-- Renamed the public dialect entrypoint from `@oh-my-pi/pi-ai/grammar` to `@oh-my-pi/pi-ai/dialect`.
-- Renamed grammar dialect identifiers from `ToolCallSyntax` to `Dialect`, renamed the `Grammar` interface to `DialectDefinition`, and renamed `Grammar.syntax` to `DialectDefinition.dialect`.
-- Added `DialectDefinition.renderThinking` and `DialectDefinition.renderTranscript` so dialect implementations serialize complete native chat transcripts, not just tool call/result blocks.
-
-### Added
-
-- Added `renderTranscript` method to dialect definitions for serializing complete native chat transcripts
-- Added `renderThinking` method to dialect definitions for rendering thinking/reasoning blocks
-- Added support for 11 dialect implementations: Anthropic, DeepSeek, Gemini, Gemma, GLM, Harmony, Hermes, Kimi, Pi-native, Qwen3, and XML
-- Added `createInbandScanner` factory function to instantiate dialect-specific scanners
-- Added `getDialectDefinition` function to retrieve dialect implementations by name
-- Added `renderToolCatalog` and `renderInbandToolPrompt` functions for tool catalog rendering
-- Added `renderToolInventory` function to generate human-readable per-tool documentation with examples
-- Added `renderToolExamples` function to render tool usage examples in the model's native dialect
-- Added `encodeInbandToolHistory` function to encode tool call history in dialect-specific format
-- Added `wrapInbandToolStream` function to process streaming responses with in-band tool call parsing
-- Added `ThinkingInbandScanner` for parsing thinking/reasoning blocks across dialects
-- Added `OwnedStream` class for managing dialect-aware streaming with tool call events
-- Added in-band thinking channels to every dialect that was missing one: `gemini` (a ` ```thinking ` fence mirroring ` ```tool_code `), `gemma` (its native `<|channel>thought…<channel|>` reasoning channel), `kimi` (`<think>…</think>`), and `pi` (`<thinking>…</thinking>`). Each scanner now parses reasoning into thinking events instead of leaking chain-of-thought into the visible reply, and every dialect's `renderThinking` is a real channel that round-trips back through its scanner (no passthrough renderers).
-
-### Changed
-
-- Moved public dialect entrypoint from `@oh-my-pi/pi-ai/grammar` to `@oh-my-pi/pi-ai/dialect` in package exports
-- Updated internal imports in `stream-markup-healing.ts` to use new dialect module path
-- Changed `renderToolInventory` to demote a tool description's own markdown headers by one level when it contains a top-level `# ` header, so they nest under the wrapping `# Tool: <name>` heading instead of reading as sibling sections. Descriptions that already start at `##` and headers inside fenced code blocks are left untouched.
-
-### Fixed
-
-- Fixed Gemini, Gemma, Kimi, and Pi in-band scanners to respect `parseThinking: false`, leaving private reasoning markers in visible text when parsing is disabled
-- Fixed thinking-channel parsing for streaming Gemini, Gemma, Kimi, and Pi outputs so split or partial `<thinking>` blocks no longer leak into visible replies
-- Fixed in-band thinking finalization and Kimi stream-healing interactions so leaked `<think>` blocks are preserved when structured tool calls are present, not duplicated when explicit reasoning is present, and closed on stream flush.
-
-### Removed
-
-- Removed `src/grammar/factory.ts` (replaced by `src/dialect/factory.ts`)
-- Removed `src/grammar/rendering.ts` (functionality moved to `src/dialect/rendering.ts`)
-- Removed `src/grammar/xml.ts` (replaced by `src/dialect/xml.ts`)
-
-## [15.13.3] - 2026-06-15
-
-### Added
-
-- Added the `gemini` in-band tool-call syntax with Python-style `tool_code` blocks and `default_api` invocations
-- Added the `gemma` token-delimited in-band tool-call syntax using `<|tool_call>` and `<|tool_response>` blocks
-- Added `gemini` and `gemma` to owned stream tool-result token detection so their tool responses are recognized
-- Fixed truncated Gemini and Gemma tool blocks from being emitted as plain text during streaming
-- Added the Azure OpenAI provider definition (`azure`) to the registry; `AZURE_OPENAI_API_KEY` resolves as its env-var API key via the catalog provider table.
-
-### Changed
-
-- Gemini tool-call examples now render without the `default_api.` namespace prefix, keeping `<example>` blocks concise. The live wire format still uses `default_api.` per the Gemini grammar.
-
-### Fixed
-
-- Fixed duplicate tool call projections by deduplicating provider-native `toolCall` events against in-band `tool_code` calls and keeping only the first real channel
-- Dropped nameless native `toolCall` events so they no longer appear as surfaced tool calls in owned-mode streams
-- Fixed truncated Gemini and Gemma tool blocks from being emitted as plain text during streaming
-- Fixed Gemini/Gemma in-band tool-call parsing around Python comments, raw/unicode string literals, and Gemma close-token text inside string values.
-
-Older entries are archived in [packages/ai/CHANGELOG.md@a20cc0d04b64](https://github.com/can1357/oh-my-pi/blob/a20cc0d04b64f4a68fcc559cbd258743d984c50e/packages/ai/CHANGELOG.md).
+Older entries are archived in [packages/ai/CHANGELOG.md@d22e34333695](https://github.com/can1357/oh-my-pi/blob/d22e34333695d3dd9de7741ff45903681dba4606/packages/ai/CHANGELOG.md).

package/dist/types/auth/cascade.d.ts

@@ -2,7 +2,7 @@ import { type ApiKeyResolver, type ResolvedApiKey } from "../auth-retry.js";
 import type { SessionAffinity } from "./affinity.js";
 import type { CredentialPool } from "./pool.js";
 import type { CredentialSelector } from "./select.js";
-import type { AuthApiKeyOptions, AuthCredential, AuthSource, AuthSourceOptions, KeysApi, LimitsApi, OAuthRequestIdentity } from "./types.js";
+import type { AuthApiKeyOptions, AuthCredential, AuthSource, AuthSourceOptions, KeysApi, LimitsApi } from "./types.js";
 /** Runtime (--api-key) and config (models.yml) key overrides plus the config-value resolver. */
 export declare class KeyOverrides {
     #private;
@@ -117,7 +117,13 @@ export declare class KeyCascade implements KeysApi {
      * credential to reach the correct host.
      */
     peek(provider: string): Promise<string | undefined>;
-    /** Resolve a bearer together with the stored row that supplied it. */
+    /**
+     * Resolve a bearer together with the stored row that supplied it, for a request.
+     * Same precedence as {@link KeyCascade.get}, but rejects with
+     * {@link AIError.OAuthRefreshUnavailableError} (transient, retryable) when OAuth
+     * refresh failed with a retryable error and no other permitted source could serve
+     * the request, so request paths retry instead of reporting a missing key.
+     */
     getWithCredential(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<ResolvedApiKey | undefined>;
     /**
      * Get API key for a provider.
@@ -127,8 +133,11 @@ export declare class KeyCascade implements KeysApi {
      * OAuth accounts and throws {@link AIError.MissingApiKeyError} when none
      * can serve or a config key (a models.yml `apiKey`, often for a proxy
      * `baseUrl`) owns the provider, rather than using any other credential.
+     * A transient OAuth refresh failure resolves `undefined`, so availability
+     * probes move on to their next candidate; request paths use
+     * {@link KeyCascade.getWithCredential}, which surfaces it.
      */
-    get(provider: string, sessionId?: string, options?: AuthApiKeyOptions, onCredentialId?: (id: number, identity?: OAuthRequestIdentity) => void): Promise<string | undefined>;
+    get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
     /**
      * Build an {@link ApiKeyResolver} backed by this storage, implementing the
      * central a/b/c auth-retry policy:

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

@@ -37,9 +37,11 @@ export declare class OAuthAccounts implements OAuthApi {
      * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
      * scenarios, prefer API-key resolution.
      *
-     * 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.
+     * Returns `undefined` when no usable OAuth credential is available
+     * (none stored, or every one definitively failed to refresh) or
+     * runtime/config overrides have replaced OAuth with an explicit API key.
+     * Rejects with {@link AIError.OAuthRefreshUnavailableError} (transient,
+     * retryable) when a retryable refresh failure left no usable credential.
      */
     access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
     /**

package/dist/types/auth/select.d.ts

@@ -32,6 +32,8 @@ export type TryOAuthOptions = {
     blockScopes?: readonly string[];
     /** When false, a definitive failure of THIS credential returns undefined instead of falling back to the ranked/round-robin selector (target-only resolution). */
     allowFallback?: boolean;
+    /** Receives a non-definitive refresh failure that left this credential unusable; the caller filters for retryable ones. */
+    onTransientRefreshFailure?: (error: unknown) => void;
 };
 /** Services consulted by CredentialSelector for policy, usage, blocks, refresh, and session affinity. */
 export interface CredentialSelectorDeps {

package/dist/types/auth/store.d.ts

@@ -122,8 +122,8 @@ export interface UsageLedgerStore {
 }
 /** Broker-delegated OAuth refresh and usage-report operations. */
 export interface CredentialUpstream {
-    /** Optional hook to notify the underlying store that usage report cache is stale. */
-    invalidateUsageCache(signal?: AbortSignal): Promise<void>;
+    /** Optional hook to notify the underlying store that usage reports (one provider's, when given) are stale. */
+    invalidateUsageCache(provider?: string, signal?: AbortSignal): Promise<void>;
     /**
      * Optional store-supplied OAuth refresh. When present, `AuthStorage` uses
      * it before the per-provider local refresh path. `RemoteAuthCredentialStore`

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

@@ -812,9 +812,20 @@ export interface KeysApi {
      * 4. API key persisted by a successful `/login`
      * 5. Environment variable
      * 6. Stored API key (e.g. a broker-migrated copy) — last resort, so an explicit env var wins
+     *
+     * Resolves `undefined` when no permitted credential can serve, including when
+     * OAuth refresh failed transiently (network, timeout, 5xx), so availability
+     * probes move on to their next candidate. Request paths use
+     * {@link KeysApi.getWithCredential}, which surfaces that failure.
      */
     get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
-    /** Resolve a bearer together with its durable stored credential row id, when known. */
+    /**
+     * Resolve a bearer together with its durable stored credential row id, when known.
+     * Same precedence as {@link KeysApi.get}, but rejects with
+     * `OAuthRefreshUnavailableError` (transient, retryable) when OAuth refresh failed
+     * with a retryable error and no other permitted source could serve the request;
+     * the stored credential is kept.
+     */
     getWithCredential(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<ResolvedApiKey | undefined>;
     /**
      * Peek at API key for a provider without refreshing OAuth tokens.
@@ -935,9 +946,11 @@ export interface OAuthApi {
      * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
      * scenarios, prefer {@link AuthStorage.keys.get}.
      *
-     * 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.
+     * Returns `undefined` when no usable OAuth credential is available (none
+     * stored, or every one definitively failed to refresh) or runtime/config
+     * overrides have replaced OAuth with an explicit API key. Rejects with
+     * `OAuthRefreshUnavailableError` (transient, retryable) when a retryable
+     * refresh failure left no usable credential.
      */
     access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
     /**

package/dist/types/auth-broker/client.d.ts

@@ -85,7 +85,7 @@ export declare class AuthBrokerClient {
     fetchClientUsageSummary(query?: {
         sinceMs?: number;
     }, signal?: AbortSignal): Promise<ClientUsageSummaryResponse>;
-    notifyUsageStale(signal?: AbortSignal): Promise<UsageStaleResponse>;
+    notifyUsageStale(provider?: string, signal?: AbortSignal): Promise<UsageStaleResponse>;
     refreshCredential(id: number, signal?: AbortSignal, reason?: OAuthRefreshReason): Promise<CredentialRefreshResponse>;
     disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;
     /**

package/dist/types/auth-broker/remote-store.d.ts

@@ -122,7 +122,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     /** Drop all cache rows whose keys start with the supplied prefix. */
     deleteCachePrefix(prefix: string): void;
     cleanExpiredCache(): void;
-    invalidateUsageCache(signal?: AbortSignal): Promise<void>;
+    invalidateUsageCache(provider?: string, signal?: AbortSignal): Promise<void>;
     /**
      * Store-level hook consumed by `AuthStorage` — routes refresh through the
      * broker so the actual refresh token never leaves the broker host. Returns

package/dist/types/auth-broker/server.d.ts

@@ -17,6 +17,8 @@ export interface AuthBrokerServerOptions {
     bind?: string;
     /** Accept any of these bearer tokens. Empty disables auth (loopback only). */
     bearerTokens: string[];
+    /** Honor forwarded peer headers only when the connecting proxy is trusted. Default false. */
+    trustProxyHeaders?: boolean;
     /** Broker version string surfaced on `/v1/healthz`. */
     version?: string;
     /** Refresh credentials expiring within this window. Default 5 min. */

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

@@ -17,6 +17,8 @@ export interface AuthGatewayRouteOptions {
     resolveModel: ModelResolver;
     /** Optional supplier for `/v1/models` listing. Returns the full model array. */
     listModels?: () => Iterable<Model<Api>>;
+    /** Providers the host does not serve; `/v1/usage` and `/v1/credentials/check` leave their accounts out. */
+    excludeProviders?: ReadonlySet<string>;
     /** Upstream transport for every provider call; defaults to global `fetch`. Test seam. */
     fetch?: FetchImpl;
 }

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

@@ -16,8 +16,6 @@ export declare function gatewayResponseHeaders(model: Model<Api>, info: {
     costUsd?: number;
     startedAt?: number;
 }): Record<string, string>;
-/** Use the socket peer unless the gateway explicitly trusts its reverse proxy. */
-export declare function resolvePeer(req: Request, socketAddress: string, trustProxyHeaders?: boolean): string;
 /** Keep configured gateway credentials out of URL and forwarded/logged request fields. */
 export declare function hasMisplacedBearer(req: Request, url: URL, tokens: ReadonlySet<string>): boolean;
 /**

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

@@ -10,6 +10,16 @@ export declare class MissingApiKeyError extends Error {
     readonly provider: string | undefined;
     constructor(provider?: string, message?: string);
 }
+/**
+ * Every usable OAuth credential for a provider failed to refresh with a
+ * retryable error (network blip, timeout, 5xx). The stored credentials are
+ * intact, so this is classified transient: retrying the request can succeed,
+ * unlike {@link MissingApiKeyError}. The refresh failure is kept as `cause`.
+ */
+export declare class OAuthRefreshUnavailableError extends Error {
+    readonly provider: string;
+    constructor(provider: string, cause: unknown);
+}
 /** A user-facing login flow required an `onPrompt` callback that was not supplied. */
 export declare class OnPromptRequiredError extends Error {
     constructor(providerLabel: string);

package/dist/types/provider-session-state.d.ts

@@ -18,8 +18,8 @@
  *   siblings are endpoint-scoped and stay: `strictToolsDisabled`
  *   (grammar-too-large 400 for the model's tool schema),
  *   `replayUnsignedThinkingDisabled` / `thinkingReplayDisabled` (the endpoint
- *   is a signing proxy), `prefixDroppedThinkingBlocks` (blocks the API itself
- *   dropped).
+ *   is a signing proxy), `prefixDroppedThinkingBlocks` (blocks a prefix-binding
+ *   400 made the client strip).
  * - **OpenAI Responses** — the `previous_response_id` chain baselines are
  *   account-scoped: a stored response belongs to the account that created it.
  *   Strict-tools / reasoning-effort fallbacks, replay warmup and the chaining

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

@@ -13,7 +13,7 @@ export declare function pollCursorAuth(uuid: string, verifier: string): Promise<
 }>;
 export declare function loginCursor(onAuthUrl: (url: string) => void, onPollStart?: () => void): Promise<OAuthCredentials>;
 export declare function loginCursorHook(callbacks: OAuthController): Promise<OAuthCredentials>;
-export declare function refreshCursorToken(apiKeyOrRefreshToken: string): Promise<OAuthCredentials>;
+export declare function refreshCursorToken(refreshToken: string): Promise<OAuthCredentials>;
 export declare function refreshCursorHook(credentials: OAuthCredentials, signal?: AbortSignal): Promise<OAuthCredentials>;
 /** Request headers that present `accessToken` to cursor.com as its user's web session. */
 export declare function cursorSessionHeaders(userId: string, accessToken: string): Record<string, string>;

package/dist/types/utils/resolve-peer.d.ts

@@ -0,0 +1,2 @@
+/** Use the socket peer unless the server explicitly trusts its reverse proxy. */
+export declare function resolvePeer(req: Request, socketAddress: string, trustProxyHeaders?: boolean): string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.8.2",
+	"version": "18.8.4",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -155,11 +155,11 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.8.2",
-		"@oh-my-pi/pi-catalog": "18.8.2",
-		"@oh-my-pi/pi-natives": "18.8.2",
-		"@oh-my-pi/pi-utils": "18.8.2",
-		"@oh-my-pi/pi-wire": "18.8.2"
+		"@oh-my-pi/omptype": "18.8.4",
+		"@oh-my-pi/pi-catalog": "18.8.4",
+		"@oh-my-pi/pi-natives": "18.8.4",
+		"@oh-my-pi/pi-utils": "18.8.4",
+		"@oh-my-pi/pi-wire": "18.8.4"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/auth/cascade.ts

@@ -1,5 +1,5 @@
 import { authPolicyFor } from "@oh-my-pi/pi-catalog/compat/auth";
-import { $env, $envExact } from "@oh-my-pi/pi-utils";
+import { $env, $envExact, logger } from "@oh-my-pi/pi-utils";
 import { type ApiKeyResolver, markAfterSiblingWait, type ResolvedApiKey } from "../auth-retry";
 import { getEnvApiKey, getEnvApiKeyName } from "../env-api-key";
 import * as AIError from "../error";
@@ -7,7 +7,7 @@ import { isUsageLimitOutcome } from "../error/rate-limit";
 import { AUTHENTICATED_SENTINEL } from "../registry/types";
 import type { SessionAffinity } from "./affinity";
 import type { CredentialPool } from "./pool";
-import type { CredentialSelector } from "./select";
+import type { CredentialSelector, OAuthResolutionResult } from "./select";
 import type {
 	AuthApiKeyOptions,
 	AuthCredential,
@@ -308,7 +308,13 @@ export class KeyCascade implements KeysApi {
 		return undefined;
 	}
 
-	/** Resolve a bearer together with the stored row that supplied it. */
+	/**
+	 * Resolve a bearer together with the stored row that supplied it, for a request.
+	 * Same precedence as {@link KeyCascade.get}, but rejects with
+	 * {@link AIError.OAuthRefreshUnavailableError} (transient, retryable) when OAuth
+	 * refresh failed with a retryable error and no other permitted source could serve
+	 * the request, so request paths retry instead of reporting a missing key.
+	 */
 	async getWithCredential(
 		provider: string,
 		sessionId?: string,
@@ -316,7 +322,7 @@ export class KeyCascade implements KeysApi {
 	): Promise<ResolvedApiKey | undefined> {
 		let credentialId: number | undefined;
 		let oauthIdentity: OAuthRequestIdentity | undefined;
-		const apiKey = await this.get(provider, sessionId, options, (id, identity) => {
+		const apiKey = await this.#resolve(provider, sessionId, options, (id, identity) => {
 			credentialId = id;
 			oauthIdentity = identity;
 		});
@@ -331,8 +337,21 @@ export class KeyCascade implements KeysApi {
 	 * OAuth accounts and throws {@link AIError.MissingApiKeyError} when none
 	 * can serve or a config key (a models.yml `apiKey`, often for a proxy
 	 * `baseUrl`) owns the provider, rather than using any other credential.
+	 * A transient OAuth refresh failure resolves `undefined`, so availability
+	 * probes move on to their next candidate; request paths use
+	 * {@link KeyCascade.getWithCredential}, which surfaces it.
 	 */
-	async get(
+	async get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined> {
+		try {
+			return await this.#resolve(provider, sessionId, options);
+		} catch (error) {
+			if (!(error instanceof AIError.OAuthRefreshUnavailableError)) throw error;
+			logger.debug("API key probe skipped transient OAuth refresh failure", { provider, error: error.message });
+			return undefined;
+		}
+	}
+
+	async #resolve(
 		provider: string,
 		sessionId?: string,
 		options?: AuthApiKeyOptions,
@@ -363,7 +382,16 @@ export class KeyCascade implements KeysApi {
 
 		// Precedence: a deliberate OAuth/login credential wins, then an explicit env var,
 		// then a stored static api_key (which may be a stale broker-migrated copy) as a last resort.
-		const oauthResolved = await this.#deps.selector.resolveOAuth(provider, sessionId, options);
+		// A transient OAuth refresh failure still lets later sources serve the request; it is
+		// rethrown only when none can, so callers retry instead of reporting a missing key.
+		let oauthResolved: OAuthResolutionResult | undefined;
+		let oauthRefreshFailure: AIError.OAuthRefreshUnavailableError | undefined;
+		try {
+			oauthResolved = await this.#deps.selector.resolveOAuth(provider, sessionId, options);
+		} catch (error) {
+			if (!(error instanceof AIError.OAuthRefreshUnavailableError)) throw error;
+			oauthRefreshFailure = error;
+		}
 		if (oauthResolved) {
 			if (onCredentialId && oauthResolved.credentialId !== undefined) {
 				const { orgId, region, inferenceRegion } = oauthResolved.credential;
@@ -372,6 +400,7 @@ export class KeyCascade implements KeysApi {
 			return oauthResolved.apiKey;
 		}
 		if (restricted) {
+			if (oauthRefreshFailure) throw oauthRefreshFailure;
 			throw new AIError.MissingApiKeyError(
 				provider,
 				`No API key for provider: ${provider} (session ${sessionId} is restricted to its OAuth account pool and none of those accounts is available)`,
@@ -420,6 +449,7 @@ export class KeyCascade implements KeysApi {
 			if (apiKey !== undefined && credentialId !== undefined) onCredentialId?.(credentialId);
 			return apiKey;
 		}
+		if (oauthRefreshFailure) throw oauthRefreshFailure;
 		return undefined;
 	}
 

package/src/auth/oauth.ts

@@ -127,9 +127,11 @@ export class OAuthAccounts implements OAuthApi {
 	 * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
 	 * scenarios, prefer API-key resolution.
 	 *
-	 * 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.
+	 * Returns `undefined` when no usable OAuth credential is available
+	 * (none stored, or every one definitively failed to refresh) or
+	 * runtime/config overrides have replaced OAuth with an explicit API key.
+	 * Rejects with {@link AIError.OAuthRefreshUnavailableError} (transient,
+	 * retryable) when a retryable refresh failure left no usable credential.
 	 */
 	async access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined> {
 		// Runtime / config overrides intentionally short-circuit OAuth: when the

package/src/auth/resets.ts

@@ -262,7 +262,7 @@ export class ResetCredits implements ResetsApi {
 				resetSpentCredentialId: access.credentialId,
 			});
 			if (this.#deps.store.invalidateUsageCache) {
-				await this.#deps.store.invalidateUsageCache(options.signal).catch(err => {
+				await this.#deps.store.invalidateUsageCache(provider, options.signal).catch(err => {
 					logger.debug("Failed to notify store of stale usage", { err });
 				});
 			}

package/src/auth/select.ts

@@ -65,6 +65,8 @@ export type TryOAuthOptions = {
 	blockScopes?: readonly string[];
 	/** When false, a definitive failure of THIS credential returns undefined instead of falling back to the ranked/round-robin selector (target-only resolution). */
 	allowFallback?: boolean;
+	/** Receives a non-definitive refresh failure that left this credential unusable; the caller filters for retryable ones. */
+	onTransientRefreshFailure?: (error: unknown) => void;
 };
 
 /** Services consulted by CredentialSelector for policy, usage, blocks, refresh, and session affinity. */
@@ -653,6 +655,14 @@ export class CredentialSelector {
 							: { selection, usage: null, usageChecked: false },
 					);
 		const preflightFailures = new Set<OAuthCandidate>();
+		// The last retryable refresh error (network, timeout, 5xx) that removed a candidate.
+		// When no candidate resolves, it is rethrown so callers retry instead of reporting
+		// a missing key. Refresher outcomes after a dead grant (row disabled, CAS lost) are
+		// classified auth failures and keep resolving to undefined.
+		let transientRefreshFailure: unknown;
+		const recordTransientRefreshFailure = (error: unknown): void => {
+			if (AIError.retriable(AIError.classify(error))) transientRefreshFailure = error;
+		};
 
 		const sessionPreferredCandidate = candidates.findIndex(
 			candidate =>
@@ -799,16 +809,21 @@ export class CredentialSelector {
 							// to a sibling account with the wrong prefetched usage/plan.
 							return;
 						}
-					} else if (credentialId !== undefined) {
-						const latestIndex = this.#deps.pool.entries(provider).findIndex(entry => entry.id === credentialId);
-						if (latestIndex !== -1) {
-							this.#deps.blocks.mark(
-								provider,
-								providerKey,
-								latestIndex,
-								Date.now() + OAUTH_REFRESH_FAILURE_BACKOFF_MS,
-								AUTH_BLOCK_SCOPE,
-							);
+					} else {
+						recordTransientRefreshFailure(error);
+						if (credentialId !== undefined) {
+							const latestIndex = this.#deps.pool
+								.entries(provider)
+								.findIndex(entry => entry.id === credentialId);
+							if (latestIndex !== -1) {
+								this.#deps.blocks.mark(
+									provider,
+									providerKey,
+									latestIndex,
+									Date.now() + OAUTH_REFRESH_FAILURE_BACKOFF_MS,
+									AUTH_BLOCK_SCOPE,
+								);
+							}
 						}
 					}
 					preflightFailures.add(candidate);
@@ -882,11 +897,15 @@ export class CredentialSelector {
 					rankingContext,
 					blockScope,
 					blockScopes,
+					onTransientRefreshFailure: recordTransientRefreshFailure,
 				});
 				if (resolved) return resolved;
 			}
 		}
 
+		if (transientRefreshFailure !== undefined) {
+			throw new AIError.OAuthRefreshUnavailableError(provider, transientRefreshFailure);
+		}
 		return undefined;
 	}
 
@@ -1117,6 +1136,7 @@ export class CredentialSelector {
 					if (allowFallback) return this.resolveOAuth(provider, sessionId, options);
 				}
 			} else {
+				usageOptions.onTransientRefreshFailure?.(error);
 				// Block temporarily for transient failures (5 minutes)
 				this.#deps.blocks.mark(
 					provider,

package/src/auth/store.ts

@@ -152,8 +152,8 @@ export interface UsageLedgerStore {
 
 /** Broker-delegated OAuth refresh and usage-report operations. */
 export interface CredentialUpstream {
-	/** Optional hook to notify the underlying store that usage report cache is stale. */
-	invalidateUsageCache(signal?: AbortSignal): Promise<void>;
+	/** Optional hook to notify the underlying store that usage reports (one provider's, when given) are stale. */
+	invalidateUsageCache(provider?: string, signal?: AbortSignal): Promise<void>;
 	/**
 	 * Optional store-supplied OAuth refresh. When present, `AuthStorage` uses
 	 * it before the per-provider local refresh path. `RemoteAuthCredentialStore`

package/src/auth/types.ts

@@ -894,9 +894,20 @@ export interface KeysApi {
 	 * 4. API key persisted by a successful `/login`
 	 * 5. Environment variable
 	 * 6. Stored API key (e.g. a broker-migrated copy) — last resort, so an explicit env var wins
+	 *
+	 * Resolves `undefined` when no permitted credential can serve, including when
+	 * OAuth refresh failed transiently (network, timeout, 5xx), so availability
+	 * probes move on to their next candidate. Request paths use
+	 * {@link KeysApi.getWithCredential}, which surfaces that failure.
 	 */
 	get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
-	/** Resolve a bearer together with its durable stored credential row id, when known. */
+	/**
+	 * Resolve a bearer together with its durable stored credential row id, when known.
+	 * Same precedence as {@link KeysApi.get}, but rejects with
+	 * `OAuthRefreshUnavailableError` (transient, retryable) when OAuth refresh failed
+	 * with a retryable error and no other permitted source could serve the request;
+	 * the stored credential is kept.
+	 */
 	getWithCredential(
 		provider: string,
 		sessionId?: string,
@@ -1017,9 +1028,11 @@ export interface OAuthApi {
 	 * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
 	 * scenarios, prefer {@link AuthStorage.keys.get}.
 	 *
-	 * 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.
+	 * Returns `undefined` when no usable OAuth credential is available (none
+	 * stored, or every one definitively failed to refresh) or runtime/config
+	 * overrides have replaced OAuth with an explicit API key. Rejects with
+	 * `OAuthRefreshUnavailableError` (transient, retryable) when a retryable
+	 * refresh failure left no usable credential.
 	 */
 	access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
 	/**

package/src/auth/usage.ts

@@ -871,7 +871,7 @@ export class UsageService implements UsageApi {
 		await this.#deps.cache.clearReports(provider, () => this.#collectUsageRequests());
 
 		if (this.#deps.store.invalidateUsageCache) {
-			await this.#deps.store.invalidateUsageCache(signal).catch(err => {
+			await this.#deps.store.invalidateUsageCache(provider, signal).catch(err => {
 				logger.debug("Failed to notify store of stale usage", { err });
 			});
 		}

package/src/auth-broker/client.ts

@@ -309,8 +309,11 @@ export class AuthBrokerClient {
 		});
 	}
 
-	notifyUsageStale(signal?: AbortSignal): Promise<UsageStaleResponse> {
-		return this.#request<UsageStaleResponse>("POST", "/v1/usage/stale", {
+	notifyUsageStale(provider?: string, signal?: AbortSignal): Promise<UsageStaleResponse> {
+		const params = new URLSearchParams();
+		if (provider) params.set("provider", provider);
+		const path = `/v1/usage/stale${params.size > 0 ? `?${params.toString()}` : ""}`;
+		return this.#request<UsageStaleResponse>("POST", path, {
 			schema: "usageStaleResponseSchema",
 			signal,
 		});

package/src/auth-broker/remote-store.ts

@@ -1196,11 +1196,11 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		}
 	}
 
-	async invalidateUsageCache(signal?: AbortSignal): Promise<void> {
+	async invalidateUsageCache(provider?: string, signal?: AbortSignal): Promise<void> {
 		this.#noteActivity();
 		this.#invalidateUsageCache();
 		try {
-			await this.#client.notifyUsageStale(signal);
+			await this.#client.notifyUsageStale(provider, signal);
 		} catch (err) {
 			logger.warn("auth-broker notification of stale usage failed", { error: String(err) });
 		} finally {

package/src/auth-broker/server.ts

@@ -14,6 +14,7 @@ import { type Type, type } from "@oh-my-pi/omptype";
 import { logger } from "@oh-my-pi/pi-utils";
 import type { AuthCredentialSnapshotEntry, AuthStorage, StoredCredentialBlock } from "../auth-storage";
 import { parseBind } from "../utils/parse-bind";
+import { resolvePeer } from "../utils/resolve-peer";
 import { AuthBrokerRefresher, type AuthBrokerRefresherSchedule } from "./refresher";
 import type {
 	ClientUsageReportRequest,
@@ -62,6 +63,8 @@ export interface AuthBrokerServerOptions {
 	bind?: string;
 	/** Accept any of these bearer tokens. Empty disables auth (loopback only). */
 	bearerTokens: string[];
+	/** Honor forwarded peer headers only when the connecting proxy is trusted. Default false. */
+	trustProxyHeaders?: boolean;
 	/** Broker version string surfaced on `/v1/healthz`. */
 	version?: string;
 	/** Refresh credentials expiring within this window. Default 5 min. */
@@ -156,6 +159,24 @@ const REFRESH_ROUTE = /^\/v1\/credential\/(\d+)\/refresh$/;
 const DISABLE_ROUTE = /^\/v1\/credential\/(\d+)\/disable$/;
 const BLOCK_ROUTE = /^\/v1\/credential\/(\d+)\/block$/;
 const BLOCKS_ROUTE = /^\/v1\/credential\/(\d+)\/blocks$/;
+const STATIC_ROUTES: Record<string, true> = {
+	"/v1/snapshot/stream": true,
+	"/v1/snapshot": true,
+	"/v1/usage": true,
+	"/v1/usage/history": true,
+	"/v1/usage/observed": true,
+	"/v1/usage/clients": true,
+	"/v1/usage/stale": true,
+	"/v1/credentials/disabled": true,
+	"/v1/credential": true,
+};
+
+/** Only known routes reach logs verbatim; unknown paths may carry caller-supplied secrets. */
+function loggablePath(pathname: string): string {
+	if (Object.hasOwn(STATIC_ROUTES, pathname)) return pathname;
+	const dynamic = [REFRESH_ROUTE, DISABLE_ROUTE, BLOCK_ROUTE, BLOCKS_ROUTE].some(route => route.test(pathname));
+	return dynamic ? pathname : "<unrouted>";
+}
 
 const MAX_SNAPSHOT_WAIT_MS = 30_000;
 const DISABLED_NEXT_SWEEP_IN_MS = Number.MAX_SAFE_INTEGER;
@@ -808,20 +829,24 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 		hostname: bind.hostname,
 		port: bind.port,
 		idleTimeout: DEFAULT_SERVER_IDLE_TIMEOUT_S,
-		fetch: async (req): Promise<Response> => {
+		fetch: async (req, server): Promise<Response> => {
 			const url = new URL(req.url);
 			const pathname = url.pathname;
-			const peer =
-				req.headers.get("x-forwarded-for")?.split(",")[0].trim() || req.headers.get("x-real-ip") || "unknown";
+			const socketPeer = server.requestIP(req)?.address ?? "unknown";
 			try {
 				if (req.method === "GET" && pathname === "/v1/healthz") {
 					const body: HealthzResponse = { ok: true, version };
 					return json(200, body);
 				}
 				if (!isAuthorized(req, tokens)) {
-					logger.info("auth-broker request unauthorized", { method: req.method, path: pathname, peer });
+					logger.info("auth-broker request unauthorized", {
+						method: req.method,
+						path: loggablePath(pathname),
+						peer: socketPeer,
+					});
 					return json(401, { error: "unauthorized" });
 				}
+				const peer = resolvePeer(req, socketPeer, opts.trustProxyHeaders);
 				if (req.method === "GET" && pathname === "/v1/snapshot/stream") {
 					return serveSnapshotStream(req, snapshotSource, streamHub, peer, streamKeepaliveMs);
 				}
@@ -887,9 +912,10 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 					return json(200, { generatedAt: Date.now(), clients: summary.clients });
 				}
 				if (req.method === "POST" && pathname === "/v1/usage/stale") {
+					const provider = url.searchParams.get("provider") || undefined;
 					try {
-						await opts.storage.usage.invalidate?.();
-						logger.info("auth-broker usage cache invalidated", { peer });
+						await opts.storage.usage.invalidate?.(provider);
+						logger.info("auth-broker usage cache invalidated", { peer, provider });
 						return json(200, { ok: true });
 					} catch (error) {
 						const message = error instanceof Error ? error.message : String(error);
@@ -1046,7 +1072,7 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 			} catch (error) {
 				logger.error("auth-broker handler crashed", {
 					method: req.method,
-					path: pathname,
+					path: loggablePath(pathname),
 					error: String(error),
 				});
 				return json(500, { error: "internal error" });

package/src/auth-gateway/dispatch.ts

@@ -32,6 +32,8 @@ export interface AuthGatewayRouteOptions {
 	resolveModel: ModelResolver;
 	/** Optional supplier for `/v1/models` listing. Returns the full model array. */
 	listModels?: () => Iterable<Model<Api>>;
+	/** Providers the host does not serve; `/v1/usage` and `/v1/credentials/check` leave their accounts out. */
+	excludeProviders?: ReadonlySet<string>;
 	/** Upstream transport for every provider call; defaults to global `fetch`. Test seam. */
 	fetch?: FetchImpl;
 }

package/src/auth-gateway/http.ts

@@ -51,14 +51,6 @@ export function gatewayResponseHeaders(
 	return headers;
 }
 
-/** Use the socket peer unless the gateway explicitly trusts its reverse proxy. */
-export function resolvePeer(req: Request, socketAddress: string, trustProxyHeaders = false): string {
-	if (!trustProxyHeaders) return socketAddress;
-	const fwd = req.headers.get("x-forwarded-for");
-	if (fwd) return fwd.split(",")[0].trim();
-	return req.headers.get("x-real-ip") ?? socketAddress;
-}
-
 /**
  * Decode each run of percent-escapes on its own, so one malformed escape
  * elsewhere in the URL cannot hide an encoded token. A run that is not valid

package/src/auth-gateway/server.ts

@@ -31,7 +31,6 @@
 import { Effort } from "@oh-my-pi/pi-catalog/effort";
 import { type ModelKind, modelKind } from "@oh-my-pi/pi-catalog/types";
 import { logger } from "@oh-my-pi/pi-utils";
-import type { AuthStorage } from "../auth-storage";
 import { classifyGatewayError } from "../error/gateway";
 import * as anthropicMessages from "../providers/anthropic-messages-server";
 import * as openaiChat from "../providers/openai-chat-server";
@@ -41,6 +40,7 @@ import { completeSimple, streamSimple } from "../stream";
 import type { Api, AssistantMessageEventStream, Context, Model, SimpleStreamOptions } from "../types";
 import { deterministicUuid } from "../utils/deterministic-id";
 import { parseBind } from "../utils/parse-bind";
+import { resolvePeer } from "../utils/resolve-peer";
 import {
 	type AuthGatewayBootOptions,
 	type AuthGatewayRouteOptions,
@@ -59,7 +59,6 @@ import {
 	isAuthorized,
 	json,
 	resolveClientIdentity,
-	resolvePeer,
 	withCors,
 } from "./http";
 import { handleEmbeddings } from "./routes/embeddings";
@@ -709,12 +708,14 @@ async function handlePiNative(
  * failure) inside `AuthStorage`, so this handler is a thin wrapper that
  * surfaces the same data to HTTP callers (notably the macOS usage widget).
  */
-async function handleUsage(storage: AuthStorage, signal: AbortSignal): Promise<Response> {
-	const reports = (await storage.usage.reports?.({ signal })) ?? [];
+async function handleUsage(opts: AuthGatewayRouteOptions, signal: AbortSignal): Promise<Response> {
+	const reports = (await opts.storage.usage.reports?.({ signal })) ?? [];
 	// Drop the heavy provider-specific `raw` payload — UI consumers only need
 	// `limits` + `metadata`. Match the broker's `/v1/usage` shape so a single
 	// client struct (Swift widget, llm-git, ...) works against either endpoint.
-	const trimmed = reports.map(({ raw: _raw, ...rest }) => rest);
+	const trimmed = reports
+		.filter(report => !opts.excludeProviders?.has(report.provider))
+		.map(({ raw: _raw, ...rest }) => rest);
 	return json(200, { generatedAt: Date.now(), reports: trimmed });
 }
 
@@ -729,8 +730,8 @@ async function handleUsage(storage: AuthStorage, signal: AbortSignal): Promise<R
  * endpoints. For multi-account pools that's the difference between getting
  * a clean diagnosis and getting a 429 storm.
  */
-async function handleCredentialsCheck(storage: AuthStorage, signal: AbortSignal): Promise<Response> {
-	const credentials = await storage.health.check({ signal });
+async function handleCredentialsCheck(opts: AuthGatewayRouteOptions, signal: AbortSignal): Promise<Response> {
+	const credentials = await opts.storage.health.check({ signal, excludeProviders: opts.excludeProviders });
 	return json(200, { generatedAt: Date.now(), credentials });
 }
 
@@ -832,14 +833,14 @@ export function createAuthGatewayRouter(opts: AuthGatewayRouteOptions): AuthGate
 			// Same shape as the broker's `/v1/usage`, so widget/llm-git speak to either with the
 			// same client struct.
 			if (req.method === "GET" && pathname === "/v1/usage") {
-				return await handleUsage(opts.storage, req.signal);
+				return await handleUsage(opts, req.signal);
 			}
 
 			// Per-credential auth probe — diagnoses which row in a multi-account
 			// pool is producing 401s. Aggregated `/v1/usage` silently drops failed
 			// credentials, so we need a separate endpoint that captures errors.
 			if (req.method === "GET" && pathname === "/v1/credentials/check") {
-				return await handleCredentialsCheck(opts.storage, req.signal);
+				return await handleCredentialsCheck(opts, req.signal);
 			}
 
 			// Provider-format dispatch.

package/src/error/auth.ts

@@ -19,6 +19,26 @@ export class MissingApiKeyError extends Error {
 	}
 }
 
+/**
+ * Every usable OAuth credential for a provider failed to refresh with a
+ * retryable error (network blip, timeout, 5xx). The stored credentials are
+ * intact, so this is classified transient: retrying the request can succeed,
+ * unlike {@link MissingApiKeyError}. The refresh failure is kept as `cause`.
+ */
+export class OAuthRefreshUnavailableError extends Error {
+	readonly provider: string;
+
+	constructor(provider: string, cause: unknown) {
+		super(
+			`OAuth token refresh failed for provider ${provider}: ${cause instanceof Error ? cause.message : String(cause)}`,
+			{ cause },
+		);
+		this.name = "OAuthRefreshUnavailableError";
+		this.provider = provider;
+		attach(this, create(Flag.Transient));
+	}
+}
+
 /** A user-facing login flow required an `onPrompt` callback that was not supplied. */
 export class OnPromptRequiredError extends Error {
 	constructor(providerLabel: string) {

package/src/provider-session-state.ts

@@ -18,8 +18,8 @@
  *   siblings are endpoint-scoped and stay: `strictToolsDisabled`
  *   (grammar-too-large 400 for the model's tool schema),
  *   `replayUnsignedThinkingDisabled` / `thinkingReplayDisabled` (the endpoint
- *   is a signing proxy), `prefixDroppedThinkingBlocks` (blocks the API itself
- *   dropped).
+ *   is a signing proxy), `prefixDroppedThinkingBlocks` (blocks a prefix-binding
+ *   400 made the client strip).
  * - **OpenAI Responses** — the `previous_response_id` chain baselines are
  *   account-scoped: a stored response belongs to the account that created it.
  *   Strict-tools / reasoning-effort fallbacks, replay warmup and the chaining

package/src/providers/anthropic.ts

@@ -486,8 +486,14 @@ type AnthropicProviderSessionState = ProviderSessionState & {
 	 * this (baseUrl, modelId). Cleared on session close.
 	 */
 	thinkingReplayDisabled: boolean;
-	/** Thinking blocks the API permanently dropped after a prefix mismatch. */
+	/** Thinking blocks stripped after a prefix-binding 400 forced a retry without `drop_block`. */
 	prefixDroppedThinkingBlocks: Set<string>;
+	/**
+	 * Server-reported `prefix_binding_mismatch` drops already warned about. A
+	 * `drop_block` request replays dropped blocks verbatim, so the API reports
+	 * them again on every later request; only newly dropped blocks warn.
+	 */
+	reportedPrefixDroppedThinking: Set<string>;
 };
 
 function createAnthropicProviderSessionState(): AnthropicProviderSessionState {
@@ -497,12 +503,14 @@ function createAnthropicProviderSessionState(): AnthropicProviderSessionState {
 		replayUnsignedThinkingDisabled: false,
 		thinkingReplayDisabled: false,
 		prefixDroppedThinkingBlocks: new Set(),
+		reportedPrefixDroppedThinking: new Set(),
 		close: () => {
 			state.strictToolsDisabled = false;
 			state.fastModeDisabled = false;
 			state.replayUnsignedThinkingDisabled = false;
 			state.thinkingReplayDisabled = false;
 			state.prefixDroppedThinkingBlocks.clear();
+			state.reportedPrefixDroppedThinking.clear();
 		},
 	};
 	return state;
@@ -518,6 +526,7 @@ function getAnthropicProviderSessionState(
 	const existing = providerSessionState.get(key) as AnthropicProviderSessionState | undefined;
 	if (existing) {
 		existing.prefixDroppedThinkingBlocks ??= new Set();
+		existing.reportedPrefixDroppedThinking ??= new Set();
 		return existing;
 	}
 	const created = createAnthropicProviderSessionState();
@@ -1943,12 +1952,33 @@ function rememberPrefixBindingFailure(
 	return true;
 }
 
+/** Identify a reported drop by the dropped block's replay key, falling back to its wire path. */
+function reportedDropKey(params: MessageCreateParamsStreaming, path: string | undefined): string | undefined {
+	if (path === undefined) return undefined;
+	const match = INPUT_TRANSFORMATION_PATH_PATTERN.exec(path);
+	if (match) {
+		const content = params.messages[Number(match[1])]?.content;
+		const block = Array.isArray(content) ? content[Number(match[2])] : undefined;
+		const key = block ? thinkingReplayKey(block) : undefined;
+		if (key) return key;
+	}
+	return `path:${path}`;
+}
+
+/**
+ * Record server-reported input rewrites on the response. A `drop_block`
+ * request keeps replaying the transcript verbatim afterwards: the API drops
+ * the same invalid blocks again on every later request (unbilled), while
+ * omitting them client-side would change the bytes the drop request just
+ * cached and can cost another message-prefix cache miss from the first
+ * dropped block on. Repeat reports of an already-warned drop log at debug.
+ */
 function applyReportedInputTransformations(
 	output: AssistantMessage,
-	params: MessageCreateParamsStreaming,
-	state: AnthropicProviderSessionState | undefined,
 	value: unknown,
 	seen: Set<string>,
+	params: MessageCreateParamsStreaming,
+	state: AnthropicProviderSessionState | undefined,
 	replace = false,
 ): void {
 	if (value === undefined || value === null) return;
@@ -1965,14 +1995,28 @@ function applyReportedInputTransformations(
 	}
 	if (fresh.length === 0) return;
 	output.inputTransformations = [...(output.inputTransformations ?? []), ...fresh];
-	rememberPrefixDroppedThinking(params, fresh, state);
+	let repeated = 0;
 	for (const transformation of fresh) {
 		if (transformation.reason !== "prefix_binding_mismatch") continue;
+		const dropKey = reportedDropKey(params, transformation.path);
+		if (state && dropKey !== undefined) {
+			if (state.reportedPrefixDroppedThinking.has(dropKey)) {
+				repeated++;
+				continue;
+			}
+			state.reportedPrefixDroppedThinking.add(dropKey);
+		}
 		logger.warn("anthropic: dropped thinking block after conversation prefix changed", {
 			model: output.model,
 			path: transformation.path,
 		});
 	}
+	if (repeated > 0) {
+		logger.debug("anthropic: API re-dropped previously reported thinking blocks", {
+			model: output.model,
+			count: repeated,
+		});
+	}
 }
 
 /**
@@ -2661,10 +2705,10 @@ const streamAnthropicOnce = (
 							if (startMessage?.id) output.responseId = startMessage.id;
 							applyReportedInputTransformations(
 								output,
-								params,
-								providerSessionState,
 								startMessage?.input_transformations,
 								seenInputTransformations,
+								params,
+								providerSessionState,
 							);
 							const startUsage = startMessage?.usage;
 							if (startUsage) {
@@ -2978,10 +3022,10 @@ const streamAnthropicOnce = (
 							const delta = event.delta;
 							applyReportedInputTransformations(
 								output,
-								params,
-								providerSessionState,
 								event.input_transformations,
 								seenInputTransformations,
+								params,
+								providerSessionState,
 								true,
 							);
 							const rawStopReason = delta?.stop_reason;

package/src/providers/cursor.ts

@@ -611,7 +611,7 @@ function classifyCursorStructuredError(structured: CursorStructuredError): Error
 	if (code === 21) return new AIError.AbortError(fullMessage);
 	const status = CURSOR_ERROR_STATUS[code];
 	if (status !== undefined) return new AIError.ProviderHttpError(fullMessage, status, { code: name });
-	if (retryable === true || CURSOR_RETRYABLE_ERROR_CODES.has(code)) {
+	if (retryable === true || (retryable === undefined && CURSOR_RETRYABLE_ERROR_CODES.has(code))) {
 		return new AIError.ProviderHttpError(fullMessage, 503, { code: name });
 	}
 	return new AIError.ProviderHttpError(fullMessage, 400, { code: name });
@@ -1089,6 +1089,9 @@ function streamCursorWithWireMode(
 		const h2Completion = Promise.withResolvers<void>();
 		let h2Settled = false;
 		let sawTurnEnded = false;
+		// After the final step's `stepCompleted`, only a repeat checkpoint and the
+		// `turnEnded` usage frame follow.
+		let stepCompletedIsLatest = false;
 		let endStreamError: Error | null = null;
 		let progressVersion = 0;
 		let latestCheckpointProgressVersion = -1;
@@ -1115,6 +1118,20 @@ function streamCursorWithWireMode(
 				return;
 			}
 			if (!sawTurnEnded) {
+				// A stream cut after the final step lost only usage and a repeat
+				// checkpoint, so the turn is complete. The final step ends on answer
+				// text; a step that ended on tool calls, or left one open, may be
+				// followed by another step and is still treated as truncated.
+				if (
+					stepCompletedIsLatest &&
+					output.content.at(-1)?.type === "text" &&
+					openBlockState?.currentToolCall === null &&
+					openBlockState.openToolCalls.size === 0
+				) {
+					logger.debug("cursor stream ended after stepCompleted without turnEnded", { model: model.id });
+					h2Completion.resolve();
+					return;
+				}
 				h2Completion.reject(
 					new AIError.ProviderResponseError("Cursor stream ended before turnEnded", {
 						kind: "incomplete-stream",
@@ -1349,6 +1366,15 @@ function streamCursorWithWireMode(
 							sawProgressOrSideEffect = true;
 							progressVersion++;
 						}
+						if (interactionCase === "stepCompleted") {
+							stepCompletedIsLatest = true;
+						} else if (
+							interactionCase !== "heartbeat" &&
+							serverMessage.message.case !== "conversationCheckpointUpdate" &&
+							serverMessage.message.case !== "kvServerMessage"
+						) {
+							stepCompletedIsLatest = false;
+						}
 						if (serverMessage.message.case === "conversationCheckpointUpdate") {
 							latestCheckpoint = serverMessage.message.value;
 							latestCheckpointProgressVersion = progressVersion;

package/src/registry/oauth/cursor.ts

@@ -6,7 +6,9 @@ import type { OAuthController, OAuthCredentials } from "./types";
 
 const CURSOR_LOGIN_URL = "https://cursor.com/loginDeepControl";
 const CURSOR_POLL_URL = "https://api2.cursor.sh/auth/poll";
-const CURSOR_REFRESH_URL = "https://api2.cursor.sh/auth/exchange_user_api_key";
+const CURSOR_REFRESH_URL = "https://api2.cursor.sh/oauth/token";
+/** OAuth client the Cursor IDE renews its login session with. */
+const CURSOR_CLIENT_ID = "KbZUR41cY7W6zRSdpSUJ7I7mLYBKOCmB";
 const CURSOR_PROFILE_URL = "https://cursor.com/api/auth/me";
 const CURSOR_PROFILE_TIMEOUT_MS = 3_000;
 
@@ -118,14 +120,11 @@ export async function loginCursorHook(callbacks: OAuthController): Promise<OAuth
 	return withCursorAccountEmail(credentials, callbacks.fetch ?? fetch, callbacks.signal);
 }
 
-export async function refreshCursorToken(apiKeyOrRefreshToken: string): Promise<OAuthCredentials> {
+export async function refreshCursorToken(refreshToken: string): Promise<OAuthCredentials> {
 	const response = await fetch(CURSOR_REFRESH_URL, {
 		method: "POST",
-		headers: {
-			Authorization: `Bearer ${apiKeyOrRefreshToken}`,
-			"Content-Type": "application/json",
-		},
-		body: "{}",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ grant_type: "refresh_token", client_id: CURSOR_CLIENT_ID, refresh_token: refreshToken }),
 	});
 
 	if (!response.ok) {
@@ -136,17 +135,27 @@ export async function refreshCursorToken(apiKeyOrRefreshToken: string): Promise<
 		});
 	}
 
-	const data = (await response.json()) as {
-		accessToken: string;
-		refreshToken: string;
-	};
-
-	const expiresAt = getTokenExpiry(data.accessToken);
+	const data = (await response.json()) as { access_token?: string; refresh_token?: string; shouldLogout?: boolean };
+	// Cursor answers a session it will not renew with 200, an empty token and `shouldLogout`.
+	if (data.shouldLogout === true) {
+		throw new AIError.OAuthError("invalid_grant: Cursor ended this session; run /login cursor again", {
+			kind: "token-refresh",
+			provider: "cursor",
+		});
+	}
+	if (!data.access_token) {
+		throw new AIError.OAuthError("Cursor token refresh returned no access token", {
+			kind: "token-refresh",
+			provider: "cursor",
+		});
+	}
 
+	// Cursor's renewal answers only an access token; the IDE keeps its stored refresh token, so do the same
+	// unless a rotated one is returned.
 	return {
-		access: data.accessToken,
-		refresh: data.refreshToken || apiKeyOrRefreshToken,
-		expires: expiresAt,
+		access: data.access_token,
+		refresh: data.refresh_token || refreshToken,
+		expires: getTokenExpiry(data.access_token),
 	};
 }
 

package/src/usage/github-copilot.ts

@@ -272,7 +272,7 @@ function normalizeBillingUsage(data: BillingUsageResponse): UsageLimit[] {
 		? `${data.timePeriod.year}-${String(data.timePeriod.month).padStart(2, "0")}`
 		: `${data.timePeriod.year}`;
 	const window: UsageWindow = {
-		id: "billing-period",
+		id: "monthly",
 		label: periodLabel,
 	};
 

package/src/utils/resolve-peer.ts

@@ -0,0 +1,7 @@
+/** Use the socket peer unless the server explicitly trusts its reverse proxy. */
+export function resolvePeer(req: Request, socketAddress: string, trustProxyHeaders = false): string {
+	if (!trustProxyHeaders) return socketAddress;
+	const fwd = req.headers.get("x-forwarded-for");
+	if (fwd) return fwd.split(",")[0].trim();
+	return req.headers.get("x-real-ip") ?? socketAddress;
+}