Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

37.7 KB
Raw Blame
import {
  getGetV2GetCopilotUsageQueryKey,
  getGetV2GetSessionQueryKey,
} from "@/app/api/__generated__/endpoints/chat/chat";
import { toast } from "@/components/molecules/Toast/use-toast";
import { useMountEffect } from "@/hooks/useMountEffect";
import { useChat } from "@ai-sdk/react";
import { useQueryClient } from "@tanstack/react-query";
import type { UIMessage } from "ai";
import { useEffect, useMemo, useRef, useState } from "react";
import {
  getOrCreateCopilotChatRuntime,
  markCopilotChatRuntimeHealthy,
  resetCopilotChatRuntime,
  shouldReloadCopilotChatRuntime,
} from "./copilotChatRegistry";
import { handleStreamError } from "./copilotStreamErrorHandlers";
import { useCopilotStreamStore } from "./copilotStreamStore";
import {
  clearKickoffPending,
  getKickoffAttemptTokenFromMetadata,
  getKickoffExpertId,
  getKickoffExpertIdFromMetadata,
  withKickoffLock,
} from "./expertKickoff";
import {
  deduplicateMessages,
  extractSendMessageText,
  extractSendMessageAttachments,
  getSendSuppressionReason,
  hasActiveBackendStream,
  hasInProgressAssistantParts,
  hasVisibleAssistantContent,
  isEngineSwitchPart,
} from "./helpers";
import { asMidTurnFallbackRow } from "./components/ChatMessagesContainer/midTurnSplit";
import { extractDbSequence } from "./helpers/convertChatSessionToUiMessages";
import { getLatestAssistantStatusMessage } from "./messageParts";
import {
  latestProviderFailure,
  parseProviderFailurePart,
  providerFailureFingerprint,
  type ProviderFailure,
} from "./providerFailure";
import { useCopilotUIStore } from "./store";
import type { CopilotLlmModel } from "./store";
import { useCopilotReconnect } from "./useCopilotReconnect";
import { sdkStopStream, useCopilotStop } from "./useCopilotStop";
import { useHydrateOnStreamEnd } from "./useHydrateOnStreamEnd";
import { RESTORE_STALL_TIMEOUT_MS } from "./restoreConstants";
import { useStreamActivityWatchdog } from "./useStreamActivityWatchdog";
import { useFollowBackendTurn } from "./useFollowBackendTurn";
import { useWakeResync } from "./useWakeResync";

/**
 * Delay after a clean stream close before refetching the session to check
 * whether the backend executor is still running. Without this, the refetch
 * races with the backend clearing `active_stream` and often reads a stale
 * `active_stream=true`, triggering unnecessary reconnect cycles.
 */
const FINISH_REFETCH_SETTLE_MS = 500;
// Server-initiated continuation turns (e.g. the engine switch after
// enter_agent_building_mode) are dispatched via RabbitMQ right after the
// previous turn completes — one 500ms check can outrun the dispatch, so the
// post-finish active-stream probe retries before giving up. Ordinary turns
// keep a single probe; the extended window only runs when this turn emitted
// a data-mode-changed part (a continuation is actually pending), and it
// brackets the backend's dispatch retry ceiling (3 attempts, ~3s backoff).
const FINISH_REFETCH_ATTEMPTS_DEFAULT = 1;
const FINISH_REFETCH_ATTEMPTS_PENDING_SWITCH = 8;

/**
 * Batch AI SDK message updates into ~30 ms paints. The smoothing transform in
 * the transport emits word-sized deltas ~10 ms apart; without throttling each
 * word would re-render the whole chat tree.
 */
const STREAM_RENDER_THROTTLE_MS = 30;

interface UseCopilotStreamArgs {
  userId?: string | null;
  sessionId: string | null;
  hydratedMessages: UIMessage[] | undefined;
  /**
   * The session's messages as the API sent them.
   *
   * Conversion to UIMessages merges rows and drops their metadata, so the
   * persisted failure envelope does not survive it. This is the same data
   * before that happens.
   */
  rawSessionMessages?: unknown[];
  /** The route currently persisted for this session. Historical provider
   * failures from a route the chat already left are resolved, not live. */
  sessionAuthProvider?: string | null;
  sessionCredentialId?: string | null;
  /** Id of the first hydrated message of the turn the backend is still
   *  running — the point the GET-resume replay starts from. */
  activeTurnStartMessageId?: string | null;
  /** ``active_stream.started_at`` of that turn. Known with no start message
   *  above, it means the turn has persisted nothing yet. */
  activeTurnStartedAt?: string | null;
  hasActiveStream: boolean;
  refetchSession: () => Promise<{ data?: unknown }>;
  /** Model tier override. `undefined` = let backend decide. */
  copilotModel: CopilotLlmModel | undefined;
}

export function useCopilotStream({
  userId = null,
  sessionId,
  hydratedMessages,
  rawSessionMessages,
  sessionAuthProvider = null,
  sessionCredentialId = null,
  activeTurnStartMessageId = null,
  activeTurnStartedAt = null,
  hasActiveStream,
  refetchSession,
  copilotModel,
}: UseCopilotStreamArgs) {
  const queryClient = useQueryClient();
  const setInitialPrompt = useCopilotUIStore((s) => s.setInitialPrompt);
  const [rateLimitMessage, setRateLimitMessage] = useState<string | null>(null);
  // The envelope behind our own cap, when the backend sent one. It rides
  // along to the plan dialog so that dialog can also offer a linked
  // subscription to continue on: the cap does not apply to a turn billed to
  // the user's own credential, so a connected ChatGPT account is a way out
  // that costs them nothing more.
  const [platformLimitFailure, setPlatformLimitFailure] =
    useState<ProviderFailure | null>(null);
  // A linked subscription that stopped accepting turns, as opposed to our own
  // credits running out. Held separately because the answer is different.
  const [providerLimit, setProviderLimit] = useState<ProviderFailure | null>(
    null,
  );
  const dismissedProviderFailureRef = useRef<{
    sessionId: string;
    fingerprint: string;
  } | null>(null);
  function dismissRateLimit() {
    setRateLimitMessage(null);
    setPlatformLimitFailure(null);
  }
  const chatRuntime = useMemo(() => {
    if (!sessionId) return null;
    if (shouldReloadCopilotChatRuntime(sessionId)) {
      resetCopilotChatRuntime(sessionId);
    }
    return getOrCreateCopilotChatRuntime(sessionId);
  }, [sessionId]);
  if (chatRuntime) {
    chatRuntime.copilotModelRef.current = copilotModel;
  }

  // Transient per-mount flags. The parent keys this subtree by sessionId,
  // so every session-switch remounts and these refs reset naturally —
  // no cross-session bleed, no blanket "clearCoord" on the Zustand store.
  const hasResumedRef = useRef(false);
  const hydrateCompletedRef = useRef(false);
  const pendingResumeRef = useRef<(() => void) | null>(null);
  // Synchronous flag read inside SDK callbacks — kept as a ref so callbacks
  // don't have to trigger re-renders to observe changes. Scoped to this
  // mount (= this session): the parent remounts on session switch, so a
  // plain boolean can't bleed state across sessions.
  const isUserStoppingRef = useRef(false);
  const pendingEngineSwitchRef = useRef(false);
  // Cleared once consumed, so a later failure without an envelope cannot
  // inherit the explanation of an earlier one.
  const providerFailureRef = useRef<ProviderFailure | null>(null);
  // State mirror of ``isUserStoppingRef`` — the ref is read synchronously
  // inside SDK callbacks, the state drives UI so a click on the stop button
  // immediately overrides ``isStreaming`` regardless of whether AI SDK has
  // flipped ``status`` back to ``ready`` yet (which can lag by many seconds
  // when aborting a GET-based resume fetch).
  const [isUserStopping, setIsUserStopping] = useState(false);
  // True while `handleFinish`'s post-turn active-stream probe is still
  // deciding whether a continuation turn is starting. Gates the force-hydrate
  // in `useHydrateOnStreamEnd` so it can't swap message ids (and flash the
  // whole list) in the window before the reconnect is scheduled.
  const [isFinishProbing, setIsFinishProbing] = useState(false);
  // Flipped to `false` during mount cleanup so async callbacks that were
  // already in flight (e.g. the post-stream settle in `onFinish`) bail out
  // instead of arming new timers / HTTP requests against a torn-down mount.
  const isMountedRef = useRef(true);

  // Stable refs for resumeStream + handleReconnect, filled after the
  // corresponding hooks run below. `useChat`'s onFinish/onError closures
  // capture these refs at init and read `.current` at fire time, so the
  // circular "useChat needs handleReconnect and useCopilotReconnect needs
  // resumeStream" is resolved by deferring both through refs.
  const resumeStreamRef = useRef<() => void>(() => {});
  const handleReconnectRef = useRef<() => void>(() => {});

  const {
    messages: rawMessages,
    sendMessage: sdkSendMessage,
    stop: sdkStop,
    status,
    error,
    setMessages,
    resumeStream,
  } = useChat(
    chatRuntime
      ? {
          chat: chatRuntime.chat,
          experimental_throttle: STREAM_RENDER_THROTTLE_MS,
        }
      : {
          id: "new",
        },
  );

  useEffect(() => {
    if (!chatRuntime) return;

    async function handleFinish({
      isDisconnect,
      isAbort,
    }: {
      isDisconnect?: boolean;
      isAbort?: boolean;
    }) {
      if (isAbort || !sessionId) return;
      if (isUserStoppingRef.current) return;

      if (isDisconnect) {
        handleReconnectRef.current();
        return;
      }

      const attempts = pendingEngineSwitchRef.current
        ? FINISH_REFETCH_ATTEMPTS_PENDING_SWITCH
        : FINISH_REFETCH_ATTEMPTS_DEFAULT;
      pendingEngineSwitchRef.current = false;
      providerFailureRef.current = null;
      setIsFinishProbing(true);
      try {
        for (let attempt = 0; attempt < attempts; attempt++) {
          await new Promise((r) => setTimeout(r, FINISH_REFETCH_SETTLE_MS));
          if (!isMountedRef.current) return;
          const result = await refetchSession();
          if (!isMountedRef.current) return;
          if (hasActiveBackendStream(result)) {
            handleReconnectRef.current();
            return;
          }
        }
      } finally {
        if (isMountedRef.current) setIsFinishProbing(false);
      }
    }

    function handleError(error: Error) {
      if (!sessionId) return;
      const coord = useCopilotStreamStore.getState().getCoord(sessionId);
      const kickoffExpertId = coord.lastSubmittedKickoffExpertId;
      const kickoffAttemptToken = coord.lastSubmittedKickoffAttemptToken;
      function releaseKickoffPending() {
        if (!userId || !kickoffExpertId || !kickoffAttemptToken) return;
        void withKickoffLock(userId, kickoffExpertId, async () => {
          clearKickoffPending(userId, kickoffExpertId, kickoffAttemptToken);
        }).catch(() => undefined);
      }
      // Backend raises 429 and 402 BEFORE persisting the user message, so the
      // optimistic user bubble added by useChat is a lie. Restore the text
      // into the composer (via the same store slot URL pre-fills use) and
      // drop the unsent bubble so the user can edit/resend.
      const restoreUnsentSend = () => {
        const coord = useCopilotStreamStore.getState().getCoord(sessionId);
        const unsentText = coord.lastSubmittedMessageText;
        if (unsentText) {
          // The expert-kickoff control prompt must never surface in the
          // user's composer — drop the recovery slot instead of restoring
          // it. Its bubble below is dropped too; the once-per-expert
          // pending latch expires so a later visit can retry the kickoff.
          if (kickoffExpertId) {
            useCopilotStreamStore.getState().updateCoord(sessionId, {
              lastSubmittedMessageText: null,
              lastSubmittedKickoffExpertId: null,
              lastSubmittedKickoffAttemptToken: null,
            });
          } else {
            // The refusal lands async — by the time it does, the user
            // may have started typing a new draft. Only restore + clear the
            // recovery slot when the composer is empty; otherwise leave the
            // unsent text in the per-session store so a reload / resume can
            // surface it later instead of silently dropping it.
            const composer = document.getElementById(
              "chat-input",
            ) as HTMLTextAreaElement | null;
            const composerEmpty = !composer || composer.value.length === 0;
            if (composerEmpty) {
              setInitialPrompt(unsentText);
              useCopilotStreamStore.getState().updateCoord(sessionId, {
                lastSubmittedMessageText: null,
                lastSubmittedKickoffExpertId: null,
                lastSubmittedKickoffAttemptToken: null,
              });
            }
          }
          setMessages((prev) => {
            const last = prev[prev.length - 1];
            const next = last?.role === "user" ? prev.slice(0, -1) : prev;
            useCopilotStreamStore
              .getState()
              .setMessageSnapshot(sessionId, next);
            return next;
          });
        }
      };
      const failureForThisTurn = providerFailureRef.current;
      providerFailureRef.current = null;
      // Resuming keeps the send in flight, and a refused send's text is kept
      // by `restoreUnsentSend` when the composer is busy.
      let keepSendMemory = false;
      handleStreamError({
        error,
        providerFailure: failureForThisTurn,
        onRateLimit: (message, limitFailure, origin) => {
          keepSendMemory = true;
          restoreUnsentSend();
          // A provider's own limit is not answered by upgrading with us, so
          // it opens the continue path instead of the plan dialog.
          //
          // Which limit it is turns on where the turn was refused, not on
          // which connection it ran on. Our own budget is refused at
          // admission, before the stream opens; a provider refuses mid-turn,
          // on the stream. Both carry an envelope now, so the envelope alone
          // no longer says which. Reading the connection instead meant a
          // self-host -- where the route is "platform" because the deployment
          // holds the key -- was told "Daily usage limit reached, upgrade
          // your plan" when its own OpenRouter or local gateway had
          // rate-limited it. That is a claim about an account we do not bill,
          // offering a plan that would not help.
          if (limitFailure && origin === "provider") {
            // A later turn can fail in exactly the same way as an earlier one
            // the user dismissed. Live stream evidence is a new occurrence.
            dismissedProviderFailureRef.current = null;
            setProviderLimit(limitFailure);
          } else {
            // Our own cap. The envelope, when there is one, lets the plan
            // dialog offer a linked subscription to continue on beside the
            // upgrade it always offered. Older backends send a bare string
            // here and get the dialog exactly as it was.
            setPlatformLimitFailure(limitFailure ?? null);
            setRateLimitMessage(limitFailure?.message || message);
          }
        },
        onReconnect: () => {
          keepSendMemory = true;
          handleReconnectRef.current();
        },
        onPaywall: () => {
          keepSendMemory = true;
          restoreUnsentSend();
        },
        isUserStoppingRef,
      });
      // A turn that failed before answering can leave its echo as the newest
      // row, which after a reload would make the guard drop the user's resend.
      if (!keepSendMemory) {
        useCopilotStreamStore.getState().updateCoord(sessionId, {
          lastSubmittedMessageText: null,
        });
      }
      if (kickoffExpertId) {
        releaseKickoffPending();
        useCopilotStreamStore.getState().updateCoord(sessionId, {
          lastSubmittedMessageText: null,
          lastSubmittedKickoffExpertId: null,
          lastSubmittedKickoffAttemptToken: null,
        });
        setMessages((prev) => {
          const last = prev[prev.length - 1];
          const next = last?.role === "user" ? prev.slice(0, -1) : prev;
          useCopilotStreamStore.getState().setMessageSnapshot(sessionId, next);
          return next;
        });
      }
    }

    function handleData(dataPart: { type: string; data?: unknown }) {
      // The execution engine is an internal detail with no control and no
      // display — but a switch still takes longer to settle, so the signal
      // is kept to widen the post-finish refetch window below.
      if (isEngineSwitchPart(dataPart)) {
        pendingEngineSwitchRef.current = true;
      }
      // The envelope always precedes the error frame it explains, so
      // stashing it here means handleError has it in hand.
      const failure = parseProviderFailurePart(dataPart);
      if (failure) {
        providerFailureRef.current = failure;
      }
    }

    chatRuntime.onFinish = handleFinish;
    chatRuntime.onError = handleError;
    chatRuntime.onData = handleData;

    return () => {
      if (chatRuntime.onFinish === handleFinish) {
        chatRuntime.onFinish = undefined;
      }
      if (chatRuntime.onData === handleData) {
        chatRuntime.onData = undefined;
      }
      if (chatRuntime.onError === handleError) {
        chatRuntime.onError = undefined;
      }
    };
  }, [
    chatRuntime,
    sessionId,
    refetchSession,
    setInitialPrompt,
    setMessages,
    userId,
  ]);

  // Flipped to ``true`` the first time the user actually hits Send on this
  // mount. Lets the ``hasConnectedThisMountRef`` latch below distinguish
  // "resuming a turn that was already running" from "user sent a brand new
  // turn" — in the latter case the ThinkingIndicator is the right surface
  // from the first render, no "Retrieving latest messages" spinner needed.
  const hasSentThisMountRef = useRef(false);

  // Latch flips from ``false`` → ``true`` the first time the stream is
  // considered "live" on this mount. Observed by ``isRestoringActiveSession``
  // so the "Retrieving latest messages" spinner only shows while we haven't
  // yet connected.
  //
  // Flip conditions (either is sufficient):
  //  1. The user sent a fresh message this mount — we own the turn, so no
  //     restore UI is appropriate even though status is briefly "submitted"
  //     before the first byte lands.
  //  2. The stream is in an active state AND has produced at least one
  //     visible assistant content part (text / reasoning with non-empty
  //     text, any tool part, or a backend status). The ``isStreamLive``
  //     gate is what distinguishes "bytes from the live SSE" from "content
  //     just hydrated from the DB on a fresh mount" — without it, a
  //     mid-stream refresh that lands a partial assistant message in
  //     ``hydratedMessages`` would flip the latch before the GET-resume
  //     produced anything, suppressing the restore spinner and disabling
  //     the restore-stall watchdog. Checking content (not just status)
  //     still keeps the indicator up during the GET-resume-no-bytes window.
  const hasConnectedThisMountRef = useRef(false);
  if (!hasConnectedThisMountRef.current) {
    const isStreamLive = status === "streaming" || status === "submitted";
    if (
      hasSentThisMountRef.current ||
      (isStreamLive &&
        (hasVisibleAssistantContent(rawMessages) ||
          getLatestAssistantStatusMessage(rawMessages) !== null))
    ) {
      hasConnectedThisMountRef.current = true;
    }
  }

  function resumeStreamFromStart() {
    if (!chatRuntime) return;
    if (sessionId) {
      markCopilotChatRuntimeHealthy(sessionId);
    }
    setMessages((prev) => {
      // The GET-resume replays the active turn from its start as a fresh
      // assistant message, so any HYDRATED partial of that turn must be
      // dropped first — keeping it splits one turn into two bubbles with
      // two tool chains. Trimming only in-progress tails is not enough: a
      // turn parked between tools (e.g. waiting on a handoff) hydrates
      // with every persisted part already complete. Only db-hydrated
      // messages (``-seq-N`` ids) are dropped — a streamed tail belongs
      // to a finished turn this mount ran (continuation reconnect) and
      // the resume will NOT replay it.
      // The trim starts at the running turn's first hydrated message, not
      // at the last user message: a turn the backend started on its own
      // (engine-switch continuation) has no user row in front of it, so a
      // user-anchored cut would also delete the completed answer above it
      // — content the resume never replays. The turn's own opening prompt
      // is kept (the replay does not re-emit it); every assistant row after
      // it goes, and the cut does not stop at a user row the backend drained
      // into the middle of the turn — leaving the pre-drain chain above it
      // would show that chain twice. The drained row itself is kept, as a
      // fallback bubble above the replayed assistant: the pending buffer it
      // came from is empty, and a replay whose hint carries no text (older
      // backend) cannot redraw it. When the hint does carry the text, the
      // transcript draws the bubble at the drain point and drops the
      // matching fallback row (`splitMessagesAtDrainHints`).
      const last = prev[prev.length - 1];
      // When the running turn's start is known and no hydrated row falls at
      // or after it, nothing of that turn is persisted yet — a turn started
      // by Keep going or a resume at the reset saves its note row before the
      // turn opens. Every hydrated row then belongs to earlier turns and the
      // replay only appends, so none is cut; only a partial this mount
      // streamed itself goes, because the replay redraws it.
      if (activeTurnStartedAt !== null && activeTurnStartMessageId === null) {
        return hasInProgressAssistantParts(last) &&
          extractDbSequence(last) === null
          ? prev.slice(0, -1)
          : prev;
      }
      const lastUserIndex = prev.findLastIndex((m) => m.role === "user");
      const userCut = lastUserIndex === -1 ? -1 : lastUserIndex + 1;
      const activeTurnIndex = activeTurnStartMessageId
        ? prev.findIndex((m) => m.id === activeTurnStartMessageId)
        : -1;
      const cutIndex =
        activeTurnIndex === -1
          ? userCut
          : activeTurnIndex + (prev[activeTurnIndex].role === "user" ? 1 : 0);
      const tail = cutIndex === -1 ? [] : prev.slice(cutIndex);
      if (tail.length > 0 && tail.every((m) => extractDbSequence(m) !== null)) {
        const drainedFollowUps = tail
          .filter((m) => m.role === "user")
          .map(asMidTurnFallbackRow);
        return [...prev.slice(0, cutIndex), ...drainedFollowUps];
      }
      return hasInProgressAssistantParts(last) ? prev.slice(0, -1) : prev;
    });
    resumeStream();
  }
  resumeStreamRef.current = resumeStreamFromStart;
  const sessionIdRef = useRef(sessionId);
  sessionIdRef.current = sessionId;

  const {
    isReconnectScheduled,
    reconnectExhausted,
    reconnectScheduledRef,
    handleReconnect,
  } = useCopilotReconnect({
    sessionId,
    hasActiveStream,
    status,
    hasConnectedThisMountRef,
    resumeStreamRef,
    hasResumedRef,
  });
  handleReconnectRef.current = handleReconnect;

  // Wrap sdkSendMessage to guard against re-sending the user message during a
  // reconnect cycle. If the session already has the message (i.e. we are in a
  // reconnect/resume flow), only GET-resume is safe — never re-POST.
  async function sendMessage(
    ...args: Parameters<typeof sdkSendMessage>
  ): ReturnType<typeof sdkSendMessage> {
    const text = extractSendMessageText(args[0]);
    const metadata =
      args[0] && typeof args[0] === "object" && "metadata" in args[0]
        ? args[0].metadata
        : undefined;
    const kickoffExpertId = getKickoffExpertIdFromMetadata(metadata);
    const kickoffAttemptToken = getKickoffAttemptTokenFromMetadata(metadata);
    const sid = sessionId;
    const coord = sid ? useCopilotStreamStore.getState().getCoord(sid) : null;

    const suppressReason = getSendSuppressionReason({
      text,
      attachments: extractSendMessageAttachments(args[0]),
      isReconnectScheduled: reconnectScheduledRef.current,
      lastSubmittedText: coord?.lastSubmittedMessageText ?? null,
      messages: chatRuntime?.chat.messages ?? rawMessages,
      status: chatRuntime?.chat.status ?? status,
    });

    if (suppressReason === "reconnecting") {
      // The ref flips to ``true`` synchronously while the React state that
      // drives the UI's disabled state only updates on the next render, so
      // the user may have clicked send against a still-enabled input. Tell
      // them their message wasn't dropped silently.
      toast({
        title: "Reconnecting",
        description: "Wait for the connection to resume before sending.",
      });
      return;
    }
    if (suppressReason === "duplicate") return;

    if (sid) {
      markCopilotChatRuntimeHealthy(sid);
      useCopilotStreamStore.getState().updateCoord(sid, {
        lastSubmittedMessageText: text,
        lastSubmittedKickoffExpertId: kickoffExpertId,
        lastSubmittedKickoffAttemptToken: kickoffAttemptToken,
      });
    }
    hasSentThisMountRef.current = true;
    if (isUserStoppingRef.current) {
      isUserStoppingRef.current = false;
    }
    if (isUserStopping) {
      setIsUserStopping(false);
    }
    return sdkSendMessage(...args);
  }

  // Deduplicate messages continuously to prevent duplicates when resuming streams.
  // Memoised so `messages` keeps its identity across renders that did not
  // change the chat, instead of being a new array every render.
  const messages = useMemo(
    () => deduplicateMessages(rawMessages),
    [rawMessages],
  );

  useEffect(() => {
    if (!sessionId) return;
    if (messages.length === 0) return;
    useCopilotStreamStore.getState().setMessageSnapshot(sessionId, messages);
  }, [sessionId, messages]);

  // A failure the chat is still sitting on survives a reload, because the
  // backend persisted the envelope onto the marker row for exactly this. It
  // was only ever read from the live stream before, so refreshing, opening the
  // chat in another tab, or closing the laptop took away the one control that
  // offered a way out -- leaving the chat latched to the connection that had
  // just refused it, with no way to say "continue on the other one".
  useEffect(() => {
    setProviderLimit(null);
    dismissedProviderFailureRef.current = null;
  }, [sessionId]);

  useEffect(() => {
    if (!sessionId || !rawSessionMessages?.length) return;
    const latest = latestProviderFailure(
      rawSessionMessages,
      sessionAuthProvider
        ? {
            authProvider: sessionAuthProvider,
            credentialId: sessionCredentialId,
          }
        : null,
    );
    // The dialog answers a spent quota, as on the live path. Reopening it for
    // an expired login or a refused prompt would tell the user they hit a
    // limit they never hit.
    const historical = latest?.kind === "usage_limit" ? latest : null;
    const dismissed = dismissedProviderFailureRef.current;
    if (
      historical &&
      dismissed?.sessionId === sessionId &&
      dismissed.fingerprint === providerFailureFingerprint(historical)
    ) {
      return;
    }
    // A live failure is the fresher truth; never let history overwrite it.
    setProviderLimit((current) => current ?? historical);
  }, [rawSessionMessages, sessionAuthProvider, sessionCredentialId, sessionId]);

  useEffect(() => {
    if (!sessionId || !hydratedMessages) return;
    const coord = useCopilotStreamStore.getState().getCoord(sessionId);
    const kickoffExpertId = coord.lastSubmittedKickoffExpertId;
    if (!kickoffExpertId) return;
    if (
      !hydratedMessages.some(
        (message) => getKickoffExpertId(message) === kickoffExpertId,
      )
    ) {
      return;
    }
    useCopilotStreamStore.getState().updateCoord(sessionId, {
      lastSubmittedMessageText: null,
      lastSubmittedKickoffExpertId: null,
      lastSubmittedKickoffAttemptToken: null,
    });
  }, [hydratedMessages, sessionId]);

  // Cheap signal that changes on any stream activity — drives the stall
  // watchdog. Counts messages, the last message's parts, and the total
  // text length on the last message so in-place part updates (token
  // streaming) also tick the signal.
  const streamActivityToken = useMemo(() => {
    const last = rawMessages[rawMessages.length - 1];
    let textLen = 0;
    if (last) {
      for (const part of last.parts) {
        if ("text" in part && typeof part.text === "string") {
          textLen += part.text.length;
        }
      }
    }
    return `${rawMessages.length}:${last?.parts.length ?? 0}:${textLen}`;
  }, [rawMessages]);

  const stopSdkStream = sdkStopStream(sdkStop, setMessages);
  const stop = useCopilotStop({
    sessionId,
    stopStream: () => {
      // A turn stopped before it streams stores no marker, so after a reload
      // its echo is the newest row; the guard must not treat a resend as a double-click.
      if (sessionId) {
        useCopilotStreamStore.getState().updateCoord(sessionId, {
          lastSubmittedMessageText: null,
        });
      }
      stopSdkStream();
    },
    isUserStoppingRef,
    setIsUserStopping,
  });

  // Silent-stall watchdog: triggers the reconnect cascade if the stream
  // sits in "submitted" / "streaming" with no activity for 60 s. Handles
  // the case where AI SDK's onFinish / onError never fire (backend hung,
  // Redis zombie, etc.) and the UI would otherwise stay stuck forever.
  useStreamActivityWatchdog({
    sessionId,
    status,
    activityToken: streamActivityToken,
    isReconnectScheduled,
    isUserStoppingRef,
    handleReconnectRef,
  });

  // ---------------------------------------------------------------------------
  // Mount lifecycle:
  //  - On unmount: mark this React subscriber as gone so async follow-up work
  //    cannot set state into a torn-down mount.
  //  - Do NOT abort the underlying session Chat runtime here. It is
  //    intentionally kept alive in JS state so switching away from a chat does
  //    not tear down its live SSE stream.
  // ---------------------------------------------------------------------------
  useMountEffect(() => {
    // Strict Mode runs mount → cleanup → mount in development. Without this
    // reset the simulated unmount left the flag false for the whole life of
    // the real mount, so `handleFinish` never cleared `isFinishProbing` and
    // every consumer gated on it (post-finish hydration, a held follow-up)
    // stayed stuck after the first turn.
    isMountedRef.current = true;
    return () => {
      isMountedRef.current = false;
    };
  });

  const { followBackendTurn } = useFollowBackendTurn({
    status,
    refetchSession,
    hasResumedRef,
  });

  // Wake detection: refetch + optional resume when the page becomes visible
  // after being hidden for >30 s. See `useWakeResync` for details.
  const { isSyncing } = useWakeResync({
    sessionIdRef,
    isMountedRef,
    refetchSession,
    resumeStreamRef,
  });

  // After-stream hydration — force-replace AI-SDK state with the DB's view
  // once React Query has actually refetched, then keep length-gated top-ups
  // working for pagination. Also repairs zombie in-progress parts when the
  // backend confirms no active stream. See useHydrateOnStreamEnd for the
  // timing dance.
  useHydrateOnStreamEnd({
    sessionId,
    status,
    hydratedMessages,
    isReconnectScheduled,
    hasActiveStream,
    isFinishProbing,
    setMessages,
  });

  // Mark hydration complete in the transient ref whenever the hydration gate
  // has effectively run (hydrated data is present and we're not mid-stream),
  // and flush any `pendingResume` that was deferred while hydration was
  // still pending.
  useEffect(() => {
    if (!sessionId) return;
    if (!hydratedMessages) return;
    if (status === "streaming" || status === "submitted") return;
    if (isReconnectScheduled) return;

    hydrateCompletedRef.current = true;
    const pending = pendingResumeRef.current;
    if (pending) {
      pendingResumeRef.current = null;
      pending();
    }
  }, [sessionId, hydratedMessages, status, isReconnectScheduled]);

  // Invalidate session + usage caches when the stream completes.
  // Reconnect counter/timer reset on the same transition is owned by
  // `useCopilotReconnect`, which watches `status` internally.
  // `lastSubmittedMessageText` is intentionally NOT cleared here: a resume
  // may still re-POST it, and `getSendSuppressionReason` only treats a
  // resend as a duplicate while its echo is the newest message or the turn
  // is in flight, so keeping it cannot swallow a later message.
  const prevStatusRef = useRef(status);
  useEffect(() => {
    const prev = prevStatusRef.current;
    prevStatusRef.current = status;

    const wasActive = prev === "streaming" || prev === "submitted";
    const isIdle = status === "ready" || status === "error";

    if (wasActive && isIdle && sessionId && !isReconnectScheduled) {
      queryClient.invalidateQueries({
        queryKey: getGetV2GetSessionQueryKey(sessionId),
      });
      queryClient.invalidateQueries({
        queryKey: getGetV2GetCopilotUsageQueryKey(),
      });
    }
  }, [status, sessionId, queryClient, isReconnectScheduled]);

  // Resume an active stream AFTER hydration completes.
  // Only runs when this mount opens on a session with an already-active
  // backend stream (page reload OR session-switch-back). Does NOT run when
  // the user sends a new message mid-session (that goes through POST).
  // Gated on the transient `hydrateCompletedRef` to prevent racing the
  // hydration effect.
  useEffect(() => {
    if (!sessionId) return;
    if (!hasActiveStream) return;
    if (!hydratedMessages) return;

    // Never resume if currently streaming.
    if (status === "streaming" || status === "submitted") return;

    // Only resume once per mount.
    if (hasResumedRef.current) return;

    // Don't resume a stream the user just cancelled.
    if (isUserStoppingRef.current) return;

    function doResume() {
      if (!sessionId) return;
      if (hasResumedRef.current) return;
      if (isUserStoppingRef.current) return;
      hasResumedRef.current = true;
      resumeStreamRef.current();
    }

    // Wait for hydration to complete before resuming to prevent the two
    // effects from racing (duplicate messages / missing content).
    if (!hydrateCompletedRef.current) {
      pendingResumeRef.current = doResume;
      return;
    }

    doResume();
  }, [sessionId, hasActiveStream, hydratedMessages, status]);

  // Clear messages when session is null
  useEffect(() => {
    if (!sessionId) setMessages([]);
  }, [sessionId, setMessages]);

  // Restore watchdog: if we reopened a session with an active backend stream
  // but still have not connected after 6 s of zero replay activity, verify
  // the backend still reports that stream as active and then kick the
  // reconnect cascade. This covers both "status stayed ready / no replay
  // chunks ever appeared" and "resume fetch is alive but only heartbeats are
  // flowing" — the latter never trips the normal stream-activity watchdog
  // because heartbeats do not mutate `messages`.
  useEffect(() => {
    if (!sessionId) return;
    if (!hasActiveStream) return;
    if (hasConnectedThisMountRef.current) return;
    if (isReconnectScheduled || reconnectExhausted) return;
    if (isUserStoppingRef.current) return;

    let cancelled = false;
    const timeout = setTimeout(async () => {
      if (cancelled) return;
      if (!isMountedRef.current) return;
      if (sessionIdRef.current !== sessionId) return;
      if (hasConnectedThisMountRef.current) return;
      if (isUserStoppingRef.current) return;

      const result = await refetchSession();
      if (!isMountedRef.current) return;
      if (sessionIdRef.current !== sessionId) return;
      if (hasConnectedThisMountRef.current) return;
      if (isUserStoppingRef.current) return;
      if (!hasActiveBackendStream(result)) return;

      handleReconnectRef.current();
    }, RESTORE_STALL_TIMEOUT_MS);

    return () => {
      cancelled = true;
      clearTimeout(timeout);
    };
  }, [
    sessionId,
    hasActiveStream,
    streamActivityToken,
    isReconnectScheduled,
    reconnectExhausted,
    refetchSession,
  ]);

  // Reset the user-stop flag once the backend confirms the stream is no
  // longer active — this prevents the flag from staying stale forever.
  useEffect(() => {
    if (hasActiveStream) return;
    if (isUserStoppingRef.current) {
      isUserStoppingRef.current = false;
    }
    if (isUserStopping) {
      setIsUserStopping(false);
    }
  }, [hasActiveStream, isUserStopping]);

  // True while reconnecting or backend has active stream but we haven't
  // connected yet on this mount.  Once we've seen visible content this mount,
  // a lingering ``hasActiveStream=true`` from a slow session refetch (e.g.
  // backend still clearing metadata after the SSE finish) must NOT lock the
  // input — legitimate reconnect cases set ``isReconnectScheduled`` via
  // ``handleFinish`` / the watchdogs.
  const isReconnecting =
    !isUserStoppingRef.current &&
    !reconnectExhausted &&
    (isReconnectScheduled ||
      (hasActiveStream &&
        !hasConnectedThisMountRef.current &&
        status !== "streaming" &&
        status !== "submitted"));

  const isRestoringActiveSession =
    !isUserStoppingRef.current &&
    !reconnectExhausted &&
    hasActiveStream &&
    !hasConnectedThisMountRef.current;

  return {
    followBackendTurn,
    messages,
    setMessages,
    sendMessage,
    stop,
    status,
    error: isReconnecting || isUserStoppingRef.current ? undefined : error,
    isReconnecting,
    isFinishProbing,
    isRestoringActiveSession,
    isSyncing,
    isUserStoppingRef,
    isUserStopping,
    rateLimitMessage,
    platformLimitFailure,
    providerLimit,
    dismissProviderLimit: () => {
      if (sessionId && providerLimit) {
        dismissedProviderFailureRef.current = {
          sessionId,
          fingerprint: providerFailureFingerprint(providerLimit),
        };
      }
      setProviderLimit(null);
    },
    dismissRateLimit,
  };
}