@opengeni/react 0.48.0 → 0.57.0

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

@@ -1,11 +1,13 @@
 import type {
   GitFileDiff,
+  SessionCapabilities,
   SessionEvent,
   WorkspaceCaptureManifest,
   WorkspaceCaptureRepo,
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { type ClientOverride, useOpenGeni } from "../provider";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
 export type UseSandboxGitOptions = ClientOverride & {
   /** Live event log (usually `useSessionEvents().events`) — drives auto-refresh
@@ -26,9 +28,10 @@ export type UseSandboxGitOptions = ClientOverride & {
   enabled?: boolean | undefined;
   /** Pause live reads/invalidation while preserving the last rendered result. */
   active?: boolean | undefined;
-  /** Lease liveness ("warm" | "draining" | "cold"). When NOT warm, the diff is
-   *  served from the capture (cold/offline) instead of a live `gitDiff` RPC. */
-  liveness?: string | undefined;
+  /** Lease liveness. `null` means capability negotiation is still pending and
+   *  blocks live I/O. When not warm, the diff is served from the capture instead
+   *  of a live `gitDiff` RPC. Omission preserves legacy direct-hook behavior. */
+  liveness?: SessionCapabilities["liveness"] | null | undefined;
   /** The latest turn-end capture (from `useWorkspaceCapture`). Seeds the diff
    *  immediately; a warm box reconciles live and leaves this durable review
    *  surface in place if the live request is temporarily unavailable. */
@@ -93,6 +96,11 @@ function uniqueRoots(roots: readonly string[]): string[] {
   return [...new Set(roots.map(normalizeRoot))].sort((a, b) => a.localeCompare(b));
 }
 
+// GitReadBatchRequest is contract-bounded to 32 items. Keep workspace-wide
+// reads bounded without changing the wire limit; sequential chunks preserve
+// deterministic root/result mapping and cap Channel-A lease concurrency at one.
+const GIT_READ_BATCH_REQUEST_LIMIT = 32;
+
 /** Find the capture repo matching `repoPath` (default workspace root). */
 function repoForPath(
   manifest: WorkspaceCaptureManifest,
@@ -201,7 +209,13 @@ export function useSandboxGit(
   // remains live-only; legacy captures simply lack branchDiff and fall back via
   // the workspace controller without inventing an empty branch comparison.
   const capture = comparison === "staged" ? null : (options.capture ?? null);
-  const isLive = options.liveness === "warm" || options.liveness === "draining";
+  const isLive = sandboxAcceptsLiveIo(options.liveness);
+  // `liveness` is optional for compatibility with direct hook consumers. 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${repoPathsKey}\u0000${workspaceWide}\u0000${comparison}`;
 
   const [diff, setDiff] = useState<SandboxGitFileDiff[]>([]);
@@ -251,35 +265,54 @@ export function useSandboxGit(
       // take several seconds on a remote sandbox. The legacy root probe remains
       // serial so a non-repository workspace never receives a failing git diff.
       const prefetched = hasAdvertisedRepoPaths
-        ? await client
-            .gitReadBatch(
-              workspaceId,
-              sessionId,
-              {
-                requests: repoPaths.map((root) => ({
-                  status: { path: root },
-                  diff: {
-                    path: root,
-                    ...(comparison === "branch"
-                      ? { fromRef: "origin/HEAD", includeUntracked: true }
-                      : comparison === "working"
-                        ? { fromRef: "HEAD", includeUntracked: true }
-                        : { staged: true, includeUntracked: false }),
-                  },
-                })),
-              },
-              { signal: refreshAbort.signal },
-            )
-            .then((batch) =>
-              batch.results.map((item, index) => ({
-                root: repoPaths[index] ?? "",
-                status: item.status,
-                result: item.diff ?? {
-                  files: [],
-                  revision: item.status.revision,
+        ? await (async () => {
+            const prefetchedRepos: Array<{
+              root: string;
+              status: Awaited<ReturnType<typeof client.gitStatus>>;
+              result: Awaited<ReturnType<typeof client.gitDiff>>;
+            }> = [];
+            for (
+              let offset = 0;
+              offset < repoPaths.length;
+              offset += GIT_READ_BATCH_REQUEST_LIMIT
+            ) {
+              const roots = repoPaths.slice(offset, offset + GIT_READ_BATCH_REQUEST_LIMIT);
+              const batch = await client.gitReadBatch(
+                workspaceId,
+                sessionId,
+                {
+                  requests: roots.map((root) => ({
+                    status: { path: root },
+                    diff: {
+                      path: root,
+                      ...(comparison === "branch"
+                        ? { fromRef: "origin/HEAD", includeUntracked: true }
+                        : comparison === "working"
+                          ? { fromRef: "HEAD", includeUntracked: true }
+                          : { staged: true, includeUntracked: false }),
+                    },
+                  })),
                 },
-              })),
-            )
+                { signal: refreshAbort.signal },
+              );
+              if (batch.results.length !== roots.length) {
+                throw new Error(
+                  `Workspace Git batch returned ${batch.results.length} results for ${roots.length} repositories.`,
+                );
+              }
+              batch.results.forEach((item, index) => {
+                prefetchedRepos.push({
+                  root: roots[index]!,
+                  status: item.status,
+                  result: item.diff ?? {
+                    files: [],
+                    revision: item.status.revision,
+                  },
+                });
+              });
+            }
+            return prefetchedRepos;
+          })()
         : null;
       const statuses =
         prefetched ??
@@ -427,7 +460,7 @@ export function useSandboxGit(
       if (!active) setLoading(false);
       return;
     }
-    if (isLive || !currentCapture) {
+    if (isLive || (!hasLiveIoFence && !currentCapture)) {
       void refresh();
     }
     return () => {
@@ -435,14 +468,36 @@ export function useSandboxGit(
       refreshAbortRef.current = null;
       refreshGenerationRef.current += 1;
     };
-  }, [enabled, active, isLive, captureRevision, identityKey, refresh, seedFromCapture]);
+  }, [
+    enabled,
+    active,
+    isLive,
+    hasLiveIoFence,
+    captureRevision,
+    identityKey,
+    refresh,
+    seedFromCapture,
+  ]);
 
   // git.changed → re-fetch the LIVE diff. Agent tool completion is also an
   // invalidation point because shell/apply-patch writes can bypass Channel-A and
   // therefore emit no git.changed event. This is event-driven, never polling.
   const events = options.events;
   useEffect(() => {
-    if (!enabled || !active || !events) {
+    if (!enabled || !events) {
+      if (commandRefreshTimerRef.current) {
+        clearTimeout(commandRefreshTimerRef.current);
+        commandRefreshTimerRef.current = null;
+      }
+      return;
+    }
+    // Historical events describe the capture we already loaded. Inactive tabs
+    // and holderless draining/cold leases advance the cursor without issuing
+    // provider I/O; becoming warm performs one authoritative reconcile above.
+    if (!active || !acceptsEventReads) {
+      for (const event of events) {
+        if (event.sequence > lastChangeRef.current) lastChangeRef.current = event.sequence;
+      }
       if (commandRefreshTimerRef.current) {
         clearTimeout(commandRefreshTimerRef.current);
         commandRefreshTimerRef.current = null;
@@ -467,15 +522,15 @@ export function useSandboxGit(
       if (immediate) {
         if (commandRefreshTimerRef.current) clearTimeout(commandRefreshTimerRef.current);
         commandRefreshTimerRef.current = null;
-        void refresh();
+        if (acceptsEventReadsRef.current) void refresh();
       } else if (commandDelta && !commandRefreshTimerRef.current) {
         commandRefreshTimerRef.current = setTimeout(() => {
           commandRefreshTimerRef.current = null;
-          void refresh();
+          if (acceptsEventReadsRef.current) void refresh();
         }, 1_000);
       }
     }
-  }, [enabled, active, events, refresh]);
+  }, [enabled, active, acceptsEventReads, events, refresh]);
 
   useEffect(
     () => () => {

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

@@ -7,6 +7,7 @@ import type {
 import { OpenGeniApiError } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
 export type TerminalChunk = {
   /** Stable key (the source event id) so the xterm writer tracks a written-cursor. */
@@ -107,9 +108,9 @@ export function useSandboxTerminal(
   // projection is the single source of truth for what's written). The open is
   // gated on a WARM box: opening on a cold/warming lease races the box (the PTY
   // exec-session is created on a box that the next op may not resume), which is
-  // exactly the "session not found" terminal failure; we wait for warm/draining.
+  // exactly the "session not found" terminal failure; we wait for warm.
   const openInFlight = useRef(false);
-  const boxWarm = liveness === undefined || liveness === "warm" || liveness === "draining";
+  const boxWarm = liveness === undefined || sandboxAcceptsLiveIo(liveness);
   useEffect(() => {
     if (!interactive || !sessionId || ptyFilter || !boxWarm) {
       setOpenError(null);

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

@@ -7,10 +7,13 @@ import {
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
+import { terminalCanAcquirePty } from "../lib/terminal-capability";
 import { usePageLiveActivity } from "./internal";
 
-// "on-demand" is the boxless-benign resting state: the lease is cold and NOTHING
-// asked to warm a box (no viewer/consent action, no files-tab warm). Under lazy
+// "on-demand" is the boxless-benign resting state: the lease is not currently
+// holder-backed and NOTHING asked to warm a box (no viewer/consent action, no
+// files-tab warm). Under lazy
 // provisioning a chat-only turn never creates a box, so this is the correct calm
 // terminal state — NOT an error. It is distinct from "cold", which now means "a
 // warm-up is genuinely in flight" (a viewer attach was requested) and therefore
@@ -84,7 +87,8 @@ export type UseSessionCapabilitiesResult = {
   error: Error | null;
   /**
    * 409 from the desktop attach: the un-redacted (or shared) plane needs explicit
-   * acknowledgment before a viewer holder is granted. Drives the consent prompt.
+   * acknowledgment before a viewer holder is granted. The workbench uses this
+   * to complete acknowledgment automatically while Desktop is opening.
    */
   acknowledgmentRequired: "unredacted" | "shared" | null;
   /** 429 from the desktop attach: the per-session viewer cap is reached. */
@@ -112,24 +116,10 @@ function desktopAttachable(cell: SessionCapabilities["DesktopStream"]): boolean
 
 /**
  * Whether warming the box for the interactive terminal (pty-ws) is worth it.
- * The Terminal cell is ALWAYS feasible when the backend advertises a transport at
- * all (`sse-events` on a cold box, `pty-ws` once warm) — only a genuinely
- * terminal-less backend reports transport:null with a hard reason. The attach is
- * what flips `sse-events` → `pty-ws` by warming the box and minting the ttyd
- * tunnel URL, so we attach whenever the terminal is not hard-unavailable.
+ * A real-PTY descriptor is attachable when already routed as `pty-ws`, or while
+ * transiently cold. A firehose-only backend and policy/OS/backend degradation
+ * cannot become interactive, so attaching there would only waste a holder.
  */
-function terminalAttachable(cell: SessionCapabilities["Terminal"]): boolean {
-  if (cell.transport === null) {
-    // No terminal at all unless the only blocker is a transient cold state.
-    return (
-      cell.reason === "lease_cold" || cell.reason === "not_provisioned" || cell.reason === null
-    );
-  }
-  // Already pty-ws (warm) is fine to (re)attach; sse-events is the cold state the
-  // attach upgrades. Either way it's attachable.
-  return true;
-}
-
 /** Read `stream.url.rotated` payloads off the live event log, newest last. */
 function rotationsFrom(events: SessionEvent[]): StreamUrlRotatedPayload[] {
   const out: StreamUrlRotatedPayload[] = [];
@@ -149,8 +139,8 @@ function rotationsFrom(events: SessionEvent[]): StreamUrlRotatedPayload[] {
  *
  * Degradation is a value, never a crash: an unsupported surface comes back
  * `available:false`/`transport:null` + a `reason`; the components render the
- * reason-aware empty state. 409 (consent) and 429 (viewer cap) are surfaced as
- * typed signals, not thrown.
+ * reason-aware empty state. 409 (acknowledgment) and 429 (viewer cap) are
+ * surfaced as typed signals, not thrown.
  */
 export function useSessionCapabilities(
   sessionId: string | null | undefined,
@@ -207,8 +197,15 @@ export function useSessionCapabilities(
     if (!lifecycleEnabled || !sessionId) {
       setState("idle");
       setCapabilities(null);
+      viewerIdRef.current = null;
+      setViewerId(null);
       return;
     }
+    // The preceding effect cleanup released any old holder before this fresh
+    // lifecycle starts. Never project that stale id while re-negotiating or if
+    // the replacement grant degrades.
+    viewerIdRef.current = null;
+    setViewerId(null);
     let cancelled = false;
     let pollTimer: ReturnType<typeof setTimeout> | null = null;
     let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
@@ -273,7 +270,7 @@ export function useSessionCapabilities(
           .then((caps) => {
             if (cancelled) return;
             settle(caps);
-            if (caps.liveness === "warm" || caps.liveness === "draining") {
+            if (sandboxAcceptsLiveIo(caps.liveness)) {
               setState("ready");
               return;
             }
@@ -308,8 +305,8 @@ export function useSessionCapabilities(
         // attach serves BOTH live planes — the desktop pixel stream AND the
         // interactive terminal (ttyd pty-ws) ride the same warm box and the same
         // holder; the response folds the minted address for each requested plane.
-        // The consent gate (409) and the viewer cap (429) surface as typed signals
-        // rather than throwing — the tabs degrade gracefully.
+        // The acknowledgment requirement (409) and viewer cap (429) surface as
+        // typed signals rather than throwing — the tabs degrade gracefully.
         //
         // KEY: the handshake (getStreamCapabilities) NEVER spins up a cold box, so
         // on a cold/warming lease the desktop cell comes back transport:null and
@@ -321,7 +318,7 @@ export function useSessionCapabilities(
         // already live OR cold-but-feasible — and let POST /viewers warm the box and
         // mint the URLs. Only a genuinely-unsupported reason suppresses the attach.
         const wantDesktopAttach = attachDesktop && desktopAttachable(caps.DesktopStream);
-        const wantTerminalAttach = attachTerminal && terminalAttachable(caps.Terminal);
+        const wantTerminalAttach = attachTerminal && terminalCanAcquirePty(caps.Terminal);
         // The Files attach warms the box for a file WRITE (wake-on-edit intent). It
         // folds no live URL (files are stateless HTTP) — the attach is purely a
         // liveness refcount. Unlike the previous "keep the box warm while the Files
@@ -339,6 +336,8 @@ export function useSessionCapabilities(
             // pty-ws terminal cell WITHOUT tripping the desktop consent 409.
             const holder = await client.attachViewer(workspaceId, sessionId, {
               desktop: wantDesktopAttach,
+              terminal: wantTerminalAttach,
+              files: wantFilesAttach,
             });
             if (cancelled) {
               // The attach crossed an identity/unmount boundary after the server
@@ -348,6 +347,18 @@ export function useSessionCapabilities(
               void client.detachViewer(workspaceId, sessionId, holder.viewerId).catch(() => {});
               return;
             }
+            if (
+              (wantDesktopAttach &&
+                (!holder.dataPlaneUrl || !holder.transport || !holder.client)) ||
+              (wantTerminalAttach && (!holder.terminalUrl || !holder.terminalTransport))
+            ) {
+              // Nullable plane cells are valid graceful-degradation values at
+              // the raw API boundary, but an explicit UI grant must not become
+              // a successful holder that waits forever. Release it and surface
+              // a retryable error instead of retaining stale credentials.
+              await client.detachViewer(workspaceId, sessionId, holder.viewerId).catch(() => {});
+              throw new Error("live plane unavailable");
+            }
             localViewerId = holder.viewerId;
             viewerIdRef.current = holder.viewerId;
             setViewerId(holder.viewerId);
@@ -367,24 +378,24 @@ export function useSessionCapabilities(
                           ...prev.DesktopStream,
                           transport: holder.transport ?? prev.DesktopStream.transport,
                           client: holder.client ?? prev.DesktopStream.client,
-                          url: holder.dataPlaneUrl ?? prev.DesktopStream.url,
-                          token: holder.streamToken ?? prev.DesktopStream.token,
-                          expiresAt: holder.streamExpiresAt ?? prev.DesktopStream.expiresAt,
+                          url: holder.dataPlaneUrl,
+                          token: holder.streamToken,
+                          expiresAt: holder.streamExpiresAt,
                           resolution: holder.resolution ?? prev.DesktopStream.resolution,
                         }
                       : prev.DesktopStream,
-                    Terminal:
-                      holder.terminalUrl && holder.terminalTransport
-                        ? {
-                            ...prev.Terminal,
-                            transport: holder.terminalTransport,
-                            url: holder.terminalUrl,
-                            token: holder.terminalToken ?? prev.Terminal.token,
-                            // A live pty-ws means the box is pty-capable for real.
-                            ptyCapable: true,
-                            reason: null,
-                          }
-                        : prev.Terminal,
+                    Terminal: wantTerminalAttach
+                      ? {
+                          ...prev.Terminal,
+                          transport: holder.terminalTransport ?? prev.Terminal.transport,
+                          url: holder.terminalUrl,
+                          token: holder.terminalToken,
+                          expiresAt: holder.terminalExpiresAt,
+                          // A live pty-ws means the box is pty-capable for real.
+                          ptyCapable: holder.terminalTransport ? true : prev.Terminal.ptyCapable,
+                          reason: holder.terminalTransport ? null : prev.Terminal.reason,
+                        }
+                      : prev.Terminal,
                   }
                 : prev,
             );
@@ -393,8 +404,8 @@ export function useSessionCapabilities(
             if (cause instanceof OpenGeniApiError) {
               if (cause.status === 409) {
                 // The un-redacted/shared consent gate is a DESKTOP requirement. A
-                // terminal-only warm attach needs no consent, so a 409 there is not
-                // a consent prompt — the terminal just stays on the read-only
+                // terminal-only warm attach needs no acknowledgment, so a 409 there
+                // is not a desktop-open signal — the terminal stays on the read-only
                 // firehose. Only raise the consent requirement when the desktop was
                 // the (or a) reason we attached.
                 if (wantDesktopAttach) {
@@ -408,6 +419,8 @@ export function useSessionCapabilities(
                 setState("error");
                 setError(cause);
                 return;
+              } else {
+                throw cause;
               }
               // 409/429 are recoverable: structured surfaces still negotiated;
               // keep going to set ready/cold below.
@@ -418,16 +431,16 @@ export function useSessionCapabilities(
         }
 
         // Whether ANYTHING asked to warm a box this negotiation. Only then is a
-        // cold lease "warming in flight" — worth polling, and worth surfacing a
+        // non-warm lease "warming in flight" — worth polling, and worth surfacing a
         // stall as an error. With no warm-up requested a cold lease is the benign
         // boxless resting state (below), never an error.
         const warmUpRequested = wantDesktopAttach || wantTerminalAttach || wantFilesAttach;
-        if (caps.liveness === "warm" || caps.liveness === "draining" || localViewerId) {
+        if (sandboxAcceptsLiveIo(caps.liveness) || localViewerId) {
           setState("ready");
           startHeartbeat(caps);
         } else if (warmUpRequested) {
           // A warm-up is genuinely in flight (a viewer attach was requested) but the
-          // box isn't warm yet — poll until it warms, with the patience deadline so a
+          // box isn't holder-confirmed warm yet — poll until it is, with the deadline so a
           // real stall surfaces as an error.
           setState("cold");
           pollUntilWarm();

package/src/hooks/use-site-auth-connections.ts

@@ -0,0 +1,226 @@
+import type {
+  CreateSiteAuthConnectionRequest,
+  SiteAuthConnection,
+  SiteAuthConnectionMutationResponse,
+  UpdateSiteAuthConnectionRequest,
+} 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 UseSiteAuthConnectionsOptions = EmbeddedBrowserInteractionClientOverride & {
+  enabled?: boolean | undefined;
+  includeArchived?: boolean | undefined;
+};
+
+export type UseSiteAuthConnectionsResult = {
+  revision: number;
+  connections: SiteAuthConnection[];
+  loading: boolean;
+  refreshing: boolean;
+  mutating: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  create: (
+    request: Omit<CreateSiteAuthConnectionRequest, "operationId"> & { operationId?: string },
+  ) => Promise<SiteAuthConnectionMutationResponse>;
+  update: (
+    connectionId: string,
+    request: Omit<UpdateSiteAuthConnectionRequest, "operationId"> & {
+      operationId?: string;
+    },
+  ) => Promise<SiteAuthConnectionMutationResponse>;
+};
+
+/** Secret-free workspace login recipes and their verified health. */
+export function useSiteAuthConnections(
+  options: UseSiteAuthConnectionsOptions = {},
+): UseSiteAuthConnectionsResult {
+  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.listSiteAuthConnections(workspaceId, {
+          includeArchived,
+          signal: controller.signal,
+        });
+        if (!mountedRef.current || requestRef.current.id !== id) return;
+        setState({
+          key,
+          revision: response.revision,
+          connections: sortConnections(response.connections),
+          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],
+  );
+
+  const refresh = useCallback(async () => await load(false), [load]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!enabled) {
+      cancelLoad();
+      setState(emptyState(key, false));
+      return;
+    }
+    void load(true);
+    return () => {
+      mountedRef.current = false;
+      cancelLoad();
+    };
+  }, [cancelLoad, enabled, key, 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(
+    (connection: SiteAuthConnection) => {
+      setState((current) => {
+        if (current.key !== key) return current;
+        const connections = current.connections.filter(
+          (candidate) => candidate.id !== connection.id,
+        );
+        if (includeArchived || connection.status !== "archived") connections.push(connection);
+        return { ...current, connections: sortConnections(connections), error: null };
+      });
+    },
+    [includeArchived, key],
+  );
+
+  const create = useCallback(
+    async (
+      request: Omit<CreateSiteAuthConnectionRequest, "operationId"> & {
+        operationId?: string;
+      },
+    ): Promise<SiteAuthConnectionMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.createSiteAuthConnection(workspaceId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.connection);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  const update = useCallback(
+    async (
+      connectionId: string,
+      request: Omit<UpdateSiteAuthConnectionRequest, "operationId"> & {
+        operationId?: string;
+      },
+    ): Promise<SiteAuthConnectionMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.updateSiteAuthConnection(workspaceId, connectionId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.connection);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  return {
+    revision: visible.revision,
+    connections: visible.connections,
+    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,
+    connections: [] as SiteAuthConnection[],
+    loading,
+    refreshing: false,
+    error: null as Error | null,
+  };
+}
+
+function sortConnections(connections: readonly SiteAuthConnection[]): SiteAuthConnection[] {
+  return [...connections].sort(
+    (left, right) =>
+      Number(left.status === "archived") - Number(right.status === "archived") ||
+      left.name.localeCompare(right.name) ||
+      left.accountLabel.localeCompare(right.accountLabel),
+  );
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+export type SiteAuthConnectionsClient = EmbeddedBrowserInteractionClientLike;