@linxiraos/pi-ai 1.1.26 → 1.2.0

package/CHANGELOG.md

@@ -1,15 +1,16 @@
-# Changelog
-
 ## [Unreleased]
 
-## [1.1.26] - 2026-10-03
-
-- 版本线推进至 1.1.26；本版无独立用户可见变化。
-
-## [1.1.25] - 2026-10-03
+## [1.2.0] - 2026-10-12
 
-- 版本线推进至 1.1.25；本版无独立用户可见变化。
+- 版本线推进至 1.2.0；本版无独立用户可见变化。
 
 ## [1.1.24] - 2026-10-03
 
 - 网关身份头统一 `x-zeta-*`（消费方同步）；新增 `extractHttpStatusFromError`/`extractRetryHint` 导出。
+
+### Fixed
+
+- Fixed Antigravity chat and image requests sending an outdated client version when the model list came from cache, which could make newer models such as Claude Opus 5.5 unavailable.
+- When a DeepSeek model writes a broken DSML tool call (for example with the opening `<｜DSML｜tool_calls>` and `<｜DSML｜invoke>` tags missing), its closing tags are now kept in the streamed text instead of being dropped. This lets the agent remove exactly the broken call while keeping any text after it ([#14202](https://github.com/can1357/oh-my-pi/pull/14202) by [@H4vC](https://github.com/H4vC)).
+
+Older entries are archived in [packages/ai/CHANGELOG.md@a20cc0d04b64](https://github.com/can1357/oh-my-pi/blob/a20cc0d04b64f4a68fcc559cbd258743d984c50e/packages/ai/CHANGELOG.md).

package/README.md

@@ -77,6 +77,7 @@ Unified LLM API with automatic model discovery, provider configuration, token an
 - **QwenCloud Token Plan** (supports `/login alibaba-token-plan`, `ALIBABA_TOKEN_PLAN_API_KEY`, or `BAILIAN_TOKEN_PLAN_API_KEY`; interactive login first selects a region — International (Singapore, default), China (Beijing) for 百炼 Token Plan keys, or a custom base URL — since region keys are non-interchangeable, then optionally stores a `home.qwencloud.com` Cookie request header for best-effort 5-hour and 7-day quota reporting)
   To enable quota reporting, sign in to the Token Plan dashboard, copy the `Cookie` request-header value from a `home.qwencloud.com` request in browser developer tools, and paste it at the second login prompt. Press Enter to skip; the Cookie is sensitive and session-lived, so rerun login when it expires.
 - **Cloudflare AI Gateway** (supports `/login cloudflare-ai-gateway`, or `CLOUDFLARE_AI_GATEWAY_API_KEY` with `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_GATEWAY_ID`)
+- **Snowflake Cortex** (browser `/login snowflake`, or `SNOWFLAKE_ACCOUNT` + `SNOWFLAKE_PAT`; account-billed Cortex REST API)
 - **Ollama** (local OpenAI-compatible runtime; optional `OLLAMA_API_KEY`)
 - **Ollama Cloud** (hosted native Ollama API; requires `OLLAMA_CLOUD_API_KEY`)
 - **llama.cpp** (local OpenAI and Anthropic compatible inference server)
@@ -961,6 +962,7 @@ In Node.js environments, you can set environment variables to avoid passing API
 | ZenMux                | `ZENMUX_API_KEY`                                                                                                    |
 | vLLM                  | `VLLM_API_KEY`                                                                                                      |
 | Cloudflare AI Gateway | `CLOUDFLARE_AI_GATEWAY_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_GATEWAY_ID`                                 |
+| Snowflake Cortex      | `SNOWFLAKE_PAT` + `SNOWFLAKE_ACCOUNT`                                                                               |
 | GitHub Copilot        | `COPILOT_GITHUB_TOKEN` or `GH_TOKEN` or `GITHUB_TOKEN`                                                              |
 
 `/login cloudflare-ai-gateway` collects and stores the gateway token, account ID, and gateway ID. For environment configuration, set all three Cloudflare values above. OMP derives provider endpoints from the account and gateway IDs.
@@ -1029,9 +1031,22 @@ Several providers support OAuth authentication (some also support static API key
 - **Google Gemini CLI** (Gemini 2.0/2.5 via Google Cloud Code Assist; free tier or paid subscription)
 - **Antigravity** (Free Gemini 3, Claude, GPT-OSS via Google Cloud)
 - **Qwen Portal** (Qwen OAuth token or API key)
+- **Snowflake Cortex** (Snowflake account OAuth with PKCE and refresh, subject to the account's local-application integration)
 
 For paid Cloud Code Assist subscriptions, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` to your project ID.
 
+### Snowflake Cortex
+
+`/login snowflake` prompts for an account identifier (for example, `myorg-myaccount`), an HTTPS Snowflake account URL, or a Snowsight account link. It opens Snowflake's built-in `SNOWFLAKE$LOCAL_APPLICATION` OAuth flow using PKCE and a `127.0.0.1` callback (port 54551, with an ephemeral-port fallback). The stored account selects the inference endpoint; OAuth credentials cannot be sent to a different account through a custom model endpoint.
+
+The default inference role must hold either `SNOWFLAKE.CORTEX_USER` or the narrower, REST-only `SNOWFLAKE.CORTEX_REST_API_USER` (recommended for least privilege). `CORTEX_REST_API_USER` cannot be granted to a user directly; grant it to a custom role, and revoke `CORTEX_USER` from users who already hold it so the narrower control applies. The Cortex REST API is not available in China-region (`.snowflakecomputing.cn`) accounts. An administrator can check local-app availability with `SHOW SECURITY INTEGRATIONS LIKE 'SNOWFLAKE$LOCAL_APPLICATION'` and enable the integration or refresh issuance if necessary. When Snowflake issues a refresh token, omp refreshes the access token automatically. Without one, login remains valid until expiry; then sign in again or use the PAT environment alternative.
+
+For PAT authentication, set both `SNOWFLAKE_ACCOUNT` and `SNOWFLAKE_PAT`. Prefer a short-lived PAT restricted to a dedicated inference role and the required user-scoped network allowlist; do not disable network-policy enforcement. See [Snowflake PAT setup](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) and [local-application OAuth](https://docs.snowflake.com/en/user-guide/oauth-local-applications).
+
+Claude models use `/api/v2/cortex/v1/messages`; OpenAI models use `/api/v2/cortex/v1/chat/completions`. Both reuse omp's streaming transports and local tool execution. The 15 bundled models are a documented roster, not an account entitlement check: availability still depends on Cortex REST API enablement, role grants, model allowlists, and region. If authentication succeeds but Cortex returns `003001` ("This account is not allowed to access this endpoint"), Snowflake has not enabled Cortex REST for the account. [Self-service trial accounts disable AI features until a credit card is added](https://docs.snowflake.com/en/user-guide/admin-trial-account#label-trial-account-ai-features) (adding one does not end the trial); REST access can remain disabled even after AI SQL functions work, in which case Snowflake support must enable it. Cross-region inference requires an account administrator's explicit decision. `zetacode models snowflake --json` lists available models only after credentials are configured.
+
+This provider uses the [public, account-billed Cortex REST API](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-rest-api). CoCo-subscription coverage is unverified. Catalog prices are per-million-token estimates from [Consumption Table 6(b)](https://www.snowflake.com/legal-files/CreditConsumptionTable.pdf) at [$2 per AI Credit](https://docs.snowflake.com/en/user-guide/snowflake-cortex/pricing) for on-demand global routing, not your contract price. Output is capped at the REST API's documented 16,384-token maximum; context windows are conservative AI_COMPLETE limits, not verified REST maxima. Cortex compatibility rules limit explicit cache retention to five minutes. Paste an account identifier or current Snowsight link; legacy `app.snowflake.com/<region>/<locator>` links are rejected because they don't map uniformly to an account host.
+
 ### Vertex AI (ADC)
 
 Vertex AI models use Application Default Credentials (ADC):

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

@@ -1,4 +1,4 @@
-import type { AuthCredential, OAuthCredential, SessionsApi } from "./types.js";
+import type { AuthCredential, OAuthCredential, SessionRestrictionLease, SessionsApi } from "./types.js";
 import type { AuthCredentialStore } from "./store.js";
 import type { CredentialPool } from "./pool.js";
 import type { KeyOverrides } from "./cascade.js";
@@ -13,10 +13,31 @@ export type SessionCredential = {
     /** Set only by the public user-facing pin API; automatic warm affinity leaves it absent. */
     explicit?: true;
 };
+/** One installed restriction: the allowed OAuth identity keys and the lease that lifts it. */
+type SessionRestriction = {
+    readonly allowed: ReadonlySet<string>;
+    readonly lease: SessionRestrictionLease;
+};
+/**
+ * Provider → session id → installed restriction. Owned by `AuthStorage` so
+ * restrictions outlive store replacement, which rebuilds every store-bound
+ * module (pins included) around the same identities.
+ */
+export type SessionRestrictions = Map<string, Map<string, SessionRestriction>>;
 /** Session → credential affinity (pins), persisted in the store cache. */
 export declare class SessionAffinity implements SessionsApi {
     #private;
-    constructor(store: AuthCredentialStore, pool: CredentialPool, overrides: KeyOverrides);
+    constructor(store: AuthCredentialStore, pool: CredentialPool, overrides: KeyOverrides, restrictions: SessionRestrictions);
+    restrict(provider: string, sessionId: string, identityKeys: readonly string[]): SessionRestrictionLease;
+    unrestrict(provider: string, sessionId: string, lease: SessionRestrictionLease): void;
+    /** True when {@link restrict} limits `sessionId` for `provider`. */
+    isRestricted(provider: string, sessionId: string | undefined): boolean;
+    /**
+     * True when `credential` may serve `sessionId`: always for an unrestricted
+     * session, otherwise only an OAuth credential whose identity key is allowed.
+     */
+    allows(provider: string, sessionId: string | undefined, credential: AuthCredential): boolean;
+    permits(provider: string, sessionId: string, credentialId: number): boolean;
     /** 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. */
@@ -33,7 +54,11 @@ export declare class SessionAffinity implements SessionsApi {
      * rewrites were pure database churn.
      */
     record(provider: string, sessionId: string | undefined, type: AuthCredential["type"], index: number, lastUsedAtMs?: number, explicit?: boolean): void;
-    /** Retrieves the last credential used by a session. */
+    /**
+     * Retrieves the last credential used by a session. A restricted session
+     * never sees a pin outside its allowlist — inherited, restored, or recorded
+     * before the restriction — so it re-ranks inside the allowlist instead.
+     */
     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;
@@ -55,14 +80,15 @@ export declare class SessionAffinity implements SessionsApi {
         restoredAtMs?: number;
     }): boolean;
     /**
-     * Copy every stored credential affinity from one live session to another.
+     * Copy stored credential affinities 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.
+     * source session. `include` limits the copy to the providers it accepts,
+     * given whether the source's affinity is an explicit user pin.
      */
-    inherit(sourceSessionId: string, targetSessionId: string): number;
+    inherit(sourceSessionId: string, targetSessionId: string, include?: (provider: string, explicit: boolean) => boolean): 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
@@ -71,3 +97,4 @@ export declare class SessionAffinity implements SessionsApi {
      */
     release(provider: string, sessionId: string): boolean;
 }
+export {};

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

@@ -2,16 +2,31 @@ import { type ApiKeyResolver, type ResolvedApiKey } from "../auth-retry.js";
 import type { SessionAffinity } from "./affinity.js";
 import type { CredentialPool } from "./pool.js";
 import type { CredentialSelector } from "./select.js";
-import type { AuthApiKeyOptions, AuthCredential, AuthSource, AuthSourceOptions, KeysApi, LimitsApi, OAuthRequestIdentity } from "./types.js";
+import type { AuthApiKeyOptions, AuthCredential, AuthSource, AuthSourceOptions, KeysApi, LimitsApi } from "./types.js";
 /** Runtime (--api-key) and config (models.yml) key overrides plus the config-value resolver. */
 export declare class KeyOverrides {
     #private;
     constructor(resolver?: (config: string) => Promise<string | undefined>);
     has(provider: string): boolean;
+    /**
+     * Whether an override replaces OAuth for a session. Any override does for an
+     * unrestricted session. A restricted session skips the runtime key, but a
+     * config key still blocks OAuth: it marks the provider's endpoint (often a
+     * proxy) as taking that key, so the session fails closed instead of sending
+     * a pooled OAuth token there (see `KeyCascade.get`).
+     */
+    suppressesOAuth(provider: string, restricted: boolean): boolean;
     runtimeKey(provider: string): string | undefined;
     configKey(provider: string): string | undefined;
     /** Config value consulted only after stored OAuth/login credentials. */
     fallbackKey(provider: string): string | undefined;
+    /**
+     * Config value consulted only after every other source, including stored
+     * api_key credentials — the lowest cascade tier. The OMP compatibility
+     * overlay uses it so an upstream key is a pure fallback: any credential
+     * the user later stores locally wins without needing to evict the mirror.
+     */
+    mirrorKey(provider: string): string | undefined;
     /** Resolve a config value (env var name, "!command", literal) to the secret. */
     resolve(config: string): Promise<string | undefined>;
     /**
@@ -37,12 +52,17 @@ export declare class KeyOverrides {
      * credentials (at the env-var tier). Providers that own a `/login` flow use
      * this so their default key reference (e.g. an unset env-var name, which
      * resolves to its literal text) cannot shadow the key the user logged in with.
+     *
+     * `mirror: true` ranks the value below everything else, under stored
+     * api_key credentials — a read-only compatibility mirror (upstream OMP
+     * agent.db key) that must never shadow a key the user stores locally.
      */
     setConfig(provider: string, apiKeyConfig: string, options?: {
         fallback?: boolean;
+        mirror?: boolean;
     }): void;
     /**
-     * Remove a single config-sourced API key (override or fallback).
+     * Remove a single config-sourced API key (override, fallback, or mirror).
      */
     removeConfig(provider: string): void;
     /**
@@ -68,7 +88,7 @@ export interface KeyCascadeDeps {
     rotate: LimitsApi["rotate"];
     sourceLabel?: string;
 }
-/** The provider auth precedence cascade (runtime → config → OAuth → login key → env → stored key). */
+/** The provider auth precedence cascade (runtime → config → OAuth → login key → env → stored key → compat mirror). */
 export declare class KeyCascade implements KeysApi {
     #private;
     constructor(deps: KeyCascadeDeps);
@@ -94,8 +114,8 @@ export declare class KeyCascade implements KeysApi {
     /**
      * 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 → config fallback → env var → stored api_key.
-     * Returns undefined when no auth is configured.
+     * stored OAuth → login-stored api_key → config fallback → env var →
+     * stored api_key → compat mirror. Returns undefined when no auth is configured.
      *
      * Compact, structured counterpart to {@link KeyCascade.describe}; `env`
      * selects dedicated-only, alias-aware, or no environment fallback.
@@ -109,14 +129,29 @@ export declare class KeyCascade implements KeysApi {
      * credential to reach the correct host.
      */
     peek(provider: string): Promise<string | undefined>;
-    /** Resolve a bearer together with the stored row that supplied it. */
+    /**
+     * Resolve a bearer together with the stored row that supplied it, for a request.
+     * Same precedence as {@link KeyCascade.get}, but rejects with
+     * {@link AIError.OAuthRefreshUnavailableError} (transient, retryable) when OAuth
+     * refresh failed with a retryable error and no other permitted source could serve
+     * the request, so request paths retry instead of reporting a missing key.
+     */
     getWithCredential(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<ResolvedApiKey | undefined>;
     /**
      * Get API key for a provider.
      * Priority (first match wins): runtime override, config override, OAuth,
+     * login API key, environment variable, another stored API key, then the
+     * lowest-tier OMP compat mirror.
      * login API key, environment variable, then another stored API key.
+     * A session restricted by `sessions.restrict` resolves only its allowed
+     * OAuth accounts and throws {@link AIError.MissingApiKeyError} when none
+     * can serve or a config key (a models.yml `apiKey`, often for a proxy
+     * `baseUrl`) owns the provider, rather than using any other credential.
+     * A transient OAuth refresh failure resolves `undefined`, so availability
+     * probes move on to their next candidate; request paths use
+     * {@link KeyCascade.getWithCredential}, which surfaces it.
      */
-    get(provider: string, sessionId?: string, options?: AuthApiKeyOptions, onCredentialId?: (id: number, identity?: OAuthRequestIdentity) => void): Promise<string | undefined>;
+    get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
     /**
      * Build an {@link ApiKeyResolver} backed by this storage, implementing the
      * central a/b/c auth-retry policy:
@@ -143,6 +178,7 @@ export declare class KeyCascade implements KeysApi {
      *   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.
+     *   7. OMP compatibility mirror (upstream agent.db fallback key).
      *
      * The string is purely informational; consumers must not parse it.
      */
@@ -151,6 +187,7 @@ export declare class KeyCascade implements KeysApi {
     removeRuntime(provider: string): void;
     setConfig(provider: string, apiKeyConfig: string, options?: {
         fallback?: boolean;
+        mirror?: boolean;
     }): void;
     removeConfig(provider: string): void;
     clearConfig(): void;

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

@@ -37,9 +37,11 @@ export declare class OAuthAccounts implements OAuthApi {
      * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
      * scenarios, prefer API-key resolution.
      *
-     * Returns `undefined` when no OAuth credential is available, the
-     * credential fails to refresh, or runtime/config overrides have replaced
-     * OAuth with an explicit API key.
+     * Returns `undefined` when no usable OAuth credential is available
+     * (none stored, or every one definitively failed to refresh) or
+     * runtime/config overrides have replaced OAuth with an explicit API key.
+     * Rejects with {@link AIError.OAuthRefreshUnavailableError} (transient,
+     * retryable) when a retryable refresh failure left no usable credential.
      */
     access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
     /**
@@ -65,9 +67,10 @@ export declare class OAuthAccounts implements OAuthApi {
      * 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.
+     * falls back to sibling credentials. A generic forced refresh re-mints only the
+     * requested row; with `refreshReason: "auth-recovery"` it may instead reuse a
+     * still-usable recent mint of that row. Either way exact-account affinity holds
+     * 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.

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

@@ -14,6 +14,7 @@ export declare class AccountPolicies {
      */
     replace(policies: AuthAccountPolicies, defaultReservePct: number | undefined, storedCredentials?: ReadonlyMap<string, readonly AuthCredential[]>): void;
     validateUsageCapability(provider: string, canFetchUsage: boolean): void;
+    /** Throw on ambiguous selectors for `provider`; a selector whose account is absent is inert and warns once. */
     validateFor(provider: string, credentials: readonly AuthCredential[]): void;
     /**
      * Return the configured account policy matching an OAuth identity.

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

@@ -1,7 +1,6 @@
 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 OAuthRefreshByIdOptions, type OAuthRefreshReason, type StoredOAuthRefreshOptions, type StoredOAuthRefreshResult } from "./types.js";
 /**
@@ -30,8 +29,8 @@ export declare function mergeRefreshedCredential<T extends OAuthCredential>(curr
 export interface OAuthRefresherDeps {
     store: AuthCredentialStore;
     pool: CredentialPool;
-    policies: AccountPolicies;
     override?: AuthStorageOptions["refreshOAuthCredential"];
+    overrideMints?: AuthStorageOptions["refreshOAuthCredentialMints"];
 }
 /** Single-flighted, lease-guarded OAuth refresh with compare-and-set persistence. */
 export declare class OAuthRefresher {

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

@@ -8,7 +8,7 @@ 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 ApiKeyCredential, type AuthApiKeyOptions, type AuthCredential, type 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;
@@ -32,6 +32,8 @@ export type TryOAuthOptions = {
     blockScopes?: readonly string[];
     /** When false, a definitive failure of THIS credential returns undefined instead of falling back to the ranked/round-robin selector (target-only resolution). */
     allowFallback?: boolean;
+    /** Receives a non-definitive refresh failure that left this credential unusable; the caller filters for retryable ones. */
+    onTransientRefreshFailure?: (error: unknown) => void;
 };
 /** Services consulted by CredentialSelector for policy, usage, blocks, refresh, and session affinity. */
 export interface CredentialSelectorDeps {
@@ -69,9 +71,9 @@ export declare class CredentialSelector {
      * 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;
+     *    accounts are allowed (an explicit session pin first, then blocked
+     *    candidates 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.

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

@@ -7,7 +7,7 @@
 import type { Database } from "bun:sqlite";
 import { isSqliteBusyError, isSqliteCorruptionError } from "@linxiraos/pi-utils";
 import type { AuthCredentialStore, CredentialRefreshLeaseFence } from "./store.js";
-import type { AuthCredential, DisabledCredentialSummary, StoredAuthCredential, StoredCredentialBlock } from "./types.js";
+import type { AuthCredential, DisabledCredentialSummary, OAuthCredential, 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;
@@ -18,7 +18,26 @@ type SerializedCredentialRecord = {
 };
 export { isSqliteBusyError, isSqliteCorruptionError };
 export declare function serializeCredential(provider: string, credential: AuthCredential): SerializedCredentialRecord | null;
+/**
+ * Identity key of a credential: the `identityKey` that broker snapshots carry
+ * and that broker account pools and `sessions.restrict` match, such as
+ * `email:<address>|org:<id>` for org-scoped providers. `null` for an API key or
+ * an OAuth credential without any account, email, project, or org identity.
+ */
 export declare function resolveCredentialIdentityKey(provider: string, credential: AuthCredential): string | null;
+/**
+ * Whether upserting `incoming` replaces the active row holding `existing` (stored
+ * under `existingIdentityKey`) instead of inserting a new row beside it.
+ */
+export declare function matchesReplacementCredential(provider: string, existing: AuthCredential | null, existingIdentityKey: string | null, incoming: AuthCredential): boolean;
+/**
+ * Whether two OAuth credentials belong to the same account of the same organization,
+ * whichever identity key each is stored under. The email decides when both carry one;
+ * otherwise a matching account id does, unless it is the organization's own id (a
+ * ChatGPT workspace id shared by every member). Project ids are shared between users
+ * (every consumer Antigravity login has the same one) and never count.
+ */
+export declare function isSameOAuthAccount(a: OAuthCredential, b: OAuthCredential): boolean;
 /**
  * Default SQLite-backed implementation of {@link AuthCredentialStore}.
  *
@@ -60,6 +79,7 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     deleteCachePrefix(prefix: string): void;
     cleanExpiredCache(): void;
     getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    getCredentialBlockScopes(credentialId: number, providerKey: string): Map<string, number>;
     getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
     upsertCredentialBlock(block: StoredCredentialBlock): void;
     deleteCredentialBlock(credentialId: number, providerKey: string, blockScope: string): void;

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

@@ -71,6 +71,12 @@ export interface CredentialCacheStore {
 export interface CredentialBlockStore {
     /** Non-expired block for one (credential, providerKey, scope) key, or undefined. */
     getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    /**
+     * Non-expired blocks for one credential and providerKey, keyed by block
+     * scope (`""` is unscoped), in one read. Optional: selectors fall back to
+     * {@link CredentialBlockStore.getCredentialBlock} per scope when absent.
+     */
+    getCredentialBlockScopes?(credentialId: number, providerKey: string): ReadonlyMap<string, number>;
     /** Earliest time a shared-store block should be eligible for live-usage reconciliation. */
     getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
     /** Upsert with MAX semantics: keep the later blockedUntilMs on conflict. */
@@ -116,8 +122,8 @@ export interface UsageLedgerStore {
 }
 /** Broker-delegated OAuth refresh and usage-report operations. */
 export interface CredentialUpstream {
-    /** Optional hook to notify the underlying store that usage report cache is stale. */
-    invalidateUsageCache(signal?: AbortSignal): Promise<void>;
+    /** Optional hook to notify the underlying store that usage reports (one provider's, when given) are stale. */
+    invalidateUsageCache(provider?: string, signal?: AbortSignal): Promise<void>;
     /**
      * Optional store-supplied OAuth refresh. When present, `AuthStorage` uses
      * it before the per-provider local refresh path. `RemoteAuthCredentialStore`

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

@@ -220,6 +220,8 @@ export interface CheckCredentialsOptions {
     completionProbe?: CompletionProbe;
     /** Per-credential completion probe timeout (ms). Defaults to `timeoutMs`. */
     completionTimeoutMs?: number;
+    /** Providers whose credentials are skipped entirely (not probed, not reported). */
+    excludeProviders?: ReadonlySet<string>;
 }
 /**
  * Sentinel value placed in OAuth `refresh` fields when a credential is shared
@@ -314,6 +316,12 @@ export type AuthStorageOptions = {
      * the actual refresh token never leaves the broker.
      */
     refreshOAuthCredential?: (provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal, reason?: OAuthRefreshReason) => Promise<OAuthCredentials>;
+    /**
+     * Set when {@link refreshOAuthCredential} exchanges the refresh token with the
+     * provider itself instead of delegating (e.g. to a broker), so its tokens count
+     * as this process's mints for auth-recovery reuse.
+     */
+    refreshOAuthCredentialMints?: boolean;
     /**
      * Human-readable description of the credential store backing this
      * AuthStorage instance. Surfaced through {@link AuthStorage.keys.describe}
@@ -407,7 +415,7 @@ export interface ModelUsageHealthOptions {
 export type AuthApiKeyOptions = {
     baseUrl?: string;
     modelId?: string;
-    /** Provider account ids known to serve `modelId` from multi-account discovery; OAuth selection prefers them and tries other accounts only as a last resort. */
+    /** {@link oauthAccountKey}s of accounts known to serve `modelId` from multi-account discovery; OAuth selection prefers them and tries other accounts only as a last resort. */
     accountIds?: readonly string[];
     /**
      * Caller's cancel signal. Threaded into any broker-bound OAuth refresh so
@@ -424,7 +432,22 @@ export type AuthApiKeyOptions = {
     forceRefresh?: boolean;
     /** Explicit provider-401 recovery; generic force refreshes leave this unset. */
     refreshReason?: OAuthRefreshReason;
+    /** When false, select as `sessionId` would without recording the choice as that session's sticky credential. */
+    recordAffinity?: boolean;
 };
+/**
+ * Identity that multi-account discovery records in `Model.accountAccess` and
+ * that {@link AuthApiKeyOptions.accountIds} selection matches: the provider
+ * account id (Codex `chatgpt_account_id`), else the login email for providers
+ * whose credentials carry no account id (Antigravity), else the project id for
+ * a login whose email lookup failed. Same precedence as the credential store's
+ * identity key.
+ */
+export declare function oauthAccountKey(identity: {
+    accountId?: string;
+    email?: string;
+    projectId?: string;
+}): string | undefined;
 /** Non-secret identity bound to the OAuth credential selected for one request attempt. */
 export interface OAuthRequestIdentity {
     orgId?: string;
@@ -808,9 +831,22 @@ export interface KeysApi {
      * 4. API key persisted by a successful `/login`
      * 5. Environment variable
      * 6. Stored API key (e.g. a broker-migrated copy) — last resort, so an explicit env var wins
+     * 7. OMP compatibility mirror — below every stored credential, so a key the
+     *    user saves locally always wins over the upstream fallback
+     *
+     * Resolves `undefined` when no permitted credential can serve, including when
+     * OAuth refresh failed transiently (network, timeout, 5xx), so availability
+     * probes move on to their next candidate. Request paths use
+     * {@link KeysApi.getWithCredential}, which surfaces that failure.
      */
     get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
-    /** Resolve a bearer together with its durable stored credential row id, when known. */
+    /**
+     * Resolve a bearer together with its durable stored credential row id, when known.
+     * Same precedence as {@link KeysApi.get}, but rejects with
+     * `OAuthRefreshUnavailableError` (transient, retryable) when OAuth refresh failed
+     * with a retryable error and no other permitted source could serve the request;
+     * the stored credential is kept.
+     */
     getWithCredential(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<ResolvedApiKey | undefined>;
     /**
      * Peek at API key for a provider without refreshing OAuth tokens.
@@ -865,12 +901,17 @@ export interface KeysApi {
      * `fallback: true` ranks the value below stored OAuth and `/login`
      * credentials instead, so a provider's default key reference cannot shadow
      * a key the user logged in with.
+     *
+     * `mirror: true` ranks the value below everything else, under stored
+     * api_key credentials — a read-only compatibility mirror (upstream OMP
+     * agent.db key) that must never shadow a locally stored key.
      */
     setConfig(provider: string, apiKeyConfig: string, options?: {
         fallback?: boolean;
+        mirror?: boolean;
     }): void;
     /**
-     * Remove a single config-sourced API key (override or fallback).
+     * Remove a single config-sourced API key (override, fallback, or mirror).
      */
     removeConfig(provider: string): void;
     /**
@@ -902,7 +943,7 @@ export interface KeysApi {
         modelId?: string;
     }): ApiKeyResolver;
 }
-/** Controls whether a row-id refresh may reuse a token minted by this refresher. */
+/** Controls whether a row-id refresh may reuse a recently minted token. */
 export interface OAuthRefreshByIdOptions {
     /**
      * Return the stored credential when it still holds a fresh access token this
@@ -910,6 +951,12 @@ export interface OAuthRefreshByIdOptions {
      * refresh tokens repeatedly when a provider rejects every valid bearer.
      */
     reuseRecentMint?: boolean;
+    /**
+     * Provider-401 recovery intent. Forwarded to a delegated refresh (an auth
+     * broker), which may then return a token it minted in the last five minutes.
+     * Local reuse still requires {@link reuseRecentMint}.
+     */
+    reason?: OAuthRefreshReason;
 }
 /** OAuth login, access, account identity, and refresh operations. */
 export interface OAuthApi {
@@ -931,9 +978,11 @@ export interface OAuthApi {
      * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
      * scenarios, prefer {@link AuthStorage.keys.get}.
      *
-     * Returns `undefined` when no OAuth credential is available, the
-     * credential fails to refresh, or runtime/config overrides have replaced
-     * OAuth with an explicit API key.
+     * Returns `undefined` when no usable OAuth credential is available (none
+     * stored, or every one definitively failed to refresh) or runtime/config
+     * overrides have replaced OAuth with an explicit API key. Rejects with
+     * `OAuthRefreshUnavailableError` (transient, retryable) when a retryable
+     * refresh failure left no usable credential.
      */
     access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined>;
     /**
@@ -949,9 +998,10 @@ export interface OAuthApi {
      * 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.
+     * falls back to sibling credentials. A generic forced refresh re-mints only the
+     * requested row; with `refreshReason: "auth-recovery"` it may instead reuse a
+     * still-usable recent mint of that row. Either way exact-account affinity holds
+     * 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.
@@ -985,8 +1035,9 @@ export interface OAuthApi {
      * 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. Mints unconditionally unless
-     * {@link OAuthRefreshByIdOptions.reuseRecentMint} is set.
+     * on every successful refresh. Mints unless {@link OAuthRefreshByIdOptions.reuseRecentMint}
+     * finds a recent local mint, or a delegated refresh given
+     * {@link OAuthRefreshByIdOptions.reason} `"auth-recovery"` returns its recent mint.
      */
     refresh(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry>;
     /**
@@ -994,6 +1045,11 @@ export interface OAuthApi {
      */
     refreshStored<T extends OAuthCredential = OAuthCredential>(provider: string, options: StoredOAuthRefreshOptions<T>): Promise<StoredOAuthRefreshResult<T>>;
 }
+/**
+ * Handle for one {@link SessionsApi.restrict} call. {@link SessionsApi.unrestrict}
+ * lifts a restriction only with the lease of the call that installed it.
+ */
+export type SessionRestrictionLease = symbol;
 /** Session credential affinity operations. */
 export interface SessionsApi {
     /**
@@ -1013,14 +1069,42 @@ export interface SessionsApi {
         restoredAtMs?: number;
     }): boolean;
     /**
-     * Copy every stored credential affinity from one live session to another.
+     * Copy stored credential affinities 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.
+     * source session. `include` limits the copy to the providers it accepts,
+     * given whether the source's affinity is an explicit user pin.
+     */
+    inherit(sourceSessionId: string, targetSessionId: string, include?: (provider: string, explicit: boolean) => boolean): number;
+    /**
+     * Restrict one session's credentials for `provider` to the OAuth accounts
+     * whose identity key (`email:<address>|org:<id>` for org-scoped providers;
+     * otherwise `account:`, `email:`, or `project:` — the keys broker account
+     * pools use) is listed. Selection, session pins, inherited affinity,
+     * fallback passes, and rotation never leave the list, and runtime, config,
+     * environment, and stored API keys are not used for that session; when no
+     * listed account can serve, key resolution fails instead of borrowing
+     * another account. An empty list allows no account. Replaces any earlier
+     * restriction for the same provider and session; {@link inherit} does not
+     * copy restrictions. Restrictions are never evicted, because that would
+     * widen a live session; the owner passes the returned lease to
+     * {@link unrestrict} when the session ends.
+     */
+    restrict(provider: string, sessionId: string, identityKeys: readonly string[]): SessionRestrictionLease;
+    /**
+     * Lift the restriction that `lease` installed. Once a later {@link restrict}
+     * call has replaced it for the same provider and session, this does nothing,
+     * so a stale owner never lifts the restriction a newer owner relies on.
+     */
+    unrestrict(provider: string, sessionId: string, lease: SessionRestrictionLease): void;
+    /**
+     * Whether stored credential `credentialId` may serve `sessionId`: always for
+     * an unrestricted session, otherwise only an OAuth account its
+     * {@link restrict} list names.
      */
-    inherit(sourceSessionId: string, targetSessionId: string): number;
+    permits(provider: string, sessionId: string, credentialId: number): boolean;
     /**
      * Release a session's sticky credential so its next {@link getApiKey} call
      * re-runs native pool ranking. This never blocks or penalizes the released