@oh-my-pi/pi-ai 17.3.3 → 17.3.5

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## [Unreleased]
 
+## [17.3.5] - 2026-08-16
+
+### Added
+
+- Added retryable oneshot completion support (`retryTransientCompletion`) so non-agent LLM calls correctly retry on transient provider failures (Anthropic overload/rate-limit errors, HTTP 429/500/502/503/529), honoring provider-supplied retry-after timing before giving up.
+
+### Fixed
+
+- Fixed xAI availability detection so paid-key-only setups correctly default to `xai/grok-4.5` instead of the free SuperGrok catalog; explicit `xai-oauth/…` selectors still work as before.
+- Fixed xAI Responses requests sending unsupported parameters (reasoning summary, presence/frequency penalties) that some models rejected.
+- Fixed Umans usage reporting incorrectly marking quota as exhausted based on raw request counts instead of actual weighted usage, and improved the usage display to show both a soft-cap warning and a hard exhaustion limit with an accurate countdown to reset.
+- Fixed `omp usage invalidate` to fully clear stale usage data and force a fresh refresh, so upgraded subscriptions no longer show outdated quota information.
+- Improved session recovery to correctly treat certain Cursor HTTP/2 connection errors as transient instead of ending the session.
+- Fixed OpenAI-compatible streams (e.g. DeepSeek) that are cut off mid-generation being silently treated as a completed response instead of being retried.
+- Fixed DeepSeek resource-exhaustion interruptions not being automatically retried.
+- Fixed tool-call IDs being lost during same-model replay, which could break correlation with custom gateways.
+- Fixed Kimi Code multi-account routing to prefer accounts with more available quota, respect usage-limit cooldowns, and keep consistent usage history across token refreshes.
+- Fixed Anthropic custom signing-proxy conversations losing tool-search results and thinking content during replay.
+- Fixed rare runaway response loops across model providers so they now fail gracefully instead of repeating indefinitely.
+- Fixed xAI rejecting entire turns due to certain MCP tool schema shapes, restoring compatibility while isolating any remaining incompatible tools rather than failing the whole request.
+- Fixed Alibaba DashScope/Bailian transient per-minute rate limits being misclassified as full quota exhaustion, causing unnecessary long backoffs instead of quick retries.
+- Fixed Anthropic-compatible streams dropping thinking content, which broke replay of prior reasoning.
+- Updated the Alibaba Coding Plan China login flow to point to the current Bailian API-key management console.
+
+## [17.3.4] - 2026-08-14
+
+### Fixed
+
+- Fixed `omp usage invalidate` to discard stale OAuth and API-key usage snapshots, then force a cache-bypassing, per-provider serialized refresh with a broker request budget sized for the full unfiltered account batch, so upgraded subscriptions do not silently retain pre-change quota data.
+- Fixed quota reporting and Cookie capture guidance for China (Beijing) Alibaba Token Plan credentials ([#8509](https://github.com/can1357/oh-my-pi/issues/8509)).
+
 ## [17.3.3] - 2026-08-14
 
 ### Fixed

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

@@ -66,7 +66,14 @@ export declare class AuthBrokerClient {
     openSnapshotStream(opts?: {
         signal?: AbortSignal;
     }): AsyncGenerator<SnapshotStreamEvent>;
-    fetchUsage(signal?: AbortSignal): Promise<UsageResponse>;
+    /**
+     * Fetch aggregate broker usage with a timeout sized for serialized
+     * same-provider account probes.
+     */
+    fetchUsage(options?: {
+        signal?: AbortSignal;
+        maxAccountsPerProvider?: number;
+    }): Promise<UsageResponse>;
     /** Recorded usage-limit snapshots from the broker host, oldest first. */
     fetchUsageHistory(query?: {
         sinceMs?: number;

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

@@ -804,10 +804,20 @@ export declare class AuthStorage {
      */
     has(provider: string): boolean;
     /**
-     * Check if any form of auth is configured for a provider.
-     * Unlike getApiKey(), this doesn't refresh OAuth tokens.
+     * Dedicated auth for default-model availability (picker / `getAvailable`).
+     * Unlike {@link getApiKey}, this does not refresh OAuth tokens, and unlike
+     * {@link hasResolvableAuth} it ignores cross-provider env aliases so
+     * `XAI_API_KEY` does not auto-select SuperGrok (`xai-oauth`).
      */
     hasAuth(provider: string): boolean;
+    /**
+     * Whether a request could resolve a key for this provider, including
+     * cross-provider env aliases (`xai-oauth` borrowing `XAI_API_KEY`).
+     * Use this for explicit model preflight (`xai-oauth/grok-4.5`); use
+     * {@link hasAuth} for auto-availability so the default picker stays on
+     * paid `xai` when only `XAI_API_KEY` is set.
+     */
+    hasResolvableAuth(provider: string): boolean;
     /**
      * True iff a dedicated, non-env credential source is configured for this
      * provider — i.e. anything in the cascade EXCEPT `getEnvApiKey(provider)`.
@@ -1111,10 +1121,9 @@ export declare class AuthStorage {
         signal?: AbortSignal;
     }): Promise<ResetCreditRedeemOutcome>;
     /**
-     * Force-invalidate cached usage reports so the next fetch retrieves fresh
-     * values from upstream providers. If `provider` is specified, only that
-     * provider's credentials are invalidated; otherwise, all credentials in the
-     * store are invalidated.
+     * Discard cached usage reports before a user-requested refresh. The next
+     * read probes upstream serially per provider; a failure reports no fresh
+     * usage instead of replaying an invalidated last-good snapshot.
      */
     invalidateUsageCache(provider?: string, signal?: AbortSignal): Promise<void>;
     invalidateCredentialMatching(provider: string, apiKey: string, options?: InvalidateCredentialMatchingOptions): Promise<boolean>;

package/dist/types/error/rate-limit.d.ts

@@ -3,11 +3,14 @@
  * Ported from opencode-antigravity-auth plugin for consistency.
  */
 export type RateLimitReason = "QUOTA_EXHAUSTED" | "INSUFFICIENT_G1_CREDITS_BALANCE" | "RATE_LIMIT_EXCEEDED" | "CONCURRENT_LIMIT" | "MODEL_CAPACITY_EXHAUSTED" | "SERVER_ERROR" | "UNKNOWN";
+/** True for DashScope/Bailian's documented OpenAI-compatible TPM/TPS throttle. */
+export declare function isDashScopeTokenLimitText(errorMessage: string): boolean;
 /**
  * Classify a rate-limit error message into a reason category.
  * Priority order: explicit details in a resource-exhausted error > QUOTA
- * (Antigravity "quota will reset") > CONCURRENT_LIMIT > MODEL_CAPACITY >
- * QUOTA (account) > RATE_LIMIT > QUOTA (generic) > SERVER_ERROR > bare resource-exhausted > UNKNOWN.
+ * (Antigravity "quota will reset") > CN quota > DASHSCOPE_TOKEN_LIMIT (TPM/TPS
+ * throttle) > CONCURRENT_LIMIT > MODEL_CAPACITY > QUOTA (account) > RATE_LIMIT >
+ * QUOTA (generic) > SERVER_ERROR > bare resource-exhausted > UNKNOWN.
  *
  * Bare "resource exhausted" / "resource_exhausted" maps to MODEL_CAPACITY (transient, short wait).
  * Explicit details such as "quota exceeded" retain their normal classification.

package/dist/types/index.d.ts

@@ -6,6 +6,7 @@ export * from "./auth-gateway/types.js";
 export * from "./auth-retry.js";
 export * from "./auth-storage.js";
 export * from "./error/rate-limit.js";
+export * from "./oneshot-retry.js";
 export * from "./provider-details.js";
 export * from "./providers/anthropic.js";
 export * from "./providers/anthropic-client.js";

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

@@ -0,0 +1,89 @@
+import type { AssistantMessage } from "./types.js";
+import { type HeadersLike } from "./utils/retry-after.js";
+/**
+ * Transient-failure retry for **oneshot** (non-agent-loop) completions.
+ *
+ * Why this exists: `streamSimple`/`completeSimple` retry *auth* failures
+ * (credential rotation) but deliberately surface *transient* provider failures
+ * — Anthropic `overloaded_error`, `rate_limit_error`, HTTP 429/500/502/503/529
+ * — as a **resolved** `AssistantMessage` with `stopReason: "error"`. For the
+ * main agent turn that is correct: `TurnRecovery` owns recovery there, and it
+ * must refuse to replay once tool calls or visible text have streamed.
+ *
+ * Oneshots have no such hazard. A summary, title, handoff, or image
+ * description produces no side effects, so re-issuing the whole request is
+ * safe and is almost always what the caller wants. Before this helper every
+ * oneshot call site had to re-implement that decision, and most did not —
+ * failing on the first blip, or swallowing it into `null` so a transient
+ * overload was indistinguishable from a legitimate empty result.
+ *
+ * Classification reuses the existing provider predicates (`AIError`), so the
+ * set of retryable Anthropic failures stays defined in exactly one place.
+ * Usage limits are included: unlike the provider loop — which excludes them so
+ * credential rotation can own them — a oneshot has no rotation layer above it,
+ * and the retry hint the provider supplies (`retry-after`, "try again in ~5m")
+ * is honored, so waiting is the correct response.
+ */
+export interface OneshotRetryOptions {
+    /** Total attempts, including the first. Default 3. Values < 1 are treated as 1. */
+    maxAttempts?: number;
+    /** First backoff step in ms; doubles per attempt. Default 500. */
+    baseDelayMs?: number;
+    /**
+     * Upper bound for a single wait. Default 30_000. A provider retry hint
+     * longer than this aborts the retry instead of parking the caller — the
+     * error surfaces so higher-level recovery (or the user) can decide.
+     */
+    maxDelayMs?: number;
+    /**
+     * Stops further attempts. Two distinct paths, both preserving the caller's
+     * intent: an abort already visible when an attempt settles surfaces that
+     * attempt's own result (`completeSimple` reports `stopReason: "aborted"`),
+     * while an abort that lands during the backoff wait rejects with the abort
+     * reason — a user cancel stays a cancel and is never relabelled as the
+     * provider failure we happened to be waiting on.
+     *
+     * This helper does NOT pass the signal into `run` — cancelling the in-flight
+     * request is the closure's job, because a per-attempt deadline must be
+     * rebuilt on every attempt. Construct it inside `run`
+     * (`signal: AbortSignal.timeout(MS)`, or `AbortSignal.any([outer, perAttempt])`);
+     * a deadline captured outside would fire once and then abort every retry,
+     * silently turning this helper into a single attempt.
+     */
+    signal?: AbortSignal;
+    /**
+     * Headers of the attempt that just failed, used to honor `retry-after`.
+     *
+     * Load-bearing: a transient Anthropic failure arrives as a **resolved**
+     * `AssistantMessage`, and `AssistantMessage` carries no headers — so without
+     * this the real `retry-after` / `x-ratelimit-reset` values on a 429/529 are
+     * invisible and only the (usually hint-free) error text is available.
+     * Callers that already capture headers via `SimpleStreamOptions.onResponse`
+     * should return the latest capture here; it is read once per failed attempt.
+     * Thrown errors need no wiring — headers are recovered from the error itself.
+     */
+    getResponseHeaders?: () => HeadersLike;
+    /** Observability hook. Fires immediately before sleeping. */
+    onRetry?: (info: OneshotRetryInfo) => void;
+}
+export interface OneshotRetryInfo {
+    /** 1-based index of the attempt that just failed. */
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    /** True when `delayMs` came from a provider retry hint rather than backoff. */
+    fromRetryHint: boolean;
+    errorMessage: string;
+    /** `AIError` classification bits of the failure. */
+    errorId: number;
+}
+/**
+ * Run a oneshot completion, retrying transient provider failures.
+ *
+ * Handles both failure shapes: a resolved `AssistantMessage` carrying
+ * `stopReason: "error"` (what `completeSimple` produces) and a thrown error
+ * (what the raw HTTP helpers produce). A non-retryable failure is returned or
+ * rethrown unchanged, so existing caller error handling keeps working — this
+ * only removes the *first-blip* failure mode.
+ */
+export declare function retryTransientCompletion(run: (attempt: number) => Promise<AssistantMessage>, options?: OneshotRetryOptions): Promise<AssistantMessage>;

package/dist/types/providers/anthropic-wire.d.ts

@@ -69,6 +69,10 @@ export type ServerToolUseBlockParam = {
 export type WebSearchServerToolUseBlockParam = ServerToolUseBlockParam & {
     name: "web_search";
 };
+/** Tool-search server-tool call whose matching result is replayable by omp. */
+export type ToolSearchServerToolUseBlockParam = ServerToolUseBlockParam & {
+    name: "tool_search_tool_regex" | "tool_search_tool_bm25";
+};
 /** Native web-search result replayed inside an assistant turn. */
 export type WebSearchToolResultBlockParam = {
     type: "web_search_tool_result";
@@ -76,14 +80,23 @@ export type WebSearchToolResultBlockParam = {
     content: unknown;
     [key: string]: unknown;
 };
-/** True for the complete native web-search history variants omp can replay. */
-export declare function isAnthropicWebSearchHistoryBlock(block: {
+/** Native tool-search result replayed inside an assistant turn. */
+export type ToolSearchToolResultBlockParam = {
+    type: "tool_search_tool_result";
+    tool_use_id: string;
+    content: unknown;
+    [key: string]: unknown;
+};
+/** Anthropic server-tool history variants omp can replay atomically. */
+export type AnthropicServerToolHistoryBlockParam = WebSearchServerToolUseBlockParam | WebSearchToolResultBlockParam | ToolSearchServerToolUseBlockParam | ToolSearchToolResultBlockParam;
+/** True when a block is complete Anthropic server-tool history omp can replay. */
+export declare function isAnthropicServerToolHistoryBlock(block: {
     type: string;
     name?: unknown;
     id?: unknown;
     tool_use_id?: unknown;
     content?: unknown;
-}): block is WebSearchServerToolUseBlockParam | WebSearchToolResultBlockParam;
+}): block is AnthropicServerToolHistoryBlockParam;
 export type ThinkingBlockParam = {
     type: "thinking";
     thinking: string;
@@ -108,7 +121,7 @@ export type FallbackBlockParam = {
         model: string;
     };
 };
-export type ContentBlockParam = TextBlockParam | ImageBlockParam | ToolUseBlockParam | ToolResultBlockParam | ServerToolUseBlockParam | WebSearchToolResultBlockParam | ThinkingBlockParam | RedactedThinkingBlockParam | FallbackBlockParam;
+export type ContentBlockParam = TextBlockParam | ImageBlockParam | ToolUseBlockParam | ToolResultBlockParam | ServerToolUseBlockParam | WebSearchToolResultBlockParam | ToolSearchToolResultBlockParam | ThinkingBlockParam | RedactedThinkingBlockParam | FallbackBlockParam;
 /**
  * A single conversation turn.
  *
@@ -284,7 +297,7 @@ export type ResponseContentBlock = {
     id: string;
     name: string;
     input?: Record<string, unknown> | null;
-} | ServerToolUseBlockParam | WebSearchToolResultBlockParam | {
+} | ServerToolUseBlockParam | WebSearchToolResultBlockParam | ToolSearchToolResultBlockParam | {
     type: "fallback";
     from: {
         model: string;

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

@@ -582,7 +582,7 @@ type CommonSamplingOptions = Pick<StreamOptions, "temperature" | "topP" | "topK"
  * reflect the model's context window rather than the upstream output limit.
  */
 export declare function applyCommonResponsesSamplingParams<P extends CommonResponsesParams>(params: P, options: CommonSamplingOptions | undefined, model: Pick<Model, "provider" | "api" | "id" | "omitMaxOutputTokens" | "maxTokens"> & {
-    compat: Pick<ResolvedOpenAISharedCompat, "supportsSamplingParams">;
+    compat: Pick<ResolvedOpenAISharedCompat, "supportsSamplingParams" | "supportsPenaltyAndStopParams">;
 }): void;
 type ReasoningOptions = {
     reasoning?: string;

package/dist/types/types.d.ts

@@ -521,19 +521,20 @@ export interface AnthropicFallbackContent {
     };
 }
 /**
- * Verbatim Anthropic web-search call/result retained for same-provider
- * history replay. Other providers discard it in `transformMessages`.
+ * Verbatim Anthropic web-search or tool-search call/result retained for
+ * same-provider history replay. Other providers discard it in
+ * `transformMessages`.
  */
 export interface AnthropicServerToolContent {
     type: "anthropicServerTool";
     block: {
         type: "server_tool_use";
         id: string;
-        name: "web_search";
+        name: "web_search" | "tool_search_tool_regex" | "tool_search_tool_bm25";
         input?: Record<string, unknown> | null;
         [key: string]: unknown;
     } | {
-        type: "web_search_tool_result";
+        type: "web_search_tool_result" | "tool_search_tool_result";
         tool_use_id: string;
         content: unknown;
         [key: string]: unknown;

package/dist/types/usage/kimi.d.ts

@@ -1,2 +1,4 @@
-import type { UsageProvider } from "../usage.js";
+import type { CredentialRankingStrategy, UsageProvider } from "../usage.js";
 export declare const kimiUsageProvider: UsageProvider;
+/** Ranks Kimi OAuth accounts by the canonical 5-hour and 7-day quota windows. */
+export declare const kimiRankingStrategy: CredentialRankingStrategy;

package/dist/types/utils/schema/strict-tool-validation.d.ts

@@ -7,10 +7,19 @@
  * copied onto a `type: "null"` branch, or an `enum` placed on an `array`
  * schema instead of its `items`). One such tool 400s the entire turn, so
  * callers quarantine just the offending tool. See issue #2652.
+ *
+ * xAI additionally rejects a leftover *root* `anyOf`/`oneOf` whose branches
+ * are not objects ("tool parameter root must be an object type"). That class
+ * is opt-in via {@link FindStrictToolSchemaViolationOptions.rejectXaiRootObjectUnion}
+ * so OpenAI/Azure/Codex keep valid object-root unions.
  */
+export interface FindStrictToolSchemaViolationOptions {
+    /** xAI (paid + OAuth) only: leftover object-root unions 400 the whole turn. */
+    rejectXaiRootObjectUnion?: boolean;
+}
 /**
  * Walk a tool parameter schema for OpenAI-strict `enum`/`const`-vs-`type`
  * contradictions. Returns a JSON-pointer-ish path to the first offending node,
  * or `null` when the schema is safe to emit.
  */
-export declare function findStrictToolSchemaViolation(schema: unknown, path?: string): string | null;
+export declare function findStrictToolSchemaViolation(schema: unknown, path?: string, options?: FindStrictToolSchemaViolationOptions): string | null;

package/dist/types/utils/schema/wire.d.ts

@@ -14,6 +14,12 @@ import type { Tool } from "../../types.js";
  * methods, while raw JSON Schema is a plain object.
  */
 export declare function isArkSchema(value: unknown): value is Type;
+/**
+ * Return an xAI-compatible copy of an object-root schema whose union consists
+ * only of typeless required-key fragments. Other providers must retain the
+ * union because it is a real model-facing constraint.
+ */
+export declare function flattenExclusiveRequiredRootUnion(schema: Record<string, unknown>): Record<string, unknown>;
 /**
  * Normalize `{}` (an unconstrained schema) to boolean `true` in every
  * schema-valued position. JSON Schema draft 2020-12 §4.3.1 defines them as

package/dist/types/utils/thinking-loop.d.ts

@@ -5,11 +5,12 @@ import { AssistantMessageEventStream } from "./event-stream.js";
  *  classifiers treat it as a transient (retryable) stop without bespoke rules. */
 export declare const THINKING_LOOP_ERROR_MARKER = "Thinking loop detected";
 /**
- * True when `model.id` belongs to a family guarded for thinking/response loops:
- * Gemini, DeepSeek, or Grok.
+ * True when `model.id` belongs to a family guarded by the semantic loop
+ * heuristics: Gemini, DeepSeek, or Grok. Exact suffix-cycle detection applies to
+ * every enabled model independently of this predicate.
  *
  * Model identity is derived only from its id; provider and compatibility metadata
- * do not opt opaque aliases into the guard.
+ * do not opt opaque aliases into semantic detection.
  */
 export declare function isLoopGuardedModel(model: Model<Api>, options?: StreamOptions): boolean;
 /**
@@ -19,6 +20,8 @@ export declare function isLoopGuardedModel(model: Model<Api>, options?: StreamOp
  */
 export declare class ThinkingLoopDetector {
     #private;
+    private readonly semanticHeuristics;
+    constructor(semanticHeuristics?: boolean);
     push(delta: string): string | null;
     /** Process the buffered trailing paragraph (one with no blank-line / heading
      *  terminator). Called when the thinking block ends so the final segment —
@@ -75,12 +78,12 @@ export declare class GeminiHeaderRunDetector {
  */
 export declare function guardThinkingLoopStream(inner: AssistantMessageEventStream, model: Model<Api>, controller: AbortController, options?: StreamOptions): AssistantMessageEventStream;
 /**
- * Apply the loop guard around a provider dispatch. For non-guarded models
- * (or when disabled) this is a transparent pass-through. For guarded models it injects a
- * guard abort signal into the provider call so a detected loop tears down the
- * upstream, then wraps the returned stream. The guard only raises the retryable
- * stall; bounding the re-samples and the final cook pass lives in the
- * result-awaiting caller.
+ * Apply the loop guard around a provider dispatch. Unless explicitly disabled,
+ * every model gets exact suffix-cycle detection; Gemini, DeepSeek, and Grok also
+ * get the semantic heuristics selected by {@link isLoopGuardedModel}. The guard
+ * injects an abort signal into the provider call so a detected loop tears down
+ * the upstream, then wraps the returned stream. Bounding result-path re-samples
+ * lives in the result-awaiting caller.
  */
 export declare function withThinkingLoopGuard<O extends {
     signal?: AbortSignal;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.3.3",
+	"version": "17.3.5",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,10 +38,10 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/omptype": "17.3.3",
-		"@oh-my-pi/pi-catalog": "17.3.3",
-		"@oh-my-pi/pi-utils": "17.3.3",
-		"@oh-my-pi/pi-wire": "17.3.3"
+		"@oh-my-pi/omptype": "17.3.5",
+		"@oh-my-pi/pi-catalog": "17.3.5",
+		"@oh-my-pi/pi-utils": "17.3.5",
+		"@oh-my-pi/pi-wire": "17.3.5"
 	},
 	"devDependencies": {
 		"@bufbuild/protoc-gen-es": "^2.12.1",

package/src/auth-broker/client.ts

@@ -249,12 +249,23 @@ export class AuthBrokerClient {
 		}
 	}
 
-	fetchUsage(signal?: AbortSignal): Promise<UsageResponse> {
-		// Validates the envelope (`generatedAt`, `reports[].provider`, `limits`,
-		// `metadata`) but leaves provider-specific extension fields permissive so
-		// the broker can ship new shapes ahead of the client. `raw` is accepted
-		// but normally stripped by the broker before send.
-		return this.#request<UsageResponse>("GET", "/v1/usage", { schema: "usageResponseSchema", signal });
+	/**
+	 * Fetch aggregate broker usage with a timeout sized for serialized
+	 * same-provider account probes.
+	 */
+	fetchUsage(options: { signal?: AbortSignal; maxAccountsPerProvider?: number } = {}): Promise<UsageResponse> {
+		const requestedAccountCount = options.maxAccountsPerProvider;
+		const accountCount =
+			typeof requestedAccountCount === "number" && Number.isFinite(requestedAccountCount)
+				? Math.max(1, Math.floor(requestedAccountCount))
+				: 1;
+		const perAccountTimeoutMs = Math.max(DEFAULT_TIMEOUT_MS, this.#timeoutMs);
+		const timeoutMs = perAccountTimeoutMs * (accountCount + 1);
+		return this.#request<UsageResponse>("GET", "/v1/usage", {
+			schema: "usageResponseSchema",
+			signal: options.signal,
+			timeoutMs,
+		});
 	}
 
 	/** Recorded usage-limit snapshots from the broker host, oldest first. */
@@ -369,7 +380,13 @@ export class AuthBrokerClient {
 	async #request<t>(
 		method: "GET" | "POST" | "DELETE",
 		path: string,
-		opts: { schema: AuthBrokerResponseSchemaName; auth?: boolean; body?: unknown; signal?: AbortSignal },
+		opts: {
+			schema: AuthBrokerResponseSchemaName;
+			auth?: boolean;
+			body?: unknown;
+			signal?: AbortSignal;
+			timeoutMs?: number;
+		},
 	): Promise<t> {
 		const response = await this.#fetchRaw(method, path, opts);
 		const text = await response.text();

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

@@ -253,6 +253,9 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	#usageInflight?: Promise<UsageReport[] | null>;
 	#credentialBlockReconcileAfter: Map<string, number> = new Map();
 	#usageCacheEpoch = 0;
+	/** Raw broker credentials retained to size aggregate usage requests before account-pool filtering. */
+	#brokerUsageProviderByCredentialId = new Map<number, Provider>();
+	#brokerUsageAccountCounts = new Map<Provider, number>();
 	/** Per-snapshot lookup of oauth credentials by provider; rebuilt when `#snapshot` is replaced. */
 	#usageFilterLookup?: { snapshot: SnapshotResponse; byProvider: Map<Provider, OAuthCredential[]> };
 	/** Memoized `#filterUsageReports` output, keyed on (input identity, lookup identity). */
@@ -296,6 +299,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	#applySnapshot(snapshot: SnapshotResponse, generation: number, protectNewBlocks = true): void {
 		const nowMs = Date.now();
+		this.#replaceBrokerUsageAccounts(snapshot.credentials);
 		const previousCredentials = this.#snapshot.credentials;
 		const credentials = snapshot.credentials
 			.filter(entry => isCredentialInAccountPool(entry, this.#accountPool))
@@ -427,8 +431,9 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		generation: number,
 		serverNowMs: number,
 	): void {
+		this.#upsertBrokerUsageAccount(entry);
 		if (!isCredentialInAccountPool(entry, this.#accountPool)) {
-			this.#removeStreamCredential(entry.id, refresher, generation, serverNowMs);
+			this.#removeStreamCredential(entry.id, refresher, generation, serverNowMs, { retainBrokerUsageAccount: true });
 			return;
 		}
 		const incoming = this.#normalizeSnapshotEntryBlocks(entry, Date.now());
@@ -446,7 +451,14 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		this.#snapshotReceivedAt = Date.now();
 	}
 
-	#removeStreamCredential(id: number, refresher: RefresherSchedule, generation: number, serverNowMs: number): void {
+	#removeStreamCredential(
+		id: number,
+		refresher: RefresherSchedule,
+		generation: number,
+		serverNowMs: number,
+		options?: { retainBrokerUsageAccount?: boolean },
+	): void {
+		if (!options?.retainBrokerUsageAccount) this.#removeBrokerUsageAccount(id);
 		const removed = this.#snapshot.credentials.find(entry => entry.id === id);
 		if (removed?.blocks && removed.blocks.length > 0) this.#invalidateUsageCache();
 		const credentials = this.#snapshot.credentials.filter(entry => entry.id !== id);
@@ -1066,6 +1078,39 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		});
 	}
 
+	#replaceBrokerUsageAccounts(entries: readonly SnapshotEntry[]): void {
+		this.#brokerUsageProviderByCredentialId.clear();
+		this.#brokerUsageAccountCounts.clear();
+		for (const entry of entries) this.#upsertBrokerUsageAccount(entry);
+	}
+
+	#upsertBrokerUsageAccount(entry: Pick<SnapshotEntry, "id" | "provider">): void {
+		const previous = this.#brokerUsageProviderByCredentialId.get(entry.id);
+		if (previous === entry.provider) return;
+		if (previous !== undefined) {
+			const count = this.#brokerUsageAccountCounts.get(previous) ?? 0;
+			if (count <= 1) this.#brokerUsageAccountCounts.delete(previous);
+			else this.#brokerUsageAccountCounts.set(previous, count - 1);
+		}
+		this.#brokerUsageProviderByCredentialId.set(entry.id, entry.provider);
+		this.#brokerUsageAccountCounts.set(entry.provider, (this.#brokerUsageAccountCounts.get(entry.provider) ?? 0) + 1);
+	}
+
+	#removeBrokerUsageAccount(id: number): void {
+		const provider = this.#brokerUsageProviderByCredentialId.get(id);
+		if (provider === undefined) return;
+		this.#brokerUsageProviderByCredentialId.delete(id);
+		const count = this.#brokerUsageAccountCounts.get(provider) ?? 0;
+		if (count <= 1) this.#brokerUsageAccountCounts.delete(provider);
+		else this.#brokerUsageAccountCounts.set(provider, count - 1);
+	}
+
+	#maxBrokerUsageAccounts(): number {
+		let maximum = 1;
+		for (const count of this.#brokerUsageAccountCounts.values()) maximum = Math.max(maximum, count);
+		return maximum;
+	}
+
 	#loadUsageReports(): Promise<UsageReport[] | null> {
 		const cached = this.#usageCache;
 		if (cached && Date.now() - cached.fetchedAt < USAGE_CACHE_TTL_MS) {
@@ -1074,7 +1119,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		if (this.#usageInflight) return this.#usageInflight;
 		const epoch = this.#usageCacheEpoch;
 		const inflight = this.#client
-			.fetchUsage()
+			.fetchUsage({ maxAccountsPerProvider: this.#maxBrokerUsageAccounts() })
 			.then(body => {
 				if (epoch !== this.#usageCacheEpoch) return this.#loadUsageReports();
 				this.#usageCache = { reports: body.reports, fetchedAt: Date.now() };

package/src/auth-broker/server.ts

@@ -741,7 +741,7 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 				}
 				if (req.method === "POST" && pathname === "/v1/usage/stale") {
 					try {
-						opts.storage.invalidateUsageCache?.();
+						await opts.storage.invalidateUsageCache?.();
 						logger.info("auth-broker usage cache invalidated", { peer });
 						return json(200, { ok: true });
 					} catch (error) {