Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

41.3 KB
Raw Blame
/*
 *  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

import { FileUploadProps } from '@/components/file-upload';
import { useHandleFilterSubmit } from '@/components/list-filter-bar/use-handle-filter-submit';
import message from '@/components/ui/message';
import { AgentCategory, AgentGlobals } from '@/constants/agent';
import { Permission } from '@/ee/constants/team';
import { ListDeletionKey } from '@/constants/list-deletion';
import { useFetchTenantInfo } from '@/hooks/use-user-setting-request';
import {
  AgentListItem,
  DSL,
  IAgentLogResponse,
  IAgentLogsRequest,
  IAgentLogsResponse,
  IBuiltinPipelineListResponse,
  IFlow,
  IFlowTemplate,
  IAgentWebhookCredential,
  IPipeLineListRequest,
  ITraceData,
  IWebhookTrace,
} from '@/interfaces/database/agent';
import { IAgentWebhookTraceRequest } from '@/interfaces/request/agent';
import i18n from '@/locales/config';
import { IInputs } from '@/pages/agent/interface';
import { useGetSharedChatSearchParams } from '@/pages/next-chats/hooks/use-send-shared-message';
import agentService, {
  createAgentSession,
  deleteAgentSession,
  fetchAgentLogsByCanvasId,
  fetchAgentLogsById,
  fetchPipeLineList,
  fetchSharedTrace,
  fetchTrace,
  fetchWebhookTrace,
  issueAgentWebhookCredential,
  revokeAgentWebhookCredential,
  updateAgent,
  updateAgentTags,
  updateVersion,
  uploadAgentFile,
} from '@/services/agent-service';
import { buildMessageListWithUuid } from '@/utils/chat';
import { markListItemsDeleted } from '@/utils/list-deletion-util';
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
import { useDebounce } from 'ahooks';
import { get, isEmpty, set } from 'lodash';
import { useCallback, useState } from 'react';
import { useParams, useSearchParams } from 'react-router';
import {
  useGetPaginationWithRouter,
  useHandleSearchChange,
} from './logic-hooks';
import { useSessionList } from './use-session-list';
import { PipelineVersionKeys } from './use-pipeline-version-request';

export const enum AgentApiAction {
  FetchAgentListByPage = 'fetchAgentListByPage',
  FetchAllAgentList = 'fetchAllAgentList',
  FetchAgentList = 'fetchAgentList',
  FetchAgentFilters = 'fetchAgentFilters',
  UpdateAgentSetting = 'updateAgentSetting',
  DeleteAgent = 'deleteAgent',
  FetchAgentDetail = 'fetchAgentDetail',
  ResetAgent = 'resetAgent',
  CreateAgent = 'createAgent',
  SaveAgent = 'saveAgent',
  FetchAgentTemplates = 'fetchAgentTemplates',
  UploadAgentFile = 'uploadAgentFile',
  UploadAgentFileWithProgress = 'uploadAgentFileWithProgress',
  Trace = 'trace',
  TestDbConnect = 'testDbConnect',
  DebugSingle = 'debugSingle',
  FetchInputForm = 'fetchInputForm',
  FetchVersionList = 'fetchVersionList',
  FetchVersion = 'fetchVersion',
  FetchExternalAgentInputs = 'fetchExternalAgentInputs',
  SetAgentSetting = 'setAgentSetting',
  FetchPrompt = 'fetchPrompt',
  CancelDataflow = 'cancelDataflow',
  CancelCanvas = 'cancelCanvas',
  FetchWebhookTrace = 'fetchWebhookTrace',
  CreateWebhookCredential = 'createWebhookCredential',
  RevokeWebhookCredential = 'revokeWebhookCredential',
  FetchSessionsByCanvasId = 'fetchSessionsByCanvasId',
  FetchSessionById = 'fetchSessionById',
  CreateAgentSession = 'createAgentSession',
  DeleteAgentSession = 'deleteAgentSession',
  FetchSessionByIdManually = 'fetchSessionByIdManually',
  FetchCanvasPresence = 'fetchCanvasPresence',
  JoinCanvasPresence = 'joinCanvasPresence',
  HeartbeatCanvasPresence = 'heartbeatCanvasPresence',
  LeaveCanvasPresence = 'leaveCanvasPresence',
  FetchAgentLog = 'fetchAgentLog',
  FetchSharedAgent = 'fetchSharedAgent',
  FetchAgentTags = 'fetchAgentTags',
  UpdateAgentTags = 'updateAgentTags',
  FetchBuiltinPipelineList = 'fetchBuiltinPipelineList',
  FetchBuiltinPipelineDetail = 'fetchBuiltinPipelineDetail',
}

// Invalidation rule for the list-page queries (list/filters/tags): they all
// use gcTime: 0 and refetch on mount, so invalidating them only matters while
// the agents list page is still mounted — i.e. from the list page's own
// mutations (delete, rename, tag edits, compilation group delete). Create and
// save flows navigate away or run on the canvas page, where these queries are
// inactive; invalidating them there only fires wasted refetches from the list
// page still mounted behind the create dialog.
export const AgentKeys = {
  templates: () => [AgentApiAction.FetchAgentTemplates] as const,
  list: (params?: unknown) =>
    params === undefined
      ? ([AgentApiAction.FetchAgentListByPage] as const)
      : ([AgentApiAction.FetchAgentListByPage, params] as const),
  all: () => [AgentApiAction.FetchAllAgentList] as const,
  listAll: (canvasCategory?: string) =>
    [AgentApiAction.FetchAgentList, canvasCategory] as const,
  filters: (canvasCategory?: string) =>
    canvasCategory === undefined
      ? ([AgentApiAction.FetchAgentFilters] as const)
      : ([AgentApiAction.FetchAgentFilters, canvasCategory] as const),
  tags: (canvasCategory?: string) =>
    canvasCategory === undefined
      ? ([AgentApiAction.FetchAgentTags] as const)
      : ([AgentApiAction.FetchAgentTags, canvasCategory] as const),
  detail: (agentId?: string) =>
    [AgentApiAction.FetchAgentDetail, agentId] as const,
  inputForm: (agentId?: string, componentId?: string) =>
    [AgentApiAction.FetchInputForm, agentId, componentId] as const,
  versionList: (agentId?: string) =>
    [AgentApiAction.FetchVersionList, agentId] as const,
  canvasVersionList: (canvasId?: string) =>
    ['canvasVersionList', canvasId] as const,
  version: (agentId?: string, versionId?: string) =>
    [AgentApiAction.FetchVersion, agentId, versionId] as const,
};

export const useFetchAgentTemplates = () => {
  const { data } = useQuery<IFlowTemplate[]>({
    queryKey: AgentKeys.templates(),
    initialData: [],
    queryFn: async () => {
      const { data } = await agentService.listAgentTemplate();

      return data.data;
    },
  });

  return data;
};

const buildAgentListParams = ({
  page,
  pageSize,
  keywords,
  canvasCategory,
  ownerIds,
  tags,
}: {
  page: number;
  pageSize: number;
  keywords?: string;
  canvasCategory?: string;
  ownerIds?: string[];
  tags?: string[];
}) => {
  const params: Record<string, unknown> = {
    page,
    page_size: pageSize,
  };

  if (keywords) {
    params.keywords = keywords;
  }
  if (canvasCategory) {
    params.canvas_category = canvasCategory;
  }
  if (Array.isArray(ownerIds) && ownerIds.length > 0) {
    params.owner_ids = ownerIds.join(',');
  }
  if (Array.isArray(tags) && tags.length > 0) {
    params.tags = tags.join(',');
  }

  return params;
};

export const useFetchAgentListByPage = (canvasCategory?: string) => {
  const { searchString, setSearchString, handleInputChange } =
    useHandleSearchChange();
  const { pagination, setPagination } = useGetPaginationWithRouter();
  const debouncedSearchString = useDebounce(searchString, { wait: 500 });
  const { filterValue, setFilterValue, handleFilterSubmit, checkValue } =
    useHandleFilterSubmit();
  const owner = filterValue.owner;
  const tags = Array.isArray(filterValue.tags) ? filterValue.tags : undefined;

  const requestParams = buildAgentListParams({
    page: pagination.current,
    pageSize: pagination.pageSize,
    keywords: debouncedSearchString,
    canvasCategory,
    ownerIds: Array.isArray(owner) ? owner : undefined,
    tags,
  });

  const { data, isFetching: loading } = useQuery<{
    canvas: AgentListItem[];
    total: number;
  }>({
    queryKey: AgentKeys.list({
      debouncedSearchString,
      ...pagination,
      canvasCategory,
      filterValue,
    }),
    placeholderData: (previousData) => {
      if (previousData === undefined) {
        return { canvas: [], total: 0 };
      }
      return previousData;
    },
    gcTime: 0,
    queryFn: async () => {
      const { data } = await agentService.listAgents(
        {
          params: requestParams,
        },
        true,
      );

      return data?.data;
    },
  });

  const onInputChange: React.ChangeEventHandler<HTMLInputElement> = useCallback(
    (e) => {
      // setPagination({ page: 1 });
      handleInputChange(e);
    },
    [handleInputChange],
  );

  return {
    data: data?.canvas ?? [],
    loading,
    searchString,
    debouncedSearchString,
    setSearchString,
    handleInputChange: onInputChange,
    pagination: { ...pagination, total: data?.total ?? 0 },
    setPagination,
    filterValue,
    setFilterValue,
    handleFilterSubmit,
    checkValue,
  };
};

export const fetchAllAgents = async (): Promise<AgentListItem[]> => {
  const all: AgentListItem[] = [];
  let page = 1;
  let total = Number.POSITIVE_INFINITY;
  while (all.length < total) {
    const { data } = await agentService.listAgents(
      {
        params: buildAgentListParams({
          page,
          pageSize: 100,
          canvasCategory: AgentCategory.AgentCanvas,
        }),
      },
      true,
    );
    const canvas: AgentListItem[] = data?.data?.canvas ?? [];
    all.push(...canvas);
    total = data?.data?.total ?? all.length;
    if (canvas.length === 0) {
      break;
    }
    page += 1;
  }
  return all;
};

export function useFetchAllAgentList() {
  const { data, isFetching: loading } = useQuery<AgentListItem[]>({
    queryKey: AgentKeys.all(),
    queryFn: fetchAllAgents,
  });

  return { data, loading };
}

export const useUpdateAgentSetting = () => {
  const queryClient = useQueryClient();

  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.UpdateAgentSetting],
    mutationFn: async (params: any) => {
      const ret = await updateAgent(params.id, {
        title: params.title,
        description: params.description,
        permission: params.permission,
        avatar: params.avatar,
      });
      if (ret?.data?.code === 0) {
        message.success('success');
        queryClient.invalidateQueries({
          queryKey: AgentKeys.list(),
        });
        queryClient.invalidateQueries({
          queryKey: PipelineVersionKeys.catalog(),
        });
      }
      return ret?.data?.code;
    },
  });

  return { data, loading, updateAgentSetting: mutateAsync };
};

export const useDeleteAgent = () => {
  const queryClient = useQueryClient();
  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.DeleteAgent],
    mutationFn: async (agentId: string) => {
      const { data } = await agentService.deleteAgent(agentId);
      if (data.code === 0) {
        queryClient.invalidateQueries({
          queryKey: AgentKeys.list(),
        });
        queryClient.invalidateQueries({
          queryKey: PipelineVersionKeys.catalog(),
        });
        queryClient.invalidateQueries({
          queryKey: AgentKeys.filters(),
        });
        queryClient.invalidateQueries({
          queryKey: AgentKeys.tags(),
        });
        markListItemsDeleted(ListDeletionKey.AgentList);
      }
      return data?.code;
    },
  });

  return { data, loading, deleteAgent: mutateAsync };
};

export interface IAgentTagCount {
  tag: string;
  count: number;
}

export const useFetchAgentTags = (canvasCategory?: string) => {
  const { data, isFetching: loading } = useQuery<IAgentTagCount[]>({
    queryKey: AgentKeys.tags(canvasCategory),
    initialData: [],
    gcTime: 0,
    queryFn: async () => {
      const { data } = await agentService.listAgentTags(
        {
          params: canvasCategory ? { canvas_category: canvasCategory } : {},
        },
        true,
      );
      return Array.isArray(data?.data) ? data.data : [];
    },
  });
  return { data, loading };
};

export const useUpdateAgentTags = () => {
  const queryClient = useQueryClient();
  const { isPending: loading, mutateAsync } = useMutation({
    mutationKey: [AgentApiAction.UpdateAgentTags],
    mutationFn: async ({
      agentId,
      tags,
    }: {
      agentId: string;
      tags: string[];
    }) => {
      const { data } = await updateAgentTags(agentId, tags);
      if (data?.code === 0) {
        queryClient.invalidateQueries({
          queryKey: AgentKeys.list(),
        });
        queryClient.invalidateQueries({
          queryKey: AgentKeys.tags(),
        });
      } else {
        message.error(data?.message || 'Update failed');
      }
      return data?.code === 0;
    },
  });
  return { loading, updateAgentTags: mutateAsync };
};

export const useFetchAgent = (): {
  data: IFlow;
  loading: boolean;
  refetch: () => void;
} => {
  const { id } = useParams();
  const { sharedId } = useGetSharedChatSearchParams();

  const {
    data,
    isFetching: loading,
    refetch,
  } = useQuery({
    queryKey: AgentKeys.detail(sharedId || id),
    initialData: {} as IFlow,
    refetchOnReconnect: false,
    refetchOnMount: false,
    refetchOnWindowFocus: false,
    gcTime: 0,
    queryFn: async () => {
      const { data } = await agentService.getAgent(sharedId || id);

      const messageList = buildMessageListWithUuid(
        get(data, 'data.dsl.messages', []),
      );
      set(data, 'data.dsl.messages', messageList);

      const sysHistoryPath = [
        'data',
        'dsl',
        'globals',
        AgentGlobals.SysHistory,
      ];

      if (isEmpty(get(data, sysHistoryPath))) {
        set(data, sysHistoryPath, []);
      }

      return data?.data ?? {};
    },
  });

  return { data, loading, refetch };
};

export const useResetAgent = () => {
  const { id } = useParams();
  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.ResetAgent],
    mutationFn: async () => {
      const { data } = await agentService.resetAgent(id);
      return data;
    },
  });

  return { data, loading, resetAgent: mutateAsync };
};

// Every create flow (blank, template, JSON import, built-in pipeline copy)
// navigates to the new canvas; invalidate the cached metadata catalog too.
export const useCreateAgent = (showMessage: boolean = true) => {
  const queryClient = useQueryClient();
  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.CreateAgent],
    mutationFn: async (params: {
      title?: string;
      dsl?: DSL | Record<string, any>;
      avatar?: string;
      canvas_category?: string;
    }) => {
      const { data = {} } = await agentService.createAgent(params);
      if (data.code === 0) {
        queryClient.invalidateQueries({
          queryKey: PipelineVersionKeys.catalog(),
        });
        if (showMessage) message.success(i18n.t('message.created'));
      }
      return data;
    },
  });

  return { data, loading, createAgent: mutateAsync };
};

export const useSaveAgent = (
  showMessage: boolean = true,
  skipDetailRefresh: boolean = false,
) => {
  const { id } = useParams();
  const queryClient = useQueryClient();
  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.SaveAgent],
    mutationFn: async (params: {
      id?: string;
      title?: string;
      dsl?: DSL | Record<string, any>;
      avatar?: string | null;
      release?: string;
      description?: string | null;
      permission?: string;
      autosave?: boolean;
      alias?: string;
    }) => {
      const agentId = params.id ?? id;
      if (!agentId) {
        return {};
      }
      const { data = {} } = await updateAgent(agentId, {
        title: params.title,
        dsl: params.dsl,
        avatar: params.avatar,
        description: params.description,
        permission: params.permission,
        release: params.release,
        autosave: params.autosave,
        alias: params.alias,
      });
      if (data.code === 0) {
        if (showMessage) {
          message.success(i18n.t('message.modified'));
        }
        if (!params.autosave || params.release) {
          queryClient.invalidateQueries({
            queryKey: PipelineVersionKeys.catalog(),
          });
        }
        // Every save can prune the oldest unpublished versions server-side,
        // so the version history list must refetch even when autosave skips
        // the detail refresh.
        queryClient.invalidateQueries({
          queryKey: AgentKeys.versionList(agentId),
        });
        if (!skipDetailRefresh) {
          queryClient.invalidateQueries({
            queryKey: AgentKeys.detail(agentId),
          });
        }
      }
      return data;
    },
  });

  return { data, loading, saveAgent: mutateAsync };
};

// Only one file can be uploaded at a time
export const useUploadAgentFile = () => {
  const { id } = useParams();
  const [searchParams] = useSearchParams();
  const shared_id = searchParams.get('shared_id');
  const agentId = id || shared_id;
  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.UploadAgentFile],
    mutationFn: async (body: any) => {
      let nextBody = body;
      try {
        if (Array.isArray(body)) {
          nextBody = new FormData();
          body.forEach((file: File) => {
            nextBody.append('file', file as any);
          });
        }

        const { data } = await uploadAgentFile(agentId as string, nextBody);
        if (data?.code === 0) {
          message.success(i18n.t('message.uploaded'));
        }
        return data;
      } catch (error) {
        message.error(error as string);
      }
    },
  });

  return { data, loading, uploadAgentFile: mutateAsync };
};

export const useUploadAgentFileWithProgress = (identifier?: string | null) => {
  const { id } = useParams();

  type UploadParameters = Parameters<NonNullable<FileUploadProps['onUpload']>>;

  type X = { files: UploadParameters[0]; options: UploadParameters[1] };

  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.UploadAgentFileWithProgress],
    mutationFn: async ({
      files,
      options: { onError, onSuccess, onProgress },
    }: X) => {
      const formData = new FormData();
      try {
        if (Array.isArray(files)) {
          files.forEach((file: File) => {
            formData.append('file', file);
          });
        }

        const { data } = await agentService.uploadAgentFile(
          {
            agentId: identifier || id,
            data: formData,
            onUploadProgress: ({ progress }) => {
              files.forEach((file) => {
                onProgress(file, (progress || 0) * 100);
              });
            },
          },
          true,
        );
        if (data?.code === 0) {
          files.forEach((file) => {
            onSuccess(file);
          });
          message.success(i18n.t('message.uploaded'));
        }
        return data;
      } catch (error) {
        files.forEach((file) => {
          onError(file, error as Error);
        });
        message.error((error as Error)?.message || 'Upload failed');
      }
    },
  });

  return { data, loading, uploadAgentFile: mutateAsync };
};

export const useFetchMessageTrace = (canvasId?: string, isShare?: boolean) => {
  const { id } = useParams();
  // In shared mode there's no :id route param and `canvasId` actually carries
  // the share (beta) APIToken — route through fetchSharedTrace so the request
  // hits the beta-token-aware endpoint instead of /agents/<id>/logs which
  // requires a session login (fixes #14985).
  const queryId = id || canvasId;
  const [messageId, setMessageId] = useState('');
  const [isStopFetchTrace, setISStopFetchTrace] = useState(false);

  const {
    data,
    isFetching: loading,
    refetch,
  } = useQuery<ITraceData[]>({
    queryKey: [AgentApiAction.Trace, queryId, messageId, !!isShare],
    refetchOnReconnect: false,
    refetchOnMount: false,
    refetchOnWindowFocus: false,
    gcTime: 0,
    enabled: !!queryId && !!messageId,
    refetchInterval: !isStopFetchTrace ? 3000 : false,
    queryFn: async () => {
      const { data } = isShare
        ? await fetchSharedTrace({
            shared_id: queryId as string,
            message_id: messageId,
          })
        : await fetchTrace({
            canvas_id: queryId as string,
            message_id: messageId,
          });

      return Array.isArray(data?.data) ? data?.data : [];
    },
  });

  return {
    data,
    loading,
    refetch,
    setMessageId,
    messageId,
    isStopFetchTrace,
    setISStopFetchTrace,
  };
};

export const useTestDbConnect = () => {
  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.TestDbConnect],
    mutationFn: async (params: any) => {
      const ret = await agentService.testDbConnect(params);
      if (ret?.data?.code === 0) {
        const successMessage = ret?.data?.message;
        message.success(
          typeof successMessage === 'string' &&
            successMessage.trim() &&
            successMessage.trim().toLowerCase() !== 'success'
            ? successMessage
            : i18n.t('setting.dataSourceTestSuccess'),
        );
      }
      return ret;
    },
  });

  return { data, loading, testDbConnect: mutateAsync };
};

export const useFetchInputForm = (componentId?: string) => {
  const { id } = useParams();

  const { data } = useQuery<Record<string, any>>({
    queryKey: AgentKeys.inputForm(id, componentId),
    initialData: {},
    enabled: !!id && !!componentId,
    queryFn: async () => {
      const { data } = await agentService.inputForm(
        { agentId: id as string, componentId: componentId as string },
        true,
      );

      return data.data;
    },
  });

  return data;
};

export const useFetchVersionList = () => {
  const { id } = useParams();
  const { data, isFetching: loading } = useQuery<
    Array<{
      created_at: string;
      title: string;
      id: string;
      release?: boolean;
      alias?: string;
    }>
  >({
    queryKey: AgentKeys.versionList(id),
    initialData: [],
    gcTime: 0,
    queryFn: async () => {
      const { data } = await agentService.fetchVersionList(id);

      return data?.data ?? [];
    },
  });

  return { data, loading };
};

// Row shape of a published canvas version, newest-first (design section 7/E1),
// including the free-text alias (A2/F1).
export interface ICanvasVersionRow {
  id: string;
  title: string;
  created_at: string;
  release?: boolean;
  alias?: string;
}

// Query options shared by useFetchCanvasVersionList and imperative callers
// (queryClient.fetchQuery), so both hit the same cache entry.
export const canvasVersionListQuery = (canvasId?: string) =>
  ({
    queryKey: AgentKeys.canvasVersionList(canvasId),
    queryFn: async (): Promise<ICanvasVersionRow[]> => {
      if (!canvasId) return [];
      const { data } = await agentService.fetchVersionList(canvasId);
      return data?.data ?? [];
    },
  }) as const;

// Lists versions for document status displays. Parser selection uses the
// lightweight catalog instead. No initialData so pending and empty differ.
export const useFetchCanvasVersionList = (canvasId?: string) => {
  const {
    data,
    isFetching: loading,
    isError,
  } = useQuery({
    ...canvasVersionListQuery(canvasId),
    gcTime: 0,
    enabled: !!canvasId,
  });

  return { data, loading, isError };
};

// useDeleteVersion removes a single canvas version (design section 7/B2). The
// backend still allows deletion when the version is referenced by a dataset or
// file; the binding then enters a Missing (unparseable) state, so the UI shows a
// confirmation that warns about breaking bound files (B2.1).
export const useDeleteVersion = () => {
  const queryClient = useQueryClient();
  const {
    isPending: loading,
    isError,
    mutateAsync,
  } = useMutation({
    mutationFn: async ({
      canvasId,
      versionId,
    }: {
      canvasId: string;
      versionId: string;
    }) => {
      const { data } = await agentService.deleteVersion({
        agentId: canvasId,
        versionId,
      });
      return data?.code === 0;
    },
    onSuccess: (_result, variables) => {
      // Refresh version history, document status, and the parser catalog.
      queryClient.invalidateQueries({
        queryKey: AgentKeys.versionList(variables.canvasId),
      });
      queryClient.invalidateQueries({
        queryKey: AgentKeys.canvasVersionList(variables.canvasId),
      });
      queryClient.invalidateQueries({
        queryKey: PipelineVersionKeys.catalog(),
      });
    },
  });

  return { loading, isError, deleteVersion: mutateAsync };
};

export const useApplyVersion = () => {
  const queryClient = useQueryClient();
  const { isPending: loading, mutateAsync } = useMutation({
    mutationFn: async ({
      canvasId,
      versionId,
    }: {
      canvasId: string;
      versionId: string;
    }) => {
      const { data } = await agentService.applyVersion({
        agentId: canvasId,
        versionId,
      });
      return data?.code === 0;
    },
    onSuccess: (ok, { canvasId }) => {
      if (!ok) return;
      queryClient.invalidateQueries({ queryKey: AgentKeys.list() });
      queryClient.invalidateQueries({
        queryKey: AgentKeys.versionList(canvasId),
      });
      queryClient.invalidateQueries({ queryKey: AgentKeys.detail(canvasId) });
      queryClient.invalidateQueries({
        queryKey: PipelineVersionKeys.catalog(),
      });
    },
  });

  return { loading, applyVersion: mutateAsync };
};

export const useUpdateVersion = () => {
  const queryClient = useQueryClient();
  const {
    isPending: loading,
    isError,
    mutateAsync,
  } = useMutation({
    mutationFn: async ({
      canvasId,
      versionId,
      alias,
    }: {
      canvasId: string;
      versionId: string;
      alias: string;
    }) => {
      const { data } = await updateVersion(canvasId, versionId, { alias });
      return data?.code === 0;
    },
    onSuccess: (_result, variables) => {
      // The alias edit does not create a version or change the DSL, but the
      // version-list cache must reflect the new alias without a manual refresh
      // (design G2/§4.4).
      queryClient.invalidateQueries({
        queryKey: AgentKeys.versionList(variables.canvasId),
      });
      queryClient.invalidateQueries({
        queryKey: AgentKeys.canvasVersionList(variables.canvasId),
      });
      queryClient.invalidateQueries({
        queryKey: PipelineVersionKeys.catalog(),
      });
    },
  });

  return { loading, isError, updateVersion: mutateAsync };
};

// Shared query options for a single canvas version's detail (IFlow, dsl
// included). Both useFetchVersion (canvas version dialog) and
// useFetchPipelineDslByPipelineId (operator tabs) must cache the same shape
// under AgentKeys.version so they can share the entry safely.
const canvasVersionQuery = (agentId?: string, versionId?: string) => ({
  queryKey: AgentKeys.version(agentId, versionId),
  gcTime: 0,
  // A pruned version never recovers on retry, and each attempt would
  // re-fire the error path.
  retry: false,
  queryFn: async (): Promise<IFlow | undefined> => {
    if (!agentId || !versionId) return undefined;

    // Consumers render their own error/empty state, so suppress the global
    // notification whose "no permission" wording misleads here.
    const { data } = await agentService.fetchVersion(
      { agentId, versionId, skipGlobalErrorNotification: true },
      true,
    );

    if (data?.code !== 0) {
      throw new Error(data?.message);
    }

    return data?.data ?? undefined;
  },
});

export const useFetchVersion = (
  version_id?: string,
): {
  data?: IFlow;
  loading: boolean;
  isError: boolean;
} => {
  const { id } = useParams();
  const {
    data,
    isFetching: loading,
    isError,
  } = useQuery({
    ...canvasVersionQuery(id, version_id),
    enabled: !!id && !!version_id,
  });

  return { data, loading, isError };
};

export const useFetchAgentLog = (searchParams: IAgentLogsRequest) => {
  const { id } = useParams();
  const {
    data,
    isFetching: loading,
    refetch,
  } = useQuery<IAgentLogsResponse>({
    queryKey: [AgentApiAction.FetchAgentLog, id, searchParams],
    initialData: {} as IAgentLogsResponse,
    gcTime: 0,
    queryFn: async () => {
      const { data } = await fetchAgentLogsByCanvasId(id as string, {
        ...searchParams,
        include_reference: true,
      });

      return { total: data?.total ?? 0, sessions: data?.data ?? [] };
    },
  });

  return { data, loading, refetch };
};

export const AgentSessionKeys = {
  all: [AgentApiAction.FetchSessionsByCanvasId] as const,
  list: (
    canvasId?: string,
    tenantId?: string,
    operatorPermission?: Permission,
  ) =>
    [...AgentSessionKeys.all, canvasId, tenantId, operatorPermission] as const,
};

export const useFetchSessionsByCanvasId = () => {
  const { id: canvasId } = useParams();
  const { data: tenantInfo } = useFetchTenantInfo();
  const { data: agentDetail } = useFetchAgent();
  const operatorPermission = agentDetail?.operator_permission;

  return useSessionList<IAgentLogResponse>({
    queryKey: AgentSessionKeys.list(
      canvasId,
      tenantInfo.tenant_id,
      operatorPermission,
    ),
    enabled:
      !!canvasId && !isEmpty(tenantInfo) && operatorPermission !== undefined,
    fetchPage: async (params) => {
      const shouldListAllSessions = operatorPermission !== Permission.Read;
      const { data } = await fetchAgentLogsByCanvasId(canvasId!, {
        ...params,
        include_history: false,
        ...(shouldListAllSessions ? {} : { exp_user_id: tenantInfo.tenant_id }),
      });

      return { total: data?.total ?? 0, items: data?.data ?? [] };
    },
  });
};

export const useFetchExternalAgentInputs = () => {
  const { sharedId } = useGetSharedChatSearchParams();

  const {
    data,
    isFetching: loading,
    refetch,
  } = useQuery<IInputs>({
    queryKey: [AgentApiAction.FetchExternalAgentInputs, sharedId],
    initialData: {} as IInputs,
    refetchOnReconnect: false,
    // refetchOnMount: false,
    refetchOnWindowFocus: false,
    gcTime: 0,
    enabled: !!sharedId,
    queryFn: async () => {
      const { data } = await agentService.fetchExternalAgentInputs(sharedId!);

      return data?.data ?? {};
    },
  });

  return { data, loading, refetch };
};

export const useFetchPrompt = () => {
  const {
    data,
    isFetching: loading,
    refetch,
  } = useQuery<Record<string, string>>({
    queryKey: [AgentApiAction.FetchPrompt],
    refetchOnReconnect: false,
    refetchOnMount: false,
    refetchOnWindowFocus: false,
    gcTime: 0,
    queryFn: async () => {
      const { data } = await agentService.fetchPrompt();

      return data?.data ?? {};
    },
  });

  return { data, loading, refetch };
};

export const useFetchAgentList = ({
  canvas_category,
}: IPipeLineListRequest) => {
  const { data, isFetching: loading } = useQuery<{
    canvas: AgentListItem[];
    total: number;
  }>({
    queryKey: AgentKeys.listAll(canvas_category),
    initialData: { canvas: [], total: 0 },
    gcTime: 0,
    queryFn: async () => {
      const { data } = await fetchPipeLineList({
        canvas_category,
      });

      return data?.data ?? [];
    },
  });

  return { data, loading };
};

export interface IAgentOwnerFilter {
  id: string;
  label: string;
  count: number;
}

export interface IAgentCategoryFilter {
  id: string;
  count: number;
}

export const useFetchAgentFilters = (canvasCategory?: string) => {
  const { data, isFetching: loading } = useQuery<{
    filter: {
      owner: IAgentOwnerFilter[];
      canvas_category: IAgentCategoryFilter[];
    };
    total: number;
  }>({
    queryKey: AgentKeys.filters(canvasCategory),
    initialData: { filter: { owner: [], canvas_category: [] }, total: 0 },
    gcTime: 0,
    queryFn: async () => {
      const { data } = await agentService.listAgents(
        {
          params: {
            type: 'filter',
            ...(canvasCategory ? { canvas_category: canvasCategory } : {}),
          },
        },
        true,
      );
      return (
        data?.data ?? { filter: { owner: [], canvas_category: [] }, total: 0 }
      );
    },
  });

  return {
    data: data?.filter ?? { owner: [], canvas_category: [] },
    loading,
  };
};

export const BuiltinPipelineKeys = {
  list: (type: string) =>
    [AgentApiAction.FetchBuiltinPipelineList, type] as const,
  detail: (id: string) =>
    [AgentApiAction.FetchBuiltinPipelineDetail, id] as const,
};

export const useFetchBuiltinPipelines = () => {
  const { data, isFetching: loading } = useQuery<IBuiltinPipelineListResponse>({
    queryKey: BuiltinPipelineKeys.list('builtin'),
    initialData: { canvas: [], total: 0 },
    gcTime: 0,
    queryFn: async () => {
      const { data } = await agentService.listBuiltinPipelines(
        { params: { type: 'builtin' } },
        true,
      );
      return data?.data ?? { canvas: [], total: 0 };
    },
  });

  const options =
    data?.canvas?.map((item) => ({
      label: item.title,
      value: item.id,
    })) ?? [];

  return { data, loading, options };
};

export const useCancelDataflow = () => {
  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.CancelDataflow],
    mutationFn: async (taskId: string) => {
      const ret = await agentService.cancelDataflow(taskId);
      if (ret?.data?.code === 0) {
        message.success('success');
      } else {
        message.error(ret?.data?.message);
      }
      return ret?.data?.code;
    },
  });

  return { data, loading, cancelDataflow: mutateAsync };
};

// export const useFetchKnowledgeList = () => {
//   const { data, isFetching: loading } = useQuery<IFlow[]>({
//     queryKey: [AgentApiAction.FetchAgentList],
//     initialData: [],
//     gcTime: 0, // https://tanstack.com/query/latest/docs/framework/react/guides/caching?from=reactQueryV3
//     queryFn: async () => {
//       const { data } = await agentService.listAgents();

//       return data?.data ?? [];
//     },
//   });

//   return { list: data, loading };
// };

export function useCancelConversation() {
  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.CancelCanvas],
    mutationFn: async (taskId: string) => {
      const ret = await agentService.cancelCanvas(taskId);

      return ret?.data?.code;
    },
  });

  return { data, loading, cancelConversation: mutateAsync };
}

export const useFetchFlowSSE = (): {
  data: IFlow;
  loading: boolean;
  refetch: () => void;
} => {
  const { sharedId } = useGetSharedChatSearchParams();

  const {
    data,
    isFetching: loading,
    refetch,
  } = useQuery({
    queryKey: [AgentApiAction.FetchSharedAgent, sharedId],
    initialData: {} as IFlow,
    enabled: !!sharedId,
    refetchOnReconnect: false,
    refetchOnMount: false,
    refetchOnWindowFocus: false,
    gcTime: 0,
    queryFn: async () => {
      if (!sharedId) return {};
      const { data } = await agentService.getAgent(sharedId);

      const messageList = buildMessageListWithUuid(
        get(data, 'data.dsl.messages', []),
      );
      set(data, 'data.dsl.messages', messageList);

      return data?.data ?? {};
    },
  });

  return { data, loading, refetch };
};

export const useFetchWebhookTrace = (autoStart: boolean = true) => {
  const { id } = useParams();
  const [currentWebhookId, setCurrentWebhookId] = useState<string>('');
  const [currentNextSinceTs, setCurrentNextSinceTs] = useState<number>(0);
  const [shouldPoll, setShouldPoll] = useState(autoStart);

  const {
    data,
    isFetching: loading,
    refetch,
  } = useQuery<IWebhookTrace>({
    queryKey: [AgentApiAction.FetchWebhookTrace, id],
    refetchOnReconnect: false,
    refetchOnMount: false,
    refetchOnWindowFocus: false,
    refetchIntervalInBackground: false,
    gcTime: 0,
    enabled: !!id && shouldPoll,
    queryFn: async () => {
      if (!id) return {};

      const payload: IAgentWebhookTraceRequest =
        {} as IAgentWebhookTraceRequest;

      if (currentNextSinceTs) {
        payload['since_ts'] = currentNextSinceTs;
      }

      if (currentWebhookId) {
        payload['webhook_id'] = currentWebhookId;
      }

      const { data } = await fetchWebhookTrace(id, payload);

      const result = data.data ?? {};

      if (result.webhook_id && result.webhook_id !== currentWebhookId) {
        setCurrentWebhookId(result.webhook_id);
      }

      if (
        currentNextSinceTs === 0 &&
        result.next_since_ts &&
        result.next_since_ts !== currentNextSinceTs
      ) {
        setCurrentNextSinceTs(result.next_since_ts);
      }

      if (result.finished) {
        setShouldPoll(false);
      }

      return result;
    },
    refetchInterval: shouldPoll ? 3000 : false,
  });

  return {
    data,
    loading,
    refetch,
    isPolling: shouldPoll,
    currentWebhookId,
    currentNextSinceTs,
  };
};

export function useCreateAgentWebhookCredential() {
  const { id } = useParams();
  const { mutateAsync, isPending: loading } = useMutation({
    mutationKey: [AgentApiAction.CreateWebhookCredential],
    mutationFn: async () => {
      if (!id) throw new Error('Agent ID is required');

      const { data } = await issueAgentWebhookCredential(id);
      if (data?.code !== 0 || !data?.data?.webhook_url) {
        throw new Error(data?.message || 'Failed to create webhook URL');
      }

      return data.data as IAgentWebhookCredential;
    },
  });

  return { createWebhookCredential: mutateAsync, loading };
}

export function useRevokeAgentWebhookCredential() {
  const { id } = useParams();
  const { mutateAsync, isPending: loading } = useMutation({
    mutationKey: [AgentApiAction.RevokeWebhookCredential],
    mutationFn: async () => {
      if (!id) throw new Error('Agent ID is required');

      const { data } = await revokeAgentWebhookCredential(id);
      if (data?.code !== 0) {
        throw new Error(data?.message || 'Failed to revoke webhook URL');
      }
    },
  });

  return { revokeWebhookCredential: mutateAsync, loading };
}

export function useCreateAgentSession() {
  const queryClient = useQueryClient();

  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.CreateAgentSession],
    mutationFn: async (payload: { id: string; name: string }) => {
      const { data } = await createAgentSession(payload);

      if (data.code === 0) {
        queryClient.invalidateQueries({
          queryKey: AgentSessionKeys.all,
        });
        return data.data;
      }

      throw new Error(data.message);
    },
  });

  return { data, loading, createAgentSession: mutateAsync };
}

export function useDeleteAgentSession() {
  const queryClient = useQueryClient();

  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation({
    mutationKey: [AgentApiAction.DeleteAgentSession],
    mutationFn: async ({
      canvasId,
      sessionId,
    }: {
      canvasId: string;
      sessionId: string;
    }) => {
      const { data } = await deleteAgentSession(canvasId, sessionId);

      if (data.code === 0) {
        queryClient.invalidateQueries({
          queryKey: AgentSessionKeys.all,
        });
      }

      return data?.code ?? -1;
    },
  });

  return { data, loading, deleteAgentSession: mutateAsync };
}

export function useFetchSessionManually() {
  const { id: canvasId } = useParams();

  const {
    data,
    isPending: loading,
    mutateAsync,
  } = useMutation<IAgentLogResponse, unknown, string>({
    mutationKey: [AgentApiAction.FetchSessionByIdManually, canvasId],
    mutationFn: async (sessionId) => {
      if (!canvasId || !sessionId) {
        return null;
      }

      const { data } = await fetchAgentLogsById(canvasId, sessionId, {
        include_reference: true,
        include_prompt: true,
      });

      return data?.data;
    },
  });

  return { data, loading, fetchSessionManually: mutateAsync };
}

export const useExportAgentLog = () => {
  const { id } = useParams();
  const { mutateAsync, isPending: loading } = useMutation({
    mutationKey: [AgentApiAction.FetchAgentLog, 'export', id],
    mutationFn: async (searchParams: IAgentLogsRequest) => {
      const { data } = await fetchAgentLogsByCanvasId(id as string, {
        ...searchParams,
      });

      return data?.data ?? [];
    },
  });

  return { exportLogs: mutateAsync, loading };
};

// useFetchPipelineDslByPipelineId loads the DSL that backs the pipeline
// operator tabs. Builtin pipelines have no version concept and are fetched
// directly; a dataflow pipeline is versioned, so its DSL comes from the
// selected canvas version — without a version id nothing is fetched and the
// tabs stay hidden.
export const useFetchPipelineDslByPipelineId = (
  pipelineId?: string,
  versionId?: string,
  isBuiltin = false,
) => {
  const { data: builtinDsl, isFetching: builtinLoading } = useQuery({
    queryKey: BuiltinPipelineKeys.detail(pipelineId!),
    gcTime: 0,
    enabled: isBuiltin && !!pipelineId,
    queryFn: async (): Promise<DSL | undefined> => {
      const { data } = await agentService.getBuiltinPipeline(pipelineId!);
      return data?.data?.dsl;
    },
  });
  const { data: version, isFetching: versionLoading } = useQuery({
    ...canvasVersionQuery(pipelineId, versionId),
    enabled: !isBuiltin && !!pipelineId && !!versionId,
  });

  return {
    dsl: isBuiltin ? builtinDsl : version?.dsl,
    loading: isBuiltin ? builtinLoading : versionLoading,
  };
};