@prestyj/core 5.11.0 → 5.13.0

package/dist/index.d.cts

@@ -12,7 +12,7 @@ declare function getNextThinkingLevel(provider: Provider, model: string, current
  * and any other OpenAI-compatible server the user points us at.
  *
  * Everything rides the OpenAI-compatible `/v1` transport (see the `local`
- * provider in gg-ai's stream.ts); the only per-server difference is where the
+ * provider in @prestyj/ai's stream.ts); the only per-server difference is where the
  * *capabilities* come from, because `GET /v1/models` reports nothing useful:
  *
  *   - Ollama    → `POST /api/show`      → `capabilities[]` + `model_info["<arch>.context_length"]`
@@ -185,7 +185,16 @@ interface OAuthCredentials {
 }
 interface OAuthLoginCallbacks {
     onOpenUrl: (url: string) => void;
-    onPromptCode: (message: string) => Promise<string>;
+    /**
+     * Collect a pasted authorization code or callback URL.
+     *
+     * `signal` aborts when the code already arrived another way (the local
+     * callback listener won the race) and the prompt should be torn down.
+     * Implementations may ignore it — an abandoned promise is simply never
+     * awaited — but a terminal prompt should honour it so the line does not
+     * linger after login already succeeded.
+     */
+    onPromptCode: (message: string, signal?: AbortSignal) => Promise<string>;
     onStatus: (message: string) => void;
 }
 
@@ -195,6 +204,43 @@ interface OAuthLoginCallbacks {
  * prefer OAuth for the logical `moonshot` provider.
  */
 declare const MOONSHOT_OAUTH_KEY = "moonshot-oauth";
+/**
+ * Storage key for Grok (xAI) subscription OAuth credentials. Kept distinct from
+ * the `xai` API-key entry for the same reason as Kimi's: a user may configure
+ * BOTH — a SuperGrok/X Premium subscription plus a metered console key — and we
+ * always prefer OAuth for the logical `xai` provider.
+ */
+declare const XAI_OAUTH_KEY = "xai-oauth";
+/**
+ * A provider that can hold two credentials at once: a refreshable subscription
+ * OAuth token and a static API key. One policy governs all of them — see
+ * {@link DUAL_AUTH_PROVIDERS} — so adding a provider here is enough to give it
+ * OAuth-first resolution, usage-exhaustion fallback, per-method logout and the
+ * matching UI affordances.
+ */
+interface DualAuthProvider {
+    /** Logical provider id, which is also the API-key storage key. */
+    provider: string;
+    /** Storage key holding the OAuth credential. */
+    oauthKey: string;
+    /** Human label for the OAuth credential (log/UI wording). */
+    oauthLabel: string;
+    /** Human label for the API-key credential (log/UI wording). */
+    apiKeyLabel: string;
+    /** What the user should do to restore OAuth after it went invalid. */
+    restoreHint: string;
+}
+/** Dual-auth policy for a logical provider, or undefined if it has just one method. */
+declare function dualAuthProvider(provider: string): DualAuthProvider | undefined;
+/** Dual-auth policy keyed by the OAuth storage key (the reverse lookup). */
+declare function dualAuthProviderByOAuthKey(storageKey: string): DualAuthProvider | undefined;
+/** The OAuth storage key for a dual-auth provider, if it has one. */
+declare function oauthStorageKey(provider: string): string | undefined;
+/**
+ * Both storage keys a dual-auth provider may hold, in resolution order
+ * (OAuth first). Single-method providers yield just their own key.
+ */
+declare function providerStorageKeys(provider: string): string[];
 /**
  * Storage key for the Xiaomi API Credits credential (`https://api.xiaomimimo.com/v1`).
  * Kept distinct from the `xiaomi` Token Plan entry (`token-plan-sgp.xiaomimimo.com`)
@@ -224,6 +270,16 @@ declare class AuthStorage {
     private data;
     private filePath;
     private loaded;
+    /**
+     * mtime+size of the file as of the cached snapshot (`size: -1` = no file).
+     * auth.json is shared: the desktop app writes API keys and disconnects
+     * NATIVELY (so they work with no daemon running), and every window/process has
+     * its own AuthStorage. A load-once cache therefore goes stale — the sidecar
+     * would keep listing models for a provider just disconnected, and hide the
+     * ones just connected, until the daemon restarted.
+     */
+    private snapshotMtimeMs;
+    private snapshotSize;
     /** Per-provider lock to serialize concurrent refresh calls. */
     private refreshLocks;
     constructor(filePath?: string);
@@ -242,9 +298,9 @@ declare class AuthStorage {
      */
     pickStorageKey(keys: string[]): Promise<string | undefined>;
     /**
-     * True if the user has any usable auth for the logical provider. For
-     * `moonshot` this is satisfied by either the Kimi OAuth credential or the
-     * Moonshot API key.
+     * True if the user has any usable auth for the logical provider. For a
+     * dual-auth provider (Kimi/Grok) either the OAuth credential or the API key
+     * satisfies it.
      */
     hasProviderAuth(provider: string): Promise<boolean>;
     /** Endpoint ids that currently have a `local:<id>` credential stored. */
@@ -259,16 +315,17 @@ declare class AuthStorage {
     removeLocalEndpoint(endpointId: string): Promise<void>;
     /**
      * True if the active credential for `provider` is a static API key with no
-     * refresh mechanism. For `moonshot` this is only true when the Kimi OAuth
-     * credential is absent (a present OAuth credential is refreshable).
+     * refresh mechanism. For a dual-auth provider this is only true when its OAuth
+     * credential is absent or sidelined (a live OAuth credential is refreshable).
      */
     isStaticApiKey(provider: string): Promise<boolean>;
     /**
      * The base URL on the credential that is active right now, if any.
      * Synchronous — call only after load()/resolveCredentials() populated the
-     * snapshot. For `moonshot` this is the Kimi For Coding URL whenever the
-     * OAuth entry is the one resolveCredentials would serve (i.e. not currently
-     * usage-exhausted with an API key configured).
+     * snapshot. For a dual-auth provider this is the subscription endpoint (Kimi
+     * For Coding, the Grok CLI proxy) whenever the OAuth entry is the one
+     * resolveCredentials would serve (i.e. not currently usage-exhausted with an
+     * API key configured).
      */
     getStoredBaseUrl(provider: string): string | undefined;
     load(): Promise<void>;
@@ -279,6 +336,20 @@ declare class AuthStorage {
      * writes API keys natively without going through this instance.
      */
     reload(): Promise<void>;
+    /**
+     * Like {@link ensureLoaded}, but re-reads when the file changed since this
+     * snapshot — a cheap stat, not a re-parse. Used by the "what is connected?"
+     * readers, which must reflect writes made by another window, the CLI, or the
+     * desktop app's native (daemon-free) API-key and disconnect paths.
+     *
+     * Deliberately NOT used by {@link resolveCredentials}: that path compares the
+     * caller's snapshot against the latest file to detect a concurrent re-login,
+     * and silently refreshing this instance's view first would destroy the
+     * evidence that the token it just had rejected has already been replaced.
+     */
+    private ensureFresh;
+    /** Record the file identity behind the current snapshot. */
+    private rememberSnapshot;
     /**
      * Apply one provider-scoped mutation to the latest on-disk snapshot.
      * AuthStorage instances live in every app session/process, so writing this
@@ -296,7 +367,7 @@ declare class AuthStorage {
      * `resetsAt` (unix SECONDS, from the provider's rate-limit response) or a
      * 15-minute default when no reset time is known. While the mark is in the
      * future, `resolveCredentials("moonshot")` serves the Moonshot API key
-     * instead of the Kimi OAuth credential (when both are configured) — OAuth
+     * instead of the subscription OAuth credential (when both are configured) — OAuth
      * stays the preferred credential and is retried automatically once the mark
      * lapses. Persisted to auth.json so a restart (or another ezcoder-app window)
      * doesn't burn a request rediscovering the same exhausted window. No-op if
@@ -306,13 +377,27 @@ declare class AuthStorage {
     clearAll(): Promise<void>;
     /**
      * Returns valid credentials, auto-refreshing if expired.
+     *
      * If `forceRefresh` is true, refreshes even if the token hasn't expired
-     * (useful when the provider rejects a token with 401 before its stored expiry).
+     * (useful when the provider rejects a token with 401 before its stored
+     * expiry). Callers recovering from a rejection should also pass
+     * `rejectedToken` — see the stampede guard below.
+     *
      * Throws if not logged in.
      */
     resolveCredentials(provider: string, opts?: {
         forceRefresh?: boolean;
         storageKeys?: string[];
+        /**
+         * The access token the provider just rejected. Refreshing an OAuth grant
+         * invalidates the previous access token, so N processes sharing auth.json
+         * (app windows, CLI sessions, the usage poller) can otherwise revoke each
+         * other in a loop: each one force-refreshes on 401, and every refresh kills
+         * the token the others still hold. Naming the rejected token lets the
+         * refresh path tell "this credential is genuinely dead" from "someone else
+         * already rotated it" and simply adopt the newer on-disk credential.
+         */
+        rejectedToken?: string;
     }): Promise<OAuthCredentials>;
     /**
      * Returns a valid access token, auto-refreshing if expired.
@@ -417,6 +502,69 @@ declare function loginKimi(callbacks: OAuthLoginCallbacks): Promise<OAuthCredent
 /** Exchange a refresh token for a fresh Kimi access token. */
 declare function refreshKimiToken(refreshToken: string): Promise<OAuthCredentials>;
 
+/**
+ * Grok (xAI) subscription OAuth — Device Authorization Grant (RFC 8628).
+ *
+ * Two form-encoded POST endpoints against xAI's OIDC issuer (`https://auth.x.ai`,
+ * advertised by its `/.well-known/openid-configuration`):
+ *
+ *  - `/oauth2/device/code` (client_id + scope)          → device + user code
+ *  - `/oauth2/token` (grant_type=device_code)           → poll until authorized
+ *  - `/oauth2/token` (grant_type=refresh_token)         → refresh access token
+ *
+ * Like Kimi (and unlike Anthropic/OpenAI/Gemini's browser-redirect PKCE) this is
+ * a device-code/poll flow: show a URL + code, the user authorizes in a browser on
+ * any device, we poll for the token. Deliberately chosen over the loopback PKCE
+ * variant because xAI pins the Grok-CLI client's redirect to
+ * `http://127.0.0.1:56121/callback` — a fixed port we cannot rebind if it's busy,
+ * and unreachable from a container/SSH session. Device code has neither problem.
+ *
+ * The issued token is used against the Grok CLI's chat proxy
+ * (`https://cli-chat-proxy.grok.com/v1`, distinct from the `api.x.ai` API-key
+ * endpoint) — that is the surface the `grok-cli:access` scope grants, and it
+ * bills against the user's SuperGrok / X Premium subscription instead of metered
+ * API credits. We persist that base URL on the credential so the runtime routes
+ * there automatically; `grokCliHeaders()` supplies the client identity the proxy
+ * requires (attached centrally in @prestyj/ai's `xai` transport).
+ *
+ * Caveats worth knowing, both observed in the wild and surfaced to users rather
+ * than hidden here:
+ *  - The client id below is xAI's public Grok-CLI desktop client (no secret).
+ *    Every third-party implementation reuses it; xAI has not published a
+ *    partner-client program, so subscription OAuth is a best-effort path.
+ *  - xAI gates proxy access by subscription tier. A perfectly valid login can
+ *    still be refused at inference time, which is exactly why `xai` keeps its
+ *    API-key method as a fallback (see AuthStorage's dual-auth resolution).
+ */
+
+/** Grok CLI chat-proxy base URL the issued OAuth token is used against. */
+declare function grokCliBaseUrl(): string;
+/**
+ * Headers the Grok CLI chat proxy requires on every model request. It serves
+ * only recognized Grok-CLI clients: without the token-auth marker and a client
+ * version it refuses the request. `modelId` populates the model-override header
+ * the proxy uses to route a request to the entitled model.
+ *
+ * Attach these ONLY to the proxy — the `api.x.ai` API-key path must not receive
+ * them (see {@link isGrokCliEndpoint}).
+ */
+declare function grokCliHeaders(modelId?: string): Record<string, string>;
+/**
+ * True if `baseUrl` targets the Grok CLI chat proxy (the URL persisted on Grok
+ * OAuth credentials). Callers use this to decide whether to attach
+ * {@link grokCliHeaders} and whether a usage/permission rejection should fall
+ * back to the xAI API key.
+ */
+declare function isGrokCliEndpoint(baseUrl: string | undefined): boolean;
+/**
+ * Drive the Grok device-code flow end-to-end. Shows the verification URL + user
+ * code via callbacks, opens the browser, and polls until the user authorizes or
+ * the device code expires (deadline set by the server).
+ */
+declare function loginXai(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+/** Exchange a refresh token for a fresh Grok access token. */
+declare function refreshXaiToken(refreshToken: string): Promise<OAuthCredentials>;
+
 /**
  * Minimal Telegram Bot API client using raw fetch().
  * Supports long polling, markdown messages, inline keyboards, and message splitting.
@@ -590,4 +738,4 @@ interface AutoUpdater {
 }
 declare function createAutoUpdater(config: AutoUpdateConfig): AutoUpdater;
 
-export { AuthStorage, type AutoUpdateConfig, type AutoUpdater, DEFAULT_LOCAL_ENDPOINTS, type DiscoverOptions, type DiscoveryResult, FALLBACK_CONTEXT_WINDOW, type InlineButton, LOCAL_API_KEY_PLACEHOLDER, LOCAL_AUTH_KEY_PREFIX, type LocalEndpoint, type LocalEndpointKind, type LocalEndpointProbe, type LocalModel, type LogLevel, MOONSHOT_OAUTH_KEY, ModelInfo, NotLoggedInError, type OAuthCredentials, type OAuthLoginCallbacks, type ProbeOptions, type ProgressCallback, SubscriptionUsageError, type SubscriptionUsageProvider, type SubscriptionUsageSnapshot, type SubscriptionUsageWindow, TelegramBot, type TelegramConfig, type TelegramMessage, type TelegramUpdate, type TelegramVoiceMessage, XIAOMI_CREDITS_KEY, clearLocalDiscoveryCache, closeLogger, createAutoUpdater, decodeOggOpus, discoverLocalModels, downmixToMono, endpointRoot, fetchSubscriptionUsage, findProbedModel, formatLocalModelId, generatePKCE, getClaudeCliUserAgent, getClaudeCodeVersion, getNextThinkingLevel, getSessionId, getSupportedThinkingLevels, isKimiCodingEndpoint, isLocalModelId, isLoggerOpen, isModelLoaded, isThinkingLevelSupported, kimiCodeBaseUrl, kimiCodingHeaders, localAuthStorageKey, log, loginAnthropic, loginGemini, loginKimi, loginOpenAI, openLog, parseLocalModelId, probeEndpoint, readStoredBaseUrlSync, refreshAnthropicToken, refreshGeminiToken, refreshKimiToken, refreshOpenAIToken, registerLogCleanup, resample, setProgressCallback, toModelInfo, transcribeVoice, withFileLock };
+export { AuthStorage, type AutoUpdateConfig, type AutoUpdater, DEFAULT_LOCAL_ENDPOINTS, type DiscoverOptions, type DiscoveryResult, type DualAuthProvider, FALLBACK_CONTEXT_WINDOW, type InlineButton, LOCAL_API_KEY_PLACEHOLDER, LOCAL_AUTH_KEY_PREFIX, type LocalEndpoint, type LocalEndpointKind, type LocalEndpointProbe, type LocalModel, type LogLevel, MOONSHOT_OAUTH_KEY, ModelInfo, NotLoggedInError, type OAuthCredentials, type OAuthLoginCallbacks, type ProbeOptions, type ProgressCallback, SubscriptionUsageError, type SubscriptionUsageProvider, type SubscriptionUsageSnapshot, type SubscriptionUsageWindow, TelegramBot, type TelegramConfig, type TelegramMessage, type TelegramUpdate, type TelegramVoiceMessage, XAI_OAUTH_KEY, XIAOMI_CREDITS_KEY, clearLocalDiscoveryCache, closeLogger, createAutoUpdater, decodeOggOpus, discoverLocalModels, downmixToMono, dualAuthProvider, dualAuthProviderByOAuthKey, endpointRoot, fetchSubscriptionUsage, findProbedModel, formatLocalModelId, generatePKCE, getClaudeCliUserAgent, getClaudeCodeVersion, getNextThinkingLevel, getSessionId, getSupportedThinkingLevels, grokCliBaseUrl, grokCliHeaders, isGrokCliEndpoint, isKimiCodingEndpoint, isLocalModelId, isLoggerOpen, isModelLoaded, isThinkingLevelSupported, kimiCodeBaseUrl, kimiCodingHeaders, localAuthStorageKey, log, loginAnthropic, loginGemini, loginKimi, loginOpenAI, loginXai, oauthStorageKey, openLog, parseLocalModelId, probeEndpoint, providerStorageKeys, readStoredBaseUrlSync, refreshAnthropicToken, refreshGeminiToken, refreshKimiToken, refreshOpenAIToken, refreshXaiToken, registerLogCleanup, resample, setProgressCallback, toModelInfo, transcribeVoice, withFileLock };

package/dist/index.d.ts

@@ -12,7 +12,7 @@ declare function getNextThinkingLevel(provider: Provider, model: string, current
  * and any other OpenAI-compatible server the user points us at.
  *
  * Everything rides the OpenAI-compatible `/v1` transport (see the `local`
- * provider in gg-ai's stream.ts); the only per-server difference is where the
+ * provider in @prestyj/ai's stream.ts); the only per-server difference is where the
  * *capabilities* come from, because `GET /v1/models` reports nothing useful:
  *
  *   - Ollama    → `POST /api/show`      → `capabilities[]` + `model_info["<arch>.context_length"]`
@@ -185,7 +185,16 @@ interface OAuthCredentials {
 }
 interface OAuthLoginCallbacks {
     onOpenUrl: (url: string) => void;
-    onPromptCode: (message: string) => Promise<string>;
+    /**
+     * Collect a pasted authorization code or callback URL.
+     *
+     * `signal` aborts when the code already arrived another way (the local
+     * callback listener won the race) and the prompt should be torn down.
+     * Implementations may ignore it — an abandoned promise is simply never
+     * awaited — but a terminal prompt should honour it so the line does not
+     * linger after login already succeeded.
+     */
+    onPromptCode: (message: string, signal?: AbortSignal) => Promise<string>;
     onStatus: (message: string) => void;
 }
 
@@ -195,6 +204,43 @@ interface OAuthLoginCallbacks {
  * prefer OAuth for the logical `moonshot` provider.
  */
 declare const MOONSHOT_OAUTH_KEY = "moonshot-oauth";
+/**
+ * Storage key for Grok (xAI) subscription OAuth credentials. Kept distinct from
+ * the `xai` API-key entry for the same reason as Kimi's: a user may configure
+ * BOTH — a SuperGrok/X Premium subscription plus a metered console key — and we
+ * always prefer OAuth for the logical `xai` provider.
+ */
+declare const XAI_OAUTH_KEY = "xai-oauth";
+/**
+ * A provider that can hold two credentials at once: a refreshable subscription
+ * OAuth token and a static API key. One policy governs all of them — see
+ * {@link DUAL_AUTH_PROVIDERS} — so adding a provider here is enough to give it
+ * OAuth-first resolution, usage-exhaustion fallback, per-method logout and the
+ * matching UI affordances.
+ */
+interface DualAuthProvider {
+    /** Logical provider id, which is also the API-key storage key. */
+    provider: string;
+    /** Storage key holding the OAuth credential. */
+    oauthKey: string;
+    /** Human label for the OAuth credential (log/UI wording). */
+    oauthLabel: string;
+    /** Human label for the API-key credential (log/UI wording). */
+    apiKeyLabel: string;
+    /** What the user should do to restore OAuth after it went invalid. */
+    restoreHint: string;
+}
+/** Dual-auth policy for a logical provider, or undefined if it has just one method. */
+declare function dualAuthProvider(provider: string): DualAuthProvider | undefined;
+/** Dual-auth policy keyed by the OAuth storage key (the reverse lookup). */
+declare function dualAuthProviderByOAuthKey(storageKey: string): DualAuthProvider | undefined;
+/** The OAuth storage key for a dual-auth provider, if it has one. */
+declare function oauthStorageKey(provider: string): string | undefined;
+/**
+ * Both storage keys a dual-auth provider may hold, in resolution order
+ * (OAuth first). Single-method providers yield just their own key.
+ */
+declare function providerStorageKeys(provider: string): string[];
 /**
  * Storage key for the Xiaomi API Credits credential (`https://api.xiaomimimo.com/v1`).
  * Kept distinct from the `xiaomi` Token Plan entry (`token-plan-sgp.xiaomimimo.com`)
@@ -224,6 +270,16 @@ declare class AuthStorage {
     private data;
     private filePath;
     private loaded;
+    /**
+     * mtime+size of the file as of the cached snapshot (`size: -1` = no file).
+     * auth.json is shared: the desktop app writes API keys and disconnects
+     * NATIVELY (so they work with no daemon running), and every window/process has
+     * its own AuthStorage. A load-once cache therefore goes stale — the sidecar
+     * would keep listing models for a provider just disconnected, and hide the
+     * ones just connected, until the daemon restarted.
+     */
+    private snapshotMtimeMs;
+    private snapshotSize;
     /** Per-provider lock to serialize concurrent refresh calls. */
     private refreshLocks;
     constructor(filePath?: string);
@@ -242,9 +298,9 @@ declare class AuthStorage {
      */
     pickStorageKey(keys: string[]): Promise<string | undefined>;
     /**
-     * True if the user has any usable auth for the logical provider. For
-     * `moonshot` this is satisfied by either the Kimi OAuth credential or the
-     * Moonshot API key.
+     * True if the user has any usable auth for the logical provider. For a
+     * dual-auth provider (Kimi/Grok) either the OAuth credential or the API key
+     * satisfies it.
      */
     hasProviderAuth(provider: string): Promise<boolean>;
     /** Endpoint ids that currently have a `local:<id>` credential stored. */
@@ -259,16 +315,17 @@ declare class AuthStorage {
     removeLocalEndpoint(endpointId: string): Promise<void>;
     /**
      * True if the active credential for `provider` is a static API key with no
-     * refresh mechanism. For `moonshot` this is only true when the Kimi OAuth
-     * credential is absent (a present OAuth credential is refreshable).
+     * refresh mechanism. For a dual-auth provider this is only true when its OAuth
+     * credential is absent or sidelined (a live OAuth credential is refreshable).
      */
     isStaticApiKey(provider: string): Promise<boolean>;
     /**
      * The base URL on the credential that is active right now, if any.
      * Synchronous — call only after load()/resolveCredentials() populated the
-     * snapshot. For `moonshot` this is the Kimi For Coding URL whenever the
-     * OAuth entry is the one resolveCredentials would serve (i.e. not currently
-     * usage-exhausted with an API key configured).
+     * snapshot. For a dual-auth provider this is the subscription endpoint (Kimi
+     * For Coding, the Grok CLI proxy) whenever the OAuth entry is the one
+     * resolveCredentials would serve (i.e. not currently usage-exhausted with an
+     * API key configured).
      */
     getStoredBaseUrl(provider: string): string | undefined;
     load(): Promise<void>;
@@ -279,6 +336,20 @@ declare class AuthStorage {
      * writes API keys natively without going through this instance.
      */
     reload(): Promise<void>;
+    /**
+     * Like {@link ensureLoaded}, but re-reads when the file changed since this
+     * snapshot — a cheap stat, not a re-parse. Used by the "what is connected?"
+     * readers, which must reflect writes made by another window, the CLI, or the
+     * desktop app's native (daemon-free) API-key and disconnect paths.
+     *
+     * Deliberately NOT used by {@link resolveCredentials}: that path compares the
+     * caller's snapshot against the latest file to detect a concurrent re-login,
+     * and silently refreshing this instance's view first would destroy the
+     * evidence that the token it just had rejected has already been replaced.
+     */
+    private ensureFresh;
+    /** Record the file identity behind the current snapshot. */
+    private rememberSnapshot;
     /**
      * Apply one provider-scoped mutation to the latest on-disk snapshot.
      * AuthStorage instances live in every app session/process, so writing this
@@ -296,7 +367,7 @@ declare class AuthStorage {
      * `resetsAt` (unix SECONDS, from the provider's rate-limit response) or a
      * 15-minute default when no reset time is known. While the mark is in the
      * future, `resolveCredentials("moonshot")` serves the Moonshot API key
-     * instead of the Kimi OAuth credential (when both are configured) — OAuth
+     * instead of the subscription OAuth credential (when both are configured) — OAuth
      * stays the preferred credential and is retried automatically once the mark
      * lapses. Persisted to auth.json so a restart (or another ezcoder-app window)
      * doesn't burn a request rediscovering the same exhausted window. No-op if
@@ -306,13 +377,27 @@ declare class AuthStorage {
     clearAll(): Promise<void>;
     /**
      * Returns valid credentials, auto-refreshing if expired.
+     *
      * If `forceRefresh` is true, refreshes even if the token hasn't expired
-     * (useful when the provider rejects a token with 401 before its stored expiry).
+     * (useful when the provider rejects a token with 401 before its stored
+     * expiry). Callers recovering from a rejection should also pass
+     * `rejectedToken` — see the stampede guard below.
+     *
      * Throws if not logged in.
      */
     resolveCredentials(provider: string, opts?: {
         forceRefresh?: boolean;
         storageKeys?: string[];
+        /**
+         * The access token the provider just rejected. Refreshing an OAuth grant
+         * invalidates the previous access token, so N processes sharing auth.json
+         * (app windows, CLI sessions, the usage poller) can otherwise revoke each
+         * other in a loop: each one force-refreshes on 401, and every refresh kills
+         * the token the others still hold. Naming the rejected token lets the
+         * refresh path tell "this credential is genuinely dead" from "someone else
+         * already rotated it" and simply adopt the newer on-disk credential.
+         */
+        rejectedToken?: string;
     }): Promise<OAuthCredentials>;
     /**
      * Returns a valid access token, auto-refreshing if expired.
@@ -417,6 +502,69 @@ declare function loginKimi(callbacks: OAuthLoginCallbacks): Promise<OAuthCredent
 /** Exchange a refresh token for a fresh Kimi access token. */
 declare function refreshKimiToken(refreshToken: string): Promise<OAuthCredentials>;
 
+/**
+ * Grok (xAI) subscription OAuth — Device Authorization Grant (RFC 8628).
+ *
+ * Two form-encoded POST endpoints against xAI's OIDC issuer (`https://auth.x.ai`,
+ * advertised by its `/.well-known/openid-configuration`):
+ *
+ *  - `/oauth2/device/code` (client_id + scope)          → device + user code
+ *  - `/oauth2/token` (grant_type=device_code)           → poll until authorized
+ *  - `/oauth2/token` (grant_type=refresh_token)         → refresh access token
+ *
+ * Like Kimi (and unlike Anthropic/OpenAI/Gemini's browser-redirect PKCE) this is
+ * a device-code/poll flow: show a URL + code, the user authorizes in a browser on
+ * any device, we poll for the token. Deliberately chosen over the loopback PKCE
+ * variant because xAI pins the Grok-CLI client's redirect to
+ * `http://127.0.0.1:56121/callback` — a fixed port we cannot rebind if it's busy,
+ * and unreachable from a container/SSH session. Device code has neither problem.
+ *
+ * The issued token is used against the Grok CLI's chat proxy
+ * (`https://cli-chat-proxy.grok.com/v1`, distinct from the `api.x.ai` API-key
+ * endpoint) — that is the surface the `grok-cli:access` scope grants, and it
+ * bills against the user's SuperGrok / X Premium subscription instead of metered
+ * API credits. We persist that base URL on the credential so the runtime routes
+ * there automatically; `grokCliHeaders()` supplies the client identity the proxy
+ * requires (attached centrally in @prestyj/ai's `xai` transport).
+ *
+ * Caveats worth knowing, both observed in the wild and surfaced to users rather
+ * than hidden here:
+ *  - The client id below is xAI's public Grok-CLI desktop client (no secret).
+ *    Every third-party implementation reuses it; xAI has not published a
+ *    partner-client program, so subscription OAuth is a best-effort path.
+ *  - xAI gates proxy access by subscription tier. A perfectly valid login can
+ *    still be refused at inference time, which is exactly why `xai` keeps its
+ *    API-key method as a fallback (see AuthStorage's dual-auth resolution).
+ */
+
+/** Grok CLI chat-proxy base URL the issued OAuth token is used against. */
+declare function grokCliBaseUrl(): string;
+/**
+ * Headers the Grok CLI chat proxy requires on every model request. It serves
+ * only recognized Grok-CLI clients: without the token-auth marker and a client
+ * version it refuses the request. `modelId` populates the model-override header
+ * the proxy uses to route a request to the entitled model.
+ *
+ * Attach these ONLY to the proxy — the `api.x.ai` API-key path must not receive
+ * them (see {@link isGrokCliEndpoint}).
+ */
+declare function grokCliHeaders(modelId?: string): Record<string, string>;
+/**
+ * True if `baseUrl` targets the Grok CLI chat proxy (the URL persisted on Grok
+ * OAuth credentials). Callers use this to decide whether to attach
+ * {@link grokCliHeaders} and whether a usage/permission rejection should fall
+ * back to the xAI API key.
+ */
+declare function isGrokCliEndpoint(baseUrl: string | undefined): boolean;
+/**
+ * Drive the Grok device-code flow end-to-end. Shows the verification URL + user
+ * code via callbacks, opens the browser, and polls until the user authorizes or
+ * the device code expires (deadline set by the server).
+ */
+declare function loginXai(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+/** Exchange a refresh token for a fresh Grok access token. */
+declare function refreshXaiToken(refreshToken: string): Promise<OAuthCredentials>;
+
 /**
  * Minimal Telegram Bot API client using raw fetch().
  * Supports long polling, markdown messages, inline keyboards, and message splitting.
@@ -590,4 +738,4 @@ interface AutoUpdater {
 }
 declare function createAutoUpdater(config: AutoUpdateConfig): AutoUpdater;
 
-export { AuthStorage, type AutoUpdateConfig, type AutoUpdater, DEFAULT_LOCAL_ENDPOINTS, type DiscoverOptions, type DiscoveryResult, FALLBACK_CONTEXT_WINDOW, type InlineButton, LOCAL_API_KEY_PLACEHOLDER, LOCAL_AUTH_KEY_PREFIX, type LocalEndpoint, type LocalEndpointKind, type LocalEndpointProbe, type LocalModel, type LogLevel, MOONSHOT_OAUTH_KEY, ModelInfo, NotLoggedInError, type OAuthCredentials, type OAuthLoginCallbacks, type ProbeOptions, type ProgressCallback, SubscriptionUsageError, type SubscriptionUsageProvider, type SubscriptionUsageSnapshot, type SubscriptionUsageWindow, TelegramBot, type TelegramConfig, type TelegramMessage, type TelegramUpdate, type TelegramVoiceMessage, XIAOMI_CREDITS_KEY, clearLocalDiscoveryCache, closeLogger, createAutoUpdater, decodeOggOpus, discoverLocalModels, downmixToMono, endpointRoot, fetchSubscriptionUsage, findProbedModel, formatLocalModelId, generatePKCE, getClaudeCliUserAgent, getClaudeCodeVersion, getNextThinkingLevel, getSessionId, getSupportedThinkingLevels, isKimiCodingEndpoint, isLocalModelId, isLoggerOpen, isModelLoaded, isThinkingLevelSupported, kimiCodeBaseUrl, kimiCodingHeaders, localAuthStorageKey, log, loginAnthropic, loginGemini, loginKimi, loginOpenAI, openLog, parseLocalModelId, probeEndpoint, readStoredBaseUrlSync, refreshAnthropicToken, refreshGeminiToken, refreshKimiToken, refreshOpenAIToken, registerLogCleanup, resample, setProgressCallback, toModelInfo, transcribeVoice, withFileLock };
+export { AuthStorage, type AutoUpdateConfig, type AutoUpdater, DEFAULT_LOCAL_ENDPOINTS, type DiscoverOptions, type DiscoveryResult, type DualAuthProvider, FALLBACK_CONTEXT_WINDOW, type InlineButton, LOCAL_API_KEY_PLACEHOLDER, LOCAL_AUTH_KEY_PREFIX, type LocalEndpoint, type LocalEndpointKind, type LocalEndpointProbe, type LocalModel, type LogLevel, MOONSHOT_OAUTH_KEY, ModelInfo, NotLoggedInError, type OAuthCredentials, type OAuthLoginCallbacks, type ProbeOptions, type ProgressCallback, SubscriptionUsageError, type SubscriptionUsageProvider, type SubscriptionUsageSnapshot, type SubscriptionUsageWindow, TelegramBot, type TelegramConfig, type TelegramMessage, type TelegramUpdate, type TelegramVoiceMessage, XAI_OAUTH_KEY, XIAOMI_CREDITS_KEY, clearLocalDiscoveryCache, closeLogger, createAutoUpdater, decodeOggOpus, discoverLocalModels, downmixToMono, dualAuthProvider, dualAuthProviderByOAuthKey, endpointRoot, fetchSubscriptionUsage, findProbedModel, formatLocalModelId, generatePKCE, getClaudeCliUserAgent, getClaudeCodeVersion, getNextThinkingLevel, getSessionId, getSupportedThinkingLevels, grokCliBaseUrl, grokCliHeaders, isGrokCliEndpoint, isKimiCodingEndpoint, isLocalModelId, isLoggerOpen, isModelLoaded, isThinkingLevelSupported, kimiCodeBaseUrl, kimiCodingHeaders, localAuthStorageKey, log, loginAnthropic, loginGemini, loginKimi, loginOpenAI, loginXai, oauthStorageKey, openLog, parseLocalModelId, probeEndpoint, providerStorageKeys, readStoredBaseUrlSync, refreshAnthropicToken, refreshGeminiToken, refreshKimiToken, refreshOpenAIToken, refreshXaiToken, registerLogCleanup, resample, setProgressCallback, toModelInfo, transcribeVoice, withFileLock };

package/dist/index.js

@@ -5,9 +5,12 @@ import {
   MODELS,
   MOONSHOT_OAUTH_KEY,
   NotLoggedInError,
+  XAI_OAUTH_KEY,
   XIAOMI_CREDITS_KEY,
   clearRuntimeModels,
   closeLogger,
+  dualAuthProvider,
+  dualAuthProviderByOAuthKey,
   generatePKCE,
   getAllModels,
   getAuthStorageKey,
@@ -25,6 +28,9 @@ import {
   getSummaryModel,
   getToolResultCharLimit,
   getVideoByteLimit,
+  grokCliBaseUrl,
+  grokCliHeaders,
+  isGrokCliEndpoint,
   isKimiCodingEndpoint,
   isLoggerOpen,
   kimiCodeBaseUrl,
@@ -34,17 +40,21 @@ import {
   loginGemini,
   loginKimi,
   loginOpenAI,
+  loginXai,
+  oauthStorageKey,
   openLog,
+  providerStorageKeys,
   readStoredBaseUrlSync,
   refreshAnthropicToken,
   refreshGeminiToken,
   refreshKimiToken,
   refreshOpenAIToken,
+  refreshXaiToken,
   registerLogCleanup,
   registerRuntimeModels,
   usesOpenAICodexTransport,
   withFileLock
-} from "./chunk-WAG5K2MH.js";
+} from "./chunk-S6QBRJ4D.js";
 import {
   getAppPaths
 } from "./chunk-CRU3SSNX.js";
@@ -75,6 +85,7 @@ var ANTHROPIC_ADAPTIVE_THINKING_LEVELS = [
   "max"
 ];
 var MOONSHOT_K3_THINKING_LEVELS = ["low", "high", "max"];
+var GLM_THINKING_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 var LOCAL_THINKING_LEVELS = ["low", "medium", "high", "max"];
 function isOpenAIGptModel(provider, model) {
   return provider === "openai" && model.startsWith("gpt-");
@@ -88,6 +99,9 @@ function isXaiModel(provider) {
 function isMoonshotK3Model(provider, model) {
   return provider === "moonshot" && model === "kimi-k3";
 }
+function isGlmModel(provider) {
+  return provider === "glm";
+}
 function isAnthropicXhighModel(provider, model) {
   return provider === "anthropic" && /opus-5|opus-4-8|opus-4-7/.test(model);
 }
@@ -119,6 +133,11 @@ function getSupportedThinkingLevels(provider, model) {
     return XAI_THINKING_LEVELS.slice(0, maxIndex2 + 1);
   }
   if (isMoonshotK3Model(provider, model)) return MOONSHOT_K3_THINKING_LEVELS;
+  if (isGlmModel(provider)) {
+    const maxIndex2 = GLM_THINKING_LEVELS.indexOf(maxLevel);
+    if (maxIndex2 === -1) return GLM_THINKING_LEVELS;
+    return GLM_THINKING_LEVELS.slice(0, maxIndex2 + 1);
+  }
   if (!isOpenAIGptModel(provider, model)) return [maxLevel];
   const levels = model.startsWith("gpt-5.6-") ? OPENAI_GPT_56_THINKING_LEVELS : OPENAI_GPT_THINKING_LEVELS;
   const maxIndex = levels.indexOf(maxLevel);
@@ -130,7 +149,7 @@ function isThinkingLevelSupported(provider, model, level) {
 }
 function getNextThinkingLevel(provider, model, current) {
   const supportedLevels = getSupportedThinkingLevels(provider, model);
-  const shouldCycleLevels = isOpenAIGptModel(provider, model) || isAnthropicAdaptiveModel(provider, model) || isSakanaModel(provider) || isXaiModel(provider) || isMoonshotK3Model(provider, model) || // Local servers take a real effort level, not just on/off: Ollama accepts
+  const shouldCycleLevels = isOpenAIGptModel(provider, model) || isAnthropicAdaptiveModel(provider, model) || isSakanaModel(provider) || isXaiModel(provider) || isMoonshotK3Model(provider, model) || isGlmModel(provider) || // Local servers take a real effort level, not just on/off: Ollama accepts
   // low/medium/high on `reasoning_effort` (verified against 0.32) and the
   // other OpenAI-compatible servers use the same three. A model that can't
   // reason at all already has no supported levels, so it never gets here.
@@ -1117,6 +1136,7 @@ export {
   NotLoggedInError,
   SubscriptionUsageError,
   TelegramBot,
+  XAI_OAUTH_KEY,
   XIAOMI_CREDITS_KEY,
   clearLocalDiscoveryCache,
   clearRuntimeModels,
@@ -1125,6 +1145,8 @@ export {
   decodeOggOpus,
   discoverLocalModels,
   downmixToMono,
+  dualAuthProvider,
+  dualAuthProviderByOAuthKey,
   endpointRoot,
   fetchSubscriptionUsage,
   findProbedModel,
@@ -1149,6 +1171,9 @@ export {
   getSupportedThinkingLevels,
   getToolResultCharLimit,
   getVideoByteLimit,
+  grokCliBaseUrl,
+  grokCliHeaders,
+  isGrokCliEndpoint,
   isKimiCodingEndpoint,
   isLocalModelId,
   isLoggerOpen,
@@ -1162,14 +1187,18 @@ export {
   loginGemini,
   loginKimi,
   loginOpenAI,
+  loginXai,
+  oauthStorageKey,
   openLog,
   parseLocalModelId,
   probeEndpoint,
+  providerStorageKeys,
   readStoredBaseUrlSync,
   refreshAnthropicToken,
   refreshGeminiToken,
   refreshKimiToken,
   refreshOpenAIToken,
+  refreshXaiToken,
   registerLogCleanup,
   registerRuntimeModels,
   resample,