@opengeni/react 0.45.0 → 0.48.0

package/src/components/tooltip.tsx

@@ -8,19 +8,17 @@
  * tips and look like a blank white bubble.
  */
 import { Tooltip as TooltipPrimitive } from "radix-ui";
-import {
-  createContext,
-  useContext,
-  useRef,
-  type ComponentProps,
-  type CSSProperties,
-  type RefObject,
-} from "react";
+import { createContext, useContext, type ComponentProps, type CSSProperties } from "react";
 
 import { cn } from "../lib/cn";
-import { usePortalTokenStyle } from "../lib/use-portal-token-style";
+import { usePortalTokenSource, usePortalTokenStyle } from "../lib/use-portal-token-style";
 
-const TooltipSourceContext = createContext<RefObject<HTMLElement | null> | null>(null);
+type TooltipSourceContextValue = {
+  source: HTMLElement | null;
+  ref: (node: HTMLElement | null) => void;
+};
+
+const TooltipSourceContext = createContext<TooltipSourceContextValue | null>(null);
 
 function TooltipProvider({
   delayDuration = 300,
@@ -30,9 +28,9 @@ function TooltipProvider({
 }
 
 function Tooltip({ children, ...props }: ComponentProps<typeof TooltipPrimitive.Root>) {
-  const sourceRef = useRef<HTMLElement | null>(null);
+  const source = usePortalTokenSource<HTMLElement>();
   return (
-    <TooltipSourceContext.Provider value={sourceRef}>
+    <TooltipSourceContext.Provider value={source}>
       <TooltipPrimitive.Root data-slot="tooltip" {...props}>
         {children}
       </TooltipPrimitive.Root>
@@ -50,7 +48,7 @@ function TooltipTrigger({
       data-slot="tooltip-trigger"
       asChild={asChild}
       ref={(node) => {
-        if (sourceRef) sourceRef.current = node;
+        sourceRef?.ref(node);
       }}
       {...props}
     />
@@ -69,9 +67,8 @@ function TooltipContent({
   style,
   ...props
 }: ComponentProps<typeof TooltipPrimitive.Content>) {
-  const sourceRef = useContext(TooltipSourceContext);
-  const fallbackRef = useRef<HTMLElement | null>(null);
-  const portalStyle = usePortalTokenStyle(sourceRef ?? fallbackRef);
+  const source = useContext(TooltipSourceContext);
+  const portalStyle = usePortalTokenStyle(source?.source ?? null);
 
   return (
     <TooltipPrimitive.Portal>

package/src/components/user-message-body.tsx

@@ -330,7 +330,7 @@ export function UserMessageBody({ messageId, text, children, className }: UserMe
           aria-controls={contentId}
           aria-expanded={expanded}
           data-og-user-message-disclosure=""
-          className="mt-1.5 inline-flex min-h-7 items-center rounded-og-sm px-1.5 text-og-xs font-medium text-og-fg-muted outline-none transition-colors hover:bg-og-surface-3/60 hover:text-og-fg focus-visible:ring-2 focus-visible:ring-og-accent/45 pointer-coarse:min-h-11"
+          className="mt-1.5 inline-flex min-h-7 items-center rounded-og-sm px-1.5 text-og-xs font-medium text-og-fg-muted outline-hidden transition-colors hover:bg-og-surface-3/60 hover:text-og-fg focus-visible:ring-2 focus-visible:ring-og-accent/45 pointer-coarse:min-h-11"
           onClick={(event) => toggle(event.currentTarget)}
         >
           {expanded ? "Show less" : "Show more"}

package/src/components/workbench-changes.tsx

@@ -321,7 +321,7 @@ export function WorkbenchChanges({
               }}
               title={activeFile?.path}
               data-compact-file-picker
-              className="h-11 w-full rounded-og-md border border-og-border bg-og-bg px-3 font-og-mono text-og-sm text-og-fg outline-none transition-colors focus:border-og-accent focus:ring-2 focus:ring-og-accent-soft"
+              className="h-11 w-full rounded-og-md border border-og-border bg-og-bg px-3 font-og-mono text-og-sm text-og-fg outline-hidden transition-colors focus:border-og-accent focus:ring-2 focus:ring-og-accent-soft"
             >
               {orderedFiles.map((file, index) => (
                 <option key={file.path} value={index}>
@@ -480,7 +480,7 @@ function RailFileRow({
       title={file.path}
       data-rail-file
       className={cn(
-        "relative flex min-h-7 w-full items-center gap-1.5 truncate px-2 py-0.5 text-left text-og-sm transition-colors hover:bg-og-surface-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-og-accent pointer-coarse:min-h-11",
+        "relative flex min-h-7 w-full items-center gap-1.5 truncate px-2 py-0.5 text-left text-og-sm transition-colors hover:bg-og-surface-2 focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-og-accent pointer-coarse:min-h-11",
         grouped && "pl-3",
         active &&
           "bg-og-accent-soft text-og-fg before:absolute before:inset-y-1 before:left-0 before:w-0.5 before:rounded-r-full before:bg-og-accent",
@@ -597,7 +597,7 @@ function GuardBody({
         <button
           type="button"
           onClick={() => onOpenFile(file.path)}
-          className="inline-flex min-h-8 shrink-0 items-center gap-1.5 rounded-og-sm border border-og-border px-2 py-1 text-og-xs font-medium text-og-fg-muted transition-colors hover:border-og-border-strong hover:bg-og-surface-2 hover:text-og-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:min-h-11"
+          className="inline-flex min-h-8 shrink-0 items-center gap-1.5 rounded-og-sm border border-og-border px-2 py-1 text-og-xs font-medium text-og-fg-muted transition-colors hover:border-og-border-strong hover:bg-og-surface-2 hover:text-og-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:min-h-11"
         >
           Open in Files
           <ArrowUpRightIcon className="size-3.5" aria-hidden />
@@ -622,7 +622,7 @@ function LayoutToggle({
           type="button"
           onClick={() => onChange(value)}
           className={cn(
-            "min-h-7 rounded-og-xs px-1.5 py-0.5 text-og-xs capitalize focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent max-[1023px]:min-w-11 pointer-coarse:min-h-11 pointer-coarse:min-w-11",
+            "min-h-7 rounded-og-xs px-1.5 py-0.5 text-og-xs capitalize focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent max-[1023px]:min-w-11 pointer-coarse:min-h-11 pointer-coarse:min-w-11",
             layout === value
               ? "bg-og-accent-soft text-og-fg"
               : "text-og-fg-subtle hover:text-og-fg",

package/src/components/workspace-dock.tsx

@@ -44,6 +44,8 @@ export type WorkspaceDockProps = {
   /** Controlled collapsed state for hosts that expose their own dock toggle. */
   collapsed?: boolean | undefined;
   onCollapsedChange?: ((collapsed: boolean) => void) | undefined;
+  /** Keep the built-in collapse control when the host controls collapsed state. */
+  showCollapseControl?: boolean | undefined;
   /** A status accessory pinned to the right of the tab strip, left of the
    *  maximize/collapse controls (e.g. the machine-state chip). Renders in both
    *  the docked header and the full-screen overlay header. */
@@ -129,6 +131,7 @@ export function WorkspaceDock({
   onActiveTabChange,
   collapsed: collapsedProp,
   onCollapsedChange,
+  showCollapseControl = false,
   headerAccessory,
   mobileLeadingControl,
   autoSaveId = "og.session.dock",
@@ -343,6 +346,11 @@ export function WorkspaceDock({
           className="fixed inset-0 z-40 flex flex-col bg-og-bg"
           hidden={collapsed}
           style={{
+            // Author utility classes can override the user-agent `[hidden]`
+            // rule (for example this surface's `flex` class). Keep an inline
+            // display guard so a collapsed mobile workspace is actually gone
+            // visually as well as from the accessibility tree.
+            display: collapsed ? "none" : undefined,
             paddingTop: "env(safe-area-inset-top)",
             paddingBottom: "env(safe-area-inset-bottom)",
           }}
@@ -367,7 +375,7 @@ export function WorkspaceDock({
             onClick={expand}
             title="Open workspace"
             aria-label="Open workspace"
-            className="absolute right-3 top-3 z-30 inline-flex size-11 items-center justify-center rounded-og-md border border-og-border bg-og-surface-1 text-og-fg-muted shadow-lg transition-colors hover:border-og-border-strong hover:text-og-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent"
+            className="absolute right-3 top-3 z-30 inline-flex size-11 items-center justify-center rounded-og-md border border-og-border bg-og-surface-1 text-og-fg-muted shadow-lg transition-colors hover:border-og-border-strong hover:text-og-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent"
             style={{ marginTop: "env(safe-area-inset-top)" }}
           >
             <ChevronsLeftRightIcon className="size-4" aria-hidden />
@@ -396,7 +404,7 @@ export function WorkspaceDock({
               <Maximize2Icon className="size-3.5" />
             )}
           </ChromeButton>
-          {hostControlled ? null : (
+          {hostControlled && !showCollapseControl ? null : (
             <ChromeButton onClick={collapse} title="Collapse" label="Collapse dock">
               <PanelRightCloseIcon className="size-3.5" />
             </ChromeButton>
@@ -426,7 +434,7 @@ export function WorkspaceDock({
         </Panel>
 
         {!collapsed && (
-          <Separator className="group relative z-10 w-1.5 shrink-0 outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-og-accent max-[1023px]:-mx-[19px] max-[1023px]:w-11 pointer-coarse:-mx-[19px] pointer-coarse:w-11">
+          <Separator className="group relative z-10 w-1.5 shrink-0 outline-hidden focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-og-accent max-[1023px]:-mx-[19px] max-[1023px]:w-11 pointer-coarse:-mx-[19px] pointer-coarse:w-11">
             <span className="absolute inset-y-0 left-1/2 w-px -translate-x-1/2 bg-og-border transition-colors group-hover:bg-og-accent group-focus-visible:bg-og-accent group-data-[separator-state=dragging]:bg-og-accent" />
           </Separator>
         )}
@@ -503,7 +511,7 @@ function ChromeButton({
       onClick={onClick}
       title={title}
       aria-label={label}
-      className="inline-flex size-7 items-center justify-center rounded-og-sm p-1 transition-colors hover:bg-og-surface-2 hover:text-og-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent max-[1023px]:size-11 pointer-coarse:size-11"
+      className="inline-flex size-7 items-center justify-center rounded-og-sm p-1 transition-colors hover:bg-og-surface-2 hover:text-og-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent max-[1023px]:size-11 pointer-coarse:size-11"
     >
       {children}
     </button>
@@ -664,7 +672,7 @@ function DockChrome({
               onClick={() => onTab(tab.id)}
               onKeyDown={(event) => onTabKeyDown(event, index)}
               className={cn(
-                "flex min-h-7 shrink-0 items-center justify-center gap-1 rounded-og-sm px-2 py-1 text-og-xs font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent max-[1023px]:min-h-11 max-[1023px]:min-w-11 pointer-coarse:min-h-11 pointer-coarse:min-w-11",
+                "flex min-h-7 shrink-0 items-center justify-center gap-1 rounded-og-sm px-2 py-1 text-og-xs font-medium transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent max-[1023px]:min-h-11 max-[1023px]:min-w-11 pointer-coarse:min-h-11 pointer-coarse:min-w-11",
                 tab.id === current
                   ? "bg-og-accent-soft text-og-fg"
                   : "text-og-fg-subtle hover:text-og-fg",

package/src/composer.ts

@@ -64,6 +64,7 @@ export type {
   ComposerSubmitBlocker,
   ComposerSubmitMode,
   ComposerSurfaceProps,
+  ResponsiveBasis,
   UseChatComposerControllerOptions,
 } from "./components/composer";
 export { ComposerTranscriptionControl } from "./components/composer-transcription-control";
@@ -101,7 +102,9 @@ export type {
   VoiceRecordingChunk,
   VoiceRecordingChunkUploadState,
   VoiceRecordingFinalizationState,
+  VoiceRecordingHandoffMode,
   VoiceRecordingManifest,
+  VoiceRecordingRecoveryMode,
   VoiceRecordingStore,
   VoiceRecordingTranscriptionState,
   VoiceRecordingUploadState,

package/src/hooks/internal.ts

@@ -2,6 +2,51 @@ import type { SessionEvent } from "@opengeni/sdk";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import type { EmbeddedSessionEventClientLike } from "../client";
 
+const HIDDEN_STREAM_GRACE_MS = 2_000;
+
+/**
+ * Keep live browser work active while the page is visible, then suspend it
+ * after a short hidden-tab grace period. Returning to the page re-enables the
+ * caller, which must reconcile durable state before resuming live delivery.
+ */
+export function usePageLiveActivity(hiddenGraceMs = HIDDEN_STREAM_GRACE_MS): boolean {
+  // Keep the server and initial browser render identical; the effect applies
+  // visibility after mount and preserves the intentional hidden-tab grace.
+  const [active, setActive] = useState(true);
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    let hiddenTimer: ReturnType<typeof setTimeout> | null = null;
+    const cancelHiddenTimer = () => {
+      if (hiddenTimer !== null) {
+        clearTimeout(hiddenTimer);
+        hiddenTimer = null;
+      }
+    };
+    const sync = () => {
+      cancelHiddenTimer();
+      if (document.visibilityState !== "hidden") {
+        setActive(true);
+        return;
+      }
+      hiddenTimer = setTimeout(() => {
+        hiddenTimer = null;
+        if (document.visibilityState === "hidden") setActive(false);
+      }, hiddenGraceMs);
+    };
+    document.addEventListener("visibilitychange", sync);
+    window.addEventListener("pageshow", sync);
+    sync();
+    return () => {
+      cancelHiddenTimer();
+      document.removeEventListener("visibilitychange", sync);
+      window.removeEventListener("pageshow", sync);
+    };
+  }, [hiddenGraceMs]);
+
+  return active;
+}
+
 export type AsyncListState<T> = {
   data: T | null;
   loading: boolean;
@@ -19,6 +64,7 @@ export function usePolledValue<T>(
 ): AsyncListState<T> {
   const enabled = options.enabled ?? true;
   const pollIntervalMs = options.pollIntervalMs;
+  const pageLive = usePageLiveActivity();
   const [data, setData] = useState<T | null>(null);
   const [loading, setLoading] = useState(enabled);
   const [error, setError] = useState<Error | null>(null);
@@ -28,6 +74,8 @@ export function usePolledValue<T>(
     activeLoadRef.current = load;
   }, [load]);
   const requestAbortRef = useRef<AbortController | null>(null);
+  const inFlightRef = useRef<{ load: typeof load; promise: Promise<void> } | null>(null);
+  const trailingRefreshRef = useRef<{ load: typeof load; promise: Promise<void> } | null>(null);
   const [stateIdentity, setStateIdentity] = useState<{ load: typeof load }>(() => ({ load }));
 
   // A new loader identity means a new query (different session/workspace/...):
@@ -40,68 +88,107 @@ export function usePolledValue<T>(
     }
   }, [load, stateIdentity.load]);
 
-  const run = useCallback(async () => {
+  const run = useCallback((): Promise<void> => {
     // A callback retained by a completed mutation from the previous query must
     // not supersede or settle the current query's request.
-    if (activeLoadRef.current !== load) return;
+    if (activeLoadRef.current !== load) return Promise.resolve();
+    const existing = inFlightRef.current;
+    if (existing?.load === load) return existing.promise;
     const ticket = ++generation.current;
-    requestAbortRef.current?.abort();
     const requestAbort = new AbortController();
     requestAbortRef.current = requestAbort;
-    try {
-      const result = await load(requestAbort.signal);
-      if (
-        ticket === generation.current &&
-        activeLoadRef.current === load &&
-        !requestAbort.signal.aborted
-      ) {
-        setData(result);
-        setError(null);
-        setLoading(false);
-      }
-    } catch (cause) {
-      if (
-        ticket === generation.current &&
-        activeLoadRef.current === load &&
-        !requestAbort.signal.aborted
-      ) {
-        setError(cause instanceof Error ? cause : new Error(String(cause)));
-        setLoading(false);
-      }
-    } finally {
-      if (requestAbortRef.current === requestAbort) {
-        requestAbortRef.current = null;
+    let promise!: Promise<void>;
+    promise = (async () => {
+      try {
+        const result = await load(requestAbort.signal);
+        if (
+          ticket === generation.current &&
+          activeLoadRef.current === load &&
+          !requestAbort.signal.aborted
+        ) {
+          setData(result);
+          setError(null);
+          setLoading(false);
+        }
+      } catch (cause) {
+        if (
+          ticket === generation.current &&
+          activeLoadRef.current === load &&
+          !requestAbort.signal.aborted
+        ) {
+          setError(cause instanceof Error ? cause : new Error(String(cause)));
+          setLoading(false);
+        }
+      } finally {
+        if (requestAbortRef.current === requestAbort) requestAbortRef.current = null;
+        if (inFlightRef.current?.promise === promise) inFlightRef.current = null;
       }
-    }
+    })();
+    inFlightRef.current = { load, promise };
+    return promise;
   }, [load]);
 
+  const refresh = useCallback((): Promise<void> => {
+    const existing = inFlightRef.current;
+    if (existing?.load !== load) return run();
+    const trailing = trailingRefreshRef.current;
+    if (trailing?.load === load) return trailing.promise;
+    let promise!: Promise<void>;
+    promise = existing.promise.then(async () => {
+      if (trailingRefreshRef.current?.promise === promise) {
+        trailingRefreshRef.current = null;
+      }
+      if (activeLoadRef.current === load) await run();
+    });
+    trailingRefreshRef.current = { load, promise };
+    return promise;
+  }, [load, run]);
+
   useEffect(() => {
-    if (!enabled) {
+    if (!enabled || !pageLive) {
       setLoading(false);
+      generation.current += 1;
+      requestAbortRef.current?.abort();
+      inFlightRef.current = null;
+      trailingRefreshRef.current = null;
       return;
     }
     setLoading(true);
-    void run();
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const schedule = () => {
+      if (cancelled || pollIntervalMs === undefined || pollIntervalMs <= 0) return;
+      timer = setTimeout(() => {
+        timer = null;
+        void run().finally(schedule);
+      }, pollIntervalMs);
+    };
+    void run().finally(schedule);
     if (pollIntervalMs === undefined || pollIntervalMs <= 0) {
       return () => {
+        cancelled = true;
         generation.current += 1;
         requestAbortRef.current?.abort();
+        inFlightRef.current = null;
+        trailingRefreshRef.current = null;
       };
     }
-    const timer = setInterval(() => void run(), pollIntervalMs);
     return () => {
-      clearInterval(timer);
+      cancelled = true;
+      if (timer !== null) clearTimeout(timer);
       generation.current += 1;
       requestAbortRef.current?.abort();
+      inFlightRef.current = null;
+      trailingRefreshRef.current = null;
     };
-  }, [run, enabled, pollIntervalMs]);
+  }, [run, enabled, pageLive, pollIntervalMs]);
 
   const identityMatches = stateIdentity.load === load;
   return {
     data: identityMatches ? data : null,
     loading: identityMatches ? loading : enabled,
     error: identityMatches ? error : null,
-    refresh: run,
+    refresh,
   };
 }
 
@@ -224,6 +311,8 @@ export function useSessionEventTrigger(
   reconcileBeforeLive?: (() => void | Promise<void>) | undefined,
 ): void {
   const enabled = options.enabled ?? true;
+  const pageLive = usePageLiveActivity();
+  const liveEnabled = enabled && pageLive;
   const events = options.events;
   const sharedFeed = events !== undefined;
   const matchRef = useRef(match);
@@ -240,7 +329,7 @@ export function useSessionEventTrigger(
 
   // Shared-log mode: scan only the unseen tail on every append.
   useEffect(() => {
-    if (!sharedFeed || !enabled || !sessionId) {
+    if (!sharedFeed || !liveEnabled || !sessionId) {
       return;
     }
     const feedKey = `${workspaceId}\u0000${sessionId}`;
@@ -285,11 +374,11 @@ export function useSessionEventTrigger(
         onEventRef.current(event);
       }
     }
-  }, [sharedFeed, enabled, events, workspaceId, sessionId]);
+  }, [sharedFeed, liveEnabled, events, workspaceId, sessionId]);
 
   // Self-stream mode: tail from the session's current lastSequence.
   useEffect(() => {
-    if (sharedFeed || !enabled || !sessionId) {
+    if (sharedFeed || !liveEnabled || !sessionId) {
       return;
     }
     const controller = new AbortController();
@@ -302,7 +391,12 @@ export function useSessionEventTrigger(
         const stream = client.streamEvents(workspaceId, sessionId, {
           after: session.lastSequence,
           signal: controller.signal,
-          beforeLive: async () => await reconcileBeforeLiveRef.current?.(),
+          onOpen: () => {
+            // Start reconciliation without delaying consumption of live SSE.
+            void Promise.resolve()
+              .then(() => reconcileBeforeLiveRef.current?.())
+              .catch(() => undefined);
+          },
         });
         for await (const event of stream) {
           if (matchRef.current(event)) {
@@ -317,7 +411,7 @@ export function useSessionEventTrigger(
     return () => {
       controller.abort();
     };
-  }, [sharedFeed, enabled, client, workspaceId, sessionId]);
+  }, [sharedFeed, liveEnabled, client, workspaceId, sessionId]);
 }
 
 /** Debounce rapid event bursts into one trailing call (default 150ms). */

package/src/hooks/use-codex-accounts.ts

@@ -15,7 +15,7 @@ import {
 
 /** Events that change which Codex account a session runs on (or just ran). */
 export function isCodexAccountEvent(event: Pick<SessionEvent, "type">): boolean {
-  return event.type === "codex.account.switched" || event.type === "turn.started";
+  return event.type === "codex.account.switched";
 }
 
 /**
@@ -104,7 +104,7 @@ const EMPTY_STATE: CodexAccountsState = {
  * The workspace's Codex accounts + the per-workspace active pointer + (when
  * session-scoped) the session pin and last-ran-on account. Composed like
  * `useMachines`: slow polling (the realtime work is done by the
- * `codex.account.switched` / `turn.started` event trigger) + a `pin` mutation.
+ * `codex.account.switched` event trigger) + a `pin` mutation.
  * Dual-consumer safe via the structural `CodexAccountsClientLike` surface.
  */
 export function useCodexAccounts(options: UseCodexAccountsOptions = {}): UseCodexAccountsResult {
@@ -141,8 +141,8 @@ export function useCodexAccounts(options: UseCodexAccountsOptions = {}): UseCode
   const { run: runUsageMutation, mutating: refreshingUsage } = useMutationRunner();
   const [pinningTarget, setPinningTarget] = useState<string | null>(null);
 
-  // Live flip: a manual switch (P1) or a failover (P3) emits codex.account.switched;
-  // turn.started covers the case where the worker recorded the actual account.
+  // Refresh only after the durable post-selection event. `turn.started` is
+  // emitted before account selection settles and races this authoritative read.
   useSessionEventTrigger(
     client,
     workspaceId,

package/src/hooks/use-environments.ts

@@ -2,6 +2,7 @@ import type {
   CreateVariableSetRequest,
   UpdateVariableSetRequest,
   VariableSet,
+  VariableSetSecret,
   VariableSetVariableMetadata,
 } from "@opengeni/sdk";
 import { useCallback, useMemo } from "react";
@@ -21,7 +22,12 @@ export type UseVariableSetsResult = {
   create: (request: CreateVariableSetRequest) => Promise<VariableSet | null>;
   update: (variableSetId: string, request: UpdateVariableSetRequest) => Promise<VariableSet | null>;
   remove: (variableSetId: string) => Promise<boolean>;
-  /** Set/rotate a variable. Values are write-only — reads expose metadata only. */
+  /**
+   * Read one exact value through the dedicated permissioned API. The hook never
+   * puts plaintext in its polled variable-set cache.
+   */
+  readVariable: (variableSetId: string, name: string) => Promise<VariableSetSecret | null>;
+  /** Set/rotate a variable. Generic reads expose metadata only. */
   setVariable: (
     variableSetId: string,
     name: string,
@@ -35,8 +41,9 @@ export type UseVariableSetsResult = {
 
 /**
  * Variable sets (named, encrypted variable sets attached to sessions
- * and scheduled tasks). Variable values are write-only end to end: this hook
- * never sees a value after it is sent.
+ * and scheduled tasks). Generic reads stay metadata-only. A dedicated,
+ * permissioned method can retrieve one value and returns it directly without
+ * adding plaintext to hook state or polling caches.
  */
 export function useVariableSets(options: UseVariableSetsOptions = {}): UseVariableSetsResult {
   const { client, workspaceId } = useOpenGeni(options);
@@ -89,6 +96,12 @@ export function useVariableSets(options: UseVariableSetsOptions = {}): UseVariab
     [client, workspaceId, run, refresh],
   );
 
+  const readVariable = useCallback(
+    async (variableSetId: string, name: string): Promise<VariableSetSecret | null> =>
+      await run(() => client.getVariableSetVariable(workspaceId, variableSetId, name)),
+    [client, workspaceId, run],
+  );
+
   const setVariable = useCallback(
     async (
       variableSetId: string,
@@ -128,6 +141,7 @@ export function useVariableSets(options: UseVariableSetsOptions = {}): UseVariab
     create,
     update,
     remove,
+    readVariable,
     setVariable,
     deleteVariable,
     mutating,
@@ -139,7 +153,9 @@ export function useVariableSets(options: UseVariableSetsOptions = {}): UseVariab
 /** @deprecated use UseVariableSetsOptions */
 export type UseEnvironmentsOptions = UseVariableSetsOptions;
 /** @deprecated use UseVariableSetsResult */
-export type UseEnvironmentsResult = UseVariableSetsResult & { environments: VariableSet[] };
+export type UseEnvironmentsResult = UseVariableSetsResult & {
+  environments: VariableSet[];
+};
 /** @deprecated use useVariableSets */
 export function useEnvironments(options: UseEnvironmentsOptions = {}): UseEnvironmentsResult {
   const legacyClient = useMemo(() => {
@@ -158,6 +174,9 @@ export function useEnvironments(options: UseEnvironmentsOptions = {}): UseEnviro
         options.client.deleteEnvironmentVariable ?? options.client.deleteVariableSetVariable,
     };
   }, [options.client]);
-  const result = useVariableSets({ ...options, ...(legacyClient ? { client: legacyClient } : {}) });
+  const result = useVariableSets({
+    ...options,
+    ...(legacyClient ? { client: legacyClient } : {}),
+  });
   return { ...result, environments: result.variableSets };
 }