@arbidocs/react 0.5.111 → 0.5.112

package/dist/chat/stream-handlers.js

@@ -0,0 +1,419 @@
+import { useCallback } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import {
+  quotaFromStreamError
+} from "@arbidocs/sdk/browser";
+import { arbiQueryKeys } from "../hooks.js";
+import { useArbi } from "../useArbi.js";
+import { useArbiHost } from "../host/config.js";
+import { refreshDocuments } from "../documents/index.js";
+import { useArbiSessionStore } from "../session/index.js";
+import { invalidateConversationLists, patchConversationList } from "../conversation-list.js";
+import { MIN_QUEUED_MESSAGE_VISIBILITY_MS, queuedMessages } from "./run-state.js";
+import {
+  addAssistantMessageToCache,
+  addUserMessageToCache,
+  appendTokenToMessage,
+  applyFinalContextToMessage,
+  applyOutputItemToMessage,
+  commitFinalMessage,
+  completeQueuedUserMessageByContent,
+  ensureAssistantMessageLoading,
+  flushStreamingTokens,
+  getInterjectionText,
+  getThreadsQueryKey,
+  isMessageRunning,
+  markMessageAsFailed,
+  markNarrationSettled,
+  removeSettledNarration,
+  setUserInputRequest,
+  threadEndingAtContains,
+  updateUserMessageInCache,
+  updateUserMessageStateInCache
+} from "./conversation-cache.js";
+import { adoptNewChatDocument } from "./thread-binding.js";
+import { recordChatArtifact } from "./chat-artifacts.js";
+const MIN_NARRATION_DWELL_MS = 4e3;
+const FIRST_TOKEN_MEASURE = "arbi:send-message:first-token";
+function createStreamHandlers(ctx, params) {
+  const { queryClient, session, host } = ctx;
+  const { streamState, parentMessageId, parentId } = params;
+  let turnUserMessageId = null;
+  let queuedEntryRetired = false;
+  const isViewingConversation = () => session.getState().conversationId === streamState.conversationId;
+  const retireQueuedEntry = () => {
+    const clientId = streamState.queuedClientId;
+    if (!clientId || queuedEntryRetired) return;
+    queuedEntryRetired = true;
+    const entry = queuedMessages.find(session.getState().queuedMessages, clientId);
+    if (!entry) return;
+    const remainingVisibility = Math.max(
+      0,
+      MIN_QUEUED_MESSAGE_VISIBILITY_MS - (Date.now() - entry.createdAt)
+    );
+    if (remainingVisibility === 0) {
+      session.removeQueuedMessage(clientId);
+    } else {
+      setTimeout(() => session.removeQueuedMessage(clientId), remainingVisibility);
+    }
+  };
+  const handleUserMessage = (userMessage) => {
+    console.debug("[SSE] user_message:", userMessage.external_id, userMessage.status);
+    const serverConversationId = userMessage.conversation_ext_id;
+    if (serverConversationId && streamState.conversationId === "new") {
+      streamState.conversationId = serverConversationId;
+      session.moveConversation("new", serverConversationId);
+      const userExtId = ctx.userId();
+      const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+      patchConversationList(
+        queryClient,
+        streamState.workspaceId ?? session.getState().workspaceId,
+        (old) => old.some((c) => c.external_id === serverConversationId) ? old : [
+          {
+            external_id: serverConversationId,
+            title: null,
+            created_by_ext_id: userExtId,
+            updated_by_ext_id: null,
+            created_at: nowIso,
+            updated_at: nowIso,
+            is_shared: false,
+            message_count: 1,
+            last_message_status: "in_progress"
+          },
+          ...old
+        ]
+      );
+      adoptNewChatDocument(
+        session,
+        queryClient,
+        serverConversationId,
+        streamState.threadDocumentId ?? null
+      );
+    }
+    const { type: _type, ...messageData } = userMessage;
+    const userMsg = { ...messageData, isLoading: true };
+    if (userMessage.status === "queued") {
+      streamState.queuedUserMessageId = userMessage.external_id;
+    }
+    const updated = updateUserMessageInCache(queryClient, streamState.conversationId, userMsg);
+    if (!updated) {
+      addUserMessageToCache(queryClient, streamState.conversationId, userMsg, {
+        parentId,
+        parentMessageId,
+        currentParentMessageId: session.getState().cursor
+      });
+    }
+    turnUserMessageId = userMessage.external_id;
+    streamState.userMessageId = userMessage.external_id;
+    if (streamState.queuedContinuation) {
+      retireQueuedEntry();
+      const viewedLeaf = session.getState().cursor;
+      if (isViewingConversation() && viewedLeaf && threadEndingAtContains(
+        queryClient,
+        streamState.conversationId,
+        userMessage.external_id,
+        viewedLeaf
+      )) {
+        session.setCursor(userMessage.external_id);
+      }
+    }
+  };
+  const handleMessageQueued = (data) => {
+    if (!streamState.queuedContinuation && data.response_id && !streamState.assistantId) {
+      streamState.assistantId = data.response_id;
+      session.setStreamingAssistantId(streamState.conversationId, data.response_id);
+    }
+    streamState.queuedUserMessageId = data.user_message?.external_id ?? data.user_message_id ?? streamState.queuedUserMessageId;
+    if (streamState.queuedClientId) {
+      session.acknowledgeQueuedMessage(streamState.queuedClientId, streamState.queuedUserMessageId);
+    }
+  };
+  const handleStreamStart = (streamStart) => {
+    console.debug("[SSE] stream_start:", streamStart.assistant_message_ext_id);
+    streamState.hasStreamStarted = true;
+    if (streamState.queuedUserMessageId) {
+      updateUserMessageStateInCache(
+        queryClient,
+        streamState.conversationId,
+        streamState.queuedUserMessageId,
+        "completed",
+        false
+      );
+    }
+    if (streamState.queuedContinuation) {
+      retireQueuedEntry();
+      if (streamState.queueOwnerAssistantId) {
+        session.moveQueuedMessages(
+          streamState.queueOwnerAssistantId,
+          streamStart.assistant_message_ext_id
+        );
+      }
+    }
+    if (streamState.queuedContinuation) {
+      session.setConversationGenerating(
+        streamState.conversationId,
+        true,
+        streamState.abortController
+      );
+    }
+    streamState.assistantId = streamStart.assistant_message_ext_id;
+    session.setStreamingAssistantId(
+      streamState.conversationId,
+      streamStart.assistant_message_ext_id
+    );
+    const assistantMsg = {
+      role: "assistant",
+      content: "",
+      external_id: streamState.assistantId,
+      created_at: (/* @__PURE__ */ new Date()).toISOString(),
+      config_ext_id: null,
+      created_by_ext_id: "",
+      conversation_ext_id: streamState.conversationId,
+      tokens: 0,
+      status: "in_progress",
+      isLoading: true
+    };
+    const placed = addAssistantMessageToCache(
+      queryClient,
+      streamState.conversationId,
+      assistantMsg,
+      turnUserMessageId ?? streamState.queuedUserMessageId
+    );
+    if (!placed) {
+      const conversationId = streamState.conversationId;
+      const answerId = streamStart.assistant_message_ext_id;
+      void queryClient.invalidateQueries({ queryKey: getThreadsQueryKey(conversationId) }).then(() => {
+        if (streamState.assistantId === answerId && !streamState.isStopped() && isMessageRunning(queryClient, conversationId, answerId))
+          ensureAssistantMessageLoading(queryClient, conversationId, answerId);
+      });
+    }
+    void invalidateConversationLists(queryClient);
+    session.setCursor(streamState.assistantId);
+  };
+  let firstTokenSeen = false;
+  const markFirstToken = () => {
+    if (firstTokenSeen) return;
+    firstTokenSeen = true;
+    try {
+      performance.mark("arbi:send-message:first-token");
+      if (performance.getEntriesByName("arbi:send-message:start", "mark").length > 0)
+        performance.measure(
+          "arbi:send-message:first-token",
+          "arbi:send-message:start",
+          "arbi:send-message:first-token"
+        );
+    } catch {
+    }
+  };
+  const handleToken = (tokenContent) => {
+    if (!streamState.assistantId) return;
+    markFirstToken();
+    appendTokenToMessage(
+      queryClient,
+      streamState.conversationId,
+      streamState.assistantId,
+      tokenContent
+    );
+  };
+  const handleOutputTextDelta = (data) => {
+    if (!streamState.assistantId) return;
+    markFirstToken();
+    if (streamState.pivotedSinceProse) {
+      streamState.pivotedSinceProse = false;
+      markNarrationSettled(queryClient, streamState.conversationId, streamState.assistantId);
+    }
+    appendTokenToMessage(
+      queryClient,
+      streamState.conversationId,
+      streamState.assistantId,
+      data.delta
+    );
+  };
+  const resolveNotBefore = () => streamState.lastNarrationSettledAt === 0 ? 0 : streamState.lastNarrationSettledAt + MIN_NARRATION_DWELL_MS;
+  const handleMetadata = (metadata) => {
+    console.debug("[SSE] message_metadata:", metadata.external_id);
+    const serverAssistantId = metadata.external_id;
+    const viewedLeaf = session.getState().cursor;
+    const viewingNewerLeaf = !!viewedLeaf && threadEndingAtContains(queryClient, streamState.conversationId, viewedLeaf, serverAssistantId);
+    if (isViewingConversation() && !viewingNewerLeaf) {
+      session.setCursor(serverAssistantId);
+    }
+    if (metadata.suggested_query) {
+      session.setSuggestedQuery({
+        conversationExtId: streamState.conversationId,
+        text: metadata.suggested_query
+      });
+    }
+    if (streamState.assistantId) {
+      const { type: _type, ...messageData } = metadata;
+      commitFinalMessage(
+        queryClient,
+        streamState.conversationId,
+        streamState.assistantId,
+        messageData,
+        resolveNotBefore()
+      );
+    }
+  };
+  const handleOutputItemDone = (ev) => {
+    if (!streamState.assistantId) return;
+    const item = ev.item;
+    const interjection = getInterjectionText(item);
+    if (interjection) {
+      completeQueuedUserMessageByContent(queryClient, streamState.conversationId, interjection);
+      session.consumeQueuedMessage(streamState.assistantId, interjection);
+    }
+    const isAnswerMessage = item.arbi?.step === "answering" || item.arbi?.label === "Answered";
+    if (item.type === "message" && !isAnswerMessage && item.arbi?.label === "Narration") {
+      removeSettledNarration(
+        queryClient,
+        streamState.conversationId,
+        streamState.assistantId,
+        item.content
+      );
+    } else if (item.type === "message" && !isAnswerMessage) {
+      streamState.lastNarrationSettledAt = Date.now();
+    }
+    if (item.type === "function_call") {
+      streamState.pivotedSinceProse = true;
+      const tool = item.name || item.arbi?.detail?.[0]?.tool || "";
+      if (tool === "create_fact" || tool === "label_facts") {
+        streamState.factsTouched = true;
+      }
+    }
+    applyOutputItemToMessage(queryClient, streamState.conversationId, streamState.assistantId, ev);
+  };
+  const handleUserInputRequest = (request) => {
+    if (!streamState.assistantId) return;
+    setUserInputRequest(queryClient, streamState.conversationId, streamState.assistantId, request);
+  };
+  const handleProbeAnswer = (probe) => {
+    if (!streamState.assistantId) return;
+    session.setAgentProbeAnswer(streamState.assistantId, probe);
+  };
+  const handleDeferredInterjection = (data) => {
+    if (!data.message) return;
+    streamState.deferredInterjections.push(data.message);
+  };
+  const handleAgentControlState = (event) => {
+    if (!streamState.assistantId) return;
+    session.setAgentControlState(streamState.assistantId, event.state);
+  };
+  const handleMailDraft = (draft) => host.onMailDraft?.(draft);
+  const handleArtifact = (artifact) => {
+    console.info("[SSE] Received artifact event:", {
+      doc_ext_id: artifact.doc_ext_id,
+      title: artifact.title,
+      is_complete: artifact.is_complete
+    });
+    recordChatArtifact(artifact, streamState.conversationId);
+    host.onArtifact?.(artifact, streamState.conversationId);
+    if (artifact.is_complete) {
+      const documents = session.getState().conversationDocuments[streamState.conversationId] ?? [];
+      if (!documents.some((d) => d.docId === artifact.doc_ext_id))
+        session.setConversationDocuments(streamState.conversationId, [
+          ...documents,
+          { docId: artifact.doc_ext_id, isPinned: false }
+        ]);
+      if (artifact.mode === "html" || artifact.mode === "react")
+        session.setPinnedDocumentId(artifact.doc_ext_id);
+      ctx.refreshDocuments([artifact.doc_ext_id]).catch(() => {
+      });
+    }
+  };
+  const handleElapsedTime = (t) => {
+    session.setBackendElapsed(streamState.conversationId, t);
+  };
+  const handleContextUpdate = (context) => {
+    if (!streamState.assistantId) return;
+    applyFinalContextToMessage(
+      queryClient,
+      streamState.conversationId,
+      streamState.assistantId,
+      context
+    );
+  };
+  const handleError = (error) => {
+    if (streamState.isStopped()) return;
+    console.error("Stream error:", error);
+    if (streamState.queuedContinuation && !streamState.hasStreamStarted) {
+      streamState.queuedFailed = true;
+    }
+    const quota = quotaFromStreamError(error);
+    if (quota) host.onQuotaExceeded?.(quota);
+    if (error instanceof Error) return;
+    streamState.serverError = String(error);
+    if (streamState.assistantId) {
+      markMessageAsFailed(queryClient, streamState.conversationId, streamState.assistantId);
+    }
+  };
+  const handleComplete = () => {
+    console.debug("[SSE] Stream complete");
+    const generation = session.getState().generating[streamState.conversationId];
+    if (streamState.isStopped() || generation?.isGenerating === false) {
+      void queryClient.invalidateQueries({
+        queryKey: getThreadsQueryKey(streamState.conversationId)
+      });
+    }
+    flushStreamingTokens(queryClient);
+    if (streamState.assistantId) {
+      session.clearAgentControl(streamState.assistantId);
+    }
+    if (streamState.factsTouched) {
+      streamState.factsTouched = false;
+      queryClient.invalidateQueries({ queryKey: arbiQueryKeys.allFacts(), refetchType: "all" });
+      queryClient.invalidateQueries({ queryKey: arbiQueryKeys.allTags(), refetchType: "all" });
+    }
+  };
+  return {
+    onMessageQueued: handleMessageQueued,
+    onUserMessage: handleUserMessage,
+    onStreamStart: handleStreamStart,
+    onToken: handleToken,
+    onMetadata: handleMetadata,
+    onOutputItemDone: handleOutputItemDone,
+    onOutputTextDelta: handleOutputTextDelta,
+    onUserInputRequest: handleUserInputRequest,
+    onProbeAnswer: handleProbeAnswer,
+    onDeferredInterjection: handleDeferredInterjection,
+    onAgentControlState: handleAgentControlState,
+    onArtifact: handleArtifact,
+    onMailDraft: handleMailDraft,
+    onElapsedTime: handleElapsedTime,
+    onContextUpdate: handleContextUpdate,
+    onError: handleError,
+    onComplete: handleComplete
+  };
+}
+function useStreamHandlers() {
+  const queryClient = useQueryClient();
+  const session = useArbiSessionStore();
+  const config = useArbiHost();
+  const arbi = useArbi();
+  return useCallback(
+    (params) => createStreamHandlers(
+      {
+        queryClient,
+        session,
+        host: config.chat ?? {},
+        userId: () => {
+          try {
+            return arbi.user.identity()?.externalId ?? "";
+          } catch {
+            return "";
+          }
+        },
+        refreshDocuments: (ids) => refreshDocuments(queryClient, arbi, ids)
+      },
+      params
+    ),
+    [queryClient, session, config, arbi]
+  );
+}
+export {
+  FIRST_TOKEN_MEASURE,
+  MIN_NARRATION_DWELL_MS,
+  createStreamHandlers,
+  useStreamHandlers
+};
+//# sourceMappingURL=stream-handlers.js.map

package/dist/chat/stream-handlers.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/chat/stream-handlers.ts"],
+  "sourcesContent": ["/**\n * The chat engine's stream handlers: what each frame of an assistant turn does to the conversation\n * cache (`conversation-cache`), the session (`ArbiSessionState`: generation, cursor, queued\n * follow-ups, run control) and the host (`ArbiHostConfig.chat`: documents shown, mail drafts, used-up\n * quota). `createStreamHandlers` builds one set per stream, sharing that stream's mutable state\n * (its conversation id moves from `new` to the server's, its answer id arrives with\n * `response.created`).\n */\n\nimport { useCallback } from 'react'\nimport { useQueryClient, type QueryClient } from '@tanstack/react-query'\nimport {\n  quotaFromStreamError,\n  type AgentControlStateEvent,\n  type ArtifactEvent,\n  type ChatMessage as Message,\n  type ConversationResponse as Conversation,\n  type DeferredInterjectionEvent,\n  type MailDraftSSEEvent,\n  type MessageMetadataPayload,\n  type MessageQueuedEvent,\n  type OutputItemDone,\n  type ProbeAnswerEvent,\n  type SSEStreamStartData,\n  type TokenBudgetContext,\n  type UserInputRequestEvent,\n  type UserMessageEvent,\n} from '@arbidocs/sdk/browser'\nimport { arbiQueryKeys } from '../hooks'\nimport { useArbi } from '../useArbi'\nimport { useArbiHost } from '../host/config'\nimport { refreshDocuments } from '../documents'\nimport { useArbiSessionStore } from '../session'\nimport type { ArbiSessionStore } from '../session/store'\nimport { invalidateConversationLists, patchConversationList } from '../conversation-list'\nimport type { ArbiChatHost } from './host'\nimport { MIN_QUEUED_MESSAGE_VISIBILITY_MS, queuedMessages } from './run-state'\nimport {\n  addAssistantMessageToCache,\n  addUserMessageToCache,\n  appendTokenToMessage,\n  applyFinalContextToMessage,\n  applyOutputItemToMessage,\n  commitFinalMessage,\n  completeQueuedUserMessageByContent,\n  ensureAssistantMessageLoading,\n  flushStreamingTokens,\n  getInterjectionText,\n  getThreadsQueryKey,\n  isMessageRunning,\n  markMessageAsFailed,\n  markNarrationSettled,\n  removeSettledNarration,\n  setUserInputRequest,\n  threadEndingAtContains,\n  updateUserMessageInCache,\n  updateUserMessageStateInCache,\n} from './conversation-cache'\nimport { adoptNewChatDocument } from './thread-binding'\nimport { recordChatArtifact } from './chat-artifacts'\n\n/**\n * How long freshly-arrived narration must stay readable on screen before the\n * turn's one resolving commit is allowed to remove it.\n *\n * The whole point is that the user can READ what the agent narrated. If a\n * narration line settles a few hundred ms before the answer completes, resolving\n * immediately would flash that line away \u2014 the original complaint, in a new\n * costume. So the commit that hands the window to the answer waits until the\n * newest narration has had this long on screen.\n *\n * 4000 ms, set from measurement rather than taste. A live turn (see\n * answer-resolves.visual.spec) narrated \"Now I'll open and read the most relevant\n * document \u2014 test-case.pdf (PDF)\" \u2014 13 words, ~3.9 s of reading at a normal\n * 200-250 wpm \u2014 and the answer began almost immediately after it. At a 2500 ms\n * dwell that sentence measured 2446 ms on screen: not comfortably readable.\n *\n * Being generous is close to free: the answer streams in BELOW the narration\n * while it dwells, so nothing is hidden or delayed \u2014 and in the common case the\n * answer takes longer than this to stream, so the wait is already over when\n * `response.completed` lands and the delay is exactly zero.\n *\n * (Formerly MIN_PREAMBLE_DWELL_MS. Same 4 s, same purpose; renamed because there\n * is no \"preamble\" any more \u2014 nothing is folded out of the window mid-turn.)\n */\nexport const MIN_NARRATION_DWELL_MS = 4000\n\n/** The measure of the time to an answer's first token (from the send's `arbi:send-message:start`). */\nexport const FIRST_TOKEN_MEASURE = 'arbi:send-message:first-token'\n\nexport interface StreamHandlers {\n  onMessageQueued: (data: MessageQueuedEvent) => void\n  onUserMessage: (msg: UserMessageEvent) => void\n  onStreamStart: (msg: SSEStreamStartData) => void\n  onToken: (content: string) => void\n  onMetadata: (msg: MessageMetadataPayload) => void\n  onOutputItemDone: (ev: OutputItemDone) => void\n  onOutputTextDelta: (data: { item_id: string; delta: string }) => void\n  onUserInputRequest: (request: UserInputRequestEvent) => void\n  onProbeAnswer: (probe: ProbeAnswerEvent) => void\n  onDeferredInterjection: (data: DeferredInterjectionEvent) => void\n  onAgentControlState: (event: AgentControlStateEvent) => void\n  onArtifact: (artifact: ArtifactEvent) => void\n  onMailDraft: (draft: MailDraftSSEEvent) => void\n  onElapsedTime: (t: number) => void\n  onContextUpdate: (context: TokenBudgetContext) => void\n  onError: (error: unknown) => void\n  onComplete: () => void\n}\n\n/** The mutable state of one stream, shared by its handlers and the send that started it. */\nexport interface StreamState {\n  conversationId: string\n  /**\n   * The workspace the turn is in (captured when it started; the server's if it moved the turn to\n   * its thread's). A new conversation joins this workspace's list, whatever the session is on now.\n   */\n  workspaceId?: string | null\n  assistantId: string | null\n  /**\n   * Epoch ms when the newest narration block settled \u2014 the dwell clock's start. 0 while the turn\n   * has narrated nothing, which is the honest answer to \"how long must this stay readable\": no time\n   * at all.\n   */\n  lastNarrationSettledAt: number\n  /**\n   * The model has pivoted to a tool call and not yet resumed prose. The next prose therefore opens\n   * a new narration and closes the previous one \u2014 the only reliable paragraph boundary, since one\n   * sentence can span several message items.\n   */\n  pivotedSinceProse: boolean\n  /**\n   * Steering messages the backend deferred because they landed after the agent had committed to\n   * its answer. Collected during the stream and resubmitted as a new turn once it completes.\n   */\n  deferredInterjections: string[]\n  queuedContinuation: boolean\n  queuedUserMessageId: string | null\n  hasStreamStarted: boolean\n  /** The backend refused a queued follow-up before its turn started. */\n  queuedFailed: boolean\n  abortController: AbortController\n  /**\n   * The person pressed Stop on this turn. Stop cancels the run on the server first, and that can\n   * drop this connection before the local abort lands: a stopped turn must not then be recorded as\n   * a failed one.\n   */\n  isStopped: () => boolean\n  queueOwnerAssistantId: string | null\n  queuedClientId: string | null\n  /**\n   * A memory tool (`create_fact` / `label_facts`) ran this turn, so the Facts table and the\n   * workspace label vocabulary may have changed on the server. The tags query never auto-refetches\n   * (staleTime: Infinity), so both are refreshed when the turn completes rather than making the\n   * person reload the page to see a label the model just created.\n   */\n  factsTouched: boolean\n  /**\n   * The document the turn's thread is bound to, sent with it: a new chat's binding becomes the\n   * conversation's once the server names it.\n   */\n  threadDocumentId?: string | null\n  /** The server confirmed this turn's user message: it is stored, so the turn exists there. */\n  userMessageId?: string | null\n  /**\n   * The server's own failure report (`response.failed` / `arbi.error` / an HTTP error), as opposed\n   * to a dropped connection, which does not end the run on the server.\n   */\n  serverError?: string | null\n}\n\n/** What the handlers write to besides the cache. */\nexport interface StreamHandlerContext {\n  queryClient: QueryClient\n  session: ArbiSessionStore\n  host: ArbiChatHost\n  /** The signed-in user (the owner of a conversation this stream creates). */\n  userId: () => string\n  /** Re-read documents a turn wrote, into every documents cache. */\n  refreshDocuments: (docIds: string[]) => Promise<unknown>\n}\n\nexport interface StreamHandlerParams {\n  streamState: StreamState\n  /** The message the send continued from (the cursor when it was sent). */\n  parentMessageId: string | null\n  /** The message the turn replies to. */\n  parentId?: string | null\n}\n\n/** One stream's handlers. */\nexport function createStreamHandlers(\n  ctx: StreamHandlerContext,\n  params: StreamHandlerParams\n): StreamHandlers {\n  const { queryClient, session, host } = ctx\n  const { streamState, parentMessageId, parentId } = params\n\n  // The user message this turn answers, as the server placed it.\n  let turnUserMessageId: string | null = null\n  let queuedEntryRetired = false\n\n  const isViewingConversation = () =>\n    session.getState().conversationId === streamState.conversationId\n\n  /**\n   * Take this follow-up out of the agent bar's queue box: the server has confirmed it\n   * as a message of its own. The bubble in the thread shows it from here on. A follow-up\n   * the server answers this fast still stays readable for a moment.\n   */\n  const retireQueuedEntry = () => {\n    const clientId = streamState.queuedClientId\n    if (!clientId || queuedEntryRetired) return\n    queuedEntryRetired = true\n    const entry = queuedMessages.find(session.getState().queuedMessages, clientId)\n    if (!entry) return\n    const remainingVisibility = Math.max(\n      0,\n      MIN_QUEUED_MESSAGE_VISIBILITY_MS - (Date.now() - entry.createdAt)\n    )\n    if (remainingVisibility === 0) {\n      session.removeQueuedMessage(clientId)\n    } else {\n      setTimeout(() => session.removeQueuedMessage(clientId), remainingVisibility)\n    }\n  }\n\n  const handleUserMessage = (userMessage: UserMessageEvent) => {\n    console.debug('[SSE] user_message:', userMessage.external_id, userMessage.status)\n\n    const serverConversationId = userMessage.conversation_ext_id\n\n    // Handle conversation ID transition from 'new' to real conversation\n    if (serverConversationId && streamState.conversationId === 'new') {\n      streamState.conversationId = serverConversationId\n\n      // Its generation, documents, facts and tab move to the server id, and it stays open.\n      session.moveConversation('new', serverConversationId)\n\n      // Append a synthetic row to the conversations list so the sidebar /\n      // ConversationList shows it immediately. We initialize every field\n      // we know of so column readers (message count cell, last-message\n      // status cell, owner cell) don't render `undefined`. Fields the\n      // server may add later (generated title, message_count once the\n      // first assistant message lands) get corrected when the user opens\n      // the conversation (which fetches its detail) or by subsequent\n      // events that touch the same conversation.\n      const userExtId = ctx.userId()\n      const nowIso = new Date().toISOString()\n      patchConversationList(\n        queryClient,\n        streamState.workspaceId ?? session.getState().workspaceId,\n        (old) =>\n          old.some((c) => c.external_id === serverConversationId)\n            ? old\n            : [\n                {\n                  external_id: serverConversationId,\n                  title: null,\n                  created_by_ext_id: userExtId,\n                  updated_by_ext_id: null,\n                  created_at: nowIso,\n                  updated_at: nowIso,\n                  is_shared: false,\n                  message_count: 1,\n                  last_message_status: 'in_progress',\n                } as Conversation,\n                ...old,\n              ]\n      )\n      // The server bound it with this turn (a chat about a document): the row says so at once.\n      adoptNewChatDocument(\n        session,\n        queryClient,\n        serverConversationId,\n        streamState.threadDocumentId ?? null\n      )\n    }\n\n    // eslint-disable-next-line @typescript-eslint/no-unused-vars\n    const { type: _type, ...messageData } = userMessage\n    // Mark the freshly-arrived user message as in-flight (isLoading=true)\n    // so getOrphanedLastMessage suppresses the red \"Response Incomplete\"\n    // banner during the brief gap between this event and the assistant's\n    // stream_start. clearLoadingState (called when streams end / fail)\n    // clears it back. Backend-loaded historical messages don't get this\n    // flag, so genuine orphans from prior sessions still surface.\n    const userMsg: Message = { ...messageData, isLoading: true }\n\n    if (userMessage.status === 'queued') {\n      streamState.queuedUserMessageId = userMessage.external_id\n    }\n\n    // If the message was already added from arbi.message_queued (with status=queued),\n    // update it in-place (e.g., status \u2192 completed) instead of duplicating.\n    const updated = updateUserMessageInCache(queryClient, streamState.conversationId, userMsg)\n    if (!updated) {\n      // Placed under the server's parent (userMessage.parent_message_ext_id) when the\n      // cache has it, so queued follow-ups line up one after another.\n      addUserMessageToCache(queryClient, streamState.conversationId, userMsg, {\n        parentId,\n        parentMessageId,\n        currentParentMessageId: session.getState().cursor,\n      })\n    }\n    turnUserMessageId = userMessage.external_id\n    streamState.userMessageId = userMessage.external_id\n\n    if (streamState.queuedContinuation) {\n      retireQueuedEntry()\n      // Follow the thread to its newest turn: when the follow-up extends the line being\n      // viewed, view the line that now ends at it, not the sibling it would otherwise be.\n      const viewedLeaf = session.getState().cursor\n      if (\n        isViewingConversation() &&\n        viewedLeaf &&\n        threadEndingAtContains(\n          queryClient,\n          streamState.conversationId,\n          userMessage.external_id,\n          viewedLeaf\n        )\n      ) {\n        session.setCursor(userMessage.external_id)\n      }\n    }\n  }\n\n  const handleMessageQueued = (data: MessageQueuedEvent) => {\n    // The queued acknowledgement precedes response.created but already has\n    // the canonical assistant response ID. Seed the generation state now so\n    // the docked agent bar appears with the user message instead of popping\n    // in later. A queued continuation belongs to the existing parent bar, so\n    // never replace its ID with the acknowledgement's throwaway response ID.\n    if (!streamState.queuedContinuation && data.response_id && !streamState.assistantId) {\n      streamState.assistantId = data.response_id\n      session.setStreamingAssistantId(streamState.conversationId, data.response_id)\n    }\n    streamState.queuedUserMessageId =\n      data.user_message?.external_id ?? data.user_message_id ?? streamState.queuedUserMessageId\n    if (streamState.queuedClientId) {\n      session.acknowledgeQueuedMessage(streamState.queuedClientId, streamState.queuedUserMessageId)\n    }\n  }\n\n  const handleStreamStart = (streamStart: SSEStreamStartData) => {\n    console.debug('[SSE] stream_start:', streamStart.assistant_message_ext_id)\n\n    streamState.hasStreamStarted = true\n    if (streamState.queuedUserMessageId) {\n      updateUserMessageStateInCache(\n        queryClient,\n        streamState.conversationId,\n        streamState.queuedUserMessageId,\n        'completed',\n        false\n      )\n    }\n    if (streamState.queuedContinuation) {\n      retireQueuedEntry()\n      // Follow-ups still waiting were queued on the turn that just finished; they now\n      // wait on this one, so show them in its bar.\n      if (streamState.queueOwnerAssistantId) {\n        session.moveQueuedMessages(\n          streamState.queueOwnerAssistantId,\n          streamStart.assistant_message_ext_id\n        )\n      }\n    }\n\n    if (streamState.queuedContinuation) {\n      session.setConversationGenerating(\n        streamState.conversationId,\n        true,\n        streamState.abortController\n      )\n    }\n\n    streamState.assistantId = streamStart.assistant_message_ext_id\n\n    // The session holds the answer's id, so interjections and Stop can name it.\n    session.setStreamingAssistantId(\n      streamState.conversationId,\n      streamStart.assistant_message_ext_id\n    )\n\n    const assistantMsg: Message = {\n      role: 'assistant',\n      content: '',\n      external_id: streamState.assistantId,\n      created_at: new Date().toISOString(),\n      config_ext_id: null,\n      created_by_ext_id: '',\n      conversation_ext_id: streamState.conversationId,\n      tokens: 0,\n      status: 'in_progress',\n      isLoading: true,\n    }\n\n    const placed = addAssistantMessageToCache(\n      queryClient,\n      streamState.conversationId,\n      assistantMsg,\n      turnUserMessageId ?? streamState.queuedUserMessageId\n    )\n    if (!placed) {\n      // The answer's user message is not in the cache, so the answer could not be placed\n      // after it. Re-read the thread for the server's order, then mark the row as streaming\n      // again (the refetched row has no local loading flag).\n      const conversationId = streamState.conversationId\n      const answerId = streamStart.assistant_message_ext_id\n      void queryClient\n        .invalidateQueries({ queryKey: getThreadsQueryKey(conversationId) })\n        .then(() => {\n          if (\n            streamState.assistantId === answerId &&\n            !streamState.isStopped() &&\n            isMessageRunning(queryClient, conversationId, answerId)\n          )\n            ensureAssistantMessageLoading(queryClient, conversationId, answerId)\n        })\n    }\n\n    // The turn's user and assistant messages are stored now, so the list's Messages count\n    // must include them while the answer generates (it is re-read again on completion).\n    void invalidateConversationLists(queryClient)\n\n    // The backend persists the assistant message at response.created,\n    // so this ID is permanent and safe to use for chaining.\n    session.setCursor(streamState.assistantId)\n  }\n\n  let firstTokenSeen = false\n  const markFirstToken = () => {\n    if (firstTokenSeen) return\n    firstTokenSeen = true\n    // Time to first token, from the send's own mark (the host reports the measure).\n    try {\n      performance.mark('arbi:send-message:first-token')\n      if (performance.getEntriesByName('arbi:send-message:start', 'mark').length > 0)\n        performance.measure(\n          'arbi:send-message:first-token',\n          'arbi:send-message:start',\n          'arbi:send-message:first-token'\n        )\n    } catch {\n      // No performance timeline here: nothing to measure.\n    }\n  }\n\n  // Raw tokens (non-agent LLM / fallback) \u2014 no item id. Stream straight through.\n  const handleToken = (tokenContent: string) => {\n    if (!streamState.assistantId) return\n    markFirstToken()\n    appendTokenToMessage(\n      queryClient,\n      streamState.conversationId,\n      streamState.assistantId,\n      tokenContent\n    )\n  }\n\n  // A message output_item streaming its text (#2075). Every delta is APPENDED,\n  // rendered provisionally (faded \u2014 see Message.tsx), until `response.completed`\n  // says which of it was the answer. The one removal mid-turn is an item the\n  // server settles as Narration (see handleOutputItemDone).\n  //\n  // There is deliberately no attempt to spot the answer mid-stream. The\n  // previous design guessed (\"a new text block, once a tool call has settled,\n  // is the answer\") and was wrong by construction: a turn may make any number\n  // of tool calls, so every intermediate block after the first tool call was\n  // mis-called. It survived only because the correcting event usually landed\n  // inside the dwell \u2014 a race, not correctness.\n  //\n  // Deltas are appended VERBATIM, with no separator injected at item\n  // boundaries. An item boundary is not an utterance boundary: the backend\n  // settles the open narration item whenever it needs to emit a tool event,\n  // which routinely splits one sentence across several items. A real captured\n  // run shows the three items \"I've\" / \" started two background research tasks\n  // \u2026for both Apple and\" / \" Microsoft. Let me collect those results now.\\n\\n\" \u2014\n  // one sentence in three parts. Injecting a blank line per item would break\n  // that into three mangled paragraphs. The model supplies its own line breaks\n  // (note the trailing \"\\n\\n\" ending the utterance above), so plain appending\n  // reproduces exactly the layout it intended: one line per utterance.\n  const handleOutputTextDelta = (data: { item_id: string; delta: string }) => {\n    if (!streamState.assistantId) return\n    markFirstToken()\n    // Prose resuming after a tool call is a NEW narration, not a continuation\n    // of the one before it. Close the previous one here rather than when it\n    // settled: only now is it known that the model went away and came back,\n    // which is what makes this a paragraph boundary and what makes the prose\n    // above it superseded.\n    if (streamState.pivotedSinceProse) {\n      streamState.pivotedSinceProse = false\n      markNarrationSettled(queryClient, streamState.conversationId, streamState.assistantId)\n    }\n    appendTokenToMessage(\n      queryClient,\n      streamState.conversationId,\n      streamState.assistantId,\n      data.delta\n    )\n  }\n\n  /**\n   * The earliest moment the turn may resolve: a full dwell after the newest\n   * narration settled. Zero when the turn narrated nothing \u2014 there is no prose\n   * to protect, so a one-shot answer resolves the instant it completes.\n   */\n  const resolveNotBefore = () =>\n    streamState.lastNarrationSettledAt === 0\n      ? 0\n      : streamState.lastNarrationSettledAt + MIN_NARRATION_DWELL_MS\n\n  const handleMetadata = (metadata: MessageMetadataPayload) => {\n    console.debug('[SSE] message_metadata:', metadata.external_id)\n\n    const serverAssistantId = metadata.external_id\n\n    // Update parentMessageId with the server-confirmed ID, but only if the user\n    // is still viewing this conversation. Without this guard, metadata arriving from\n    // a background stream would overwrite the active tab's parentMessageId.\n    // A follow-up queued behind this turn may already extend the thread past it: keep\n    // viewing that newer leaf rather than stepping back to this answer.\n    const viewedLeaf = session.getState().cursor\n    const viewingNewerLeaf =\n      !!viewedLeaf &&\n      threadEndingAtContains(queryClient, streamState.conversationId, viewedLeaf, serverAssistantId)\n    if (isViewingConversation() && !viewingNewerLeaf) {\n      session.setCursor(serverAssistantId)\n    }\n\n    // Backend-suggested follow-up (SUGGESTED_QUERIES config) \u2014 stashed\n    // keyed to its conversation; the composer offers it as a chip.\n    if (metadata.suggested_query) {\n      session.setSuggestedQuery({\n        conversationExtId: streamState.conversationId,\n        text: metadata.suggested_query,\n      })\n    }\n\n    if (streamState.assistantId) {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      const { type: _type, ...messageData } = metadata\n\n      // `response.completed` is the ONLY place the main window resolves, and it\n      // resolves in ONE commit: metadata.content is the authoritative answer\n      // (the backend's _answer_final persists the answer alone, no narration),\n      // it carries the citation offsets computed against that exact string, and\n      // it clears `isLoading` so the body stops rendering provisionally.\n      //\n      // Doing all three together is the fix for the jitter: the answer used to\n      // re-render un-faded with its footnotes, and the narration used to leave\n      // the body on a separate timer, so the window reflowed twice in quick\n      // succession. One commit, one reflow.\n      commitFinalMessage(\n        queryClient,\n        streamState.conversationId,\n        streamState.assistantId,\n        messageData,\n        resolveNotBefore()\n      )\n    }\n  }\n\n  // A settled output_item (#2075). Every item folds into the trace via the\n  // reducer \u2014 including narration, which is why the body can drop narration's\n  // text without losing it. Narration is the only text that leaves the body\n  // before `response.completed`.\n  const handleOutputItemDone = (ev: OutputItemDone) => {\n    if (!streamState.assistantId) return\n    const item = ev.item as {\n      type?: string\n      name?: string\n      arbi?: { label?: string; step?: string; detail?: Array<{ tool?: string }> }\n      summary?: unknown\n      content?: unknown\n    }\n    // An interjection reasoning item settles the queued prompts it steered in.\n    const interjection = getInterjectionText(item)\n    if (interjection) {\n      completeQueuedUserMessageByContent(queryClient, streamState.conversationId, interjection)\n      session.consumeQueuedMessage(streamState.assistantId, interjection)\n    }\n    // A narration message settles the instant the model pivots to a tool call \u2014\n    // which is the moment its prose is complete on screen, and so the moment its\n    // reading window starts. The answer's own item is excluded: the answer is\n    // what stays, so it needs no protection from being removed.\n    //\n    // Timing off the settled ITEM (not off deltas) is what keeps a normal turn\n    // free of any added delay. Deltas cannot distinguish narration from the\n    // answer, so a delta clock would restart on the answer's own last token and\n    // make every single turn wait out the full dwell.\n    const isAnswerMessage = item.arbi?.step === 'answering' || item.arbi?.label === 'Answered'\n    // An item the server settles as Narration (a working note, or a first draft the\n    // grounding guard re-rolled into a tool call) is not the answer: it leaves the body now\n    // and lives on in Show steps. Left in place it read as the finished answer. Having left,\n    // it needs no reading window, so it does not hold the resolution either.\n    if (item.type === 'message' && !isAnswerMessage && item.arbi?.label === 'Narration') {\n      removeSettledNarration(\n        queryClient,\n        streamState.conversationId,\n        streamState.assistantId,\n        item.content\n      )\n    } else if (item.type === 'message' && !isAnswerMessage) {\n      streamState.lastNarrationSettledAt = Date.now()\n    }\n    // A message item ending is NOT a paragraph ending. The backend splits one\n    // sentence across several items \u2014 \"I've\" / \" started two background\n    // research tasks\u2026\" / \" Microsoft. Let me collect those results now.\" \u2014\n    // so breaking at every settle would shred prose mid-sentence.\n    //\n    // What genuinely ends a narration is the model PIVOTING to a tool call\n    // and coming back. Record the pivot; the next prose acts on it.\n    if (item.type === 'function_call') {\n      streamState.pivotedSinceProse = true\n      // A memory tool changed facts / labels server-side. Note it now and\n      // refresh those views at completion, by when the tool has executed and\n      // committed (invalidating on the call itself would race the DB write).\n      // The tool name rides on `item.name`; fall back to the display detail.\n      const tool = item.name || item.arbi?.detail?.[0]?.tool || ''\n      if (tool === 'create_fact' || tool === 'label_facts') {\n        streamState.factsTouched = true\n      }\n    }\n\n    applyOutputItemToMessage(queryClient, streamState.conversationId, streamState.assistantId, ev)\n  }\n\n  const handleUserInputRequest = (request: UserInputRequestEvent) => {\n    if (!streamState.assistantId) return\n    setUserInputRequest(queryClient, streamState.conversationId, streamState.assistantId, request)\n  }\n\n  const handleProbeAnswer = (probe: ProbeAnswerEvent) => {\n    if (!streamState.assistantId) return\n    // Out-of-band status answer \u2014 a transient note on the streaming turn.\n    session.setAgentProbeAnswer(streamState.assistantId, probe)\n  }\n\n  const handleDeferredInterjection = (data: DeferredInterjectionEvent) => {\n    // Steering that reached the agent after it had committed to its answer.\n    // Too late to fold into this turn \u2014 collect it and let the send\n    // resubmit it as a new turn once the current turn finishes (submitting\n    // now would race the in-flight stream).\n    if (!data.message) return\n    streamState.deferredInterjections.push(data.message)\n  }\n\n  const handleAgentControlState = (event: AgentControlStateEvent) => {\n    if (!streamState.assistantId) return\n    // Server-confirmed pause/resume state overrides the optimistic client state.\n    session.setAgentControlState(streamState.assistantId, event.state)\n  }\n\n  // ARBI saved an email draft (a reply it was asked for): the host opens it beside this chat.\n  const handleMailDraft = (draft: MailDraftSSEEvent) => host.onMailDraft?.(draft)\n\n  const handleArtifact = (artifact: ArtifactEvent) => {\n    console.info('[SSE] Received artifact event:', {\n      doc_ext_id: artifact.doc_ext_id,\n      title: artifact.title,\n      is_complete: artifact.is_complete,\n    })\n\n    // Kept for every surface that shows the document as it is written; the host shows it.\n    recordChatArtifact(artifact, streamState.conversationId)\n    host.onArtifact?.(artifact, streamState.conversationId)\n\n    // Auto-pin a freshly created artifact as this conversation's full-context\n    // document once it's done streaming \u2014 \"make it bigger\", \"change the\n    // color\" means the thing just shown, not whatever was pinned before.\n    // Deliberately scoped to artifact CREATION, not general document\n    // viewing: opening an unrelated doc to check something must not\n    // silently redirect full-context to it (that's exactly the footgun the\n    // existing manual-pin-only design avoids). The pin button\n    // (the context chip's PinnedDocChip) remains the cancel/override \u2014 same\n    // setPinnedDocumentId it already uses, so unpinning or pinning\n    // something else works exactly as it does today. the conversation's documents\n    // are required too: selectFullContextDocument only honours a pin that's\n    // also in the conversation's document list (`selectFullContextDocument`),\n    // and a just-generated artifact was never added there.\n    if (artifact.is_complete) {\n      const documents = session.getState().conversationDocuments[streamState.conversationId] ?? []\n      if (!documents.some((d) => d.docId === artifact.doc_ext_id))\n        session.setConversationDocuments(streamState.conversationId, [\n          ...documents,\n          { docId: artifact.doc_ext_id, isPinned: false },\n        ])\n      // A document draft is a Word document (stored as DOCX): the assistant drafts in it through\n      // the open document (read on demand, tracked changes), so it is never pinned \u2014 a pin\n      // would resend the whole document every turn. Only html/react artifacts, whose source\n      // the assistant edits directly, are pinned.\n      if (artifact.mode === 'html' || artifact.mode === 'react')\n        session.setPinnedDocumentId(artifact.doc_ext_id)\n      // The pin only WORKS once the doc is in the workspace-documents\n      // cache: the composer's pill lookup and selectFullContextDocument\n      // both intersect against it, and a just-generated artifact isn't\n      // there until some later refetch. Without this, the auto-pin was\n      // set but invisible AND dropped from the next send \u2014 same append\n      // the upload path does.\n      ctx.refreshDocuments([artifact.doc_ext_id]).catch(() => {})\n    }\n  }\n\n  const handleElapsedTime = (t: number) => {\n    session.setBackendElapsed(streamState.conversationId, t)\n  }\n\n  const handleContextUpdate = (context: TokenBudgetContext) => {\n    if (!streamState.assistantId) return\n    applyFinalContextToMessage(\n      queryClient,\n      streamState.conversationId,\n      streamState.assistantId,\n      context\n    )\n  }\n\n  const handleError = (error: unknown) => {\n    // A stop ends the stream as well; the stop itself settles the turn.\n    if (streamState.isStopped()) return\n    console.error('Stream error:', error)\n    if (streamState.queuedContinuation && !streamState.hasStreamStarted) {\n      streamState.queuedFailed = true\n    }\n    // If the stream error carries LiteLLM's ExceededBudget payload, open\n    // the upgrade modal proactively. The \"Response Failed\" inline alert\n    // still appears (driven by message status), but the user gets the\n    // popup explaining why and offering to upgrade.\n    const quota = quotaFromStreamError(error)\n    if (quota) host.onQuotaExceeded?.(quota)\n    // A thrown error is the connection, not the run: the run goes on on the server, and the\n    // send re-reads the thread to attach to it or show how it ended (see useMessageActions).\n    // Marking it failed here offered Retry, which deleted the question under a live answer.\n    if (error instanceof Error) return\n    streamState.serverError = String(error)\n    // The server failed the answer: mark it failed so the UI shows the error state\n    if (streamState.assistantId) {\n      markMessageAsFailed(queryClient, streamState.conversationId, streamState.assistantId)\n    }\n  }\n\n  const handleComplete = () => {\n    console.debug('[SSE] Stream complete')\n    // A Stop can end the run with a completed frame that carries only the partial answer,\n    // either before its abort lands or with no local stream to abort. That frame's status\n    // is not the run's: re-read the thread so the message shows how the server ended it.\n    const generation = session.getState().generating[streamState.conversationId]\n    if (streamState.isStopped() || generation?.isGenerating === false) {\n      void queryClient.invalidateQueries({\n        queryKey: getThreadsQueryKey(streamState.conversationId),\n      })\n    }\n    // Ensure any rAF-buffered tokens are committed before the consumer\n    // considers the stream finished. Without this, final deltas that\n    // arrived in the same frame as the complete event would be dropped.\n    flushStreamingTokens(queryClient)\n    // Turn is over \u2014 drop its transient control state (pause/probe).\n    if (streamState.assistantId) {\n      session.clearAgentControl(streamState.assistantId)\n    }\n    // The model added a fact or a new label this turn: refresh the Facts\n    // list and the workspace label vocabulary so they appear without a page\n    // reload. `refetchType: 'all'` updates the cache even when the Facts view\n    // is not currently mounted (the tags query has staleTime: Infinity and\n    // would otherwise never pick the new label up on its own).\n    if (streamState.factsTouched) {\n      streamState.factsTouched = false\n      queryClient.invalidateQueries({ queryKey: arbiQueryKeys.allFacts(), refetchType: 'all' })\n      queryClient.invalidateQueries({ queryKey: arbiQueryKeys.allTags(), refetchType: 'all' })\n    }\n  }\n\n  return {\n    onMessageQueued: handleMessageQueued,\n    onUserMessage: handleUserMessage,\n    onStreamStart: handleStreamStart,\n    onToken: handleToken,\n    onMetadata: handleMetadata,\n    onOutputItemDone: handleOutputItemDone,\n    onOutputTextDelta: handleOutputTextDelta,\n    onUserInputRequest: handleUserInputRequest,\n    onProbeAnswer: handleProbeAnswer,\n    onDeferredInterjection: handleDeferredInterjection,\n    onAgentControlState: handleAgentControlState,\n    onArtifact: handleArtifact,\n    onMailDraft: handleMailDraft,\n    onElapsedTime: handleElapsedTime,\n    onContextUpdate: handleContextUpdate,\n    onError: handleError,\n    onComplete: handleComplete,\n  }\n}\n\n/** The stream handlers of this host's chat (its cache, session and chat host). */\nexport function useStreamHandlers(): (params: StreamHandlerParams) => StreamHandlers {\n  const queryClient = useQueryClient()\n  const session = useArbiSessionStore()\n  const config = useArbiHost()\n  const arbi = useArbi()\n  return useCallback(\n    (params: StreamHandlerParams) =>\n      createStreamHandlers(\n        {\n          queryClient,\n          session,\n          host: config.chat ?? {},\n          userId: () => {\n            try {\n              return arbi.user.identity()?.externalId ?? ''\n            } catch {\n              return ''\n            }\n          },\n          refreshDocuments: (ids) => refreshDocuments(queryClient, arbi, ids),\n        },\n        params\n      ),\n    [queryClient, session, config, arbi]\n  )\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/chat/thread-binding.js

@@ -0,0 +1,76 @@
+import { findConversation, patchConversation } from "../conversation-list.js";
+import { getThreadsQueryKey } from "./conversation-cache.js";
+import {
+  UNBOUND,
+  bindingOfRow,
+  forgetLegacyThreadDocuments,
+  readLegacyThreadDocuments
+} from "./thread-document.js";
+function threadBinding(queryClient, conversationId) {
+  if (!conversationId) return UNBOUND;
+  const row = findConversation(queryClient, conversationId);
+  if (row) return bindingOfRow(row);
+  const threads = queryClient.getQueryData(getThreadsQueryKey(conversationId));
+  return bindingOfRow(threads ? { external_id: conversationId, ...threads } : null);
+}
+function boundDocumentOf(queryClient, state) {
+  return state.conversationId ? threadBinding(queryClient, state.conversationId).documentId : state.newChatDocumentId;
+}
+function cacheThreadBinding(queryClient, conversationId, binding) {
+  const fields = {
+    bound_document_ext_id: binding.documentId,
+    bound_document_unavailable: binding.unavailable
+  };
+  patchConversation(queryClient, conversationId, fields);
+  queryClient.setQueryData(
+    getThreadsQueryKey(conversationId),
+    (old) => old ? { ...old, ...fields } : old
+  );
+}
+async function bindThreadDocument(arbi, queryClient, conversationId, documentId) {
+  const before = threadBinding(queryClient, conversationId);
+  if (before.documentId === documentId && !before.unavailable) return;
+  cacheThreadBinding(queryClient, conversationId, { documentId, unavailable: false });
+  try {
+    const saved = await arbi.conversations.update(conversationId, {
+      bound_document_ext_id: documentId
+    });
+    patchConversation(queryClient, conversationId, saved);
+    cacheThreadBinding(queryClient, conversationId, bindingOfRow(saved));
+  } catch (error) {
+    cacheThreadBinding(queryClient, conversationId, before);
+    throw error;
+  }
+}
+function adoptNewChatDocument(session, queryClient, conversationId, documentId = session.getState().newChatDocumentId) {
+  if (!documentId) return;
+  cacheThreadBinding(queryClient, conversationId, { documentId, unavailable: false });
+  if (session.getState().newChatDocumentId === documentId) session.setNewChatDocumentId(null);
+}
+async function migrateLegacyThreadDocuments(arbi, queryClient, conversations) {
+  const legacy = readLegacyThreadDocuments();
+  const listed = conversations.filter(
+    (c) => c.external_id in legacy && "bound_document_unavailable" in c
+  );
+  if (listed.length === 0) return;
+  await Promise.all(
+    listed.map(async (row) => {
+      const server = bindingOfRow(row);
+      if (server.documentId || server.unavailable) return;
+      try {
+        await bindThreadDocument(arbi, queryClient, row.external_id, legacy[row.external_id]);
+      } catch {
+      }
+    })
+  );
+  forgetLegacyThreadDocuments(listed.map((c) => c.external_id));
+}
+export {
+  adoptNewChatDocument,
+  bindThreadDocument,
+  boundDocumentOf,
+  cacheThreadBinding,
+  migrateLegacyThreadDocuments,
+  threadBinding
+};
+//# sourceMappingURL=thread-binding.js.map

package/dist/chat/thread-binding.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/chat/thread-binding.ts"],
+  "sourcesContent": ["/**\n * A conversation's bound document in the query cache, and the writes that change it on the server.\n *\n * The server holds the binding (`./thread-document`); the cache is its mirror: the conversation's\n * row in the workspace's list (`bound_document_ext_id`, `bound_document_unavailable`), else its\n * threads response (a thread opened from a link, not listed yet). An attach or unbind shows at once\n * and is written with `PATCH /v1/conversation/{id}`; a failure puts the cache back. Another\n * member's or device's change arrives as `conversation.document_binding_changed`\n * (`./conversation-events`), which re-reads the conversation under this reader's access.\n */\n\nimport type { QueryClient } from '@tanstack/react-query'\nimport type { Arbi, ConversationResponse, ThreadsResponse } from '@arbidocs/sdk/browser'\nimport { findConversation, patchConversation } from '../conversation-list'\nimport { getThreadsQueryKey } from './conversation-cache'\nimport {\n  UNBOUND,\n  bindingOfRow,\n  forgetLegacyThreadDocuments,\n  readLegacyThreadDocuments,\n  type ThreadBinding,\n} from './thread-document'\n\n/** What this module needs of the session store (structural, like the rest of the chat engine). */\ninterface NewChatSession {\n  getState(): { conversationId: string | null; newChatDocumentId: string | null }\n  setNewChatDocumentId(documentId: string | null): void\n}\n\n/** A saved conversation's binding, from the cache (its list row, else its threads). */\nexport function threadBinding(\n  queryClient: QueryClient,\n  conversationId: string | null | undefined\n): ThreadBinding {\n  if (!conversationId) return UNBOUND\n  const row = findConversation(queryClient, conversationId)\n  if (row) return bindingOfRow(row)\n  const threads = queryClient.getQueryData<ThreadsResponse>(getThreadsQueryKey(conversationId))\n  return bindingOfRow(threads ? { external_id: conversationId, ...threads } : null)\n}\n\n/** The document the open conversation is bound to: its saved binding, or the new chat's. */\nexport function boundDocumentOf(\n  queryClient: QueryClient,\n  state: ReturnType<NewChatSession['getState']>\n): string | null {\n  return state.conversationId\n    ? threadBinding(queryClient, state.conversationId).documentId\n    : state.newChatDocumentId\n}\n\n/** Put a binding in the cache (the list rows and the threads response that hold the conversation). */\nexport function cacheThreadBinding(\n  queryClient: QueryClient,\n  conversationId: string,\n  binding: ThreadBinding\n): void {\n  const fields = {\n    bound_document_ext_id: binding.documentId,\n    bound_document_unavailable: binding.unavailable,\n  }\n  patchConversation(queryClient, conversationId, fields)\n  queryClient.setQueryData<ThreadsResponse>(getThreadsQueryKey(conversationId), (old) =>\n    old ? { ...old, ...fields } : old\n  )\n}\n\n/**\n * Bind a saved conversation to a document, or (null) unbind it: shown at once, written to the\n * server. Rejects (with the cache put back) when the server refuses: a document of another\n * workspace, or one the caller cannot read.\n */\nexport async function bindThreadDocument(\n  arbi: Pick<Arbi, 'conversations'>,\n  queryClient: QueryClient,\n  conversationId: string,\n  documentId: string | null\n): Promise<void> {\n  const before = threadBinding(queryClient, conversationId)\n  if (before.documentId === documentId && !before.unavailable) return\n  cacheThreadBinding(queryClient, conversationId, { documentId, unavailable: false })\n  try {\n    const saved: ConversationResponse = await arbi.conversations.update(conversationId, {\n      bound_document_ext_id: documentId,\n    })\n    patchConversation(queryClient, conversationId, saved)\n    cacheThreadBinding(queryClient, conversationId, bindingOfRow(saved))\n  } catch (error) {\n    cacheThreadBinding(queryClient, conversationId, before)\n    throw error\n  }\n}\n\n/**\n * A new chat got its server id: the document its first turn was sent with is now the\n * conversation's (the server bound it with that turn). Call it once the conversation's row is in\n * the list; `documentId` defaults to the session's new-chat binding.\n */\nexport function adoptNewChatDocument(\n  session: NewChatSession,\n  queryClient: QueryClient,\n  conversationId: string,\n  documentId: string | null = session.getState().newChatDocumentId\n): void {\n  if (!documentId) return\n  cacheThreadBinding(queryClient, conversationId, { documentId, unavailable: false })\n  if (session.getState().newChatDocumentId === documentId) session.setNewChatDocumentId(null)\n}\n\n/**\n * Move the bindings this browser kept locally (before the server held them) to the server, for\n * the conversations of a workspace's list, then forget them here. A conversation the server\n * already binds keeps its server binding. Runs once per list it is given; the key is removed when\n * the last kept binding is moved.\n */\nexport async function migrateLegacyThreadDocuments(\n  arbi: Pick<Arbi, 'conversations'>,\n  queryClient: QueryClient,\n  conversations: readonly ConversationResponse[]\n): Promise<void> {\n  const legacy = readLegacyThreadDocuments()\n  // Only rows from a server that holds bindings (they carry the field): never lose a kept one.\n  const listed = conversations.filter(\n    (c) => c.external_id in legacy && 'bound_document_unavailable' in c\n  )\n  if (listed.length === 0) return\n  await Promise.all(\n    listed.map(async (row) => {\n      const server = bindingOfRow(row)\n      if (server.documentId || server.unavailable) return\n      try {\n        await bindThreadDocument(arbi, queryClient, row.external_id, legacy[row.external_id])\n      } catch {\n        // The document is gone or not readable any more: nothing to keep.\n      }\n    })\n  )\n  forgetLegacyThreadDocuments(listed.map((c) => c.external_id))\n}\n"],
+  "mappings": "AAaA,SAAS,kBAAkB,yBAAyB;AACpD,SAAS,0BAA0B;AACnC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AASA,SAAS,cACd,aACA,gBACe;AACf,MAAI,CAAC,eAAgB,QAAO;AAC5B,QAAM,MAAM,iBAAiB,aAAa,cAAc;AACxD,MAAI,IAAK,QAAO,aAAa,GAAG;AAChC,QAAM,UAAU,YAAY,aAA8B,mBAAmB,cAAc,CAAC;AAC5F,SAAO,aAAa,UAAU,EAAE,aAAa,gBAAgB,GAAG,QAAQ,IAAI,IAAI;AAClF;AAGO,SAAS,gBACd,aACA,OACe;AACf,SAAO,MAAM,iBACT,cAAc,aAAa,MAAM,cAAc,EAAE,aACjD,MAAM;AACZ;AAGO,SAAS,mBACd,aACA,gBACA,SACM;AACN,QAAM,SAAS;AAAA,IACb,uBAAuB,QAAQ;AAAA,IAC/B,4BAA4B,QAAQ;AAAA,EACtC;AACA,oBAAkB,aAAa,gBAAgB,MAAM;AACrD,cAAY;AAAA,IAA8B,mBAAmB,cAAc;AAAA,IAAG,CAAC,QAC7E,MAAM,EAAE,GAAG,KAAK,GAAG,OAAO,IAAI;AAAA,EAChC;AACF;AAOA,eAAsB,mBACpB,MACA,aACA,gBACA,YACe;AACf,QAAM,SAAS,cAAc,aAAa,cAAc;AACxD,MAAI,OAAO,eAAe,cAAc,CAAC,OAAO,YAAa;AAC7D,qBAAmB,aAAa,gBAAgB,EAAE,YAAY,aAAa,MAAM,CAAC;AAClF,MAAI;AACF,UAAM,QAA8B,MAAM,KAAK,cAAc,OAAO,gBAAgB;AAAA,MAClF,uBAAuB;AAAA,IACzB,CAAC;AACD,sBAAkB,aAAa,gBAAgB,KAAK;AACpD,uBAAmB,aAAa,gBAAgB,aAAa,KAAK,CAAC;AAAA,EACrE,SAAS,OAAO;AACd,uBAAmB,aAAa,gBAAgB,MAAM;AACtD,UAAM;AAAA,EACR;AACF;AAOO,SAAS,qBACd,SACA,aACA,gBACA,aAA4B,QAAQ,SAAS,EAAE,mBACzC;AACN,MAAI,CAAC,WAAY;AACjB,qBAAmB,aAAa,gBAAgB,EAAE,YAAY,aAAa,MAAM,CAAC;AAClF,MAAI,QAAQ,SAAS,EAAE,sBAAsB,WAAY,SAAQ,qBAAqB,IAAI;AAC5F;AAQA,eAAsB,6BACpB,MACA,aACA,eACe;AACf,QAAM,SAAS,0BAA0B;AAEzC,QAAM,SAAS,cAAc;AAAA,IAC3B,CAAC,MAAM,EAAE,eAAe,UAAU,gCAAgC;AAAA,EACpE;AACA,MAAI,OAAO,WAAW,EAAG;AACzB,QAAM,QAAQ;AAAA,IACZ,OAAO,IAAI,OAAO,QAAQ;AACxB,YAAM,SAAS,aAAa,GAAG;AAC/B,UAAI,OAAO,cAAc,OAAO,YAAa;AAC7C,UAAI;AACF,cAAM,mBAAmB,MAAM,aAAa,IAAI,aAAa,OAAO,IAAI,WAAW,CAAC;AAAA,MACtF,QAAQ;AAAA,MAER;AAAA,IACF,CAAC;AAAA,EACH;AACA,8BAA4B,OAAO,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC;AAC9D;",
+  "names": []
+}