The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
import type { ModelOptionProvider } from '@hermes/shared'
import { atom } from 'nanostores'
import { persistString, storedString } from '@/lib/storage'
const STORAGE_KEY = 'hermes.desktop.visible-models'
/** Every `provider::model` key the user has had a chance to judge — snapshotted
* each time the visible set is persisted. A model absent from here appeared
* AFTER the user last curated (plugin update, catalog refresh, new release), so
* it falls through to the curated default rule instead of defaulting to hidden. */
const KNOWN_STORAGE_KEY = 'hermes.desktop.known-models'
/** Models shown per provider in the status-bar dropdown before the user has
* customized the list. Backend `models` are already relevance-ordered. */
export const DEFAULT_VISIBLE_PER_PROVIDER = 50
/** Stable key for a provider/model pair (`::` avoids colliding with model ids
* that contain a single colon, e.g. `model:tag`). */
export const modelVisibilityKey = (provider: string, model: string): string => `${provider}::${model}`
/** Sentinel key suffix stored when the user explicitly hides ALL models for a
* provider. Distinguishes "user hid everything" from "never customized" so
* `effectiveVisibleKeys` does not re-add defaults for that provider. */
export const EMPTY_PROVIDER_SENTINEL = ''
/** Build the sentinel key for a provider whose last model was toggled off. */
export const emptyProviderSentinelKey = (provider: string): string =>
modelVisibilityKey(provider, EMPTY_PROVIDER_SENTINEL)
/** Check whether a stored key is a provider-hidden sentinel. */
export const isProviderSentinel = (key: string): boolean => key.endsWith('::')
/** A model and its optional `…-fast` sibling, collapsed into one logical row.
* `id` is the canonical (base) model; `fastId` is the fast variant if present. */
export interface ModelFamily {
fastId: string | null
id: string
}
/** Collapse a provider's model list so a base model and its `…-fast` variant
* become a single family (one row, one toggle). Order is preserved by the
* base model's position. A `…-fast` model with no base stands on its own. */
export function collapseModelFamilies(models: readonly string[]): ModelFamily[] {
const present = new Set(models)
const families: ModelFamily[] = []
const consumed = new Set<string>()
for (const model of models) {
if (consumed.has(model)) {
continue
}
if (/-fast$/i.test(model) && present.has(model.replace(/-fast$/i, ''))) {
// Represented by its base entry — the base attaches it as `fastId`.
continue
}
if (/-\d{8}$/.test(model) && present.has(model.replace(/-\d{8}$/, ''))) {
// A date-pinned snapshot superseded by its rolling alias — drop the dupe.
continue
}
const fastId = `${model}-fast`
const hasFast = present.has(fastId)
families.push({ fastId: hasFast ? fastId : null, id: model })
consumed.add(model)
if (hasFast) {
consumed.add(fastId)
}
}
return families
}
function loadKeySet(storageKey: string): Set<string> | null {
const raw = storedString(storageKey)
if (!raw) {
return null
}
try {
const parsed = JSON.parse(raw)
return Array.isArray(parsed) ? new Set(parsed.filter((x): x is string => typeof x === 'string')) : null
} catch {
return null
}
}
/** Explicit set of visible `provider::model` keys, or null when the user
* hasn't customized — in which case the curated default applies. */
export const $visibleModels = atom<Set<string> | null>(loadKeySet(STORAGE_KEY))
/** Keys the user has seen, or null when nothing has been recorded yet (a fresh
* install, or a store written before the snapshot existed). */
export const $knownModels = atom<Set<string> | null>(loadKeySet(KNOWN_STORAGE_KEY))
export const $modelVisibilityOpen = atom(false)
/** Every collapsed-family key across `providers`. */
function allFamilyKeys(providers: readonly ModelOptionProvider[]): Set<string> {
const keys = new Set<string>()
for (const provider of providers) {
for (const family of collapseModelFamilies(provider.models ?? [])) {
keys.add(modelVisibilityKey(provider.slug, family.id))
}
}
return keys
}
/** Persist the visible set and, when the current catalog is supplied, mark every
* model in it as judged so only models that appear later count as new. */
export function setVisibleModels(keys: Set<string>, providers: readonly ModelOptionProvider[] = []): void {
$visibleModels.set(new Set(keys))
persistString(STORAGE_KEY, JSON.stringify([...keys]))
if (providers.length === 0) {
return
}
persistKnownModels(new Set([...($knownModels.get() ?? []), ...allFamilyKeys(providers)]))
}
function persistKnownModels(known: Set<string>): void {
$knownModels.set(known)
persistString(KNOWN_STORAGE_KEY, JSON.stringify([...known]))
}
/** One-time adoption for a visible set persisted before the known snapshot
* existed. The old store predates the snapshot machinery, so "absent from the
* allowlist" is ambiguous: a deliberate hide and a model that arrived after
* the user last curated look identical. Recording everything in the catalog
* as judged therefore strands catalog-present defaults behind a stale
* allowlist forever (https://github.com/NousResearch/hermes-agent/issues/122053)
* — so the curated defaults the old allowlist does NOT contain stay unknown,
* and the default rule re-admits them on the next resolve. The one-time cost
* is that a deliberately hidden default comes back once; the user's next save
* records the re-hide properly and it locks. Non-default models keep the
* verbatim-hide semantics — the default rule never showed them anyway — and
* a provider hidden outright (sentinel) is skipped entirely. Never a running
* union — that would mark a newcomer judged on the very render that first
* shows it. Call when the catalog has loaded. */
export function seedKnownModels(providers: readonly ModelOptionProvider[]): void {
const stored = $visibleModels.get()
if ($knownModels.get() !== null || stored === null || providers.length === 0) {
return
}
const known = allFamilyKeys(providers)
for (const provider of providers) {
if (stored.has(emptyProviderSentinelKey(provider.slug))) {
continue
}
const defaults = new Set<string>()
expandProviderDefaults(provider, defaults)
for (const key of defaults) {
if (!stored.has(key)) {
known.delete(key)
}
}
}
persistKnownModels(known)
}
/** Back to "never customized": the curated defaults apply again and the known
* snapshot starts over. The snapshot records what was LISTED at each persist,
* not what the user chose, so a model hidden when it was recorded (e.g. by the
* one-time adoption above) stays hidden through every later catalog change.
* This is the user's way out of that without a global storage-key bump; Edit
* Models reaches it through `resetModelVisibilityKeepingCustoms`. */
export function resetModelVisibility(): void {
$visibleModels.set(null)
persistString(STORAGE_KEY, null)
$knownModels.set(null)
persistString(KNOWN_STORAGE_KEY, null)
}
export function setModelVisibilityOpen(open: boolean): void {
$modelVisibilityOpen.set(open)
}
/** The default-visible key set: the curated top-N per provider. Used both as
* the dropdown fallback and to seed the Edit Models dialog. */
export function defaultVisibleKeys(providers: readonly ModelOptionProvider[]): Set<string> {
const keys = new Set<string>()
for (const provider of providers) {
expandProviderDefaults(provider, keys)
}
return keys
}
/** Add a provider's curated default model keys to `target`. Prefers the
* backend's `featured_models` shortlist (one flagship per lab) for aggregator
* providers that would otherwise flood the default view with dozens of models;
* falls back to the top-N collapsed families when a provider ships no featured
* list. Shared by `defaultVisibleKeys` and `resolveVisibleKeys` so the
* expansion rule lives in exactly one place. */
function expandProviderDefaults(
provider: ModelOptionProvider,
target: Set<string>,
admit: (key: string) => boolean = () => true
): void {
const families = collapseModelFamilies(provider.models ?? [])
const featured = provider.featured_models ?? []
const defaults = featured.length
? families.filter(family => featured.includes(family.id))
: families.slice(0, DEFAULT_VISIBLE_PER_PROVIDER)
for (const family of defaults) {
const key = modelVisibilityKey(provider.slug, family.id)
if (admit(key)) {
target.add(key)
}
}
}
/** Resolve the canonical working set: the user's stored keys plus the curated
* default expansion for any provider they haven't customized. Hide-all
* sentinels are PRESERVED here — this is the set the toggle handler mutates and
* persists, so dropping a sentinel would silently re-enable a provider the user
* emptied. Use `effectiveVisibleKeys` for display (sentinels stripped).
*
* A provider the user has curated still admits models absent from `known`
* (they arrived after the last curation) through the same default rule, so a
* plugin or catalog update never lands a model silently switched off. A
* provider the user hid outright (sentinel) stays hidden, new models included.
* With no snapshot yet (`known` null) nothing counts as new. */
export function resolveVisibleKeys(
stored: Set<string> | null,
providers: readonly ModelOptionProvider[],
known: Set<string> | null = $knownModels.get()
): Set<string> {
if (!stored) {
return defaultVisibleKeys(providers)
}
if (stored.size === 0) {
return new Set()
}
const next = new Set(stored)
for (const provider of providers) {
const providerPrefix = `${provider.slug}::`
if (stored.has(emptyProviderSentinelKey(provider.slug))) {
continue
}
const hasStoredProvider = [...stored].some(key => key.startsWith(providerPrefix) && !isProviderSentinel(key))
if (!hasStoredProvider) {
expandProviderDefaults(provider, next)
} else if (known) {
expandProviderDefaults(provider, next, key => !known.has(key))
}
}
return next
}
/** Resolve which keys are currently visible for DISPLAY: the resolved working
* set with bookkeeping sentinels stripped (they are not real models). */
export function effectiveVisibleKeys(
stored: Set<string> | null,
providers: readonly ModelOptionProvider[],
known: Set<string> | null = $knownModels.get()
): Set<string> {
const next = resolveVisibleKeys(stored, providers, known)
// Strip sentinel keys — they are bookkeeping, not real visibility entries.
for (const key of [...next]) {
if (isProviderSentinel(key)) {
next.delete(key)
}
}
return next
}
/** Compute the next persisted visibility set when one model row is toggled.
* Seeds from `resolveVisibleKeys` (NOT `effectiveVisibleKeys`) so other
* providers' hide-all sentinels survive the persist. When the last visible
* model of a provider is toggled off, a sentinel records the explicit
* hide-all; re-enabling a model clears THAT provider's sentinel (only). */
export function toggleModelVisibility(
stored: Set<string> | null,
providers: readonly ModelOptionProvider[],
providerSlug: string,
model: string,
known: Set<string> | null = $knownModels.get()
): Set<string> {
// `resolveVisibleKeys` always returns a fresh Set, so we can mutate it directly.
const next = resolveVisibleKeys(stored, providers, known)
const key = modelVisibilityKey(providerSlug, model)
const sentinel = emptyProviderSentinelKey(providerSlug)
if (next.has(key)) {
next.delete(key)
// Check if this was the last real model for this provider.
const remainingForProvider = [...next].some(k => k.startsWith(`${providerSlug}::`) && !isProviderSentinel(k))
if (!remainingForProvider) {
next.add(sentinel)
}
} else {
// Re-enabling promotes a previously hidden-all provider to an explicit
// set of exactly the one re-enabled model — the curated defaults are NOT
// restored. Intentional: "you hid everything, you get back only what you
// re-enable." (Locked in by the sentinel-clear-on-re-enable test.)
next.delete(sentinel)
next.add(key)
}
return next
}
/** Compute the next persisted visibility set when a provider's master switch is
* flipped. `visible=true` enables every one of the provider's collapsed model
* families (and clears its hide-all sentinel); `visible=false` removes them all
* and records the sentinel so the defaults are not silently re-expanded.
* Seeds from `resolveVisibleKeys` so other providers' state (including their
* sentinels) survives the persist, mirroring `toggleModelVisibility`. */
export function setProviderVisibility(
stored: Set<string> | null,
providers: readonly ModelOptionProvider[],
providerSlug: string,
visible: boolean,
known: Set<string> | null = $knownModels.get()
): Set<string> {
const next = resolveVisibleKeys(stored, providers, known)
const sentinel = emptyProviderSentinelKey(providerSlug)
const provider = providers.find(p => p.slug === providerSlug)
const families = collapseModelFamilies(provider?.models ?? [])
// Drop every existing entry for this provider (real keys + sentinel); we
// rebuild its state from scratch below.
for (const key of [...next]) {
if (key.startsWith(`${providerSlug}::`)) {
next.delete(key)
}
}
if (visible) {
for (const family of families) {
next.add(modelVisibilityKey(providerSlug, family.id))
}
// A provider with zero models can't be "all on" — leave it empty rather
// than stranding a sentinel that reads as an explicit hide-all.
if (families.length === 0) {
next.delete(sentinel)
}
} else {
next.add(sentinel)
}
return next
}