@opengeni/react 0.12.0 → 0.15.0

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

@@ -1,7 +1,12 @@
 import type { SessionEvent, SessionStatus, StreamConnectionState } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
-import { buildTimeline, groupTimeline, 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";
@@ -36,23 +41,29 @@ export type UseSessionEventsResult = {
   error: Error | null;
 };
 
-const TAIL_PAGE_SIZE = 5000;
+const INITIAL_TAIL_PAGE_SIZE = 1000;
+const OLDER_PAGE_SIZE = 5000;
 const INITIAL_FETCH_CAP = 1;
 const OLDER_GROUP_TARGET = 32;
 const OLDER_FETCH_CAP = 2;
 const BOUNDARY_PAGE_CAP = 4;
+const EMPTY_EVENTS: SessionEvent[] = [];
 
 /**
  * Live-stream a session's event log with replay-by-sequence, reconnect, and
  * 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);
+export function useSessionEvents(
+  sessionId: string | null | undefined,
+  options: UseSessionEventsOptions = {},
+): UseSessionEventsResult {
+  const { client, workspaceId, reconcileSession } = useOpenGeni(options);
   const enabled = options.enabled ?? true;
   const after = options.after ?? 0;
   const replay = options.replay ?? "windowed";
   const fullReplay = replay === "full" || after !== 0;
+  const streamKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${after}\u0000${fullReplay ? "full" : "windowed"}`;
 
   const [events, setEvents] = useState<SessionEvent[]>([]);
   const [connectionState, setConnectionState] = useState<SessionEventsConnectionState>("idle");
@@ -66,14 +77,17 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
   const loadingOlderRef = useRef(false);
   const streamKeyRef = useRef<string | null>(null);
   const generationRef = useRef(0);
+  // Effects reset state after commit. Tag the state so the first render for a
+  // new stream identity cannot expose the previous session's event log.
+  const [stateStreamKey, setStateStreamKey] = useState(streamKey);
 
   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}\u0000${fullReplay ? "full" : "windowed"}`;
     if (streamKeyRef.current !== streamKey) {
       streamKeyRef.current = streamKey;
       generationRef.current += 1;
+      setStateStreamKey(streamKey);
       setEvents([]);
       setError(null);
       setHasOlder(false);
@@ -105,7 +119,10 @@ 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 = Math.max(lastSequenceRef.current, ...batch.map(eventResumeSequence));
+        lastSequenceRef.current = Math.max(
+          lastSequenceRef.current,
+          ...batch.map(eventResumeSequence),
+        );
       }
       setEvents((existing) => [...existing, ...batch]);
     };
@@ -122,7 +139,7 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
           // reader actually scrolls up (the sentinel drives loadOlder).
           const window = await loadEventWindow(client, workspaceId, sessionId, {
             before: Number.MAX_SAFE_INTEGER,
-            pageSize: TAIL_PAGE_SIZE,
+            pageSize: INITIAL_TAIL_PAGE_SIZE,
             targetGroups: Number.POSITIVE_INFINITY,
             maxFetches: INITIAL_FETCH_CAP,
             signal: controller.signal,
@@ -143,6 +160,7 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
         const stream = client.streamEvents(workspaceId, sessionId, {
           after: lastSequenceRef.current,
           signal: controller.signal,
+          beforeLive: async () => await reconcileSession(sessionId),
           onStateChange: (state) => {
             if (!controller.signal.aborted) {
               setConnectionState(state);
@@ -172,7 +190,7 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
         clearTimeout(flushTimer);
       }
     };
-  }, [client, workspaceId, sessionId, after, enabled, fullReplay]);
+  }, [client, workspaceId, sessionId, after, enabled, fullReplay, streamKey, reconcileSession]);
 
   const loadOlder = useCallback(async (): Promise<boolean> => {
     if (!sessionId || fullReplay || loadingOlderRef.current || !hasOlderRef.current) {
@@ -190,7 +208,7 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
     try {
       const window = await loadEventWindow(client, workspaceId, sessionId, {
         before,
-        pageSize: TAIL_PAGE_SIZE,
+        pageSize: OLDER_PAGE_SIZE,
         targetGroups: OLDER_GROUP_TARGET,
         maxFetches: OLDER_FETCH_CAP,
       });
@@ -219,20 +237,22 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
     }
   }, [client, workspaceId, sessionId, fullReplay]);
 
-  const timeline = useMemo(() => buildTimeline(events), [events]);
-  const sessionStatus = useMemo(() => sessionStatusFromEvents(events), [events]);
+  const identityMatches = stateStreamKey === streamKey;
+  const visibleEvents = identityMatches ? events : EMPTY_EVENTS;
+  const timeline = useMemo(() => buildTimeline(visibleEvents), [visibleEvents]);
+  const sessionStatus = useMemo(() => sessionStatusFromEvents(visibleEvents), [visibleEvents]);
 
   return {
-    events,
+    events: visibleEvents,
     timeline,
     sessionStatus,
-    connectionState,
-    lastSequence: lastSequenceRef.current,
-    initialLoading: fullReplay ? false : initialLoading,
-    hasOlder: fullReplay ? false : hasOlder,
-    loadingOlder: fullReplay ? false : loadingOlder,
+    connectionState: identityMatches ? connectionState : "idle",
+    lastSequence: identityMatches ? lastSequenceRef.current : after,
+    initialLoading: fullReplay ? false : identityMatches ? initialLoading : true,
+    hasOlder: fullReplay || !identityMatches ? false : hasOlder,
+    loadingOlder: fullReplay || !identityMatches ? false : loadingOlder,
     loadOlder,
-    error,
+    error: identityMatches ? error : null,
   };
 }
 
@@ -289,7 +309,12 @@ async function loadEventWindow(
   // 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) {
+  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 } : {}),
@@ -355,7 +380,11 @@ async function loadPreviousPage(
   if (requested === 0) {
     return Object.assign([], { requested });
   }
-  const page = await client.listEvents(workspaceId, sessionId, { before, limit: requested, compact: true });
+  const page = await client.listEvents(workspaceId, sessionId, {
+    before,
+    limit: requested,
+    compact: true,
+  });
   if (options.signal?.aborted) {
     throw abortError();
   }
@@ -384,7 +413,7 @@ function eventResumeSequence(event: SessionEvent): number {
 }
 
 function asRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === "object" ? value as Record<string, unknown> : {};
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : {};
 }
 
 function assertAscending(events: SessionEvent[]): void {

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

@@ -0,0 +1,128 @@
+import type { SessionEvent, SessionLineageResponse } from "@opengeni/sdk";
+import { useCallback, useEffect, useRef } from "react";
+import { useOpenGeni, type ClientOverride } from "../provider";
+import { useDebouncedCallback, usePolledValue, useSessionEventTrigger } from "./internal";
+
+export type UseSessionLineageOptions = ClientOverride & {
+  events?: SessionEvent[] | undefined;
+  /** Refresh interval (ms). Off by default. */
+  pollIntervalMs?: number | undefined;
+  enabled?: boolean | undefined;
+};
+
+export type UseSessionLineageResult = {
+  lineage: SessionLineageResponse | null;
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+};
+
+export function isLineageRefreshEvent(event: SessionEvent): boolean {
+  if (event.type === "session.status.changed" || event.type === "session.created") {
+    return true;
+  }
+  // A child's creation never appears on the PARENT's stream as session.created —
+  // the parent sees its own spawn as an agent.toolCall.* for session_create.
+  // Created events are handled separately so they can refresh immediately and
+  // once after the child row has had time to commit.
+  if (event.type === "agent.toolCall.output") {
+    const payload = event.payload as { name?: unknown; toolName?: unknown } | null | undefined;
+    const name =
+      typeof payload?.name === "string"
+        ? payload.name
+        : typeof payload?.toolName === "string"
+          ? payload.toolName
+          : "";
+    return name === "session_create" || name.endsWith("__session_create");
+  }
+  return false;
+}
+
+function isSessionCreateToolCallCreated(event: SessionEvent): boolean {
+  if (event.type !== "agent.toolCall.created") {
+    return false;
+  }
+  const payload = event.payload as { name?: unknown; toolName?: unknown } | null | undefined;
+  const name =
+    typeof payload?.name === "string"
+      ? payload.name
+      : typeof payload?.toolName === "string"
+        ? payload.toolName
+        : "";
+  return name === "session_create" || name.endsWith("__session_create");
+}
+
+/** Read the ancestors + descendant tree for one session. Data-only; no UI state. */
+export function useSessionLineage(
+  sessionId: string | null | undefined,
+  options: UseSessionLineageOptions = {},
+): UseSessionLineageResult {
+  const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
+    useOpenGeni(options);
+  const enabled = (options.enabled ?? true) && Boolean(sessionId);
+  const load = useCallback(
+    async () =>
+      sessionId
+        ? await client.getSessionLineage(workspaceId, sessionId)
+        : { ancestors: [], children: [], truncated: false },
+    [client, workspaceId, sessionId],
+  );
+  const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled });
+  const refresh = state.refresh;
+  useEffect(() => {
+    if (enabled && workspaceControlEvent) void refresh();
+  }, [enabled, refresh, workspaceControlEvent]);
+  useEffect(() => {
+    if (!sessionId || !enabled) return;
+    return registerSessionReconciler(sessionId, "lineage", refresh);
+  }, [enabled, refresh, registerSessionReconciler, sessionId]);
+  const refreshSoon = useDebouncedCallback(() => void refresh(), 150);
+  const delayedChildRefreshRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Clear a pending delayed refresh on session/workspace SWITCH (not just
+  // unmount): otherwise a timer scheduled for the previous session can fire
+  // ~2.5s later and commit that session's lineage onto the new one.
+  useEffect(() => {
+    return () => {
+      if (delayedChildRefreshRef.current !== null) {
+        clearTimeout(delayedChildRefreshRef.current);
+        delayedChildRefreshRef.current = null;
+      }
+    };
+  }, [sessionId, workspaceId]);
+  const refreshAfterChildCreate = useCallback(() => {
+    void refresh();
+    if (delayedChildRefreshRef.current !== null) {
+      clearTimeout(delayedChildRefreshRef.current);
+    }
+    delayedChildRefreshRef.current = setTimeout(() => {
+      delayedChildRefreshRef.current = null;
+      void refresh();
+    }, 2500);
+  }, [refresh]);
+  useSessionEventTrigger(
+    client,
+    workspaceId,
+    sessionId,
+    isLineageRefreshEvent,
+    refreshSoon,
+    // SHARED-FEED ONLY: without a caller-provided events log the trigger would
+    // open its OWN streamEvents tail — a second live SSE connection next to the
+    // session route's useSessionEvents. A caller with no feed opts into polling
+    // (pollIntervalMs), never a duplicate stream.
+    { events: options.events, enabled: enabled && options.events !== undefined },
+  );
+  useSessionEventTrigger(
+    client,
+    workspaceId,
+    sessionId,
+    isSessionCreateToolCallCreated,
+    refreshAfterChildCreate,
+    { events: options.events, enabled: enabled && options.events !== undefined },
+  );
+  return {
+    lineage: state.data,
+    loading: state.loading,
+    error: state.error,
+    refresh,
+  };
+}

package/src/hooks/use-session.ts

@@ -1,7 +1,12 @@
 import type { Session, SessionEvent } from "@opengeni/sdk";
-import { useCallback, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
-import { useMutationRunner, usePolledValue, useSessionEventTrigger, type SessionEventFeedOptions } from "./internal";
+import {
+  useMutationRunner,
+  usePolledValue,
+  useSessionEventTrigger,
+  type SessionEventFeedOptions,
+} from "./internal";
 
 export type UseSessionOptions = ClientOverride &
   SessionEventFeedOptions & {
@@ -28,11 +33,15 @@ export function isTitleEvent(event: Pick<SessionEvent, "type">): boolean {
 }
 
 /** Fetch one session (with optional polling), live-patching its title on `session.title_set`. */
-export function useSession(sessionId: string | null | undefined, options: UseSessionOptions = {}): UseSessionResult {
-  const { client, workspaceId } = useOpenGeni(options);
+export function useSession(
+  sessionId: string | null | undefined,
+  options: UseSessionOptions = {},
+): UseSessionResult {
+  const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
+    useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const [override, setOverride] = useState<Session | null>(null);
-  const mutation = useMutationRunner();
+  const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
   const load = useCallback(async () => {
     if (!sessionId) {
       return null;
@@ -42,33 +51,47 @@ export function useSession(sessionId: string | null | undefined, options: UseSes
     setOverride(null);
     return fetched;
   }, [client, workspaceId, sessionId]);
-  const state = usePolledValue(load, {
+  const { data, loading, error, refresh } = usePolledValue(load, {
     pollIntervalMs: options.pollIntervalMs,
     enabled,
   });
+  useEffect(() => {
+    if (enabled && workspaceControlEvent) void refresh();
+  }, [enabled, refresh, workspaceControlEvent]);
+  useEffect(() => {
+    if (!sessionId || !enabled) return;
+    return registerSessionReconciler(sessionId, "session", refresh);
+  }, [enabled, refresh, registerSessionReconciler, sessionId]);
 
-  const base = state.data ?? null;
+  const base = data ?? null;
   // The override only ever carries title/titleSource patches; it is reset on
   // every fresh load so it can never go stale against the server snapshot.
-  const session = base && override && override.id === base.id ? { ...base, title: override.title, titleSource: override.titleSource } : base;
+  const session =
+    base && override && override.id === base.id
+      ? { ...base, title: override.title, titleSource: override.titleSource }
+      : base;
 
   // Live-patch the title on auto (agent) + cross-client (user/agent) renames so
   // the UI reflects the new title without polling or a full re-fetch.
-  const onTitleEvent = useCallback((event: SessionEvent) => {
-    const payload = (event.payload ?? {}) as { title?: unknown; source?: unknown };
-    const title = payload.title;
-    if (typeof title !== "string") {
-      return;
-    }
-    const source: "user" | "agent" | null = payload.source === "user" || payload.source === "agent" ? payload.source : null;
-    setOverride((current): Session | null => {
-      const next = current ?? base;
-      if (!next) {
-        return current;
+  const onTitleEvent = useCallback(
+    (event: SessionEvent) => {
+      const payload = (event.payload ?? {}) as { title?: unknown; source?: unknown };
+      const title = payload.title;
+      if (typeof title !== "string") {
+        return;
       }
-      return { ...next, title, titleSource: source };
-    });
-  }, [base]);
+      const source: "user" | "agent" | null =
+        payload.source === "user" || payload.source === "agent" ? payload.source : null;
+      setOverride((current): Session | null => {
+        const next = current ?? base;
+        if (!next) {
+          return current;
+        }
+        return { ...next, title, titleSource: source };
+      });
+    },
+    [base],
+  );
   useSessionEventTrigger(client, workspaceId, sessionId, isTitleEvent, onTitleEvent, {
     enabled,
     ...(options.events !== undefined ? { events: options.events } : {}),
@@ -79,23 +102,23 @@ export function useSession(sessionId: string | null | undefined, options: UseSes
       if (!sessionId) {
         return null;
       }
-      const result = await mutation.run(() => client.updateSession(workspaceId, sessionId, { title }));
+      const result = await run(() => client.updateSession(workspaceId, sessionId, { title }));
       if (result) {
         setOverride(result);
       }
       return result;
     },
-    [client, workspaceId, sessionId, mutation.run],
+    [client, workspaceId, sessionId, run],
   );
 
   return {
     session,
-    loading: state.loading,
-    error: state.error,
-    refresh: state.refresh,
+    loading,
+    error,
+    refresh,
     updateTitle,
-    updating: mutation.mutating,
-    mutationError: mutation.mutationError,
-    clearMutationError: mutation.clearMutationError,
+    updating: mutating,
+    mutationError,
+    clearMutationError,
   };
 }

package/src/hooks/use-slash-commands.ts

@@ -7,7 +7,7 @@ import {
   matchCommand,
   parseCommandLine,
 } from "../commands/registry";
-import type { CommandContext, Notice, SlashCommand } from "../commands/types";
+import type { CommandContext, SlashCommand } from "../commands/types";
 
 /**
  * Context the composer supplies for command execution and visibility. The
@@ -200,11 +200,11 @@ export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashComm
   // exact-match heuristic) and a pointer click (which has ALREADY chosen the
   // command — the clicked row — and must not re-resolve to a near-match).
   const runResolved = useCallback(
-    async (command: SlashCommand, options?: { explicit?: boolean }): Promise<void> => {
+    async (command: SlashCommand, executionOptions?: { explicit?: boolean }): Promise<void> => {
       if (!parsed) {
         return;
       }
-      const explicit = options?.explicit ?? false;
+      const explicit = executionOptions?.explicit ?? false;
       // Token-vs-command equality is case-insensitive (matching the registry's
       // matchCommand/filterCommands), so a fully-typed "/Clear" counts as having
       // named `clear` and runs rather than autocompleting.
@@ -298,7 +298,9 @@ export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashComm
         case "ArrowDown": {
           event.preventDefault();
           navigatedRef.current = true;
-          setHighlight((current) => (items.length === 0 ? 0 : (Math.min(current, items.length - 1) + 1) % items.length));
+          setHighlight((current) =>
+            items.length === 0 ? 0 : (Math.min(current, items.length - 1) + 1) % items.length,
+          );
           return true;
         }
         case "ArrowUp": {