@stigmer/react 3.7.0 → 3.8.0

package/src/conversation/useConversationParticipation.ts

@@ -0,0 +1,178 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import type {
+  ChannelConversation,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import {
+  ConversationControlInputSchema,
+  GetChannelConversationInputSchema,
+  ReplyToConversationInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import type { SendChannelMessageOutput } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import { useCallback, useMemo } from "react";
+import { useStigmer } from "../hooks.js";
+import { useKeyedSubmission } from "../internal/useKeyedSubmission.js";
+
+/** The four staff-facing participation commands. */
+export type ConversationCommand = "reply" | "takeOver" | "handBack" | "clearAttention";
+
+/** Options for {@link useConversationParticipation}. */
+export interface UseConversationParticipationOptions {
+  /** AgentChannel the conversation belongs to. */
+  readonly agentChannelId: string;
+  /** Conversation key within the channel. */
+  readonly conversationKey: string;
+  /**
+   * Receives the fresh conversation row every command answers with —
+   * wire it to {@link useConversation}'s `applyServerState` so banners
+   * and controls adopt server truth immediately. Called for reply too
+   * (via a follow-up row read): a staff reply implicitly takes over
+   * BEFORE the send, unconditionally, so control has moved even when
+   * the send itself was refused.
+   */
+  readonly onConversation?: (fresh: ChannelConversation) => void;
+}
+
+/** Return value of {@link useConversationParticipation}. */
+export interface UseConversationParticipationReturn {
+  /**
+   * Send a staff text reply. Resolves with the truthful outcome of the
+   * inline attempt: `accepted` (with `outboundMessageId` — the item will
+   * appear on the timeline as `ob:<that id>`), `queued`, or `refused`.
+   * A `refused` outcome WITHOUT an `outboundMessageId` left no ledger
+   * row and no timeline item will ever exist for it.
+   */
+  readonly reply: (text: string) => Promise<SendChannelMessageOutput>;
+  /**
+   * Take the conversation over: the agent goes quiet until handBack.
+   * Resolves with the fresh row — for the LOSER of a concurrent
+   * takeover too (success-with-the-winner's-state, never an error), so
+   * compare `controlledBy` against the caller rather than assuming the
+   * transition won.
+   */
+  readonly takeOver: () => Promise<ChannelConversation>;
+  /** Hand the conversation back to the agent. */
+  readonly handBack: () => Promise<ChannelConversation>;
+  /** Dismiss the needs-attention flag in place; control is untouched. */
+  readonly clearAttention: () => Promise<ChannelConversation>;
+  /** Commands currently in flight. */
+  readonly pendingCommands: ReadonlySet<ConversationCommand>;
+  /** Per-command failures, cleared when that command is retried. */
+  readonly commandErrors: ReadonlyMap<ConversationCommand, Error>;
+  /** Reset every recorded command error. */
+  readonly clearErrors: () => void;
+}
+
+/**
+ * Behavior hook for the participation commands on one conversation
+ * (channel-conversations DD-005/DD-007/DD-008/DD-009): reply, takeOver,
+ * handBack, clearAttention — each keyed independently so a slow reply
+ * and a takeover can be in flight at once with attributable spinners
+ * and errors.
+ *
+ * Every command re-throws its failure after recording it in
+ * {@link UseConversationParticipationReturn.commandErrors}, so callers
+ * choose the propagation (await-and-toast, or ignore and render the
+ * keyed error inline).
+ */
+export function useConversationParticipation(
+  options: UseConversationParticipationOptions,
+): UseConversationParticipationReturn {
+  const { agentChannelId, conversationKey, onConversation } = options;
+  const stigmer = useStigmer();
+  const submission = useKeyedSubmission<unknown>();
+  const { run } = submission;
+
+  const controlInput = useCallback(
+    () => create(ConversationControlInputSchema, { agentChannelId, conversationKey }),
+    [agentChannelId, conversationKey],
+  );
+
+  const takeOver = useCallback(
+    () =>
+      run("takeOver", async () => {
+        const fresh = await stigmer.agentChannel.takeOver(controlInput());
+        onConversation?.(fresh);
+        return fresh;
+      }) as Promise<ChannelConversation>,
+    [run, stigmer, controlInput, onConversation],
+  );
+
+  const handBack = useCallback(
+    () =>
+      run("handBack", async () => {
+        const fresh = await stigmer.agentChannel.handBack(controlInput());
+        onConversation?.(fresh);
+        return fresh;
+      }) as Promise<ChannelConversation>,
+    [run, stigmer, controlInput, onConversation],
+  );
+
+  const clearAttention = useCallback(
+    () =>
+      run("clearAttention", async () => {
+        const fresh = await stigmer.agentChannel.clearAttention(controlInput());
+        onConversation?.(fresh);
+        return fresh;
+      }) as Promise<ChannelConversation>,
+    [run, stigmer, controlInput, onConversation],
+  );
+
+  const reply = useCallback(
+    (text: string) =>
+      run("reply", async () => {
+        const output = await stigmer.agentChannel.reply(
+          create(ReplyToConversationInputSchema, {
+            agentChannelId,
+            conversationKey,
+            payload: { kind: { case: "text", value: { body: text } } },
+          }),
+        );
+        // The implicit takeover flipped control BEFORE the send ran —
+        // even a refused reply moved it — but reply answers the send
+        // outcome, not the row. One follow-up read keeps the control
+        // banner honest without waiting a poll tick. Best-effort: a
+        // failed read only delays the banner until the next poll.
+        if (onConversation) {
+          try {
+            onConversation(
+              await stigmer.agentChannel.getConversation(
+                create(GetChannelConversationInputSchema, {
+                  agentChannelId,
+                  conversationKey,
+                }),
+              ),
+            );
+          } catch {
+            // The reply itself succeeded; the poll will catch the row up.
+          }
+        }
+        return output;
+      }) as Promise<SendChannelMessageOutput>,
+    [run, stigmer, agentChannelId, conversationKey, onConversation],
+  );
+
+  return useMemo(
+    () => ({
+      reply,
+      takeOver,
+      handBack,
+      clearAttention,
+      // The submission primitive keys by string; this hook only ever
+      // submits the four command names, so the narrowing is sound.
+      pendingCommands: submission.submittingKeys as ReadonlySet<ConversationCommand>,
+      commandErrors: submission.errorsByKey as ReadonlyMap<ConversationCommand, Error>,
+      clearErrors: submission.clearErrors,
+    }),
+    [
+      reply,
+      takeOver,
+      handBack,
+      clearAttention,
+      submission.submittingKeys,
+      submission.errorsByKey,
+      submission.clearErrors,
+    ],
+  );
+}

package/src/conversation/useConversationTimeline.ts

@@ -0,0 +1,244 @@
+"use client";
+
+import { create, equals } from "@bufbuild/protobuf";
+import type { ConversationTimelineItem } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import {
+  ConversationTimelineItemSchema,
+  GetConversationTimelineInputSchema,
+} 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 { compareTimelineItemsNewestFirst } from "./conversationPresentation.js";
+import { CONVERSATION_DETAIL_POLL_INTERVAL_MS } from "./polling.js";
+
+/** Options for {@link useConversationTimeline}. */
+export interface UseConversationTimelineOptions {
+  /** Items per page, for the polled head and each loadOlder page. Default 50. */
+  readonly pageSize?: number;
+  /**
+   * Poll interval in milliseconds; `false` disables polling. Defaults to
+   * {@link CONVERSATION_DETAIL_POLL_INTERVAL_MS}. Only the head page
+   * polls — it is where new items land and where recent items' delivery
+   * and receipt states still move.
+   */
+  readonly refetchIntervalMs?: number | false;
+}
+
+/** Return value of {@link useConversationTimeline}. */
+export interface UseConversationTimelineReturn {
+  /**
+   * Every item seen so far, in chronological (oldest → newest) order —
+   * the render order of a chat view. Items are never dropped: the polled
+   * head window may shift as new messages land, and an item that slides
+   * out of it stays here rather than vanishing mid-scroll.
+   */
+  readonly items: readonly ConversationTimelineItem[];
+  /**
+   * `true` while older history exists beyond what is loaded. Decided
+   * ONLY by the server's cursor — a short page mid-history is normal
+   * (same-second bursts narrow pages) and never means the end.
+   */
+  readonly hasOlder: boolean;
+  /** Load the next older page. No-op while one is already loading. */
+  readonly loadOlder: () => void;
+  /** `true` while a loadOlder page is in flight. */
+  readonly isLoadingOlder: boolean;
+  /** Error from the last failed loadOlder, or `null`. Cleared on retry. */
+  readonly loadOlderError: 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;
+}
+
+interface HeadPage {
+  readonly items: readonly ConversationTimelineItem[];
+  readonly nextPageToken: string;
+}
+
+const EMPTY_HEAD: HeadPage = { items: [], nextPageToken: "" };
+
+/**
+ * Data hook for one conversation's customer-visible timeline
+ * (channel-conversations DD-004): newest-first cursor pages from the
+ * server, accumulated into one chronological list for a chat view.
+ *
+ * The accumulation is an UPSERT by `item_id`, not head/tail
+ * concatenation, for two verified server behaviors:
+ *
+ * - Item instants are stable but STATUSES mutate in place — an outbound
+ *   item's delivery status and receipt ticks advance after it first
+ *   renders. Each head poll re-upserts the newest window, so those
+ *   fields stay live without any diffing protocol.
+ * - The head window SHIFTS as new items land. Items that slide out of
+ *   it are not in any loaded older page (older cursors are anchored
+ *   below the original head), so concatenation would silently drop
+ *   them; the upsert map keeps everything ever seen.
+ *
+ * The older cursor is captured from the FIRST head page only: later
+ * head refreshes serve the top of the timeline, while the cursor tracks
+ * how deep into history the consumer has scrolled — two independent
+ * frontiers. Receipt ticks on items deeper than the head window can go
+ * stale until the conversation is reopened; accepted for v1 (the T05
+ * liveness seam is where per-item freshness lands).
+ *
+ * Pass empty strings to skip fetching (the `null`-fetchFn convention).
+ */
+export function useConversationTimeline(
+  agentChannelId: string,
+  conversationKey: string,
+  options?: UseConversationTimelineOptions,
+): UseConversationTimelineReturn {
+  const pageSize = options?.pageSize ?? 50;
+  const refetchIntervalMs =
+    options?.refetchIntervalMs ?? CONVERSATION_DETAIL_POLL_INTERVAL_MS;
+  const stigmer = useStigmer();
+
+  const enabled = agentChannelId !== "" && conversationKey !== "";
+
+  const fetchFn = enabled
+    ? async (): Promise<HeadPage> => {
+        const result = await stigmer.agentChannel.getTimeline(
+          create(GetConversationTimelineInputSchema, {
+            agentChannelId,
+            conversationKey,
+            pageSize,
+          }),
+        );
+        return { items: result.items, nextPageToken: result.nextPageToken };
+      }
+    : null;
+
+  const {
+    data: head,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  } = useFetch(fetchFn, [agentChannelId, conversationKey, pageSize, stigmer], EMPTY_HEAD, {
+    refetchInterval: refetchIntervalMs,
+    // DD-012 D-a: returning to the tab is fresh (the head re-upserts, so
+    // a focus refetch can never disturb accumulated history).
+    refetchOnWindowFocus: true,
+  });
+
+  // Everything ever seen for this conversation, by item id.
+  const [known, setKnown] = useState<ReadonlyMap<string, ConversationTimelineItem>>(
+    new Map(),
+  );
+  // The older-history frontier: null until the first head page answers,
+  // "" once history is exhausted, otherwise the next older cursor.
+  const [olderCursor, setOlderCursor] = useState<string | null>(null);
+  const [isLoadingOlder, setIsLoadingOlder] = useState(false);
+  const [loadOlderError, setLoadOlderError] = useState<Error | null>(null);
+  const epochRef = useRef(0);
+
+  useEffect(() => {
+    epochRef.current += 1;
+    setKnown(new Map());
+    setOlderCursor(null);
+    setIsLoadingOlder(false);
+    setLoadOlderError(null);
+  }, [agentChannelId, conversationKey, pageSize, stigmer]);
+
+  // Fold each head page into the map. `head` is referentially fresh per
+  // fetch, so this runs exactly once per answer.
+  useEffect(() => {
+    if (head === EMPTY_HEAD) return;
+    setKnown((current) => upsert(current, head.items));
+    setOlderCursor((current) => (current === null ? head.nextPageToken : current));
+  }, [head]);
+
+  const loadOlder = useCallback(() => {
+    if (!enabled || isLoadingOlder || !olderCursor) return;
+    const epoch = epochRef.current;
+    setIsLoadingOlder(true);
+    setLoadOlderError(null);
+
+    stigmer.agentChannel
+      .getTimeline(
+        create(GetConversationTimelineInputSchema, {
+          agentChannelId,
+          conversationKey,
+          pageSize,
+          pageToken: olderCursor,
+        }),
+      )
+      .then(
+        (result) => {
+          if (epochRef.current !== epoch) return;
+          setKnown((current) => upsert(current, result.items));
+          setOlderCursor(result.nextPageToken);
+          setIsLoadingOlder(false);
+        },
+        (err) => {
+          if (epochRef.current !== epoch) return;
+          setLoadOlderError(toError(err));
+          setIsLoadingOlder(false);
+        },
+      );
+  }, [enabled, isLoadingOlder, olderCursor, agentChannelId, conversationKey, pageSize, stigmer]);
+
+  const items = useMemo(
+    () =>
+      Array.from(known.values())
+        .sort(compareTimelineItemsNewestFirst)
+        .reverse(),
+    [known],
+  );
+
+  const hasOlder = olderCursor !== null && olderCursor !== "";
+
+  return useMemo(
+    () => ({
+      items,
+      hasOlder,
+      loadOlder,
+      isLoadingOlder,
+      loadOlderError,
+      isLoading,
+      isRefetching,
+      error,
+      refetch,
+    }),
+    [
+      items,
+      hasOlder,
+      loadOlder,
+      isLoadingOlder,
+      loadOlderError,
+      isLoading,
+      isRefetching,
+      error,
+      refetch,
+    ],
+  );
+}
+
+/**
+ * Fold a page into the map, preserving references: a poll returns fresh
+ * proto objects even when nothing changed, and swapping equal items
+ * would defeat `React.memo` on every row every poll tick (DD-010 —
+ * reference stability is architectural, not an optimization). An
+ * unchanged page returns the SAME map, so the sorted `items` memo does
+ * not even re-run.
+ */
+function upsert(
+  current: ReadonlyMap<string, ConversationTimelineItem>,
+  incoming: readonly ConversationTimelineItem[],
+): ReadonlyMap<string, ConversationTimelineItem> {
+  let next: Map<string, ConversationTimelineItem> | null = null;
+  for (const item of incoming) {
+    const existing = current.get(item.itemId);
+    if (existing && equals(ConversationTimelineItemSchema, existing, item)) continue;
+    next ??= new Map(current);
+    next.set(item.itemId, item);
+  }
+  return next ?? current;
+}

package/src/conversation/useConversationsWantsHumanCount.ts

@@ -0,0 +1,86 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import {
+  ChannelConversationListFilter,
+  ListChannelConversationsInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { useMemo } from "react";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+import { CONVERSATION_BADGE_POLL_INTERVAL_MS } from "./polling.js";
+
+/** Options for {@link useConversationsWantsHumanCount}. */
+export interface UseConversationsWantsHumanCountOptions {
+  /**
+   * Poll interval in milliseconds; `false` disables polling. Defaults to
+   * {@link CONVERSATION_BADGE_POLL_INTERVAL_MS} — deliberately the
+   * slowest budget on the conversation surface (DD-012 D-b): a badge
+   * tolerates staleness an open inbox does not, and it renders on every
+   * console page in every tab.
+   */
+  readonly refetchIntervalMs?: number | false;
+}
+
+/** Return value of {@link useConversationsWantsHumanCount}. */
+export interface UseConversationsWantsHumanCountReturn {
+  /**
+   * Conversations where a human action is wanted:
+   * `needs_attention OR (awaiting_reply AND human-held)` — the two ways
+   * a conversation can be blocked on a person (the agent asked for one,
+   * or a human took over and the customer wrote). `0` until the first
+   * answer.
+   */
+  readonly count: number;
+  /** `true` only until the first answer arrives. */
+  readonly isLoading: boolean;
+  /** Error from the last failed read, or `null`. */
+  readonly error: Error | null;
+  /** Imperatively re-read the count. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook for the sidebar's Conversations badge (channel-conversations
+ * DD-011 D-f): how many conversations want a human right now, org-wide.
+ *
+ * The count IS the filtered list's `total_count` — one page-size-1 read
+ * with `filter_wants_human`, zero dedicated RPCs (DD-011 D-g). Because
+ * the badge and the wants-human list filter share one server-side
+ * predicate, the number shown and the list it leads to can never
+ * disagree.
+ *
+ * Pass `null` to skip fetching (no active org).
+ */
+export function useConversationsWantsHumanCount(
+  org: string | null,
+  options?: UseConversationsWantsHumanCountOptions,
+): UseConversationsWantsHumanCountReturn {
+  const stigmer = useStigmer();
+  const refetchIntervalMs =
+    options?.refetchIntervalMs ?? CONVERSATION_BADGE_POLL_INTERVAL_MS;
+
+  const fetchFn = org
+    ? async (): Promise<number> => {
+        const result = await stigmer.agentChannel.listConversations(
+          create(ListChannelConversationsInputSchema, {
+            org,
+            filter: ChannelConversationListFilter.filter_wants_human,
+            pageInfo: { num: 1, size: 1 },
+          }),
+        );
+        return result.totalCount;
+      }
+    : null;
+
+  const { data, isLoading, error, refetch } = useFetch(fetchFn, [org, stigmer], 0, {
+    refetchInterval: refetchIntervalMs,
+    // DD-012 D-a: returning to the tab is fresh.
+    refetchOnWindowFocus: true,
+  });
+
+  return useMemo(
+    () => ({ count: data, isLoading, error, refetch }),
+    [data, isLoading, error, refetch],
+  );
+}

package/src/index.ts

@@ -1356,6 +1356,73 @@ export type {
   ChannelTemplatesDialogProps,
 } from "./channel/index.js";
 
+// Conversation — the channel conversation surface (channel-conversations
+// T04): the org-wide list, one conversation's row and timeline, the
+// participation commands (reply / takeOver / handBack / clearAttention),
+// and the pure render vocabulary shared by every conversation view.
+export {
+  ConversationsWorkbench,
+  ConversationListPane,
+  ConversationTimelineView,
+  ConversationControlBanner,
+  ConversationAttentionBanner,
+  ConversationComposer,
+  useConversation,
+  useConversationList,
+  useConversationTimeline,
+  useConversationParticipation,
+  useConversationsWantsHumanCount,
+  authorKindOf,
+  awaitingIndicatorOf,
+  compareTimelineItemsNewestFirst,
+  conversationContactOf,
+  conversationLabelOf,
+  inboundPlaceholderOf,
+  isInternalItem,
+  receiptOf,
+  sendAttemptOf,
+  serviceWindowOf,
+  CONVERSATION_BADGE_POLL_INTERVAL_MS,
+  CONVERSATION_DETAIL_POLL_INTERVAL_MS,
+  CONVERSATION_LIST_POLL_INTERVAL_MS,
+} from "./conversation/index.js";
+export type {
+  ConversationsWorkbenchProps,
+  ConversationHeaderContext,
+  ConversationIdentity,
+  ConversationListPaneProps,
+  ConversationTimelineViewProps,
+  ConversationControlBannerProps,
+  ConversationAttentionBannerProps,
+  ConversationComposerProps,
+  UseConversationOptions,
+  UseConversationReturn,
+  UseConversationListOptions,
+  UseConversationListReturn,
+  UseConversationTimelineOptions,
+  UseConversationTimelineReturn,
+  ConversationCommand,
+  UseConversationParticipationOptions,
+  UseConversationParticipationReturn,
+  UseConversationsWantsHumanCountOptions,
+  UseConversationsWantsHumanCountReturn,
+  AwaitingIndicator,
+  ConversationAuthorKind,
+  ReceiptKind,
+  SendAttemptKind,
+  ServiceWindowState,
+} from "./conversation/index.js";
+// Wire types the conversation hooks answer with (DD-007: generated types
+// are the source of truth — re-exported for consumer convenience).
+export {
+  ChannelConversationListFilter,
+  ConversationControl,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+export type {
+  ChannelConversation,
+  ConversationTimelineItem,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+
 // Error — structured error display with classification, retry, and contextual guidance
 export { ErrorMessage, SecretFlowErrorGuide, isSecretFlowError } from "./error/index.js";
 export type { ErrorMessageProps, SecretFlowErrorGuideProps } from "./error/index.js";

package/src/internal/__tests__/fake-timer-slices.ts

@@ -0,0 +1,29 @@
+import { act } from "@testing-library/react";
+import { vi } from "vitest";
+
+/**
+ * Advance fake time in small slices with an `act` boundary per slice.
+ *
+ * A single long `advanceTimersByTimeAsync` inside one `act` coalesces
+ * every React commit to the END of the block: no re-render lands
+ * between timer callbacks, and state updates queued by multiple timer
+ * ticks collapse into one commit. Any test about how timers and renders
+ * INTERLEAVE (poll phase stability, render-pressure starvation, data
+ * arriving "on the next poll tick") silently measures nothing under a
+ * single long advance. Slicing lets React commit between timer steps,
+ * the way real time does in production.
+ *
+ * Not a `.test` file and inside `__tests__` deliberately: vitest does
+ * not collect it, and the build/typedoc excludes keep it out of the
+ * published package.
+ */
+export async function advanceInSlices(
+  totalMs: number,
+  sliceMs = 100,
+): Promise<void> {
+  for (let elapsed = 0; elapsed < totalMs; elapsed += sliceMs) {
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(sliceMs);
+    });
+  }
+}