@opengeni/react 2.5.0-canary.2 → 3.1.0

package/src/components/sandbox-files.tsx

@@ -10,6 +10,7 @@ import {
   type UseSandboxFilesResult,
 } from "../hooks/use-sandbox-files";
 import type { UseSandboxGitResult } from "../hooks/use-sandbox-git";
+import { filePathVisibility, type FileNodeVisibilityPredicate } from "../file-node-visibility";
 import { CodeEditor } from "./code-editor";
 import { FileBrowser } from "./file-browser";
 import { PierreFile } from "./pierre-file";
@@ -37,6 +38,8 @@ export type SandboxFilesProps = {
    * surface the ordinary file-view error instead of changing files silently. */
   initialSelectedPath?: string | null | undefined;
   onSelectedPathChange?: ((path: string | null) => void) | undefined;
+  /** Presentation-only node filter shared with the tree and selected-file view. */
+  isNodeVisible?: FileNodeVisibilityPredicate | undefined;
   /** A deliberate file-open path routed here by the parent workspace. */
   requestedPath?: string | undefined;
   /** 1-based line to reveal after `requestedPath` opens. */
@@ -76,6 +79,7 @@ export function SandboxFiles({
   onEditIntent,
   initialSelectedPath,
   onSelectedPathChange,
+  isNodeVisible,
   requestedPath,
   requestedLine,
   requestedPathRequestId,
@@ -118,6 +122,19 @@ export function SandboxFiles({
       setTreeRevealRequest(null);
       return;
     }
+    if (isNodeVisible && files.loading && files.tree.length === 0) return;
+    if (isNodeVisible && !files.loading && files.tree.length === 0) {
+      handledRequestRef.current = requestKey;
+      pendingRequestRef.current = null;
+      setTreeRevealRequest(null);
+      return;
+    }
+    if (filePathVisibility(files.tree, requestedPath, isNodeVisible) === "hidden") {
+      handledRequestRef.current = requestKey;
+      pendingRequestRef.current = null;
+      setTreeRevealRequest(null);
+      return;
+    }
     handledRequestRef.current = requestKey;
     pendingRequestRef.current = null;
     setSelected(requestedPath);
@@ -126,7 +143,16 @@ export function SandboxFiles({
     setFocusLine(requestedLine != null && requestedLine > 0 ? requestedLine : null);
     setTreeRevealRequest({ path: requestedPath, requestId: requestKey });
     setViewReloadRevision((revision) => revision + 1);
-  }, [onSelectedPathChange, requestKey, requestedLine, requestedPath, requestedPathReady]);
+  }, [
+    files.loading,
+    files.tree,
+    isNodeVisible,
+    onSelectedPathChange,
+    requestKey,
+    requestedLine,
+    requestedPath,
+    requestedPathReady,
+  ]);
 
   // Side-by-side (tree left, viewer right) once the surface is wide enough;
   // stacked (tree over viewer) on a narrow dock. Tracked off the container so it
@@ -165,7 +191,20 @@ export function SandboxFiles({
   // The selected tree file opens in the viewer (read-only) or the editor (when
   // writable). Nothing is auto-selected — the pane waits for a tree click, so the
   // Files tab opens as a calm browser, not a diff.
-  const viewPath = selected;
+  const selectedVisibility = selected
+    ? filePathVisibility(files.tree, selected, isNodeVisible)
+    : "unknown";
+  const visibilityPending = Boolean(isNodeVisible && files.loading && files.tree.length === 0);
+  const viewPath = selectedVisibility === "hidden" || visibilityPending ? null : selected;
+  useEffect(() => {
+    if (selected === null || selectedVisibility !== "hidden") return;
+    setSelected(null);
+    onSelectedPathChange?.(null);
+    setEditMode(false);
+    setFocusLine(null);
+    setTreeRevealRequest(null);
+    setLiveRequestedPath(null);
+  }, [onSelectedPathChange, selected, selectedVisibility]);
   const fileView = useFileView(
     viewPath,
     files.readFile,
@@ -297,6 +336,7 @@ export function SandboxFiles({
         >
           <FileBrowser
             result={files}
+            isNodeVisible={isNodeVisible}
             selectedPath={selected ?? undefined}
             {...(treeRevealRequest
               ? {

package/src/components/sandbox-workspace.tsx

@@ -45,6 +45,7 @@ import { xtermThemeFromTokens } from "../lib/xterm-theme";
 import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 import type { BrowserFrameWebSocketFactory } from "../hooks/use-browser-frame-stream";
 import type { ComputerFrameWebSocketFactory } from "../hooks/use-computer-frame-stream";
+import type { FileNodeVisibilityPredicate } from "../file-node-visibility";
 import { useSessionCapabilities } from "../hooks/use-session-capabilities";
 import { useSandboxFiles } from "../hooks/use-sandbox-files";
 import {
@@ -301,6 +302,8 @@ export type UseSandboxWorkspaceTabsOptions = ClientOverride & {
   /** Restore and report navigation inside the built-in workbench surfaces. */
   initialFilePath?: string | null | undefined;
   onFilePathChange?: ((path: string | null) => void) | undefined;
+  /** Presentation-only filter for Files tree nodes and selected-file viewing. */
+  isFileNodeVisible?: FileNodeVisibilityPredicate | undefined;
   initialBrowserSessionId?: string | null | undefined;
   onBrowserSessionIdChange?: ((browserSessionId: string | null) => void) | undefined;
   initialComputerSessionId?: string | null | undefined;
@@ -361,6 +364,7 @@ export function useSandboxWorkspaceTabs(
     onOpenFile,
     initialFilePath,
     onFilePathChange,
+    isFileNodeVisible,
     initialBrowserSessionId,
     onBrowserSessionIdChange,
     initialComputerSessionId,
@@ -752,6 +756,7 @@ export function useSandboxWorkspaceTabs(
             key={sessionId}
             files={files}
             git={git}
+            isNodeVisible={isFileNodeVisible}
             fileSystemAvailable={fileSystemOn || captureAvailable}
             editable={
               filesEditable && files.source === "live" && files.error === null && !files.loading
@@ -900,6 +905,7 @@ export function useSandboxWorkspaceTabs(
     onOpenFile,
     initialFilePath,
     onFilePathChange,
+    isFileNodeVisible,
     initialBrowserSessionId,
     onBrowserSessionIdChange,
     initialComputerSessionId,
@@ -965,6 +971,8 @@ export type SandboxWorkspaceProps = ClientOverride & {
   onActiveTabChange?: ((activeTab: string) => void) | undefined;
   initialFilePath?: string | null | undefined;
   onFilePathChange?: ((path: string | null) => void) | undefined;
+  /** Presentation-only filter for Files tree nodes and selected-file viewing. */
+  isFileNodeVisible?: FileNodeVisibilityPredicate | undefined;
   /**
    * Host request to open a workspace file (and optional line) in Files. A new
    * `requestId` re-opens even the same path.
@@ -1022,6 +1030,7 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     onActiveTabChange,
     initialFilePath,
     onFilePathChange,
+    isFileNodeVisible,
     openFileRequest,
     initialBrowserSessionId,
     onBrowserSessionIdChange,
@@ -1117,6 +1126,7 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     ...(browserExtensionSetupUrl ? { browserExtensionSetupUrl } : {}),
     initialFilePath,
     onFilePathChange,
+    isFileNodeVisible,
     initialBrowserSessionId,
     onBrowserSessionIdChange,
     initialComputerSessionId,

package/src/embedded-session-client.ts

@@ -0,0 +1,104 @@
+import type { ComposerDraft } from "@opengeni/sdk";
+import type { EmbeddedSessionClientLike } from "./client";
+
+export type ComposerDraftMapContext = {
+  operation: "read" | "save" | "submit";
+  workspaceId: string;
+  sessionId: string;
+};
+
+export type CreateEmbeddedSessionClientOptions = {
+  /**
+   * Explicit host-owned method replacements. Methods inherited from `base`
+   * retain `base` as their receiver; overrides retain this object as theirs.
+   */
+  overrides?: Partial<EmbeddedSessionClientLike> | undefined;
+  /** Presentation/policy projection for every draft entering the React layer. */
+  mapComposerDraft?:
+    | ((draft: ComposerDraft, context: ComposerDraftMapContext) => ComposerDraft)
+    | undefined;
+};
+
+const requiredMethods = [
+  "getSession",
+  "listEvents",
+  "streamEvents",
+  "getComposerDraft",
+  "saveComposerDraft",
+  "submitComposerDraft",
+  "sendMessage",
+  "steerMessage",
+  "getQueue",
+  "moveQueueItem",
+  "editQueueItem",
+  "steerQueueItem",
+  "deleteQueueItem",
+  "pauseSession",
+  "resumeSession",
+  "sendApprovalDecision",
+] as const satisfies readonly (keyof EmbeddedSessionClientLike)[];
+
+/**
+ * Build the exact client required by `@opengeni/react/session` from a full SDK
+ * client or host proxy. The constructor binds every delegated method once,
+ * supports a host-owned atomic composer-submit override, and fails at creation
+ * time instead of waiting for a missing method to be exercised by a hook.
+ */
+export function createEmbeddedSessionClient(
+  base: EmbeddedSessionClientLike,
+  options: CreateEmbeddedSessionClientOptions = {},
+): EmbeddedSessionClientLike {
+  const overrides = options.overrides ?? {};
+  const client = {} as EmbeddedSessionClientLike;
+  for (const key of requiredMethods) {
+    const override = overrides[key];
+    const method = override ?? base[key];
+    if (typeof method !== "function") {
+      throw new TypeError(`Embedded session client method is required: ${key}`);
+    }
+    client[key] = method.bind(override === undefined ? base : overrides) as never;
+  }
+
+  const inferenceOverride = overrides.setWorkspaceInferenceState;
+  const inferenceBase = base.setWorkspaceInferenceState;
+  const inferenceMethod = inferenceOverride ?? inferenceBase;
+  if (typeof inferenceMethod === "function") {
+    client.setWorkspaceInferenceState = inferenceMethod.bind(
+      inferenceOverride === undefined ? base : overrides,
+    );
+  }
+
+  const mapDraft = options.mapComposerDraft;
+  if (!mapDraft) return client;
+
+  const getComposerDraft = client.getComposerDraft;
+  client.getComposerDraft = async (workspaceId, sessionId) =>
+    mapDraft(await getComposerDraft(workspaceId, sessionId), {
+      operation: "read",
+      workspaceId,
+      sessionId,
+    });
+
+  const saveComposerDraft = client.saveComposerDraft;
+  client.saveComposerDraft = async (workspaceId, sessionId, request) =>
+    mapDraft(await saveComposerDraft(workspaceId, sessionId, request), {
+      operation: "save",
+      workspaceId,
+      sessionId,
+    });
+
+  const submitComposerDraft = client.submitComposerDraft;
+  client.submitComposerDraft = async (workspaceId, sessionId, request) => {
+    const response = await submitComposerDraft(workspaceId, sessionId, request);
+    return {
+      ...response,
+      draft: mapDraft(response.draft, {
+        operation: "submit",
+        workspaceId,
+        sessionId,
+      }),
+    };
+  };
+
+  return client;
+}

package/src/file-node-visibility.ts

@@ -0,0 +1,66 @@
+import type { FileTreeNode } from "./hooks/use-sandbox-files";
+
+export type FileNodeVisibilityContext = {
+  depth: number;
+  parent: FileTreeNode | null;
+};
+
+/** Presentation-only predicate. It never changes filesystem authorization. */
+export type FileNodeVisibilityPredicate = (
+  node: FileTreeNode,
+  context: FileNodeVisibilityContext,
+) => boolean;
+
+export type FilePathVisibility = "visible" | "hidden" | "unknown";
+
+function pathIsInsideDirectory(path: string, directory: string): boolean {
+  if (!path.startsWith(directory) || path === directory) return false;
+  if (directory.endsWith("/") || directory.endsWith("\\")) return true;
+  const boundary = path[directory.length];
+  return boundary === "/" || boundary === "\\";
+}
+
+/**
+ * Filter an authoritative tree without promoting children of a hidden parent.
+ * Undefined children stay undefined so lazy-loading semantics are preserved.
+ */
+export function visibleFileTree(
+  nodes: FileTreeNode[],
+  predicate?: FileNodeVisibilityPredicate,
+  parent: FileTreeNode | null = null,
+  depth = 0,
+): FileTreeNode[] {
+  if (!predicate) return nodes;
+  const visible: FileTreeNode[] = [];
+  for (const node of nodes) {
+    if (!predicate(node, { depth, parent })) continue;
+    visible.push(
+      node.children === undefined
+        ? node
+        : {
+            ...node,
+            children: visibleFileTree(node.children, predicate, node, depth + 1),
+          },
+    );
+  }
+  return visible;
+}
+
+/** Resolve only what the currently loaded tree can prove. */
+export function filePathVisibility(
+  nodes: FileTreeNode[],
+  path: string,
+  predicate?: FileNodeVisibilityPredicate,
+  parent: FileTreeNode | null = null,
+  depth = 0,
+): FilePathVisibility {
+  if (!predicate) return "visible";
+  for (const node of nodes) {
+    if (node.path !== path && !pathIsInsideDirectory(path, node.path)) continue;
+    if (!predicate(node, { depth, parent })) return "hidden";
+    if (node.path === path) return "visible";
+    if (node.kind !== "dir" || node.children === undefined) return "unknown";
+    return filePathVisibility(node.children, path, predicate, node, depth + 1);
+  }
+  return "unknown";
+}

package/src/hooks/use-composer.ts

@@ -115,7 +115,6 @@ type StoredOptimisticSendOperation = Omit<OptimisticSendOperation, "input" | "ca
 
 const PENDING_COMPOSER_STORAGE_PREFIX = "opengeni.pending-composer.v1:";
 const OPTIMISTIC_SEND_STORAGE_PREFIX = "opengeni.optimistic-sends.v1:";
-
 // A remount must not manufacture a new operation while the previous mutation
 // is still outcome-unknown. Keep only non-credential request fields here; the
 // mounted hook retains the exact input, including any credential updates. The
@@ -697,6 +696,12 @@ export function useComposer(
   const localEditRevision = useRef(initialShadow ? 1 : 0);
   const targetGeneration = useRef(0);
   const draftReadGeneration = useRef(0);
+  const draftReadInFlightRef = useRef<string | null>(null);
+  const draftReadRetryRef = useRef<{
+    targetKey: string;
+    failures: number;
+    timer: ReturnType<typeof setTimeout> | null;
+  }>({ targetKey, failures: 0, timer: null });
   const lastSavedSignature = useRef<string | null>(null);
   const saveChain = useRef<Promise<void>>(Promise.resolve());
   const onSent = options.onSent;
@@ -725,6 +730,10 @@ export function useComposer(
   const targetKeyRef = useRef(targetKey);
   useLayoutEffect(() => {
     if (targetKeyRef.current === targetKey) return;
+    if (draftReadRetryRef.current.timer !== null) {
+      clearTimeout(draftReadRetryRef.current.timer);
+    }
+    draftReadRetryRef.current = { targetKey, failures: 0, timer: null };
     targetKeyRef.current = targetKey;
     targetGeneration.current += 1;
     draftReadGeneration.current += 1;
@@ -777,6 +786,14 @@ export function useComposer(
     setDraftConflict(null);
     setRestoredResources(shadow?.resources ?? []);
   }, [durableDrafts, options.initialPolicy, pendingOperationKey, sessionId, targetKey]);
+  useEffect(
+    () => () => {
+      if (draftReadRetryRef.current.timer !== null) {
+        clearTimeout(draftReadRetryRef.current.timer);
+      }
+    },
+    [],
+  );
 
   const setOptimisticDraftShadow = useCallback(
     (shadow: ComposerDraftShadow): void => {
@@ -886,6 +903,30 @@ export function useComposer(
         setDraftLoading(false);
         return;
       }
+      let retry = draftReadRetryRef.current;
+      if (retry.targetKey !== targetKey) {
+        if (retry.timer !== null) clearTimeout(retry.timer);
+        retry = { targetKey, failures: 0, timer: null };
+        draftReadRetryRef.current = retry;
+      }
+      const scheduleRetry = (): void => {
+        if (retry.timer !== null) return;
+        retry.timer = setTimeout(
+          () => {
+            if (draftReadRetryRef.current !== retry || targetKeyRef.current !== targetKey) return;
+            retry.timer = null;
+            void loadDraft(false);
+          },
+          Math.min(25_000, 1_000 * 2 ** (retry.failures - 1)) * (0.8 + Math.random() * 0.4),
+        );
+      };
+      if (!replaceLocal && retry.timer !== null) return;
+      if (draftReadInFlightRef.current === targetKey) return;
+      if (retry.timer !== null) {
+        clearTimeout(retry.timer);
+        retry.timer = null;
+      }
+      draftReadInFlightRef.current = targetKey;
       const generation = targetGeneration.current;
       const readTicket = ++draftReadGeneration.current;
       const localAtStart = localEditRevision.current;
@@ -925,8 +966,15 @@ export function useComposer(
         ) {
           return;
         }
+        if (retry.timer !== null) clearTimeout(retry.timer);
+        retry.failures = 0;
+        retry.timer = null;
         const currentRevision = draftRef.current?.revision ?? -1;
-        if (fetched.revision >= currentRevision) {
+        // Reconnect and client-generation effects can legitimately ask for the
+        // draft again. A same-revision response is not new authority: publishing
+        // its freshly decoded object back into React creates a response -> render
+        // -> read feedback loop. Hard reload remains the explicit exception.
+        if (replaceLocal || fetched.revision > currentRevision) {
           draftRef.current = fetched;
           setDraft(fetched);
           setDraftConflict(null);
@@ -978,6 +1026,17 @@ export function useComposer(
           readTicket === draftReadGeneration.current
         ) {
           setError(asError(cause));
+          if (
+            cause instanceof TypeError ||
+            (cause && typeof cause === "object" && "retryable" in cause && cause.retryable === true)
+          ) {
+            retry.failures += 1;
+            scheduleRetry();
+          } else {
+            if (retry.timer !== null) clearTimeout(retry.timer);
+            retry.failures = 0;
+            retry.timer = null;
+          }
         }
       } finally {
         if (
@@ -987,6 +1046,9 @@ export function useComposer(
         ) {
           setDraftLoading(false);
         }
+        if (draftReadInFlightRef.current === targetKey) {
+          draftReadInFlightRef.current = null;
+        }
       }
     },
     [client, durableDrafts, sessionId, targetKey, workspaceId],

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

@@ -55,7 +55,14 @@ export type UseFileAttachmentsResult = {
    * source file). No-op for an id that isn't a known failed upload.
    */
   retry: (id: string) => void;
-  /** Remove one attachment; revokes its object-URL. */
+  /**
+   * Keep an attachment's object-URL alive for a consumer that outlives its
+   * queue entry (for example, an open route-level lightbox). The returned
+   * release is idempotent; pending revocation finishes after the last holder
+   * releases. Returns `undefined` when the attachment has no local preview.
+   */
+  retainPreview: (id: string) => (() => void) | undefined;
+  /** Remove one attachment; revokes its object-URL after retained users finish. */
   remove: (id: string) => void;
   /**
    * Remove only finalized files whose durable ids were accepted by a send.
@@ -63,7 +70,7 @@ export type UseFileAttachmentsResult = {
    * next message.
    */
   removeReadyFiles: (fileIds: Iterable<string>) => void;
-  /** Remove all attachments and revoke every object-URL. */
+  /** Remove all attachments and revoke every unretained object-URL. */
   clear: () => void;
 };
 
@@ -91,17 +98,41 @@ export function useFileAttachments(
   // state update when its component unmounts in the same batch that minted the
   // preview. The registry remains available to cleanup even before a render.
   const previewUrls = useRef<Map<string, string>>(new Map());
+  const previewRetainers = useRef<Map<string, number>>(new Map());
+  const pendingPreviewRevocations = useRef<Set<string>>(new Set());
   const revokePreview = useCallback((id: string) => {
     const previewUrl = previewUrls.current.get(id);
     if (!previewUrl) return;
+    if ((previewRetainers.current.get(id) ?? 0) > 0) {
+      pendingPreviewRevocations.current.add(id);
+      return;
+    }
     previewUrls.current.delete(id);
+    pendingPreviewRevocations.current.delete(id);
     URL.revokeObjectURL(previewUrl);
   }, []);
   const revokeAllPreviews = useCallback(() => {
-    const urls = [...previewUrls.current.values()];
-    previewUrls.current.clear();
-    for (const previewUrl of urls) URL.revokeObjectURL(previewUrl);
-  }, []);
+    for (const id of previewUrls.current.keys()) revokePreview(id);
+  }, [revokePreview]);
+  const retainPreview = useCallback(
+    (id: string): (() => void) | undefined => {
+      if (!previewUrls.current.has(id)) return undefined;
+      previewRetainers.current.set(id, (previewRetainers.current.get(id) ?? 0) + 1);
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        const remaining = (previewRetainers.current.get(id) ?? 1) - 1;
+        if (remaining > 0) {
+          previewRetainers.current.set(id, remaining);
+          return;
+        }
+        previewRetainers.current.delete(id);
+        if (pendingPreviewRevocations.current.has(id)) revokePreview(id);
+      };
+    },
+    [revokePreview],
+  );
   // Ready-file reconciliation uses functional state updaters, which React may
   // evaluate during a concurrent render that later suspends or is abandoned.
   // Diff only committed attachment sets here so URL revocation cannot run from
@@ -338,6 +369,7 @@ export function useFileAttachments(
     addFromPaste,
     restoreReadyFiles,
     retry,
+    retainPreview,
     remove,
     removeReadyFiles,
     clear,

package/src/hooks/use-human-input.ts

@@ -8,6 +8,7 @@ import {
   useEmbeddedHumanInputSession,
   type EmbeddedHumanInputClientOverride,
 } from "../session-context";
+import { isActionableHumanInputRequest } from "../human-input";
 import {
   useDebouncedCallback,
   useMutationRunner,
@@ -70,8 +71,11 @@ export function useHumanInputRequests(
     enabled,
     pollIntervalMs: options.pollIntervalMs,
   });
+  const loadedRequests = state.data;
+  const refreshRequests = state.refresh;
   const mutation = useMutationRunner(`${workspaceId}\u0000${sessionId ?? ""}`);
   const [respondingRequestId, setRespondingRequestId] = useState<string | null>(null);
+  const [deadlineVersion, setDeadlineVersion] = useState(0);
   const respondingRequestRef = useRef<string | null>(null);
 
   useEffect(() => {
@@ -89,6 +93,25 @@ export function useHumanInputRequests(
     ...(options.events !== undefined ? { events: options.events } : {}),
   });
 
+  useEffect(() => {
+    const now = Date.now();
+    const nextDeadline = (loadedRequests ?? []).reduce<number | null>((next, request) => {
+      if (request.status !== "pending" || !request.expiresAt) return next;
+      const deadline = Date.parse(request.expiresAt);
+      if (!Number.isFinite(deadline) || deadline <= now) return next;
+      return next === null ? deadline : Math.min(next, deadline);
+    }, null);
+    if (nextDeadline === null) return;
+    const timer = globalThis.setTimeout(
+      () => {
+        setDeadlineVersion((current) => current + 1);
+        void refreshRequests();
+      },
+      Math.min(2_147_483_647, Math.max(0, nextDeadline - now + 1)),
+    );
+    return () => globalThis.clearTimeout(timer);
+  }, [loadedRequests, refreshRequests]);
+
   const respond = useCallback(
     async (
       requestId: string,
@@ -115,11 +138,15 @@ export function useHumanInputRequests(
     [client, mutation, sessionId, state, workspaceId],
   );
 
+  const now = Date.now();
+  void deadlineVersion;
   return {
-    requests: [...(state.data ?? [])].sort(
-      (left, right) =>
-        left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id),
-    ),
+    requests: [...(state.data ?? [])]
+      .filter((request) => isActionableHumanInputRequest(request, now))
+      .sort(
+        (left, right) =>
+          left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id),
+      ),
     loading: state.loading,
     error: state.error,
     refresh: state.refresh,

package/src/human-input.ts

@@ -1,4 +1,4 @@
-import type { HumanInputQuestion, SessionEvent } from "@opengeni/sdk";
+import type { HumanInputQuestion, SessionEvent, SessionHumanInputRequest } from "@opengeni/sdk";
 
 /** Minimal actionable request shape available from the durable event log. */
 export type PendingHumanInputRequest = {
@@ -9,6 +9,17 @@ export type PendingHumanInputRequest = {
   expiresAt: string | null;
 };
 
+/** A pending row stops being actionable at its durable deadline, even before refresh. */
+export function isActionableHumanInputRequest(
+  request: Pick<SessionHumanInputRequest, "status" | "expiresAt">,
+  nowMs = Date.now(),
+): boolean {
+  if (request.status !== "pending") return false;
+  if (!request.expiresAt) return true;
+  const deadline = Date.parse(request.expiresAt);
+  return Number.isFinite(deadline) && deadline > nowMs;
+}
+
 /** Parse one generic `session.humanInput.requested` event defensively. */
 export function humanInputRequestFromEvent(
   event: Pick<SessionEvent, "type" | "payload" | "turnId">,

package/src/index.ts

@@ -27,7 +27,18 @@ export type { OpenGeniProviderProps } from "./provider";
 export { useOpenGeni, useOpenGeniClient } from "./session-context";
 export { useVideoArtifactPlaybackLoader } from "./hooks/use-video-artifact-playback";
 export type { ClientOverride, OpenGeniContextValue } from "./session-context";
+export { createEmbeddedSessionClient } from "./embedded-session-client";
+export type {
+  ComposerDraftMapContext,
+  CreateEmbeddedSessionClientOptions,
+} from "./embedded-session-client";
 export { usePageLiveActivity } from "./hooks/internal";
+export { filePathVisibility, visibleFileTree } from "./file-node-visibility";
+export type {
+  FileNodeVisibilityContext,
+  FileNodeVisibilityPredicate,
+  FilePathVisibility,
+} from "./file-node-visibility";
 
 // Hooks
 export { useSession, isTitleEvent } from "./hooks/use-session";
@@ -397,6 +408,7 @@ export type {
   TurnSummaryFacetResult,
   TurnSummaryOptions,
   TurnSummaryProps,
+  LightboxControlLabels,
 } from "./timeline";
 
 // Pure provider-shape parsers (exec banner, V4A diff, tool arguments, …)

package/src/session.ts

@@ -22,6 +22,11 @@ export type {
   EmbeddedSessionReadClientOverride as SessionReadClientOverride,
   EmbeddedSessionClientOverride as ClientOverride,
 } from "./session-context";
+export { createEmbeddedSessionClient } from "./embedded-session-client";
+export type {
+  ComposerDraftMapContext,
+  CreateEmbeddedSessionClientOptions,
+} from "./embedded-session-client";
 
 export { useSession, isTitleEvent } from "./hooks/use-session";
 export type { UseSessionOptions, UseSessionResult } from "./hooks/use-session";

package/src/timeline/index.ts

@@ -92,6 +92,7 @@ export type { ActivityDisclosureProps, DisclosureChip } from "./shared";
 
 // screenshot lightbox
 export { LightboxProvider, useLightbox, useLightboxOptional } from "./screenshot-lightbox";
+export type { LightboxControlLabels } from "./screenshot-lightbox";
 
 // disclosure defaults (opt-in initial-open seed; for screenshot/test instrumentation)
 export { DisclosureDefaultsProvider, useForcedDefaultOpen } from "./disclosure-context";