@prestyj/core 5.8.0 → 5.10.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-export { ContextWindowOptions, DEFAULT_MAX_VIDEO_BYTES, MODELS, ModelInfo, getAuthStorageKey, getAuthStorageKeys, getContextWindow, getDefaultModel, getFastModel, getMaxThinkingLevel, getModel, getModelsForProvider, getSummaryModel, getToolResultCharLimit, getVideoByteLimit, usesOpenAICodexTransport } from './model-registry.cjs';
+import { ModelInfo } from './model-registry.cjs';
+export { ContextWindowOptions, DEFAULT_MAX_VIDEO_BYTES, MODELS, clearRuntimeModels, getAllModels, getAuthStorageKey, getAuthStorageKeys, getContextWindow, getDefaultModel, getDefaultThinkingLevel, getFastModel, getMaxThinkingLevel, getModel, getModelsForProvider, getSummaryModel, getToolResultCharLimit, getVideoByteLimit, registerRuntimeModels, usesOpenAICodexTransport } from './model-registry.cjs';
 import { Provider, ThinkingLevel } from '@prestyj/ai';
 export { AppPaths, getAppPaths } from './paths.cjs';
 
@@ -6,6 +7,120 @@ declare function getSupportedThinkingLevels(provider: Provider, model: string):
 declare function isThinkingLevelSupported(provider: Provider, model: string, level: ThinkingLevel): boolean;
 declare function getNextThinkingLevel(provider: Provider, model: string, current: ThinkingLevel | undefined): ThinkingLevel | undefined;
 
+/**
+ * Local model discovery — Ollama, LM Studio, llama.cpp (`llama-server`), vLLM,
+ * 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
+ * *capabilities* come from, because `GET /v1/models` reports nothing useful:
+ *
+ *   - Ollama    → `POST /api/show`      → `capabilities[]` + `model_info["<arch>.context_length"]`
+ *   - LM Studio → `GET /api/v0/models`  → `type`, `state`, `max_context_length`
+ *   - llama.cpp → `GET /props`          → `default_generation_settings.n_ctx`
+ *   - vLLM/other → nothing; `max_model_len` sometimes rides the model object.
+ *
+ * Probing never throws: an unreachable server is a normal state (the user just
+ * doesn't have it running), not an error to surface.
+ */
+
+/** Which capability API a local endpoint speaks, beyond plain `/v1/models`. */
+type LocalEndpointKind = "ollama" | "lmstudio" | "llamacpp" | "vllm" | "custom";
+interface LocalEndpoint {
+    /** Stable slug, used in model ids (`local/<id>/<rawId>`) and auth keys (`local:<id>`). */
+    id: string;
+    label: string;
+    /** OpenAI-compatible base URL, including the `/v1` suffix. */
+    baseUrl: string;
+    kind: LocalEndpointKind;
+    /** Optional bearer token (LM Studio 0.4+ can require one). */
+    apiKey?: string;
+    /** True for endpoints the user added by hand (removable). */
+    custom?: boolean;
+}
+/** One model as reported (and enriched) by a local server. */
+interface LocalModel {
+    /** Model id on the wire, exactly as the server names it (e.g. `qwen3-coder:30b`). */
+    rawId: string;
+    endpointId: string;
+    contextWindow: number;
+    /** True when the server told us the real window; false means we guessed. */
+    contextWindowKnown: boolean;
+    supportsTools: boolean;
+    supportsImages: boolean;
+    supportsThinking: boolean;
+    /** LM Studio only: whether the model is currently resident in memory. */
+    loaded?: boolean;
+}
+interface LocalEndpointProbe {
+    endpoint: LocalEndpoint;
+    reachable: boolean;
+    /** Human-readable reason when `reachable` is false (never a raw stack). */
+    reason?: string;
+    models: LocalModel[];
+}
+/**
+ * The servers we look for without being asked. Ports are each project's
+ * documented default; users who moved a port add a custom endpoint instead.
+ */
+declare const DEFAULT_LOCAL_ENDPOINTS: readonly LocalEndpoint[];
+/**
+ * Context window assumed when a server tells us nothing. Deliberately
+ * conservative: over-guessing means the provider 400s mid-run at a point
+ * auto-compaction already sailed past, while under-guessing only compacts early.
+ */
+declare const FALLBACK_CONTEXT_WINDOW = 8192;
+/** Placeholder token for endpoints with no key — these servers ignore it. */
+declare const LOCAL_API_KEY_PLACEHOLDER = "local";
+/**
+ * `local/<endpointId>/<rawModelId>`. The raw id can itself contain slashes
+ * (`hf.co/user/repo:q4`), so only the first two segments are structural.
+ */
+declare function formatLocalModelId(endpointId: string, rawId: string): string;
+declare function parseLocalModelId(id: string): {
+    endpointId: string;
+    rawId: string;
+} | undefined;
+declare function isLocalModelId(id: string): boolean;
+/** Auth-storage key holding the credential (and baseUrl) for one local endpoint. */
+declare function localAuthStorageKey(endpointId: string): string;
+/** Base URL with any trailing `/v1` (and trailing slashes) removed — the server root. */
+declare function endpointRoot(baseUrl: string): string;
+interface ProbeOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Ask one endpoint what it serves. Never throws — an unreachable server yields
+ * `{ reachable: false, reason }` so the UI can say "not running" without an
+ * error toast.
+ */
+declare function probeEndpoint(endpoint: LocalEndpoint, { timeoutMs, signal }?: ProbeOptions): Promise<LocalEndpointProbe>;
+/** Convert a probed local model into the registry shape the whole app speaks. */
+declare function toModelInfo(model: LocalModel, endpoint: LocalEndpoint): ModelInfo;
+interface DiscoveryResult {
+    probes: LocalEndpointProbe[];
+    models: ModelInfo[];
+}
+interface DiscoverOptions extends ProbeOptions {
+    /** Skip the 30s cache (the UI's "Scan" button). */
+    force?: boolean;
+}
+/**
+ * Probe every endpoint in parallel and return both the per-endpoint status (for
+ * the UI) and the `ModelInfo[]` ready for `registerRuntimeModels()`. Results are
+ * cached for 30s per endpoint set so repeated `GET /models` calls don't re-probe
+ * four servers; `force` bypasses it after an `ollama pull`.
+ */
+declare function discoverLocalModels(endpoints?: readonly LocalEndpoint[], options?: DiscoverOptions): Promise<DiscoveryResult>;
+/** Drop the discovery cache (used by tests and after an endpoint is added/removed). */
+declare function clearLocalDiscoveryCache(): void;
+/** Look up the probed capabilities of a discovered model, by full local id. */
+declare function findProbedModel(probes: readonly LocalEndpointProbe[], modelId: string): {
+    model: LocalModel;
+    endpoint: LocalEndpoint;
+} | undefined;
+
 type LogLevel = "INFO" | "ERROR" | "WARN" | "DEBUG";
 /**
  * Open the debug log in append mode, tagging this process with a session id and
@@ -55,6 +170,10 @@ interface OAuthCredentials {
     accessToken: string;
     refreshToken: string;
     expiresAt: number;
+    /** Original token lifetime in seconds (the provider's `expires_in`). Used to
+     *  scale the proactive-refresh threshold: short-lived tokens (e.g. Kimi's
+     *  15-min access token) must refresh well before expiry, not 60s prior. */
+    expiresIn?: number;
     accountId?: string;
     projectId?: string;
     baseUrl?: string;
@@ -85,6 +204,22 @@ declare const MOONSHOT_OAUTH_KEY = "moonshot-oauth";
  * order, is decided per-model via `getAuthStorageKeys()` in model-registry.ts.
  */
 declare const XIAOMI_CREDITS_KEY = "xiaomi-credits";
+/**
+ * Prefix for local-endpoint credentials (`local:ollama`, `local:lmstudio`, …).
+ * One entry per endpoint, each carrying that endpoint's `baseUrl`, so the
+ * existing `resolveCredentials({ storageKeys })` override resolves a local model
+ * with no new code path. Kept in sync with `localAuthStorageKey()` in
+ * local-models.ts.
+ */
+declare const LOCAL_AUTH_KEY_PREFIX = "local:";
+/**
+ * Synchronous baseUrl read straight from the auth file, for boot paths that
+ * need the active endpoint before an AuthStorage instance exists (e.g. the
+ * CLI's sync main()). Missing/corrupt files yield undefined — callers treat
+ * that as the provider's public endpoint. Read-only: safe without the file
+ * lock (a torn mid-write read just falls back to undefined).
+ */
+declare function readStoredBaseUrlSync(authFile: string, provider: string): string | undefined;
 declare class AuthStorage {
     private data;
     private filePath;
@@ -112,22 +247,47 @@ declare class AuthStorage {
      * Moonshot API key.
      */
     hasProviderAuth(provider: string): Promise<boolean>;
+    /** Endpoint ids that currently have a `local:<id>` credential stored. */
+    listLocalEndpointIds(): Promise<string[]>;
+    /**
+     * Write (or refresh) the credential for one local endpoint. The `baseUrl` is
+     * what `effectiveBaseUrl` later picks up, and `accessToken` is the endpoint's
+     * key — a placeholder for the servers that ignore it.
+     */
+    setLocalEndpoint(endpointId: string, baseUrl: string, apiKey?: string): Promise<void>;
+    /** Remove one local endpoint's credential. No-op when it isn't stored. */
+    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).
      */
     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).
+     */
+    getStoredBaseUrl(provider: string): string | undefined;
     load(): Promise<void>;
     private ensureLoaded;
     /**
      * Force a re-read from disk, discarding the in-memory cache. Needed when
      * another process mutates the auth file out-of-band — e.g. the desktop app
-     * writes API keys natively (Rust → ~/.ezcoder/auth.json) without going through
-     * this instance, so a long-lived daemon's cache would otherwise stay stale and
-     * never see a newly added provider key.
+     * writes API keys natively without going through this instance.
      */
     reload(): Promise<void>;
+    /**
+     * Apply one provider-scoped mutation to the latest on-disk snapshot.
+     * AuthStorage instances live in every app session/process, so writing this
+     * instance's cached snapshot can erase credentials another instance just
+     * added. The file lock only serializes writers; the re-read prevents stale
+     * full-file overwrites.
+     */
+    private mutateLatest;
+    private reloadLatest;
     getCredentials(provider: string): Promise<OAuthCredentials | undefined>;
     setCredentials(provider: string, creds: OAuthCredentials): Promise<void>;
     clearCredentials(provider: string): Promise<void>;
@@ -159,14 +319,13 @@ declare class AuthStorage {
      * Throws if not logged in.
      */
     resolveToken(provider: string): Promise<string>;
-    private save;
 }
 declare class NotLoggedInError extends Error {
     provider: string;
     constructor(provider: string);
 }
 
-type SubscriptionUsageProvider = "anthropic" | "openai";
+type SubscriptionUsageProvider = "anthropic" | "openai" | "moonshot";
 interface SubscriptionUsageWindow {
     kind: "current" | "weekly";
     label: string;
@@ -182,7 +341,8 @@ interface SubscriptionUsageSnapshot {
 }
 declare class SubscriptionUsageError extends Error {
     readonly status?: number | undefined;
-    constructor(message: string, status?: number | undefined);
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, status?: number | undefined, retryAfterMs?: number | undefined);
 }
 type FetchFn = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface FetchSubscriptionUsageOptions {
@@ -430,4 +590,4 @@ interface AutoUpdater {
 }
 declare function createAutoUpdater(config: AutoUpdateConfig): AutoUpdater;
 
-export { AuthStorage, type AutoUpdateConfig, type AutoUpdater, type InlineButton, type LogLevel, MOONSHOT_OAUTH_KEY, NotLoggedInError, type OAuthCredentials, type OAuthLoginCallbacks, type ProgressCallback, SubscriptionUsageError, type SubscriptionUsageProvider, type SubscriptionUsageSnapshot, type SubscriptionUsageWindow, TelegramBot, type TelegramConfig, type TelegramMessage, type TelegramUpdate, type TelegramVoiceMessage, XIAOMI_CREDITS_KEY, closeLogger, createAutoUpdater, decodeOggOpus, downmixToMono, fetchSubscriptionUsage, generatePKCE, getClaudeCliUserAgent, getClaudeCodeVersion, getNextThinkingLevel, getSessionId, getSupportedThinkingLevels, isKimiCodingEndpoint, isLoggerOpen, isModelLoaded, isThinkingLevelSupported, kimiCodeBaseUrl, kimiCodingHeaders, log, loginAnthropic, loginGemini, loginKimi, loginOpenAI, openLog, refreshAnthropicToken, refreshGeminiToken, refreshKimiToken, refreshOpenAIToken, registerLogCleanup, resample, setProgressCallback, transcribeVoice, withFileLock };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { ContextWindowOptions, DEFAULT_MAX_VIDEO_BYTES, MODELS, ModelInfo, getAuthStorageKey, getAuthStorageKeys, getContextWindow, getDefaultModel, getFastModel, getMaxThinkingLevel, getModel, getModelsForProvider, getSummaryModel, getToolResultCharLimit, getVideoByteLimit, usesOpenAICodexTransport } from './model-registry.js';
+import { ModelInfo } from './model-registry.js';
+export { ContextWindowOptions, DEFAULT_MAX_VIDEO_BYTES, MODELS, clearRuntimeModels, getAllModels, getAuthStorageKey, getAuthStorageKeys, getContextWindow, getDefaultModel, getDefaultThinkingLevel, getFastModel, getMaxThinkingLevel, getModel, getModelsForProvider, getSummaryModel, getToolResultCharLimit, getVideoByteLimit, registerRuntimeModels, usesOpenAICodexTransport } from './model-registry.js';
 import { Provider, ThinkingLevel } from '@prestyj/ai';
 export { AppPaths, getAppPaths } from './paths.js';
 
@@ -6,6 +7,120 @@ declare function getSupportedThinkingLevels(provider: Provider, model: string):
 declare function isThinkingLevelSupported(provider: Provider, model: string, level: ThinkingLevel): boolean;
 declare function getNextThinkingLevel(provider: Provider, model: string, current: ThinkingLevel | undefined): ThinkingLevel | undefined;
 
+/**
+ * Local model discovery — Ollama, LM Studio, llama.cpp (`llama-server`), vLLM,
+ * 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
+ * *capabilities* come from, because `GET /v1/models` reports nothing useful:
+ *
+ *   - Ollama    → `POST /api/show`      → `capabilities[]` + `model_info["<arch>.context_length"]`
+ *   - LM Studio → `GET /api/v0/models`  → `type`, `state`, `max_context_length`
+ *   - llama.cpp → `GET /props`          → `default_generation_settings.n_ctx`
+ *   - vLLM/other → nothing; `max_model_len` sometimes rides the model object.
+ *
+ * Probing never throws: an unreachable server is a normal state (the user just
+ * doesn't have it running), not an error to surface.
+ */
+
+/** Which capability API a local endpoint speaks, beyond plain `/v1/models`. */
+type LocalEndpointKind = "ollama" | "lmstudio" | "llamacpp" | "vllm" | "custom";
+interface LocalEndpoint {
+    /** Stable slug, used in model ids (`local/<id>/<rawId>`) and auth keys (`local:<id>`). */
+    id: string;
+    label: string;
+    /** OpenAI-compatible base URL, including the `/v1` suffix. */
+    baseUrl: string;
+    kind: LocalEndpointKind;
+    /** Optional bearer token (LM Studio 0.4+ can require one). */
+    apiKey?: string;
+    /** True for endpoints the user added by hand (removable). */
+    custom?: boolean;
+}
+/** One model as reported (and enriched) by a local server. */
+interface LocalModel {
+    /** Model id on the wire, exactly as the server names it (e.g. `qwen3-coder:30b`). */
+    rawId: string;
+    endpointId: string;
+    contextWindow: number;
+    /** True when the server told us the real window; false means we guessed. */
+    contextWindowKnown: boolean;
+    supportsTools: boolean;
+    supportsImages: boolean;
+    supportsThinking: boolean;
+    /** LM Studio only: whether the model is currently resident in memory. */
+    loaded?: boolean;
+}
+interface LocalEndpointProbe {
+    endpoint: LocalEndpoint;
+    reachable: boolean;
+    /** Human-readable reason when `reachable` is false (never a raw stack). */
+    reason?: string;
+    models: LocalModel[];
+}
+/**
+ * The servers we look for without being asked. Ports are each project's
+ * documented default; users who moved a port add a custom endpoint instead.
+ */
+declare const DEFAULT_LOCAL_ENDPOINTS: readonly LocalEndpoint[];
+/**
+ * Context window assumed when a server tells us nothing. Deliberately
+ * conservative: over-guessing means the provider 400s mid-run at a point
+ * auto-compaction already sailed past, while under-guessing only compacts early.
+ */
+declare const FALLBACK_CONTEXT_WINDOW = 8192;
+/** Placeholder token for endpoints with no key — these servers ignore it. */
+declare const LOCAL_API_KEY_PLACEHOLDER = "local";
+/**
+ * `local/<endpointId>/<rawModelId>`. The raw id can itself contain slashes
+ * (`hf.co/user/repo:q4`), so only the first two segments are structural.
+ */
+declare function formatLocalModelId(endpointId: string, rawId: string): string;
+declare function parseLocalModelId(id: string): {
+    endpointId: string;
+    rawId: string;
+} | undefined;
+declare function isLocalModelId(id: string): boolean;
+/** Auth-storage key holding the credential (and baseUrl) for one local endpoint. */
+declare function localAuthStorageKey(endpointId: string): string;
+/** Base URL with any trailing `/v1` (and trailing slashes) removed — the server root. */
+declare function endpointRoot(baseUrl: string): string;
+interface ProbeOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Ask one endpoint what it serves. Never throws — an unreachable server yields
+ * `{ reachable: false, reason }` so the UI can say "not running" without an
+ * error toast.
+ */
+declare function probeEndpoint(endpoint: LocalEndpoint, { timeoutMs, signal }?: ProbeOptions): Promise<LocalEndpointProbe>;
+/** Convert a probed local model into the registry shape the whole app speaks. */
+declare function toModelInfo(model: LocalModel, endpoint: LocalEndpoint): ModelInfo;
+interface DiscoveryResult {
+    probes: LocalEndpointProbe[];
+    models: ModelInfo[];
+}
+interface DiscoverOptions extends ProbeOptions {
+    /** Skip the 30s cache (the UI's "Scan" button). */
+    force?: boolean;
+}
+/**
+ * Probe every endpoint in parallel and return both the per-endpoint status (for
+ * the UI) and the `ModelInfo[]` ready for `registerRuntimeModels()`. Results are
+ * cached for 30s per endpoint set so repeated `GET /models` calls don't re-probe
+ * four servers; `force` bypasses it after an `ollama pull`.
+ */
+declare function discoverLocalModels(endpoints?: readonly LocalEndpoint[], options?: DiscoverOptions): Promise<DiscoveryResult>;
+/** Drop the discovery cache (used by tests and after an endpoint is added/removed). */
+declare function clearLocalDiscoveryCache(): void;
+/** Look up the probed capabilities of a discovered model, by full local id. */
+declare function findProbedModel(probes: readonly LocalEndpointProbe[], modelId: string): {
+    model: LocalModel;
+    endpoint: LocalEndpoint;
+} | undefined;
+
 type LogLevel = "INFO" | "ERROR" | "WARN" | "DEBUG";
 /**
  * Open the debug log in append mode, tagging this process with a session id and
@@ -55,6 +170,10 @@ interface OAuthCredentials {
     accessToken: string;
     refreshToken: string;
     expiresAt: number;
+    /** Original token lifetime in seconds (the provider's `expires_in`). Used to
+     *  scale the proactive-refresh threshold: short-lived tokens (e.g. Kimi's
+     *  15-min access token) must refresh well before expiry, not 60s prior. */
+    expiresIn?: number;
     accountId?: string;
     projectId?: string;
     baseUrl?: string;
@@ -85,6 +204,22 @@ declare const MOONSHOT_OAUTH_KEY = "moonshot-oauth";
  * order, is decided per-model via `getAuthStorageKeys()` in model-registry.ts.
  */
 declare const XIAOMI_CREDITS_KEY = "xiaomi-credits";
+/**
+ * Prefix for local-endpoint credentials (`local:ollama`, `local:lmstudio`, …).
+ * One entry per endpoint, each carrying that endpoint's `baseUrl`, so the
+ * existing `resolveCredentials({ storageKeys })` override resolves a local model
+ * with no new code path. Kept in sync with `localAuthStorageKey()` in
+ * local-models.ts.
+ */
+declare const LOCAL_AUTH_KEY_PREFIX = "local:";
+/**
+ * Synchronous baseUrl read straight from the auth file, for boot paths that
+ * need the active endpoint before an AuthStorage instance exists (e.g. the
+ * CLI's sync main()). Missing/corrupt files yield undefined — callers treat
+ * that as the provider's public endpoint. Read-only: safe without the file
+ * lock (a torn mid-write read just falls back to undefined).
+ */
+declare function readStoredBaseUrlSync(authFile: string, provider: string): string | undefined;
 declare class AuthStorage {
     private data;
     private filePath;
@@ -112,22 +247,47 @@ declare class AuthStorage {
      * Moonshot API key.
      */
     hasProviderAuth(provider: string): Promise<boolean>;
+    /** Endpoint ids that currently have a `local:<id>` credential stored. */
+    listLocalEndpointIds(): Promise<string[]>;
+    /**
+     * Write (or refresh) the credential for one local endpoint. The `baseUrl` is
+     * what `effectiveBaseUrl` later picks up, and `accessToken` is the endpoint's
+     * key — a placeholder for the servers that ignore it.
+     */
+    setLocalEndpoint(endpointId: string, baseUrl: string, apiKey?: string): Promise<void>;
+    /** Remove one local endpoint's credential. No-op when it isn't stored. */
+    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).
      */
     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).
+     */
+    getStoredBaseUrl(provider: string): string | undefined;
     load(): Promise<void>;
     private ensureLoaded;
     /**
      * Force a re-read from disk, discarding the in-memory cache. Needed when
      * another process mutates the auth file out-of-band — e.g. the desktop app
-     * writes API keys natively (Rust → ~/.ezcoder/auth.json) without going through
-     * this instance, so a long-lived daemon's cache would otherwise stay stale and
-     * never see a newly added provider key.
+     * writes API keys natively without going through this instance.
      */
     reload(): Promise<void>;
+    /**
+     * Apply one provider-scoped mutation to the latest on-disk snapshot.
+     * AuthStorage instances live in every app session/process, so writing this
+     * instance's cached snapshot can erase credentials another instance just
+     * added. The file lock only serializes writers; the re-read prevents stale
+     * full-file overwrites.
+     */
+    private mutateLatest;
+    private reloadLatest;
     getCredentials(provider: string): Promise<OAuthCredentials | undefined>;
     setCredentials(provider: string, creds: OAuthCredentials): Promise<void>;
     clearCredentials(provider: string): Promise<void>;
@@ -159,14 +319,13 @@ declare class AuthStorage {
      * Throws if not logged in.
      */
     resolveToken(provider: string): Promise<string>;
-    private save;
 }
 declare class NotLoggedInError extends Error {
     provider: string;
     constructor(provider: string);
 }
 
-type SubscriptionUsageProvider = "anthropic" | "openai";
+type SubscriptionUsageProvider = "anthropic" | "openai" | "moonshot";
 interface SubscriptionUsageWindow {
     kind: "current" | "weekly";
     label: string;
@@ -182,7 +341,8 @@ interface SubscriptionUsageSnapshot {
 }
 declare class SubscriptionUsageError extends Error {
     readonly status?: number | undefined;
-    constructor(message: string, status?: number | undefined);
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, status?: number | undefined, retryAfterMs?: number | undefined);
 }
 type FetchFn = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface FetchSubscriptionUsageOptions {
@@ -430,4 +590,4 @@ interface AutoUpdater {
 }
 declare function createAutoUpdater(config: AutoUpdateConfig): AutoUpdater;
 
-export { AuthStorage, type AutoUpdateConfig, type AutoUpdater, type InlineButton, type LogLevel, MOONSHOT_OAUTH_KEY, NotLoggedInError, type OAuthCredentials, type OAuthLoginCallbacks, type ProgressCallback, SubscriptionUsageError, type SubscriptionUsageProvider, type SubscriptionUsageSnapshot, type SubscriptionUsageWindow, TelegramBot, type TelegramConfig, type TelegramMessage, type TelegramUpdate, type TelegramVoiceMessage, XIAOMI_CREDITS_KEY, closeLogger, createAutoUpdater, decodeOggOpus, downmixToMono, fetchSubscriptionUsage, generatePKCE, getClaudeCliUserAgent, getClaudeCodeVersion, getNextThinkingLevel, getSessionId, getSupportedThinkingLevels, isKimiCodingEndpoint, isLoggerOpen, isModelLoaded, isThinkingLevelSupported, kimiCodeBaseUrl, kimiCodingHeaders, log, loginAnthropic, loginGemini, loginKimi, loginOpenAI, openLog, refreshAnthropicToken, refreshGeminiToken, refreshKimiToken, refreshOpenAIToken, registerLogCleanup, resample, setProgressCallback, transcribeVoice, withFileLock };
+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 };