@opengeni/react 0.6.3 → 0.9.0

package/dist/{machines-Bv9tG7qZ.d.ts → machines-BeZ3bD3t.d.ts}

@@ -7,7 +7,7 @@ import { ReactNode } from 'react';
  * pass the real SDK client, a proxy-backed client that routes through their
  * own API, or a scripted client in tests/demos.
  */
-type SessionClientLike = Pick<OpenGeniClient, "getClientConfig" | "getSession" | "updateSession" | "listSessions" | "sendMessage" | "steerMessage" | "interrupt" | "sendApprovalDecision" | "streamEvents" | "listTurns" | "updateQueuedTurn" | "reorderQueuedTurns" | "deleteQueuedTurn" | "getGoal" | "updateGoal" | "clearSessionContext" | "compactSessionContext" | "listScheduledTasks" | "uploadFile" | "getFile" | "createFileDownloadUrl" | "listEnvironments" | "createEnvironment" | "updateEnvironment" | "deleteEnvironment" | "setEnvironmentVariable" | "deleteEnvironmentVariable" | "listPacks" | "registerPack" | "enablePack" | "deletePack" | "listWorkspaces" | "createWorkspace" | "updateWorkspace" | "getBillingUsage" | "getClientConfig" | "getStreamCapabilities" | "acknowledgeStream" | "attachViewer" | "heartbeatViewer" | "detachViewer" | "fsList" | "fsRead" | "fsWrite" | "fsDelete" | "fsMove" | "fsMkdir" | "gitStatus" | "gitDiff" | "terminalExec" | "terminalPtyOpen" | "terminalPtyWrite" | "terminalPtyResize" | "terminalPtyClose">;
+type SessionClientLike = Pick<OpenGeniClient, "getClientConfig" | "getSession" | "updateSession" | "listSessions" | "sendMessage" | "steerMessage" | "interrupt" | "sendApprovalDecision" | "listEvents" | "streamEvents" | "listTurns" | "updateQueuedTurn" | "reorderQueuedTurns" | "deleteQueuedTurn" | "getGoal" | "updateGoal" | "clearSessionContext" | "compactSessionContext" | "listScheduledTasks" | "uploadFile" | "getFile" | "createFileDownloadUrl" | "listEnvironments" | "createEnvironment" | "updateEnvironment" | "deleteEnvironment" | "setEnvironmentVariable" | "deleteEnvironmentVariable" | "listPacks" | "registerPack" | "enablePack" | "deletePack" | "listWorkspaces" | "createWorkspace" | "updateWorkspace" | "getBillingUsage" | "getClientConfig" | "getStreamCapabilities" | "acknowledgeStream" | "attachViewer" | "heartbeatViewer" | "detachViewer" | "fsList" | "fsRead" | "fsWrite" | "fsDelete" | "fsMove" | "fsMkdir" | "gitStatus" | "gitDiff" | "terminalExec" | "terminalPtyOpen" | "terminalPtyWrite" | "terminalPtyResize" | "terminalPtyClose">;
 
 type OpenGeniContextValue = {
     client: SessionClientLike;

package/dist/machines.d.ts

@@ -1,4 +1,4 @@
-export { a as CONNECTION_STATUS_META, b as ConnectionDot, c as ConnectionDotProps, d as ConnectionStatus, e as ConnectionStatusMeta, f as ConnectionStatusPill, g as ConnectionStatusPillProps, D as DeviceFlowPhase, E as EnrollmentConsent, h as EnrollmentConsentMachine, i as EnrollmentConsentPhase, j as EnrollmentConsentProps, k as EnrollmentDeviceFlow, l as EnrollmentDeviceFlowProps, M as MACHINE_STATE_BADGE_META, m as MachineCard, n as MachineCardProps, o as MachineDockBar, p as MachineDockBarProps, q as MachineMetrics, r as MachineMetricsProps, s as MachineStateBadgeMeta, t as MachineStatusPill, u as MachineStatusPillProps, v as MachinesClientLike, w as MachinesDashboard, x as MachinesDashboardProps, A as SharedMachineDisclosure, B as SharedMachineDisclosureProps, U as UseMachinesOptions, F as UseMachinesResult, G as connectionStatusForState, H as useMachines } from './machines-Bv9tG7qZ.js';
+export { a as CONNECTION_STATUS_META, b as ConnectionDot, c as ConnectionDotProps, d as ConnectionStatus, e as ConnectionStatusMeta, f as ConnectionStatusPill, g as ConnectionStatusPillProps, D as DeviceFlowPhase, E as EnrollmentConsent, h as EnrollmentConsentMachine, i as EnrollmentConsentPhase, j as EnrollmentConsentProps, k as EnrollmentDeviceFlow, l as EnrollmentDeviceFlowProps, M as MACHINE_STATE_BADGE_META, m as MachineCard, n as MachineCardProps, o as MachineDockBar, p as MachineDockBarProps, q as MachineMetrics, r as MachineMetricsProps, s as MachineStateBadgeMeta, t as MachineStatusPill, u as MachineStatusPillProps, v as MachinesClientLike, w as MachinesDashboard, x as MachinesDashboardProps, A as SharedMachineDisclosure, B as SharedMachineDisclosureProps, U as UseMachinesOptions, F as UseMachinesResult, G as connectionStatusForState, H as useMachines } from './machines-BeZ3bD3t.js';
 export { MachineKind, MachineMetricsSeriesResponse, MachineState, MachineView, MachinesResponse, MetricSample } from '@opengeni/sdk';
 import 'react/jsx-runtime';
 import 'react';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/react",
-  "version": "0.6.3",
+  "version": "0.9.0",
   "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": {
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.2.0",
-    "@opengeni/sdk": "^0.6.3",
+    "@opengeni/sdk": "^0.9.0",
     "clsx": "^2.1.1",
     "lucide-react": "^1.8.0",
     "motion": "^12.0.0",

package/src/client.ts

@@ -17,6 +17,7 @@ export type SessionClientLike = Pick<
   | "steerMessage"
   | "interrupt"
   | "sendApprovalDecision"
+  | "listEvents"
   | "streamEvents"
   // Turn queue
   | "listTurns"

package/src/components/message-timeline.tsx

@@ -11,7 +11,7 @@ import {
 } from "lucide-react";
 import type { ComponentType } from "react";
 import { AnimatePresence, motion } from "motion/react";
-import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { formatRelativeTime, truncate } from "../lib/format";
 import { Markdown } from "./markdown";
@@ -32,6 +32,7 @@ import {
   TurnSummary,
 } from "../timeline";
 import { SESSION_STATUS_META, StatusDot } from "./session-status";
+import { EntranceAnimationProvider, useEntranceAnimation } from "../timeline/entrance";
 
 export type MessageTimelineProps = {
   /** Raw session events (projected internally) … */
@@ -52,6 +53,12 @@ export type MessageTimelineProps = {
   toolRegistry?: ToolRegistry | undefined;
   /** Follow new events when pinned to the bottom. Defaults to true. */
   autoFollow?: boolean | undefined;
+  /** Older durable history exists above the current window (see useSessionEvents). */
+  hasOlder?: boolean | undefined;
+  /** An older window is being fetched; shows the quiet top shimmer. */
+  loadingOlder?: boolean | undefined;
+  /** Called when the reader nears the top and older history should backfill. */
+  onLoadOlder?: (() => void) | undefined;
   emptyState?: ReactNode | undefined;
   className?: string | undefined;
 };
@@ -70,14 +77,40 @@ export function MessageTimeline({
   onOpenSession,
   toolRegistry = defaultToolRegistry,
   autoFollow = true,
+  hasOlder = false,
+  loadingOlder = false,
+  onLoadOlder,
   emptyState,
   className,
 }: MessageTimelineProps) {
   const resolvedItems = useMemo(() => items ?? buildTimeline(events ?? []), [items, events]);
   const groups = useMemo(() => groupTimeline(resolvedItems), [resolvedItems]);
+  const firstGroupKey = groups[0] ? timelineGroupKey(groups[0]) : null;
 
   const scrollRef = useRef<HTMLDivElement | null>(null);
+  const topSentinelRef = useRef<HTMLDivElement | null>(null);
+  const previousBulkFirstKeyRef = useRef<string | null | undefined>(undefined);
   const [pinned, setPinned] = useState(true);
+  const [bulkActive, setBulkActive] = useState(true);
+  // Content stays invisible until its first bottom-anchored frame, so a flash
+  // of the window's TOP while a large timeline lays out across commits is
+  // 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);
+  const assignScrollTop = useCallback((node: HTMLElement, value: number) => {
+    const previous = node.scrollTop;
+    programmaticScrollRef.current = true;
+    node.scrollTop = value;
+    if (node.scrollTop === previous) {
+      programmaticScrollRef.current = false;
+    }
+  }, []);
   // Mirror `pinned` into a ref so the ResizeObserver callback (a stable closure)
   // always reads the live value without re-subscribing on every scroll.
   const pinnedRef = useRef(true);
@@ -89,9 +122,15 @@ export function MessageTimeline({
   const lastItem = resolvedItems[resolvedItems.length - 1];
   const streaming = lastItem !== undefined && (lastItem.kind === "agent-message" || lastItem.kind === "reasoning") && lastItem.streaming;
   const working = status === "running" && !streaming;
+  // Bulk paints (the initial tail window, a prepended older window — detected
+  // by the first group key changing) must not run per-row entrance animations.
+  const firstKeyChangedForBulk = previousBulkFirstKeyRef.current !== undefined && previousBulkFirstKeyRef.current !== firstGroupKey;
+  const bulkRender = groups.length > 0 && (bulkActive || firstKeyChangedForBulk);
 
   // Snapshot the topmost visible element and where it sits in the viewport, so a
-  // later reflow can restore it to the same spot.
+  // 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.
   const captureAnchor = useCallback(() => {
     const node = scrollRef.current;
     const inner = node?.firstElementChild;
@@ -101,6 +140,9 @@ export function MessageTimeline({
     }
     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 };
@@ -111,12 +153,56 @@ export function MessageTimeline({
   }, []);
 
   // Follow the stream while pinned to the bottom; never fight the reader.
-  useEffect(() => {
+  // 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) {
-      node.scrollTop = node.scrollHeight;
+      assignScrollTop(node, node.scrollHeight);
+    }
+    if (!revealed && groups.length > 0) {
+      setRevealed(true);
+    }
+  }, [resolvedItems, working, autoFollow, pinned, revealed, groups.length, assignScrollTop]);
+
+  // A cleared timeline (stream identity change) re-arms the reveal so the next
+  // session also first paints at its bottom.
+  useLayoutEffect(() => {
+    if (groups.length === 0 && revealed) {
+      setRevealed(false);
     }
-  }, [resolvedItems, working, autoFollow, pinned]);
+  }, [groups.length, revealed]);
+
+  // Clear the bulk-paint marker a frame after it renders, so rows appended
+  // live (streams, new turns) animate exactly as before.
+  useLayoutEffect(() => {
+    previousBulkFirstKeyRef.current = firstGroupKey;
+    if (!bulkRender) {
+      return;
+    }
+    setBulkActive(true);
+    const frame = requestFrame(() => setBulkActive(false));
+    return () => cancelFrame(frame);
+  }, [bulkRender, firstGroupKey]);
+
+  // Prefetch older history well before the reader reaches the top: the
+  // sentinel sits above the first group and trips 1600px early, so backfill
+  // is usually rendered (and anchored by the ResizeObserver below) before the
+  // top of the window ever becomes visible.
+  useEffect(() => {
+    const root = scrollRef.current;
+    const target = topSentinelRef.current;
+    if (!root || !target || !hasOlder || loadingOlder || !onLoadOlder || typeof IntersectionObserver === "undefined") {
+      return;
+    }
+    const observer = new IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) {
+        onLoadOlder();
+      }
+    }, { root, rootMargin: "1600px 0px 0px 0px" });
+    observer.observe(target);
+    return () => observer.disconnect();
+  }, [hasOlder, loadingOlder, onLoadOlder, firstGroupKey]);
 
   // Scroll anchoring: when the content reflows (a fold expands/collapses, a
   // stream appends), keep following the bottom if pinned; otherwise pin the
@@ -136,7 +222,7 @@ export function MessageTimeline({
         return;
       }
       if (autoFollow && pinnedRef.current) {
-        current.scrollTop = current.scrollHeight;
+        assignScrollTop(current, current.scrollHeight);
       } else {
         const anchor = anchorRef.current;
         if (anchor && anchor.el.isConnected) {
@@ -144,7 +230,7 @@ export function MessageTimeline({
           const now = anchor.el.getBoundingClientRect().top - containerTop;
           const diff = now - anchor.top;
           if (diff !== 0) {
-            current.scrollTop += diff;
+            assignScrollTop(current, current.scrollTop + diff);
           }
         }
       }
@@ -152,27 +238,47 @@ export function MessageTimeline({
     });
     observer.observe(inner);
     return () => observer.disconnect();
-  }, [autoFollow, captureAnchor]);
+  }, [autoFollow, captureAnchor, assignScrollTop]);
 
   const onScroll = () => {
     const node = scrollRef.current;
     if (!node) {
       return;
     }
+    const programmatic = programmaticScrollRef.current;
+    programmaticScrollRef.current = false;
     const nextPinned = node.scrollHeight - node.scrollTop - node.clientHeight < 48;
-    pinnedRef.current = nextPinned;
-    setPinned(nextPinned);
+    // Echoes of our own assignments may PIN but never UNPIN — only the reader
+    // scrolling away releases the bottom-follow.
+    if (nextPinned || !programmatic) {
+      pinnedRef.current = nextPinned;
+      setPinned(nextPinned);
+    }
     captureAnchor();
   };
 
   return (
     <LightboxProvider>
+    <EntranceAnimationProvider value={!bulkRender}>
     <div className={cn("og-root relative flex min-h-0 flex-col", className)}>
-      <div ref={scrollRef} onScroll={onScroll} className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-4 py-6 sm:px-6">
+      {/* overflow-anchor off: the browser's native scroll anchoring would fight
+          the ResizeObserver corrections above — one authority only. */}
+      <div
+        ref={scrollRef}
+        onScroll={onScroll}
+        style={groups.length > 0 && !revealed ? { visibility: "hidden" } : undefined}
+        className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-4 py-6 [overflow-anchor:none] sm:px-6"
+      >
         <div className="mx-auto flex w-full max-w-3xl flex-col gap-5">
           {groups.length === 0 && !working
             ? (emptyState ?? <p className="py-10 text-center text-sm text-og-fg-subtle">No activity yet.</p>)
             : null}
+          {hasOlder ? <div ref={topSentinelRef} data-og-top-sentinel="" data-og-timeline-chrome="" aria-hidden="true" className="h-px w-full shrink-0" /> : null}
+          {loadingOlder ? (
+            <div data-og-timeline-chrome="" className="flex items-center gap-2 text-sm">
+              <span className="og-shimmer-text font-medium">Loading earlier activity…</span>
+            </div>
+          ) : null}
           {groups.map((group) => (
             <TimelineGroupView
               key={timelineGroupKey(group)}
@@ -183,7 +289,7 @@ export function MessageTimeline({
             />
           ))}
           {working ? (
-            <div className="animate-og-enter flex items-center gap-2 text-sm">
+            <div className="flex items-center gap-2 text-sm">
               <span className="og-shimmer-text font-medium">Working…</span>
             </div>
           ) : null}
@@ -218,10 +324,26 @@ export function MessageTimeline({
         ) : null}
       </AnimatePresence>
     </div>
+    </EntranceAnimationProvider>
     </LightboxProvider>
   );
 }
 
+function requestFrame(callback: FrameRequestCallback): number {
+  if (typeof requestAnimationFrame === "function") {
+    return requestAnimationFrame(callback);
+  }
+  return window.setTimeout(() => callback(performance.now()), 16);
+}
+
+function cancelFrame(id: number): void {
+  if (typeof cancelAnimationFrame === "function") {
+    cancelAnimationFrame(id);
+    return;
+  }
+  window.clearTimeout(id);
+}
+
 function TimelineGroupView({
   group,
   renderMessageText,
@@ -353,8 +475,9 @@ function UserMessageRow({
   item: UserMessageItem;
   renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
 }) {
+  const enter = useEntranceAnimation();
   return (
-    <div className="animate-og-enter flex justify-end">
+    <div className={cn(enter && "animate-og-enter", "flex justify-end")}>
       <div className="flex max-w-[85%] min-w-0 flex-col items-end gap-1">
         {item.pending ? <span className="px-1 text-og-xs text-og-fg-subtle">queued</span> : null}
         <div className="w-fit max-w-full min-w-0 rounded-og-lg rounded-br-og-xs border border-og-border bg-og-surface-2 px-4 py-2.5 text-og-md leading-6 text-og-fg">
@@ -372,11 +495,12 @@ function AgentMessageRow({
   item: AgentMessageItem;
   renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
 }) {
+  const enter = useEntranceAnimation();
   const caret = item.streaming ? (
     <span className="ml-0.5 inline-block h-[1.1em] w-[2px] translate-y-[3px] animate-og-blink rounded-full bg-og-accent" aria-hidden />
   ) : null;
   return (
-    <div className="animate-og-enter min-w-0 text-og-md leading-7 text-og-fg">
+    <div className={cn(enter && "animate-og-enter", "min-w-0 text-og-md leading-7 text-og-fg")}>
       {renderMessageText ? (
         <>
           {renderMessageText(item.text, item)}
@@ -396,9 +520,10 @@ function AgentMessageRow({
 }
 
 function SessionStatusRow({ item }: { item: { status: SessionStatus; occurredAt: string } }) {
+  const enter = useEntranceAnimation();
   const meta = SESSION_STATUS_META[item.status];
   return (
-    <div className="animate-og-enter flex items-center gap-3 text-og-xs text-og-fg-subtle" role="status">
+    <div className={cn(enter && "animate-og-enter", "flex items-center gap-3 text-og-xs text-og-fg-subtle")} role="status">
       <span className="h-px flex-1 bg-og-border" />
       <span className="inline-flex items-center gap-1.5">
         <StatusDot status={item.status} className="size-1" />
@@ -445,9 +570,10 @@ const GOAL_META: Record<GoalItem["action"], GoalMeta> = {
  * palette stays restrained — see that table for the per-action rationale.
  */
 function GoalRow({ item }: { item: GoalItem }) {
+  const enter = useEntranceAnimation();
   const { label, pill, icon: Icon } = GOAL_META[item.action];
   return (
-    <div className="animate-og-enter flex justify-center">
+    <div className={cn(enter && "animate-og-enter", "flex justify-center")}>
       <span className={cn("inline-flex max-w-full items-center gap-1.5 rounded-full border px-3 py-1 text-og-sm", pill)}>
         <Icon className="size-3.5 shrink-0" />
         <span className="truncate">
@@ -460,6 +586,7 @@ function GoalRow({ item }: { item: GoalItem }) {
 }
 
 function NoticeRow({ item }: { item: NoticeItem }) {
+  const enter = useEntranceAnimation();
   const tone =
     item.tone === "failed"
       ? "border-og-status-failed/35 bg-og-status-failed/10 text-og-status-failed"
@@ -467,7 +594,7 @@ function NoticeRow({ item }: { item: NoticeItem }) {
         ? "border-og-status-waiting/35 bg-og-status-waiting/10 text-og-status-waiting"
         : "border-og-border bg-og-surface-1 text-og-fg-muted";
   return (
-    <div className={cn("animate-og-enter flex items-start gap-2.5 rounded-og-md border px-3.5 py-2.5 text-sm", tone)} role="status">
+    <div className={cn(enter && "animate-og-enter", "flex items-start gap-2.5 rounded-og-md border px-3.5 py-2.5 text-sm", tone)} role="status">
       <TriangleAlertIcon className={cn("mt-0.5 size-4 shrink-0", item.tone === "cancelled" && "opacity-60")} />
       <span className="min-w-0 whitespace-pre-wrap break-words">{item.text}</span>
     </div>

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

@@ -52,8 +52,9 @@ export type UseSessionCapabilitiesOptions = ClientOverride & {
   warmingPollMs?: number | undefined;
   /**
    * Give up waiting for `warm` after this long while polling (ms) and surface a
-   * stalled error with a manual `renegotiate`. Default 30000 (must agree with
-   * the lease warming TTL — I15). 0 disables the deadline.
+   * stalled error with a manual `renegotiate`. Default 30000. This is a UI
+   * patience deadline, independent from the worker's sandbox warming timeout.
+   * 0 disables the deadline.
    */
   warmingDeadlineMs?: number | undefined;
 };