@maudecode/talaria-web 1.18.0 → 1.20.0

package/dist/providers/catalog.d.ts

@@ -1,19 +1,44 @@
+/**
+ * Provider cards, the model picker catalog, live model lists, quotas and cost
+ * history (Python `api/providers.py`, the `/api/models` parts of
+ * `api/config.py`, `_handle_live_models`).
+ *
+ * The Agent's own primitives (registry, auth status, live model ids, account
+ * usage) come through the sidecar; the static tables and key detection live
+ * here. ponytail: one live-id cache with a 24h TTL replaces the Python
+ * publisher/provenance machinery; `refresh()` evicts it.
+ */
+import type { DocumentBackend } from '../sessions/storage/backend.js';
 import type { SidecarLike } from '../sidecar/client.js';
-import type { SidecarResult } from '@maudecode/talaria-web-contracts';
+import type { CatalogAvailability, SidecarResult } from '@maudecode/talaria-web-contracts';
 import { type QuotaThresholds } from '../settings.js';
-import { type AgentConfig, type Config, type Dict } from '../config/agent-config.js';
+import { type AgentConfig, type Config, type Dict, type SpeedTier } from '../config/agent-config.js';
 export interface ModelEntry {
     id: string;
     label: string;
     supports_fast_tier?: boolean;
+    supported_speed_tiers?: SpeedTier[];
     provider_id?: string;
     bare_id?: string;
+    limit?: {
+        scope: 'model';
+        resets_at: string;
+    };
 }
 export interface ModelGroup {
+    availability?: CatalogAvailability;
     provider: string;
     provider_id: string;
     models: ModelEntry[];
     extra_models?: ModelEntry[];
+    limit?: {
+        scope: 'account';
+        resets_at: string;
+    } | {
+        scope: 'models';
+        models: Record<string, string>;
+    };
+    quota_level?: QuotaLevel;
 }
 /** TAL-301: the catalog entry a stored `(model, provider)` pair selects, so clients render the pairing instead of computing it. */
 export declare function catalogOptionId(catalog: ModelsCatalog, model: string | null, provider: string | null): string | null;
@@ -28,6 +53,7 @@ export declare function repairSessionModel(catalog: ModelsCatalog, model: string
 /** Python `_split_picker_overflow_models`: past 25 rows the picker shows 15, keeping the selected model visible. */
 export declare function splitPickerOverflow(models: ModelEntry[], selected: string, providerId: string): [ModelEntry[], ModelEntry[]];
 export interface ModelsCatalog {
+    availability?: CatalogAvailability;
     active_provider: string | null;
     default_model: string;
     default_provider_id?: string | null;
@@ -63,9 +89,9 @@ export interface CatalogDeps {
     /** Whether `profileHome` is the default profile's home (`$HERMES_HOME`). */
     isRootProfileHome: (profileHome: string) => boolean;
     /** WebUI state directory; holds `.quota_scope_id`, the stable public identity namespace for quota sources. */
-    stateDir?: string;
+    documents?: DocumentBackend;
     /** Settings `provider_quota_thresholds` for a profile; defaults when absent. */
-    quotaThresholds?: (profile: string) => QuotaThresholds;
+    quotaThresholds?: (profile: string) => Promise<QuotaThresholds>;
 }
 /** ISO-8601 UTC for epoch seconds, without a `.000` fraction. */
 export declare const isoAt: (seconds: number) => string;
@@ -134,6 +160,8 @@ export declare function classifyQuotaSource<T extends {
     windows: ClassifiedQuotaWindow[];
     urgency: QuotaUrgency;
 };
+/** A provider's name as the catalog lists it (a named custom endpoint's configured name, a plugin's display name), else its static display name. */
+export declare function providerLabel(catalog: ModelsCatalog | undefined, provider: string): string;
 export declare function displayName(pid: string): string;
 /** Python `_format_ollama_label`. */
 export declare function formatOllamaLabel(mid: string): string;
@@ -154,9 +182,14 @@ export declare function uniqueQuotaSources<T extends {
 }>(sources: T[]): T[];
 export declare class ProviderCatalog {
     private readonly deps;
+    private readonly scopedKeyRevisions;
+    private readonly scopedKeyAuthority;
+    private readonly modelGenerations;
+    private readonly modelReads;
+    private readonly credentialReads;
     /** Failed live lookups by home, provider, and the `sourceFingerprint` they ran under (TAL-542). */
     private readonly liveFailed;
-    /** `source`: the `sourceFingerprint` the ids were fetched under; another one makes them stale (TAL-542). */
+    /** `source`: the `sourceFingerprint` the ids were fetched under; another one makes them stale (TAL-542). `ttl`: seconds they stay fresh. */
     private readonly liveIds;
     private readonly liveInflight;
     /** `pooled`: the fill's `poolProviders` answer, null when unknown (TAL-638). */
@@ -172,13 +205,17 @@ export declare class ProviderCatalog {
         models: number;
         age_seconds: number | null;
     };
-    invalidate(profileHome?: string, provider?: string): void;
+    invalidate(profileHome?: string, provider?: string, opts?: {
+        preserveConfirmed?: boolean;
+    }): void;
     /** TAL-301: the entry id a stored `(model, provider)` pair selects in the last catalog built for this home; a cold home starts building one. */
     modelOptionFor(profileHome: string, model: string | null, provider: string | null): string | null;
+    /** TAL-821: `providerLabel` against the last catalog built for this home; a cold home starts building one. */
+    providerLabel(profileHome: string, provider: string): string;
     /**
      * TAL-542: the identity of the files a catalog and its live ids derive from: config.yaml, `.env`, the Agent's sign-in
      * store (`auth.json`, rewritten by an account switch), and the installed plugins directory, so a change outside Web
-     * makes both stale.
+     * makes both stale. Opaque scoped-key revisions cover external secret sources without exposing their keys.
      */
     private sourceFingerprint;
     /** The last catalog built for this home, younger than `maxAgeS`, while its source files are unchanged since (TAL-542). */
@@ -190,10 +227,12 @@ export declare class ProviderCatalog {
      */
     sessionModelRepair(profileHome: string, model: string, provider: string | null): [string, string] | null;
     /**
-     * Builds the catalog `sessionModelRepair` reads unless a fresh enough one exists; call it after the request's last
-     * await. A source that changed while the build awaited makes that build stale, so it is rebuilt once.
+     * Explicitly await discovery, or start it in the background from `sessionModelRepair`. Admission never awaits it.
+     * A source that changed while the build awaited makes that build stale, so it is rebuilt once.
      */
     warmSessionModelRepair(profileHome: string): Promise<void>;
+    /** TAL-1381: warms this home's catalog once, then answers `modelOptionFor` synchronously for every row of a batch. */
+    modelOptionResolver(profileHome: string): Promise<(model: string | null, provider: string | null) => string | null>;
     /** Builds the catalog `modelOptionFor` reads once per home, again after config.yaml or `.env` changes; an unavailable catalog leaves every option id null. */
     warmModelOptions(profileHome: string): Promise<void>;
     /**
@@ -213,27 +252,52 @@ export declare class ProviderCatalog {
     /** Live model ids from the Agent for one provider, cached per profile home. */
     liveModelIds(profileHome: string, pid: string, opts?: {
         force?: boolean;
+        source?: string;
     }): Promise<string[]>;
+    /** Whether the last live lookup for this provider under `source` failed or answered with the Agent's placeholder list. */
+    private liveLookupFailed;
     /**
      * TAL-288: the model-provider plugins installed and enabled in this profile, as the sidecar reads them from the Agent.
      * A failed lookup lists none, so every other provider stays usable; an id that cannot be a provider routing hint is dropped.
      */
     private pluginProviders;
+    /**
+     * TAL-798: the GGUFs staged for the Agent's managed llama.cpp provider, selectable before its server runs (a turn boots
+     * it). Null when none are staged or the listing failed, so every other provider stays usable.
+     */
+    private localModels;
     /** Python `get_providers`. */
     providers(profileHome: string): Promise<{
         providers: Dict[];
         active_provider: string | null;
+        availability: CatalogAvailability;
     }>;
     /** The cached `providers` answer, shared with `quotas`; callers never mutate it. */
     private providerRows;
     /** Python `get_available_models` (static catalog + live ids for keyed providers). */
-    models(profileHome: string): Promise<ModelsCatalog>;
+    models(profileHome: string, attempt?: number): Promise<ModelsCatalog>;
+    private buildModels;
+    private readonly pickerLimitsCache;
+    /** Bounded, shared pool-limit reads; a warm picker serves its snapshot during refresh. */
+    private pickerLimits;
+    /** TAL-807: the picker adds pool limits and quota levels without storing them in the model catalog. */
+    pickerModels(profileHome: string, profile: string): Promise<ModelsCatalog>;
+    /** TAL-807: account-usage reads the picker started, by `accountUsageCache` key. */
+    private readonly pickerUsageReads;
+    /**
+     * TAL-807: the TAL-411 `remaining` level of the tightest account-scope window in the provider's cached account-usage
+     * read; a model-family window (Opus or Sonnet weekly) never counts. A read past the cache TTL starts a new one, which
+     * the picker waits for only when it has no read at all, and then for at most `PICKER_USAGE_WAIT_MS`; one past
+     * `PICKER_USAGE_MAX_AGE_S` shows nothing.
+     */
+    private pickerQuotaLevel;
     /** Stamps the default's entry id and keeps the catalog for `modelOptionFor`. */
     private remember;
     /** Python `_configured_model_badges_from_static_catalog`: which picker rows are the main/fallback selections. */
     private badges;
     /** Python `_handle_live_models`. */
-    liveModels(profileHome: string, providerRaw: string): Promise<Dict>;
+    liveModels(profileHome: string, providerRaw: string, attempt?: number): Promise<Dict>;
+    private stampSpeedTiers;
     /**
      * Python `_resolve_model_context_length` inputs: the effective base URL, key, and any configured window for this
      * model under this profile (`model.context_length`, `providers.<p>.models[].context_length`, custom providers).
@@ -244,8 +308,11 @@ export declare class ProviderCatalog {
         config_context_length?: number | null;
     }>;
     private apiKeyFor;
+    /** A raw key or the names the Agent resolves inside the profile's secret scope. */
+    private usageKey;
     /** Account-usage snapshots by profile home, provider, and pool account. */
     private readonly accountUsageCache;
+    private quotaReadSequence;
     /**
      * Python `get_provider_quota`. `credential` scopes the read to one credential-pool account (TAL-548): a benched account
      * answers with its local pool state, and every other read uses that account's key.
@@ -254,6 +321,7 @@ export declare class ProviderCatalog {
         refresh?: boolean;
         at?: number;
         credential?: PoolEntry | null;
+        sequence?: number;
     }): Promise<Dict>;
     /**
      * TAL-548: the provider's credential-pool accounts as the sidecar reads them locally. Each says whether it holds
@@ -267,7 +335,7 @@ export declare class ProviderCatalog {
      * lookup, else null: an unknown pool, never an empty one, so no pool account is ever reported as removed.
      */
     private poolLookup;
-    /** TAL-548: the providers whose persisted credential pool holds an added account; none when the sidecar cannot say. */
+    /** One shared read of pool membership and scoped key revisions before reusing catalog data. */
     private poolProviders;
     /** TAL-548: one key-based balance read through the sidecar, which resolves a pool account's key itself; null when it fails. */
     private balance;
@@ -275,7 +343,7 @@ export declare class ProviderCatalog {
     /** Python `_quota_server_scope_id`: a 32-hex id persisted at `<state>/.quota_scope_id` (created atomically once). */
     private quotaServerScopeId;
     /** Python `_quota_profile_scope_id`. */
-    quotaProfileScopeId(profile: string): string;
+    quotaProfileScopeId(profile: string): Promise<string>;
     /**
      * Python `get_provider_quotas`: the stable-identity envelope the iOS widget persists. A keyed provider is one source per
      * credential-pool account, else one for its own key (Python `_quota_source_descriptors`, TAL-548). Each source id appears
@@ -284,7 +352,10 @@ export declare class ProviderCatalog {
     quotas(profileHome: string, profile: string, opts?: {
         sourceId?: string | null;
         refresh?: boolean;
-    }): Promise<Dict>;
+    }, attempt?: number): Promise<Dict>;
+    private readonly lastQuotaSources;
+    private staleQuotaSource;
+    private availability;
     /** Python `get_provider_cost_history` (OpenRouter only; daily snapshots under `<home>/cost-snapshots`). */
     costHistory(profileHome: string, providerRaw: string | null, days: number): Promise<Dict>;
     private readCostSnapshots;