Skip to content

Your lightweight open-source personal agent.

44.0 KB
Raw Blame
import { acceptsCompactionPhase } from "../../../packages/client-events/notifications";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useThreadVisibility } from "@/hooks/useThreadVisibility";

import { useClient } from "@/providers/ClientProvider";
import { hasPendingAgentActivity } from "@/lib/activity-timeline";
import { ApiError, fetchWebuiThread, fetchWebuiThreadTraceDetail } from "@/lib/api";
import { fetchLatestWebuiThread } from "@/lib/latest-thread-request";
import { persistedCanonicalRunState } from "@/lib/canonical-run-snapshot";
import { webuiThreadCache } from "@/lib/webui-thread-cache";
import { ThreadTranscript, type ThreadPaging, type ThreadRead, type ThreadTranscriptSnapshot } from "@/lib/thread-transcript";
import type { ThreadMessageCache } from "@/lib/thread-message-cache";
import type { StreamError } from "@/lib/nanobot-client";
import {
  clearThreadProjectionActivity,
  closeThreadProjectionAnswer,
  finalizeStreamedTurn,
  resetThreadProjectionCursor,
  turnFieldsFromEvent,
} from "@/lib/thread-event-projection";
import type {
  ThreadProjectionEvent,
  UIMessageTurnFields,
} from "@/lib/thread-event-projection";
import { formatQuotedUserMessage } from "@/lib/user-message-quote";
import { playTurnCompleteSound } from "@/lib/notification-sound";
import type {
  InboundEvent,
  OutboundCliAppMention,
  OutboundMcpPresetMention,
  OutboundMedia,
  SessionMention,
  GoalStateWsPayload,
  MessageDeliveryStatus,
  RecoveryState,
  RetryStatus,
  UIMediaAttachment,
  UIMessage,
  UIModelRequestSnapshot,
  WorkspaceScopePayload,
} from "@/lib/types";

type PendingStreamEvent =
  | { kind: "delta"; text: string; turn: UIMessageTurnFields; streamId?: string; source?: UIMessage["source"]; responseSources?: UIMessage["responseSources"] }
  | { kind: "reasoning"; text: string; turn: UIMessageTurnFields; streamId?: string };

const BACKGROUND_STREAM_FLUSH_INTERVAL_MS = 1_000;
// Markdown and layout work must leave room for input between visible updates.
const VISIBLE_STREAM_FLUSH_INTERVAL_MS = 50;
const EMPTY_INITIAL_MESSAGES: UIMessage[] = [];
const EMPTY_COMPLETED_TURN_IDS: readonly string[] = [];

/** Payload passed to ``send`` when the user attaches one or more files.
 *
 * ``media`` is handed to the wire client verbatim; ``preview`` powers the
 * optimistic user bubble. Keeping the two separate lets the bubble re-use the
 * local data URL even after the server persists the file under a different
 * name. */
export interface SendAttachment {
  media: OutboundMedia;
  preview: UIMediaAttachment;
}

export interface SendOptions {
  intent?: "create_automation";
  cliApps?: OutboundCliAppMention[];
  mcpPresets?: OutboundMcpPresetMention[];
  sessionMentions?: SessionMention[];
  quotedContext?: string;
  workspaceScope?: WorkspaceScopePayload | null;
  sideChannel?: boolean;
  userShell?: boolean;
  finalizeActiveTurn?: boolean;
  /** Append guidance to the running turn without detaching its active answer segment. */
  continueActiveTurn?: boolean;
}

export interface SubmittedTurn {
  delivery?: Promise<void>;
  turnId: string;
  userMessageId: string;
  sideChannel: boolean;
}

function eventTurnId(ev: InboundEvent): string | undefined {
  return "turn_id" in ev && typeof ev.turn_id === "string" ? ev.turn_id : undefined;
}

function transitionTurnDelivery(
  messages: UIMessage[],
  turnId: string,
  status: MessageDeliveryStatus,
): UIMessage[] {
  let changed = false;
  const next = messages.map((message) => {
    if (
      message.role !== "user"
      || message.turnId !== turnId
      || message.deliveryStatus === status
      || (status === "accepted" && message.deliveryStatus !== "sending")
    ) {
      return message;
    }
    changed = true;
    return { ...message, deliveryStatus: status };
  });
  return changed ? next : messages;
}

function appendProjectedSessionInput(
  messages: UIMessage[],
  event: Extract<InboundEvent, { event: "user_message" }>,
): UIMessage[] {
  const sessionMessage = event.provenance?.session_message;
  const messageId = sessionMessage?.message_id?.trim();
  if (!sessionMessage || !messageId) return messages;
  if (messages.some((message) => message.sessionMessage?.message_id === messageId)) return messages;

  const row: UIMessage = {
    id: `session-message:${messageId}`,
    role: "user",
    content: event.text,
    createdAt: typeof event.created_at_ms === "number"
      && Number.isFinite(event.created_at_ms)
      ? event.created_at_ms
      : Date.now(),
    sessionMessage,
    ...turnFieldsFromEvent(event, "user"),
  };
  return [...messages, row];
}

function createTranscript(messages: UIMessage[], saved: ThreadTranscriptSnapshot | undefined, historyKey: string | null) {
  const owner = new ThreadTranscript(messages, saved);
  // The first paint must not enter the welcome layout while history is pending.
  owner.paging = { ...owner.paging, loading: !!historyKey && owner.paging.version === 0,
    hasMoreBefore: historyKey ? owner.paging.hasMoreBefore : false };
  return owner;
}

export function useNanobotStream(
  chatId: string | null,
  initialMessages: UIMessage[] = EMPTY_INITIAL_MESSAGES,
  hasPendingToolCalls = false,
  onTurnEnd?: () => void,
  onStreamDetach?: (messages: UIMessage[]) => void,
  completedTurnIds: readonly string[] = EMPTY_COMPLETED_TURN_IDS,
  history?: { key: string | null; cache?: ThreadMessageCache },
  historyActiveTurnId: string | null = null,
): {
  messages: UIMessage[];
  modelRequests: ReadonlyMap<string, UIModelRequestSnapshot>;
  /** Conversation owning these messages, including while a selection is handing over. */
  messagesKey: string | null;
  /** Whether ``messages`` belongs to the current ``chatId`` after a session switch. */
  messagesReady: boolean;
  isStreaming: boolean;
  /** Unix epoch seconds when the current user turn started (WebSocket ``goal_status``). */
  runStartedAt: number | null;
  retryStatus: RetryStatus | null;
  /** Latest sustained goal for this ``chatId`` (``goal_state`` WS events). */
  goalState: GoalStateWsPayload | undefined;
  recoveryState: RecoveryState | null;
  continueRecovery: () => Promise<void>;
  dismissRecovery: () => Promise<void>;
  send: (
    content: string,
    images?: SendAttachment[],
    options?: SendOptions,
  ) => SubmittedTurn | null;
  transcribeAudio: (dataUrl: string, options?: { durationMs?: number }) => Promise<string>;
  stop: () => void;
  history: ThreadPaging;
  refreshHistory: () => void;
  loadOlder: () => Promise<void>;
  loadTraceDetails: (refs: string[]) => Promise<Array<{ ref: string; events: ThreadProjectionEvent[] }>>;
  /** Latest transport-level fault raised since the last ``dismissStreamError``.
   * ``null`` when there is nothing to show. */
  streamError: StreamError | null;
  dismissStreamError: () => void;
} {
  const { client, getToken } = useClient();
  const historyKey = history?.key ?? null;
  const messageCache = history?.cache;
  const [initialTranscript] = useState(() => createTranscript(initialMessages,
    chatId ? messageCache?.get(chatId) : undefined, historyKey));
  const transcriptRef = useRef(initialTranscript);
  const [historyState, setHistoryState] = useState(initialTranscript.paging);
  const publishHistory = useCallback(() => setHistoryState(transcriptRef.current.paging), []);
  const [refreshSeq, setRefreshSeq] = useState(0);
  const refreshHistory = useCallback(() => setRefreshSeq((value) => value + 1), []);
  const threadVisible = useThreadVisibility();
  const threadVisibleRef = useRef(threadVisible);
  threadVisibleRef.current = threadVisible;
  const [runState, setRunState] = useState(() => chatId ? client.getRunState(chatId) : null);
  const isStreaming = runState?.active ?? false;
  const runStartedAt = runState?.startedAt ?? null;
  const historyRunGenerationRef = useRef({ chatId, generation: chatId ? client.getRunGeneration(chatId) : 0 });
  if (historyRunGenerationRef.current.chatId !== chatId) {
    historyRunGenerationRef.current = { chatId, generation: chatId ? client.getRunGeneration(chatId) : 0 };
  }
  const [messages, setRenderedMessages] = useState<UIMessage[]>(initialTranscript.messages);
  const [modelRequests, setModelRequests] = useState(initialTranscript.modelRequests);
  const messagesRef = useRef(messages);
  // Keep received state ahead of React's batched render: navigation can unmount
  // this hook after a stream flush but before the queued render commits.
  const setMessages = useCallback<React.Dispatch<React.SetStateAction<UIMessage[]>>>((update) => {
    const next = typeof update === "function" ? update(messagesRef.current) : update;
    messagesRef.current = next;
    transcriptRef.current.projection = { ...transcriptRef.current.projection, messages: next };
    setRenderedMessages(next);
    setModelRequests(transcriptRef.current.modelRequests);
    setHistoryState(transcriptRef.current.paging);
  }, []);
  const [messageScope, setMessageScope] = useState({ chatId, historyKey, client });
  const initialStreaming = useMemo(() => {
    if (completedTurnIds.length === 0) return hasPendingAgentActivity(initialMessages);
    const completedInitialTurns = new Set(completedTurnIds);
    return hasPendingAgentActivity(initialMessages.filter((message) => (
      !message.turnId || !completedInitialTurns.has(message.turnId)
    )));
  }, [completedTurnIds, initialMessages]);
  const [retryStatus, setRetryStatus] = useState<RetryStatus | null>(null);
  const [goalState, setGoalState] = useState<GoalStateWsPayload | undefined>(undefined);
  const [recoveryState, setRecoveryState] = useState<RecoveryState | null>(null);
  const [streamError, setStreamError] = useState<StreamError | null>(null);

  const pendingStreamEventsRef = useRef<PendingStreamEvent[]>([]);
  const streamFrameRef = useRef<number | null>(null);
  const streamTimerRef = useRef<number | null>(null);
  const lastStreamFlushRef = useRef(0);


  const dismissStreamError = useCallback(() => setStreamError(null), []);

  const clearPendingStreamWork = useCallback(() => {
    if (streamFrameRef.current !== null) {
      window.cancelAnimationFrame(streamFrameRef.current);
      streamFrameRef.current = null;
    }
    if (streamTimerRef.current !== null) {
      window.clearTimeout(streamTimerRef.current);
      streamTimerRef.current = null;
    }
    pendingStreamEventsRef.current = [];
    lastStreamFlushRef.current = 0;
  }, []);

  const isSideChannelEvent = useCallback((ev: InboundEvent) => {
    const turnId = eventTurnId(ev);
    return turnId !== undefined && transcriptRef.current.sideChannelTurnIds.has(turnId);
  }, []);

  const clearActivitySegment = useCallback(() => {
    transcriptRef.current.projection = clearThreadProjectionActivity(transcriptRef.current.projection);
  }, []);

  const closeActiveAssistantStream = useCallback(() => {
    const hadActiveAssistant = transcriptRef.current.projection.activeAssistantId !== null;
    transcriptRef.current.projection = closeThreadProjectionAnswer(transcriptRef.current.projection);
    return hadActiveAssistant;
  }, []);

  const applyStreamError = useCallback((err: StreamError) => {
    // One multiplexed client serves every thread. A correlated send fault
    // belongs only to its target chat. An uncorrelated transport close can
    // still be shown in the mounted thread, but cannot roll back any turn.
    if (!chatId || (err.chatId && err.chatId !== chatId)) return;
    setStreamError(err);
    if (err.kind === "model_request_failed") return;
    if (!err.turnId) return;

    const rejectedTurnId = err.turnId;
    pendingStreamEventsRef.current = pendingStreamEventsRef.current.filter(
      (event) => event.turn.turnId !== rejectedTurnId,
    );
    transcriptRef.current.sideChannelTurnIds.delete(rejectedTurnId);
    setMessages((prev) => {
      const rejectedRows = prev.filter((message) => message.turnId === rejectedTurnId);
      if (rejectedRows.length === 0) return prev;
      const rejectedIds = new Set(rejectedRows.map((message) => message.id));
      const rejectedSegments = new Set(
        rejectedRows
          .map((message) => message.activitySegmentId)
          .filter((segmentId): segmentId is string => typeof segmentId === "string"),
      );
      const projection = transcriptRef.current.projection;
      const closedAssistantIds = new Set(projection.closedAssistantIds);
      for (const id of rejectedIds) closedAssistantIds.delete(id);
      const nextMessages = prev.flatMap<UIMessage>((message) => {
        if (message.turnId !== rejectedTurnId) return [message];
        if (message.role !== "user") return [];
        return [{
          ...message,
          deliveryStatus: "failed" as const,
          deliveryErrorKind: err.kind,
        }];
      });
      transcriptRef.current.projection = {
        ...projection,
        messages: nextMessages,
        activeAssistantId: projection.activeAssistantId
          && rejectedIds.has(projection.activeAssistantId)
          ? null
          : projection.activeAssistantId,
        closedAssistantIds,
        activitySegmentId: projection.activitySegmentId
          && rejectedSegments.has(projection.activitySegmentId)
          ? null
          : projection.activitySegmentId,
        fileEditSegmentId: projection.fileEditSegmentId
          && rejectedSegments.has(projection.fileEditSegmentId)
          ? null
          : projection.fileEditSegmentId,
      };
      transcriptRef.current.rejectTurn(rejectedTurnId);
      return nextMessages;
    });

    if (!client.getRunState(chatId).active) {
      transcriptRef.current.projection = {
        ...transcriptRef.current.projection,
        suppressUntilTurnEnd: false,
      };
    }
  }, [chatId, client, setMessages]);

  useEffect(() => client.onError(applyStreamError), [applyStreamError, client]);

  const applyPendingStreamEvents = useCallback(
    (prev: UIMessage[], events: PendingStreamEvent[]): UIMessage[] => {
      transcriptRef.current.projection = { ...transcriptRef.current.projection, messages: prev };
      for (let index = 0; index < events.length; index++) {
        const event = events[index];
        const chunks = [event.text];
        const members = event.turn.turnSeq === undefined ? [] : [event.turn.turnSeq];
        let turn = event.turn;
        while (index + 1 < events.length) {
          const nextEvent = events[index + 1];
          if (nextEvent.kind !== event.kind
            || nextEvent.turn.turnId !== event.turn.turnId
            || nextEvent.turn.turnPhase !== event.turn.turnPhase
            || nextEvent.streamId !== event.streamId
            || (nextEvent.kind === "delta" && event.kind === "delta"
              && (nextEvent.source !== event.source
                || JSON.stringify(nextEvent.responseSources) !== JSON.stringify(event.responseSources)))) break;
          chunks.push(nextEvent.text);
          if (nextEvent.turn.turnSeq !== undefined) members.push(nextEvent.turn.turnSeq);
          turn = { ...turn, ...nextEvent.turn };
          index++;
        }
        const text = chunks.join("");
        const projectedEvent: ThreadProjectionEvent = event.kind === "delta"
          ? {
              event: "delta",
              chat_id: chatId ?? "",
              text,
              turn_id: turn.turnId,
              turn_phase: turn.turnPhase,
              turn_seq: turn.turnSeq,
              source: event.source,
              response_sources: event.responseSources,
            }
          : {
              event: "reasoning_delta",
              chat_id: chatId ?? "",
              text,
              turn_id: turn.turnId,
              turn_phase: turn.turnPhase,
              turn_seq: turn.turnSeq,
            };
        projectedEvent.stream_id = event.streamId;
        if (turn.turnId && members.length) {
          const ranges: Array<[number, number]> = [];
          for (const seq of members) {
            const last = ranges[ranges.length - 1];
            if (last && last[1] + 1 === seq) last[1] = seq;
            else ranges.push([seq, seq]);
          }
          projectedEvent.projection_receipts = [{ turn_id: turn.turnId, ranges }];
        }
        transcriptRef.current.project(projectedEvent, {
          createId: () => crypto.randomUUID(), now: Date.now(), startSeq: event.turn.turnSeq,
        });
      }
      return transcriptRef.current.messages;
    },
    [chatId],
  );

  const flushPendingStreamEvents = useCallback((end?: Extract<ThreadProjectionEvent, { event: "stream_end" }>) => {
    lastStreamFlushRef.current = 0;
    if (streamFrameRef.current !== null) {
      window.cancelAnimationFrame(streamFrameRef.current);
      streamFrameRef.current = null;
    }
    if (streamTimerRef.current !== null) {
      window.clearTimeout(streamTimerRef.current);
      streamTimerRef.current = null;
    }
    const events = pendingStreamEventsRef.current;
    if (events.length === 0 && !end) return;
    pendingStreamEventsRef.current = [];
    setMessages((prev) => {
      const nextMessages = events.length > 0 ? applyPendingStreamEvents(prev, events) : prev;
      transcriptRef.current.projection = { ...transcriptRef.current.projection, messages: nextMessages };
      if (end) transcriptRef.current.project(end, {
        createId: () => crypto.randomUUID(), now: Date.now(),
      });
      return transcriptRef.current.messages;
    });
  }, [applyPendingStreamEvents, setMessages]);

  const schedulePendingStreamFlush = useCallback(function schedule() {
    if (streamFrameRef.current !== null || streamTimerRef.current !== null) return;
    if (document.visibilityState === "hidden" || !threadVisibleRef.current) {
      streamTimerRef.current = window.setTimeout(() => {
        streamTimerRef.current = null;
        const events = pendingStreamEventsRef.current;
        if (events.length === 0) return;
        pendingStreamEventsRef.current = [];
        setMessages((prev) => applyPendingStreamEvents(prev, events));
      }, BACKGROUND_STREAM_FLUSH_INTERVAL_MS);
      return;
    }
    const delay = VISIBLE_STREAM_FLUSH_INTERVAL_MS
      - (performance.now() - lastStreamFlushRef.current);
    if (delay > 0) {
      streamTimerRef.current = window.setTimeout(() => {
        streamTimerRef.current = null;
        schedule();
      }, delay);
      return;
    }
    streamFrameRef.current = window.requestAnimationFrame(() => {
      streamFrameRef.current = null;
      const events = pendingStreamEventsRef.current;
      if (events.length === 0) return;
      pendingStreamEventsRef.current = [];
      lastStreamFlushRef.current = performance.now();
      setMessages((prev) => applyPendingStreamEvents(prev, events));
    });
  }, [applyPendingStreamEvents, setMessages]);

  useEffect(() => {
    if (threadVisible) {
      flushPendingStreamEvents();
    } else if (streamFrameRef.current !== null || streamTimerRef.current !== null) {
      if (streamFrameRef.current !== null) window.cancelAnimationFrame(streamFrameRef.current);
      streamFrameRef.current = null;
      if (streamTimerRef.current !== null) window.clearTimeout(streamTimerRef.current);
      streamTimerRef.current = null;
      schedulePendingStreamFlush();
    }
  }, [threadVisible, flushPendingStreamEvents, schedulePendingStreamFlush]);

  useEffect(() => {
    const onVisibilityChange = () => {
      if (pendingStreamEventsRef.current.length === 0) return;
      if (document.visibilityState === "visible" && threadVisibleRef.current) {
        flushPendingStreamEvents();
      } else {
        if (streamFrameRef.current !== null) window.cancelAnimationFrame(streamFrameRef.current);
        streamFrameRef.current = null;
        if (streamTimerRef.current !== null) window.clearTimeout(streamTimerRef.current);
        streamTimerRef.current = null;
        schedulePendingStreamFlush();
      }
    };
    document.addEventListener("visibilitychange", onVisibilityChange);
    return () => document.removeEventListener("visibilitychange", onVisibilityChange);
  }, [flushPendingStreamEvents, schedulePendingStreamFlush]);

  useEffect(() => {
    if (!chatId) return;
    return client.onRunStatus((runChatId, state) => {
      if (runChatId !== chatId) return;
      setRunState(state);
      if (state.active) return;
      flushPendingStreamEvents();
      setMessages((prev) => {
        const settled = prev.map((message) => (
          message.isStreaming ? { ...message, isStreaming: false } : message
        ));
        transcriptRef.current.projection = resetThreadProjectionCursor(
          transcriptRef.current.projection,
          settled,
        );
        return settled;
      });
    });
  }, [chatId, client, clearActivitySegment, flushPendingStreamEvents, setMessages]);

  // Reset local state when switching chats. Do not reset on every
  // ``initialMessages`` update: a brand-new chat can receive an empty/404
  // history response after the optimistic first message has already rendered.
  useEffect(() => {
    transcriptRef.current = createTranscript(initialMessages, chatId ? messageCache?.get(chatId) : undefined, historyKey);
    setMessages(transcriptRef.current.messages);
    setMessageScope({ chatId, historyKey, client });
    setRunState(chatId ? client.getRunState(chatId) : null);
    setStreamError(null);
    setRetryStatus(null);
    setGoalState(chatId ? client.getGoalState(chatId) : undefined);
    setRecoveryState(null);
    clearPendingStreamWork();
  }, [chatId, client, historyKey, clearActivitySegment, clearPendingStreamWork, setMessages]);

  useEffect(() => {
    if (!chatId || (!hasPendingToolCalls && !initialStreaming)) return;
    client.restorePendingRun(chatId, historyRunGenerationRef.current.generation, historyActiveTurnId);
  }, [chatId, client, hasPendingToolCalls, historyActiveTurnId, initialStreaming]);

  const applyProjectionEvent = useCallback((
    event: ThreadProjectionEvent,
    options?: { sideChannel?: boolean },
  ) => {
    setMessages((prev) => {
      transcriptRef.current.projection = { ...transcriptRef.current.projection, messages: prev };
      return transcriptRef.current.project(event, { createId: () => crypto.randomUUID(), now: Date.now(),
        sideChannel: options?.sideChannel });
    });
  }, [setMessages]);

  const olderReadRef = useRef<{
    owner: ThreadTranscript; read: ThreadRead; controller: AbortController;
  } | null>(null);
  const cancelOlderRead = useCallback(() => {
    const pending = olderReadRef.current;
    if (!pending) return;
    olderReadRef.current = null;
    pending.controller.abort();
    pending.owner.finishRead(pending.read);
    if (transcriptRef.current === pending.owner) publishHistory();
  }, [publishHistory]);
  const latestReadOwnerRef = useRef<ThreadTranscript>();
  const detailRequestsRef = useRef(new Map<string, Promise<{ ref: string; events: ThreadProjectionEvent[] } | null>>());

  useEffect(() => {
    if (!historyKey) return;
    const owner = transcriptRef.current;
    const controller = new AbortController();
    const generation = chatId ? client.getRunGeneration(chatId) : 0;
    const read = owner.begin(latestReadOwnerRef.current === owner ? "latest" : "initial");
    latestReadOwnerRef.current = owner;
    publishHistory();
    let disposed = false;
    let superseded = false;
    let publishing = false;
    const install = (body: Awaited<ReturnType<typeof fetchWebuiThread>>, ownRead: boolean, seed = false) => {
      if (disposed || (ownRead && superseded) || transcriptRef.current !== owner) return;
      flushPendingStreamEvents();
      const decision = ownRead ? read : owner.begin(seed ? "initial" : "latest");
      const canonical = body ? persistedCanonicalRunState(body) : null;
      const settle = chatId && canonical && !canonical.snapshot.hasPendingToolCalls
        && client.canReconcileCanonicalCompletion(chatId, generation, canonical.completedTurnIds, canonical.snapshot);
      const accepted = owner.accept(body, decision);
      // Commit the received owner before cache listeners/ledger callbacks can reenter.
      setMessages(owner.messages);
      if (accepted && chatId) messageCache?.set(chatId, owner.save());
      if (ownRead) {
        publishing = true;
        if (body) webuiThreadCache.set(historyKey, body);
        else webuiThreadCache.delete(historyKey);
        publishing = false;
      }
      if (ownRead && chatId && canonical) {
        if (accepted && settle && client.reconcileCanonicalCompletion(chatId, generation,
          canonical.completedTurnIds, canonical.snapshot)) {
          setRetryStatus(null);
        } else client.fenceCanonicalCompletedTurns(chatId, canonical.completedTurnIds);
      }
    };
    const cached = webuiThreadCache.get(historyKey);
    if (cached && owner.paging.version === 0) install(cached, false, true);
    const unsubscribe = webuiThreadCache.subscribe(historyKey, (body) => {
      if (publishing) return;
      superseded = true;
      controller.abort();
      cancelOlderRead();
      install(body, false);
    });
    void fetchLatestWebuiThread(client, getToken(), historyKey, controller.signal)
      .then((body) => install(body, true))
      .catch((error: unknown) => {
        if (disposed || superseded || controller.signal.aborted || transcriptRef.current !== owner) return;
        if (error instanceof ApiError && error.status === 404) install(null, true);
        else { owner.finishRead(read, (error as Error).message); publishHistory(); }
      });
    return () => { disposed = true; controller.abort(); cancelOlderRead(); unsubscribe(); };
  }, [cancelOlderRead, chatId, client, flushPendingStreamEvents, getToken, historyKey, messageCache, publishHistory, refreshSeq, setMessages]);

  const loadOlder = useCallback(async () => {
    const owner = transcriptRef.current;
    const before = owner.paging.beforeCursor;
    if (!historyKey || !before || !owner.paging.hasMoreBefore || owner.paging.loadingOlder) return;
    const read = owner.begin("older");
    const controller = new AbortController();
    const operation = { owner, read, controller };
    olderReadRef.current = operation;
    publishHistory();
    try {
      const body = await fetchWebuiThread(getToken(), historyKey, { before, limit: 120, signal: controller.signal });
      if (olderReadRef.current !== operation || transcriptRef.current !== owner) return;
      flushPendingStreamEvents();
      owner.accept(body, read);
      setMessages(owner.messages);
    } catch (error) {
      if (olderReadRef.current === operation && transcriptRef.current === owner) {
        owner.finishRead(read, (error as Error).message);
        publishHistory();
      }
    } finally {
      if (olderReadRef.current === operation) olderReadRef.current = null;
    }
  }, [flushPendingStreamEvents, getToken, historyKey, publishHistory, setMessages]);

  const loadTraceDetails = useCallback(async (refs: string[]) => {
    const owner = transcriptRef.current;
    if (!historyKey) return [];
    const details = await Promise.all(refs.map((ref) => {
      const id = `${historyKey}:${ref}`;
      const existing = detailRequestsRef.current.get(id);
      if (existing) return existing;
      const request = fetchWebuiThreadTraceDetail(getToken(), historyKey, ref).then((detail) => {
        if (transcriptRef.current !== owner) return null;
        flushPendingStreamEvents();
        owner.expandDetail(ref, detail.events);
        setMessages(owner.messages);
        return { ref, events: detail.events };
      }).finally(() => detailRequestsRef.current.delete(id));
      detailRequestsRef.current.set(id, request);
      return request;
    }));
    return details.filter((detail) => detail !== null);
  }, [flushPendingStreamEvents, getToken, historyKey, setMessages]);

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

    const handle = (ev: InboundEvent) => {
      if (ev.event === "error") {
        if (ev.detail === "message_too_big") {
          applyStreamError({
            kind: "message_too_big",
            chatId,
            turnId: ev.turn_id,
          });
        } else if (ev.detail === "workspace_scope_rejected") {
          applyStreamError({
            kind: "workspace_scope_rejected",
            reason: ev.reason,
            chatId,
            turnId: ev.turn_id,
          });
        } else if (ev.turn_id) {
          applyStreamError({
            kind: "turn_rejected",
            detail: ev.detail,
            reason: ev.reason,
            chatId,
            turnId: ev.turn_id,
          });
        }
        return;
      }
      const turnId = eventTurnId(ev);
      if (turnId) {
        setMessages((prev) => transitionTurnDelivery(prev, turnId, "accepted"));
      }
      if (ev.event === "message_accepted") {
        if (ev.media_urls?.length) {
          setMessages((prev) => prev.map((message) => (
            message.role === "user" && message.turnId === ev.turn_id
              ? { ...message, media: ev.media_urls }
              : message
          )));
        }
        return;
      }
      if (ev.event === "user_message") {
        if (ev.provenance?.session_message) {
          flushPendingStreamEvents();
          closeActiveAssistantStream();
          clearActivitySegment();
          setMessages((prev) => {
            const next = appendProjectedSessionInput(prev, ev);
            if (next !== prev) transcriptRef.current.registerInput(next[next.length - 1]);
            return next;
          });
          return;
        }
        setMessages((prev) => {
          if (ev.turn_id && prev.some((message) => (
            message.role === "user" && message.turnId === ev.turn_id
          ))) return ev.media_urls?.length ? prev.map((message) => (
            message.role === "user" && message.turnId === ev.turn_id
              ? { ...message, media: ev.media_urls }
              : message
          )) : prev;
          const row: UIMessage = {
              id: crypto.randomUUID(),
              role: "user",
              content: ev.text,
              ...(ev.turn_id ? { turnId: ev.turn_id } : {}),
              turnPhase: "user",
              turnSeq: 0,
              deliveryStatus: "accepted",
              createdAt: typeof ev.created_at_ms === "number"
                && Number.isFinite(ev.created_at_ms)
                ? ev.created_at_ms
                : Date.now(),
              ...(ev.media_urls?.length ? { media: ev.media_urls } : {}),
              ...(ev.cli_apps?.length ? { cliApps: ev.cli_apps } : {}),
              ...(ev.mcp_presets?.length ? { mcpPresets: ev.mcp_presets } : {}),
              ...(ev.session_mentions?.length
                ? { sessionMentions: ev.session_mentions }
                : {}),
          };
          transcriptRef.current.registerInput(row);
          return [...prev, row];
        });
        return;
      }
      if (ev.event === "model_request") {
        flushPendingStreamEvents();
        applyProjectionEvent(ev);
        return;
      }
      const sideChannelEvent = isSideChannelEvent(ev);
      if (ev.event === "context_compaction") {
        flushPendingStreamEvents();
        closeActiveAssistantStream();
        clearActivitySegment();
        const previous = transcriptRef.current.messages.find((row) => row.id === `compaction-${ev.compaction_id}`);
        if (acceptsCompactionPhase(previous?.compaction?.phase, ev.phase)) applyProjectionEvent(ev);
        return;
      }
      if (
        ev.event === "delta"
        || ev.event === "message"
        || ev.event === "file_edit"
        || ev.event === "reasoning_delta"
        || ev.event === "stream_end"
      ) setRetryStatus(null);
      if (ev.event === "delta") {
        if (transcriptRef.current.projection.suppressUntilTurnEnd || transcriptRef.current.represented(ev)) return;
        const chunk = typeof ev.text === "string" ? ev.text : "";
        if (!chunk) return;
        pendingStreamEventsRef.current.push({
          kind: "delta",
          text: chunk,
          turn: turnFieldsFromEvent(ev, "answer"),
          streamId: ev.stream_id,
          source: ev.source,
          responseSources: ev.response_sources,
        });
        schedulePendingStreamFlush();
        return;
      }

      if (ev.event === "reasoning_delta") {
        if (transcriptRef.current.projection.suppressUntilTurnEnd || transcriptRef.current.represented(ev)) return;
        const chunk = ev.text;
        if (!chunk) return;
        pendingStreamEventsRef.current.push({
          kind: "reasoning",
          text: chunk,
          turn: turnFieldsFromEvent(ev, "reasoning"),
          streamId: ev.stream_id,
        });
        schedulePendingStreamFlush();
        return;
      }

      if (ev.event === "stream_end") {
        if (transcriptRef.current.represented(ev)) return;
        flushPendingStreamEvents(ev);
        if (transcriptRef.current.projection.suppressUntilTurnEnd) return;
        if (ev.resuming) {
          return;
        }
        // ``stream_end`` closes the current answer segment, not the turn.
        // Tools and follow-up model segments may still arrive before the
        // definitive ``turn_end`` event.
        return;
      }

      flushPendingStreamEvents();

      if (ev.event === "reasoning_end") {
        if (transcriptRef.current.projection.suppressUntilTurnEnd) return;
        applyProjectionEvent(ev);
        return;
      }

      if (ev.event === "goal_state") {
        setGoalState(ev.goal_state);
        return;
      }

      if (ev.event === "goal_status") {
        if (ev.status === "running") setStreamError(null);
        else setRetryStatus(null);
        return;
      }

      if (ev.event === "retry_status") {
        const activeTurnId = client.getRunTurnId(chatId);
        if (ev.turn_id && activeTurnId && ev.turn_id !== activeTurnId) return;
        if (ev.state === "recovered" || ev.state === "cleared") {
          setRetryStatus(null);
        } else {
          const retryAfterSeconds =
            typeof ev.retry_after_s === "number" &&
            Number.isFinite(ev.retry_after_s) &&
            ev.retry_after_s >= 0
              ? ev.retry_after_s
              : undefined;
          setRetryStatus({
            state: ev.state,
            attempt: ev.attempt,
            error_kind: ev.error_kind,
            ...(typeof ev.max_attempts === "number"
              ? { max_attempts: ev.max_attempts }
              : {}),
            ...(retryAfterSeconds !== undefined
              ? { next_retry_at: Date.now() / 1000 + retryAfterSeconds }
              : {}),
            ...(ev.turn_id ? { turn_id: ev.turn_id } : {}),
          });
        }
        return;
      }

      if (ev.event === "turn_end") {
        if (typeof ev.turn_id === "string") transcriptRef.current.sideChannelTurnIds.delete(ev.turn_id);
        if ("goal_state" in ev && ev.goal_state != null && typeof ev.goal_state === "object") {
          setGoalState(ev.goal_state);
        }
        setRetryStatus(null);
        const modelRequestFailed = ev.outcome === "failed" && ev.failure_kind === "model";
        const failureAttempts =
          typeof ev.failure_attempts === "number"
          && Number.isInteger(ev.failure_attempts)
          && ev.failure_attempts > 0
            ? ev.failure_attempts
            : undefined;
        const modelFailure = modelRequestFailed
          ? {
              kind: "model_request_failed" as const,
              chatId,
              ...(ev.turn_id ? { turnId: ev.turn_id } : {}),
              ...(typeof ev.failure_error_kind === "string"
                ? { errorKind: ev.failure_error_kind }
                : {}),
              ...(failureAttempts !== undefined ? { attempts: failureAttempts } : {}),
            }
          : null;
        if (modelFailure) setStreamError(modelFailure);
        applyProjectionEvent(ev);
        playTurnCompleteSound();
        onTurnEnd?.();
        return;
      }

      if (ev.event === "recovery_state") {
        const next: RecoveryState = {
          status: ev.status,
          recovery_id: ev.recovery_id,
          ...(ev.reason ? { reason: ev.reason } : {}),
          ...(typeof ev.attempts === "number" ? { attempts: ev.attempts } : {}),
          ...(typeof ev.can_continue === "boolean"
            ? { can_continue: ev.can_continue }
            : {}),
          ...(typeof ev.failure_error_kind === "string"
            ? { failure_error_kind: ev.failure_error_kind }
            : {}),
          ...(typeof ev.reply_preserved === "boolean"
            ? { reply_preserved: ev.reply_preserved }
            : {}),
        };
        setRecoveryState(next);
        if (ev.reason === "model_request_failed" || ev.status === "resuming") {
          setStreamError(null);
        }
        if (
          ev.status === "awaiting_user"
          || ev.status === "recovered"
          || ev.status === "failed"
        ) {
          setRetryStatus(null);
          clearPendingStreamWork();
          closeActiveAssistantStream();
          clearActivitySegment();
        }
        return;
      }

      if (ev.event === "attached") {
        setRecoveryState(ev.recovery_state ?? null);
        if (
          ev.recovery_state?.reason === "model_request_failed"
          || ev.recovery_state?.status === "resuming"
        ) {
          setStreamError(null);
        }
        if (
          ev.recovery_state?.status === "awaiting_user"
          || ev.recovery_state?.status === "failed"
        ) {
          clearPendingStreamWork();
          closeActiveAssistantStream();
          clearActivitySegment();
        }
        return;
      }

      if (ev.event === "message") {
        applyProjectionEvent(ev, { sideChannel: sideChannelEvent });
        if (sideChannelEvent && typeof ev.turn_id === "string") {
          transcriptRef.current.sideChannelTurnIds.delete(ev.turn_id);
        }
        return;
      }
      if (ev.event === "file_edit") {
        applyProjectionEvent(ev);
        return;
      }
    };

    const unsub = client.onTranscript(chatId, handle);
    return () => {
      unsub();
      // Navigation may happen before the throttled paint. Snapshot the pending
      // deltas synchronously while they still belong to this subscription.
      const pending = pendingStreamEventsRef.current;
      const snapshot = pending.length > 0
        ? applyPendingStreamEvents(messagesRef.current, pending)
        : messagesRef.current;
      onStreamDetach?.(snapshot);
      if (pending.length > 0) setMessages(snapshot);
      messageCache?.set(chatId, transcriptRef.current.save());
      clearPendingStreamWork();
    };
  }, [
    applyProjectionEvent,
    applyPendingStreamEvents,
    applyStreamError,
    chatId,
    closeActiveAssistantStream,
    client,
    clearActivitySegment,
    clearPendingStreamWork,
    flushPendingStreamEvents,
    isSideChannelEvent,
    onTurnEnd,
    onStreamDetach,
    messageCache,
    schedulePendingStreamFlush,
    setMessages,
  ]);

  const send = useCallback(
    (content: string, images?: SendAttachment[], options?: SendOptions) => {
      if (!chatId) return null;
      const hasAttachments = !!images && images.length > 0;
      // Text is optional when files are attached — the agent will still see
      // them via ``media`` paths.
      if (!hasAttachments && !content.trim()) return null;

      setStreamError(null);
      const sideChannel = options?.sideChannel === true;
      const finalizeActiveTurn = options?.finalizeActiveTurn === true;
      const continueActiveTurn = options?.continueActiveTurn === true;
      const outboundContent = options?.quotedContext
        ? formatQuotedUserMessage(content, options.quotedContext)
        : content;
      flushPendingStreamEvents();
      if (finalizeActiveTurn) {
        client.finishRunLocally(chatId);
        setRetryStatus(null);
      }
      const turnId = crypto.randomUUID();
      const userMessageId = crypto.randomUUID();
      if (sideChannel) transcriptRef.current.sideChannelTurnIds.add(turnId);
      const previews = hasAttachments ? images!.map(({ preview }) => (
        preview.kind === "video" && preview.url?.startsWith("data:")
          ? { kind: preview.kind, name: preview.name }
          : preview
      )) : undefined;
      setMessages((prev) => {
        let projection = { ...transcriptRef.current.projection, messages: prev };
        if ((!sideChannel && !continueActiveTurn) || finalizeActiveTurn) {
          projection = resetThreadProjectionCursor(projection, prev);
        } else if (continueActiveTurn) {
          // Guidance belongs to the active backend turn. Preserve the answer
          // cursor so its resuming stream_end can finalize the text already
          // shown before the new user row, while starting fresh activity after it.
          projection = clearThreadProjectionActivity(projection);
        }
        const base = finalizeActiveTurn ? finalizeStreamedTurn(prev) : prev;
        const next: UIMessage[] = [
          ...base,
          {
            id: userMessageId,
            role: "user" as const,
            content: outboundContent,
            turnId,
            turnPhase: "user",
            turnSeq: 0,
            deliveryStatus: "sending" as const,
            createdAt: Date.now(),
            ...(previews ? { media: previews } : {}),
            ...(options?.cliApps?.length ? { cliApps: options.cliApps } : {}),
            ...(options?.mcpPresets?.length ? { mcpPresets: options.mcpPresets } : {}),
            ...(options?.sessionMentions?.length
              ? { sessionMentions: options.sessionMentions }
              : {}),
            },
        ];
        transcriptRef.current.projection = { ...projection, messages: next };
        transcriptRef.current.registerInput(next[next.length - 1]);
        return next;
      });
      const wireMedia = hasAttachments ? images!.map((i) => i.media) : undefined;
      const clientOptions = {
        ...options,
        turnId,
        ...((sideChannel || continueActiveTurn) ? { startsNewRun: false } : {}),
      };
      delete clientOptions.quotedContext;
      delete clientOptions.sideChannel;
      delete clientOptions.finalizeActiveTurn;
      delete clientOptions.continueActiveTurn;
      const delivery = options?.userShell
        ? client.sendUserShellCommand(chatId, outboundContent, clientOptions)
        : wireMedia?.length
          ? client.sendAttachments(chatId, outboundContent, wireMedia, clientOptions)
          : undefined;
      if (!delivery) client.sendMessage(chatId, outboundContent, undefined, clientOptions);
      // Every caller may keep this promise to retain its draft until accepted.
      // Also observe it here for queued/landing sends without an active composer.
      void delivery?.catch(() => {});
      return { turnId, userMessageId, sideChannel, delivery };
    },
    [chatId, clearActivitySegment, client, flushPendingStreamEvents, setMessages],
  );

  const stop = useCallback(() => {
    if (!chatId) return;
    flushPendingStreamEvents();
    setRetryStatus(null);
    setMessages((prev) => {
      const settled = prev.map((m) => ({ ...m, isStreaming: false }));
      const projection = resetThreadProjectionCursor(transcriptRef.current.projection, settled);
      const modelRequests = new Map(projection.modelRequests);
      for (const [turn, snapshot] of modelRequests) modelRequests.set(turn, { ...snapshot, ended: true });
      transcriptRef.current.projection = { ...projection, modelRequests };
      return settled;
    });
    client.finishRunLocally(chatId);
    client.sendMessage(chatId, "/stop");
  }, [chatId, clearActivitySegment, client, flushPendingStreamEvents, setMessages]);

  const transcribeAudio = useCallback(
    (dataUrl: string, options?: { durationMs?: number }) =>
      client.transcribeAudio(dataUrl, options),
    [client],
  );

  const recoveryAction = useCallback(async (action: "continue" | "dismiss") => {
    if (!chatId || !recoveryState) return;
    await client.requestMutation(`recovery.${action}`, {
      chat_id: chatId,
      recovery_id: recoveryState.recovery_id,
    });
  }, [chatId, client, recoveryState]);

  const continueRecovery = useCallback(
    () => recoveryAction("continue"),
    [recoveryAction],
  );
  const dismissRecovery = useCallback(
    () => recoveryAction("dismiss"),
    [recoveryAction],
  );

  return {
    messages,
    modelRequests,
    messagesKey: messageScope.historyKey ?? messageScope.chatId,
    messagesReady: messageScope.chatId === chatId && messageScope.historyKey === historyKey && messageScope.client === client,
    isStreaming,
    runStartedAt,
    retryStatus,
    goalState,
    recoveryState,
    continueRecovery,
    dismissRecovery,
    send,
    transcribeAudio,
    stop,
    history: historyState,
    refreshHistory,
    loadOlder,
    loadTraceDetails,
    streamError,
    dismissStreamError,
  };
}