LibreChat/client/src/utils/endpoints.ts

import {
  Constants,
  EModelEndpoint,
  defaultEndpoints,
  modularEndpoints,
  LocalStorageKeys,
  getEndpointField,
  isAgentsEndpoint,
  isEphemeralAgentId,
  isAssistantsEndpoint,
} from 'librechat-data-provider';
import type * as t from 'librechat-data-provider';
import type { LocalizeFunction, IconsRecord } from '~/common';
import { getTimestampedValue } from './timestamps';

/**
 * Clears model for non-ephemeral agent conversations.
 * Agents use their configured model internally, so the conversation model should be undefined.
 * Mutates the template in place.
 */
export function clearModelForNonEphemeralAgent<
  T extends {
    endpoint?: EModelEndpoint | string | null;
    agent_id?: string | null;
    model?: string | null;
  },
>(template: T): void {
  if (
    isAgentsEndpoint(template.endpoint) &&
    template.agent_id &&
    !isEphemeralAgentId(template.agent_id)
  ) {
    template.model = undefined as T['model'];
  }
}

export const getEntityName = ({
  name = '',
  localize,
  isAgent,
}: {
  name?: string;
  isAgent?: boolean;
  localize: LocalizeFunction;
}) => {
  if (name && name.length > 0) {
    return name;
  } else {
    return isAgent === true ? localize('com_ui_agent') : localize('com_ui_assistant');
  }
};

export const getEndpointsFilter = (endpointsConfig: t.TEndpointsConfig) => {
  const filter: Record<string, boolean> = {};
  if (!endpointsConfig) {
    return filter;
  }
  for (const key of Object.keys(endpointsConfig)) {
    filter[key] = !!endpointsConfig[key];
  }
  return filter;
};

export const getAvailableEndpoints = (
  filter: Record<string, boolean>,
  endpointsConfig: t.TEndpointsConfig,
) => {
  const defaultSet = new Set(defaultEndpoints);
  const availableEndpoints: EModelEndpoint[] = [];

  for (const endpoint in endpointsConfig) {
    // Check if endpoint is in the filter or its type is in defaultEndpoints
    if (
      filter[endpoint] ||
      (endpointsConfig[endpoint]?.type &&
        defaultSet.has(endpointsConfig[endpoint]?.type as EModelEndpoint))
    ) {
      availableEndpoints.push(endpoint as EModelEndpoint);
    }
  }

  return availableEndpoints;
};

export function mapEndpoints(endpointsConfig: t.TEndpointsConfig) {
  const filter = getEndpointsFilter(endpointsConfig);
  return getAvailableEndpoints(filter, endpointsConfig).sort(
    (a, b) => (endpointsConfig?.[a]?.order ?? 0) - (endpointsConfig?.[b]?.order ?? 0),
  );
}

const firstLocalConvoKey = LocalStorageKeys.LAST_CONVO_SETUP + '_0';

/**
 * Ensures the last selected model stays up to date, as conversation may
 * update without updating last convo setup when same endpoint */
export function updateLastSelectedModel({
  endpoint,
  model = '',
}: {
  endpoint: string;
  model?: string;
}) {
  if (!model) {
    return;
  }
  /* Note: an empty string value is possible */
  const lastConversationSetup = JSON.parse(
    (localStorage.getItem(firstLocalConvoKey) ?? '{}') || '{}',
  );

  if (lastConversationSetup.endpoint === endpoint) {
    lastConversationSetup.model = model;
    localStorage.setItem(firstLocalConvoKey, JSON.stringify(lastConversationSetup));
  }

  const lastSelectedModels = JSON.parse(
    (localStorage.getItem(LocalStorageKeys.LAST_MODEL) ?? '{}') || '{}',
  );
  lastSelectedModels[endpoint] = model;
  localStorage.setItem(LocalStorageKeys.LAST_MODEL, JSON.stringify(lastSelectedModels));
}

interface ConversationInitParams {
  conversation: t.TConversation | null;
  newEndpoint: EModelEndpoint | string | null;
  endpointsConfig: t.TEndpointsConfig;
  modularChat?: boolean;
}

interface InitiatedTemplateResult {
  template: Partial<t.TPreset>;
  shouldSwitch: boolean;
  isExistingConversation: boolean;
  isCurrentModular: boolean;
  isNewModular: boolean;
  newEndpointType: EModelEndpoint | undefined;
}

type StoredModelSelection = Pick<
  t.TConversation,
  'endpoint' | 'model' | 'spec' | 'agent_id' | 'assistant_id'
>;

function hasSelectionValue(value?: string | null): boolean {
  return typeof value === 'string' && value.trim() !== '';
}

function parseStoredModelSelection(
  value: string | null,
): Partial<StoredModelSelection> | undefined {
  if (!value) {
    return;
  }

  try {
    return JSON.parse(value) as Partial<StoredModelSelection>;
  } catch {
    return;
  }
}

function hasStoredPrefixValue(prefix: string): boolean {
  for (let i = 0; i < localStorage.length; i++) {
    const key = localStorage.key(i);
    if (!key?.startsWith(prefix)) {
      continue;
    }

    if (hasSelectionValue(localStorage.getItem(key))) {
      return true;
    }
  }

  return false;
}

function hasStoredModelValue(): boolean {
  const storedModelValue = localStorage.getItem(LocalStorageKeys.LAST_MODEL);
  if (!storedModelValue) {
    return false;
  }

  try {
    const storedModels = JSON.parse(storedModelValue) as Record<string, string | null | undefined>;
    return Object.values(storedModels).some(hasSelectionValue);
  } catch {
    return false;
  }
}

export function hasModelSelection(selection?: Partial<StoredModelSelection> | null): boolean {
  if (!selection) {
    return false;
  }

  return (
    hasSelectionValue(selection.spec) ||
    hasSelectionValue(selection.agent_id) ||
    hasSelectionValue(selection.assistant_id) ||
    hasSelectionValue(selection.model) ||
    hasSelectionValue(selection.endpoint)
  );
}

function hasStoredModelSelection(): boolean {
  if (hasSelectionValue(localStorage.getItem(LocalStorageKeys.LAST_SPEC))) {
    return true;
  }

  if (hasStoredModelValue()) {
    return true;
  }

  if (
    hasStoredPrefixValue(LocalStorageKeys.AGENT_ID_PREFIX) ||
    hasStoredPrefixValue(LocalStorageKeys.ASST_ID_PREFIX)
  ) {
    return true;
  }

  const lastConversationSetup = parseStoredModelSelection(
    localStorage.getItem(LocalStorageKeys.LAST_CONVO_SETUP + '_0'),
  );

  return hasModelSelection(lastConversationSetup);
}

/** Get the conditional logic for switching conversations */
export function getConvoSwitchLogic(params: ConversationInitParams): InitiatedTemplateResult {
  const { conversation, newEndpoint, endpointsConfig, modularChat = false } = params;

  const currentEndpoint = conversation?.endpoint;
  const template: Partial<t.TPreset> = {
    ...conversation,
    endpoint: newEndpoint,
    conversationId: 'new',
  };

  // Reset agent_id if switching to a non-agents endpoint but template has a non-ephemeral agent_id
  if (
    !isAgentsEndpoint(newEndpoint) &&
    template.agent_id &&
    !isEphemeralAgentId(template.agent_id)
  ) {
    template.agent_id = Constants.EPHEMERAL_AGENT_ID;
  }

  // Clear model for non-ephemeral agents - agents use their configured model internally
  clearModelForNonEphemeralAgent(template);

  const isAssistantSwitch =
    isAssistantsEndpoint(newEndpoint) &&
    isAssistantsEndpoint(currentEndpoint) &&
    currentEndpoint === newEndpoint;

  const conversationId = conversation?.conversationId ?? '';
  const isExistingConversation = !!(conversationId && conversationId !== 'new');

  const currentEndpointType =
    getEndpointField(endpointsConfig, currentEndpoint, 'type') ?? currentEndpoint;
  const newEndpointType =
    getEndpointField(endpointsConfig, newEndpoint, 'type') ??
    (newEndpoint as EModelEndpoint | undefined);

  const hasEndpoint = modularEndpoints.has(currentEndpoint ?? '');
  const hasCurrentEndpointType = modularEndpoints.has(currentEndpointType ?? '');
  const isCurrentModular = hasEndpoint || hasCurrentEndpointType || isAssistantSwitch;

  const hasNewEndpoint = modularEndpoints.has(newEndpoint ?? '');
  const hasNewEndpointType = modularEndpoints.has(newEndpointType ?? '');
  const isNewModular = hasNewEndpoint || hasNewEndpointType || isAssistantSwitch;

  const endpointsMatch = currentEndpoint === newEndpoint;
  const shouldSwitch = endpointsMatch || modularChat || isAssistantSwitch;

  return {
    template,
    shouldSwitch,
    isExistingConversation,
    isCurrentModular,
    newEndpointType,
    isNewModular,
  };
}

export function getModelSpec({
  specName,
  startupConfig,
}: {
  specName?: string | null;
  startupConfig?: t.TStartupConfig;
}): t.TModelSpec | undefined {
  if (!startupConfig || !specName) {
    return;
  }
  return startupConfig.modelSpecs?.list?.find((spec) => spec.name === specName);
}

export function applyModelSpecEphemeralAgent({
  convoId,
  modelSpec,
  updateEphemeralAgent,
}: {
  convoId?: string | null;
  modelSpec?: t.TModelSpec;
  updateEphemeralAgent: ((convoId: string, agent: t.TEphemeralAgent | null) => void) | undefined;
}) {
  if (!modelSpec || !updateEphemeralAgent) {
    return;
  }
  const key = (convoId ?? Constants.NEW_CONVO) || Constants.NEW_CONVO;
  const agent: t.TEphemeralAgent = {
    mcp: modelSpec.mcpServers ?? [],
    web_search: modelSpec.webSearch ?? false,
    file_search: modelSpec.fileSearch ?? false,
    execute_code: modelSpec.executeCode ?? false,
    artifacts: modelSpec.artifacts === true ? 'default' : modelSpec.artifacts || '',
  };

  // For existing conversations, layer per-conversation localStorage overrides
  // on top of spec defaults so user modifications persist across navigation.
  // If localStorage is empty (e.g., cleared), spec values stand alone.
  if (key !== Constants.NEW_CONVO) {
    const toolStorageMap: Array<[keyof t.TEphemeralAgent, string]> = [
      ['execute_code', LocalStorageKeys.LAST_CODE_TOGGLE_],
      ['web_search', LocalStorageKeys.LAST_WEB_SEARCH_TOGGLE_],
      ['file_search', LocalStorageKeys.LAST_FILE_SEARCH_TOGGLE_],
      ['artifacts', LocalStorageKeys.LAST_ARTIFACTS_TOGGLE_],
    ];

    for (const [toolKey, storagePrefix] of toolStorageMap) {
      const raw = getTimestampedValue(`${storagePrefix}${key}`);
      if (raw !== null) {
        try {
          agent[toolKey] = JSON.parse(raw) as never;
        } catch {
          // ignore parse errors
        }
      }
    }

    const mcpRaw = localStorage.getItem(`${LocalStorageKeys.LAST_MCP_}${key}`);
    if (mcpRaw !== null) {
      try {
        const parsed = JSON.parse(mcpRaw);
        if (Array.isArray(parsed)) {
          agent.mcp = parsed;
        }
      } catch {
        // ignore parse errors
      }
    }
  }

  updateEphemeralAgent(key, agent);
}

/**
 * Gets default model spec from config and user preferences.
 * Priority: hard admin default → prior user selection → soft first-time default.
 * Legacy first-spec prioritization remains only when no soft default is configured.
 */
export function getDefaultModelSpec(startupConfig?: t.TStartupConfig):
  | {
      default?: t.TModelSpec;
      last?: t.TModelSpec;
      softDefault?: t.TModelSpec;
    }
  | undefined {
  const { modelSpecs, interface: interfaceConfig } = startupConfig ?? {};
  const { list, prioritize } = modelSpecs ?? {};
  if (!list) {
    return;
  }
  const defaultSpec = list?.find((spec) => spec.default);
  const softDefaultSpec = list?.find((spec) => spec.softDefault);
  if (prioritize === true || !interfaceConfig?.modelSelect) {
    const lastSelectedSpecName = localStorage.getItem(LocalStorageKeys.LAST_SPEC);
    const lastSelectedSpec = list?.find((spec) => spec.name === lastSelectedSpecName);
    if (defaultSpec) {
      return { default: defaultSpec };
    }
    if (lastSelectedSpec) {
      return { last: lastSelectedSpec };
    }
    if (softDefaultSpec) {
      return hasStoredModelSelection() ? undefined : { softDefault: softDefaultSpec };
    }
    return { default: list?.[0] };
  } else if (defaultSpec) {
    return { default: defaultSpec };
  }
  const lastConversationSetup = parseStoredModelSelection(
    localStorage.getItem(LocalStorageKeys.LAST_CONVO_SETUP + '_0'),
  );
  const lastConversationSpecName = lastConversationSetup?.spec;
  if (!hasSelectionValue(lastConversationSpecName)) {
    if (softDefaultSpec && !hasStoredModelSelection()) {
      return { softDefault: softDefaultSpec };
    }
    return;
  }
  return { last: list?.find((spec) => spec.name === lastConversationSpecName) };
}

export function getModelSpecPreset(modelSpec?: t.TModelSpec) {
  if (!modelSpec) {
    return;
  }
  return {
    ...modelSpec.preset,
    spec: modelSpec.name,
    iconURL: getModelSpecIconURL(modelSpec),
  };
}

/** Fields set by a model spec that should be cleared when switching to a non-spec conversation. */
export const specDisplayFieldReset = {
  spec: null as string | null,
  iconURL: null as string | null,
  modelLabel: null as string | null,
  greeting: undefined as string | undefined,
};

/**
 * Merges a spec preset base with URL query settings, clearing spec display fields
 * when the query doesn't explicitly set a spec. Prevents spec contamination on
 * agent/assistant share links.
 */
export function mergeQuerySettingsWithSpec(
  specPreset: t.TPreset | undefined,
  querySettings: t.TPreset,
): t.TPreset {
  return {
    ...specPreset,
    ...querySettings,
    ...(specPreset != null && querySettings.spec == null ? specDisplayFieldReset : {}),
  };
}

/** Gets the model spec iconURL by explicit icon, preset icon, then preset endpoint. */
export function getModelSpecIconURL(modelSpec: t.TModelSpec) {
  return modelSpec.iconURL ?? modelSpec.preset?.iconURL ?? modelSpec.preset?.endpoint ?? '';
}

/** Gets the default frontend-facing endpoint, dependent on iconURL definition.
 *
 * If the iconURL is defined in the endpoint config, use it, otherwise use the endpoint
 */
export function getIconEndpoint({
  endpointsConfig,
  iconURL,
  endpoint,
}: {
  endpointsConfig?: t.TEndpointsConfig;
  iconURL?: string | null;
  endpoint?: string | null;
}) {
  return (endpointsConfig?.[iconURL ?? ''] ? (iconURL ?? endpoint) : endpoint) ?? '';
}

/** Gets the key to use for the default endpoint iconURL, as defined by the custom config */
export function getIconKey({
  endpoint,
  endpointType: _eType,
  endpointsConfig,
  endpointIconURL: iconURL,
}: {
  endpoint?: string | null;
  endpointsConfig?: t.TEndpointsConfig | null;
  endpointType?: string | null;
  endpointIconURL?: string;
}): keyof IconsRecord {
  const endpointType = _eType ?? getEndpointField(endpointsConfig, endpoint, 'type') ?? '';
  const endpointIconURL = iconURL ?? getEndpointField(endpointsConfig, endpoint, 'iconURL') ?? '';
  if (endpointIconURL && EModelEndpoint[endpointIconURL] != null) {
    return endpointIconURL;
  }
  return endpointType ? 'unknown' : (endpoint ?? 'unknown');
}

export const getEntity = ({
  endpoint,
  assistant_id,
  agent_id,
  agentsMap,
  assistantMap,
}: {
  endpoint: EModelEndpoint | string | null | undefined;
  assistant_id: string | undefined;
  agent_id: string | undefined;
  agentsMap: t.TAgentsMap | undefined;
  assistantMap: t.TAssistantsMap | undefined;
}): {
  entity: t.Agent | t.Assistant | undefined | null;
  isAgent: boolean;
  isAssistant: boolean;
} => {
  const isAgent = isAgentsEndpoint(endpoint);
  const isAssistant = isAssistantsEndpoint(endpoint);

  if (isAgent) {
    const agent = agentsMap?.[agent_id ?? ''];
    return { entity: agent, isAgent, isAssistant };
  } else if (isAssistant) {
    const assistant = assistantMap?.[endpoint ?? '']?.[assistant_id ?? ''];
    return { entity: assistant, isAgent, isAssistant };
  }
  return { entity: null, isAgent, isAssistant };
};