@maudecode/talaria-web 1.16.1 → 1.18.0

package/dist/providers/catalog.d.ts

@@ -1,4 +1,6 @@
 import type { SidecarLike } from '../sidecar/client.js';
+import type { SidecarResult } from '@maudecode/talaria-web-contracts';
+import { type QuotaThresholds } from '../settings.js';
 import { type AgentConfig, type Config, type Dict } from '../config/agent-config.js';
 export interface ModelEntry {
     id: string;
@@ -15,6 +17,14 @@ export interface ModelGroup {
 }
 /** 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;
+/**
+ * TAL-542 (Python `_resolve_compatible_session_model_state` + `_repair_foreign_session_model_provider`): the pair a
+ * session's stale model starts on. A model its provider's catalog group does not list moves to the one other provider
+ * that lists it; else, when the model names another vendor than a first-party provider, to the profile default. No
+ * evidence (no group for the provider, a group built from a failed live lookup in `unlisted`, which never names an owner either) keeps the pair, and so does a stored
+ * provider that is the profile's own unless the model names another vendor. `null` keeps the pair.
+ */
+export declare function repairSessionModel(catalog: ModelsCatalog, model: string, provider: string | null, unlisted?: ReadonlySet<string>): [string, string] | null;
 /** 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 {
@@ -50,11 +60,12 @@ export interface CatalogDeps {
     log: (line: string) => void;
     /** Settings `provider_cost_budget` (monthly). */
     costBudget: () => number | null;
-    fetch?: typeof fetch;
     /** 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;
+    /** Settings `provider_quota_thresholds` for a profile; defaults when absent. */
+    quotaThresholds?: (profile: string) => QuotaThresholds;
 }
 /** ISO-8601 UTC for epoch seconds, without a `.000` fraction. */
 export declare const isoAt: (seconds: number) => string;
@@ -99,6 +110,30 @@ export declare function quotaForecast(pace: QuotaPace, remaining: number | null)
  * as of `nowSeconds`; the indexes name the windows the App shows for pace, session and weekly selections.
  */
 export declare function normalizeQuotaWindows(raw: unknown, nowSeconds: number): QuotaWindows;
+export type QuotaLevel = 'healthy' | 'warning' | 'critical' | 'stale' | 'unavailable';
+export interface QuotaUrgency {
+    remaining: QuotaLevel;
+    pace: QuotaLevel;
+}
+/**
+ * TAL-411: each window's `projection_eligible`, `urgency` per colour basis, and `pace.status` (over/on/under the
+ * tolerance), and the source's `urgency` on the windows a widget shows by default (the first; the pace window for pace).
+ */
+export interface ClassifiedQuotaWindow extends Omit<QuotaWindow, 'pace'> {
+    pace: (QuotaPace & {
+        status: 'over' | 'on' | 'under';
+    }) | null;
+    projection_eligible: boolean;
+    urgency: QuotaUrgency;
+}
+export declare function classifyQuotaSource<T extends {
+    status: string;
+    windows: QuotaWindow[];
+    pace_window_index: number | null;
+}>(source: T, t: QuotaThresholds): Omit<T, 'windows'> & {
+    windows: ClassifiedQuotaWindow[];
+    urgency: QuotaUrgency;
+};
 export declare function displayName(pid: string): string;
 /** Python `_format_ollama_label`. */
 export declare function formatOllamaLabel(mid: string): string;
@@ -109,6 +144,8 @@ export declare function providerEnvVar(pid: string): string | null;
 export declare function applyProviderPrefix(models: ModelEntry[], pid: string, active: string | null): ModelEntry[];
 /** Python `_deduplicate_model_ids`: later duplicate ids (by provider-id order) gain an `@provider:` prefix. */
 export declare function deduplicateModelIds(groups: ModelGroup[]): void;
+/** TAL-548: one credential-pool account's local state, as the sidecar reads it without probing. */
+type PoolEntry = SidecarResult<'usage.pool'>['entries'][number];
 /** Quota sources keep the first row per source id, ordered by provider id, account label, then source id (TAL-272). */
 export declare function uniqueQuotaSources<T extends {
     source_id: string;
@@ -117,12 +154,17 @@ export declare function uniqueQuotaSources<T extends {
 }>(sources: T[]): T[];
 export declare class ProviderCatalog {
     private readonly deps;
+    /** 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). */
     private readonly liveIds;
     private readonly liveInflight;
+    /** `pooled`: the fill's `poolProviders` answer, null when unknown (TAL-638). */
     private readonly providersCache;
     /** TAL-301: the last catalog served per profile home, for the sync session payloads' `model_option_id`. */
     private readonly lastModels;
+    /** TAL-542: per `lastModels` catalog, the `sourceFingerprint` it was built from, when, and the providers whose group came from a failed live lookup. */
+    private readonly lastModelsMeta;
     constructor(deps: CatalogDeps);
     /** Python `models_cache` diagnostics: live-id groups held, ids across them, and the oldest snapshot's age. */
     diagnosticSnapshot(): {
@@ -133,16 +175,40 @@ export declare class ProviderCatalog {
     invalidate(profileHome?: string, provider?: string): 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;
-    /** Builds the catalog `modelOptionFor` reads once per home; an unavailable catalog leaves every option id null. */
+    /**
+     * 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.
+     */
+    private sourceFingerprint;
+    /** The last catalog built for this home, younger than `maxAgeS`, while its source files are unchanged since (TAL-542). */
+    private currentModels;
+    /**
+     * TAL-542: `repairSessionModel` against this home's catalog. Agent-owned sign-in and plugin state has no file to
+     * fingerprint, so the repair also needs a catalog no older than the providers listing it read (`PROVIDERS_TTL_S`);
+     * a cold or stale one keeps the pair and starts a rebuild.
+     */
+    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.
+     */
+    warmSessionModelRepair(profileHome: string): Promise<void>;
+    /** 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>;
     /**
      * The process-environment value of `name` as a named profile may see it: values `loadStartupEnv` copied from the
      * default profile's `.env` belong to that profile only, so they never count for another profile.
      */
+    /** `cleared`: the variable a key delete clears, which also retires its `.env`-owned startup copy (TAL-641). */
     private processEnv;
-    /** Python `_provider_has_key` minus the credential pool (the sidecar answers OAuth/pool state). */
-    providerHasKey(pid: string, config: Config, envValues: Record<string, string>, profileHome: string): boolean;
+    /**
+     * Python `_provider_has_key` minus the credential pool, which `probeKey` reads from the sidecar.
+     * `cleared` (TAL-641) answers for after `setProviderKey(…, null)`: that variable's `.env` entry and startup copy are gone.
+     */
+    providerHasKey(pid: string, config: Config, envValues: Record<string, string>, profileHome: string, cleared?: string): boolean;
     private authStatus;
+    /** `pooled`: the providers whose persisted credential pool holds an added account (TAL-638). */
     private probeKey;
     /** Live model ids from the Agent for one provider, cached per profile home. */
     liveModelIds(profileHome: string, pid: string, opts?: {
@@ -158,6 +224,8 @@ export declare class ProviderCatalog {
         providers: Dict[];
         active_provider: string | null;
     }>;
+    /** 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>;
     /** Stamps the default's entry id and keeps the catalog for `modelOptionFor`. */
@@ -176,21 +244,42 @@ export declare class ProviderCatalog {
         config_context_length?: number | null;
     }>;
     private apiKeyFor;
-    /** Python `get_provider_quota`. */
+    /** Account-usage snapshots by profile home, provider, and pool account. */
     private readonly accountUsageCache;
+    /**
+     * 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.
+     */
     quota(profileHome: string, providerRaw: string | null, opts?: {
         refresh?: boolean;
         at?: number;
+        credential?: PoolEntry | null;
     }): Promise<Dict>;
-    private fetchOpenRouterKey;
+    /**
+     * TAL-548: the provider's credential-pool accounts as the sidecar reads them locally. Each says whether it holds
+     * `apiKey`, the provider's configured key. Null when the pool is unknown (see `poolLookup`).
+     */
+    private poolEntries;
+    /** The last answer of each credential-pool lookup, by profile home and lookup. */
+    private readonly lastPoolAnswers;
+    /**
+     * TAL-548: one credential-pool lookup through the sidecar. A failed lookup answers with the last answer to the same
+     * 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. */
+    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;
     private quotaScopeCache;
     /** 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;
     /**
-     * Python `get_provider_quotas`: one source per keyed provider, in the stable-identity envelope the iOS widget persists.
-     * Each source id appears once (two custom providers can share a slug), ordered by provider, account label, then source id.
+     * 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
+     * once (two custom providers can share a slug), ordered by provider, account label, then source id.
      */
     quotas(profileHome: string, profile: string, opts?: {
         sourceId?: string | null;
@@ -198,5 +287,9 @@ export declare class ProviderCatalog {
     }): Promise<Dict>;
     /** 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;
+    /** Writes or updates the UTC day's OpenRouter usage snapshot; every successful key read (quota or cost history) records one. */
+    private recordCostSnapshot;
 }
 export declare const envFileExists: (profileHome: string) => boolean;
+export {};