@opengeni/react 0.23.0 → 0.25.5

package/src/hooks/use-file-attachments.ts

@@ -1,6 +1,6 @@
 import type { FileAsset, FileResourceRef } from "@opengeni/sdk";
 import { useCallback, useRef, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../provider";
+import { useOpenGeni, type ClientOverride } from "../session-context";
 
 export type UseFileAttachmentsOptions = ClientOverride & {
   /**
@@ -33,12 +33,20 @@ export type UseFileAttachmentsResult = {
    * straight into `useComposer`'s `sendExtras.resources`.
    */
   readyResources: FileResourceRef[];
-  /** True while any attachment is still uploading (drives the send-gate). */
+  /** True while any attachment is still uploading (drives progress UI). */
   uploading: boolean;
+  /**
+   * True while any attachment still needs an explicit outcome: wait for an
+   * upload, retry a failure, or remove it. This is the loss-prevention send
+   * gate; failed cards must never be silently omitted from a message.
+   */
+  hasUnresolved: boolean;
   /** Explicit picker / drop path — uploads every file, no filter. */
   addFiles: (files: Iterable<File>) => void;
   /** Clipboard path — applies `pasteFilter` (default `image/*`) then uploads. */
   addFromPaste: (event: { clipboardData: DataTransfer | null }) => void;
+  /** Restore already-ready server assets without recreating browser-local bytes. */
+  restoreReadyFiles: (files: Iterable<FileAsset>) => void;
   /**
    * Re-run the upload for a `failed` attachment, in place (same id, same
    * source file). No-op for an id that isn't a known failed upload.
@@ -46,7 +54,13 @@ export type UseFileAttachmentsResult = {
   retry: (id: string) => void;
   /** Remove one attachment; revokes its object-URL. */
   remove: (id: string) => void;
-  /** Remove all; revokes every object-URL. Call from `useComposer`'s `onSent`. */
+  /**
+   * Remove only finalized files whose durable ids were accepted by a send.
+   * Attachments added while that request was in flight remain queued for the
+   * next message.
+   */
+  removeReadyFiles: (fileIds: Iterable<string>) => void;
+  /** Remove all attachments and revoke every object-URL. */
   clear: () => void;
 };
 
@@ -83,6 +97,10 @@ export function useFileAttachments(
           data: file,
         })
         .then((asset) => {
+          // Retry bytes are useful only until durable finalization succeeds.
+          // Drop the source File immediately; restored/ready attachments must
+          // never retain browser-local byte authority.
+          sources.current.delete(id);
           setAttachments((current) =>
             current.map((attachment) =>
               attachment.id === id
@@ -171,6 +189,60 @@ export function useFileAttachments(
     [addFiles, pasteFilter],
   );
 
+  const restoreReadyFiles = useCallback(
+    (files: Iterable<FileAsset>) => {
+      const incoming = new Map<string, FileAsset>();
+      for (const file of files) {
+        if (file.status === "ready" && file.workspaceId === workspaceId) {
+          incoming.set(file.id, file);
+        }
+      }
+      setAttachments((current) => {
+        const unresolved = current.filter((attachment) => attachment.status !== "ready");
+        const existingReady = new Map(
+          current.flatMap((attachment) =>
+            attachment.status === "ready" && attachment.file
+              ? ([[attachment.file.id, attachment]] as const)
+              : [],
+          ),
+        );
+        const restored = [...incoming.values()].map((file): FileAttachment => {
+          const existing = existingReady.get(file.id);
+          return existing
+            ? {
+                ...existing,
+                name: file.filename,
+                contentType: file.contentType,
+                sizeBytes: file.sizeBytes,
+                status: "ready",
+                file,
+                error: undefined,
+              }
+            : {
+                id: `restored:${file.id}`,
+                name: file.filename,
+                contentType: file.contentType,
+                sizeBytes: file.sizeBytes,
+                status: "ready",
+                file,
+                // No source File and no object URL: server metadata is the
+                // only authority restored across page/device boundaries.
+              };
+        });
+        for (const [fileId, attachment] of existingReady) {
+          if (!incoming.has(fileId) && attachment.previewUrl) {
+            URL.revokeObjectURL(attachment.previewUrl);
+          }
+        }
+        // A server restoration is authoritative for finalized assets, but an
+        // upload that has not finalized still belongs to the local actor. Keep
+        // those unresolved entries while replacing the ready set exactly.
+        return [...unresolved, ...restored];
+      });
+    },
+    [workspaceId],
+  );
+
   const remove = useCallback((id: string) => {
     sources.current.delete(id);
     setAttachments((current) => {
@@ -182,6 +254,24 @@ export function useFileAttachments(
     });
   }, []);
 
+  const removeReadyFiles = useCallback((fileIds: Iterable<string>) => {
+    const accepted = new Set(fileIds);
+    if (accepted.size === 0) return;
+    setAttachments((current) =>
+      current.filter((attachment) => {
+        const removeAccepted =
+          attachment.status === "ready" &&
+          attachment.file !== undefined &&
+          accepted.has(attachment.file.id);
+        if (removeAccepted) {
+          sources.current.delete(attachment.id);
+          if (attachment.previewUrl) URL.revokeObjectURL(attachment.previewUrl);
+        }
+        return !removeAccepted;
+      }),
+    );
+  }, []);
+
   const clear = useCallback(() => {
     sources.current.clear();
     setAttachments((current) => {
@@ -202,10 +292,13 @@ export function useFileAttachments(
         : [],
     ),
     uploading: attachments.some((attachment) => attachment.status === "uploading"),
+    hasUnresolved: attachments.some((attachment) => attachment.status !== "ready"),
     addFiles,
     addFromPaste,
+    restoreReadyFiles,
     retry,
     remove,
+    removeReadyFiles,
     clear,
   };
 }

package/src/hooks/use-goal.ts

@@ -1,6 +1,6 @@
 import { OpenGeniApiError, type SessionEvent, type SessionGoal } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../provider";
+import { useOpenGeni, type ClientOverride } from "../session-context";
 import {
   useDebouncedCallback,
   useMutationRunner,
@@ -13,9 +13,26 @@ export function isGoalEvent(event: Pick<SessionEvent, "type">): boolean {
   return event.type.startsWith("goal.");
 }
 
+/**
+ * Events that can change the server-authoritative continuation projection.
+ * The projection is derived from durable turn, session, control, and system
+ * update state, so those events refresh the goal without model polling.
+ */
+export function isGoalRefreshEvent(event: Pick<SessionEvent, "type">): boolean {
+  const type = event.type;
+  return (
+    isGoalEvent(event) ||
+    type.startsWith("turn.") ||
+    type.startsWith("session.") ||
+    type.startsWith("system.update.") ||
+    type.startsWith("workspace.inference.") ||
+    type.startsWith("user.")
+  );
+}
+
 export type UseGoalOptions = ClientOverride &
   SessionEventFeedOptions & {
-    /** Optional safety-net polling (ms). Off by default — goal.* events drive updates. */
+    /** Optional safety-net polling (ms). Off by default — event refreshes drive updates. */
     pollIntervalMs?: number | undefined;
   };
 
@@ -46,8 +63,9 @@ export type UseGoalResult = {
 /**
  * The session's goal: state, the autonomy counters (`autoContinuations`,
  * `noProgressStreak`), and pause/resume control. A goal-less session yields
- * `goal: null` (the 404 is absorbed). Live-updates on `goal.*` events —
- * pass `options.events` from `useSessionEvents` to reuse its stream.
+ * `goal: null` (the 404 is absorbed). Live-updates on goal, turn, session,
+ * control, and system-update events — pass `options.events` from
+ * `useSessionEvents` to reuse its stream.
  */
 export function useGoal(
   sessionId: string | null | undefined,
@@ -124,7 +142,7 @@ export function useGoal(
   }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs, sharedFeed]);
 
   const scheduleRefresh = useDebouncedCallback(() => void load());
-  useSessionEventTrigger(client, workspaceId, sessionId, isGoalEvent, scheduleRefresh, {
+  useSessionEventTrigger(client, workspaceId, sessionId, isGoalRefreshEvent, scheduleRefresh, {
     enabled,
     ...(sharedEvents !== undefined ? { events: sharedEvents } : {}),
   });

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

@@ -858,6 +858,11 @@ async function loadPreviousPage(
     before,
     limit: requested,
     compact: true,
+    // Monitoring summaries omit correlation fields once a bounded durable
+    // payload exceeds their preview threshold. The browser timeline needs the
+    // sanitized stored payload so persisted tool outputs still match their
+    // calls and expose truthful truncation telemetry after a reload.
+    payloadMode: "full",
   });
   if (options.signal?.aborted) {
     throw abortError();

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

@@ -1,6 +1,6 @@
 import type { SessionEvent, SessionLineageResponse } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef } from "react";
-import { useOpenGeni, type ClientOverride } from "../provider";
+import { useOpenGeni, type ClientOverride } from "../session-context";
 import { useDebouncedCallback, usePolledValue, useSessionEventTrigger } from "./internal";
 
 export type UseSessionLineageOptions = ClientOverride & {

package/src/hooks/use-session.ts

@@ -1,6 +1,6 @@
 import type { Session, SessionEvent } from "@opengeni/sdk";
-import { useCallback, useEffect, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../provider";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useOpenGeni, type ClientOverride } from "../session-context";
 import {
   useMutationRunner,
   usePolledValue,
@@ -66,10 +66,13 @@ export function useSession(
   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 = useMemo(
+    () =>
+      base && override && override.id === base.id
+        ? { ...base, title: override.title, titleSource: override.titleSource }
+        : base,
+    [base, override],
+  );
 
   // 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.

package/src/hooks/use-workspace-sessions.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@opengeni/sdk";
-import { useCallback } from "react";
+import { useCallback, useEffect, useRef } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
 import { usePolledValue } from "./internal";
 
@@ -8,6 +8,8 @@ export type UseWorkspaceSessionsOptions = ClientOverride & {
   parentSessionId?: string | null | undefined;
   cursor?: string | undefined;
   search?: string | undefined;
+  /** Return only the complete personal pinned projection. */
+  pinsOnly?: boolean | undefined;
   /** Refresh interval (ms) for fleet/manager views. Off by default. */
   pollIntervalMs?: number | undefined;
   enabled?: boolean | undefined;
@@ -38,7 +40,21 @@ export function useWorkspaceSessions(
   const parentSessionId = options.parentSessionId;
   const cursor = options.cursor;
   const search = options.search;
-  const queryKey = JSON.stringify({ workspaceId, limit, parentSessionId, cursor, search });
+  const pinsOnly = options.pinsOnly;
+  const enabled = options.enabled ?? true;
+  const queryKey = [
+    workspaceId,
+    limit ?? "",
+    parentSessionId === null ? "null" : (parentSessionId ?? ""),
+    cursor ?? "",
+    search ?? "",
+    pinsOnly ? "1" : "",
+  ].join("\u0000");
+  const previousQueryKey = useRef(queryKey);
+  const queryKeyTransition = previousQueryKey.current !== queryKey;
+  useEffect(() => {
+    previousQueryKey.current = queryKey;
+  }, [queryKey]);
   const load = useCallback(
     async () => ({
       queryKey,
@@ -47,13 +63,14 @@ export function useWorkspaceSessions(
         ...(parentSessionId !== undefined ? { parentSessionId } : {}),
         ...(cursor !== undefined ? { cursor } : {}),
         ...(search !== undefined ? { search } : {}),
+        ...(pinsOnly ? { pinsOnly: true } : {}),
       }),
     }),
-    [client, workspaceId, limit, parentSessionId, cursor, search, queryKey],
+    [client, workspaceId, limit, parentSessionId, cursor, search, pinsOnly, queryKey],
   );
   const state = usePolledValue(load, {
     pollIntervalMs: options.pollIntervalMs,
-    enabled: options.enabled,
+    enabled,
   });
   // usePolledValue drops stale async completions, while the explicit query key
   // also prevents the previous query's cached value from painting for the one
@@ -69,7 +86,15 @@ export function useWorkspaceSessions(
     pinned,
     pinnedTruncated: page?.pinnedTruncated ?? false,
     nextCursor: page?.nextCursor ?? null,
-    loading: state.loading,
+    // `usePolledValue` clears the old data and starts the new request in an
+    // effect. During that query-key transition render, its old loading flag
+    // can still be false; expose loading immediately so consumers do not
+    // announce a transient false zero-match result.
+    loading:
+      enabled &&
+      (state.loading ||
+        queryKeyTransition ||
+        (state.data !== null && state.data.queryKey !== queryKey)),
     error: state.error,
     refresh: state.refresh,
   };

package/src/session-ui.ts

@@ -0,0 +1,13 @@
+// @opengeni/react/session-ui — styled surfaces used by the session route.
+// Keep these separate from the hook-only session entry and the broad root barrel
+// so session hosts do not pay for unrelated React surfaces.
+export { HumanInputForm } from "./components/human-input-form";
+export type {
+  HumanInputAnswerDraft,
+  HumanInputFormMessages,
+  HumanInputFormProps,
+} from "./components/human-input-form";
+export { MessageTimeline, TimelineRow } from "./components/message-timeline";
+export type { MessageTimelineProps } from "./components/message-timeline";
+export { QueueSurface } from "./components/queue-surface";
+export type { QueueSurfaceProps } from "./components/queue-surface";

package/src/session.ts

@@ -15,6 +15,8 @@ export type {
   EmbeddedSessionClientOverride as ClientOverride,
 } from "./session-context";
 
+export { useSession, isTitleEvent } from "./hooks/use-session";
+export type { UseSessionOptions, UseSessionResult } from "./hooks/use-session";
 export { useSessionEvents } from "./hooks/use-session-events";
 export type {
   SessionEventsConnectionState,
@@ -29,12 +31,25 @@ export {
   FILE_ONLY_MESSAGE_TEXT,
 } from "./hooks/use-composer";
 export type { ComposerSendExtras, ComposerState, UseComposerOptions } from "./hooks/use-composer";
+export { useFileAttachments } from "./hooks/use-file-attachments";
+export type {
+  FileAttachment,
+  UseFileAttachmentsOptions,
+  UseFileAttachmentsResult,
+} from "./hooks/use-file-attachments";
 export { useTurnQueue, isTurnQueueEvent } from "./hooks/use-turn-queue";
 export type {
   QueueMutationKind,
   UseTurnQueueOptions,
   UseTurnQueueResult,
 } from "./hooks/use-turn-queue";
+export { useGoal, isGoalEvent } from "./hooks/use-goal";
+export type { UseGoalOptions, UseGoalResult } from "./hooks/use-goal";
+export { useSessionLineage, isLineageRefreshEvent } from "./hooks/use-session-lineage";
+export type {
+  UseSessionLineageOptions,
+  UseSessionLineageResult,
+} from "./hooks/use-session-lineage";
 export { useSessionControl } from "./hooks/use-session-control";
 export type {
   UseSessionControlOptions,

package/src/timeline/activity-rail.tsx

@@ -5,15 +5,19 @@ import {
   BrainIcon,
   SquareTerminalIcon,
 } from "lucide-react";
+import { lazy, Suspense } from "react";
+import { jsx as rowJsx, jsxs as rowJsxs } from "react/jsx-runtime";
 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 { BodyNote, PayloadBlock, ActivityDisclosure } from "./shared";
-import { toolDisplayName } from "./projection";
+import { toolDisplayName } from "./tool-display-name";
 import type { ActivityItem, MemoryItem, ReasoningItem, SandboxItem, WorkerItem } from "./types";
 
+const LazyFleetDecisionRow = lazy(() => import("./fleet-decision-row"));
+
 /* ----------------------------------------------------------------------------
    Activity rail
 
@@ -79,7 +83,7 @@ export function ActivityRail({
         const newFamily = index > 0 && familyOf(item) !== familyOf(items[index - 1]!);
         const row = renderActivity(item, toolRegistry, onOpenSession, onMemoryClick);
         return (
-          <div key={item.id} className={cn(newFamily && "mt-3")}>
+          <div key={item.id} data-og-timeline-row-anchor="" className={cn(newFamily && "mt-3")}>
             {row}
           </div>
         );
@@ -112,6 +116,18 @@ function renderActivity(
       return <SandboxRow item={item} />;
     case "memory":
       return <MemoryRow item={item} onMemoryClick={onMemoryClick} />;
+    case "fleet-decision":
+      return (
+        <Suspense fallback={null}>
+          <LazyFleetDecisionRow
+            item={item}
+            d={ActivityDisclosure}
+            b={BodyNote}
+            j={rowJsx}
+            s={rowJsxs}
+          />
+        </Suspense>
+      );
     default:
       return assertNever(item);
   }