@opengeni/react 0.48.0 → 0.57.0

package/src/hooks/use-network-routes.ts

@@ -0,0 +1,214 @@
+import type {
+  CreateNetworkRouteRequest,
+  NetworkRoute,
+  NetworkRouteMutationResponse,
+  UpdateNetworkRouteRequest,
+} from "@opengeni/sdk/interaction";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { EmbeddedBrowserInteractionClientLike } from "../client";
+import {
+  type EmbeddedBrowserInteractionClientOverride,
+  useEmbeddedBrowserInteraction,
+} from "../session-context";
+import { useInteractionInvalidation } from "./use-interaction-invalidation";
+
+export type UseNetworkRoutesOptions = EmbeddedBrowserInteractionClientOverride & {
+  enabled?: boolean | undefined;
+  includeArchived?: boolean | undefined;
+};
+
+export type UseNetworkRoutesResult = {
+  revision: number;
+  routes: NetworkRoute[];
+  loading: boolean;
+  refreshing: boolean;
+  mutating: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  create: (
+    request: Omit<CreateNetworkRouteRequest, "operationId"> & { operationId?: string },
+  ) => Promise<NetworkRouteMutationResponse>;
+  update: (
+    networkRouteId: string,
+    request: Omit<UpdateNetworkRouteRequest, "operationId"> & { operationId?: string },
+  ) => Promise<NetworkRouteMutationResponse>;
+};
+
+/** Workspace network-route registry. Route mutations never expose brokered credentials. */
+export function useNetworkRoutes(options: UseNetworkRoutesOptions = {}): UseNetworkRoutesResult {
+  const { client, workspaceId, workspaceInteractionEvent, workspaceInteractionConnectionState } =
+    useEmbeddedBrowserInteraction(options);
+  const enabled = options.enabled ?? true;
+  const includeArchived = options.includeArchived ?? false;
+  const key = `${workspaceId}:${includeArchived ? "all" : "active"}`;
+  const [state, setState] = useState(() => emptyState(key, enabled));
+  const [mutationCount, setMutationCount] = useState(0);
+  const requestRef = useRef<{ id: number; controller: AbortController | null }>({
+    id: 0,
+    controller: null,
+  });
+  const mountedRef = useRef(true);
+  const visible = state.key === key ? state : emptyState(key, enabled);
+
+  const cancelLoad = useCallback(() => {
+    requestRef.current.controller?.abort();
+    requestRef.current = { id: requestRef.current.id + 1, controller: null };
+  }, []);
+
+  const load = useCallback(
+    async (foreground: boolean): Promise<void> => {
+      if (!enabled) return;
+      const id = requestRef.current.id + 1;
+      requestRef.current.controller?.abort();
+      const controller = new AbortController();
+      requestRef.current = { id, controller };
+      setState((current) => ({
+        ...(current.key === key ? current : emptyState(key, true)),
+        loading: foreground,
+        refreshing: !foreground,
+        error: foreground || current.key !== key ? null : current.error,
+      }));
+      try {
+        const response = await client.listNetworkRoutes(workspaceId, {
+          includeArchived,
+          signal: controller.signal,
+        });
+        if (!mountedRef.current || requestRef.current.id !== id) return;
+        setState({
+          key,
+          revision: response.revision,
+          routes: sortRoutes(response.routes),
+          loading: false,
+          refreshing: false,
+          error: null,
+        });
+      } catch (cause) {
+        if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id)
+          return;
+        setState((current) => ({
+          ...(current.key === key ? current : emptyState(key, true)),
+          loading: false,
+          refreshing: false,
+          error: asError(cause),
+        }));
+      } finally {
+        if (requestRef.current.id === id) requestRef.current = { id, controller: null };
+      }
+    },
+    [client, enabled, includeArchived, key, workspaceId],
+  );
+
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!enabled) {
+      cancelLoad();
+      setState(emptyState(key, false));
+      return;
+    }
+    void load(true);
+    return () => {
+      mountedRef.current = false;
+      cancelLoad();
+    };
+  }, [cancelLoad, enabled, key, load]);
+
+  const refresh = useCallback(async () => await load(false), [load]);
+  useInteractionInvalidation({
+    workspaceId,
+    key,
+    enabled,
+    event: workspaceInteractionEvent,
+    connectionState: workspaceInteractionConnectionState,
+    knownRevision: visible.revision,
+    refresh,
+  });
+
+  const mutate = useCallback(async <T>(operation: () => Promise<T>): Promise<T> => {
+    setMutationCount((count) => count + 1);
+    try {
+      return await operation();
+    } finally {
+      if (mountedRef.current) setMutationCount((count) => Math.max(0, count - 1));
+    }
+  }, []);
+
+  const merge = useCallback(
+    (route: NetworkRoute) => {
+      setState((current) => {
+        if (current.key !== key) return current;
+        const routes = current.routes.filter((candidate) => candidate.id !== route.id);
+        if (includeArchived || route.status !== "archived") routes.push(route);
+        return { ...current, routes: sortRoutes(routes), error: null };
+      });
+    },
+    [includeArchived, key],
+  );
+
+  const create = useCallback(
+    async (
+      request: Omit<CreateNetworkRouteRequest, "operationId"> & { operationId?: string },
+    ): Promise<NetworkRouteMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.createNetworkRoute(workspaceId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.route);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  const update = useCallback(
+    async (
+      networkRouteId: string,
+      request: Omit<UpdateNetworkRouteRequest, "operationId"> & { operationId?: string },
+    ): Promise<NetworkRouteMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.updateNetworkRoute(workspaceId, networkRouteId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.route);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  return {
+    revision: visible.revision,
+    routes: visible.routes,
+    loading: visible.loading,
+    refreshing: visible.refreshing,
+    mutating: mutationCount > 0,
+    error: visible.error,
+    refresh,
+    create,
+    update,
+  };
+}
+
+function emptyState(key: string, loading: boolean) {
+  return {
+    key,
+    revision: 0,
+    routes: [] as NetworkRoute[],
+    loading,
+    refreshing: false,
+    error: null as Error | null,
+  };
+}
+
+function sortRoutes(routes: readonly NetworkRoute[]): NetworkRoute[] {
+  return [...routes].sort(
+    (left, right) =>
+      Number(left.status === "archived") - Number(right.status === "archived") ||
+      left.name.localeCompare(right.name),
+  );
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+export type NetworkRoutesClient = EmbeddedBrowserInteractionClientLike;

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,

package/src/hooks/use-sandbox-files.ts

@@ -7,11 +7,13 @@ import type {
   GitFileStatusCode,
   GitStatusResponse,
   OpenGeniRequestOptions,
+  SessionCapabilities,
   SessionEvent,
   WorkspaceCaptureManifest,
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { type ClientOverride, useOpenGeni } from "../provider";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
 /** The git-status overlay a file row may carry (tints modified files in the tree). */
 export type FileTreeStatus = "added" | "modified" | "deleted" | "renamed" | "untracked";
@@ -87,12 +89,14 @@ export type UseSandboxFilesOptions = ClientOverride & {
   active?: boolean | undefined;
   /** Repository roots advertised by capabilities, relative to the workspace. */
   repoPaths?: readonly string[] | undefined;
-  /** The lease liveness ("cold" | "warm" | "draining"). The structured FileSystem
+  /** The lease liveness. `null` means capability negotiation has not produced
+   *  an authoritative lifecycle value yet and therefore blocks live I/O. Omitting
+   *  the option preserves the legacy direct-hook behavior. The structured FileSystem
    *  capability is advertised even on a COLD box, so the mount-time list can race
    *  the box: it lists before the box is warm, gets an empty/errored result, and
    *  (with no `fs.changed` event) never re-lists. Passing liveness re-lists when
    *  the box first becomes warm, so the tree populates as soon as the box is up. */
-  liveness?: string | undefined;
+  liveness?: SessionCapabilities["liveness"] | null | undefined;
   /** The latest turn-end workspace capture (from `useWorkspaceCapture`). The tree
    *  paints immediately from this durable index, then a warm box reconciles live
    *  in place. If that live read fails, the capture remains a truthful read-only
@@ -487,7 +491,13 @@ export function useSandboxFiles(
   ].join("\u0000");
   const repoPaths = useMemo(() => repoPathsKey.split("\u0000"), [repoPathsKey]);
   const capture = options.capture ?? null;
-  const isLive = options.liveness === "warm" || options.liveness === "draining";
+  const isLive = sandboxAcceptsLiveIo(options.liveness);
+  // `liveness` predates this hook option. Preserve legacy embedders that omit it;
+  // explicit `null` (negotiating) and lifecycle values require authoritative warm.
+  const acceptsEventReads = options.liveness === undefined || isLive;
+  const acceptsEventReadsRef = useRef(acceptsEventReads);
+  acceptsEventReadsRef.current = acceptsEventReads;
+  const hasLiveIoFence = options.liveness !== undefined;
   const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${rootPath}\u0000${repoPathsKey}`;
 
   const [tree, setTree] = useState<FileTreeNode[]>([]);
@@ -512,6 +522,7 @@ export function useSandboxFiles(
   const refreshGenerationRef = useRef(0);
   const refreshAbortRef = useRef<AbortController | null>(null);
   const identityAbortRef = useRef(new AbortController());
+  const eventReadAbortRef = useRef(new AbortController());
   const identityGenerationRef = useRef(0);
   const lastSeqRef = useRef(0);
   const pendingParentsRef = useRef<Set<string>>(new Set());
@@ -846,20 +857,18 @@ export function useSandboxFiles(
   // of a parent that isn't loaded (collapsed/unmounted) is a no-op — there's
   // nothing visible to update, and it re-lists fresh when the user expands it.
   const reconcilePath = useCallback(
-    async (path: string) => {
+    async (path: string, requestSignal?: AbortSignal) => {
       if (!sessionId) return;
       const identityGeneration = identityGenerationRef.current;
       const identitySignal = identityAbortRef.current.signal;
+      const signal = requestSignal
+        ? AbortSignal.any([identitySignal, requestSignal])
+        : identitySignal;
       // Skip parents that aren't currently loaded/expanded in the tree (nothing
       // visible to update; they re-list fresh on the next expand).
       if (!parentIsLoaded(treeRef.current, path)) return;
       try {
-        const listed = await client.fsList(
-          workspaceId,
-          sessionId,
-          { path, depth: 1 },
-          { signal: identitySignal },
-        );
+        const listed = await client.fsList(workspaceId, sessionId, { path, depth: 1 }, { signal });
         if (identityGenerationRef.current !== identityGeneration) return;
         const children = (listed.root.children ?? []).map((node) => fsNodeToTree(node));
         if (path === "") setTree((prev) => applyStatus(mergeRootChildren(prev, children)));
@@ -1075,9 +1084,10 @@ export function useSandboxFiles(
 
   // Initial paint + reset on identity change. Source selection:
   //   • any box WITH a capture → paint instantly from the durable capture index;
-  //     a warm/draining box then reconciles live in place.
+  //     a holder-confirmed warm box then reconciles live in place.
   //   • if that live reconciliation fails, keep the capture visible and read-only.
-  //   • cold box with NO capture → best-effort live list (status quo — never worse).
+  //   • legacy callers that omit liveness and have no capture retain their live
+  //     fallback; an explicitly cold/draining lease never wakes from a passive mount.
   // Key the seed on the capture's REVISION (a primitive), not the manifest object
   // — a consumer passing a fresh object each render (or a new revision) must not
   // spin the effect. The latest manifest is read from a ref at run time.
@@ -1092,6 +1102,8 @@ export function useSandboxFiles(
     refreshAbortRef.current?.abort();
     refreshAbortRef.current = null;
     refreshGenerationRef.current += 1;
+    eventReadAbortRef.current.abort();
+    eventReadAbortRef.current = new AbortController();
     const identityChanged = previousIdentityRef.current !== identityKey;
     previousIdentityRef.current = identityKey;
     if (identityChanged || !enabled) {
@@ -1135,53 +1147,69 @@ export function useSandboxFiles(
       }
       return;
     }
-    if (isLive || !currentCapture) {
+    if (isLive || (!hasLiveIoFence && !currentCapture)) {
       void refresh();
     }
     return () => {
       refreshAbortRef.current?.abort();
       refreshAbortRef.current = null;
       refreshGenerationRef.current += 1;
+      eventReadAbortRef.current.abort();
     };
-  }, [enabled, active, isLive, captureRevision, identityKey, refresh, seedFromCapture]);
+  }, [
+    enabled,
+    active,
+    isLive,
+    hasLiveIoFence,
+    captureRevision,
+    identityKey,
+    refresh,
+    seedFromCapture,
+  ]);
 
   // Re-pull JUST the git-status overlay and re-tint the existing tree in place —
   // no fs re-list, no collapse. This is all a `git.changed` (commit/stage/checkout)
   // needs: the tree SHAPE is unchanged, only the tints move.
-  const refreshGitOverlay = useCallback(async () => {
-    if (!sessionId) return;
-    const identityGeneration = identityGenerationRef.current;
-    const identitySignal = identityAbortRef.current.signal;
-    setGitLoading(true);
-    try {
-      const batch = await client.gitReadBatch(
-        workspaceId,
-        sessionId,
-        { requests: repoPaths.map((root) => ({ status: { path: root } })) },
-        { signal: identitySignal },
-      );
-      const statuses = batch.results.map((result, index) => ({
-        root: repoPaths[index] ?? "",
-        status: result.status,
-      }));
-      if (identityGenerationRef.current !== identityGeneration) return;
-      const overlay = new Map<string, FileTreeStatus>();
-      for (const { root, status } of statuses) {
-        for (const file of status.files) {
-          const code = file.worktree ?? file.index;
-          const mapped = code ? GIT_STATUS_TO_TREE[code] : undefined;
-          if (mapped) overlay.set(qualifyStatusPath(root, file.path), mapped);
+  const refreshGitOverlay = useCallback(
+    async (requestSignal?: AbortSignal) => {
+      if (!sessionId) return;
+      const identityGeneration = identityGenerationRef.current;
+      const identitySignal = identityAbortRef.current.signal;
+      const signal = requestSignal
+        ? AbortSignal.any([identitySignal, requestSignal])
+        : identitySignal;
+      setGitLoading(true);
+      try {
+        const batch = await client.gitReadBatch(
+          workspaceId,
+          sessionId,
+          { requests: repoPaths.map((root) => ({ status: { path: root } })) },
+          { signal },
+        );
+        const statuses = batch.results.map((result, index) => ({
+          root: repoPaths[index] ?? "",
+          status: result.status,
+        }));
+        if (identityGenerationRef.current !== identityGeneration) return;
+        const overlay = new Map<string, FileTreeStatus>();
+        for (const { root, status } of statuses) {
+          for (const file of status.files) {
+            const code = file.worktree ?? file.index;
+            const mapped = code ? GIT_STATUS_TO_TREE[code] : undefined;
+            if (mapped) overlay.set(qualifyStatusPath(root, file.path), mapped);
+          }
         }
+        statusRef.current = overlay;
+        setGitSummary(summarizeStatuses(statuses));
+        setTree((prev) => applyStatus(prev));
+      } catch {
+        /* a non-repo box has no overlay — leave the tree untinted */
+      } finally {
+        if (identityGenerationRef.current === identityGeneration) setGitLoading(false);
       }
-      statusRef.current = overlay;
-      setGitSummary(summarizeStatuses(statuses));
-      setTree((prev) => applyStatus(prev));
-    } catch {
-      /* a non-repo box has no overlay — leave the tree untinted */
-    } finally {
-      if (identityGenerationRef.current === identityGeneration) setGitLoading(false);
-    }
-  }, [client, workspaceId, sessionId, repoPaths, applyStatus]);
+    },
+    [client, workspaceId, sessionId, repoPaths, applyStatus],
+  );
 
   // Auto-reconcile on fs/git change notifications — TARGETED, never a root
   // collapse-reload, and de-duped against our OWN mutations.
@@ -1197,13 +1225,20 @@ export function useSandboxFiles(
 
   useEffect(() => {
     if (!enabled || !events) return;
-    // An inactive tab must not replay the entire historical event log when it is
-    // opened. Keep its cursor current without performing any reconciliation;
-    // only events that arrive while Files is visible should trigger live reads.
-    if (!active) {
+    // An inactive tab or holderless draining/cold lease must not replay the
+    // historical log into live provider reads. The capture already includes
+    // those events; a later warm transition performs one authoritative refresh.
+    if (!active || !acceptsEventReads) {
       for (const event of events) {
         if (event.sequence > lastSeqRef.current) lastSeqRef.current = event.sequence;
       }
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+        debounceRef.current = null;
+      }
+      pendingParentsRef.current = new Set();
+      pendingGitRef.current = false;
+      pendingAgentToolRef.current = false;
       return;
     }
     let sawNew = false;
@@ -1277,6 +1312,12 @@ export function useSandboxFiles(
     debounceRef.current = setTimeout(() => {
       debounceRef.current = null;
       if (identityGenerationRef.current !== identityGeneration) return;
+      if (!acceptsEventReadsRef.current) {
+        pendingParentsRef.current = new Set();
+        pendingGitRef.current = false;
+        pendingAgentToolRef.current = false;
+        return;
+      }
       if (sawCommandDelta) {
         lastCommandRefreshAtRef.current = Date.now();
         setContentRevision((revision) => revision + 1);
@@ -1289,18 +1330,19 @@ export function useSandboxFiles(
       pendingAgentToolRef.current = false;
       // Reconcile the changed directories and Git overlay concurrently. Both are
       // independent remote reads; applyStatus makes their completion order safe.
+      const eventReadSignal = eventReadAbortRef.current.signal;
       void (async () => {
         const paths = wantAgentTool ? loadedDirectoryPaths(treeRef.current) : [...parents];
         await Promise.all([
-          wantGit ? refreshGitOverlay() : Promise.resolve(),
-          Promise.all(paths.map((path) => reconcilePath(path))),
+          wantGit ? refreshGitOverlay(eventReadSignal) : Promise.resolve(),
+          Promise.all(paths.map((path) => reconcilePath(path, eventReadSignal))),
         ]);
       })();
     }, delay);
-  }, [enabled, active, events, reconcilePath, refreshGitOverlay]);
+  }, [enabled, active, acceptsEventReads, events, reconcilePath, refreshGitOverlay]);
 
   useEffect(() => {
-    if (active) return;
+    if (active && acceptsEventReads) return;
     if (debounceRef.current) {
       clearTimeout(debounceRef.current);
       debounceRef.current = null;
@@ -1308,12 +1350,13 @@ export function useSandboxFiles(
     pendingParentsRef.current = new Set();
     pendingGitRef.current = false;
     pendingAgentToolRef.current = false;
-  }, [active]);
+  }, [active, acceptsEventReads]);
 
   useEffect(
     () => () => {
       refreshAbortRef.current?.abort();
       identityAbortRef.current.abort();
+      eventReadAbortRef.current.abort();
       identityGenerationRef.current += 1;
       if (debounceRef.current) clearTimeout(debounceRef.current);
     },