@opengeni/react 0.25.0 → 0.25.5

package/dist/{session-BEvtFWhe.d.ts → use-turn-queue-3rkJwjFv.d.ts}

@@ -1,5 +1,5 @@
-import { E as EmbeddedSessionClientOverride, e as EmbeddedSessionMcpApprovalPolicyClientOverride, f as EmbeddedHumanInputClientOverride } from './session-context-rgrfElMl.js';
-import { ToolAuthNeededPayload, ResourceRef, ToolRef, SessionStatus, SessionEvent, StreamConnectionState, SessionQueueSnapshot, SessionTurn, EffectiveSessionControl, ComposerDraft, SessionControlResponse, SessionMcpServerMetadata, SessionMcpApprovalPolicy, UpdateSessionMcpApprovalPolicyResponse, HumanInputQuestion, SessionHumanInputRequest, SubmitHumanInputResponseRequest } from '@opengeni/sdk';
+import { ToolAuthNeededPayload, ResourceRef, ToolRef, SessionStatus, SessionQueueSnapshot, SessionTurn, EffectiveSessionControl, ComposerDraft, SessionEvent } from '@opengeni/sdk';
+import { E as EmbeddedSessionClientOverride } from './session-context-rgrfElMl.js';
 import { S as SessionEventFeedOptions } from './use-composer-BnEzheSk.js';
 
 type UserMessageItem = {
@@ -249,70 +249,6 @@ type TimelineGroup = {
     groups: TimelineGroup[];
 };
 
-type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
-type UseSessionEventsOptions = EmbeddedSessionClientOverride & {
-    /** 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;
-};
-type UseSessionEventsResult = {
-    /** Replayed + live events, ordered by sequence, no gaps, no duplicates. */
-    events: SessionEvent[];
-    /** Projected, renderable timeline (memoized over `events`). */
-    timeline: TimelineItem[];
-    /** Latest session status observed in the event log, if any. */
-    sessionStatus: SessionStatus | null;
-    connectionState: SessionEventsConnectionState;
-    /** Highest sequence seen so far (0 before the first event). */
-    lastSequence: number;
-    /** Exact serialized bytes retained in the current browser event window. */
-    windowBytes: number;
-    /** Whether older delivered events were evicted from the browser window. */
-    windowTruncated: boolean;
-    /** 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;
-};
-declare const SESSION_EVENT_BROWSER_MAX_BYTES: number;
-declare const SESSION_EVENT_BROWSER_MAX_COUNT = 10000;
-declare const SESSION_EVENT_BROWSER_SINGLE_EVENT_MAX_BYTES: number;
-declare const SESSION_EVENT_BROWSER_PENDING_MAX_BYTES: number;
-declare const SESSION_EVENT_BROWSER_PENDING_MAX_COUNT = 256;
-type BrowserSessionEventWindow = {
-    events: SessionEvent[];
-    bytes: number;
-    truncated: boolean;
-};
-/**
- * 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.
- */
-declare function useSessionEvents(sessionId: string | null | undefined, options?: UseSessionEventsOptions): UseSessionEventsResult;
-/**
- * Keep one direction-aware count+byte-bounded browser window. Live/default
- * accumulation retains the newest suffix; backward paging retains the oldest
- * prefix so newly fetched history cannot be immediately evicted. This is
- * deliberately separate from durable history and transport paging: when a
- * backward page evicts the live tail, the hook reconnects from the retained
- * high-water mark while preserving the highest-ever-observed sequence
- * separately. The source event remains durable in PostgreSQL throughout.
- */
-declare function boundBrowserSessionEventWindow(events: readonly SessionEvent[], options?: {
-    maxBytes?: number;
-    maxCount?: number;
-    direction?: "newest" | "oldest";
-}): BrowserSessionEventWindow;
-
 /** Events that can change the authoritative prompt queue or effective control. */
 declare function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean;
 type QueueMutationKind = "move" | "edit" | "steer" | "delete";
@@ -351,122 +287,4 @@ type UseTurnQueueResult = {
  */
 declare function useTurnQueue(sessionId: string | null | undefined, options?: UseTurnQueueOptions): UseTurnQueueResult;
 
-type UseSessionControlOptions = EmbeddedSessionClientOverride;
-type UseSessionControlResult = {
-    pause: (reason?: string) => Promise<SessionControlResponse | null>;
-    resume: (reason?: string) => Promise<SessionControlResponse | null>;
-    controlling: boolean;
-    /** Approve a pending `requires_action` approval. */
-    approve: (approvalId: string, message?: string) => Promise<SessionEvent | null>;
-    /** Reject a pending `requires_action` approval. */
-    reject: (approvalId: string, message?: string) => Promise<SessionEvent | null>;
-    /** True while an approval decision is in flight. */
-    responding: boolean;
-    error: Error | null;
-    clearError: () => void;
-};
-/**
- * Session pause/resume and approval decisions. Pair with
- * `useSessionEvents` (for `session.requiresAction` payloads carrying the
- * `approvalId`) to render an approval bar.
- */
-declare function useSessionControl(sessionId: string | null | undefined, options?: UseSessionControlOptions): UseSessionControlResult;
-
-declare function isSessionMcpApprovalPolicyEvent(event: Pick<SessionEvent, "type" | "payload">, serverId?: string): boolean;
-type UseSessionMcpApprovalPolicyOptions = EmbeddedSessionMcpApprovalPolicyClientOverride & SessionEventFeedOptions & {
-    /** Optional safety-net polling (ms). Off by default; policy events drive refreshes. */
-    pollIntervalMs?: number | undefined;
-};
-type UseSessionMcpApprovalPolicyResult = {
-    server: SessionMcpServerMetadata | null;
-    policy: SessionMcpApprovalPolicy | null;
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
-    update: (policy: SessionMcpApprovalPolicy) => Promise<UpdateSessionMcpApprovalPolicyResponse | null>;
-    updating: boolean;
-    clearError: () => void;
-};
-/**
- * Read and update one existing session MCP server's approval policy. Updates
- * become effective for the next claimed attempt; current work is unchanged.
- */
-declare function useSessionMcpApprovalPolicy(sessionId: string | null | undefined, serverId: string | null | undefined, options?: UseSessionMcpApprovalPolicyOptions): UseSessionMcpApprovalPolicyResult;
-
-type PendingApproval = {
-    /** The id to send back via `user.approvalDecision` (`approvalId`). */
-    id: string;
-    /** Tool/function name awaiting the decision. */
-    name: string;
-    arguments?: unknown;
-    /** The raw approval entry from the `session.requiresAction` payload. */
-    raw?: unknown;
-};
-/** The approvals carried by one `session.requiresAction` payload. */
-declare function approvalsFromRequiresAction(payload: unknown): PendingApproval[];
-/** The approvals still awaiting a decision after replaying `events` in order. */
-declare function projectPendingApprovals(events: SessionEvent[]): PendingApproval[];
-
-/** Minimal actionable request shape available from the durable event log. */
-type PendingHumanInputRequest = {
-    id: string;
-    turnId: string | null;
-    questions: HumanInputQuestion[];
-    allowSkip: boolean;
-    expiresAt: string | null;
-};
-/** Parse one generic `session.humanInput.requested` event defensively. */
-declare function humanInputRequestFromEvent(event: Pick<SessionEvent, "type" | "payload" | "turnId">): PendingHumanInputRequest | null;
-/**
- * Fold a durable event log into the structured requests that are actionable
- * now. Responses remove one request; a terminal owning turn clears any
- * unresolved requests that died with it. Replaying history cannot resurrect a
- * previously answered card.
- */
-declare function projectPendingHumanInputRequests(events: SessionEvent[]): PendingHumanInputRequest[];
-
-/** Events that can create, settle, or invalidate an actionable request. */
-declare function isHumanInputEvent(event: Pick<SessionEvent, "type">): boolean;
-type UseHumanInputRequestsOptions = EmbeddedHumanInputClientOverride & SessionEventFeedOptions & {
-    /** Optional safety-net polling. Durable events drive refresh by default. */
-    pollIntervalMs?: number | undefined;
-};
-type UseHumanInputRequestsResult = {
-    requests: SessionHumanInputRequest[];
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
-    respond: (requestId: string, response: SubmitHumanInputResponseRequest) => Promise<SessionEvent | null>;
-    respondingRequestId: string | null;
-    mutationError: Error | null;
-    clearMutationError: () => void;
-};
-/**
- * Authoritative structured-human-input hook. The server's pending-request
- * table is the read model; events only trigger reconciliation. This lets an
- * embedded host use the same primitive with a shared event feed or its own SDK
- * proxy without rebuilding request lifecycle logic.
- */
-declare function useHumanInputRequests(sessionId: string | null | undefined, options?: UseHumanInputRequestsOptions): UseHumanInputRequestsResult;
-
-/** Readable label for a tool call, without leaking an MCP server prefix. */
-declare function toolDisplayName(name: string): string;
-declare function buildTimeline(events: SessionEvent[]): TimelineItem[];
-/**
- * Whether the session's most recent turn ended in credit exhaustion — the
- * terminal credit state apps key their "add credits" affordances on. Derived
- * from the LAST turn-end event (completed/failed/cancelled): a later turn that
- * settles any other way (someone topped up and kept working) clears it.
- */
-declare function creditExhaustedFromEvents(events: SessionEvent[]): boolean;
-/** The latest session status carried in the event log, if any. */
-declare function sessionStatusFromEvents(events: SessionEvent[]): SessionStatus | null;
-declare function groupTimeline(items: TimelineItem[]): TimelineGroup[];
-/**
- * Find a session id in orchestration tool arguments or output. Handles raw
- * objects, JSON strings, and MCP tool results (`{ content: [{ type: "text",
- * text: "{...}" }], structuredContent? }`).
- */
-declare function extractSessionRef(value: unknown, depth?: number): string | null;
-
-export { useTurnQueue as $, type ActivityItem as A, type BrowserSessionEventWindow as B, buildTimeline as C, creditExhaustedFromEvents as D, extractSessionRef as E, groupTimeline as F, type GoalItem as G, humanInputRequestFromEvent as H, isHumanInputEvent as I, isSessionMcpApprovalPolicyEvent as J, isTurnQueueEvent as K, projectPendingApprovals as L, projectPendingHumanInputRequests as M, type NoticeItem as N, sessionStatusFromEvents as O, type PendingApproval as P, type QueueMutationKind as Q, type ReasoningItem as R, SESSION_EVENT_BROWSER_MAX_BYTES as S, type ToolCallItem as T, type UseTurnQueueResult as U, toolDisplayName as V, type WorkerItem as W, useHumanInputRequests as X, useSessionControl as Y, useSessionEvents as Z, useSessionMcpApprovalPolicy as _, type TurnOutcome as a, type MemoryItem as a0, type WorkerCompletionItem as a1, type TimelineItem as b, type AgentMessageItem as c, type UserMessageItem as d, type AuthNeededItem as e, type PendingHumanInputRequest as f, SESSION_EVENT_BROWSER_MAX_COUNT as g, SESSION_EVENT_BROWSER_PENDING_MAX_BYTES as h, SESSION_EVENT_BROWSER_PENDING_MAX_COUNT as i, SESSION_EVENT_BROWSER_SINGLE_EVENT_MAX_BYTES as j, type SandboxItem as k, type SessionEventsConnectionState as l, type SessionStatusItem as m, type TimelineGroup as n, type TurnEndItem as o, type UseHumanInputRequestsOptions as p, type UseHumanInputRequestsResult as q, type UseSessionControlOptions as r, type UseSessionControlResult as s, type UseSessionEventsOptions as t, type UseSessionEventsResult as u, type UseSessionMcpApprovalPolicyOptions as v, type UseSessionMcpApprovalPolicyResult as w, type UseTurnQueueOptions as x, approvalsFromRequiresAction as y, boundBrowserSessionEventWindow as z };
+export { type ActivityItem as A, type GoalItem as G, type MemoryItem as M, type NoticeItem as N, type QueueMutationKind as Q, type ReasoningItem as R, type SandboxItem as S, type TurnOutcome as T, type UseTurnQueueOptions as U, type WorkerItem as W, type AgentMessageItem as a, type AuthNeededItem as b, type SessionStatusItem as c, type TimelineGroup as d, type TimelineItem as e, type ToolCallItem as f, type TurnEndItem as g, type UseTurnQueueResult as h, type UserMessageItem as i, isTurnQueueEvent as j, type WorkerCompletionItem as k, useTurnQueue as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/react",
-  "version": "0.25.0",
+  "version": "0.25.5",
   "description": "React hooks and styled components for OpenGeni: live session streaming, chat composer, message timeline, session status, and fleet views — token-themed (CSS variables), dark-first, built on Tailwind v4 + Radix + Motion.",
   "license": "Apache-2.0",
   "repository": {
@@ -31,6 +31,10 @@
       "types": "./dist/session.d.ts",
       "import": "./dist/session.js"
     },
+    "./session-ui": {
+      "types": "./dist/session-ui.d.ts",
+      "import": "./dist/session-ui.js"
+    },
     "./machines": {
       "types": "./dist/machines.d.ts",
       "import": "./dist/machines.js"
@@ -62,7 +66,7 @@
     "@dnd-kit/utilities": "3.2.2",
     "@fontsource-variable/noto-sans-arabic": "5.2.10",
     "@fontsource-variable/noto-sans-jp": "5.2.10",
-    "@opengeni/sdk": "^0.25.0",
+    "@opengeni/sdk": "^0.25.5",
     "clsx": "^2.1.1",
     "lucide-react": "^1.8.0",
     "motion": "^12.0.0",

package/src/components/message-timeline.tsx

@@ -150,18 +150,23 @@ export function MessageTimeline({
   // structurally impossible — the reader only ever sees it already at the
   // bottom. An empty timeline reveals immediately (there is nothing to anchor).
   const [revealed, setRevealed] = useState(false);
-  // Our own scrollTop assignments echo back as scroll events; those must never
-  // UNPIN the reader (they are not reader intent). Marked around every
-  // programmatic assignment and consumed by onScroll. When an assignment is a
-  // NO-OP (already at the target) no scroll event will fire, so the mark must
-  // self-clear — a stale mark would eat the reader's next real scroll-up.
-  const programmaticScrollRef = useRef(false);
+  // Our own scrollTop assignments echo back as delayed scroll events. Keep the
+  // ordered, clamped targets rather than only the latest one: successive
+  // ResizeObserver corrections can queue several echoes before the browser
+  // dispatches them. If reader input lands at a different position, its value
+  // wins and clears the pending echoes. A matching echo must not recapture the
+  // visual anchor while progressive prepend is still mounting older rows.
+  const programmaticScrollTargetsRef = useRef<number[]>([]);
   const assignScrollTop = useCallback((node: HTMLElement, value: number) => {
     const previous = node.scrollTop;
-    programmaticScrollRef.current = true;
     node.scrollTop = value;
     if (node.scrollTop === previous) {
-      programmaticScrollRef.current = false;
+      return;
+    }
+    const pending = programmaticScrollTargetsRef.current;
+    pending.push(node.scrollTop);
+    if (pending.length > 32) {
+      pending.splice(0, pending.length - 32);
     }
   }, []);
   // Mirror `pinned` into a ref so the ResizeObserver callback (a stable closure)
@@ -187,9 +192,12 @@ export function MessageTimeline({
     allGroups.length > 0 && (bulkActive || firstKeyChangedForBulk || mountingOlderGroups);
 
   // Snapshot the topmost visible element and where it sits in the viewport, so a
-  // later reflow can restore it to the same spot. Transient chrome (the backfill
-  // sentinel and shimmer) is skipped — anchoring to a row that unmounts when the
-  // older window lands would drop the correction mid-prepend.
+  // later reflow can restore it to the same spot. Prefer durable row wrappers
+  // over their containing group: an older activity item can merge into the
+  // existing group, leaving that outer group in place while shifting every row
+  // after the insertion. Transient chrome (the backfill sentinel and shimmer) is
+  // skipped — anchoring to a row that unmounts when the older window lands would
+  // drop the correction mid-prepend.
   const captureAnchor = useCallback(() => {
     const node = scrollRef.current;
     const inner = node?.firstElementChild;
@@ -198,31 +206,63 @@ export function MessageTimeline({
       return;
     }
     const containerTop = node.getBoundingClientRect().top;
-    for (const child of Array.from(inner.children)) {
-      if (child instanceof HTMLElement && child.dataset.ogTimelineChrome !== undefined) {
-        continue;
-      }
-      const rect = child.getBoundingClientRect();
-      if (rect.bottom > containerTop + 1) {
-        anchorRef.current = { el: child, top: rect.top - containerTop };
-        return;
+    const findVisible = (selector: string): Element | null => {
+      for (const candidate of inner.querySelectorAll(selector)) {
+        if (candidate instanceof HTMLElement && candidate.dataset.ogTimelineChrome !== undefined) {
+          continue;
+        }
+        const rect = candidate.getBoundingClientRect();
+        if (rect.bottom > containerTop + 1 && rect.height > 0) {
+          return candidate;
+        }
       }
+      return null;
+    };
+    const anchor =
+      findVisible("[data-og-timeline-row-anchor]") ??
+      findVisible("[data-og-timeline-group-anchor]");
+    if (anchor) {
+      const rect = anchor.getBoundingClientRect();
+      anchorRef.current = { el: anchor, top: rect.top - containerTop };
+      return;
     }
     anchorRef.current = null;
   }, []);
 
-  // Follow the stream while pinned to the bottom; never fight the reader.
+  // Restore the user-owned anchor synchronously after React commits a frame.
+  // ResizeObserver remains a late-measurement fallback, but progressive history
+  // frames must be corrected before the browser can paint an intermediate jump.
+  const restoreAnchor = useCallback(
+    (node: HTMLElement) => {
+      if (autoFollow && pinnedRef.current) {
+        assignScrollTop(node, node.scrollHeight);
+        return;
+      }
+      const anchor = anchorRef.current;
+      if (!anchor || !anchor.el.isConnected) {
+        return;
+      }
+      const containerTop = node.getBoundingClientRect().top;
+      const now = anchor.el.getBoundingClientRect().top - containerTop;
+      const diff = now - anchor.top;
+      if (diff !== 0) {
+        assignScrollTop(node, node.scrollTop + diff);
+      }
+    },
+    [assignScrollTop, autoFollow],
+  );
+
   // A LAYOUT effect so the very first paint of a freshly loaded session is
   // already anchored at the bottom — no visible traversal down the history.
   useLayoutEffect(() => {
     const node = scrollRef.current;
-    if (node && autoFollow && pinned) {
-      assignScrollTop(node, node.scrollHeight);
+    if (node) {
+      restoreAnchor(node);
     }
     if (!revealed && groups.length > 0) {
       setRevealed(true);
     }
-  }, [resolvedItems, working, autoFollow, pinned, revealed, groups.length, assignScrollTop]);
+  }, [resolvedItems, working, revealed, groups.length, restoreAnchor]);
 
   // A cleared timeline (stream identity change) re-arms the reveal so the next
   // session also first paints at its bottom.
@@ -297,32 +337,26 @@ export function MessageTimeline({
       if (!current) {
         return;
       }
-      if (autoFollow && pinnedRef.current) {
-        assignScrollTop(current, current.scrollHeight);
-      } else {
-        const anchor = anchorRef.current;
-        if (anchor && anchor.el.isConnected) {
-          const containerTop = current.getBoundingClientRect().top;
-          const now = anchor.el.getBoundingClientRect().top - containerTop;
-          const diff = now - anchor.top;
-          if (diff !== 0) {
-            assignScrollTop(current, current.scrollTop + diff);
-          }
-        }
-      }
-      captureAnchor();
+      restoreAnchor(current);
     });
     observer.observe(inner);
     return () => observer.disconnect();
-  }, [autoFollow, captureAnchor, assignScrollTop]);
+  }, [restoreAnchor]);
 
   const onScroll = () => {
     const node = scrollRef.current;
     if (!node) {
       return;
     }
-    const programmatic = programmaticScrollRef.current;
-    programmaticScrollRef.current = false;
+    const pending = programmaticScrollTargetsRef.current;
+    const programmaticIndex = pending.findIndex((target) => Math.abs(node.scrollTop - target) <= 1);
+    const programmatic = programmaticIndex >= 0;
+    if (programmatic) {
+      pending.splice(0, programmaticIndex + 1);
+    } else {
+      // A real reader scroll supersedes every delayed programmatic echo.
+      pending.length = 0;
+    }
     const nextPinned = node.scrollHeight - node.scrollTop - node.clientHeight < 48;
     // Echoes of our own assignments may PIN but never UNPIN — only the reader
     // scrolling away releases the bottom-follow.
@@ -330,7 +364,12 @@ export function MessageTimeline({
       pinnedRef.current = nextPinned;
       setPinned(nextPinned);
     }
-    captureAnchor();
+    // The assignment site already captured the corrected anchor. Recapturing
+    // it from a delayed echo can observe the next prepended row before that
+    // row's ResizeObserver correction and make the viewport walk up the page.
+    if (!programmatic) {
+      captureAnchor();
+    }
   };
 
   return (
@@ -366,17 +405,18 @@ export function MessageTimeline({
                 </div>
               ) : null}
               {groups.map(({ group, key }, index) => (
-                <TimelineGroupView
-                  key={key}
-                  group={group}
-                  renderMessageText={renderMessageText}
-                  onOpenSession={onOpenSession}
-                  onMemoryClick={onMemoryClick}
-                  onReconnect={onReconnect}
-                  resolveProviderLogo={resolveProviderLogo}
-                  toolRegistry={toolRegistry}
-                  foldLiveCluster={isAgentProgress(groups[index + 1]?.group)}
-                />
+                <div key={key} data-og-timeline-group-anchor="">
+                  <TimelineGroupView
+                    group={group}
+                    renderMessageText={renderMessageText}
+                    onOpenSession={onOpenSession}
+                    onMemoryClick={onMemoryClick}
+                    onReconnect={onReconnect}
+                    resolveProviderLogo={resolveProviderLogo}
+                    toolRegistry={toolRegistry}
+                    foldLiveCluster={isAgentProgress(groups[index + 1]?.group)}
+                  />
+                </div>
               ))}
               {working ? (
                 <div className="flex items-center gap-2 text-sm">