@opengeni/react 0.6.3 → 0.9.0

package/src/hooks/use-session-events.ts

@@ -1,13 +1,16 @@
 import type { SessionEvent, SessionStatus, StreamConnectionState } from "@opengeni/sdk";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
-import { buildTimeline, sessionStatusFromEvents, type TimelineItem } from "../timeline";
+import { buildTimeline, groupTimeline, sessionStatusFromEvents, type TimelineItem } from "../timeline";
+import type { SessionClientLike } from "../client";
 
 export type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
 
 export type UseSessionEventsOptions = ClientOverride & {
-  /** Resume after this sequence (exclusive). Defaults to 0 = full replay. */
+  /** Resume after this sequence (exclusive). Nonzero keeps full replay/resume semantics. */
   after?: number | undefined;
+  /** Load a bounded tail by default, or opt back into full replay from `after`. */
+  replay?: "windowed" | "full" | undefined;
   /** Pause the stream without unmounting (e.g. hidden tab). Defaults to true. */
   enabled?: boolean | undefined;
 };
@@ -22,34 +25,64 @@ export type UseSessionEventsResult = {
   connectionState: SessionEventsConnectionState;
   /** Highest sequence seen so far (0 before the first event). */
   lastSequence: number;
+  /** True until the initial tail window has been applied (windowed mode). */
+  initialLoading: boolean;
+  /** Whether older durable events are available before the current window. */
+  hasOlder: boolean;
+  /** True while an older window is being fetched. */
+  loadingOlder: boolean;
+  /** Prepend an older density-bounded window; resolves true when more remain. */
+  loadOlder: () => Promise<boolean>;
   error: Error | null;
 };
 
+const TAIL_PAGE_SIZE = 5000;
+const INITIAL_FETCH_CAP = 1;
+const OLDER_GROUP_TARGET = 32;
+const OLDER_FETCH_CAP = 2;
+const BOUNDARY_PAGE_CAP = 4;
+
 /**
  * Live-stream a session's event log with replay-by-sequence, reconnect, and
- * batched React updates. The SDK guarantees ordered, gap-free, exactly-once
- * delivery; this hook accumulates the log and projects it into a timeline.
+ * batched React updates. Fresh loads default to a bounded tail window; pass
+ * `replay: "full"` or a nonzero `after` for the previous full replay path.
  */
 export function useSessionEvents(sessionId: string | null | undefined, options: UseSessionEventsOptions = {}): UseSessionEventsResult {
   const { client, workspaceId } = useOpenGeni(options);
   const enabled = options.enabled ?? true;
   const after = options.after ?? 0;
+  const replay = options.replay ?? "windowed";
+  const fullReplay = replay === "full" || after !== 0;
 
   const [events, setEvents] = useState<SessionEvent[]>([]);
   const [connectionState, setConnectionState] = useState<SessionEventsConnectionState>("idle");
   const [error, setError] = useState<Error | null>(null);
+  const [hasOlder, setHasOlder] = useState(false);
+  const [initialLoading, setInitialLoading] = useState(true);
+  const [loadingOlder, setLoadingOlder] = useState(false);
   const lastSequenceRef = useRef(after);
+  const oldestSequenceRef = useRef<number | null>(null);
+  const hasOlderRef = useRef(false);
+  const loadingOlderRef = useRef(false);
   const streamKeyRef = useRef<string | null>(null);
+  const generationRef = useRef(0);
 
   useEffect(() => {
     // Reset the accumulated log only when the stream identity changes —
     // pausing via `enabled: false` keeps the timeline visible.
-    const streamKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${after}`;
+    const streamKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${after}\u0000${fullReplay ? "full" : "windowed"}`;
     if (streamKeyRef.current !== streamKey) {
       streamKeyRef.current = streamKey;
+      generationRef.current += 1;
       setEvents([]);
       setError(null);
+      setHasOlder(false);
+      setLoadingOlder(false);
+      setInitialLoading(true);
       lastSequenceRef.current = after;
+      oldestSequenceRef.current = null;
+      hasOlderRef.current = false;
+      loadingOlderRef.current = false;
     }
     if (!sessionId || !enabled) {
       setConnectionState("idle");
@@ -72,7 +105,7 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
       // the next connect instead of being skipped.
       const lastInBatch = batch[batch.length - 1];
       if (lastInBatch) {
-        lastSequenceRef.current = lastInBatch.sequence;
+        lastSequenceRef.current = Math.max(lastSequenceRef.current, ...batch.map(eventResumeSequence));
       }
       setEvents((existing) => [...existing, ...batch]);
     };
@@ -82,6 +115,31 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
 
     void (async () => {
       try {
+        if (!fullReplay) {
+          setConnectionState("connecting");
+          // First paint is ONE compact fetch — the newest window, revealed at
+          // the bottom in a few hundred ms. Deeper history loads only when the
+          // reader actually scrolls up (the sentinel drives loadOlder).
+          const window = await loadEventWindow(client, workspaceId, sessionId, {
+            before: Number.MAX_SAFE_INTEGER,
+            pageSize: TAIL_PAGE_SIZE,
+            targetGroups: Number.POSITIVE_INFINITY,
+            maxFetches: INITIAL_FETCH_CAP,
+            signal: controller.signal,
+          });
+          if (controller.signal.aborted) {
+            return;
+          }
+          oldestSequenceRef.current = window.oldestSequence;
+          hasOlderRef.current = window.hasOlder;
+          lastSequenceRef.current = window.newestSequence;
+          setHasOlder(window.hasOlder);
+          setEvents(window.events);
+          setInitialLoading(false);
+        }
+        if (fullReplay) {
+          setInitialLoading(false);
+        }
         const stream = client.streamEvents(workspaceId, sessionId, {
           after: lastSequenceRef.current,
           signal: controller.signal,
@@ -114,7 +172,52 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
         clearTimeout(flushTimer);
       }
     };
-  }, [client, workspaceId, sessionId, after, enabled]);
+  }, [client, workspaceId, sessionId, after, enabled, fullReplay]);
+
+  const loadOlder = useCallback(async (): Promise<boolean> => {
+    if (!sessionId || fullReplay || loadingOlderRef.current || !hasOlderRef.current) {
+      return false;
+    }
+    const before = oldestSequenceRef.current;
+    if (before === null) {
+      hasOlderRef.current = false;
+      setHasOlder(false);
+      return false;
+    }
+    const generation = generationRef.current;
+    loadingOlderRef.current = true;
+    setLoadingOlder(true);
+    try {
+      const window = await loadEventWindow(client, workspaceId, sessionId, {
+        before,
+        pageSize: TAIL_PAGE_SIZE,
+        targetGroups: OLDER_GROUP_TARGET,
+        maxFetches: OLDER_FETCH_CAP,
+      });
+      if (generationRef.current !== generation) {
+        return false;
+      }
+      if (window.events.length === 0) {
+        oldestSequenceRef.current = null;
+        hasOlderRef.current = false;
+        setHasOlder(false);
+        return false;
+      }
+      oldestSequenceRef.current = window.oldestSequence;
+      hasOlderRef.current = window.hasOlder;
+      setHasOlder(window.hasOlder);
+      setEvents((existing) => {
+        assertPrependOrder(existing, window.events);
+        return [...window.events, ...existing];
+      });
+      return window.hasOlder;
+    } finally {
+      if (generationRef.current === generation) {
+        loadingOlderRef.current = false;
+        setLoadingOlder(false);
+      }
+    }
+  }, [client, workspaceId, sessionId, fullReplay]);
 
   const timeline = useMemo(() => buildTimeline(events), [events]);
   const sessionStatus = useMemo(() => sessionStatusFromEvents(events), [events]);
@@ -125,6 +228,189 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
     sessionStatus,
     connectionState,
     lastSequence: lastSequenceRef.current,
+    initialLoading: fullReplay ? false : initialLoading,
+    hasOlder: fullReplay ? false : hasOlder,
+    loadingOlder: fullReplay ? false : loadingOlder,
+    loadOlder,
     error,
   };
 }
+
+type LoadedEventWindow = {
+  events: SessionEvent[];
+  oldestSequence: number | null;
+  newestSequence: number;
+  hasOlder: boolean;
+};
+
+async function loadEventWindow(
+  client: SessionClientLike,
+  workspaceId: string,
+  sessionId: string,
+  options: {
+    before: number;
+    pageSize: number;
+    targetGroups: number;
+    maxFetches: number;
+    signal?: AbortSignal;
+  },
+): Promise<LoadedEventWindow> {
+  let cursor = options.before;
+  let buffer: SessionEvent[] = [];
+  let reachedStart = false;
+  let fetches = 0;
+
+  while (fetches < options.maxFetches) {
+    if (buffer.length > 0 && groupCount(buffer) >= options.targetGroups) {
+      break;
+    }
+    const page = await loadPreviousPage(client, workspaceId, sessionId, cursor, {
+      pageSize: options.pageSize,
+      ...(options.signal ? { signal: options.signal } : {}),
+    });
+    fetches += 1;
+    if (page.length === 0) {
+      reachedStart = true;
+      break;
+    }
+    assertAscending(page);
+    buffer = [...page, ...buffer];
+    cursor = page[0]!.sequence;
+    if (isLogStart(page[0]!)) {
+      reachedStart = true;
+      break;
+    }
+  }
+
+  // Boundary snap: a window that starts mid-turn TRIMS its head to the oldest
+  // turn boundary already in the buffer — the dropped fragment is refetched by
+  // the next loadOlder (everything below the new oldest sequence), whose own
+  // window snaps the same way, so every seam lands on a turn start. Extra
+  // pages are fetched only when the buffer holds no boundary at all (one
+  // monster turn); past the cap a mid-turn top is accepted.
+  let snapPages = 0;
+  while (!reachedStart && findBoundaryIndex(buffer) === -1 && snapPages < BOUNDARY_PAGE_CAP && fetches < options.maxFetches) {
+    const page = await loadPreviousPage(client, workspaceId, sessionId, cursor, {
+      pageSize: options.pageSize,
+      ...(options.signal ? { signal: options.signal } : {}),
+    });
+    fetches += 1;
+    snapPages += 1;
+    if (page.length === 0) {
+      reachedStart = true;
+      break;
+    }
+    assertAscending(page);
+    buffer = [...page, ...buffer];
+    cursor = page[0]!.sequence;
+    if (isLogStart(page[0]!)) {
+      reachedStart = true;
+      break;
+    }
+  }
+  if (!reachedStart) {
+    const boundary = findBoundaryIndex(buffer);
+    if (boundary > 0) {
+      buffer = buffer.slice(boundary);
+    }
+  }
+
+  const oldest = buffer[0] ?? null;
+  const newest = buffer[buffer.length - 1] ?? null;
+  return {
+    events: buffer,
+    oldestSequence: oldest?.sequence ?? null,
+    newestSequence: newest ? maxResumeSequence(buffer) : 0,
+    hasOlder: buffer.length > 0 && !reachedStart && oldest?.type !== "session.created",
+  };
+}
+
+/** Index of the oldest clean turn start in the buffer, or -1. */
+function findBoundaryIndex(events: SessionEvent[]): number {
+  for (let index = 0; index < events.length; index += 1) {
+    const type = events[index]!.type;
+    if (type === "session.created" || type === "user.message") {
+      return index;
+    }
+  }
+  return -1;
+}
+
+type PreviousPage = SessionEvent[] & { requested: number };
+
+async function loadPreviousPage(
+  client: SessionClientLike,
+  workspaceId: string,
+  sessionId: string,
+  before: number,
+  options: {
+    pageSize: number;
+    signal?: AbortSignal;
+  },
+): Promise<PreviousPage> {
+  if (options.signal?.aborted) {
+    throw abortError();
+  }
+  const requested = options.pageSize;
+  if (requested === 0) {
+    return Object.assign([], { requested });
+  }
+  const page = await client.listEvents(workspaceId, sessionId, { before, limit: requested, compact: true });
+  if (options.signal?.aborted) {
+    throw abortError();
+  }
+  return Object.assign(page, { requested });
+}
+
+function groupCount(events: SessionEvent[]): number {
+  if (events.length === 0) {
+    return 0;
+  }
+  return groupTimeline(buildTimeline(events)).length;
+}
+
+function isLogStart(event: SessionEvent): boolean {
+  return event.type === "session.created" || event.sequence <= 1;
+}
+
+function maxResumeSequence(events: SessionEvent[]): number {
+  return events.reduce((max, event) => Math.max(max, eventResumeSequence(event)), 0);
+}
+
+function eventResumeSequence(event: SessionEvent): number {
+  const payload = asRecord(event.payload);
+  const coalescedUntil = Number(payload.coalescedUntil);
+  return Math.max(event.sequence, Number.isFinite(coalescedUntil) ? Math.floor(coalescedUntil) : 0);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" ? value as Record<string, unknown> : {};
+}
+
+function assertAscending(events: SessionEvent[]): void {
+  for (let index = 1; index < events.length; index += 1) {
+    if (events[index - 1]!.sequence >= events[index]!.sequence) {
+      throw new Error("@opengeni/react: session events must be ordered by ascending sequence");
+    }
+  }
+}
+
+function assertPrependOrder(existing: SessionEvent[], older: SessionEvent[]): void {
+  if (!shouldAssertDevelopment() || existing.length === 0 || older.length === 0) {
+    return;
+  }
+  if (older[older.length - 1]!.sequence >= existing[0]!.sequence) {
+    throw new Error("@opengeni/react: loadOlder returned overlapping session events");
+  }
+}
+
+function shouldAssertDevelopment(): boolean {
+  const processEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env;
+  return processEnv !== undefined && processEnv.NODE_ENV !== "production";
+}
+
+function abortError(): Error {
+  const error = new Error("The operation was aborted.");
+  error.name = "AbortError";
+  return error;
+}

package/src/timeline/activity-rail.tsx

@@ -2,6 +2,7 @@ import { BotIcon, BrainIcon, SquareTerminalIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { truncate } from "../lib/format";
 import { defaultToolRegistry } from "./tool-renderers";
+import { useEntranceAnimation } from "./entrance";
 import type { ToolRegistry } from "./registry";
 import { PayloadBlock, ActivityDisclosure } from "./shared";
 import { toolDisplayName } from "./projection";
@@ -42,6 +43,7 @@ function familyOf(item: ActivityItem): string {
 }
 
 export function ActivityRail({ items, toolRegistry = defaultToolRegistry, onOpenSession, bare, className }: ActivityRailProps) {
+  const enter = useEntranceAnimation();
   return (
     <div
       className={cn(
@@ -49,7 +51,8 @@ export function ActivityRail({ items, toolRegistry = defaultToolRegistry, onOpen
         // calm cluster; a family change opens real breathing room (mt-3) below,
         // so a long rail reads as a few clusters, not a metronome of rows.
         "flex flex-col gap-0.5",
-        !bare && "animate-og-enter border-l-2 border-og-border pl-3 sm:pl-4",
+        !bare && "border-l-2 border-og-border pl-3 sm:pl-4",
+        !bare && enter && "animate-og-enter",
         className,
       )}
     >

package/src/timeline/entrance.tsx

@@ -0,0 +1,30 @@
+import { createContext, useContext, useRef } from "react";
+
+/* ----------------------------------------------------------------------------
+   Entrance animation gating
+
+   Bulk paints (the initial tail window, a prepended older window) must not run
+   per-row entrance animations — hundreds of rows fading in at once reads as a
+   full-timeline flash. Toggling `animation: none` on and off is NOT an option:
+   removing the override restarts every animation, which is itself the flash.
+
+   Instead each animated element decides ONCE, at its own mount, whether it was
+   born in a bulk paint — and keeps that decision forever. Rows born in a bulk
+   paint never animate; rows appended live animate exactly as before. Nothing
+   is ever toggled on existing DOM, so nothing can replay.
+   -------------------------------------------------------------------------- */
+
+const EntranceAnimationContext = createContext(true);
+
+export const EntranceAnimationProvider = EntranceAnimationContext.Provider;
+
+/**
+ * Whether this element should wear the entrance animation. Captured at mount
+ * from the nearest provider (true outside any provider) and stable for the
+ * element's lifetime — see the module doctrine above.
+ */
+export function useEntranceAnimation(): boolean {
+  const enabled = useContext(EntranceAnimationContext);
+  const captured = useRef(enabled);
+  return captured.current;
+}

package/src/timeline/projection.ts

@@ -319,7 +319,11 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
       case "turn.failed": {
         const hadActivity = hasTurnActivity(items, turnId);
         const failureText = failureMessage(payload);
-        finalizeOpen(turnId, "failed");
+        // The TURN failed — the in-flight items did not. Chip doctrine: red is
+        // spent once, on the turn-level outcome. Items caught mid-flight read
+        // as calm "interrupted" (same as turn.cancelled); an item that itself
+        // failed keeps its own failed status from its output event.
+        finalizeOpen(turnId, "cancelled");
         items.push(turnEndItem(event, "failed", failureText));
         if (!hadActivity) {
           items.push({
@@ -613,8 +617,19 @@ function stampTurnOutcome(groups: TimelineGroup[], turnEnd: TurnEndItem): void {
 }
 
 function applyTurnOutcome(group: Extract<TimelineGroup, { kind: "activity" }>, turnEnd: TurnEndItem): void {
-  group.outcome = turnEnd.outcome;
-  if (turnEnd.failureText) {
+  // A sub-cluster reports ITS OWN outcome, not the turn's. When a turn fails
+  // at step 7, clusters 1–6 completed — painting them all red says "everything
+  // broke" when one thing did. The turn-level fold carries the turn outcome;
+  // a cluster goes red only if an item inside it actually failed, and reads
+  // "cancelled" (interrupted) only when it holds the items cut off mid-flight.
+  if (turnEnd.outcome === "complete") {
+    group.outcome = "complete";
+    return;
+  }
+  const hasFailed = group.items.some((item) => "status" in item && item.status === "failed");
+  const hasInterrupted = group.items.some((item) => "status" in item && item.status === "cancelled");
+  group.outcome = hasFailed ? "failed" : hasInterrupted ? "cancelled" : "complete";
+  if (turnEnd.failureText && hasFailed) {
     group.failureText = turnEnd.failureText;
   }
 }

package/src/timeline/turn-summary.tsx

@@ -3,6 +3,7 @@ import { useState } from "react";
 import { Collapsible } from "radix-ui";
 import { cn } from "../lib/cn";
 import { useForcedDefaultOpen } from "./disclosure-context";
+import { useEntranceAnimation } from "./entrance";
 import { applyPatchOps, isApplyPatch, screenshotDataUrl } from "./parsers";
 import { rawTypeOf } from "./registry";
 import type { ActivityItem, TurnOutcome } from "./types";
@@ -39,10 +40,11 @@ export function TurnSummary({ items, outcome, failureText, durationMs, defaultOp
   // (screenshot instrumentation); otherwise the turn starts folded.
   const forcedDefaultOpen = useForcedDefaultOpen();
   const [open, setOpen] = useState(defaultOpen ?? forcedDefaultOpen ?? false);
+  const enter = useEntranceAnimation();
   const facets = summarizeTurn(items, durationMs);
 
   return (
-    <Collapsible.Root open={open} onOpenChange={setOpen} className="animate-og-enter">
+    <Collapsible.Root open={open} onOpenChange={setOpen} className={enter ? "animate-og-enter" : undefined}>
       <Collapsible.Trigger
         className={cn(
           "group flex w-full items-center gap-2.5 rounded-og-md border px-3 py-2 text-left text-og-base transition-colors",