@opengeni/react 0.46.1 → 0.52.1

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 };
 }

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

@@ -1,5 +1,5 @@
 import type { FileAsset, FileResourceRef } from "@opengeni/sdk";
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import {
   useEmbeddedFileAttachments,
   type EmbeddedFileAttachmentClientOverride,
@@ -87,12 +87,64 @@ export function useFileAttachments(
   // Keep the source File per attachment id so a failed upload can be retried
   // in place. Cleared on remove/clear so it never outlives its attachment.
   const sources = useRef<Map<string, File>>(new Map());
+  // Object URLs must be owned synchronously: React may discard an attachment
+  // 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 revokePreview = useCallback((id: string) => {
+    const previewUrl = previewUrls.current.get(id);
+    if (!previewUrl) return;
+    previewUrls.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);
+  }, []);
+  // 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
+  // render-phase code while the previously committed DOM still uses a preview.
+  const committedAttachmentIds = useRef<Set<string>>(new Set());
+  useEffect(() => {
+    const currentIds = new Set(attachments.map((attachment) => attachment.id));
+    for (const id of committedAttachmentIds.current) {
+      if (!currentIds.has(id)) revokePreview(id);
+    }
+    committedAttachmentIds.current = currentIds;
+  }, [attachments, revokePreview]);
+  // Upload promises are not cancellable at this layer. Fence their settlements
+  // when the hook changes client/workspace or unmounts so an old tenant/session
+  // cannot mutate the next attachment queue (or an already-unmounted component).
+  const scopeGeneration = useRef(0);
+  const previousScope = useRef({ client, workspaceId });
+
+  useEffect(() => {
+    const previous = previousScope.current;
+    if (previous.client === client && previous.workspaceId === workspaceId) return;
+    previousScope.current = { client, workspaceId };
+    scopeGeneration.current += 1;
+    sources.current.clear();
+    revokeAllPreviews();
+    setAttachments([]);
+  }, [client, revokeAllPreviews, workspaceId]);
+
+  useEffect(
+    () => () => {
+      scopeGeneration.current += 1;
+      sources.current.clear();
+      revokeAllPreviews();
+    },
+    [revokeAllPreviews],
+  );
 
   // Run (or re-run) the upload for one already-tracked attachment id. Sets it
   // back to `uploading`, then resolves to `ready` (with the asset) or `failed`
   // (with the error message).
   const startUpload = useCallback(
     (id: string, file: File) => {
+      const generation = scopeGeneration.current;
       void client
         .uploadFile(workspaceId, {
           filename: file.name || "file",
@@ -100,6 +152,7 @@ export function useFileAttachments(
           data: file,
         })
         .then((asset) => {
+          if (scopeGeneration.current !== generation) return;
           // Retry bytes are useful only until durable finalization succeeds.
           // Drop the source File immediately; restored/ready attachments must
           // never retain browser-local byte authority.
@@ -121,6 +174,7 @@ export function useFileAttachments(
           );
         })
         .catch((error: unknown) => {
+          if (scopeGeneration.current !== generation) return;
           setAttachments((current) =>
             current.map((attachment) =>
               attachment.id === id
@@ -143,6 +197,7 @@ export function useFileAttachments(
         const id = crypto.randomUUID();
         sources.current.set(id, file);
         const previewUrl = isImage(file) ? URL.createObjectURL(file) : undefined;
+        if (previewUrl) previewUrls.current.set(id, previewUrl);
         setAttachments((current) => [
           ...current,
           {
@@ -232,11 +287,6 @@ export function useFileAttachments(
                 // 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.
@@ -246,46 +296,34 @@ export function useFileAttachments(
     [workspaceId],
   );
 
-  const remove = useCallback((id: string) => {
-    sources.current.delete(id);
-    setAttachments((current) => {
-      const removed = current.find((attachment) => attachment.id === id);
-      if (removed?.previewUrl) {
-        URL.revokeObjectURL(removed.previewUrl);
-      }
-      return current.filter((attachment) => attachment.id !== id);
-    });
-  }, []);
+  const remove = useCallback(
+    (id: string) => {
+      sources.current.delete(id);
+      revokePreview(id);
+      setAttachments((current) => current.filter((attachment) => attachment.id !== id));
+    },
+    [revokePreview],
+  );
 
   const removeReadyFiles = useCallback((fileIds: Iterable<string>) => {
     const accepted = new Set(fileIds);
     if (accepted.size === 0) return;
     setAttachments((current) =>
       current.filter((attachment) => {
-        const removeAccepted =
+        return !(
           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;
+          accepted.has(attachment.file.id)
+        );
       }),
     );
   }, []);
 
   const clear = useCallback(() => {
     sources.current.clear();
-    setAttachments((current) => {
-      for (const attachment of current) {
-        if (attachment.previewUrl) {
-          URL.revokeObjectURL(attachment.previewUrl);
-        }
-      }
-      return [];
-    });
-  }, []);
+    revokeAllPreviews();
+    setAttachments([]);
+  }, [revokeAllPreviews]);
 
   return {
     attachments,

package/src/hooks/use-goal.ts

@@ -4,6 +4,7 @@ import { useEmbeddedGoal, type EmbeddedGoalClientOverride } from "../session-con
 import {
   useDebouncedCallback,
   useMutationRunner,
+  usePageLiveActivity,
   useSessionEventTrigger,
   type SessionEventFeedOptions,
 } from "./internal";
@@ -75,6 +76,7 @@ export function useGoal(
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const sharedEvents = options.events;
   const sharedFeed = sharedEvents !== undefined;
+  const pageLive = usePageLiveActivity();
   const [goal, setGoal] = useState<SessionGoal | null>(null);
   const [loading, setLoading] = useState(enabled);
   const [error, setError] = useState<Error | null>(null);
@@ -116,7 +118,7 @@ export function useGoal(
       setGoal(null);
       setError(null);
     }
-    if (!enabled) {
+    if (!enabled || !pageLive) {
       setLoading(false);
       return;
     }
@@ -127,19 +129,29 @@ export function useGoal(
       };
     }
     setLoading(true);
-    void load();
     const pollIntervalMs = options.pollIntervalMs;
     if (pollIntervalMs === undefined || pollIntervalMs <= 0) {
+      void load();
       return () => {
         generation.current += 1;
       };
     }
-    const timer = setInterval(() => void load(), pollIntervalMs);
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const schedule = () => {
+      if (cancelled) return;
+      timer = setTimeout(() => {
+        timer = null;
+        void load().finally(schedule);
+      }, pollIntervalMs);
+    };
+    void load().finally(schedule);
     return () => {
-      clearInterval(timer);
+      cancelled = true;
+      if (timer !== null) clearTimeout(timer);
       generation.current += 1;
     };
-  }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs, sharedFeed]);
+  }, [load, enabled, pageLive, workspaceId, sessionId, options.pollIntervalMs, sharedFeed]);
 
   const scheduleRefresh = useDebouncedCallback(() => void load());
   useSessionEventTrigger(client, workspaceId, sessionId, isGoalRefreshEvent, scheduleRefresh, {

package/src/hooks/use-machine-chip.ts

@@ -1,6 +1,7 @@
 import { useMemo } from "react";
 import type { MachineState } from "@opengeni/sdk";
 import type { SessionCapabilitiesState } from "./use-session-capabilities";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
 /** The one truthful machine indicator. Honest staleness beats
  *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
@@ -53,7 +54,7 @@ export function formatAsOf(capturedAt: string, now: number): string {
  * it; the whole point is a deterministic, testable projection).
  *
  * Precedence:
- *   1. warm/draining lease → **live** (a warm box always wins).
+ *   1. warm lease → **live** (a holder-confirmed box always wins).
  *   2. actively warming (negotiating, wake-on-edit, or a reconnecting/enrolling
  *      machine) → **waking**.
  *   3. everything else (a cold/asleep box, a self-hosted machine that's offline,
@@ -64,8 +65,9 @@ export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
   const asOf = input.capturedAt ?? null;
   const offlineLabel = asOf ? `Offline — as of ${formatAsOf(asOf, now)}` : "Offline";
 
-  // 1. A warm (or draining) lease is live regardless of anything else.
-  if (input.liveness === "warm" || input.liveness === "draining") {
+  // 1. Only holder-confirmed warm is live. Draining is teardown-owned and may
+  // already have lost its provider instance, so it uses the capture-backed label.
+  if (sandboxAcceptsLiveIo(input.liveness)) {
     return { state: "live", label: "Live", asOf: null };
   }
 

package/src/hooks/use-machines.ts

@@ -1,4 +1,9 @@
 import { useCallback, useRef, useState } from "react";
+import type {
+  RemoveEnrollmentRequest,
+  RemoveEnrollmentResponse,
+  SwapActiveSandboxResponse,
+} from "@opengeni/sdk";
 import { useOpenGeni, type ClientOverride } from "../provider";
 import { useMutationRunner, usePolledValue } from "./internal";
 import type { MachinesResponse, MachineView, MetricSample } from "../types/machines";
@@ -31,6 +36,12 @@ export type MachinesClientLike = {
     enrollmentId: string,
     options?: { window?: "15m" | "1h" | "6h" | "24h" },
   ) => Promise<MetricSample[]>;
+  /** POST .../enrollments/:enrollmentId/revoke — workspace-admin removal. */
+  removeEnrollment?: (
+    workspaceId: string,
+    enrollmentId: string,
+    request?: RemoveEnrollmentRequest,
+  ) => Promise<RemoveEnrollmentResponse>;
   /**
    * POST .../sessions/:sessionId/active-sandbox — swap the session's active
    * sandbox to a machine. The default swap path; the real SDK client provides it.
@@ -39,7 +50,7 @@ export type MachinesClientLike = {
     workspaceId: string,
     sessionId: string,
     request: { target: string },
-  ) => Promise<unknown>;
+  ) => Promise<SwapActiveSandboxResponse>;
   /**
    * Host-supplied swap adapter (an escape hatch). When present it wins over the
    * default `swapActiveSandbox` path. Session-scoped, like the swap it backs.
@@ -69,6 +80,13 @@ export type UseMachinesResult = {
   refresh: () => Promise<void>;
   /** Attach/swap the session's active sandbox to a machine (returns the new pointer). */
   attach: (sandboxId: string) => Promise<boolean>;
+  /** Remove a self-hosted enrollment while retaining history. */
+  remove: (
+    enrollmentId: string,
+    request?: RemoveEnrollmentRequest,
+  ) => Promise<RemoveEnrollmentResponse | null>;
+  canRemove: boolean;
+  removingEnrollmentId: string | null;
   /** Whether the host wired an attach/swap path (drives the card affordance). */
   canAttach: boolean;
   /** Fetch a downsampled metric series for one enrolled machine. */
@@ -85,6 +103,24 @@ export type UseMachinesResult = {
 
 const EMPTY: MachinesResponse = { activeSandboxId: null, activeEpoch: 0, machines: [] };
 
+function swapFailureMessage(result: SwapActiveSandboxResponse): string {
+  if (result.reason?.trim()) return result.reason;
+  switch (result.code) {
+    case "recovery_in_progress":
+      return "The managed sandbox is still recovering. Try again shortly.";
+    case "recovery_degraded":
+      return "The managed sandbox recovery is degraded and needs attention.";
+    case "recovery_unrecoverable":
+      return "The managed sandbox could not be recovered.";
+    case "offline_enrollment":
+      return "The selected machine is offline.";
+    case "concurrent_swap":
+      return "The session route changed concurrently. Refresh and try again.";
+    default:
+      return "The session stayed on its current sandbox.";
+  }
+}
+
 /**
  * The workspace Machines fleet: the selfhosted enrollments + the session's Modal
  * box, each with latest metrics + state, plus the active-sandbox pointer. Polls
@@ -128,6 +164,12 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
     sandboxId: string | null;
   }>(() => ({ identity: identityKey, sandboxId: null }));
   const attachingSandboxId = attachState.identity === identityKey ? attachState.sandboxId : null;
+  const [removeState, setRemoveState] = useState<{
+    identity: string;
+    enrollmentId: string | null;
+  }>(() => ({ identity: identityKey, enrollmentId: null }));
+  const removingEnrollmentId =
+    removeState.identity === identityKey ? removeState.enrollmentId : null;
 
   const data = loadedData ?? EMPTY;
   // The swap is session-scoped: a host adapter (`attachMachine`) wins; otherwise
@@ -137,6 +179,7 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
     sessionId !== undefined &&
     (typeof machinesClient.attachMachine === "function" ||
       typeof machinesClient.swapActiveSandbox === "function");
+  const canRemove = typeof machinesClient.removeEnrollment === "function";
 
   const attach = useCallback(
     async (sandboxId: string): Promise<boolean> => {
@@ -150,7 +193,15 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
       const ownedIdentity = identityKey;
       setAttachState({ identity: ownedIdentity, sandboxId });
       const result = await run(async () => {
-        await runSwap();
+        const response = await runSwap();
+        if (
+          response &&
+          typeof response === "object" &&
+          "swapped" in response &&
+          response.swapped === false
+        ) {
+          throw new Error(swapFailureMessage(response as SwapActiveSandboxResponse));
+        }
         return true;
       });
       if (identityRef.current === ownedIdentity) {
@@ -173,6 +224,28 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
     [machinesClient, workspaceId],
   );
 
+  const remove = useCallback(
+    async (
+      enrollmentId: string,
+      request: RemoveEnrollmentRequest = {},
+    ): Promise<RemoveEnrollmentResponse | null> => {
+      if (!machinesClient.removeEnrollment) return null;
+      const ownedIdentity = identityKey;
+      setRemoveState({ identity: ownedIdentity, enrollmentId });
+      const result = await run(() =>
+        machinesClient.removeEnrollment!(workspaceId, enrollmentId, request),
+      );
+      if (identityRef.current === ownedIdentity) {
+        setRemoveState({ identity: ownedIdentity, enrollmentId: null });
+        if (result?.outcome === "removed" || result?.outcome === "already_removed") {
+          await refresh();
+        }
+      }
+      return result;
+    },
+    [machinesClient, workspaceId, identityKey, run, refresh],
+  );
+
   return {
     machines: data.machines,
     activeSandboxId: data.activeSandboxId,
@@ -183,8 +256,11 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
     attach,
     canAttach,
     fetchSeries,
-    attaching: mutating,
+    attaching: mutating && attachingSandboxId !== null,
     attachingSandboxId,
+    remove,
+    canRemove,
+    removingEnrollmentId,
     mutationError,
     clearMutationError,
   };

package/src/hooks/use-packs.ts

@@ -1,8 +1,14 @@
 import type {
   CapabilityPack,
   EnablePackRequest,
+  InstallPackRequest,
+  PackInstallationPreview,
   PackInstallation,
+  PackUninstallPreview,
+  PreviewPackInstallationRequest,
   RegisterCapabilityPackRequest,
+  UninstallPackRequest,
+  UninstallPackResult,
   WorkspaceRegisteredPack,
 } from "@opengeni/sdk";
 import { useCallback } from "react";
@@ -28,7 +34,15 @@ export type UsePacksResult = {
   refresh: () => Promise<void>;
   /** Register (or replace) a workspace-scoped pack manifest. */
   register: (manifest: RegisterCapabilityPackRequest) => Promise<WorkspaceRegisteredPack | null>;
+  /** @deprecated Use previewInstallation + install for component/Rig-aware Packs. */
   enable: (packId: string, request?: EnablePackRequest) => Promise<PackInstallation | null>;
+  previewInstallation: (
+    packId: string,
+    request?: PreviewPackInstallationRequest,
+  ) => Promise<PackInstallationPreview | null>;
+  install: (packId: string, request: InstallPackRequest) => Promise<PackInstallation | null>;
+  previewUninstall: (packId: string) => Promise<PackUninstallPreview | null>;
+  uninstall: (packId: string, request: UninstallPackRequest) => Promise<UninstallPackResult | null>;
   /** Unregister a workspace-scoped pack (built-ins cannot be removed). */
   remove: (packId: string) => Promise<boolean>;
   mutating: boolean;
@@ -68,6 +82,39 @@ export function usePacks(options: UsePacksOptions = {}): UsePacksResult {
     [client, workspaceId, run, refresh],
   );
 
+  const previewInstallation = useCallback(
+    async (
+      packId: string,
+      request: PreviewPackInstallationRequest = {},
+    ): Promise<PackInstallationPreview | null> =>
+      await run(() => client.previewPackInstallation(workspaceId, packId, request)),
+    [client, workspaceId, run],
+  );
+
+  const install = useCallback(
+    async (packId: string, request: InstallPackRequest): Promise<PackInstallation | null> => {
+      const result = await run(() => client.installPack(workspaceId, packId, request));
+      if (result) await refresh();
+      return result;
+    },
+    [client, workspaceId, run, refresh],
+  );
+
+  const previewUninstall = useCallback(
+    async (packId: string): Promise<PackUninstallPreview | null> =>
+      await run(() => client.previewPackUninstall(workspaceId, packId)),
+    [client, workspaceId, run],
+  );
+
+  const uninstall = useCallback(
+    async (packId: string, request: UninstallPackRequest): Promise<UninstallPackResult | null> => {
+      const result = await run(() => client.uninstallPack(workspaceId, packId, request));
+      if (result) await refresh();
+      return result;
+    },
+    [client, workspaceId, run, refresh],
+  );
+
   const remove = useCallback(
     async (packId: string): Promise<boolean> => {
       const result = await run(async () => {
@@ -98,6 +145,10 @@ export function usePacks(options: UsePacksOptions = {}): UsePacksResult {
     refresh,
     register,
     enable,
+    previewInstallation,
+    install,
+    previewUninstall,
+    uninstall,
     remove,
     mutating,
     mutationError,