@stigmer/react 3.7.0 → 3.8.0

package/src/conversation/index.ts

@@ -0,0 +1,80 @@
+export { ConversationsWorkbench } from "./ConversationsWorkbench.js";
+export type {
+  ConversationHeaderContext,
+  ConversationsWorkbenchProps,
+} from "./ConversationsWorkbench.js";
+
+export { ConversationListPane } from "./ConversationListPane.js";
+export type {
+  ConversationIdentity,
+  ConversationListPaneProps,
+} from "./ConversationListPane.js";
+
+export { ConversationTimelineView } from "./ConversationTimelineView.js";
+export type { ConversationTimelineViewProps } from "./ConversationTimelineView.js";
+
+export { ConversationControlBanner } from "./ConversationControlBanner.js";
+export type { ConversationControlBannerProps } from "./ConversationControlBanner.js";
+
+export { ConversationAttentionBanner } from "./ConversationAttentionBanner.js";
+export type { ConversationAttentionBannerProps } from "./ConversationAttentionBanner.js";
+
+export { ConversationComposer } from "./ConversationComposer.js";
+export type { ConversationComposerProps } from "./ConversationComposer.js";
+
+export { useConversation } from "./useConversation.js";
+export type {
+  UseConversationOptions,
+  UseConversationReturn,
+} from "./useConversation.js";
+
+export { useConversationList } from "./useConversationList.js";
+export type {
+  UseConversationListOptions,
+  UseConversationListReturn,
+} from "./useConversationList.js";
+
+export { useConversationTimeline } from "./useConversationTimeline.js";
+export type {
+  UseConversationTimelineOptions,
+  UseConversationTimelineReturn,
+} from "./useConversationTimeline.js";
+
+export { useConversationParticipation } from "./useConversationParticipation.js";
+export type {
+  ConversationCommand,
+  UseConversationParticipationOptions,
+  UseConversationParticipationReturn,
+} from "./useConversationParticipation.js";
+
+export { useConversationsWantsHumanCount } from "./useConversationsWantsHumanCount.js";
+export type {
+  UseConversationsWantsHumanCountOptions,
+  UseConversationsWantsHumanCountReturn,
+} from "./useConversationsWantsHumanCount.js";
+
+export {
+  authorKindOf,
+  awaitingIndicatorOf,
+  compareTimelineItemsNewestFirst,
+  conversationContactOf,
+  conversationLabelOf,
+  inboundPlaceholderOf,
+  isInternalItem,
+  receiptOf,
+  sendAttemptOf,
+  serviceWindowOf,
+} from "./conversationPresentation.js";
+export type {
+  AwaitingIndicator,
+  ConversationAuthorKind,
+  ReceiptKind,
+  SendAttemptKind,
+  ServiceWindowState,
+} from "./conversationPresentation.js";
+
+export {
+  CONVERSATION_BADGE_POLL_INTERVAL_MS,
+  CONVERSATION_DETAIL_POLL_INTERVAL_MS,
+  CONVERSATION_LIST_POLL_INTERVAL_MS,
+} from "./polling.js";

package/src/conversation/polling.ts

@@ -0,0 +1,41 @@
+/**
+ * Liveness for the conversation surface is HONEST POLLING (channel-
+ * conversations DD-012) — no streaming or watch RPC exists on the
+ * conversation query controller, and none ships until a revisit trigger
+ * fires (a real push consumer, or sub-second liveness becoming a product
+ * property). These constants are the deliberate transport seam: hooks
+ * default to them, consumers may override per instance, and when
+ * push-shaped liveness lands the defaults change here without touching a
+ * consumer.
+ *
+ * The latency budget is a stated contract (DD-012 D-b), not an accident
+ * of three numbers:
+ *
+ * | Surface                                  | Budget                       | Mechanism                                        |
+ * | ---------------------------------------- | ---------------------------- | ------------------------------------------------ |
+ * | Your own action (take over, hand back,   | immediate                    | command answer applied to the detail AND list    |
+ * | dismiss, reply)                          |                              | `applyServerState` seams — zero polls involved   |
+ * | The open conversation (row + timeline)   | ≤ 5s                         | detail polls                                     |
+ * | The inbox list                           | ≤ 20s, immediate on refocus  | list poll + focus refetch                        |
+ * | The nav badge                            | ≤ 60s, immediate on refocus  | count poll (the filtered list's `total_count`)   |
+ */
+
+/** Default poll interval for the org-wide conversation list. */
+export const CONVERSATION_LIST_POLL_INTERVAL_MS = 20_000;
+
+/**
+ * Default poll interval for the OPEN conversation (its row and its
+ * timeline head). Tighter than the list on purpose: this is where a
+ * teammate's takeover or the customer's next message must appear while
+ * a human is watching.
+ */
+export const CONVERSATION_DETAIL_POLL_INTERVAL_MS = 5_000;
+
+/**
+ * Default poll interval for the sidebar's wants-human count. Deliberately
+ * the slowest budget on the surface: a badge tolerates staleness an open
+ * inbox does not, it renders on every console page in every tab, and each
+ * tick pays an FGA ListObjects before the count (DD-011 D-g's stated
+ * price). Focus refetch keeps it honest at the moment someone returns.
+ */
+export const CONVERSATION_BADGE_POLL_INTERVAL_MS = 60_000;

package/src/conversation/useConversation.ts

@@ -0,0 +1,221 @@
+"use client";
+
+import { create, equals } from "@bufbuild/protobuf";
+import { isNotFound } from "@stigmer/sdk";
+import type { ChannelConversation } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import {
+  ChannelConversationSchema,
+  GetChannelConversationInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import { CONVERSATION_DETAIL_POLL_INTERVAL_MS } from "./polling.js";
+
+/** Options for {@link useConversation}. */
+export interface UseConversationOptions {
+  /**
+   * Poll interval in milliseconds; `false` disables polling. Defaults to
+   * {@link CONVERSATION_DETAIL_POLL_INTERVAL_MS} — the open conversation
+   * is where another teammate's takeover must appear promptly.
+   */
+  readonly refetchIntervalMs?: number | false;
+}
+
+/** Return value of {@link useConversation}. */
+export interface UseConversationReturn {
+  /**
+   * The conversation's participation state, or `null` while loading and
+   * while the conversation does not exist yet (see
+   * {@link awaitingCustomer} for the distinction).
+   */
+  readonly conversation: ChannelConversation | null;
+  /**
+   * `true` when the server answered NOT_FOUND: no conversation row
+   * exists yet for this key. NOT an error — a proactive cold-send can
+   * have a timeline before the customer ever writes, and the row is
+   * created by the customer's first message. Render it as
+   * "participation controls unlock when the customer writes".
+   */
+  readonly awaitingCustomer: boolean;
+  /** `true` only until the first answer (row or NOT_FOUND) arrives. */
+  readonly isLoading: boolean;
+  /** `true` while a background poll is in flight and stale state shows. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request (NOT_FOUND excluded), or `null`. */
+  readonly error: Error | null;
+  /** Imperatively re-read the row. */
+  readonly refetch: () => void;
+  /**
+   * Adopt a fresh row the server just returned — every participation
+   * command answers the post-command state (including for the loser of
+   * a concurrent-takeover race), and that answer is newer than anything
+   * a poll already in flight will deliver. Applying it also fences
+   * those in-flight polls so a stale answer can never overwrite it.
+   */
+  readonly applyServerState: (fresh: ChannelConversation) => void;
+}
+
+/**
+ * Data hook for one conversation's identity and participation state —
+ * the single-row read behind a conversation detail view (who holds
+ * control, whether attention is needed and why, the display name).
+ *
+ * Deliberately NOT built on the shared `useFetch`: participation
+ * commands hand back fresher state than any in-flight poll
+ * ({@link UseConversationReturn.applyServerState}), which needs a write
+ * fence over the fetch state — a seam `useFetch`'s single-writer model
+ * does not have. The fence is an epoch counter: applying server state
+ * bumps it, and a poll that started under an older epoch discards its
+ * answer instead of resurrecting pre-command state under the user's
+ * cursor.
+ *
+ * Pass empty strings to skip fetching (the `null`-fetchFn convention).
+ */
+export function useConversation(
+  agentChannelId: string,
+  conversationKey: string,
+  options?: UseConversationOptions,
+): UseConversationReturn {
+  const stigmer = useStigmer();
+  const refetchIntervalMs =
+    options?.refetchIntervalMs ?? CONVERSATION_DETAIL_POLL_INTERVAL_MS;
+
+  const enabled = agentChannelId !== "" && conversationKey !== "";
+
+  const [conversation, setConversation] = useState<ChannelConversation | null>(null);
+  const [awaitingCustomer, setAwaitingCustomer] = useState(false);
+  const [hasAnswer, setHasAnswer] = useState(false);
+  const [isFetching, setIsFetching] = useState(enabled);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  // The write fence: bumped by applyServerState and by identity changes;
+  // a fetch that started under an older epoch throws its answer away.
+  const epochRef = useRef(0);
+  // Which fetch is the latest — ONLY the latest fetch's resolution may
+  // clear the in-flight flags, so a fenced stale answer cannot strand
+  // isFetching=true (which would silence the poll interval forever).
+  const fetchIdRef = useRef(0);
+  const isFetchingRef = useRef(false);
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  const applyServerState = useCallback((fresh: ChannelConversation) => {
+    epochRef.current += 1;
+    setConversation(fresh);
+    setAwaitingCustomer(false);
+    setHasAnswer(true);
+    setError(null);
+  }, []);
+
+  useEffect(() => {
+    // Identity change (or disable): reset so channel A's control state
+    // can never render under channel B's key.
+    epochRef.current += 1;
+    setConversation(null);
+    setAwaitingCustomer(false);
+    setHasAnswer(false);
+    setError(null);
+    if (!enabled) {
+      setIsFetching(false);
+      isFetchingRef.current = false;
+    }
+  }, [agentChannelId, conversationKey, stigmer, enabled]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const epoch = epochRef.current;
+    const fetchId = ++fetchIdRef.current;
+    setIsFetching(true);
+    isFetchingRef.current = true;
+
+    const settle = () => {
+      if (fetchIdRef.current !== fetchId) return;
+      setIsFetching(false);
+      isFetchingRef.current = false;
+    };
+
+    stigmer.agentChannel
+      .getConversation(
+        create(GetChannelConversationInputSchema, { agentChannelId, conversationKey }),
+      )
+      .then(
+        (row) => {
+          if (epochRef.current === epoch) {
+            // Preserve the reference across polls that change nothing —
+            // a fresh-but-equal proto every 5s would defeat React.memo
+            // on everything rendering the row (DD-010).
+            setConversation((current) =>
+              current && equals(ChannelConversationSchema, current, row)
+                ? current
+                : row,
+            );
+            setAwaitingCustomer(false);
+            setHasAnswer(true);
+            setError(null);
+          }
+          settle();
+        },
+        (err) => {
+          if (epochRef.current === epoch) {
+            if (isNotFound(err)) {
+              // The legitimate "no row yet" answer — not an error state.
+              setConversation(null);
+              setAwaitingCustomer(true);
+              setHasAnswer(true);
+              setError(null);
+            } else {
+              setError(toError(err));
+            }
+          }
+          settle();
+        },
+      );
+  }, [enabled, agentChannelId, conversationKey, stigmer, fetchKey]);
+
+  useEffect(() => {
+    if (!enabled || !refetchIntervalMs || refetchIntervalMs <= 0) return;
+    const id = setInterval(() => {
+      if (!isFetchingRef.current) refetch();
+    }, refetchIntervalMs);
+    return () => clearInterval(id);
+  }, [enabled, refetchIntervalMs, refetch]);
+
+  // Focus refetch (DD-012 D-a: returning to the tab is fresh), guarded by
+  // the same in-flight flag as the interval. Mirrors useFetch's
+  // refetchOnWindowFocus — the second sighting of this listener shape;
+  // extract a shared helper if a third hand-rolled loop ever needs it.
+  useEffect(() => {
+    if (!enabled) return;
+    if (typeof window === "undefined") return;
+    const onActive = () => {
+      if (!isFetchingRef.current) refetch();
+    };
+    const onVisible = () => {
+      if (document.visibilityState === "visible") onActive();
+    };
+    window.addEventListener("focus", onActive);
+    document.addEventListener("visibilitychange", onVisible);
+    return () => {
+      window.removeEventListener("focus", onActive);
+      document.removeEventListener("visibilitychange", onVisible);
+    };
+  }, [enabled, refetch]);
+
+  const isLoading = isFetching && !hasAnswer;
+  const isRefetching = isFetching && hasAnswer;
+
+  return useMemo(
+    () => ({
+      conversation,
+      awaitingCustomer,
+      isLoading,
+      isRefetching,
+      error,
+      refetch,
+      applyServerState,
+    }),
+    [conversation, awaitingCustomer, isLoading, isRefetching, error, refetch, applyServerState],
+  );
+}

package/src/conversation/useConversationList.ts

@@ -0,0 +1,328 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import type { ChannelConversation } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import {
+  ChannelConversationListFilter,
+  ListChannelConversationsInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import { useFetch } from "../internal/useFetch.js";
+import { CONVERSATION_LIST_POLL_INTERVAL_MS } from "./polling.js";
+
+/** Options for {@link useConversationList}. */
+export interface UseConversationListOptions {
+  /** Organization whose conversations to list. `null` skips fetching. */
+  readonly org: string | null;
+  /** Optional filter: only conversations on this agent channel. */
+  readonly agentChannelId?: string;
+  /**
+   * Optional server-evaluated predicate filter (channel-conversations
+   * DD-011 D-g). The generated enum is the vocabulary on purpose — the
+   * predicate lives in ONE place, the server, and the hook never
+   * re-expresses it. Defaults to unspecified (no filter).
+   */
+  readonly filter?: ChannelConversationListFilter;
+  /** Page size for the head page and each loadMore page. Default 50. */
+  readonly pageSize?: number;
+  /**
+   * Poll interval in milliseconds; `false` disables polling. Defaults to
+   * {@link CONVERSATION_LIST_POLL_INTERVAL_MS}. Only the head page polls
+   * — loaded older pages refresh on the next full identity change.
+   */
+  readonly refetchIntervalMs?: number | false;
+}
+
+/** Return value of {@link useConversationList}. */
+export interface UseConversationListReturn {
+  /**
+   * Conversations, newest activity first: the polled head page followed
+   * by the accumulated older pages, deduplicated by conversation
+   * identity (offset pages drift under live activity — a conversation
+   * that moved up between fetches appears once, in its head position),
+   * with any {@link applyServerState} rows overriding both.
+   */
+  readonly conversations: readonly ChannelConversation[];
+  /** Exact total for the current filter, from the server. */
+  readonly totalCount: number;
+  /** `true` while more conversations exist beyond what is loaded. */
+  readonly hasMore: boolean;
+  /** Load the next older page. No-op while one is already loading. */
+  readonly loadMore: () => void;
+  /** `true` while a loadMore page is in flight. */
+  readonly isLoadingMore: boolean;
+  /** Error from the last failed loadMore, or `null`. Cleared on retry. */
+  readonly loadMoreError: Error | null;
+  /** `true` only during the first head-page load. */
+  readonly isLoading: boolean;
+  /** `true` while the head page refreshes in the background. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed head-page fetch, or `null`. */
+  readonly error: Error | null;
+  /** Re-fetch the head page. */
+  readonly refetch: () => void;
+  /**
+   * Adopt a fresh row the server just returned — every participation
+   * command answers the post-command state, and that answer is newer
+   * than anything a poll already in flight will deliver (DD-012 D-a:
+   * your own action reflects immediately, zero polls involved). The row
+   * overrides the listed copy for exactly one round-trip: applying also
+   * starts a fresh head fetch, and the override is dropped when a page
+   * provably fetched after the apply answers.
+   */
+  readonly applyServerState: (fresh: ChannelConversation) => void;
+}
+
+interface HeadPage {
+  readonly items: readonly ChannelConversation[];
+  readonly totalCount: number;
+  /**
+   * The apply-sequence at the moment this fetch STARTED. The overlay
+   * (see {@link useConversationList}) may only be cleared by a page
+   * whose `seq` proves it observed the post-command server state.
+   */
+  readonly seq: number;
+}
+
+const EMPTY_HEAD: HeadPage = { items: [], totalCount: 0, seq: 0 };
+
+/** Rows adopted from command answers, waiting for the head to catch up. */
+interface Overlay {
+  readonly rows: ReadonlyMap<string, ChannelConversation>;
+  /** The apply-sequence of the newest apply in {@link rows}. */
+  readonly seq: number;
+}
+
+const EMPTY_OVERLAY: Overlay = { rows: new Map(), seq: 0 };
+
+function identityOf(conversation: ChannelConversation): string {
+  return `${conversation.agentChannelId}\u0000${conversation.conversationKey}`;
+}
+
+/** Activity instant in epoch milliseconds, for sorted overlay inserts. */
+function activityMillisOf(conversation: ChannelConversation): number {
+  const at = conversation.lastActivityAt;
+  if (!at) return 0;
+  return Number(at.seconds) * 1_000 + Math.floor(at.nanos / 1_000_000);
+}
+
+/**
+ * Data hook for the org-wide conversation list (channel-conversations
+ * DD-004): newest activity first across every channel the caller can
+ * view, optionally narrowed to one channel and/or a server-evaluated
+ * predicate ({@link ChannelConversationListFilter}).
+ *
+ * The head page rides `useFetch` and polls; older pages accumulate via
+ * {@link UseConversationListReturn.loadMore} and are merged with head
+ * precedence — the server's offset pagination shifts under live activity,
+ * so identity dedup (head copy wins: it is the fresher read) is what
+ * keeps a moving conversation from rendering twice.
+ *
+ * Command answers enter through
+ * {@link UseConversationListReturn.applyServerState} as a short-lived
+ * OVERLAY rather than a write into the fetched state, because `useFetch`
+ * has no write fence (the reason `useConversation` is hand-rolled): a
+ * poll answer already in the microtask queue when the command answers can
+ * commit AFTER the apply, and clearing the adopted row on "any head
+ * change" would hand the inbox back to pre-command state for a full poll
+ * period. Instead every head page is stamped with the apply-sequence at
+ * fetch start, and the overlay is dropped only when a page with
+ * `seq >= overlay.seq` — one provably started after the apply — answers.
+ * Applying triggers that fetch immediately, so the overlay lives for
+ * exactly one round-trip.
+ *
+ * Two honesty guards on overlay INSERTS (rows the server has not listed):
+ * a row from another channel never enters a channel-scoped list (identity
+ * equality — the same scope the hook sends to the server), and under a
+ * server-evaluated predicate filter the overlay is update-only, because
+ * the client cannot honestly claim membership the server has not
+ * asserted (the DD-011 A-1 one-predicate discipline). Updates in place
+ * are always honest: the server listed the row.
+ */
+export function useConversationList(
+  options: UseConversationListOptions,
+): UseConversationListReturn {
+  const {
+    org,
+    agentChannelId = "",
+    filter = ChannelConversationListFilter.channel_conversation_list_filter_unspecified,
+    pageSize = 50,
+  } = options;
+  const refetchIntervalMs =
+    options.refetchIntervalMs ?? CONVERSATION_LIST_POLL_INTERVAL_MS;
+  const stigmer = useStigmer();
+
+  // Monotonic count of applyServerState calls; head pages carry the
+  // value read at their fetch start (see HeadPage.seq).
+  const applySeqRef = useRef(0);
+
+  const fetchFn = org
+    ? async (): Promise<HeadPage> => {
+        const seq = applySeqRef.current;
+        const result = await stigmer.agentChannel.listConversations(
+          create(ListChannelConversationsInputSchema, {
+            org,
+            agentChannelId,
+            filter,
+            pageInfo: { num: 1, size: pageSize },
+          }),
+        );
+        return { items: result.items, totalCount: result.totalCount, seq };
+      }
+    : null;
+
+  const {
+    data: head,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  } = useFetch(
+    fetchFn,
+    [org, agentChannelId, filter, pageSize, stigmer],
+    EMPTY_HEAD,
+    {
+      refetchInterval: refetchIntervalMs,
+      // DD-012 D-a: returning to the tab is fresh.
+      refetchOnWindowFocus: true,
+    },
+  );
+
+  // Older pages, keyed by the same identity deps as the head fetch; the
+  // epoch fences in-flight loadMore answers across an identity change.
+  const [olderPages, setOlderPages] = useState<readonly ChannelConversation[][]>([]);
+  const [loadedThroughPage, setLoadedThroughPage] = useState(1);
+  const [isLoadingMore, setIsLoadingMore] = useState(false);
+  const [loadMoreError, setLoadMoreError] = useState<Error | null>(null);
+  const [overlay, setOverlay] = useState<Overlay>(EMPTY_OVERLAY);
+  const epochRef = useRef(0);
+
+  useEffect(() => {
+    epochRef.current += 1;
+    setOlderPages([]);
+    setLoadedThroughPage(1);
+    setIsLoadingMore(false);
+    setLoadMoreError(null);
+    setOverlay(EMPTY_OVERLAY);
+  }, [org, agentChannelId, filter, pageSize, stigmer]);
+
+  const applyServerState = useCallback(
+    (fresh: ChannelConversation) => {
+      const seq = ++applySeqRef.current;
+      setOverlay((current) => {
+        const rows = new Map(current.rows);
+        rows.set(identityOf(fresh), fresh);
+        return { rows, seq };
+      });
+      // Starts the round-trip that retires the overlay; also cancels any
+      // in-flight pre-command head fetch (useFetch's cleanup semantics).
+      refetch();
+    },
+    [refetch],
+  );
+
+  // Retire the overlay once a head page fetched after the newest apply
+  // answers — server truth has caught up. A page with an older stamp
+  // (the microtask-race case) keeps the overlay in force.
+  useEffect(() => {
+    if (overlay.rows.size === 0) return;
+    if (head.seq >= overlay.seq) setOverlay(EMPTY_OVERLAY);
+  }, [head, overlay]);
+
+  const loadMore = useCallback(() => {
+    if (!org || isLoadingMore) return;
+    const epoch = epochRef.current;
+    const nextPage = loadedThroughPage + 1;
+    setIsLoadingMore(true);
+    setLoadMoreError(null);
+
+    stigmer.agentChannel
+      .listConversations(
+        create(ListChannelConversationsInputSchema, {
+          org,
+          agentChannelId,
+          filter,
+          pageInfo: { num: nextPage, size: pageSize },
+        }),
+      )
+      .then(
+        (result) => {
+          if (epochRef.current !== epoch) return;
+          setOlderPages((pages) => [...pages, result.items]);
+          setLoadedThroughPage(nextPage);
+          setIsLoadingMore(false);
+        },
+        (err) => {
+          if (epochRef.current !== epoch) return;
+          setLoadMoreError(toError(err));
+          setIsLoadingMore(false);
+        },
+      );
+  }, [org, agentChannelId, filter, pageSize, stigmer, isLoadingMore, loadedThroughPage]);
+
+  const conversations = useMemo(() => {
+    const seen = new Set<string>();
+    const merged: ChannelConversation[] = [];
+    for (const conversation of [...head.items, ...olderPages.flat()]) {
+      const identity = identityOf(conversation);
+      if (seen.has(identity)) continue;
+      seen.add(identity);
+      // Update-in-place is always honest: the server listed this row.
+      merged.push(overlay.rows.get(identity) ?? conversation);
+    }
+    // Overlay rows the server has not listed: sorted insert (a command
+    // answer is not a recency claim — a takeover does not advance the
+    // activity clock, so head-of-list would misorder), subject to the
+    // two honesty guards documented on the hook.
+    for (const [identity, fresh] of overlay.rows) {
+      if (seen.has(identity)) continue;
+      if (
+        filter !==
+        ChannelConversationListFilter.channel_conversation_list_filter_unspecified
+      ) {
+        continue;
+      }
+      if (agentChannelId !== "" && fresh.agentChannelId !== agentChannelId) {
+        continue;
+      }
+      const at = activityMillisOf(fresh);
+      const index = merged.findIndex((c) => activityMillisOf(c) < at);
+      merged.splice(index === -1 ? merged.length : index, 0, fresh);
+      seen.add(identity);
+    }
+    return merged;
+  }, [head.items, olderPages, overlay, agentChannelId, filter]);
+
+  const hasMore = conversations.length < head.totalCount;
+
+  return useMemo(
+    () => ({
+      conversations,
+      totalCount: head.totalCount,
+      hasMore,
+      loadMore,
+      isLoadingMore,
+      loadMoreError,
+      isLoading,
+      isRefetching,
+      error,
+      refetch,
+      applyServerState,
+    }),
+    [
+      conversations,
+      head.totalCount,
+      hasMore,
+      loadMore,
+      isLoadingMore,
+      loadMoreError,
+      isLoading,
+      isRefetching,
+      error,
+      refetch,
+      applyServerState,
+    ],
+  );
+}