@oh-my-pi/pi-ai 18.2.11 → 18.3.0

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

@@ -0,0 +1,206 @@
+import type { BlockStoreHealth } from "./blocks.js";
+import type { AccountPolicies } from "./policy.js";
+import type { AuthCredentialStore } from "./store.js";
+import type { AuthCredential, AuthCredentialEntry, AuthCredentialSnapshot, AuthCredentialSnapshotEntry, AuthStorageData, CredentialDisabledEvent, CredentialsApi, DisabledCredentialSummary, OAuthCredential, StoredAuthCredential } from "./types.js";
+import type { UsageCredential } from "../usage.js";
+/** One stored credential row as cached in memory. */
+export type StoredCredential = {
+    id: number;
+    credential: AuthCredential;
+};
+/** Credential equality used for snapshot change detection. */
+export declare function authCredentialEquals(left: AuthCredential, right: AuthCredential): boolean;
+/** Dependencies for credential validation, corruption handling, and assignment reset. */
+export interface CredentialPoolOptions {
+    policies: AccountPolicies;
+    blockHealth: BlockStoreHealth;
+    /** Called whenever a provider's credential set changed locally. */
+    onReset: (provider: string) => void;
+}
+/** In-memory credential snapshot over an AuthCredentialStore: CRUD, change detection, events. */
+export declare class CredentialPool implements CredentialsApi {
+    #private;
+    constructor(store: AuthCredentialStore, options: CredentialPoolOptions);
+    get closed(): boolean;
+    get generation(): number;
+    providers(): IterableIterator<string>;
+    /** Reset session affinity and round-robin state after a local credential change. */
+    reset(provider: string): void;
+    /** Re-list one provider and adopt its persisted rows in memory. */
+    reloadProvider(provider: string): StoredAuthCredential[];
+    /** Persist a login-entered API key. */
+    storeLoginApiKey(provider: string, key: string): Promise<void>;
+    /**
+     * Close the underlying credential store.
+     *
+     * After calling this, the instance must not be reused.
+     */
+    close(): void;
+    /**
+     * Reload state after another process commits to the backing store, then
+     * notify snapshot consumers even when only credential blocks changed.
+     */
+    poll(): Promise<boolean>;
+    /**
+     * Adopt credentials another process committed before selecting or rotating.
+     *
+     * The store is shared across every omp process, but the pool is an
+     * in-process cache refreshed only by this process's own writes. Without
+     * this a long-running session ranks a stale pool for its whole lifetime:
+     * `omp auth` in another terminal is invisible, rotation reports no usable
+     * sibling while a freshly added account sits unblocked in SQLite, and the
+     * turn degrades to the fallback chain. The auth-broker path already polls;
+     * direct-store sessions had no equivalent.
+     *
+     * A poll is two cheap reads (`PRAGMA data_version` plus the auth revision)
+     * and re-lists credentials only when another connection committed, so it
+     * runs on every resolution rather than on a timer that would make recovery
+     * depend on wall-clock spacing. It sits on the paths that read the pool —
+     * OAuth selection, and the two public usage-limit entry points — and is
+     * idempotent, so a rotation reached through `markUsageLimitReached` costs
+     * one extra `data_version` read and no second reload.
+     */
+    adoptExternalChanges(): Promise<void>;
+    onGeneration(listener: (generation: number) => void): () => void;
+    bump(reason: string): void;
+    /**
+     * Subscribe to {@link CredentialDisabledEvent}s. Multiple subscribers are supported and
+     * each fires for every disable event; subscribers are invoked in registration order with
+     * exceptions and async rejections isolated per-listener so a misbehaving subscriber
+     * cannot break the disable path or starve the rest of the chain.
+     *
+     * If `credential_disabled` events were emitted while no listener was subscribed, they are
+     * replayed (in insertion order) to the listener that triggers the empty→non-empty
+     * transition. The drain is one-shot — listeners that subscribe after that no longer see
+     * past events.
+     *
+     * Returns an unsubscribe function. The function is idempotent: calling it more than once
+     * is a no-op. After every subscriber has unsubscribed, subsequent disable events buffer
+     * again until the next subscribe.
+     *
+     * @param listener Callback invoked with each disable event. May be sync or async.
+     * @returns A function that removes this listener from the subscriber set.
+     */
+    onDisabled(listener: (event: CredentialDisabledEvent) => void | Promise<void>): () => void;
+    /**
+     * Reload credentials from storage.
+     */
+    reload(): Promise<void>;
+    /**
+     * Gets cached credentials for a provider.
+     * @param provider - Provider name (e.g., "anthropic", "openai")
+     * @returns Array of stored credentials, empty if none exist
+     */
+    entries(provider: string): StoredCredential[];
+    /**
+     * Updates in-memory credential cache for a provider.
+     * Removes the provider entry entirely if credentials array is empty.
+     * @param provider - Provider name (e.g., "anthropic", "openai")
+     * @param credentials - Array of stored credentials to cache
+     */
+    replace(provider: string, credentials: StoredCredential[]): void;
+    noteBearer(provider: string, bearer: string, credentialId: number | undefined): void;
+    idForBearer(provider: string, bearer: string): number | undefined;
+    dedupe(provider: string, credentials: AuthCredential[]): AuthCredential[];
+    pruneDuplicates(provider: string, entries: StoredCredential[]): Promise<StoredCredential[]>;
+    /** Returns all credentials for a provider as an array. */
+    credentials(provider: string): AuthCredential[];
+    /**
+     * Persist a refreshed credential by id only while the row still matches this
+     * process's snapshot. A peer rotation wins the CAS and is reloaded instead of
+     * being overwritten after this process releases its refresh lease.
+     *
+     * Returns the row's current index, or -1 when it was disabled or removed.
+     */
+    replaceById(provider: string, id: number, credential: AuthCredential): number;
+    /**
+     * CAS-disable the row with `id`, but only if its persisted credential still
+     * matches `expected` — i.e. no peer/login rotated it while we refreshed.
+     * Addresses the row by id (re-resolved here, then matched on `data` in the
+     * store) so a concurrent reorder can't tear down the wrong credential.
+     */
+    disableIfMatches(provider: string, id: number, expected: AuthCredential, disabledCause: string): boolean;
+    emitDisabled(event: CredentialDisabledEvent): void;
+    /**
+     * Get credential for a provider (first entry if multiple).
+     */
+    get(provider: string): AuthCredential | undefined;
+    /**
+     * Set credential for a provider.
+     */
+    set(provider: string, credential: AuthCredentialEntry): Promise<void>;
+    /**
+     * List stored credential rows, optionally filtered by provider.
+     */
+    list(provider?: string): StoredAuthCredential[];
+    upsertOAuth(provider: string, credential: OAuthCredential): Promise<void>;
+    /**
+     * Remove credential for a provider.
+     */
+    remove(provider: string): Promise<void>;
+    /**
+     * Remove one stored credential for a provider.
+     */
+    removeById(provider: string, credentialId: number): Promise<boolean>;
+    /**
+     * Check if credentials exist for a provider in storage.
+     */
+    has(provider: string): boolean;
+    /**
+     * Check if OAuth credentials are configured for a provider.
+     */
+    hasOAuth(provider: string): boolean;
+    /**
+     * Get OAuth credentials for a provider.
+     */
+    getOAuth(provider: string): OAuthCredential | undefined;
+    /**
+     * Get all credentials.
+     */
+    all(): AuthStorageData;
+    /**
+     * Build a redacted snapshot of all loaded credentials for the auth-broker
+     * wire. OAuth refresh tokens are replaced with {@link REMOTE_REFRESH_SENTINEL}
+     * so clients never see the actual refresh token.
+     *
+     * Callers must {@link CredentialPool.reload} first when serving a stale snapshot
+     * (the broker server's HTTP handler does this).
+     */
+    snapshot(): AuthCredentialSnapshot;
+    /**
+     * Disabled credential tombstones for display surfaces (`omp usage`,
+     * broker `GET /v1/credentials/disabled`). Empty when the backing store
+     * keeps no tombstones or the remote broker predates the endpoint.
+     */
+    listDisabled(provider?: string, signal?: AbortSignal): Promise<DisabledCredentialSummary[]>;
+    /**
+     * Force the backing store to revalidate its credential snapshot, then
+     * reload. Remote broker stores re-fetch the snapshot; local stores are
+     * always current, so only the reload runs. Callers that pair live
+     * per-credential data with stored identities (`omp usage`) use this so a
+     * disk-cached snapshot cannot misattribute fresh reports.
+     */
+    revalidate(): Promise<void>;
+    /**
+     * Disable the credential with the given id and emit a
+     * {@link CredentialDisabledEvent}. Used by the auth-broker server to honour
+     * `POST /v1/credential/:id/disable`. Returns `false` when no such row exists.
+     */
+    disable(id: number, disabledCause: string): Promise<boolean>;
+    /**
+     * Upsert a credential into the underlying store, refresh the in-memory
+     * snapshot, and return the redacted snapshot entries for the provider.
+     *
+     * Used by the auth-broker server to honour `POST /v1/credential`. The
+     * persistence layer (`SqliteAuthCredentialStore.upsertAuthCredential`)
+     * does identity-key matching, so re-uploading the same email/account replaces
+     * the existing row instead of inserting a duplicate.
+     */
+    upsert(provider: string, credential: AuthCredential): Promise<AuthCredentialSnapshotEntry[]>;
+    /**
+     * Find the stored credential id matching a {@link UsageCredential} so the
+     * refresh override can address the row. Mirrors the matching logic in
+     * `UsageService.persistRefreshedCredential`.
+     */
+    findIdForUsageCredential(provider: string, previous: UsageCredential): number | undefined;
+}

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

@@ -0,0 +1,53 @@
+import type { PlanGate, UsageReport } from "../usage.js";
+import type { AuthCredential, ApiKeyCredential, OAuthCredential } from "./types.js";
+/** Selected stored credential and its pool index. */
+export type CredentialSelection<T extends AuthCredential> = {
+    credential: T;
+    index: number;
+};
+/** Selected OAuth credential for routing. */
+export type OAuthSelection = CredentialSelection<OAuthCredential>;
+/** Selected API-key credential for routing. */
+export type ApiKeySelection = CredentialSelection<ApiKeyCredential>;
+/** Selected credential with its observed usage. */
+export type UsageCandidate<T extends AuthCredential> = {
+    selection: CredentialSelection<T>;
+    usage: UsageReport | null;
+    usageChecked: boolean;
+    /** Present after policy-aware ranking; used to decide whether a warm automatic pin may be evicted. */
+    inReserve?: boolean;
+    /** True only when reserve ranking had a usable remaining-fraction measurement. */
+    reserveMeasured?: boolean;
+};
+/** OAuth credential eligible for usage ranking. */
+export type OAuthCandidate = UsageCandidate<OAuthCredential>;
+/** API-key credential eligible for usage ranking. */
+export type ApiKeyCandidate = UsageCandidate<ApiKeyCredential>;
+/** Ranked candidate with a possible block deadline. */
+export type UsageRankingResult<T extends AuthCredential> = UsageCandidate<T> & {
+    blockedUntil: number | undefined;
+};
+/** Candidate with all account-policy and usage ranking metrics. */
+export type UsageRankedCandidate<T extends AuthCredential> = UsageCandidate<T> & {
+    blocked: boolean;
+    blockedUntil?: number;
+    inReserve: boolean;
+    reserveMeasured?: boolean;
+    accountPriority: number;
+    hasPriorityBoost: boolean;
+    usageMeasured: boolean;
+    planPriority: number;
+    secondaryUsed: number;
+    secondaryRequiredDrain: number;
+    primaryUsed: number;
+    primaryRequiredDrain: number;
+    orderPos: number;
+};
+/** OAuth candidate with complete ranking metrics. */
+export type RankedOAuthCandidate = UsageRankedCandidate<OAuthCredential>;
+/** API-key candidate with complete ranking metrics. */
+export type RankedApiKeyCandidate = UsageRankedCandidate<ApiKeyCredential>;
+/** Rank accounts by model-plan eligibility when a plan gate applies. */
+export declare function planPriority(gate: PlanGate | undefined, report: UsageReport | null): number;
+/** Sort ranked candidates by blocks, plan, reserve, boost, hot window, usage and drain. */
+export declare function orderUsageRankedCandidates<T extends AuthCredential>(candidates: UsageRankedCandidate<T>[], planGated: boolean): UsageCandidate<T>[];

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

@@ -0,0 +1,59 @@
+import type { OAuthCredentials } from "../registry/oauth/types.js";
+import type { Provider } from "../types.js";
+import { type CredentialPool } from "./pool.js";
+import type { AccountPolicies } from "./policy.js";
+import { type AuthCredentialStore } from "./store.js";
+import { type AuthCredentialSnapshotEntry, type AuthStorageOptions, type OAuthCredential, type StoredOAuthRefreshOptions, type StoredOAuthRefreshResult } from "./types.js";
+/**
+ * Refresh OAuth access tokens this many ms before their stated expiry. The
+ * skew exists so callers downstream of {@link OAuthRefresher} (stream providers,
+ * usage probes, web_search) never observe a credential that is expired or
+ * about to expire mid-request — there's a single rotation point and everyone
+ * downstream trusts the token they receive.
+ *
+ * Set to 60s: comfortably absorbs request RTT + a clock-skew window without
+ * triggering a refresh on every request. Provider token endpoints typically
+ * mint access tokens with 30-60min lifetimes, so refreshing 60s early changes
+ * the rotation cadence by <4%.
+ */
+export declare const OAUTH_REFRESH_SKEW_MS = 60000;
+/** Merge provider refresh bytes with the stored OAuth row, preserving subtype metadata for every refresh path. */
+export declare function mergeRefreshedCredential<T extends OAuthCredential>(current: T, refreshed: OAuthCredentials): T;
+/** Dependencies for lease-guarded OAuth refresh. */
+export interface OAuthRefresherDeps {
+    store: AuthCredentialStore;
+    pool: CredentialPool;
+    policies: AccountPolicies;
+    override?: AuthStorageOptions["refreshOAuthCredential"];
+}
+/** Single-flighted, lease-guarded OAuth refresh with compare-and-set persistence. */
+export declare class OAuthRefresher {
+    #private;
+    constructor(deps: OAuthRefresherDeps);
+    /**
+     * Refresh one stored OAuth credential under durable row ownership.
+     */
+    refreshStored<T extends OAuthCredential = OAuthCredential>(provider: string, options: StoredOAuthRefreshOptions<T>): Promise<StoredOAuthRefreshResult<T>>;
+    /**
+     * Handles a definitively-dead OAuth grant discovered during refresh (`invalid_grant`,
+     * `revoked`, …): checks for a peer rotation that raced the failure, then CAS-disables
+     * the row and emits `credential_disabled`. Shared by the eager preflight refresh
+     * and the final-candidate refresh so both actually disable the credential — not
+     * just temporarily block it — on a definitive failure.
+     *
+     * Returns `"disabled"` once the row is torn down, `"peer-rotated"` when a concurrent
+     * process refreshed the same row first (the persisted refresh token no longer matches
+     * what we attempted — the caller should reload and retry with the new credential), or
+     * `"cas-lost"` when the disable itself lost a race and the caller should reload before
+     * continuing.
+     */
+    disableDefinitiveFailure(provider: string, credentialId: number | undefined, attemptedCredential: OAuthCredential, index: number, errorMsg: string): Promise<"disabled" | "peer-rotated" | "cas-lost">;
+    refresh(provider: Provider, credential: OAuthCredential, credentialId: number | undefined, signal?: AbortSignal): Promise<OAuthCredentials>;
+    /**
+     * Refresh the OAuth credential with the given id through a per-credential
+     * single-flight. Concurrent callers for the same row await the same upstream
+     * refresh attempt, which is required for providers that rotate refresh tokens
+     * on every successful refresh.
+     */
+    refreshById(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
+}

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

@@ -0,0 +1,28 @@
+import type { CredentialBlocks } from "./blocks.js";
+import type { OAuthAccounts } from "./oauth.js";
+import type { CredentialPool } from "./pool.js";
+import type { AuthCredentialStore } from "./store.js";
+import type { ListResetCreditsOptions, RedeemResetCreditOptions, ResetCreditAccountStatus, ResetCreditRedeemOutcome, ResetsApi } from "./types.js";
+import type { UsageService } from "./usage.js";
+import type { UsageCache } from "./usage-cache.js";
+/** Dependencies for listing and redeeming stored-account reset credits. */
+export interface ResetCreditsDeps {
+    store: AuthCredentialStore;
+    pool: CredentialPool;
+    oauth: OAuthAccounts;
+    usage: UsageService;
+    usageCache: UsageCache;
+    blocks: CredentialBlocks;
+}
+/** Saved rate-limit resets (Codex / Claude): list offers and redeem one per account. */
+export declare class ResetCredits implements ResetsApi {
+    #private;
+    constructor(deps: ResetCreditsDeps);
+    /** List live saved-reset balances and eligibility for one provider's stored OAuth accounts. */
+    list(options?: ListResetCreditsOptions): Promise<ResetCreditAccountStatus[]>;
+    /**
+     * Redeem a stored account's saved reset after checking its live offer.
+     * Business refusals return a code; transport errors may throw without losing Claude's request ID.
+     */
+    redeem(options: RedeemResetCreditOptions): Promise<ResetCreditRedeemOutcome>;
+}

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

@@ -0,0 +1,66 @@
+import type { CredentialRankingContext, CredentialRankingStrategy } from "../usage.js";
+import type { RankingStrategyResolver } from "../usage/registry.js";
+import type { CredentialBlocks } from "./blocks.js";
+import type { KeyOverrides } from "./cascade.js";
+import type { SessionAffinity } from "./affinity.js";
+import type { CredentialPool } from "./pool.js";
+import type { AuthCredentialStore } from "./store.js";
+import type { InvalidateCredentialMatchingOptions, LimitsApi, MarkUsageLimitOptions, RotateCredentialOptions, UsageLimitMarkResult } from "./types.js";
+import type { UsageService } from "./usage.js";
+/** Routing scope and strategy for one failed credential. */
+export type CredentialBlockRouting = {
+    providerKey: string;
+    strategy: CredentialRankingStrategy | undefined;
+    rankingContext: CredentialRankingContext;
+    blockScope: string | undefined;
+    siblingBlockScopes: readonly string[];
+};
+/** Dependencies for rate-limit marking and credential rotation. */
+export interface RateLimitsDeps {
+    store: AuthCredentialStore;
+    pool: CredentialPool;
+    overrides: KeyOverrides;
+    blocks: CredentialBlocks;
+    affinity: SessionAffinity;
+    usage: UsageService;
+    strategies: RankingStrategyResolver;
+}
+/** Usage-limit marking, credential rotation after failures, and bearer-matched invalidation. */
+export declare class RateLimits implements LimitsApi {
+    #private;
+    constructor(deps: RateLimitsDeps);
+    /**
+     * Marks the current session's credential as temporarily blocked due to usage limits.
+     * Uses usage reports to determine accurate reset time when available.
+     * Returns whether a sibling credential is available now; when none is, also
+     * reports the earliest time a blocked sibling becomes available again so
+     * callers can wait for the sibling instead of the provider's full window.
+     */
+    markReached(provider: string, sessionId: string | undefined, options?: MarkUsageLimitOptions): Promise<UsageLimitMarkResult>;
+    invalidateMatching(provider: string, apiKey: string, options?: InvalidateCredentialMatchingOptions): Promise<boolean>;
+    /**
+     * Rotate away from the credential that failed after a retryable auth error —
+     * step (c) of the auth-retry policy. Prefer the failed stored row id supplied
+     * in `options.credentialId`, then the failed bearer supplied in
+     * `options.apiKey`, so overlapping requests cannot redirect rotation through
+     * stale session stickiness. Fall back to the session-sticky credential only
+     * when neither explicit target is available. For hard-auth errors, an explicit
+     * target that no longer matches storage returns `false` without mutation.
+     * Delayed usage-limit and account-policy errors may instead recover the durable
+     * OAuth row from the bearer fingerprint recorded when the request resolved.
+     *
+     * - usage-limit / account-rate-limit error → {@link RateLimits.markReached}
+     *   (temporary block via its own backoff — default plus server usage-report
+     *   reset; sticky left intact so the next resolve re-ranks around the block).
+     * - exact model-entitlement denial (Codex ChatGPT account or Cursor plan) →
+     *   temporarily block only that requested model, then rotate.
+     * - other account-scoped policy denial → temporarily block that account
+     *   without marking its credential suspect, then rotate through siblings.
+     * - otherwise (hard 401 / auth failure) → mark the credential suspect (or
+     *   reload when no broker hook is wired) and block it, then drop matching
+     *   sticky state.
+     *
+     * Returns whether another usable credential of the same type remains.
+     */
+    rotate(provider: string, sessionId: string | undefined, options?: RotateCredentialOptions): Promise<boolean>;
+}

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

@@ -0,0 +1,86 @@
+import type { Provider } from "../types.js";
+import type { CredentialRankingContext, CredentialRankingStrategy, PlanGate, UsageReport } from "../usage.js";
+import type { RankingStrategyResolver } from "../usage/registry.js";
+import type { SessionAffinity } from "./affinity.js";
+import { type CredentialBlocks } from "./blocks.js";
+import type { AccountPolicies } from "./policy.js";
+import { type CredentialPool } from "./pool.js";
+import { type ApiKeySelection, type OAuthSelection } from "./rank.js";
+import { type OAuthRefresher } from "./refresh.js";
+import type { AuthCredentialStore } from "./store.js";
+import type { ApiKeyCredential, AuthApiKeyOptions, AuthCredential, OAuthCredential } from "./types.js";
+import type { UsageService } from "./usage.js";
+/** Temporary block after a transient OAuth refresh failure. */
+export declare const OAUTH_REFRESH_FAILURE_BACKOFF_MS: number;
+/** OAuth bearer and credential chosen for a request, with its durable row id when available. */
+export type OAuthResolutionResult = {
+    apiKey: string;
+    credential: OAuthCredential;
+    credentialId?: number;
+};
+/** Options for CredentialSelector.tryOAuth when evaluating one OAuth credential. */
+export type TryOAuthOptions = {
+    checkUsage: boolean;
+    allowBlocked: boolean;
+    prefetchedUsage?: UsageReport | null;
+    usagePrechecked?: boolean;
+    planGate?: PlanGate;
+    enforcePlanRequirement?: boolean;
+    strategy?: CredentialRankingStrategy;
+    rankingContext?: CredentialRankingContext;
+    blockScope?: string;
+    blockScopes?: readonly string[];
+    /** When false, a definitive failure of THIS credential returns undefined instead of falling back to the ranked/round-robin selector (target-only resolution). */
+    allowFallback?: boolean;
+};
+/** Services consulted by CredentialSelector for policy, usage, blocks, refresh, and session affinity. */
+export interface CredentialSelectorDeps {
+    store: AuthCredentialStore;
+    pool: CredentialPool;
+    policies: AccountPolicies;
+    blocks: CredentialBlocks;
+    affinity: SessionAffinity;
+    usage: UsageService;
+    refresher: OAuthRefresher;
+    strategies: RankingStrategyResolver;
+}
+/** Picks which stored credential serves a request: ordering, usage ranking, OAuth refresh ladder. */
+export declare class CredentialSelector {
+    #private;
+    constructor(deps: CredentialSelectorDeps);
+    /** Restart round-robin assignments after a provider's credential set changes. */
+    resetRoundRobin(provider: string): void;
+    /**
+     * Selects a credential of the specified type for a provider.
+     * Returns both the credential and its index in the original array (for updates/removal).
+     * Uses deterministic hashing for session stickiness and skips blocked credentials when possible.
+     */
+    selectByType<T extends AuthCredential["type"]>(provider: string, type: T, sessionId?: string, filter?: (credential: AuthCredential) => boolean): {
+        credential: Extract<AuthCredential, {
+            type: T;
+        }>;
+        index: number;
+    } | undefined;
+    selectApiKey(provider: string, sessionId: string | undefined, options: AuthApiKeyOptions | undefined, filter?: (credential: ApiKeyCredential) => boolean): Promise<ApiKeySelection | undefined>;
+    /**
+     * Resolves an OAuth credential, trying credentials in priority order.
+     *
+     * Resolution ladder — a request in hand always beats "no API key":
+     * 1. strict: unblocked credentials only, usage limits respected, plan
+     *    filter enforced (when any account is confirmed eligible);
+     * 2. plan-fitting last resort: same plan filter, but blocked/exhausted
+     *    accounts are allowed (blocked candidates rank earliest-unblocking
+     *    first) so the caller gets real usage-limit semantics from the wire
+     *    instead of a missing key;
+     * 3. unfiltered last resort: the plan filter matched nothing usable —
+     *    skip it and try every account once; the server is the final arbiter
+     *    of model access.
+     *
+     * Returns both the API key bytes for outbound requests AND the refreshed
+     * {@link OAuthCredential} so callers needing identity metadata (account id,
+     * project id, etc.) do not have to dereference the snapshot themselves.
+     */
+    resolveOAuth(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthResolutionResult | undefined>;
+    /** Attempts to use a single OAuth credential, checking usage and refreshing token. */
+    tryOAuth(provider: Provider, selection: OAuthSelection, providerKey: string, sessionId: string | undefined, options: AuthApiKeyOptions | undefined, usageOptions: TryOAuthOptions): Promise<OAuthResolutionResult | undefined>;
+}

package/dist/types/auth/sqlite-credential-store.d.ts

@@ -1,12 +1,13 @@
 /**
  * SQLite-backed credential persistence for AuthStorage.
  *
- * The public AuthCredentialStore interface remains in ../auth-storage so local
- * and remote stores share the same contract.
+ * The AuthCredentialStore contract lives in ./store so local and remote stores
+ * share the same interface.
  */
 import type { Database } from "bun:sqlite";
 import { isSqliteBusyError, isSqliteCorruptionError } from "@oh-my-pi/pi-utils";
-import type { AuthCredential, AuthCredentialStore, CredentialRefreshLeaseFence, DisabledCredentialSummary, StoredAuthCredential, StoredCredentialBlock } from "../auth-storage.js";
+import type { AuthCredentialStore, CredentialRefreshLeaseFence } from "./store.js";
+import type { AuthCredential, DisabledCredentialSummary, StoredAuthCredential, StoredCredentialBlock } from "./types.js";
 import type { OAuthCredentials } from "../registry/oauth/types.js";
 import type { ClientUsageReport, ClientUsageSummary, UsageHistoryEntry, UsageHistoryQuery } from "../usage.js";
 export declare const USAGE_REPORT_TTL_MS: number;
@@ -33,11 +34,11 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     static open(dbPath?: string): Promise<SqliteAuthCredentialStore>;
     listAuthCredentials(provider?: string): StoredAuthCredential[];
     listDisabledCredentials(provider?: string): Promise<DisabledCredentialSummary[]>;
-    replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
-    upsertAuthCredentialForProvider(provider: string, credential: AuthCredential): StoredAuthCredential[];
+    replaceAuthCredentials(provider: string, credentials: AuthCredential[]): Promise<StoredAuthCredential[]>;
+    upsertAuthCredential(provider: string, credential: AuthCredential): Promise<StoredAuthCredential[]>;
     updateAuthCredential(id: number, credential: AuthCredential): void;
     tryUpdateAuthCredentialIfMatches(id: number, expectedData: string, credential: AuthCredential, lease?: CredentialRefreshLeaseFence): boolean;
-    deleteAuthCredential(id: number, disabledCause: string): void;
+    deleteAuthCredential(id: number, disabledCause: string): Promise<boolean>;
     /**
      * CAS-style disable: only soft-deletes the row when its `data` column still
      * matches `expectedData` and the row has not already been disabled. Used by
@@ -45,7 +46,7 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
      * row between our pre-check and the disable.
      */
     tryDisableAuthCredentialIfMatches(id: number, expectedData: string, disabledCause: string, lease?: CredentialRefreshLeaseFence): boolean;
-    deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void;
+    deleteAuthCredentials(provider: string, disabledCause: string): Promise<void>;
     getCache(key: string, options?: {
         includeExpired?: boolean;
     }): string | null;
@@ -72,7 +73,7 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
      * Save OAuth credentials for a provider.
      * Preserves unrelated identities and replaces only the matching credential.
      */
-    saveOAuth(provider: string, credentials: OAuthCredentials): void;
+    saveOAuth(provider: string, credentials: OAuthCredentials): Promise<void>;
     /**
      * Get OAuth credentials for a provider.
      */
@@ -80,7 +81,7 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     /**
      * Save API key for a provider (replaces existing).
      */
-    saveApiKey(provider: string, apiKey: string): void;
+    saveApiKey(provider: string, apiKey: string): Promise<void>;
     /**
      * Get API key for a provider.
      */
@@ -92,7 +93,7 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     /**
      * Delete all credentials for a provider.
      */
-    deleteProvider(provider: string): void;
+    deleteProvider(provider: string): Promise<void>;
     /**
      * SQLite increments `data_version` when another connection commits. Own
      * writes leave it unchanged and already notify AuthStorage directly.