Skip to content

The agent that grows with you

8.3 KB
Raw Blame
import type { ModelCapabilities, ModelOptionProvider, ModelOptionsResult } from '@hermes/shared'

import { getGlobalModelOptions, type HermesGateway } from '@/hermes'

type CatalogProviderIdentity = Partial<Pick<ModelOptionProvider, 'aliases' | 'name'>> &
  Pick<ModelOptionProvider, 'slug'>

/** True when `currentProvider` is this catalog row — slug, display name, or
 *  a custom-provider alias (`custom:<key>` vs the bare config key, #87035). */
export function catalogProviderMatches(provider: CatalogProviderIdentity, currentProvider: string): boolean {
  if (!currentProvider) {
    return false
  }

  return (
    provider.slug === currentProvider ||
    provider.name === currentProvider ||
    (provider.aliases?.includes(currentProvider) ?? false)
  )
}

/** The catalog row for `currentProvider`, matched the same way as
 *  `catalogProviderMatches` (so a saved `custom:<key>` finds its row). */
export function findCatalogProvider<T extends CatalogProviderIdentity>(
  providers: readonly T[],
  currentProvider: string
): T | undefined {
  return providers.find(row => catalogProviderMatches(row, currentProvider))
}

/** The catalog's option support for the current pick, or undefined while the
 *  catalog is loading / doesn't say. Callers treat undefined as "assume
 *  reasoning" so controls never flicker away during the fetch. */
export function currentModelCapabilities(
  options: ModelOptionsResult | null | undefined,
  provider: string,
  model: string
): ModelCapabilities | undefined {
  return findCatalogProvider(options?.providers ?? [], provider)?.capabilities?.[model]
}

// A picked (provider, model) pair is never retargeted from catalog membership.
// Picker rows are hints (discovered / curated / capped lists); a custom endpoint
// or a newer release legitimately serves ids the row lacks, and the backend
// soft-accepts them. Diffing the pick against the catalog silently swapped
// `deepseek-v4.1-flash` for the row's `-0731` sibling. The only authority on a
// pick's validity is the gateway's switch result.

/** The single, deliberate exception to the sticky-pick rule above: the virtual
 *  `moa` provider. Its catalog row vanishes entirely once no MoA preset is
 *  enabled (`hermes_cli/inventory.py` filters it out of explicit-only
 *  catalogs), so a persisted manual pick pointing at it leaves the composer
 *  pill reading `Model · moa: default` forever (#90244). For this one provider
 *  — and only with a populated catalog in hand — row absence is authoritative:
 *  the pick reseeds from the profile default. Every other provider keeps the
 *  sticky behavior; an unloaded/empty catalog never clobbers anything. */
export function moaPickRemoved(
  options: { providers?: ModelOptionProvider[] | null } | null | undefined,
  provider: string,
  model: string
): boolean {
  if (!model.trim() || provider.trim().toLowerCase() !== 'moa') {
    return false
  }

  const providers = options?.providers

  if (!providers || providers.length === 0) {
    return false
  }

  const row = providers.find(p => (p.slug || p.name || '').toLowerCase() === 'moa')

  return !(row?.models ?? []).includes(model)
}

/** A bare provider slug is the pre-migration spelling of a custom entry. The
 *  catalog aliases `custom:<key>` with the bare config key (#87035), so a pick
 *  still carrying `nvidia` and a profile default of `custom:nvidia` name the
 *  SAME endpoint — the pick's spelling is simply stale, not a distinct choice.
 *  Shipping the bare slug resolves the NATIVE provider instead of the custom
 *  entry, silently dropping the entry's `extra_body` (e.g.
 *  `thinking: {type: adaptive}`) that the user configured (#81922).
 *
 *  Only a bare slug can be superseded: a pick that already names a provider
 *  class (`custom:<other>`, `moa`, `openai-codex`) is a different endpoint and
 *  keeps the sticky behavior. The bare slug must be the default's own key, so
 *  an unrelated manual pick (`anthropic` while the default is `custom:nvidia`)
 *  is never clobbered. */
export function customDefaultSupersedesPick(pickProvider: string, defaultProvider: string): boolean {
  const pick = (pickProvider || '').trim().toLowerCase()
  const fallback = (defaultProvider || '').trim().toLowerCase()

  if (!pick || pick === fallback || !fallback.startsWith('custom:')) {
    return false
  }

  const key = fallback.slice('custom:'.length).trim()

  return key.length > 0 && pick === key
}

interface ModelOptionsRequest {
  /** When false, include ambient/unconfigured providers (onboarding/setup
   *  surfaces). Chat pickers default to true so only explicitly configured
   *  providers are listed (#56974). */
  explicitOnly?: boolean
  gateway?: HermesGateway
  /** Owner-routed RPC. When set, catalog reads hit this dispatcher instead of
   *  `gateway.request` — a tile's model menu must not query the ambient
   *  chrome socket (#93892). */
  request?: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
  /** Profile for the REST recovery path. Must match the catalog owner so a
   *  secondary tile does not fall back to the launch profile's models. */
  profile?: null | string
  refresh?: boolean
  sessionId?: null | string
}

export function modelOptionsQueryKey(
  profile: null | string | undefined,
  sessionId?: null | string,
  ownerConnectionId?: null | string
) {
  const profileKey = (profile ?? '').trim() || 'default'
  const ownerKey = (ownerConnectionId ?? '').trim()

  return ['model-options', profileKey, sessionId || 'global', ...(ownerKey ? ['owner', ownerKey] : [])] as const
}

function hasSelectableModels(options: ModelOptionsResult | null | undefined): boolean {
  return options?.providers?.some(provider => (provider.models?.length ?? 0) > 0) ?? false
}

function restModelOptions(
  explicitOnly: boolean,
  refresh: boolean,
  profile?: null | string
): Promise<ModelOptionsResult> {
  const opts = { explicitOnly, ...(refresh ? { refresh: true } : {}) }
  const profileKey = (profile ?? '').trim()

  return profileKey ? getGlobalModelOptions(opts, profileKey) : getGlobalModelOptions(opts)
}

export async function requestModelOptions({
  explicitOnly = true,
  gateway,
  profile,
  refresh = false,
  request,
  sessionId
}: ModelOptionsRequest): Promise<ModelOptionsResult> {
  const dispatch = request ?? (gateway ? gateway.request.bind(gateway) : null)

  if (dispatch) {
    const params: Record<string, unknown> = {}

    if (sessionId) {
      params.session_id = sessionId
    }

    if (refresh) {
      params.refresh = true
    }

    if (explicitOnly) {
      params.explicit_only = true
    }

    const profileKey = (profile ?? '').trim()

    // An owner-routed session read is scoped by its session_id. The backend lets
    // an explicit `profile` override that, and callers hand in the window's
    // ambient profile, so sending it built the launch profile's catalog; the
    // router adds the owner's own profile where its socket needs one.
    if (profileKey && !(request && sessionId)) {
      params.profile = profileKey
    }

    let gatewayError: unknown
    let gatewayOptions: ModelOptionsResult | undefined

    try {
      gatewayOptions = await dispatch<ModelOptionsResult>('model.options', params)
    } catch (error) {
      gatewayError = error
    }

    if (gatewayOptions && hasSelectableModels(gatewayOptions)) {
      return gatewayOptions
    }

    // An owner-routed dispatcher can name a different registry connection than
    // the ambient REST client. Never recover that request through ambient REST:
    // profile names are not unique across sources, so doing so can cache B's
    // catalog under A's tile. Ambient gateway requests retain the compatibility
    // recovery used by older backends with incomplete model.options responses.
    if (!request) {
      try {
        const restOptions = await restModelOptions(explicitOnly, refresh, profile)

        if (hasSelectableModels(restOptions)) {
          return {
            ...restOptions,
            ...(gatewayOptions?.provider ? { provider: gatewayOptions.provider } : {}),
            ...(gatewayOptions?.model ? { model: gatewayOptions.model } : {})
          }
        }
      } catch {
        // Preserve the gateway result (or its original error) when the recovery
        // path is unavailable.
      }
    }

    if (gatewayOptions) {
      return gatewayOptions
    }

    throw gatewayError
  }

  return restModelOptions(explicitOnly, refresh, profile)
}