@oh-my-pi/pi-ai 18.12.3 → 18.12.4

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [Unreleased]
 
+## [18.12.4] - 2026-10-20
+
+### Added
+
+- Added opt-in `reclaimAbovePct` to `auth.accountPolicies`: sessions automatically moved to a lower-priority account return to the preferred one once it has that much quota left ([#14237](https://github.com/can1357/oh-my-pi/pull/14237) by [@will-bogusz](https://github.com/will-bogusz))
+- Added `reachesBudgetedHost()`: whether the catalog's host request budgets (inline image bytes, official image count) apply to a request, true on a model's official endpoint and on Factory Droid's own hosts ([#16288](https://github.com/can1357/oh-my-pi/pull/16288) by [@will-bogusz](https://github.com/will-bogusz))
+- Added Inception API-key login (`/login inception`) and `INCEPTION_API_KEY` environment authentication ([#16439](https://github.com/can1357/oh-my-pi/pull/16439) by [@eggpeat](https://github.com/eggpeat))
+- Added image support for native OpenAI Decisions and Workers AI judgments, prompted vision chat, and auth-gateway System One requests; images exceeding a judgment API's documented caps (e.g. Clef's 4 images, 4 MiB each) are rejected locally ([#15471](https://github.com/can1357/oh-my-pi/pull/15471) by [@anatoli-tsinovoy](https://github.com/anatoli-tsinovoy)).
+- `isSurvivingAssistant` in `providers/transform-messages`: whether an assistant turn reaches a replay, malformed tool calls dropped first, so callers outside `transformMessages` pick the same latest turn ([#15791](https://github.com/can1357/oh-my-pi/pull/15791) by [@will-bogusz](https://github.com/will-bogusz))
+- Broker account-pool files (`OMP_AUTH_BROKER_ACCOUNT_POOL_FILE`) can hide whole providers and API keys: `"*": false` makes the file an allow-list, and an entry can be `true`, `false`, or `{ "accounts": [...], "apiKeys": false }` ([#14235](https://github.com/can1357/oh-my-pi/pull/14235) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Changed
+
+- `cursorRawReadPath()` writes a bare start line as `raw:N-` (`file:10` → `file:raw:10-`), so Cursor exec reads of such a path still read from line `N` onward now that `read` takes `N:raw` as one line ([#16438](https://github.com/can1357/oh-my-pi/pull/16438) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Fixed
+
+- Fixed Anthropic and Bedrock logging one warning per dropped thinking block (hundreds for one request) after a conversation change; the drop now logs one warning with the count ([#16392](https://github.com/can1357/oh-my-pi/pull/16392) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed Factory Droid Core models (Kimi, GLM, DeepSeek and others) dropping calls to tools with names over 64 characters and their results from later requests; such names now shorten to 64 characters, and shorter names are sent unchanged ([#16384](https://github.com/can1357/oh-my-pi/pull/16384) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed Devin `/usage` showing no data for accounts signed in with `/login devin`, and Devin chat sending a failing extra auth request for legacy Windsurf Enterprise keys ([#13677](https://github.com/can1357/oh-my-pi/pull/13677) by [@will-bogusz](https://github.com/will-bogusz))
+- Turns stopped for a thinking loop now keep the tokens and cost the provider had reported, the response id, the request's start time, and its time to first token and duration, instead of recording zero usage and no timing ([#16437](https://github.com/can1357/oh-my-pi/pull/16437) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed Claude requests answering a turn whose attachment is a video, PDF, HEIC or other format sent outside a JPEG/PNG/GIF/WebP image as if nothing were attached; the turn now fails with an error naming the format ([#16407](https://github.com/can1357/oh-my-pi/pull/16407) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed the repeated-tool-call guard missing a loop the model interleaves with a `wait` that elapses with nothing new; a wait that returns finished work still ends the repetition ([#11874](https://github.com/can1357/oh-my-pi/pull/11874) by [@dickyudhandika](https://github.com/dickyudhandika))
+- Fixed Google Antigravity chat and image requests failing with false 429 quota-exhausted errors ([#11849](https://github.com/can1357/oh-my-pi/pull/11849) by [@jotafurtado](https://github.com/jotafurtado))
+- Fixed the stream loop guard never stopping a model stuck repeating punctuation or symbols (`?!?!`, `✓✓✓`) until the output limit; such runs now trip once they repeat for 1 KB, while digit and whitespace runs such as padding and hexdumps are left alone ([#14436](https://github.com/can1357/oh-my-pi/pull/14436) by [@F0Rextasy](https://github.com/F0Rextasy))
+- Fixed native remote compaction for supported Bedrock Claude models without changing ordinary Converse turns; a custom non-AWS `baseUrl` needs `remoteCompaction.enabled: true` ([#16343](https://github.com/can1357/oh-my-pi/pull/16343) by [@anatoli-tsinovoy](https://github.com/anatoli-tsinovoy))
+- Fixed Anthropic compaction blocks dropping their signed `tool_changes`, which made the replayed block fail its signature ([#16343](https://github.com/can1357/oh-my-pi/pull/16343) by [@anatoli-tsinovoy](https://github.com/anatoli-tsinovoy))
+
 ## [18.12.3] - 2026-10-19
 
 ### Added
@@ -2292,59 +2320,4 @@
 - Fixed OpenRouter Anthropic Responses follow-up requests replaying prior reasoning items with stale signatures, which caused HTTP 400 `Invalid signature in thinking block` errors after a thinking turn. ([#3399](https://github.com/can1357/oh-my-pi/issues/3399))
 - Fixed OpenRouter Anthropic models on the Responses path omitting `cache_control`, so prompt caching engages without forcing Chat Completions. `cacheRetention: "long"` now upgrades the breakpoint to `ttl: "1h"`. ([#3397](https://github.com/can1357/oh-my-pi/issues/3397))
 
-## [16.1.16] - 2026-06-23
-
-### Fixed
-
-- Fixed Anthropic-compatible thinking requests sending replayed thinking blocks without `context_management.keep: "all"`, preserving multi-turn reasoning context for API-key providers. API-key requests now also advertise the required `context-management-2025-06-27` beta header so the field is honored instead of rejected. Injected SDK clients, GitHub Copilot's Anthropic proxy, and Vertex rawPredict are excluded because this code path cannot add the beta to caller-owned clients, Copilot strips Anthropic betas and demotes thinking blocks to text upstream, and Vertex expects betas in the JSON body rather than the Anthropic HTTP beta header. ([#3288](https://github.com/can1357/oh-my-pi/issues/3288))
-- Fixed OpenRouter Responses native history replay leaking Gemini reasoning item `format` metadata back into follow-up requests, which caused HTTP 400 rejections while preserving encrypted reasoning replay.
-
-## [16.1.15] - 2026-06-22
-
-### Fixed
-
-- Fixed API-key `/login` providers replacing sibling credentials instead of appending new keys for the same provider. ([#3265](https://github.com/can1357/oh-my-pi/issues/3265))
-- Fixed OpenAI Codex OAuth account rotation for quota failures that surface as bare HTTP 429 or `insufficient_quota`, so pre-content failures temporarily block only the exhausted credential and retry a healthy sibling. The 429 status-only fallback applies only to absent/opaque bodies; informative transient bodies (`Too many requests`, `Service overloaded 529`, `Please retry in 5s`, …) defer to `parseRateLimitReason` and stay in the provider's own backoff layer instead of burning sibling credentials. ([#3231](https://github.com/can1357/oh-my-pi/issues/3231))
-
-## [16.1.14] - 2026-06-22
-
-### Added
-
-- Added proxy support for model providers via `PI_PROXY` and `PI_PROXY_<PROVIDER>` variables
-- Added `NO_PROXY` environment variable support for bypassing proxy configuration
-- Added support for Sakana AI provider
-- Added Sakana AI login and request base URL support for `SAKANA_*` / `FUGU_*` environment variables
-
-### Changed
-
-- Consolidated API key authentication logic across registry providers
-- Disabled parallel tool calls for Devin provider requests
-
-### Fixed
-
-- Improved proxy bypass logic to correctly handle private IP ranges and local metadata services
-- Enhanced memoization for proxy environment variable lookups to improve performance
-
-## [16.1.13] - 2026-06-22
-
-### Added
-
-- Added support for Devin as a provider
-
-### Changed
-
-- Updated tool call arguments to use `Record<string, unknown>` and `unknown` for tool results
-
-### Fixed
-
-- Fixed OpenAI Responses native history replay dropping failed/incomplete image generation calls instead of resending their transient `ig_...` item IDs, preventing follow-up requests from failing with `404 Item with id ... not found`. ([#3225](https://github.com/can1357/oh-my-pi/issues/3225))
-- Fixed `/login fireworks` rejecting valid `fw_…` keys with `Fireworks API key validation failed (500): Error listing deployed models`. The validator pinged `/inference/v1/models`, which Fireworks serves from the per-account deployment registry and 500s for accounts without active deployments. Login now hits the static control-plane `List Models` catalog (`GET /v1/accounts/fireworks/models?filter=supports_serverless=true&pageSize=1`) — the same endpoint discovery already uses — so authentication no longer depends on the caller's deployment state. ([#3219](https://github.com/can1357/oh-my-pi/issues/3219))
-
-## [16.1.11] - 2026-06-21
-
-### Fixed
-
-- Fixed OpenAI Responses native history replay leaking image generation provider-only fields into the next request, which made OpenAI-compatible proxies reject `pi` tool-calling sessions with `Unknown parameter: input[1].action`. ([#3201](https://github.com/can1357/oh-my-pi/issues/3201))
-- Fixed a stream thought-leakage issue for `gemini-3.5-flash` where the model's internal reasoning JSON could leak into the visible text stream. The stream parser now uses a brace-balanced counting algorithm to accurately slice and discard the leading thought JSON block, with a robust fallback for unescaped double quotes, dynamic tool-name derivation, and preservation of subsequent text deltas without triggering empty-response retries.
-
-Older entries are archived in [packages/ai/CHANGELOG.md@5eb78e90fa4e](https://github.com/can1357/oh-my-pi/blob/5eb78e90fa4ec4318b9520302f1977fa58c48745/packages/ai/CHANGELOG.md).
+Older entries are archived in [packages/ai/CHANGELOG.md@47e6af055a17](https://github.com/can1357/oh-my-pi/blob/47e6af055a17862bc1cab6b5ebedd3db75ac2573/packages/ai/CHANGELOG.md).

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

@@ -23,6 +23,10 @@ export type UsageCandidate<T extends AuthCredential> = {
      * spent, so if it still serves it draws on paid overage such as Codex credits.
      */
     allowanceSpent?: boolean;
+    /** Present after policy-aware ranking: the account's configured `priority` (0 when unset). */
+    accountPriority?: number;
+    /** Present after policy-aware ranking: unblocked and measured at or above its `reclaimAbovePct`. */
+    reclaimReady?: boolean;
 };
 /** OAuth credential eligible for usage ranking. */
 export type OAuthCandidate = UsageCandidate<OAuthCredential>;

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

@@ -36,6 +36,8 @@ export interface AuthAccountPolicy {
     readonly priority?: number;
     /** Protected remaining quota percentage for this account. */
     readonly reservePct?: number;
+    /** Remaining quota percentage, above the reserve, at which this account takes back lower-priority warm pins. */
+    readonly reclaimAbovePct?: number;
 }
 /** Read-only set of per-account routing policies. */
 export type AuthAccountPolicies = readonly AuthAccountPolicy[];

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

@@ -5,12 +5,21 @@ import type { Provider } from "../types.js";
 import type { ClientUsageIdentity, ObservedUsageEntry, UsageReport } from "../usage.js";
 import { type AuthBrokerClient } from "./client.js";
 import type { SnapshotResponse } from "./types.js";
+/** Visibility rule for one provider's broker credentials. */
+export interface AuthBrokerProviderPool {
+    /** OAuth `identityKey`s visible to this client; omitted = every OAuth account. */
+    readonly accounts?: ReadonlySet<string>;
+    /** Whether API-key credentials are visible. Default `true`. */
+    readonly apiKeys?: boolean;
+}
 /**
- * Per-provider OAuth identities visible to this trusted broker client.
- * Missing providers are unrestricted; an empty set excludes that provider's
- * OAuth credentials. API keys are never filtered.
+ * Per-provider credential visibility for this trusted broker client. A set
+ * value lists the provider's visible OAuth identities and keeps its API keys
+ * (an empty set excludes every OAuth credential); a rule object can also hide
+ * API keys. Providers without an entry follow the `"*"` rule, which defaults
+ * to unrestricted.
  */
-export type AuthBrokerAccountPool = ReadonlyMap<string, ReadonlySet<string>>;
+export type AuthBrokerAccountPool = ReadonlyMap<string, ReadonlySet<string> | AuthBrokerProviderPool>;
 export interface RemoteAuthCredentialStoreOptions {
     client: AuthBrokerClient;
     /**
@@ -30,8 +39,9 @@ export interface RemoteAuthCredentialStoreOptions {
      */
     onSnapshot?: (snapshot: SnapshotResponse, generation: number) => void;
     /**
-     * OAuth identities visible through this store. This is a trusted-client
-     * routing policy, not broker authorization.
+     * Broker credentials visible through this store (OAuth identities and API
+     * keys per provider). This is a trusted-client routing policy, not broker
+     * authorization.
      */
     accountPool?: AuthBrokerAccountPool;
     /** Flush cadence for batched observed-usage reports. Default 10s. */

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

@@ -1,10 +1,12 @@
 /**
- * Amazon Bedrock Converse Stream provider.
+ * Amazon Bedrock chat transport.
  *
- * Talks directly to `bedrock-runtime.{region}.amazonaws.com` over HTTPS with
- * SigV4 signing and decodes the `application/vnd.amazon.eventstream` response.
- * No `@aws-sdk/*`, no `@smithy/*`, no `proxy-agent`. Proxies are honored via
- * Bun's native `HTTPS_PROXY` support.
+ * Ordinary requests use Converse Stream; server compaction uses the
+ * Anthropic Messages format over Bedrock's InvokeModelWithResponseStream API.
+ * Both call `bedrock-runtime.{region}.amazonaws.com` directly over HTTPS with
+ * shared credential resolution and SigV4 signing. The normal path decodes
+ * `application/vnd.amazon.eventstream`; no AWS SDK, Smithy, or proxy-agent
+ * dependency is required. Bun's native `HTTPS_PROXY` support is honored.
  *
  * A `models.yml` `baseUrl` is the request origin verbatim (VPC endpoint, gateway, …);
  * only AWS's own regional host is re-pointed at the resolved region. SigV4 unaffected.

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

@@ -4,6 +4,14 @@ import type { AnthropicMessagesClientLike } from "./anthropic-client.js";
 export declare function resolvesToOfficialAnthropicEndpoint(model: Model<"anthropic-messages">): boolean;
 /** Whether model policy and the effective deployment support on-demand compaction. */
 export declare function supportsAnthropicCompaction(model: Model<"anthropic-messages">, effectiveBaseUrl?: string): boolean;
+/**
+ * Whether a Bedrock Converse model compacts through a Bedrock Runtime
+ * `InvokeModelWithResponseStream` side request. AWS bedrock-runtime origins
+ * (public, FIPS, PrivateLink) qualify by default; any other `baseUrl` is a
+ * gateway that may implement only Converse, so it needs
+ * `remoteCompaction.enabled: true`. `enabled: false` always opts out.
+ */
+export declare function supportsBedrockConverseCompaction(model: Model<"bedrock-converse-stream">): boolean;
 /** Read a caller-owned client's endpoint for request and compaction routing. */
 export declare function injectedClientBaseUrl(client: AnthropicMessagesClientLike): string | undefined;
 /** Whether a caller-owned Anthropic client targets a compaction-capable endpoint. */

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

@@ -10,10 +10,16 @@ export declare function resolveDirectAnthropicBaseUrl(model: Model<Api>): string
 /**
  * Whether a request to `model` reaches the official endpoint its compat was built for. `compat.officialEndpoint`
  * classifies the configured `baseUrl`, but a first-party Anthropic model is rerouted at request time by
- * `ANTHROPIC_BASE_URL` or Foundry's `FOUNDRY_BASE_URL` without rebuilding compat. Gates official-only host
- * limits such as the catalog's inline image byte and image count budgets.
+ * `ANTHROPIC_BASE_URL` or Foundry's `FOUNDRY_BASE_URL` without rebuilding compat.
  */
 export declare function reachesOfficialEndpoint(model: Model<Api>): boolean;
+/**
+ * Whether the catalog's host request budgets (inline image bytes, official image count) apply to a request to
+ * `model`: it reaches the official endpoint ({@link reachesOfficialEndpoint}), or its rules set
+ * `catalog-endpoint-budgets` (Factory Droid's hosted API) and it reaches the provider's own catalog endpoint
+ * (unset `baseUrl`, or an `endpoint-hosts` host). A custom gateway keeps its own limits.
+ */
+export declare function reachesBudgetedHost(model: Model<Api>): boolean;
 /** Build the endpoint-and-model-scoped Anthropic session-state key. */
 export declare function anthropicProviderSessionStateKey(baseUrl: string, modelId: string): string;
 /** Re-arm fast mode across materialized Anthropic session-state entries. */

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

@@ -146,6 +146,8 @@ export declare const LEGACY_COMPACTION_BETA = "compact-2026-01-12";
 export type CompactionBlockParam = {
     type: "compaction";
     content: string;
+    /** Opaque signed tool changes from a compaction response. */
+    tool_changes?: Record<string, unknown>[];
     signature?: string;
     encrypted_content?: string | null;
     cache_control?: CacheControlEphemeral | null;
@@ -396,6 +398,7 @@ export type ResponseContentBlock = {
     content: string;
     signature?: string;
     encrypted_content?: string | null;
+    tool_changes?: Record<string, unknown>[];
 };
 export type ContentBlockDelta = {
     type: "text_delta";

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

@@ -1,7 +1,9 @@
 import type { Effort } from "@oh-my-pi/pi-catalog/effort";
-import type { AnthropicCompactionRequest, AnthropicOutputEffort, Api, FetchImpl, Message, Model, ServiceTier, SimpleStreamOptions, StreamFunction, StreamOptions, Usage } from "../types.js";
+import type { AnthropicCompactionRequest, AnthropicOutputEffort, Api, Context, FetchImpl, Message, Model, ServiceTier, SimpleStreamOptions, StreamFunction, StreamOptions, Usage } from "../types.js";
+import { AssistantMessageEventStream } from "../utils/event-stream.js";
+import { type RawHttpRequestDump } from "../utils/http-inspector.js";
 import { type AnthropicFetchOptions, type AnthropicMessagesClientLike } from "./anthropic-client.js";
-import { type FallbackParam, type MessageParam, type TextBlockParam } from "./anthropic-wire.js";
+import { type FallbackParam, type MessageCreateParamsStreaming, type MessageParam, type TextBlockParam } from "./anthropic-wire.js";
 import { resolvesToOfficialAnthropicEndpoint, supportsAnthropicCompaction, supportsAnthropicCompactionOnClient } from "./anthropic-compaction.js";
 import { applyClaudeToolPrefix, deriveClaudeDeviceId, generateClaudeCloakingUserId, isClaudeCloakingUserId, resolveAnthropicMetadataUserId, stripClaudeToolPrefix } from "./anthropic-identity.js";
 import { clearAnthropicFastModeFallback, isAnthropicFastModeFallbackDisabled, normalizeAnthropicBaseUrl } from "./anthropic-state.js";
@@ -204,6 +206,13 @@ export declare function applyAnthropicUsageExtras(usage: Usage, source: Anthropi
 /** Detects the preserved-thinking error caused by rewriting a signed block's conversation prefix. */
 export declare function isThinkingPrefixBindingError(message: string): boolean;
 export declare function isInvalidThinkingSignatureError(message: string): boolean;
+/**
+ * Warn once for the signed thinking blocks the API dropped from one request
+ * after the conversation prefix changed: the count and first path at warn,
+ * every path at debug. One prefix change can drop hundreds of blocks in a
+ * single request, which would otherwise flood the log one line per block.
+ */
+export declare function logDroppedThinking(provider: string, model: string, paths: Array<string | undefined>): void;
 /**
  * Prepend a pointed remediation to a thinking-signature rejection 400 when the
  * model looks like an unmarked custom signing proxy
@@ -288,6 +297,14 @@ export declare function resolveAnthropicCompactionEffort(model: Model<"anthropic
  * gate its header-level interleaved beta on the same decision.
  */
 export declare function shouldStripThinkingHistory(messages: readonly Message[]): boolean;
+/**
+ * Route Bedrock's on-demand Anthropic compaction through the shared Messages
+ * stream consumer while keeping source-provider identity and pricing.
+ */
+export declare function streamBedrockAnthropicCompaction(sourceModel: Model<"bedrock-converse-stream">, context: Context, options: AnthropicOptions, prepareRequest: (params: MessageCreateParamsStreaming, betas: readonly string[]) => Promise<{
+    payload: unknown;
+    rawRequestDump: RawHttpRequestDump;
+}>, createClient: (getPayload: () => unknown) => AnthropicMessagesClientLike, prepareOptions: (options: AnthropicOptions) => AnthropicOptions, forceThinkingOffFields?: Record<string, unknown>): AssistantMessageEventStream;
 /**
  * A single Anthropic conversation turn, including the mid-conversation
  * `system` role (Opus 4.8+ and Fable/Mythos 5).

package/dist/types/providers/factory-droid/tool-names.d.ts

@@ -0,0 +1,21 @@
+import type { Tool } from "../../types.js";
+/**
+ * The CLI sanitizes tool names to `[a-zA-Z0-9_-]`; a name longer than
+ * `maxLength` (64 by default) keeps its first `maxLength - 9` chars and ends
+ * `_` + an 8-char sha256, `maxLength` in all, which stays inside the route's
+ * tool-name bound. Applied to declarations and replayed call/result names on
+ * every wire droid sanitizes.
+ */
+export declare function sanitizeFactoryDroidToolName(name: string, maxLength?: number): string;
+/**
+ * Chat-completions names go out verbatim (the route accepts dots) unless they
+ * exceed `maxLength`, the target's catalog `tool-call-name-max-length`; only
+ * those take the capped, sanitized form.
+ */
+export declare function encodeFactoryDroidCompletionsToolName(name: string, maxLength: number): string;
+/**
+ * Wire name -> caller tool name for the declared tools, so returned calls
+ * dispatch to the tool that was advertised. Two tools sharing one wire name
+ * could not be told apart, so that request is rejected.
+ */
+export declare function factoryDroidToolNamesByWire(tools: Tool[] | undefined, encode?: (name: string) => string): Map<string, string>;

package/dist/types/types.d.ts

@@ -885,6 +885,8 @@ export interface AnthropicCompactionPayload {
     content: string;
     /** Signature of an on-demand block; replayed verbatim. */
     signature?: string;
+    /** Net tool changes across the summarized range; covered by the signature, replayed verbatim. */
+    toolChanges?: Record<string, unknown>[];
     /** Legacy threshold block state (`compact-2026-01-12`); replay-only. */
     encryptedContent?: string;
     /**

package/dist/types/utils/tool-call-loop-guard.d.ts

@@ -8,6 +8,8 @@ export interface ToolCallLoopGuardOptions {
 export interface ToolCallLoopTurn {
     readonly message: AssistantMessage;
     readonly toolResults: readonly ToolResultMessage[];
+    /** The turn also delivered context outside its tool results (extension `additionalContext`). */
+    readonly injectedContext?: boolean;
 }
 /** Details needed to steer the model away from a repeated tool call. */
 export interface RepeatedToolCallDetection {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.12.3",
+	"version": "18.12.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.12.3",
-		"@oh-my-pi/pi-catalog": "18.12.3",
-		"@oh-my-pi/pi-natives": "18.12.3",
-		"@oh-my-pi/pi-utils": "18.12.3",
-		"@oh-my-pi/pi-wire": "18.12.3"
+		"@oh-my-pi/omptype": "18.12.4",
+		"@oh-my-pi/pi-catalog": "18.12.4",
+		"@oh-my-pi/pi-natives": "18.12.4",
+		"@oh-my-pi/pi-utils": "18.12.4",
+		"@oh-my-pi/pi-wire": "18.12.4"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/auth/policy.ts

@@ -28,12 +28,13 @@ export class AccountPolicies {
 	#warnedUnmatched = new Set<number>();
 
 	constructor(policies: AuthAccountPolicies, defaultReservePct: number | undefined) {
-		AccountPolicies.#validateAccountPolicyConfiguration(policies);
-		this.#accountPolicies = policies;
-		this.#defaultReservePct =
+		const effectiveDefaultReservePct =
 			typeof defaultReservePct === "number" && Number.isFinite(defaultReservePct)
 				? Math.max(0, Math.min(100, defaultReservePct))
 				: DEFAULT_USAGE_RESERVE_PCT;
+		AccountPolicies.#validateAccountPolicyConfiguration(policies, effectiveDefaultReservePct);
+		this.#accountPolicies = policies;
+		this.#defaultReservePct = effectiveDefaultReservePct;
 	}
 
 	/** Global usage reserve (0–100) for accounts without a per-account `reservePct`. */
@@ -58,7 +59,7 @@ export class AccountPolicies {
 		this.#warnedUnmatched = next.#warnedUnmatched;
 	}
 
-	static #validateAccountPolicyConfiguration(accountPolicies: AuthAccountPolicies): void {
+	static #validateAccountPolicyConfiguration(accountPolicies: AuthAccountPolicies, defaultReservePct: number): void {
 		for (let index = 0; index < accountPolicies.length; index += 1) {
 			const policy = accountPolicies[index]!;
 			const path = `auth.accountPolicies[${index}]`;
@@ -95,17 +96,32 @@ export class AccountPolicies {
 			) {
 				throw new AIError.ConfigurationError(`${path}.reservePct must be a finite number between 0 and 100`);
 			}
+			if (policy.reclaimAbovePct !== undefined) {
+				const reservePct = policy.reservePct ?? defaultReservePct;
+				if (
+					!Number.isFinite(policy.reclaimAbovePct) ||
+					policy.reclaimAbovePct <= reservePct ||
+					policy.reclaimAbovePct > 100
+				) {
+					throw new AIError.ConfigurationError(
+						`${path}.reclaimAbovePct must be a finite number above the account's reserve (${reservePct}%) and at most 100`,
+					);
+				}
+			}
 		}
 	}
 
 	validateUsageCapability(provider: string, canFetchUsage: boolean): void {
-		const policyIndex = this.#accountPolicies.findIndex(
-			policy => policy.provider === provider && policy.reservePct !== undefined,
-		);
-		if (policyIndex !== -1 && !canFetchUsage) {
-			throw new AIError.ConfigurationError(
-				`auth.accountPolicies[${policyIndex}].reservePct requires a usage provider for ${provider}`,
+		if (canFetchUsage) return;
+		for (const field of ["reservePct", "reclaimAbovePct"] as const) {
+			const policyIndex = this.#accountPolicies.findIndex(
+				policy => policy.provider === provider && policy[field] !== undefined,
 			);
+			if (policyIndex !== -1) {
+				throw new AIError.ConfigurationError(
+					`auth.accountPolicies[${policyIndex}].${field} requires a usage provider for ${provider}`,
+				);
+			}
 		}
 	}
 

package/src/auth/rank.ts

@@ -25,6 +25,10 @@ export type UsageCandidate<T extends AuthCredential> = {
 	 * spent, so if it still serves it draws on paid overage such as Codex credits.
 	 */
 	allowanceSpent?: boolean;
+	/** Present after policy-aware ranking: the account's configured `priority` (0 when unset). */
+	accountPriority?: number;
+	/** Present after policy-aware ranking: unblocked and measured at or above its `reclaimAbovePct`. */
+	reclaimReady?: boolean;
 };
 
 /** OAuth credential eligible for usage ranking. */
@@ -152,5 +156,7 @@ export function orderUsageRankedCandidates<T extends AuthCredential>(
 		inReserve: candidate.inReserve,
 		reserveMeasured: candidate.reserveMeasured,
 		allowanceSpent: candidate.allowanceSpent,
+		accountPriority: candidate.accountPriority,
+		reclaimReady: candidate.reclaimReady,
 	}));
 }

package/src/auth/select.ts

@@ -489,6 +489,11 @@ export class CredentialSelector {
 				reserveMeasured: reserveFraction !== undefined && remainingFraction !== undefined,
 				accountPriority: policy?.priority === undefined || !Number.isFinite(policy.priority) ? 0 : policy.priority,
 				allowanceSpent: remainingFraction === 0,
+				reclaimReady:
+					!blocked &&
+					policy?.reclaimAbovePct !== undefined &&
+					remainingFraction !== undefined &&
+					remainingFraction * 100 >= policy.reclaimAbovePct,
 				usageMeasured,
 				hasPriorityBoost: strategy?.hasPriorityBoost?.(primary, primaryUncapped, args.rankingContext) ?? false,
 				planPriority: planPriority(args.planGate, usage),
@@ -689,13 +694,26 @@ export class CredentialSelector {
 				candidate.selection.index === sessionPreferredIndex,
 		);
 		const preferredCandidate = sessionPreferredCandidate === -1 ? undefined : candidates[sessionPreferredCandidate];
-		// A warm automatic pin normally wins. Two policies may evict it, each only
+		// A warm automatic pin normally wins. Three policies may evict it, each only
 		// while a sibling is confirmed better: reserve (sibling measured outside
-		// reserve) and spent allowance (unblocked sibling with allowance left).
-		const automaticPinWouldBeEvicted = (excludePreflightFailures: boolean): boolean =>
-			!sessionPinIsExplicit &&
-			preferredCandidate !== undefined &&
-			candidates.some(candidate => {
+		// reserve), spent allowance (unblocked sibling with allowance left), and
+		// opt-in reclaim (the sibling ranking picks next has higher priority and is
+		// measured at or above its `reclaimAbovePct`).
+		const automaticPinWouldBeEvicted = (excludePreflightFailures: boolean): boolean => {
+			if (sessionPinIsExplicit || preferredCandidate === undefined) return false;
+			const rankedWinner = candidates.find(
+				candidate =>
+					candidate !== preferredCandidate &&
+					!(excludePreflightFailures && preflightFailures.has(candidate)) &&
+					!this.#deps.blocks.isBlocked(provider, providerKey, candidate.selection.index, blockScopes),
+			);
+			if (
+				rankedWinner?.reclaimReady === true &&
+				(rankedWinner.accountPriority ?? 0) > (preferredCandidate.accountPriority ?? 0)
+			) {
+				return true;
+			}
+			return candidates.some(candidate => {
 				if (candidate === preferredCandidate) return false;
 				if (excludePreflightFailures && preflightFailures.has(candidate)) return false;
 				if (
@@ -712,6 +730,7 @@ export class CredentialSelector {
 					!this.#deps.blocks.isBlocked(provider, providerKey, candidate.selection.index, blockScopes)
 				);
 			});
+		};
 		const pinEvictedBeforePreflight = automaticPinWouldBeEvicted(false);
 		if (
 			!hasPlanRequirement &&

package/src/auth/types.ts

@@ -62,6 +62,8 @@ export interface AuthAccountPolicy {
 	readonly priority?: number;
 	/** Protected remaining quota percentage for this account. */
 	readonly reservePct?: number;
+	/** Remaining quota percentage, above the reserve, at which this account takes back lower-priority warm pins. */
+	readonly reclaimAbovePct?: number;
 }
 
 /** Read-only set of per-account routing policies. */

package/src/auth-broker/discover.ts

@@ -27,7 +27,7 @@ import {
 } from "../auth-storage";
 import * as AIError from "../error";
 import { AuthBrokerClient, AuthBrokerError } from "./client";
-import { type AuthBrokerAccountPool, RemoteAuthCredentialStore } from "./remote-store";
+import { type AuthBrokerAccountPool, type AuthBrokerProviderPool, RemoteAuthCredentialStore } from "./remote-store";
 import { readAuthBrokerSnapshotCache, scheduleAuthBrokerSnapshotCacheWrite } from "./snapshot-cache";
 import { DEFAULT_SNAPSHOT_CACHE_TTL_MS, type SnapshotResponse } from "./types";
 
@@ -122,7 +122,12 @@ function parseAuthAccountPolicies(value: unknown): AuthAccountPolicies {
 		}
 		const policy = entry as Record<string, unknown>;
 		const unknownPolicyFields = Object.keys(policy).filter(
-			key => key !== "provider" && key !== "account" && key !== "priority" && key !== "reservePct",
+			key =>
+				key !== "provider" &&
+				key !== "account" &&
+				key !== "priority" &&
+				key !== "reservePct" &&
+				key !== "reclaimAbovePct",
 		);
 		if (unknownPolicyFields.length > 0) {
 			throw new AIError.ConfigurationError(`${path} has unknown fields: ${unknownPolicyFields.join(", ")}`);
@@ -171,6 +176,12 @@ function parseAuthAccountPolicies(value: unknown): AuthAccountPolicies {
 		) {
 			throw new AIError.ConfigurationError(`${path}.reservePct must be between 0 and 100`);
 		}
+		if (
+			policy.reclaimAbovePct !== undefined &&
+			(typeof policy.reclaimAbovePct !== "number" || !Number.isFinite(policy.reclaimAbovePct))
+		) {
+			throw new AIError.ConfigurationError(`${path}.reclaimAbovePct must be a finite number`);
+		}
 
 		return {
 			provider,
@@ -182,6 +193,7 @@ function parseAuthAccountPolicies(value: unknown): AuthAccountPolicies {
 			},
 			...(typeof policy.priority === "number" ? { priority: policy.priority } : {}),
 			...(typeof policy.reservePct === "number" ? { reservePct: policy.reservePct } : {}),
+			...(typeof policy.reclaimAbovePct === "number" ? { reclaimAbovePct: policy.reclaimAbovePct } : {}),
 		};
 	});
 }
@@ -272,7 +284,7 @@ export async function loadAuthBrokerAccountPool(): Promise<AuthBrokerAccountPool
 		throw new AIError.ConfigurationError("OMP_AUTH_BROKER_ACCOUNT_POOL_FILE must contain a JSON object");
 	}
 
-	const accountPool = new Map<string, ReadonlySet<string>>();
+	const accountPool = new Map<string, ReadonlySet<string> | AuthBrokerProviderPool>();
 	for (const [provider, value] of Object.entries(parsed)) {
 		const normalizedProvider = provider.trim();
 		if (normalizedProvider.length === 0) {
@@ -283,28 +295,66 @@ export async function loadAuthBrokerAccountPool(): Promise<AuthBrokerAccountPool
 				"OMP_AUTH_BROKER_ACCOUNT_POOL_FILE contains a provider id with surrounding whitespace",
 			);
 		}
-		if (!Array.isArray(value)) {
-			throw new AIError.ConfigurationError(
-				`OMP_AUTH_BROKER_ACCOUNT_POOL_FILE entry for ${provider} must be an array of identity keys`,
-			);
-		}
-		const identities = new Set<string>();
-		for (const identity of value) {
-			if (typeof identity !== "string" || identity.length === 0) {
+		accountPool.set(provider, parseAccountPoolEntry(provider, value));
+	}
+	return accountPool;
+}
+
+/**
+ * One pool-file entry: an identity array (visible OAuth accounts, API keys
+ * kept), `true` (everything visible), `false` (nothing visible), or a rule
+ * object `{ "accounts"?: [...], "apiKeys"?: boolean }`.
+ */
+function parseAccountPoolEntry(provider: string, value: unknown): ReadonlySet<string> | AuthBrokerProviderPool {
+	if (Array.isArray(value)) return parseAccountPoolIdentities(provider, value);
+	if (value === true) return {};
+	if (value === false) return { accounts: new Set(), apiKeys: false };
+	if (value === null || typeof value !== "object") {
+		throw new AIError.ConfigurationError(
+			`OMP_AUTH_BROKER_ACCOUNT_POOL_FILE entry for ${provider} must be an array of identity keys, a boolean, or an object with "accounts"/"apiKeys"`,
+		);
+	}
+	const rule: { accounts?: ReadonlySet<string>; apiKeys?: boolean } = {};
+	for (const [key, field] of Object.entries(value)) {
+		if (key === "accounts") {
+			if (!Array.isArray(field)) {
 				throw new AIError.ConfigurationError(
-					`OMP_AUTH_BROKER_ACCOUNT_POOL_FILE entry for ${provider} contains an invalid identity key`,
+					`OMP_AUTH_BROKER_ACCOUNT_POOL_FILE entry for ${provider} has "accounts" that is not an array of identity keys`,
 				);
 			}
-			if (identity !== identity.trim()) {
+			rule.accounts = parseAccountPoolIdentities(provider, field);
+		} else if (key === "apiKeys") {
+			if (typeof field !== "boolean") {
 				throw new AIError.ConfigurationError(
-					`OMP_AUTH_BROKER_ACCOUNT_POOL_FILE entry for ${provider} contains an identity key with surrounding whitespace`,
+					`OMP_AUTH_BROKER_ACCOUNT_POOL_FILE entry for ${provider} has "apiKeys" that is not a boolean`,
 				);
 			}
-			identities.add(identity);
+			rule.apiKeys = field;
+		} else {
+			throw new AIError.ConfigurationError(
+				`OMP_AUTH_BROKER_ACCOUNT_POOL_FILE entry for ${provider} has unknown field ${JSON.stringify(key)}`,
+			);
 		}
-		accountPool.set(provider, identities);
 	}
-	return accountPool;
+	return rule;
+}
+
+function parseAccountPoolIdentities(provider: string, value: unknown[]): Set<string> {
+	const identities = new Set<string>();
+	for (const identity of value) {
+		if (typeof identity !== "string" || identity.length === 0) {
+			throw new AIError.ConfigurationError(
+				`OMP_AUTH_BROKER_ACCOUNT_POOL_FILE entry for ${provider} contains an invalid identity key`,
+			);
+		}
+		if (identity !== identity.trim()) {
+			throw new AIError.ConfigurationError(
+				`OMP_AUTH_BROKER_ACCOUNT_POOL_FILE entry for ${provider} contains an identity key with surrounding whitespace`,
+			);
+		}
+		identities.add(identity);
+	}
+	return identities;
 }
 
 function resolveSnapshotTtlMs(): number {