@maudecode/talaria-web 1.15.0 → 1.17.2

package/dist/providers/catalog.d.ts

@@ -1,9 +1,13 @@
 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;
     label: string;
     supports_fast_tier?: boolean;
+    provider_id?: string;
+    bare_id?: string;
 }
 export interface ModelGroup {
     provider: string;
@@ -11,11 +15,24 @@ export interface ModelGroup {
     models: ModelEntry[];
     extra_models?: ModelEntry[];
 }
+/** 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 {
     active_provider: string | null;
     default_model: string;
+    default_provider_id?: string | null;
+    default_bare_id?: string;
+    default_option_id?: string | null;
     groups: ModelGroup[];
     aliases: Record<string, string>;
     configured_model_badges: Record<string, {
@@ -43,12 +60,80 @@ 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;
+/** ISO-8601 UTC (`…Z`) or null. Accepts the pre-TAL-409 sidecar's `str(datetime)` space form; a zone-less stamp is UTC. */
+export declare function isoUtc(value: unknown): string | null;
+export interface QuotaPace {
+    expected_remaining_percent: number;
+    pace_delta_percent: number;
+    burn_rate: number;
+    minutes_to_reset: number;
+    projected_minutes_to_empty: number | null;
+    elapsed_minutes: number;
+    valid_until: string;
+}
+export interface QuotaForecast {
+    outcome: 'safe' | 'warning';
+    budget_unit: 'hour' | 'day';
+    budget_percent: number | null;
+    depletion_margin_minutes: number | null;
+}
+export interface QuotaWindow {
+    label: string;
+    used_percent: number | null;
+    remaining_percent: number | null;
+    reset_at: string | null;
+    detail: string | null;
+    window_seconds: number | null;
+    pace: QuotaPace | null;
+    forecast: QuotaForecast | null;
+}
+export interface QuotaWindows {
+    windows: QuotaWindow[];
+    pace_window_index: number | null;
+    session_window_index: number | null;
+    weekly_window_index: number | null;
+}
+/** The forecast a pace implies: per-hour or per-day budget until reset, and whether the projection empties the window first. */
+export declare function quotaForecast(pace: QuotaPace, remaining: number | null): QuotaForecast;
+/**
+ * TAL-409: the one normaliser for account-usage windows (Python `_snapshot_windows_payload` plus the pace math the
+ * App used to run). Blank labels drop; `reset_at` becomes ISO `Z`; each window gets its duration, pace and forecast
+ * 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;
@@ -59,12 +144,27 @@ 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;
+    provider_id: string;
+    account_label: string;
+}>(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(): {
@@ -73,26 +173,59 @@ export declare class ProviderCatalog {
         age_seconds: number | null;
     };
     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;
+    /**
+     * 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.
      */
     private processEnv;
-    /** Python `_provider_has_key` minus the credential pool (the sidecar answers OAuth/pool state). */
+    /** Python `_provider_has_key` minus the credential pool, which `probeKey` reads from the sidecar. */
     providerHasKey(pid: string, config: Config, envValues: Record<string, string>, profileHome: 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?: {
         force?: boolean;
     }): Promise<string[]>;
+    /**
+     * 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;
     /** Python `get_providers`. */
     providers(profileHome: string): Promise<{
         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`. */
+    private remember;
     /** Python `_configured_model_badges_from_static_catalog`: which picker rows are the main/fallback selections. */
     private badges;
     /** Python `_handle_live_models`. */
@@ -107,23 +240,52 @@ 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. */
+    /**
+     * 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;
         refresh?: boolean;
     }): 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 {};