@linxiraos/pi-ai 1.1.20 → 1.1.23

package/CHANGELOG.md

@@ -2,18 +2,8 @@
 
 ## [Unreleased]
 
-## [1.1.20] - 2026-09-23
+## [1.1.23] - 2026-10-01
 
-- 版本线推进;本版无独立用户可见变化。
+## [1.1.22] - 2026-09-30
 
-## [1.1.19] - 2026-09-22
-
-- 版本线推进;本版无独立用户可见变化。
-
-## [1.1.18] - 2026-09-22
-
-- 包元数据:author/maintainer 更新为 Linxira-OS,LICENSE 追加 Linxira-OS 版权行(发行面变更)。
-
-## [1.1.16] - 2026-09-19
-
-- 上游 v18.2.5 同步:stencil.so OAuth 认证回调、流式 JSON 代理解析优化。
+- 随 1.1.22 版本线发布;无面向用户的行为变化。

package/README.md

@@ -1186,6 +1186,18 @@ const response = await complete(
 );
 ```
 
+When an auth-broker client requests recovery after a provider rejects an OAuth
+bearer, the broker may reuse a still-fresh token that it minted in the previous
+five minutes instead of rotating the refresh token again. The process-local
+cache is bound to the credential ID and access token. Scheduled expiry refreshes,
+direct forced refreshes such as MCP recovery, ordinary hard-auth blocks, and
+sibling rotation keep their existing behavior. Cached refresh responses rebind
+by durable credential ID so concurrent row removal cannot switch a pinned
+session to another account.
+Generic `forceRefresh: true` requests do not opt into reuse. Provider-401 retry
+paths pass `refreshReason: "auth-recovery"` explicitly; expiry sentinels and
+usage polling do not imply that reason.
+
 ### Provider Notes
 
 **OpenAI Codex**: Requires a ChatGPT Plus or Pro subscription. Provides access to GPT-5.x Codex models with extended context windows and reasoning capabilities. The library automatically handles session-based prompt caching when `sessionId` is provided in stream options.

package/THIRD-PARTY-NOTICES.txt

@@ -78,8 +78,8 @@ below.
 uutils coreutils (https://github.com/uutils/coreutils), MIT
 --------------------------------------------------------------------------------
 Covers: base32, base64, basename, cat, cksum (shared checksum machinery),
-b2sum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, comm, cut,
-date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nproc, paste,
+b2sum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, comm, cp,
+cut, date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nproc, paste,
 printenv, readlink, realpath, rm, seq, sort, stat, tac, tail, tee, touch, tr,
 truncate, uname, uniq, wc, whoami, yes.
 
@@ -293,7 +293,7 @@ MIT License
 Copyright (c) 2026 Sander Land
   (measured tokenizer vocabulary data, reconstruction model, and reference
   implementation: https://github.com/sanderland/ctok)
-Copyright (c) 2026 Can Bölük and the Oh My Pi contributors
+Copyright (c) 2026 Can Bölük and the omp contributors
 Copyright (c) 2026 Stencil Labs, Inc.
   (Rust implementation and the compact binary vocabulary encoding in
   crates/pi-natives/src/utok/claude)
@@ -335,43 +335,6 @@ This license allows the work and adaptations of it to be shared and used
 commercially, as long as it is attributed to Poppy Works. The font is bundled
 here (crates/pi-natives/src/fonts/Silver.ttf) as a CJK/Unicode bitmap fallback.
 
--------------------------------------------------------------------------------
-packages/utils/src/vendor/mermaid-ascii/NOTICE
-
-This directory contains an in-house Mermaid-diagram-to-ASCII renderer adapted
-from beautiful-mermaid (https://github.com/lukilabs/beautiful-mermaid), used
-under the MIT License.
-
-  Copyright (c) 2026 Craft Docs
-
-Only the ASCII rendering pipeline is ported (flowchart/state, sequence, class,
-ER, and xychart diagrams); the SVG renderer and its `elkjs` graph-layout
-dependency, the browser entry point, and the SVG theme/style modules were
-dropped. Terminal display width is reimplemented on `Bun.stringWidth`, and
-inline label formatting (HTML tags, markdown emphasis) is reduced to plain text
-for ASCII output. Layout and edge-routing logic is preserved faithfully so
-ASCII output matches the upstream package.
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
 -------------------------------------------------------------------------------
 packages/coding-agent/src/markit/NOTICE
 

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

@@ -0,0 +1,6 @@
+/**
+ * Race `promise` against `signal`, rejecting only this caller when the signal
+ * fires. The underlying promise keeps running so other awaiters on the same
+ * single-flight operation aren't punished by a peer's cancel.
+ */
+export declare function raceSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined, message: string): Promise<T>;

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

@@ -0,0 +1,68 @@
+import type { AuthCredential, OAuthCredential, SessionsApi } from "./types.js";
+import type { AuthCredentialStore } from "./store.js";
+import type { CredentialPool } from "./pool.js";
+import type { KeyOverrides } from "./cascade.js";
+/** Prefix for persisted session-to-credential affinity. */
+export declare const SESSION_STICKY_CACHE_PREFIX = "session:sticky:";
+/** A session's pinned credential (resolved index + durable row id). */
+export type SessionCredential = {
+    type: AuthCredential["type"];
+    index: number;
+    credentialId?: number;
+    lastUsedAtMs?: number;
+    /** Set only by the public user-facing pin API; automatic warm affinity leaves it absent. */
+    explicit?: true;
+};
+/** Session → credential affinity (pins), persisted in the store cache. */
+export declare class SessionAffinity implements SessionsApi {
+    #private;
+    constructor(store: AuthCredentialStore, pool: CredentialPool, overrides: KeyOverrides);
+    /** Drop every pin for a provider, both in memory and in the persisted cache. */
+    clearProvider(provider: string): void;
+    /** Drop only this in-memory session pin after OAuth selection falls through. */
+    forget(provider: string, sessionId: string): void;
+    /**
+     * Records which credential was used for a session (for rate-limit switching).
+     * `lastUsedAtMs` backdates the sticky (session-file pin restores on resume);
+     * it defaults to now for live selections. Automatic re-recording of the same
+     * durable row preserves an explicit user pin.
+     */
+    record(provider: string, sessionId: string | undefined, type: AuthCredential["type"], index: number, lastUsedAtMs?: number, explicit?: boolean): void;
+    /** Retrieves the last credential used by a session. */
+    get(provider: string, sessionId: string | undefined): SessionCredential | undefined;
+    /** Clears the last credential used by a session for a provider. */
+    clear(provider: string, sessionId: string | undefined): void;
+    activeOAuth(provider: string, sessionId?: string): OAuthCredential | undefined;
+    /**
+     * Pin one stored OAuth account as this session's preferred credential.
+     *
+     * The durable credential id keeps the pin stable across credential refreshes,
+     * storage reordering, and process restarts. By default this is an explicit
+     * user pin: ranking and account reserve never evict it; hard unavailability
+     * and auth retry may still route around it.
+     *
+     * `options.restoredAtMs` instead restores an automatic affinity recorded by a
+     * persisted session, backdated to its last use, so it keeps the provider's
+     * warm-window semantics: a resume inside the prompt-cache TTL reuses the
+     * account, a stale resume re-ranks.
+     */
+    pin(provider: string, sessionId: string, credentialId: number, options?: {
+        restoredAtMs?: number;
+    }): boolean;
+    /**
+     * Copy every stored credential affinity from one live session to another.
+     *
+     * The target receives its own sticky entries, so request resolution, usage
+     * blocking, credential rotation, metadata, and persisted pins all continue
+     * through the target session id without retaining a live dependency on the
+     * source session.
+     */
+    inherit(sourceSessionId: string, targetSessionId: string): number;
+    /**
+     * Release a session's sticky credential so its next `KeyCascade.get` call
+     * re-runs native pool ranking. This never blocks or penalizes the released
+     * account; usage-aware routing uses it when another sibling has more
+     * headroom, before considering a model/provider fallback.
+     */
+    release(provider: string, sessionId: string): boolean;
+}

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

@@ -0,0 +1,106 @@
+import type { Provider } from "../types.js";
+import type { CredentialRankingContext, CredentialRankingStrategy, UsageReport } from "../usage.js";
+import type { RankingStrategyResolver } from "../usage/registry.js";
+import type { CredentialPool } from "./pool.js";
+import type { AuthCredentialStore } from "./store.js";
+import type { UsageCache, UsageRequestDescriptor } from "./usage-cache.js";
+import type { AuthCredential, BlocksApi, StoredCredentialBlock } from "./types.js";
+/** Default block when no provider reset time is known; used by selectors and rate limits. */
+export declare const DEFAULT_BLOCK_MS = 60000;
+/** Composite key for round-robin tracking: "<provider>:oauth" or "<provider>:api_key". */
+export declare function providerTypeKey(provider: string, type: AuthCredential["type"]): string;
+/** Scoped backoff map key used by the credential block store. */
+export declare function scopedBackoffKey(providerKey: string, blockScope: string | undefined): string;
+/** Authentication backoffs apply to every model and cannot be healed by quota evidence. */
+export declare const AUTH_BLOCK_SCOPE = "auth";
+/** Account-policy backoffs apply to every model and survive quota resets. */
+export declare const ACCOUNT_POLICY_BLOCK_SCOPE = "account-policy";
+/** Scope key for one model-specific account-policy block, shared by selectors and rate limits. */
+export declare function modelAccountPolicyBlockScope(provider: string, modelId: string | undefined): string | undefined;
+/** Scope keys that a request must check, including model-policy constraints. */
+export declare function credentialBlockScopesForRequest(provider: string, strategy: CredentialRankingStrategy | undefined, rankingContext: CredentialRankingContext, blockScope: string | undefined): readonly string[];
+/** Latch for unrecoverably corrupt persisted block stores, shared with the credential pool. */
+export declare class BlockStoreHealth {
+    #private;
+    constructor(sourceLabel: string | undefined);
+    get damaged(): boolean;
+    handle(err: unknown): boolean;
+    assertWritable(): void;
+}
+/** Dependencies for persisted rate-limit blocks and usage-report healing. */
+export interface CredentialBlocksDeps {
+    store: AuthCredentialStore;
+    pool: CredentialPool;
+    health: BlockStoreHealth;
+    usageCache: UsageCache;
+    strategies: RankingStrategyResolver;
+}
+/** Temporary rate-limit blocks: id-keyed in memory, mirrored to the store, healed by live usage. */
+export declare class CredentialBlocks implements BlocksApi {
+    #private;
+    constructor(deps: CredentialBlocksDeps);
+    /** Returns block expiry timestamp for a credential, checking unscoped and scoped blocks. */
+    blockedUntil(provider: string, providerKey: string, credentialIndex: number, blockScopeOrScopes?: string | readonly string[] | undefined): number | undefined;
+    /** Checks if a credential is temporarily blocked due to usage limits. */
+    isBlocked(provider: string, providerKey: string, credentialIndex: number, blockScope?: string | readonly string[] | undefined): boolean;
+    /**
+     * Whether the in-memory block currently sitting at exactly `deadline` for
+     * this credential was written with provider-stated timing. Mirrors the
+     * scope enumeration of {@link CredentialBlocks.blockedUntil}.
+     * A deadline with no matching in-memory entry came from the persisted
+     * store, which carries no provenance — a stale persisted heuristic guess
+     * (pre-restart hintless response) must not outrank a fresh complete usage
+     * report, so persisted-only deadlines count as untimed. Persisted
+     * deadlines longer than this call's own request still win through the
+     * merged `blockedUntilMs` comparison, which needs no provenance.
+     */
+    isTimed(providerKey: string, blockScopeOrScopes: string | readonly string[] | undefined, credentialId: number, deadline: number): boolean;
+    /**
+     * Marks a credential as blocked until the specified time. `providerTimed`
+     * records whether the requested deadline comes from provider-stated
+     * timing (a parsed retry hint or a usage-report reset) rather than a
+     * heuristic/default guess; the stored block keeps the provenance of
+     * whichever deadline wins the longest-wins merge.
+     */
+    mark(provider: string, providerKey: string, credentialIndex: number, blockedUntilMs: number, blockScope?: string | undefined, providerTimed?: boolean): void;
+    /**
+     * Lift any temporary backoff blocks on one credential (across the bare
+     * `provider:oauth` key and its scoped `\0`-suffixed derivatives). Called
+     * after a saved reset is redeemed so the just-reset account is immediately
+     * selectable again instead of being skipped/under-ranked by a stale block
+     * that `markUsageLimitReached` set for the now-obsolete reset time.
+     */
+    clearAll(provider: string, credentialId: number): void;
+    /** Clear exactly one quota scope, preserving unrelated account and model blocks. */
+    clearScope(provider: string, credentialId: number, providerKey: string, blockScope: string | undefined): boolean;
+    /** Providers whose stale usage-limit blocks a healthy live report may clear. */
+    supportsHealing(provider: Provider): boolean;
+    /**
+     * Whether a fresh report could lift what currently blocks this credential.
+     *
+     * Claude reports can heal legacy account-wide quota blocks too. Explicit
+     * auth/account-policy blocks never justify a usage probe.
+     */
+    canHeal(provider: Provider, providerKey: string, credentialIndex: number, blockScopeOrScopes: string | readonly string[] | undefined): boolean;
+    /**
+     * Self-heal stale usage-limit blocks: when a fresh live usage report says a
+     * scope is below every limit gating it, drop its persisted and in-memory
+     * blocks so credential selection re-includes the recovered account before
+     * the block expires by clock. Providers declare their scopes and any meter
+     * verdicts via {@link CredentialRankingStrategy.healableBlockScopes}.
+     */
+    reconcile(provider: Provider, credentialId: number, report: UsageReport): void;
+    reconcileRequest(request: UsageRequestDescriptor, report: UsageReport): void;
+    reconcileReports(reports: UsageReport[]): void;
+    /**
+     * Broker-server seam: list non-expired persisted blocks for snapshot entries.
+     */
+    list(credentialIds: readonly number[]): StoredCredentialBlock[];
+    /**
+     * Broker-server seam: persist one credential block and notify snapshot waiters.
+     */
+    upsert(block: StoredCredentialBlock): void;
+    /** Broker-server seam: clear exactly one persisted and local block and notify snapshot waiters. */
+    delete(credentialId: number, providerKey: string, blockScope: string, invalidateUsage?: boolean): void;
+    deleteAll(credentialId: number): void;
+}

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

@@ -0,0 +1,147 @@
+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 } from "./types.js";
+/** Runtime (--api-key) and config (models.yml) key overrides plus the config-value resolver. */
+export declare class KeyOverrides {
+    #private;
+    constructor(resolver?: (config: string) => Promise<string | undefined>);
+    has(provider: string): boolean;
+    runtimeKey(provider: string): string | undefined;
+    configKey(provider: string): string | undefined;
+    /** Resolve a config value (env var name, "!command", literal) to the secret. */
+    resolve(config: string): Promise<string | undefined>;
+    /**
+     * Set a runtime API key override (not persisted to disk).
+     * Used for CLI --api-key flag.
+     */
+    setRuntime(provider: string, apiKey: string): void;
+    /**
+     * Remove a runtime API key override.
+     */
+    removeRuntime(provider: string): void;
+    /**
+     * Register a per-provider API key sourced from user configuration
+     * (e.g. `models.yml` `providers.<name>.apiKey`). Higher priority than
+     * stored credentials and OAuth tokens — when the user pins a key in
+     * config, that key is what authenticates outbound requests, regardless
+     * of whatever the broker happens to have loaded for that provider.
+     *
+     * Lower priority than {@link KeyOverrides.setRuntime} so a CLI `--api-key`
+     * still wins for the duration of a single invocation.
+     */
+    setConfig(provider: string, apiKeyConfig: string): void;
+    /**
+     * Remove a single config-sourced API key override.
+     */
+    removeConfig(provider: string): void;
+    /**
+     * Drop every config-sourced API key. Called by `ModelRegistry` before
+     * re-parsing `models.yml` so removed entries actually disappear.
+     */
+    clearConfig(): void;
+    /**
+     * Install the host's async config-value resolver. Coding-agent uses this so
+     * every stored/config credential reference shares command caching,
+     * failure backoff, and process hardening even when AuthStorage was created
+     * independently and later attached to a registry.
+     */
+    setResolver(resolver: (config: string) => Promise<string | undefined>): void;
+}
+/** Dependencies of the provider key precedence cascade. */
+export interface KeyCascadeDeps {
+    pool: CredentialPool;
+    overrides: KeyOverrides;
+    selector: CredentialSelector;
+    affinity: SessionAffinity;
+    /** LimitsApi.rotate, injected to avoid a cascade↔rotation import cycle. */
+    rotate: LimitsApi["rotate"];
+    sourceLabel?: string;
+}
+/** The provider auth precedence cascade (runtime → config → OAuth → login key → env → stored key). */
+export declare class KeyCascade implements KeysApi {
+    #private;
+    constructor(deps: KeyCascadeDeps);
+    /**
+     * True when a stored credential is the provider's KDL `empty-fallback`
+     * keyless-mode marker — what an empty paste at an "Optional: paste API key"
+     * login prompt stores (e.g. `lm-studio-local` for lm-studio). The wire layer
+     * never sends these as a bearer (`isDiscoveryBearerApiKey` strips them), so
+     * auth-status surfaces must not count them either; otherwise the model hub
+     * and `/login` report the provider as authenticated while every request
+     * goes out bare (issue #12281). The credential itself stays stored: `/logout`
+     * can still remove it, and availability treats the provider as keyless.
+     */
+    isKeylessFallback(provider: string, credential: AuthCredential): boolean;
+    /**
+     * True when the provider has stored credentials but none of them carries
+     * auth — i.e. its only credential is the KDL `empty-fallback` keyless-mode
+     * marker (an empty paste at an optional-key login prompt). Such a provider
+     * is configured-but-keyless: model availability treats it like an
+     * `auth: none` endpoint instead of locking it out (issue #12281).
+     */
+    keyless(provider: string): boolean;
+    /**
+     * Classify where a provider's auth comes from, following the same precedence
+     * as {@link KeyCascade.get}: runtime override → config override →
+     * stored OAuth → login-stored api_key → env var → stored api_key.
+     * Returns undefined when no auth is configured.
+     *
+     * Compact, structured counterpart to {@link KeyCascade.describe}; `env`
+     * selects dedicated-only, alias-aware, or no environment fallback.
+     */
+    source(provider: string, { env }?: AuthSourceOptions): AuthSource | undefined;
+    /**
+     * Peek at API key for a provider without refreshing OAuth tokens.
+     * Used for model discovery where we only need to know if credentials exist
+     * and get a best-effort token. GitHub Copilot's peek must preserve
+     * enterprise routing metadata because discovery needs a structured
+     * credential to reach the correct host.
+     */
+    peek(provider: string): Promise<string | undefined>;
+    /** Resolve a bearer together with the stored row that supplied it. */
+    getWithCredential(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<ResolvedApiKey | undefined>;
+    /**
+     * Get API key for a provider.
+     * Priority (first match wins): runtime override, config override, OAuth,
+     * login API key, environment variable, then another stored API key.
+     */
+    get(provider: string, sessionId?: string, options?: AuthApiKeyOptions, onCredentialId?: (id: number) => void): Promise<string | undefined>;
+    /**
+     * Build an {@link ApiKeyResolver} backed by this storage, implementing the
+     * central a/b/c auth-retry policy:
+     *
+     * - initial (`error: undefined`) → resolve the session credential.
+     * - step (b) `!lastChance` → force-refresh the SAME session-sticky credential.
+     * - step (c) `lastChance` → rotate to a sibling and re-resolve, unless quota exhaustion has no sibling.
+     *
+     * Used by web-search providers and other consumers that hold a KeyCascade
+     * directly (no ModelRegistry in scope).
+     */
+    resolver(provider: string, options?: {
+        sessionId?: string;
+        baseUrl?: string;
+        modelId?: string;
+    }): ApiKeyResolver;
+    /**
+     * Describe where the active credential for a provider came from.
+     *
+     * Mirrors {@link KeyCascade.get} precedence, highest first:
+     *   1. Runtime override (`--api-key`).
+     *   2. Config override (`models.yml` `providers.<name>.apiKey`).
+     *   3. Stored OAuth credential.
+     *   4. API key persisted by a successful `/login`.
+     *   5. Env var — overrides a stored static api_key (e.g. a stale broker copy).
+     *   6. Stored api_key credential.
+     *
+     * The string is purely informational; consumers must not parse it.
+     */
+    describe(provider: string, sessionId?: string): string | undefined;
+    setRuntime(provider: string, apiKey: string): void;
+    removeRuntime(provider: string): void;
+    setConfig(provider: string, apiKeyConfig: string): void;
+    removeConfig(provider: string): void;
+    clearConfig(): void;
+    setResolver(resolver: (config: string) => Promise<string | undefined>): void;
+}

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

@@ -0,0 +1,66 @@
+import type { Provider } from "../types.js";
+import type { RankingStrategyResolver } from "../usage/registry.js";
+import type { SessionAffinity } from "./affinity.js";
+import type { CredentialBlocks } from "./blocks.js";
+import type { KeyCascade, KeyOverrides } from "./cascade.js";
+import type { AccountPolicies } from "./policy.js";
+import type { CredentialPool } from "./pool.js";
+import type { OAuthRefresher } from "./refresh.js";
+import type { AuthCredentialStore } from "./store.js";
+import type { CheckCredentialsOptions, CredentialHealthResult, HealthApi, ModelUsageHealth, ModelUsageHealthOptions } from "./types.js";
+import type { UsageService } from "./usage.js";
+/** Dependencies for model pool health and stored credential probes. */
+export interface CredentialHealthDeps {
+    store: AuthCredentialStore;
+    pool: CredentialPool;
+    keys: KeyCascade;
+    policies: AccountPolicies;
+    blocks: CredentialBlocks;
+    affinity: SessionAffinity;
+    usage: UsageService;
+    refresher: OAuthRefresher;
+    overrides: KeyOverrides;
+    strategies: RankingStrategyResolver;
+}
+/** Model-level pool health and per-credential auth probes. */
+export declare class CredentialHealth implements HealthApi {
+    #private;
+    constructor(deps: CredentialHealthDeps);
+    /**
+     * Inspect the credential pool that {@link getApiKey} would use for one model
+     * without advancing round-robin state or changing session stickiness.
+     *
+     * Pool aggregation is deliberately conservative: one healthy sibling makes
+     * the model healthy, while any unknown sibling prevents a depleted/reserve
+     * conclusion. Static runtime/config/env credentials return unknown because
+     * they bypass the managed account pool.
+     */
+    model(provider: Provider, options: ModelUsageHealthOptions): Promise<ModelUsageHealth>;
+    /**
+     * Probe each stored credential against its provider's auth-verifying usage
+     * endpoint and report per-credential auth health.
+     *
+     * Surfaces the identity of failing credentials so callers running a
+     * multi-account pool (e.g. a broker-backed auth-gateway) can tell which
+     * row is producing 401s. The probe mirrors the per-credential fan-out
+     * inside {@link UsageService.reports} (OAuth refresh-on-expiry,
+     * then `UsageProvider.fetchUsage`) but does NOT swallow errors — every
+     * credential gets either `ok: true`, `ok: false` with `reason`, or
+     * `ok: null` when no probe is configured for the provider.
+     *
+     * Iterates sequentially to avoid synchronized N-account fan-out that
+     * upstream `/usage` rate limiters (per source IP) treat as a burst.
+     *
+     * Only inspects active rows from {@link AuthCredentialStore.listAuthCredentials};
+     * soft-disabled rows are already known-bad and don't need a network probe.
+     * Environment-variable API keys are not enumerated — the caller's intent
+     * here is "which of my stored credentials is broken".
+     *
+     * Pass {@link CheckCredentialsOptions.completionProbe} to additionally
+     * exercise each credential against the provider's chat-completion endpoint
+     * (strict mode). The result lands on
+     * {@link CredentialHealthResult.completion}; the usage `ok` field is
+     * unchanged so callers can tell the two signals apart.
+     */
+    check(options?: CheckCredentialsOptions): Promise<CredentialHealthResult[]>;
+}

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

@@ -0,0 +1,93 @@
+import type { OAuthProviderId } from "../registry/oauth/types.js";
+import type { SessionAffinity } from "./affinity.js";
+import type { KeyOverrides } from "./cascade.js";
+import type { AccountPolicies } from "./policy.js";
+import type { CredentialPool } from "./pool.js";
+import type { OAuthRefresher } from "./refresh.js";
+import type { CredentialSelector } from "./select.js";
+import type { AuthAccountPolicy, AuthApiKeyOptions, AuthCredentialSnapshotEntry, OAuthAccess, OAuthAccessResolution, OAuthAccountIdentity, OAuthAccountSummary, OAuthApi, OAuthCredential, OAuthLoginController, OAuthLoginIdentity, OAuthRefreshByIdOptions, StoredOAuthRefreshOptions, StoredOAuthRefreshResult } from "./types.js";
+/** Dependencies used by the OAuth account operations. */
+export interface OAuthAccountsDeps {
+    pool: CredentialPool;
+    overrides: KeyOverrides;
+    policies: AccountPolicies;
+    selector: CredentialSelector;
+    affinity: SessionAffinity;
+    refresher: OAuthRefresher;
+}
+/** OAuth login, per-account access resolution, and account listings. */
+export declare class OAuthAccounts implements OAuthApi {
+    #private;
+    constructor(deps: OAuthAccountsDeps);
+    /**
+     * Login to an OAuth provider. Resolves with the stored credential's
+     * identity slice (or `undefined` when nothing was stored) so callers can
+     * surface which account — and for Anthropic, which organization — the
+     * login registered.
+     */
+    login(provider: OAuthProviderId, ctrl: OAuthLoginController): Promise<OAuthLoginIdentity | undefined>;
+    /**
+     * Resolve the OAuth credential for `provider`, refreshing through the same
+     * pipeline as API-key resolution but returning the refreshed
+     * {@link OAuthAccess} (raw access token + identity metadata) instead of
+     * the API-key bytes.
+     *
+     * Use this when the caller needs to inject identity headers alongside the
+     * bearer (Codex `chatgpt-account-id`, Google `project`, GitHub
+     * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
+     * scenarios, prefer 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.
+     */
+    access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
+    /**
+     * Read-only list of stored OAuth accounts for `provider` in stable storage
+     * order, WITHOUT refreshing any token. The array position (0-based) is the
+     * selector displayed by a "pick the Nth account" UI as `position + 1`.
+     *
+     * When `sessionId` is supplied, the session-sticky OAuth credential is marked
+     * `active`. No account is active before that session has resolved or pinned a
+     * credential.
+     */
+    accounts(provider: string, sessionId?: string): OAuthAccountSummary[];
+    /**
+     * Resolve every stored OAuth credential for `provider` independently.
+     *
+     * Refreshes credentials through the same broker/local path as
+     * {@link OAuthAccounts.access}, but does not rank, round-robin, or
+     * stop after the first usable account. Intended for diagnostics that must
+     * exercise each stored account exactly once.
+     */
+    accessAll(provider: string, options?: AuthApiKeyOptions): Promise<OAuthAccessResolution[]>;
+    /**
+     * Resolve one stored OAuth credential by its durable storage row id.
+     *
+     * Unlike the normal session resolver, this method never ranks, rotates, or
+     * falls back to sibling credentials. A forced refresh re-mints only the
+     * requested row, preserving exact-account affinity for operations whose
+     * provenance and policy boundary are tied to one workspace.
+     *
+     * Returns `undefined` when the row does not exist for `provider` or an
+     * explicit runtime/config API-key override suppresses OAuth.
+     */
+    accessById(provider: string, credentialId: number, options?: AuthApiKeyOptions): Promise<OAuthAccessResolution | undefined>;
+    /**
+     * Get the OAuth account identity for a provider, preferring the credential that
+     * is session-sticky for `sessionId`. This is a read-only lookup for display and
+     * metadata paths; it does not refresh tokens, rank usage, or advance selection.
+     */
+    identity(provider: string, sessionId?: string): OAuthAccountIdentity | undefined;
+    /**
+     * Return the configured account policy matching an OAuth identity.
+     *
+     * This is a read-only diagnostics surface: it performs the same conjunctive
+     * selector match as routing and never refreshes, ranks, or mutates credentials.
+     */
+    policy(provider: string, identity: OAuthAccountIdentity): AuthAccountPolicy | undefined;
+    /** Force-refresh one stored credential by its durable row id. */
+    refresh(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry>;
+    /** Refresh one stored OAuth credential through the durable ownership path. */
+    refreshStored<T extends OAuthCredential = OAuthCredential>(provider: string, options: StoredOAuthRefreshOptions<T>): Promise<StoredOAuthRefreshResult<T>>;
+}

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

@@ -0,0 +1,27 @@
+import type { AuthAccountPolicies, AuthAccountPolicy, AuthAccountSelector, AuthCredential, OAuthAccountIdentity } from "./types.js";
+/** Whether every identity field set on `selector` matches `identity`. */
+export declare function matchesAuthAccountSelector(selector: AuthAccountSelector, identity: OAuthAccountIdentity): boolean;
+/** Validated per-account routing policies (priority/reserve) plus the global reserve fallback. */
+export declare class AccountPolicies {
+    #private;
+    constructor(policies: AuthAccountPolicies, defaultReservePct: number | undefined);
+    /** Global usage reserve (0–100) for accounts without a per-account `reservePct`. */
+    get defaultReservePct(): number;
+    /**
+     * Replace the policy set and global reserve in place (live settings change).
+     * Validates the configuration and every provider in `storedCredentials` before
+     * committing; on error the previous policies stay active.
+     */
+    replace(policies: AuthAccountPolicies, defaultReservePct: number | undefined, storedCredentials?: ReadonlyMap<string, readonly AuthCredential[]>): void;
+    validateUsageCapability(provider: string, canFetchUsage: boolean): void;
+    validateFor(provider: string, credentials: readonly AuthCredential[]): void;
+    /**
+     * Return the configured account policy matching an OAuth identity.
+     *
+     * This is a read-only diagnostics surface: it performs the same conjunctive
+     * selector match as routing and never refreshes, ranks, or mutates credentials.
+     */
+    find(provider: string, identity: OAuthAccountIdentity): AuthAccountPolicy | undefined;
+    /** Return the configured policy for a stored OAuth credential. */
+    forCredential(provider: string, credential: AuthCredential): AuthAccountPolicy | undefined;
+}