@stigmer/react 3.7.0 → 3.8.0

package/src/conversation/__tests__/useConversationTimeline.test.tsx

@@ -0,0 +1,258 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+
+// The focus-refetch test broadcasts window events, which reach EVERY
+// still-mounted hook in this file — including earlier tests' hooks whose
+// one-shot mock chains are exhausted. Unmount between tests so a window
+// broadcast only ever exercises the test that sent it.
+afterEach(cleanup);
+import { create } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import { ConversationTimelineItemSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { ChannelDeliveryStatus } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/delivery_pb";
+import { ChannelReceiptState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/outbound_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useConversationTimeline } from "../useConversationTimeline";
+
+function item(id: string, iso: string, overrides: Record<string, unknown> = {}) {
+  return create(ConversationTimelineItemSchema, {
+    itemId: id,
+    at: timestampFromDate(new Date(iso)),
+    text: `body of ${id}`,
+    ...overrides,
+  });
+}
+
+function createMockStigmer(getTimeline: (input: unknown) => Promise<unknown>) {
+  return { agentChannel: { getTimeline } } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  };
+}
+
+const NO_POLL = { refetchIntervalMs: false as const };
+
+describe("useConversationTimeline", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("serves the head page in chronological order — the server pages newest-first", async () => {
+    const getTimeline = vi.fn().mockResolvedValue({
+      items: [item("wa:3", "2026-08-07T09:02:00Z"), item("wa:1", "2026-08-07T09:00:00Z")],
+      nextPageToken: "",
+    });
+    const { result } = renderHook(
+      () => useConversationTimeline("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getTimeline)) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.items.map((i) => i.itemId)).toEqual(["wa:1", "wa:3"]);
+    expect(result.current.hasOlder).toBe(false);
+  });
+
+  it("loads older pages behind the cursor and never infers the end from a short page", async () => {
+    const getTimeline = vi
+      .fn()
+      .mockResolvedValueOnce({
+        items: [item("wa:9", "2026-08-07T09:09:00Z")],
+        nextPageToken: "cursor-1",
+      })
+      // A SHORT mid-history page with a live cursor: same-second bursts
+      // narrow pages, so only the empty token means the end.
+      .mockResolvedValueOnce({
+        items: [item("wa:5", "2026-08-07T09:05:00Z")],
+        nextPageToken: "cursor-2",
+      })
+      .mockResolvedValueOnce({
+        items: [item("wa:1", "2026-08-07T09:01:00Z")],
+        nextPageToken: "",
+      });
+
+    const { result } = renderHook(
+      () => useConversationTimeline("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getTimeline)) },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.hasOlder).toBe(true);
+
+    act(() => result.current.loadOlder());
+    await waitFor(() => expect(result.current.isLoadingOlder).toBe(false));
+    expect(result.current.items.map((i) => i.itemId)).toEqual(["wa:5", "wa:9"]);
+    expect(result.current.hasOlder).toBe(true);
+    expect(getTimeline).toHaveBeenLastCalledWith(
+      expect.objectContaining({ pageToken: "cursor-1" }),
+    );
+
+    act(() => result.current.loadOlder());
+    await waitFor(() => expect(result.current.isLoadingOlder).toBe(false));
+    expect(result.current.items.map((i) => i.itemId)).toEqual(["wa:1", "wa:5", "wa:9"]);
+    expect(result.current.hasOlder).toBe(false);
+  });
+
+  it("keeps items that slide out of the polled head window — nothing ever vanishes mid-scroll", async () => {
+    const getTimeline = vi
+      .fn()
+      .mockResolvedValueOnce({
+        items: [item("wa:2", "2026-08-07T09:02:00Z"), item("wa:1", "2026-08-07T09:01:00Z")],
+        nextPageToken: "",
+      })
+      // The refreshed head window has shifted entirely to newer items;
+      // wa:1 and wa:2 are in no loaded page anymore.
+      .mockResolvedValueOnce({
+        items: [item("wa:4", "2026-08-07T09:04:00Z"), item("wa:3", "2026-08-07T09:03:00Z")],
+        nextPageToken: "cursor-x",
+      });
+
+    const { result } = renderHook(
+      () => useConversationTimeline("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getTimeline)) },
+    );
+    await waitFor(() => expect(result.current.items).toHaveLength(2));
+
+    act(() => result.current.refetch());
+    await waitFor(() => expect(result.current.items).toHaveLength(4));
+
+    expect(result.current.items.map((i) => i.itemId)).toEqual([
+      "wa:1",
+      "wa:2",
+      "wa:3",
+      "wa:4",
+    ]);
+    // The older cursor stays anchored to the FIRST head page: it tracks
+    // scroll depth into history, not the shifting head window.
+    expect(result.current.hasOlder).toBe(false);
+  });
+
+  it("upserts mutated statuses in place — delivery and receipt ticks advance on poll", async () => {
+    const sent = item("ob:1", "2026-08-07T09:00:00Z", {
+      deliveryStatus: ChannelDeliveryStatus.delivered,
+      receiptState: ChannelReceiptState.receipt_sent,
+    });
+    const read = item("ob:1", "2026-08-07T09:00:00Z", {
+      deliveryStatus: ChannelDeliveryStatus.delivered,
+      receiptState: ChannelReceiptState.receipt_read,
+    });
+    const getTimeline = vi
+      .fn()
+      .mockResolvedValueOnce({ items: [sent], nextPageToken: "" })
+      .mockResolvedValueOnce({ items: [read], nextPageToken: "" });
+
+    const { result } = renderHook(
+      () => useConversationTimeline("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getTimeline)) },
+    );
+    await waitFor(() => expect(result.current.items).toHaveLength(1));
+    expect(result.current.items[0].receiptState).toBe(ChannelReceiptState.receipt_sent);
+
+    act(() => result.current.refetch());
+    await waitFor(() =>
+      expect(result.current.items[0].receiptState).toBe(ChannelReceiptState.receipt_read),
+    );
+    expect(result.current.items).toHaveLength(1);
+  });
+
+  it("keeps item and list references stable across polls that change nothing (DD-010)", async () => {
+    const getTimeline = vi.fn().mockImplementation(() =>
+      Promise.resolve({
+        // Fresh-but-equal proto objects every call, like a real poll.
+        items: [item("wa:1", "2026-08-07T09:00:00Z")],
+        nextPageToken: "",
+      }),
+    );
+    const { result } = renderHook(
+      () => useConversationTimeline("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getTimeline)) },
+    );
+    await waitFor(() => expect(result.current.items).toHaveLength(1));
+    const firstItems = result.current.items;
+
+    act(() => result.current.refetch());
+    await waitFor(() => expect(result.current.isRefetching).toBe(false));
+
+    expect(result.current.items).toBe(firstItems);
+  });
+
+  it("resets on identity change so conversation A's thread never flashes under B", async () => {
+    const getTimeline = vi
+      .fn()
+      .mockResolvedValueOnce({
+        items: [item("wa:1", "2026-08-07T09:00:00Z")],
+        nextPageToken: "cursor-a",
+      })
+      .mockReturnValue(new Promise(() => {}));
+
+    const { result, rerender } = renderHook(
+      ({ key }: { key: string }) => useConversationTimeline("ach_1", key, NO_POLL),
+      {
+        wrapper: wrapper(createMockStigmer(getTimeline)),
+        initialProps: { key: "15550001111" },
+      },
+    );
+    await waitFor(() => expect(result.current.items).toHaveLength(1));
+
+    rerender({ key: "15550002222" });
+
+    expect(result.current.items).toHaveLength(0);
+    expect(result.current.hasOlder).toBe(false);
+  });
+
+  it("refetches the head when the window regains focus (DD-012: refocus is fresh)", async () => {
+    const getTimeline = vi.fn().mockResolvedValue({ items: [], nextPageToken: "" });
+    renderHook(() => useConversationTimeline("ach_1", "15550001111", NO_POLL), {
+      wrapper: wrapper(createMockStigmer(getTimeline)),
+    });
+    await waitFor(() => expect(getTimeline).toHaveBeenCalledTimes(1));
+
+    await act(async () => {
+      window.dispatchEvent(new Event("focus"));
+    });
+
+    await waitFor(() => expect(getTimeline).toHaveBeenCalledTimes(2));
+  });
+
+  it("skips fetching for empty identity (stable no-op)", async () => {
+    const getTimeline = vi.fn();
+    const { result } = renderHook(() => useConversationTimeline("", "", NO_POLL), {
+      wrapper: wrapper(createMockStigmer(getTimeline)),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(getTimeline).not.toHaveBeenCalled();
+  });
+
+  it("records a loadOlder failure beside the control, leaving the loaded thread intact", async () => {
+    const getTimeline = vi
+      .fn()
+      .mockResolvedValueOnce({
+        items: [item("wa:1", "2026-08-07T09:00:00Z")],
+        nextPageToken: "cursor-1",
+      })
+      .mockRejectedValueOnce(new Error("boom"));
+
+    const { result } = renderHook(
+      () => useConversationTimeline("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getTimeline)) },
+    );
+    await waitFor(() => expect(result.current.items).toHaveLength(1));
+
+    act(() => result.current.loadOlder());
+    await waitFor(() => expect(result.current.loadOlderError).not.toBeNull());
+
+    expect(result.current.items).toHaveLength(1);
+    expect(result.current.error).toBeNull();
+    expect(result.current.hasOlder).toBe(true);
+  });
+});

package/src/conversation/__tests__/useConversationsWantsHumanCount.test.tsx

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { ChannelConversationListFilter } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useConversationsWantsHumanCount } from "../useConversationsWantsHumanCount";
+
+// The focus-refetch test broadcasts window events, which reach EVERY
+// still-mounted hook in this file. Unmount between tests so a window
+// broadcast only ever exercises the test that sent it.
+afterEach(cleanup);
+
+function createMockStigmer(listConversations: (input: unknown) => Promise<unknown>) {
+  return { agentChannel: { listConversations } } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  };
+}
+
+const NO_POLL = { refetchIntervalMs: false as const };
+
+describe("useConversationsWantsHumanCount", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("reads the filtered list's total_count with a one-row page — zero dedicated RPCs (DD-011 D-g)", async () => {
+    const listConversations = vi
+      .fn()
+      .mockResolvedValue({ items: [], totalCount: 7 });
+    const { result } = renderHook(
+      () => useConversationsWantsHumanCount("acme", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(listConversations)) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.count).toBe(7);
+    expect(listConversations).toHaveBeenCalledWith(
+      expect.objectContaining({
+        org: "acme",
+        filter: ChannelConversationListFilter.filter_wants_human,
+        pageInfo: expect.objectContaining({ num: 1, size: 1 }),
+      }),
+    );
+  });
+
+  it("skips fetching without an org and answers zero", async () => {
+    const listConversations = vi.fn();
+    const { result } = renderHook(
+      () => useConversationsWantsHumanCount(null, NO_POLL),
+      { wrapper: wrapper(createMockStigmer(listConversations)) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(listConversations).not.toHaveBeenCalled();
+    expect(result.current.count).toBe(0);
+  });
+
+  it("keeps the stale count visible through a failed refresh — a flapping badge teaches distrust", async () => {
+    const listConversations = vi
+      .fn()
+      .mockResolvedValueOnce({ items: [], totalCount: 4 })
+      .mockRejectedValueOnce(new Error("boom"));
+    const { result } = renderHook(
+      () => useConversationsWantsHumanCount("acme", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(listConversations)) },
+    );
+    await waitFor(() => expect(result.current.count).toBe(4));
+
+    act(() => result.current.refetch());
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+
+    expect(result.current.count).toBe(4);
+  });
+
+  it("refetches when the window regains focus (DD-012: refocus is fresh)", async () => {
+    const listConversations = vi
+      .fn()
+      .mockResolvedValue({ items: [], totalCount: 2 });
+    renderHook(() => useConversationsWantsHumanCount("acme", NO_POLL), {
+      wrapper: wrapper(createMockStigmer(listConversations)),
+    });
+    await waitFor(() => expect(listConversations).toHaveBeenCalledTimes(1));
+
+    await act(async () => {
+      window.dispatchEvent(new Event("focus"));
+    });
+
+    await waitFor(() => expect(listConversations).toHaveBeenCalledTimes(2));
+  });
+});

package/src/conversation/conversationPresentation.ts

@@ -0,0 +1,305 @@
+import { timestampDate, type Timestamp } from "@bufbuild/protobuf/wkt";
+import {
+  type ChannelConversation,
+  ConversationControl,
+  ConversationItemAuthor,
+  ConversationLane,
+  type ConversationTimelineItem,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { ChannelDeliveryStatus } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/delivery_pb";
+import { ChannelReceiptState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/outbound_pb";
+import type { ChannelProviderId } from "../channel/providers.js";
+
+/**
+ * Pure render vocabulary for the conversation surface — the single place
+ * the wire enums become words and layout facts (the providerPresentation
+ * convention). No React, no I/O; every component and every test reads the
+ * same mapping.
+ */
+
+/** Who authored a timeline item, in render vocabulary. */
+export type ConversationAuthorKind =
+  | "customer"
+  | "agent"
+  | "teammate"
+  | "platform"
+  | "unknown";
+
+/** Map the wire author onto the render vocabulary. */
+export function authorKindOf(item: ConversationTimelineItem): ConversationAuthorKind {
+  switch (item.author) {
+    case ConversationItemAuthor.author_customer:
+      return "customer";
+    case ConversationItemAuthor.author_agent:
+      return "agent";
+    case ConversationItemAuthor.author_teammate:
+      return "teammate";
+    case ConversationItemAuthor.author_platform:
+      return "platform";
+    default:
+      return "unknown";
+  }
+}
+
+/** True for org-internal items (escalations, attention clears, notes). */
+export function isInternalItem(item: ConversationTimelineItem): boolean {
+  return item.lane === ConversationLane.lane_internal;
+}
+
+/**
+ * The platform's own send attempt, in render vocabulary. `null` on items
+ * that carry no attempt (inbound messages, internal events).
+ *
+ * `"suppressed"` and `"failed"` are items the customer NEVER saw and
+ * `"pending"`/`"delivering"` are items the customer has not seen YET —
+ * a renderer that shows any of them as a plain sent bubble lies to staff.
+ */
+export type SendAttemptKind =
+  | "pending"
+  | "delivering"
+  | "delivered"
+  | "failed"
+  | "suppressed";
+
+/** Map the wire delivery status onto the render vocabulary. */
+export function sendAttemptOf(item: ConversationTimelineItem): SendAttemptKind | null {
+  switch (item.deliveryStatus) {
+    case ChannelDeliveryStatus.pending:
+      return "pending";
+    case ChannelDeliveryStatus.delivering:
+      return "delivering";
+    case ChannelDeliveryStatus.delivered:
+      return "delivered";
+    case ChannelDeliveryStatus.failed:
+      return "failed";
+    case ChannelDeliveryStatus.suppressed:
+      return "suppressed";
+    default:
+      return null;
+  }
+}
+
+/**
+ * The provider's receipt report, in render vocabulary. `null` until the
+ * provider reports (and always on items with no receipt axis).
+ *
+ * A SECOND axis beside {@link sendAttemptOf}, never collapsed into it
+ * (channel-conversations DD-004 D-d): "we handed it to WhatsApp" and
+ * "it reached the phone" are different facts — an item can be
+ * `delivered` + `receipt_failed`.
+ */
+export type ReceiptKind = "sent" | "delivered" | "read" | "failed";
+
+/** Map the wire receipt state onto the render vocabulary. */
+export function receiptOf(item: ConversationTimelineItem): ReceiptKind | null {
+  switch (item.receiptState) {
+    case ChannelReceiptState.receipt_sent:
+      return "sent";
+    case ChannelReceiptState.receipt_delivered:
+      return "delivered";
+    case ChannelReceiptState.receipt_read:
+      return "read";
+    case ChannelReceiptState.receipt_failed:
+      return "failed";
+    default:
+      return null;
+  }
+}
+
+/**
+ * Placeholder copy for inbound items whose body the platform cannot
+ * render (`text` empty, `provider_message_type` names the kind). Media
+ * retrieval is a named non-goal of this surface — the placeholder tells
+ * staff something arrived and what shape it was.
+ *
+ * Returns `null` when the item needs no placeholder (it has text, or it
+ * is not a provider-typed inbound item — e.g. an attention-clear event,
+ * whose copy is the renderer's own vocabulary).
+ */
+export function inboundPlaceholderOf(item: ConversationTimelineItem): string | null {
+  if (item.text !== "" || item.providerMessageType === "") return null;
+  switch (item.providerMessageType) {
+    case "text":
+      return null;
+    case "image":
+      return "Photo";
+    case "video":
+      return "Video";
+    case "audio":
+      return "Voice message";
+    case "document":
+      return "Document";
+    case "sticker":
+      return "Sticker";
+    case "location":
+      return "Location";
+    case "contacts":
+      return "Contact card";
+    default:
+      // The provider's vocabulary passes through verbatim (never
+      // re-encoded), so an unknown kind still names itself.
+      return `Unsupported message (${item.providerMessageType})`;
+  }
+}
+
+/**
+ * The list-row label for a conversation: the provider-reported display
+ * name when one exists, else a provider-aware fallback.
+ *
+ * The fallback is provider-aware because conversation keys are not
+ * uniformly meaningful: WhatsApp's key is the customer's phone number
+ * (a real label), while Slack's key is a thread timestamp like
+ * `1723012345.678900` (noise a human cannot use).
+ */
+export function conversationLabelOf(
+  conversation: ChannelConversation,
+  provider: ChannelProviderId | null,
+): string {
+  if (conversation.displayName !== "") return conversation.displayName;
+  if (provider === "slack") return "Slack thread";
+  return conversation.conversationKey;
+}
+
+/**
+ * The customer's reachable address, when the label hides it: the fact a
+ * staffer needs to call or message the customer outside the platform.
+ *
+ * Provider-aware like {@link conversationLabelOf}, because conversation
+ * keys are not uniformly addresses: WhatsApp's key IS the customer's
+ * phone number (the wa_id), and when a display name wins the label slot
+ * that number would otherwise appear nowhere on the surface. Slack's
+ * key is a thread timestamp — not a way to reach anyone — so there is
+ * nothing to show. Unknown providers show nothing rather than guess.
+ *
+ * Returns `null` when the label already shows the key (no display
+ * name), so the same fact never renders twice. The key returns
+ * verbatim — no fabricated `+` prefix: the wire value is the truth this
+ * module reports, and formatting belongs to hosts that know their
+ * display rules.
+ */
+export function conversationContactOf(
+  conversation: ChannelConversation,
+  provider: ChannelProviderId | null,
+): string | null {
+  if (provider !== "whatsapp") return null;
+  if (conversation.displayName === "") return null;
+  return conversation.conversationKey;
+}
+
+/**
+ * Meta's customer-service window: a business can send free-form WhatsApp
+ * messages for 24 hours after the customer's last inbound message; after
+ * that, only template messages deliver. The constant lives beside its
+ * only consumer and is promoted to `ChannelProviderDescriptor` only if a
+ * second windowed provider ever appears (the second-sighting rule,
+ * DD-014 D-a).
+ */
+const WHATSAPP_SERVICE_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/** The service-window estimate, in render vocabulary. */
+export type ServiceWindowState = "open" | "closed";
+
+/**
+ * Estimate whether the provider's free-form reply window is open
+ * (channel-conversations DD-014 D-a). Provider-aware like
+ * {@link conversationLabelOf}: WhatsApp is the only windowed provider, so
+ * every other provider answers `null` — no window, no claim — as does a
+ * conversation whose customer has never written
+ * (`last_customer_message_at` unset; that conversation takes the
+ * composer's disabled branch instead).
+ *
+ * Client-derived on purpose, and NOT a divergence from DD-011 A-1's
+ * "the predicate is expressed once, in SQL" rule: the window is
+ * wall-clock-anchored — it flips with NO row change — so a
+ * server-computed boolean would be stale by construction between polls.
+ * Time-decaying presentation derived from wire instants is this
+ * surface's established class (relative timestamps, day grouping).
+ *
+ * Honesty caveat (DD-014 D-a): the anchor is the platform's receipt
+ * instant, minutes AFTER Meta's own clock started the window, so the
+ * estimate can claim "open" briefly after Meta closed it — which is why
+ * consumers warn and never block (D-b). For the same reason the exact
+ * 24-hour tie reads "closed": erring a moment early offsets an anchor
+ * that always errs late.
+ */
+export function serviceWindowOf(
+  conversation: ChannelConversation,
+  provider: ChannelProviderId | null,
+  now: Date,
+): ServiceWindowState | null {
+  if (provider !== "whatsapp") return null;
+  const anchor = conversation.lastCustomerMessageAt;
+  if (anchor === undefined) return null;
+  const elapsedMs = now.getTime() - timestampDate(anchor).getTime();
+  return elapsedMs >= WHATSAPP_SERVICE_WINDOW_MS ? "closed" : "open";
+}
+
+/**
+ * How strongly the awaiting-reply indicator renders. Two strengths, not
+ * one, because "waiting" means different things per holder (DD-011 D-a).
+ */
+export type AwaitingIndicator = "strong" | "muted";
+
+/**
+ * The awaiting-reply indicator for a conversation (channel-conversations
+ * DD-011 D-a): `"strong"` when a human holds it — the agent will not
+ * answer, so a person must (F-13's exact case) — and `"muted"` when the
+ * agent holds it: the agent is about to answer, and if its turn dies the
+ * conversation stays visibly waiting, which is the built-in recovery
+ * path (DD-011 D-b). `null` when the customer's last message has been
+ * answered (or the customer has not written).
+ *
+ * The fact itself is server-derived (`awaiting_reply` rides the wire as
+ * a boolean precisely so no client re-implements the NULL-and-compare
+ * rule); this helper only maps fact × holder onto render strength.
+ */
+export function awaitingIndicatorOf(
+  conversation: ChannelConversation,
+): AwaitingIndicator | null {
+  if (!conversation.awaitingReply) return null;
+  return conversation.control === ConversationControl.control_human
+    ? "strong"
+    : "muted";
+}
+
+/**
+ * The timeline item id an accepted staff reply appears under: the
+ * outbound ledger's `ob:` namespace over the reply output's
+ * `outbound_message_id` — the contract
+ * `useConversationParticipation.reply` documents ("the item will
+ * appear on the timeline as `ob:<that id>`"). The workbench's
+ * post-send busy state watches for exactly this id (F-05).
+ */
+export function outboundItemIdOf(outboundMessageId: string): string {
+  return `ob:${outboundMessageId}`;
+}
+
+/**
+ * Newest-first timeline order: `(at, item_id)` descending — the exact
+ * comparator the server pages with, so client-side merges can never
+ * disagree with server pages about order.
+ */
+export function compareTimelineItemsNewestFirst(
+  a: ConversationTimelineItem,
+  b: ConversationTimelineItem,
+): number {
+  const byInstant = compareInstants(b.at, a.at);
+  if (byInstant !== 0) return byInstant;
+  return a.itemId < b.itemId ? 1 : a.itemId > b.itemId ? -1 : 0;
+}
+
+// BigInt() call form, not a 0n literal: the web console compiles SDK
+// sources under a pre-ES2020 target where the literal is a syntax error.
+const ZERO_SECONDS = BigInt(0);
+
+function compareInstants(a: Timestamp | undefined, b: Timestamp | undefined): number {
+  // A missing instant sorts oldest — the server always stamps `at`, so
+  // this only orders a defensively-handled corrupt item to the top of
+  // history rather than crashing the sort.
+  const aSeconds = a?.seconds ?? ZERO_SECONDS;
+  const bSeconds = b?.seconds ?? ZERO_SECONDS;
+  if (aSeconds !== bSeconds) return aSeconds < bSeconds ? -1 : 1;
+  const aNanos = a?.nanos ?? 0;
+  const bNanos = b?.nanos ?? 0;
+  return aNanos - bNanos;
+}