@agents24/chat-react 0.1.5 → 0.1.7

package/README.md

@@ -20,6 +20,10 @@ The package owns thread hydration, older-page pagination, stream/reattach state,
 - `partsFromResponseBlocks(blocks, fallbackText)`
 - `renderChatPart(part, message, renderOptions)`
 
+`useAgents24ChatController` exposes reactive `threads`, `activeThreadId`, `activeThread`, `activeRunId`, `isRefreshingThreads`, `loadThreadById(threadId)`, and `startNewThread()` in addition to message and stream state. It hydrates selected threads, detects active runs from `active_run`/`last_run_status`, attaches through the host transport, detaches local SSE streams on navigation, and refreshes history after terminal events.
+
+Hosts can pass `onRuntimeEvent(event, context)` and `onThreadDetailLoaded(detail)` to layer product-specific runtime UI, trace panels, analytics, or metadata over the shared chat lifecycle without forking stream handling. That surface is enough for running-history badges and read-only live thread inspectors without a separate host-owned reattach state machine.
+
 `ChatMessage.parts` is the only render model. Backend `response_blocks` are normalized into ordered parts such as `text`, `tool-get_meteo`, `ui-blocks`, `reasoning`, `approval`, `error`, and `data`. Tool UI is client-owned through `renderPart`, `toolRenderers`, and `fallbackToolRenderer`; the package does not infer English tool labels or group tool rows.
 
 `useStreamingText` owns reusable visual pacing for active assistant text. It returns `displayedText`, `isAnimating`, `mode`, and `parseIncompleteMarkdown` so host renderers can pass those values into their markdown component without the package depending on any markdown/UI library. The package only chooses text timing, cache behavior, reduced-motion handling, and active text-part helpers.

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   activeRunIdFromThreadDetail: () => activeRunIdFromThreadDetail,
   assistantTextFromParts: () => assistantTextFromParts,
   assistantTextFromResponseBlocks: () => assistantTextFromResponseBlocks,
+  compressionFromContextWindow: () => compressionFromContextWindow,
   consumeSseResponse: () => consumeSseResponse,
   createChatId: () => createChatId,
   createFetchChatTransport: () => createFetchChatTransport,
@@ -39,9 +40,14 @@ __export(index_exports, {
   isAtTimelineLatestEdge: () => isAtTimelineLatestEdge,
   isRunningThreadStatus: () => isRunningThreadStatus,
   isScrollable: () => isScrollable,
+  isUserScrollIntentAwayFromLatest: () => isUserScrollIntentAwayFromLatest,
   latestContextWindowFromThread: () => latestContextWindowFromThread,
+  mergeContextWindow: () => mergeContextWindow,
+  mergeContextWindowUpdate: () => mergeContextWindowUpdate,
   mergeReasoningSteps: () => mergeReasoningSteps,
   nextLatestFollowStateOnScroll: () => nextLatestFollowStateOnScroll,
+  normalizeContextCompression: () => normalizeContextCompression,
+  normalizeContextWindow: () => normalizeContextWindow,
   parseSseBlock: () => parseSseBlock,
   partsFromResponseBlocks: () => partsFromResponseBlocks,
   reasoningStepsFromParts: () => reasoningStepsFromParts,
@@ -63,9 +69,128 @@ module.exports = __toCommonJS(index_exports);
 // src/controller.ts
 var import_react = require("react");
 
+// src/context-window.ts
+var SOURCE_PRIORITY = {
+  unknown: 0,
+  heuristic_estimate: 1,
+  tokenizer_estimate: 1,
+  text_estimate: 1,
+  estimated: 1,
+  multimodal_estimate: 2,
+  hf_tokenizer: 3,
+  runtime_tokenizer: 3,
+  provider_count_api: 4,
+  provider_usage: 5,
+  exact: 5
+};
+var STAGE_PRIORITY = {
+  preflight: 0,
+  sent_prompt: 1,
+  final_usage: 2
+};
+function numberOrNull(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function stagePriority(window2) {
+  return STAGE_PRIORITY[window2?.stage || "sent_prompt"] ?? STAGE_PRIORITY.sent_prompt;
+}
+function hasRenderableContextWindow(window2) {
+  const maxTokens = window2?.max_tokens;
+  return typeof maxTokens === "number" && Number.isFinite(maxTokens) && maxTokens > 0;
+}
+function windowWeight(window2) {
+  if (!window2) return [0, 0];
+  return [stagePriority(window2), SOURCE_PRIORITY[window2.source] || 0];
+}
+function normalizeContextCompression(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const payload = value;
+  return {
+    active: Boolean(payload.active),
+    reason: typeof payload.reason === "string" ? payload.reason : null,
+    input_tokens: numberOrNull(payload.input_tokens),
+    max_tokens: numberOrNull(payload.max_tokens),
+    usage_ratio: numberOrNull(payload.usage_ratio),
+    full_frame_count: numberOrNull(payload.full_frame_count),
+    compact_frame_count: numberOrNull(payload.compact_frame_count),
+    dropped_frame_count: numberOrNull(payload.dropped_frame_count),
+    artifact_ref_count: numberOrNull(payload.artifact_ref_count),
+    compression_trigger_budget: numberOrNull(payload.compression_trigger_budget),
+    compression_target_budget: numberOrNull(payload.compression_target_budget),
+    compression_target_ratio: numberOrNull(payload.compression_target_ratio),
+    threshold_used: numberOrNull(payload.threshold_used)
+  };
+}
+function normalizeContextWindow(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const payload = value;
+  const rawSource = String(payload.source || "").trim();
+  const source = rawSource === "exact" || rawSource === "estimated" || rawSource === "unknown" || rawSource === "provider_count_api" || rawSource === "provider_usage" || rawSource === "runtime_tokenizer" || rawSource === "hf_tokenizer" || rawSource === "multimodal_estimate" || rawSource === "text_estimate" || rawSource === "tokenizer_estimate" || rawSource === "heuristic_estimate" ? rawSource : rawSource ? "estimated" : "unknown";
+  const rawStage = String(payload.stage || "").trim();
+  const stage = rawStage === "preflight" || rawStage === "sent_prompt" || rawStage === "final_usage" ? rawStage : "sent_prompt";
+  const rawConfidence = String(payload.confidence || "").trim();
+  const confidence = rawConfidence === "exact" || rawConfidence === "high" || rawConfidence === "medium" || rawConfidence === "low" || rawConfidence === "unknown" ? rawConfidence : null;
+  return {
+    source,
+    run_id: typeof payload.run_id === "string" ? payload.run_id : null,
+    stage,
+    confidence,
+    counter: typeof payload.counter === "string" ? payload.counter : null,
+    model_id: typeof payload.model_id === "string" ? payload.model_id : null,
+    max_tokens: numberOrNull(payload.max_tokens),
+    max_tokens_source: typeof payload.max_tokens_source === "string" ? payload.max_tokens_source : null,
+    input_tokens: numberOrNull(payload.input_tokens),
+    remaining_tokens: numberOrNull(payload.remaining_tokens),
+    usage_ratio: numberOrNull(payload.usage_ratio),
+    assembly: payload.assembly && typeof payload.assembly === "object" && !Array.isArray(payload.assembly) ? payload.assembly : null,
+    context_compression: normalizeContextCompression(payload.context_compression)
+  };
+}
+function mergeContextWindow(current, incoming) {
+  if (!incoming) return current ?? null;
+  if (!current) return incoming;
+  if (hasRenderableContextWindow(current) && !hasRenderableContextWindow(incoming)) return current;
+  const currentRunId = current.run_id || null;
+  const incomingRunId = incoming.run_id || null;
+  if (incomingRunId && currentRunId && incomingRunId !== currentRunId) {
+    return stagePriority(incoming) >= STAGE_PRIORITY.sent_prompt ? incoming : current;
+  }
+  const currentWeight = windowWeight(current);
+  const incomingWeight = windowWeight(incoming);
+  return incomingWeight[0] > currentWeight[0] || incomingWeight[0] === currentWeight[0] && incomingWeight[1] >= currentWeight[1] ? incoming : current;
+}
+function mergeContextWindowUpdate(current, incoming) {
+  return mergeContextWindow(current, normalizeContextWindow(incoming));
+}
+function compressionFromContextWindow(contextWindow) {
+  if (!contextWindow) return null;
+  if (contextWindow.context_compression) return contextWindow.context_compression;
+  const assembly = contextWindow.assembly;
+  if (!assembly || typeof assembly !== "object" || Array.isArray(assembly)) return null;
+  const artifactRefs = Array.isArray(assembly.artifact_refs) ? assembly.artifact_refs : [];
+  const compactFrameCount = numberOrNull(assembly.compact_frame_count) ?? 0;
+  const droppedFrameCount = numberOrNull(assembly.dropped_frame_count) ?? 0;
+  const reason = typeof assembly.compaction_reason === "string" ? assembly.compaction_reason : "none";
+  return {
+    active: reason !== "none" || compactFrameCount > 0 || droppedFrameCount > 0,
+    reason,
+    input_tokens: contextWindow.input_tokens ?? null,
+    max_tokens: contextWindow.max_tokens ?? null,
+    usage_ratio: contextWindow.usage_ratio ?? null,
+    full_frame_count: numberOrNull(assembly.full_frame_count),
+    compact_frame_count: compactFrameCount,
+    dropped_frame_count: droppedFrameCount,
+    artifact_ref_count: artifactRefs.length,
+    compression_trigger_budget: numberOrNull(assembly.compression_trigger_budget),
+    compression_target_budget: numberOrNull(assembly.compression_target_budget),
+    compression_target_ratio: numberOrNull(assembly.compression_target_ratio),
+    threshold_used: numberOrNull(assembly.threshold_used)
+  };
+}
+
 // src/model.ts
 var DEFAULT_THREAD_PAGE_SIZE = 5;
-var isRunningThreadStatus = (status) => (/* @__PURE__ */ new Set(["queued", "running"])).has(String(status || "").toLowerCase());
+var isRunningThreadStatus = (status) => (/* @__PURE__ */ new Set(["queued", "running", "cancelling"])).has(String(status || "").toLowerCase());
 var createChatId = () => {
   if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID();
   return `chat-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
@@ -104,6 +229,16 @@ var attachmentsFromTurn = (turn) => (turn.attachments || []).map((attachment, in
     mediaType: String(record.mime_type || record.mediaType || record.type || "application/octet-stream")
   };
 });
+var tokenUsageFromTurn = (turn) => {
+  const usage = turn.run_usage;
+  if (!usage || typeof usage !== "object") return void 0;
+  return {
+    inputTokens: usage.input_tokens ?? null,
+    outputTokens: usage.output_tokens ?? null,
+    totalTokens: usage.total_tokens ?? null,
+    usageSource: usage.source ?? null
+  };
+};
 var latestEventPayloadValue = (events, key) => {
   for (let index = (events || []).length - 1; index >= 0; index -= 1) {
     const payload = events?.[index]?.payload;
@@ -305,7 +440,8 @@ var turnToMessages = (turn, activeRunId) => {
       createdAt: turn.completed_at ? new Date(turn.completed_at) : createdAt,
       parts,
       reasoningSteps: mergeReasoningSteps(reasoningStepsFromParts(parts), { finalize: !isRunning }),
-      isFinal: !isRunning
+      isFinal: !isRunning,
+      tokenUsage: tokenUsageFromTurn(turn)
     });
   }
   return messages;
@@ -322,10 +458,11 @@ var threadPaging = (thread) => {
   };
 };
 var latestContextWindowFromThread = (thread) => {
-  if (thread.context_window && typeof thread.context_window === "object") return thread.context_window;
+  const threadContextWindow = normalizeContextWindow(thread.context_window);
+  if (threadContextWindow) return threadContextWindow;
   for (let index = (thread.turns || []).length - 1; index >= 0; index -= 1) {
-    const value = thread.turns?.[index]?.context_window;
-    if (value && typeof value === "object") return value;
+    const contextWindow = normalizeContextWindow(thread.turns?.[index]?.context_window);
+    if (contextWindow) return contextWindow;
   }
   return null;
 };
@@ -356,10 +493,6 @@ var activeRunIdFromThreadDetail = (thread) => {
 };
 
 // src/controller.ts
-var mergeContextWindow = (current, incoming) => {
-  if (!incoming || typeof incoming !== "object") return current;
-  return { ...current || {}, ...incoming };
-};
 var threadSummaryToStored = (thread) => ({
   ...thread,
   id: String(thread.id),
@@ -377,7 +510,9 @@ function useAgents24ChatController({
   createId = createChatId,
   onActiveThreadIdChange,
   onSourceClick,
-  onStreamErrorMessage
+  onStreamErrorMessage,
+  onRuntimeEvent,
+  onThreadDetailLoaded
 }) {
   const activeThreadId = controlledActiveThreadId ?? storage.getActiveThreadId?.() ?? null;
   const initialCached = activeThreadId ? storage.getThread(activeThreadId) : void 0;
@@ -394,6 +529,9 @@ function useAgents24ChatController({
   const [disliked, setDisliked] = (0, import_react.useState)({});
   const [copiedMessageId, setCopiedMessageId] = (0, import_react.useState)(null);
   const [lastThinkingDurationMs, setLastThinkingDurationMs] = (0, import_react.useState)(null);
+  const [threads, setThreads] = (0, import_react.useState)(() => storage.listThreads());
+  const [isRefreshingThreads, setIsRefreshingThreads] = (0, import_react.useState)(false);
+  const [activeRunId, setActiveRunId] = (0, import_react.useState)(null);
   const textareaRef = (0, import_react.useRef)(null);
   const activeThreadIdRef = (0, import_react.useRef)(activeThreadId);
   const messagesRef = (0, import_react.useRef)(messages);
@@ -410,6 +548,20 @@ function useAgents24ChatController({
   const streamingMessageIdRef = (0, import_react.useRef)(null);
   const reasoningRef = (0, import_react.useRef)([]);
   const liveVoiceIdsRef = (0, import_react.useRef)({});
+  const setActiveRunIdValue = (0, import_react.useCallback)((runId) => {
+    activeRunIdRef.current = runId;
+    setActiveRunId(runId);
+  }, []);
+  const syncThreadsFromStorage = (0, import_react.useCallback)(() => {
+    setThreads(storage.listThreads());
+  }, [storage]);
+  const upsertStoredThread = (0, import_react.useCallback)(
+    (thread) => {
+      storage.upsertThread(thread);
+      syncThreadsFromStorage();
+    },
+    [storage, syncThreadsFromStorage]
+  );
   (0, import_react.useEffect)(() => {
     messagesRef.current = messages;
   }, [messages]);
@@ -417,7 +569,7 @@ function useAgents24ChatController({
     (threadId, nextMessages, paging, options) => {
       const existing = storage.getThread(threadId);
       const firstUser = nextMessages.find((message) => message.role === "user");
-      storage.upsertThread({
+      upsertStoredThread({
         ...existing || {},
         id: threadId,
         title: existing?.title || (firstUser ? titleFromMessage(firstUser.content, firstUser.attachments || []) : "New chat"),
@@ -428,13 +580,13 @@ function useAgents24ChatController({
         nextBeforeTurnIndex: paging?.nextBeforeTurnIndex ?? nextBeforeTurnIndexRef.current
       });
     },
-    [storage]
+    [storage, upsertStoredThread]
   );
   const markThreadRunStatus = (0, import_react.useCallback)(
     (threadId, runId, status, lastEventSeq) => {
       const existing = storage.getThread(threadId);
       if (!existing || !runId) return;
-      storage.upsertThread({
+      upsertStoredThread({
         ...existing,
         last_run_id: runId,
         last_run_status: status,
@@ -451,14 +603,25 @@ function useAgents24ChatController({
           created_at: existing.activeRun?.created_at ?? existing.active_run?.created_at ?? (/* @__PURE__ */ new Date()).toISOString()
         },
         lastEventSeq: typeof lastEventSeq === "number" ? lastEventSeq : existing.lastEventSeq ?? null,
-        isRunning: status === "queued" || status === "running"
+        isRunning: activeRunIdFromThread({
+          lastRunId: runId,
+          lastRunStatus: status,
+          activeRun: { run_id: runId, status }
+        }) !== null
       });
     },
-    [storage]
+    [storage, upsertStoredThread]
   );
   const refresh = (0, import_react.useCallback)(async () => {
-    const data = await transport.listThreads();
-    storage.setThreads((data.items || []).map((item) => threadSummaryToStored(item)));
+    setIsRefreshingThreads(true);
+    try {
+      const data = await transport.listThreads();
+      const nextThreads = (data.items || []).map((item) => threadSummaryToStored(item));
+      storage.setThreads(nextThreads);
+      setThreads(storage.listThreads());
+    } finally {
+      setIsRefreshingThreads(false);
+    }
   }, [storage, transport]);
   const applyThreadId = (0, import_react.useCallback)(
     (threadId, baseMessages) => {
@@ -486,7 +649,7 @@ function useAgents24ChatController({
     const controller = abortControllerRef.current;
     abortControllerRef.current = null;
     controller?.abort();
-    activeRunIdRef.current = null;
+    setActiveRunIdValue(null);
     reattachedRunIdRef.current = null;
     streamingMessageIdRef.current = null;
     streamingContentRef.current = "";
@@ -495,7 +658,7 @@ function useAgents24ChatController({
     setIsLoading(false);
     setStreamingContent("");
     setCurrentReasoning([]);
-  }, []);
+  }, [setActiveRunIdValue]);
   const setLiveAssistantMessage = (0, import_react.useCallback)(
     (input) => {
       setMessages((prev) => {
@@ -565,7 +728,7 @@ function useAgents24ChatController({
         persistThread(input.threadId, completed);
         const existingThread = storage.getThread(input.threadId);
         if (existingThread && input.runId) {
-          storage.upsertThread({
+          upsertStoredThread({
             ...existingThread,
             messages: completed,
             last_run_id: input.runId,
@@ -580,7 +743,7 @@ function useAgents24ChatController({
       }
       return completed;
     },
-    [createId, persistThread, storage]
+    [createId, persistThread, storage, upsertStoredThread]
   );
   const loadThread = (0, import_react.useCallback)(
     async (threadId) => {
@@ -595,6 +758,7 @@ function useAgents24ChatController({
           includeRunEvents: false
         });
         if (activeThreadIdRef.current !== threadId || seq !== requestSeqRef.current) return;
+        void onThreadDetailLoaded?.(detail);
         const nextMessages = threadDetailToMessages(detail);
         const paging = threadPaging(detail);
         setContextStatus(latestContextWindowFromThread(detail));
@@ -604,7 +768,7 @@ function useAgents24ChatController({
         hasOlderTurnsRef.current = paging.hasOlderTurns;
         nextBeforeTurnIndexRef.current = paging.nextBeforeTurnIndex;
         loadedThreadIdRef.current = threadId;
-        storage.upsertThread({
+        upsertStoredThread({
           ...threadSummaryToStored(detail),
           messages: nextMessages,
           isHydrated: true,
@@ -616,7 +780,7 @@ function useAgents24ChatController({
         if (activeThreadIdRef.current === threadId) setLoadingHistory(false);
       }
     },
-    [pageSize, setLoadingHistory, storage, transport]
+    [onThreadDetailLoaded, pageSize, setLoadingHistory, transport, upsertStoredThread]
   );
   const loadOlderTurns = (0, import_react.useCallback)(async () => {
     const threadId = activeThreadIdRef.current;
@@ -648,11 +812,18 @@ function useAgents24ChatController({
   }, [pageSize, persistThread, transport]);
   const handleStreamEvent = (0, import_react.useCallback)(
     (input) => {
-      const { event, assistantMessageId, startedAt, streamThreadIdRef, baseMessages } = input;
+      const { mode, event, assistantMessageId, startedAt, streamThreadIdRef, baseMessages } = input;
       const payload = event.payload || {};
       const responseBlocks = Array.isArray(payload.response_blocks) ? payload.response_blocks : null;
-      if (event.run_id) activeRunIdRef.current = event.run_id;
-      setContextStatus((current) => mergeContextWindow(current, payload.context_window));
+      if (event.run_id) setActiveRunIdValue(event.run_id);
+      void onRuntimeEvent?.(event, {
+        mode,
+        assistantMessageId,
+        threadId: streamThreadIdRef.current,
+        runId: event.run_id || activeRunIdRef.current,
+        startedAt
+      });
+      setContextStatus((current) => mergeContextWindowUpdate(current, payload.context_window));
       if (responseBlocks) {
         const blockText = String(payload.assistant_output_text || "") || assistantTextFromResponseBlocks(responseBlocks) || streamingContentRef.current;
         if (blockText) setStreamingText(blockText);
@@ -698,7 +869,7 @@ function useAgents24ChatController({
         error: isFailed ? String(payload.message || payload.error || event.diagnostics?.[0]?.message || onStreamErrorMessage?.(event) || "The chat run failed.") : void 0
       });
     },
-    [applyThreadId, finalizeAssistantMessage, markThreadRunStatus, onStreamErrorMessage, setLiveAssistantMessage, setReasoningSteps]
+    [applyThreadId, finalizeAssistantMessage, markThreadRunStatus, onRuntimeEvent, onStreamErrorMessage, setActiveRunIdValue, setLiveAssistantMessage, setReasoningSteps]
   );
   const runStream = (0, import_react.useCallback)(
     async (input) => {
@@ -760,16 +931,16 @@ function useAgents24ChatController({
       }
       try {
         if (input.mode === "attach") {
-          activeRunIdRef.current = input.runId;
+          setActiveRunIdValue(input.runId);
           reattachedRunIdRef.current = input.runId;
           await transport.attachRun(
             { runId: input.runId, signal: controller.signal },
-            (event) => handleStreamEvent({ event, assistantMessageId, startedAt, streamThreadIdRef, baseMessages })
+            (event) => handleStreamEvent({ mode: "attach", event, assistantMessageId, startedAt, streamThreadIdRef, baseMessages })
           );
         } else {
           await transport.streamMessage(
-            { text: input.message.text, files: input.message.files || [], threadId: activeThreadIdRef.current, signal: controller.signal },
-            (event) => handleStreamEvent({ event, assistantMessageId, startedAt, streamThreadIdRef, baseMessages })
+            { ...input.message, files: input.message.files || [], threadId: activeThreadIdRef.current, signal: controller.signal },
+            (event) => handleStreamEvent({ mode: "submit", event, assistantMessageId, startedAt, streamThreadIdRef, baseMessages })
           );
         }
         if (streamingContentRef.current.trim() && streamingMessageIdRef.current) {
@@ -801,7 +972,7 @@ function useAgents24ChatController({
         const isCurrentStream = abortControllerRef.current === controller || streamingMessageIdRef.current === assistantMessageId;
         if (abortControllerRef.current === controller) abortControllerRef.current = null;
         if (isCurrentStream) {
-          activeRunIdRef.current = null;
+          setActiveRunIdValue(null);
           streamingMessageIdRef.current = null;
           reattachedRunIdRef.current = null;
           setStreamingMessageId(null);
@@ -812,7 +983,7 @@ function useAgents24ChatController({
         }
       }
     },
-    [createId, finalizeAssistantMessage, handleStreamEvent, onStreamErrorMessage, persistThread, refresh, setReasoningSteps, transport]
+    [createId, finalizeAssistantMessage, handleStreamEvent, onStreamErrorMessage, persistThread, refresh, setActiveRunIdValue, setReasoningSteps, transport]
   );
   const handleSubmit = (0, import_react.useCallback)(
     async (message) => {
@@ -827,7 +998,7 @@ function useAgents24ChatController({
     const liveMessageId = streamingMessageIdRef.current;
     abortControllerRef.current?.abort();
     abortControllerRef.current = null;
-    activeRunIdRef.current = null;
+    setActiveRunIdValue(null);
     streamingMessageIdRef.current = null;
     setStreamingMessageId(null);
     setIsLoading(false);
@@ -844,10 +1015,16 @@ function useAgents24ChatController({
         messageId: liveMessageId
       });
     }
-  }, [finalizeAssistantMessage, lastThinkingDurationMs, setReasoningSteps, transport]);
+  }, [finalizeAssistantMessage, lastThinkingDurationMs, setActiveRunIdValue, setReasoningSteps, transport]);
   (0, import_react.useEffect)(() => {
-    refresh().catch(() => storage.setThreads([]));
+    refresh().catch(() => {
+      storage.setThreads([]);
+      setThreads([]);
+    });
   }, [refresh, storage]);
+  (0, import_react.useEffect)(() => {
+    syncThreadsFromStorage();
+  }, [storageKey, syncThreadsFromStorage]);
   (0, import_react.useEffect)(() => {
     const previous = activeThreadIdRef.current;
     activeThreadIdRef.current = activeThreadId;
@@ -955,7 +1132,40 @@ function useAgents24ChatController({
       return next;
     });
   }, [createId, persistThread]);
+  const startNewThread = (0, import_react.useCallback)(() => {
+    detachActiveStream();
+    requestSeqRef.current += 1;
+    activeThreadIdRef.current = null;
+    loadedThreadIdRef.current = null;
+    nextBeforeTurnIndexRef.current = null;
+    hasOlderTurnsRef.current = false;
+    storage.setActiveThreadId?.(null);
+    onActiveThreadIdChange?.(null);
+    setMessages([]);
+    messagesRef.current = [];
+    setHasOlderTurns(false);
+    setIsLoadingOlder(false);
+    setContextStatus(null);
+    setLoadingHistory(false);
+  }, [detachActiveStream, onActiveThreadIdChange, setLoadingHistory, storage]);
+  const loadThreadById = (0, import_react.useCallback)(
+    async (threadId) => {
+      if (!threadId) return;
+      if (activeThreadIdRef.current !== threadId) {
+        if (abortControllerRef.current) detachActiveStream();
+        activeThreadIdRef.current = threadId;
+        storage.setActiveThreadId?.(threadId);
+        onActiveThreadIdChange?.(threadId);
+      }
+      await loadThread(threadId);
+    },
+    [detachActiveStream, loadThread, onActiveThreadIdChange, storage]
+  );
+  const activeThread = activeThreadId ? storage.getThread(activeThreadId) || threads.find((thread) => thread.id === activeThreadId) || null : null;
   return (0, import_react.useMemo)(() => ({
+    threads,
+    activeThreadId,
+    activeThread,
     messages,
     streamingContent,
     streamingMessageId,
@@ -964,12 +1174,13 @@ function useAgents24ChatController({
     isLoading,
     isLoadingHistory,
     isLoadingOlder,
+    isRefreshingThreads,
     hasOlderTurns,
     liked,
     disliked,
     copiedMessageId,
     lastThinkingDurationMs,
-    activeRunId: activeRunIdRef.current,
+    activeRunId,
     handleSubmit,
     handleStop,
     handleCopy,
@@ -978,11 +1189,16 @@ function useAgents24ChatController({
     handleRetry,
     handleSourceClick: (citations) => onSourceClick?.(citations),
     upsertLiveVoiceMessage,
+    startNewThread,
+    loadThreadById,
     loadOlderTurns,
     refresh,
     textareaRef
   }), [
     copiedMessageId,
+    activeRunId,
+    activeThread,
+    activeThreadId,
     contextStatus,
     currentReasoning,
     disliked,
@@ -996,14 +1212,18 @@ function useAgents24ChatController({
     isLoading,
     isLoadingHistory,
     isLoadingOlder,
+    isRefreshingThreads,
     lastThinkingDurationMs,
     liked,
+    loadThreadById,
     loadOlderTurns,
     messages,
     onSourceClick,
     refresh,
     streamingContent,
     streamingMessageId,
+    startNewThread,
+    threads,
     upsertLiveVoiceMessage
   ]);
 }
@@ -1337,6 +1557,18 @@ var nextLatestFollowStateOnScroll = ({
   if (isProgrammatic) return current;
   return atLatest ? "following" : "detached";
 };
+var isUserScrollIntentAwayFromLatest = (intent) => {
+  if (!intent) return false;
+  if ("deltaY" in intent && typeof intent.deltaY === "number") {
+    return intent.deltaY < 0;
+  }
+  if ("key" in intent && typeof intent.key === "string") {
+    if (intent.key === "ArrowUp" || intent.key === "PageUp" || intent.key === "Home") return true;
+    if ((intent.key === " " || intent.key === "Spacebar") && intent.shiftKey) return true;
+    return false;
+  }
+  return "touches" in intent;
+};
 function useLatestThreadViewport({
   itemCount,
   hasOlder,
@@ -1386,10 +1618,11 @@ function useLatestThreadViewport({
   const reattachToLatest = (0, import_react3.useCallback)(() => {
     scrollToLatest({ reattach: true });
   }, [scrollToLatest]);
-  const handleUserScrollIntent = (0, import_react3.useCallback)(() => {
+  const handleUserScrollIntent = (0, import_react3.useCallback)((intent) => {
     const element = scrollContainerRef.current;
     if (!activeStreamKey || !element) return;
-    if (!isAtTimelineLatestEdge(element, isTopOrigin)) detachFromLatest();
+    const atLatest = isAtTimelineLatestEdge(element, isTopOrigin);
+    if (!atLatest || isUserScrollIntentAwayFromLatest(intent)) detachFromLatest();
   }, [activeStreamKey, detachFromLatest, isTopOrigin]);
   (0, import_react3.useEffect)(() => {
     return () => {
@@ -1473,9 +1706,22 @@ function useLatestThreadViewport({
     };
     intrinsicResizePreserveRef.current.frame = requestAnimationFrame(preserveFrame);
   }, [isTopOrigin, markProgrammaticScroll]);
-  (0, import_react3.useEffect)(() => {
+  (0, import_react3.useLayoutEffect)(() => {
     const key = activeStreamKey || null;
-    if (!key || activeStreamKeyRef.current === key) {
+    const previousKey = activeStreamKeyRef.current;
+    if (!key) {
+      activeStreamKeyRef.current = null;
+      if (previousKey && shouldAutoFollow && followStateRef.current === "following" && !isLoadingOlder && !olderPageRequestInFlightRef.current) {
+        const frame2 = requestAnimationFrame(() => {
+          if (followStateRef.current === "following" && !isLoadingOlder && !olderPageRequestInFlightRef.current) {
+            scrollToLatest({ reattach: false });
+          }
+        });
+        return () => cancelAnimationFrame(frame2);
+      }
+      return;
+    }
+    if (previousKey === key) {
       activeStreamKeyRef.current = key;
       return;
     }
@@ -1483,7 +1729,7 @@ function useLatestThreadViewport({
     const frame = requestAnimationFrame(() => scrollToLatest());
     activeStreamKeyRef.current = key;
     return () => cancelAnimationFrame(frame);
-  }, [activeStreamKey, scrollToLatest, setLatestFollowState]);
+  }, [activeStreamKey, isLoadingOlder, scrollToLatest, setLatestFollowState, shouldAutoFollow]);
   (0, import_react3.useLayoutEffect)(() => {
     if (!activeStreamKey || !shouldAutoFollow || followStateRef.current !== "following") return;
     if (isLoadingOlder || olderPageRequestInFlightRef.current) return;
@@ -1554,10 +1800,10 @@ function LatestThreadViewport({
     {
       ref: viewport.scrollContainerRef,
       className,
-      onKeyDown: viewport.handleUserScrollIntent,
+      onKeyDownCapture: viewport.handleUserScrollIntent,
       onScroll: viewport.handleScroll,
-      onTouchMove: viewport.handleUserScrollIntent,
-      onWheel: viewport.handleUserScrollIntent,
+      onTouchMoveCapture: viewport.handleUserScrollIntent,
+      onWheelCapture: viewport.handleUserScrollIntent,
       role: "log",
       style: { overflowAnchor: "none" },
       children: [
@@ -1578,6 +1824,7 @@ function LatestThreadViewport({
   activeRunIdFromThreadDetail,
   assistantTextFromParts,
   assistantTextFromResponseBlocks,
+  compressionFromContextWindow,
   consumeSseResponse,
   createChatId,
   createFetchChatTransport,
@@ -1589,9 +1836,14 @@ function LatestThreadViewport({
   isAtTimelineLatestEdge,
   isRunningThreadStatus,
   isScrollable,
+  isUserScrollIntentAwayFromLatest,
   latestContextWindowFromThread,
+  mergeContextWindow,
+  mergeContextWindowUpdate,
   mergeReasoningSteps,
   nextLatestFollowStateOnScroll,
+  normalizeContextCompression,
+  normalizeContextWindow,
   parseSseBlock,
   partsFromResponseBlocks,
   reasoningStepsFromParts,