Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

33.0 KB
Raw Blame
import { apId, ErrorCode, isNil, tryCatch } from '@activepieces/core-utils';
import {
  ActionPreviewEvent,
  ActionReceiptEvent,
  BuildPlanEvent,
  AgentAllowedMimeType,
  FileProducedEvent,
  ImageGeneratedEvent,
  AgentConversationStatus,
  AgentHistoryMessage,
  CHAT_ALLOWED_MIME_TYPES,
  PersistedAgentMessage,
  ToolProgressEvent,
  AgentMessageSource,
  SubagentActivity,
  subagentProgressId,
  SubagentProgressEvent,
} from '@activepieces/shared';
import { t } from 'i18next';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { toast } from 'sonner';

import { api } from '@/lib/api';
import { chatDebug } from '@/lib/chat-debug-logger';

import { chatApi, type PendingGate } from './chat-api';
import {
  chatBuildUtils,
  chatStoreSelectors,
  SetChatStore,
  ToolCallMeta,
} from './chat-store';
import { useChatStoreApi, useChatStoreContext } from './chat-store-context';
import { ChatUIMessage, QuickRepliesData, chatPartUtils } from './chat-types';
import { ChatModelPick, chatUtils } from './chat-utils';
import { useStreamingReducer } from './use-streaming-reducer';

function applyQuickRepliesToStore({
  setState,
  data,
}: {
  setState: SetChatStore;
  data: QuickRepliesData;
}): void {
  if (data.replies.length === 0 && !data.offerRecurringAutomation) return;
  setState({
    quickReplies: data.replies,
    offerRecurringAutomation: data.offerRecurringAutomation,
  });
}

function restoreReceiptsIntoStore({
  data,
  setState,
}: {
  data: PersistedAgentMessage[] | AgentHistoryMessage[];
  setState: SetChatStore;
}): void {
  const receipts = chatUtils.extractReceiptsFromHistory(data);
  const images = chatUtils.extractImagesFromHistory(data);
  const files = chatUtils.extractFilesFromHistory(data);
  const builds = chatUtils.extractBuildsFromHistory(data);
  if (
    Object.keys(receipts).length === 0 &&
    Object.keys(images).length === 0 &&
    Object.keys(files).length === 0 &&
    Object.keys(builds).length === 0
  ) {
    return;
  }
  setState((prev) => {
    const merged = { ...prev.toolCallMeta };
    for (const [toolCallId, receipt] of Object.entries(receipts)) {
      merged[toolCallId] = { ...merged[toolCallId], actionReceipt: receipt };
    }
    for (const [toolCallId, image] of Object.entries(images)) {
      merged[toolCallId] = { ...merged[toolCallId], image };
    }
    for (const [toolCallId, toolFiles] of Object.entries(files)) {
      merged[toolCallId] = { ...merged[toolCallId], files: toolFiles };
    }
    const mergedBuilds = { ...prev.builds };
    for (const [buildId, build] of Object.entries(builds)) {
      const existing = mergedBuilds[buildId];
      if (existing && existing.updatedAt >= build.updatedAt) continue;
      mergedBuilds[buildId] = build;
    }
    return { toolCallMeta: merged, builds: mergedBuilds };
  });
}

const MAX_FILE_SIZE = 10 * 1024 * 1024;
const TOOL_GATES_WITHOUT_A_PIECE = new Set([
  'ap_send_email',
  'ap_test_flow',
  'ap_delete_records',
  'ap_delete_table',
  'ap_delete_flow',
  'ap_manage_fields',
  'ap_remember',
  'ap_create_agent',
  'ap_update_agent',
  'ap_add_agent_tool',
  'ap_remove_agent_tool',
]);

function buildToolCallMetaFromGate(
  gate: PendingGate,
): Record<string, ToolCallMeta> {
  if (chatPartUtils.isDisplayTool(gate.toolName)) {
    return {};
  }
  const gateInput = gate.toolInput ?? {};
  const pieceName =
    typeof gateInput.pieceName === 'string' ? gateInput.pieceName : '';
  const actionName =
    typeof gateInput.actionName === 'string' ? gateInput.actionName : '';
  let actionPreview: ActionPreviewEvent | null = null;
  if (pieceName && actionName) {
    actionPreview = {
      toolCallId: gate.gateId,
      pieceName,
      actionName,
      actionDisplayName: gate.displayName,
      connectionLabel:
        typeof gateInput.connectionLabel === 'string'
          ? gateInput.connectionLabel
          : undefined,
      input:
        typeof gateInput.input === 'object' && gateInput.input !== null
          ? (gateInput.input as Record<string, unknown>)
          : {},
      isBatch:
        typeof gateInput.batchCount === 'number' && gateInput.batchCount > 0,
      batchCount:
        typeof gateInput.batchCount === 'number'
          ? gateInput.batchCount
          : undefined,
      batchSamples: Array.isArray(gateInput.items)
        ? (gateInput.items as Record<string, unknown>[]).slice(0, 3)
        : undefined,
    };
  } else if (TOOL_GATES_WITHOUT_A_PIECE.has(gate.toolName)) {
    actionPreview = {
      toolCallId: gate.gateId,
      pieceName: '',
      actionName: gate.toolName,
      actionDisplayName: gate.displayName,
      input: gate.toolName === 'ap_test_flow' ? {} : gateInput,
      isBatch: false,
    };
  }
  if (!actionPreview) return {};
  return {
    [gate.gateId]: {
      actionPreview: gate.taskTitle
        ? { ...actionPreview, taskTitle: gate.taskTitle }
        : actionPreview,
    },
  };
}

// History only persists resolved tool calls, so a live pending gate loses its `input-available`
// part on remount — without it the store selectors find no anchor and the card disappears.
function buildGatePart(gate: PendingGate) {
  return {
    type: 'dynamic-tool' as const,
    toolCallId: gate.gateId,
    toolName: gate.toolName,
    title: gate.displayName,
    state: 'input-available' as const,
    input: gate.toolInput,
  };
}

function buildRunningTaskPart({
  toolCallId,
  title,
}: {
  toolCallId: string;
  title: string;
}) {
  return {
    type: 'dynamic-tool' as const,
    toolCallId,
    toolName: 'ap_run_task',
    title,
    state: 'input-available' as const,
    input: { title },
  };
}

function appendRunningTaskParts({
  messages,
  toolCallMeta,
}: {
  messages: ChatUIMessage[];
  toolCallMeta: Record<string, ToolCallMeta>;
}): ChatUIMessage[] {
  return Object.entries(toolCallMeta).reduce(
    (current, [toolCallId, meta]) =>
      meta.subagent?.status === 'running'
        ? appendTrailingPart({
            messages: current,
            part: buildRunningTaskPart({
              toolCallId,
              title: meta.subagent.title,
            }),
          })
        : current,
    messages,
  );
}

function appendTrailingPart({
  messages,
  part,
}: {
  messages: ChatUIMessage[];
  part: ReturnType<typeof buildGatePart>;
}): ChatUIMessage[] {
  const baseToolCallId = subagentProgressId.baseOf(part.toolCallId);
  const alreadyAnchored = messages.some((m) =>
    m.parts.some(
      (existing) =>
        'toolCallId' in existing &&
        (existing.toolCallId === part.toolCallId ||
          existing.toolCallId === baseToolCallId),
    ),
  );
  if (alreadyAnchored) return messages;
  const last = messages[messages.length - 1];
  if (last?.role === 'assistant') {
    const next = [...messages];
    next[next.length - 1] = {
      ...last,
      parts: [...last.parts, part],
    };
    return next;
  }
  return [
    ...messages,
    {
      id: `live-${part.toolCallId}`,
      role: 'assistant',
      parts: [part],
    },
  ];
}

function progressOf(activity: SubagentActivity): number {
  return activity.stepCount + (activity.timeline?.length ?? 0);
}

const ALLOWED_MIME_SET: ReadonlySet<string> = new Set(CHAT_ALLOWED_MIME_TYPES);

function isAllowedMimeType(value: string): value is AgentAllowedMimeType {
  return ALLOWED_MIME_SET.has(value);
}

function fileToBase64(
  file: File,
): Promise<{ name: string; mimeType: AgentAllowedMimeType; data: string }> {
  return new Promise((resolve, reject) => {
    const mimeType = file.type || 'application/octet-stream';
    if (!isAllowedMimeType(mimeType)) {
      reject(new Error(`Unsupported file type: ${mimeType}`));
      return;
    }
    const reader = new FileReader();
    reader.onload = () => {
      const result = reader.result;
      if (typeof result !== 'string') {
        reject(new Error('Failed to read file'));
        return;
      }
      const base64 = result.split(',')[1];
      resolve({ name: file.name, mimeType, data: base64 });
    };
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
}

function fileNamesToFileParts(fileNames: string[]): ChatUIMessage['parts'] {
  return fileNames.map((name) => ({
    type: 'file' as const,
    mediaType: 'text/plain' as const,
    url: '',
    filename: name,
  }));
}

function injectFilePartsIntoLastUserMessage({
  messages,
  fileNames,
}: {
  messages: ChatUIMessage[];
  fileNames: string[];
}): ChatUIMessage[] {
  if (fileNames.length === 0) return messages;
  const lastUserIdx = messages.findLastIndex((m) => m.role === 'user');
  if (lastUserIdx === -1) return messages;
  const lastUser = messages[lastUserIdx];
  const alreadyHasFiles = lastUser.parts.some((p) => p.type === 'file');
  if (alreadyHasFiles) return messages;
  const patched = {
    ...lastUser,
    parts: [...lastUser.parts, ...fileNamesToFileParts(fileNames)],
  };
  const result = [...messages];
  result[lastUserIdx] = patched;
  return result;
}

function isSendCancelled({
  statusRef,
}: {
  statusRef: { current: SendStatus };
}): boolean {
  return statusRef.current.type === 'cancelled';
}

type SendStatus =
  | { type: 'idle' }
  | { type: 'submitting' }
  | { type: 'cancelled' }
  | { type: 'error'; message: string | null };

export function useAgentChat({
  agentId,
  builder,
  projectId,
  onTitleUpdate,
  onConversationCreated,
  onCreditsExhausted,
  onTurnEnd,
}: {
  agentId?: string;
  builder?: boolean;
  projectId?: string | null;
  onTitleUpdate?: (title: string) => void;
  onConversationCreated?: (conversationId: string) => void;
  onCreditsExhausted?: () => void;
  onTurnEnd?: () => void;
} = {}) {
  const store = useChatStoreApi();
  const toolCallMeta = useChatStoreContext((state) => state.toolCallMeta);

  const [conversationId, setConversationIdState] = useState<string | null>(
    null,
  );
  const [modelPick, setModelPickState] = useState<ChatModelPick | null>(null);
  const [conversationProjectId, setConversationProjectId] = useState<
    string | null
  >(null);
  const [isLoadingHistory, setIsLoadingHistory] = useState(false);
  const [sendStatus, setSendStatus] = useState<SendStatus>({ type: 'idle' });
  const sendStatusRef = useRef<SendStatus>({ type: 'idle' });
  const onCreditsExhaustedRef = useRef(onCreditsExhausted);
  onCreditsExhaustedRef.current = onCreditsExhausted;

  const [persistedMessages, setPersistedMessages] = useState<ChatUIMessage[]>(
    [],
  );
  const persistedMessagesRef = useRef(persistedMessages);
  persistedMessagesRef.current = persistedMessages;
  const [optimisticUserMessage, setOptimisticUserMessage] =
    useState<ChatUIMessage | null>(null);
  const optimisticUserMessageRef = useRef(optimisticUserMessage);
  optimisticUserMessageRef.current = optimisticUserMessage;

  const pendingFilesRef = useRef<
    { name: string; mimeType: AgentAllowedMimeType; data: string }[] | undefined
  >(undefined);
  const lastSentFileNamesRef = useRef<string[]>([]);
  const lastSentRef = useRef<{ content: string; files?: File[] } | null>(null);
  const conversationIdRef = useRef<string | null>(null);
  const modelPickRef = useRef<ChatModelPick | null>(null);
  const savedPickRef = useRef<ChatModelPick | null>(null);
  const pickSaveQueueRef = useRef<Promise<unknown>>(Promise.resolve());
  const projectIdRef = useRef(projectId ?? null);
  projectIdRef.current = projectId ?? null;
  const onTitleUpdateRef = useRef(onTitleUpdate);
  onTitleUpdateRef.current = onTitleUpdate;
  const onConversationCreatedRef = useRef(onConversationCreated);
  onConversationCreatedRef.current = onConversationCreated;

  const handleTitleUpdate = useCallback((title: string) => {
    onTitleUpdateRef.current?.(title);
  }, []);

  const handleToolProgress = useCallback(
    (event: ToolProgressEvent) => {
      store.setState((prev) => {
        const existing = prev.toolCallMeta[event.toolCallId]?.batchProgress;
        if (
          existing &&
          existing.completed === event.data.completed &&
          existing.done === event.data.done
        ) {
          return prev;
        }
        return {
          toolCallMeta: {
            ...prev.toolCallMeta,
            [event.toolCallId]: {
              ...prev.toolCallMeta[event.toolCallId],
              batchProgress: event.data,
            },
          },
        };
      });
    },
    [store],
  );

  const handleSubagentProgress = useCallback(
    (event: SubagentProgressEvent) => {
      store.setState((prev) => {
        const existing = prev.toolCallMeta[event.toolCallId]?.subagent;
        const isStale =
          existing !== undefined &&
          (existing.status !== 'running' ||
            progressOf(existing) > progressOf(event.data)) &&
          event.data.status === 'running';
        if (isStale) {
          return prev;
        }
        const opensPanel =
          prev.taskPanelAutoOpen &&
          prev.taskPanelToolCallId === null &&
          chatStoreSelectors.taskPanelDocks(prev) &&
          (event.data.timeline ?? []).some((entry) => entry.kind === 'search');
        return {
          toolCallMeta: {
            ...prev.toolCallMeta,
            [event.toolCallId]: {
              ...prev.toolCallMeta[event.toolCallId],
              subagent: event.data,
            },
          },
          ...(opensPanel ? { taskPanelToolCallId: event.toolCallId } : {}),
        };
      });
    },
    [store],
  );

  const updateToolCallMeta = useCallback(
    <K extends keyof ToolCallMeta>(
      key: K,
      event: ToolCallMeta[K] & { toolCallId: string },
    ) => {
      store.setState((prev) => ({
        toolCallMeta: {
          ...prev.toolCallMeta,
          [event.toolCallId]: {
            ...prev.toolCallMeta[event.toolCallId],
            [key]: event,
          },
        },
      }));
    },
    [store],
  );

  const handleActionPreview = useCallback(
    (event: ActionPreviewEvent) => {
      updateToolCallMeta('actionPreview', event);
    },
    [updateToolCallMeta],
  );

  const handleActionReceipt = useCallback(
    (event: ActionReceiptEvent) => {
      updateToolCallMeta('actionReceipt', event);
    },
    [updateToolCallMeta],
  );

  const handleImageGenerated = useCallback(
    (event: ImageGeneratedEvent) => {
      updateToolCallMeta('image', event);
    },
    [updateToolCallMeta],
  );

  const handleFileProduced = useCallback(
    (event: FileProducedEvent) => {
      store.setState((prev) => {
        const existing = prev.toolCallMeta[event.toolCallId]?.files ?? [];
        if (existing.some((file) => file.fileId === event.fileId)) return prev;
        return {
          toolCallMeta: {
            ...prev.toolCallMeta,
            [event.toolCallId]: {
              ...prev.toolCallMeta[event.toolCallId],
              files: [...existing, event],
            },
          },
        };
      });
    },
    [store],
  );

  const handleBuildPlan = useCallback(
    (event: BuildPlanEvent) => {
      store.setState((prev) => {
        const builds = chatBuildUtils.mergeBuildPlan({
          builds: prev.builds,
          event,
        });
        if (builds === prev.builds) return prev;
        return { builds };
      });
    },
    [store],
  );

  const updateSendStatus = useCallback((next: SendStatus) => {
    sendStatusRef.current = next;
    setSendStatus(next);
  }, []);

  const reconcile = useCallback(
    async (convId: string): Promise<ChatUIMessage[] | null> => {
      if (conversationIdRef.current !== convId) return null;
      const { data: result } = await tryCatch(() =>
        chatApi.getMessages(convId),
      );
      if (conversationIdRef.current !== convId) return null;
      if (!result) return null;
      const mapped = chatUtils.mapHistoryToUIMessages(result.data);
      setPersistedMessages(mapped);
      const restored = chatUtils.extractQuickRepliesFromHistory(mapped);
      applyQuickRepliesToStore({ setState: store.setState, data: restored });
      restoreReceiptsIntoStore({
        data: result.data,
        setState: store.setState,
      });
      return mapped;
    },
    [store],
  );

  const settleStreamRef = useRef<
    (
      convId: string,
      opts?: { errorMessage?: string; suppressNoReply?: boolean },
    ) => void
  >(() => {});

  const {
    streamingMessage,
    streamPhase,
    streamError,
    streamGeneration,
    isResumedStream,
    startStream,
    setActiveRunId,
    stopStream,
    clearStreamingState,
  } = useStreamingReducer({
    onTitleUpdate: handleTitleUpdate,
    onToolProgress: handleToolProgress,
    onActionPreview: handleActionPreview,
    onActionReceipt: handleActionReceipt,
    onImageGenerated: handleImageGenerated,
    onFileProduced: handleFileProduced,
    onBuildPlan: handleBuildPlan,
    onSubagentProgress: handleSubagentProgress,
    onStreamFinished: (convId) => {
      chatDebug.info({ conversation: { id: convId } }, 'stream finished');
      settleStreamRef.current(convId);
    },
    onStreamError: ({ conversationId: convId, errorCode, errorMessage }) => {
      chatDebug.error(
        { conversation: { id: convId }, errorCode, error: errorMessage },
        'stream error',
      );
      if (errorCode === ErrorCode.QUOTA_EXCEEDED) {
        onCreditsExhaustedRef.current?.();
        settleStreamRef.current(convId, { suppressNoReply: true });
        return;
      }
      settleStreamRef.current(convId, { errorMessage });
    },
    onStaleCheck: (convId) => {
      void tryCatch(async () => {
        const conv = await chatApi.getConversation(convId);
        if (isNil(conv) || conversationIdRef.current !== convId) return;

        if (conv.status !== AgentConversationStatus.STREAMING) {
          settleStreamRef.current(convId);
        }
      });
    },
  });

  // Settles a stream once the run ends. Reconciles server history into the view,
  // but never wipes the user's message on an empty reconcile (e.g. the worker
  // never ran), and surfaces an error — explicit, or a "no response" fallback
  // when the run ended without an assistant reply — instead of blanking the panel.
  settleStreamRef.current = (convId, opts) => {
    const gen = streamGeneration.current;
    void reconcile(convId).then((mapped) => {
      if (conversationIdRef.current !== convId) return;
      // Defense-in-depth: a settled turn's history should only ever grow (it now
      // includes the just-finished reply). Refuse a strictly-shorter reconcile so
      // a transient server hiccup can never collapse the visible conversation.
      const isShrink =
        mapped !== null && mapped.length < persistedMessagesRef.current.length;
      const history = mapped && mapped.length > 0 && !isShrink ? mapped : null;
      if (history) {
        setPersistedMessages(history);
        setOptimisticUserMessage(null);
      }
      const hasReply =
        history !== null &&
        history.findLastIndex((m) => m.role === 'assistant') >
          history.findLastIndex((m) => m.role === 'user');
      if (opts?.errorMessage) {
        const lastReply = history?.at(-1);
        const failureIsInTranscript =
          lastReply?.role === 'assistant' &&
          lastReply.parts.some(
            (part) => part.type === 'text' && part.text === opts.errorMessage,
          );
        updateSendStatus({
          type: 'error',
          message: failureIsInTranscript ? null : opts.errorMessage,
        });
      } else if (!hasReply && !opts?.suppressNoReply) {
        updateSendStatus({
          type: 'error',
          message: t('The assistant did not respond. Please try again.'),
        });
      }
      clearStreamingState(gen);
    });
  };

  const streamingQuickReplies = useMemo(
    () => chatPartUtils.extractQuickRepliesFromParts(streamingMessage),
    [streamingMessage],
  );

  useEffect(() => {
    applyQuickRepliesToStore({
      setState: store.setState,
      data: streamingQuickReplies,
    });
  }, [streamingQuickReplies, store]);

  const isStreamActive = streamPhase !== 'idle';
  const onTurnEndRef = useRef(onTurnEnd);
  onTurnEndRef.current = onTurnEnd;
  const wasStreamActiveRef = useRef(false);
  useEffect(() => {
    if (wasStreamActiveRef.current && !isStreamActive) {
      onTurnEndRef.current?.();
    }
    wasStreamActiveRef.current = isStreamActive;
  }, [isStreamActive]);

  const isStreaming =
    isStreamActive || sendStatusRef.current.type === 'submitting';

  const isAwaitingResponse =
    streamPhase === 'awaiting-stream' ||
    streamPhase === 'streaming' ||
    sendStatus.type === 'submitting';

  const messages: ChatUIMessage[] = useMemo(() => {
    const base = [...persistedMessages];
    if (optimisticUserMessage) base.push(optimisticUserMessage);
    if (streamingMessage) base.push(streamingMessage);
    return appendRunningTaskParts({
      messages: injectFilePartsIntoLastUserMessage({
        messages: base,
        fileNames: lastSentFileNamesRef.current,
      }),
      toolCallMeta,
    });
  }, [
    persistedMessages,
    optimisticUserMessage,
    streamingMessage,
    toolCallMeta,
  ]);

  const error =
    sendStatus.type === 'error' ? sendStatus.message : streamError ?? null;
  const failed = sendStatus.type === 'error' || !isNil(streamError);

  const wasCancelled = sendStatus.type === 'cancelled';

  const streamingMessageRef = useRef(streamingMessage);
  streamingMessageRef.current = streamingMessage;

  // Folds the in-flight turn (optimistic user message + live streaming assistant)
  // into persisted history so it stays painted continuously when the turn is
  // preempted or cancelled — otherwise both halves live only in ephemeral state
  // and vanish until the next end-of-turn reconcile. Deduped by id so it can
  // never double-add; the reconcile later replaces persisted with authoritative
  // server history.
  const commitInFlightTurn = useCallback(() => {
    const inflightUser = optimisticUserMessageRef.current;
    const inflightStreaming = streamingMessageRef.current;
    const hasStreaming =
      !!inflightStreaming && inflightStreaming.parts.length > 0;
    if (!inflightUser && !hasStreaming) return;
    setPersistedMessages((prev) => {
      const existingIds = new Set(prev.map((m) => m.id));
      const additions: ChatUIMessage[] = [];
      if (inflightUser && !existingIds.has(inflightUser.id)) {
        additions.push(inflightUser);
      }
      if (
        hasStreaming &&
        inflightStreaming &&
        !existingIds.has(inflightStreaming.id)
      ) {
        additions.push(inflightStreaming);
      }
      return additions.length > 0 ? [...prev, ...additions] : prev;
    });
  }, []);

  const cancelStream = useCallback(() => {
    commitInFlightTurn();
    stopStream();
    setOptimisticUserMessage(null);
    updateSendStatus({ type: 'cancelled' });
    const convId = conversationIdRef.current;
    if (convId) {
      void chatApi.cancelConversation(convId);
    }
  }, [commitInFlightTurn, stopStream, updateSendStatus]);

  const createConversation = useCallback(
    async ({
      title,
      pick,
    }: { title?: string | null; pick?: ChatModelPick | null } = {}) => {
      const chatProjectId = projectIdRef.current;
      const conv = await chatApi.createConversation({
        title: title ?? null,
        ...(agentId === undefined
          ? {
              ...(pick ?? {}),
              ...(isNil(chatProjectId) ? {} : { projectId: chatProjectId }),
            }
          : { agentId }),
        ...(builder === undefined ? {} : { builder }),
      });
      setConversationProjectId(conv.projectId ?? null);
      savedPickRef.current = pick ?? null;
      conversationIdRef.current = conv.id;
      setConversationIdState(conv.id);
      const latestPick = modelPickRef.current;
      if (!isNil(latestPick) && latestPick !== (pick ?? null)) {
        pickSaveQueueRef.current = pickSaveQueueRef.current.then(async () => {
          const { error } = await tryCatch(() =>
            chatApi.updateConversation(conv.id, latestPick),
          );
          if (isNil(error)) {
            savedPickRef.current = latestPick;
          }
        });
      }
      return conv;
    },
    [agentId, builder],
  );

  const sendMessage = useCallback(
    async (
      content: string,
      files?: File[],
      options?: { messageSource?: AgentMessageSource },
    ) => {
      updateSendStatus({ type: 'submitting' });
      await pickSaveQueueRef.current;
      if (isSendCancelled({ statusRef: sendStatusRef })) {
        return;
      }

      const fileNames = files?.map((f) => f.name) ?? [];
      lastSentFileNamesRef.current = fileNames;
      lastSentRef.current = { content, files };

      const optimisticUser: ChatUIMessage = {
        id: `optimistic-${Date.now()}`,
        role: 'user',
        parts: [
          { type: 'text', text: content },
          ...fileNamesToFileParts(fileNames),
        ],
      };

      // Preempting an in-flight turn: keep its messages on screen by folding them
      // into persisted history before they get overwritten/reset below, then clear
      // the live stream so it isn't shown twice during the send.
      commitInFlightTurn();
      stopStream();
      setOptimisticUserMessage(optimisticUser);
      store.getState().resetInteractions();

      if (files && files.length > 0) {
        const oversized = files.find((f) => f.size > MAX_FILE_SIZE);
        if (oversized) {
          setOptimisticUserMessage(null);
          updateSendStatus({
            type: 'error',
            message: `File "${oversized.name}" exceeds 10 MB limit`,
          });
          return;
        }
        const { data: encodedFiles, error: fileError } = await tryCatch(
          async () => Promise.all(files.map(fileToBase64)),
        );
        if (fileError) {
          setOptimisticUserMessage(null);
          updateSendStatus({
            type: 'error',
            message: fileError.message ?? 'Failed to read attached files',
          });
          return;
        }
        pendingFilesRef.current = encodedFiles;
      } else {
        pendingFilesRef.current = undefined;
      }

      if (!conversationIdRef.current) {
        const { error: convError } = await tryCatch(async () => {
          const conv = await createConversation({
            title: content.slice(0, 100),
            pick: modelPickRef.current,
          });
          onConversationCreatedRef.current?.(conv.id);
        });
        if (convError) {
          setOptimisticUserMessage(null);
          updateSendStatus({
            type: 'error',
            message: api.extractServerErrorMessage(
              convError,
              'Failed to start conversation',
            ),
          });
          return;
        }
        if (isSendCancelled({ statusRef: sendStatusRef })) {
          setOptimisticUserMessage(null);
          return;
        }
      }

      const convId = conversationIdRef.current;
      if (!convId) {
        setOptimisticUserMessage(null);
        updateSendStatus({
          type: 'error',
          message: 'No conversation ID',
        });
        return;
      }

      const runId = apId();
      startStream(convId);
      setActiveRunId(runId);
      updateSendStatus({ type: 'idle' });
      chatDebug.info(
        {
          conversation: { id: convId },
          run: { id: runId },
          contentLength: content.length,
          filesCount: pendingFilesRef.current?.length ?? 0,
        },
        'sending chat message',
      );

      const { error: sendError } = await tryCatch(async () =>
        chatApi.sendMessage({
          conversationId: convId,
          content,
          runId,
          files: pendingFilesRef.current,
          ...(options?.messageSource
            ? { messageSource: options.messageSource }
            : {}),
        }),
      );
      if (sendError) {
        chatDebug.error(
          {
            conversation: { id: convId },
            run: { id: runId },
            error: sendError.message,
          },
          'chat message send failed',
        );
        stopStream();
        setOptimisticUserMessage(null);
        if (api.isApError(sendError, ErrorCode.QUOTA_EXCEEDED)) {
          onCreditsExhaustedRef.current?.();
          updateSendStatus({ type: 'idle' });
        } else {
          updateSendStatus({
            type: 'error',
            message: api.extractServerErrorMessage(
              sendError,
              'Failed to send message',
            ),
          });
        }
      }
    },
    [
      createConversation,
      startStream,
      setActiveRunId,
      stopStream,
      updateSendStatus,
      commitInFlightTurn,
      store,
    ],
  );

  const retryLastMessage = useCallback(
    (fallbackContent: string) => {
      const lastSent = lastSentRef.current;
      return isNil(lastSent)
        ? sendMessage(fallbackContent)
        : sendMessage(lastSent.content, lastSent.files);
    },
    [sendMessage],
  );

  const setConversationId = useCallback(
    async (id: string) => {
      if (
        chatUtils.reopensSameConversation({
          current: conversationIdRef.current,
          next: id,
        })
      )
        return;
      stopStream();
      updateSendStatus({ type: 'idle' });
      conversationIdRef.current = id;
      setConversationIdState(id);
      store.getState().resetInteractions();
      store.getState().resetBuilds();

      pendingFilesRef.current = undefined;
      lastSentFileNamesRef.current = [];
      lastSentRef.current = null;
      setOptimisticUserMessage(null);

      setIsLoadingHistory(true);
      const [historyResult, convResult] = await Promise.all([
        tryCatch(async () => chatApi.getMessages(id)),
        tryCatch(async () => chatApi.getConversation(id)),
      ]);
      if (conversationIdRef.current !== id) return;
      if (historyResult.error || convResult.error) {
        conversationIdRef.current = null;
        setConversationIdState(null);
        setIsLoadingHistory(false);
        updateSendStatus({
          type: 'error',
          message: 'Conversation not found',
        });
        return;
      }
      const mapped = chatUtils.mapHistoryToUIMessages(historyResult.data.data);
      const restored = chatUtils.extractQuickRepliesFromHistory(mapped);
      applyQuickRepliesToStore({ setState: store.setState, data: restored });
      restoreReceiptsIntoStore({
        data: historyResult.data.data,
        setState: store.setState,
      });
      const savedPick: ChatModelPick = {
        modelTierId: convResult.data.modelTierId ?? null,
        providerConfigId: convResult.data.providerConfigId ?? null,
        modelName: convResult.data.modelName ?? null,
      };
      modelPickRef.current = savedPick;
      savedPickRef.current = savedPick;
      setModelPickState(savedPick);
      setConversationProjectId(convResult.data.projectId ?? null);
      if (convResult.data.status === AgentConversationStatus.STREAMING) {
        const lastAssistantIdx = mapped.findLastIndex(
          (m) => m.role === 'assistant',
        );
        const lastUserIdx = mapped.findLastIndex((m) => m.role === 'user');
        const isCurrentStreamingResponse =
          lastAssistantIdx >= 0 && lastAssistantIdx > lastUserIdx;
        if (isCurrentStreamingResponse) {
          setPersistedMessages(mapped.slice(0, lastAssistantIdx));
        } else {
          setPersistedMessages(mapped);
        }
        const { data: gate } = await tryCatch(() => chatApi.getPendingGate(id));
        if (conversationIdRef.current !== id) return;
        const baseParts = isCurrentStreamingResponse
          ? mapped[lastAssistantIdx].parts
          : undefined;
        const gatePart = gate ? buildGatePart(gate) : undefined;
        startStream(id, {
          initialParts: gatePart ? [...(baseParts ?? []), gatePart] : baseParts,
        });
        if (gate) {
          store.setState((prev) => ({
            toolCallMeta: {
              ...prev.toolCallMeta,
              ...buildToolCallMetaFromGate(gate),
            },
          }));
        }
      } else {
        setPersistedMessages(mapped);
        if (convResult.data.status === AgentConversationStatus.ERROR) {
          const failureIsInTranscript = mapped.at(-1)?.role === 'assistant';
          updateSendStatus({
            type: 'error',
            message: failureIsInTranscript
              ? null
              : t('The last reply did not finish. Please try again.'),
          });
        }
      }
      setIsLoadingHistory(false);
    },
    [stopStream, startStream, updateSendStatus, store, t],
  );

  const setModelPick = useCallback(async (newPick: ChatModelPick) => {
    modelPickRef.current = newPick;
    setModelPickState(newPick);
    const convId = conversationIdRef.current;
    if (isNil(convId)) {
      return;
    }
    const save = pickSaveQueueRef.current.then(() =>
      tryCatch(() => chatApi.updateConversation(convId, newPick)),
    );
    pickSaveQueueRef.current = save;
    const { error } = await save;
    if (isNil(error)) {
      savedPickRef.current = newPick;
      return;
    }
    const stillLatest =
      modelPickRef.current === newPick && conversationIdRef.current === convId;
    if (stillLatest) {
      modelPickRef.current = savedPickRef.current;
      setModelPickState(savedPickRef.current);
      toast.error(t("Couldn't switch the model. Try again."));
    }
  }, []);

  return {
    conversationId,
    conversationProjectId,
    modelPick,
    messages,
    isStreaming,
    isResumedStream,
    isAwaitingResponse,
    wasCancelled,
    isLoadingHistory,
    error,
    failed,
    sendMessage,
    retryLastMessage,
    cancelStream,
    setConversationId,
    setModelPick,
  };
}