@opengeni/react 0.5.0 → 0.6.0

package/src/components/workspace-dock.tsx

@@ -1,4 +1,4 @@
-import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
+import { type ReactNode, useCallback, useEffect, useLayoutEffect, useState } from "react";
 import {
   ChevronsLeftRightIcon,
   Maximize2Icon,
@@ -30,6 +30,9 @@ export type WorkspaceDockProps = {
   /** Controlled active tab. Falls back to the first tab. */
   activeTab?: string | undefined;
   onActiveTabChange?: ((id: string) => void) | undefined;
+  /** Controlled collapsed state for hosts that expose their own dock toggle. */
+  collapsed?: boolean | undefined;
+  onCollapsedChange?: ((collapsed: boolean) => void) | undefined;
   /** Persisted layout id (localStorage key) for react-resizable-panels. */
   autoSaveId?: string | undefined;
   /** Default dock width as a percent of the session area. */
@@ -47,11 +50,15 @@ export type WorkspaceDockProps = {
  * `autoSaveId`. Maximize is a mode ABOVE the Group (a `fixed inset-0` overlay) —
  * pushing a Panel to ~100% still fights min sizes and leaves a chat sliver.
  */
+const useDockLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
 export function WorkspaceDock({
   primary,
   tabs,
   activeTab,
   onActiveTabChange,
+  collapsed: collapsedProp,
+  onCollapsedChange,
   autoSaveId = "og.session.dock",
   defaultSize = 34,
   minSize = 22,
@@ -59,9 +66,10 @@ export function WorkspaceDock({
   className,
 }: WorkspaceDockProps) {
   const dockPanelRef = usePanelRef();
-  const [collapsed, setCollapsed] = useState(false);
+  const [internalCollapsed, setInternalCollapsed] = useState(false);
   const [maximized, setMaximized] = useState(false);
   const [internalTab, setInternalTab] = useState(tabs[0]?.id ?? "");
+  const collapsed = collapsedProp ?? internalCollapsed;
 
   // Persisted layout (width split) keyed by autoSaveId.
   const { defaultLayout, onLayoutChanged } = useDefaultLayout({
@@ -71,6 +79,8 @@ export function WorkspaceDock({
   } as Parameters<typeof useDefaultLayout>[0]);
 
   const current = activeTab ?? internalTab;
+  const tabIds = tabs.map((tab) => tab.id).join("\u0000");
+  const firstTabId = tabs[0]?.id ?? "";
   const setTab = useCallback(
     (id: string) => {
       setInternalTab(id);
@@ -78,13 +88,34 @@ export function WorkspaceDock({
     },
     [onActiveTabChange],
   );
+  const setCollapsed = useCallback(
+    (next: boolean) => {
+      setInternalCollapsed((previous) => (previous === next ? previous : next));
+      onCollapsedChange?.(next);
+    },
+    [onCollapsedChange],
+  );
+
+  useDockLayoutEffect(() => {
+    if (collapsedProp === undefined) {
+      return;
+    }
+    if (collapsedProp) {
+      dockPanelRef.current?.collapse();
+      setMaximized(false);
+    } else {
+      dockPanelRef.current?.expand();
+    }
+  }, [collapsedProp, dockPanelRef]);
 
   // Keep the active tab valid if the available tabs change.
   useEffect(() => {
-    if (tabs.length > 0 && !tabs.some((t) => t.id === current)) {
-      setTab(tabs[0]!.id);
+    if (firstTabId && !tabs.some((t) => t.id === current)) {
+      setTab(firstTabId);
     }
-  }, [tabs, current, setTab]);
+    // Depend on tab identity, not the tab content objects. Session live events
+    // rebuild tab JSX frequently; only id changes can invalidate the active tab.
+  }, [tabIds, firstTabId, current, setTab]);
 
   // Esc restores from maximize.
   useEffect(() => {
@@ -99,11 +130,11 @@ export function WorkspaceDock({
   const collapse = useCallback(() => {
     dockPanelRef.current?.collapse();
     setCollapsed(true);
-  }, [dockPanelRef]);
+  }, [dockPanelRef, setCollapsed]);
   const expand = useCallback(() => {
     dockPanelRef.current?.expand();
     setCollapsed(false);
-  }, [dockPanelRef]);
+  }, [dockPanelRef, setCollapsed]);
 
   const dockChrome = (
     <DockChrome
@@ -142,16 +173,19 @@ export function WorkspaceDock({
           defaultSize={`${defaultSize}%`}
           minSize={`${minSize}%`}
           maxSize={`${maxSize}%`}
-          onResize={(size) => {
+          onResize={(size, _id, previousSize) => {
             // `asPercentage` is 0..100; treat a near-zero panel as collapsed.
             const isCollapsed = size.asPercentage <= 1;
-            setCollapsed((prev) => (prev !== isCollapsed ? isCollapsed : prev));
+            const canInferCollapse = collapsedProp === undefined || previousSize !== undefined;
+            if (canInferCollapse && isCollapsed !== collapsed) {
+              setCollapsed(isCollapsed);
+            }
           }}
           className="min-h-0 min-w-0"
         >
           {/* Hidden behind the overlay while maximized (avoids double-mounting
               the surfaces). */}
-          {!maximized && (
+          {!collapsed && !maximized && (
             <div className="flex h-full min-h-0 min-w-0 flex-col border-l border-[color:var(--og-color-border,var(--color-border,#2a2a2a))] bg-[color:var(--og-color-bg,var(--color-bg,#0d0d0d))]">
               {dockChrome}
             </div>

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

@@ -0,0 +1,179 @@
+import { useCallback, useState } from "react";
+import type { CodexAccount, CodexAccountsResponse, CodexRotationSettings, SessionEvent } from "@opengeni/sdk";
+import { useOpenGeni, type ClientOverride } from "../provider";
+import { useMutationRunner, usePolledValue, useSessionEventTrigger, type SessionEventFeedOptions } from "./internal";
+
+/** 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";
+}
+
+/**
+ * The structural slice of the SDK client the Codex-accounts surface needs. Method
+ * NAMES + SIGNATURES match `OpenGeniClient` so the real client satisfies it
+ * directly; declared structurally (not a hard Pick) so a test/Geni client can
+ * stand in. `getSession` reads the session's pin/last; `pinSessionCodexAccount`
+ * is the optional mutation (absent ⇒ the indicator hides the switch affordance).
+ */
+export type CodexAccountsClientLike = {
+  listCodexAccounts: (workspaceId: string) => Promise<CodexAccountsResponse>;
+  getSession?: (workspaceId: string, sessionId: string) => Promise<{ codexPinnedCredentialId?: string | null; codexLastCredentialId?: string | null }>;
+  pinSessionCodexAccount?: (workspaceId: string, sessionId: string, target: string) => Promise<{ pinned: string }>;
+  /** Optional (absent ⇒ the card hides live refresh): batched live /wham/usage refresh. */
+  refreshCodexUsage?: (workspaceId: string) => Promise<{ usage: Record<string, unknown> }>;
+};
+
+export type UseCodexAccountsOptions = ClientOverride & SessionEventFeedOptions & {
+  pollIntervalMs?: number | undefined;
+  /** Scope to a session so the hook resolves the pin + the effective account. */
+  sessionId?: string | undefined;
+  /** Override the client with one implementing `CodexAccountsClientLike`. */
+  codexClient?: CodexAccountsClientLike | undefined;
+};
+
+export type UseCodexAccountsResult = {
+  accounts: CodexAccount[];
+  /** The workspace ACTIVE account (used when a session is unpinned). */
+  activeAccountId: string | null;
+  /** The session's PINNED account (null ⇒ following workspace active). */
+  pinnedAccountId: string | null;
+  /** The account the next turn will run on: pin > workspace active. */
+  effectiveAccountId: string | null;
+  /** The account the session's last turn ACTUALLY ran on (the "Running on:" source). */
+  lastAccountId: string | null;
+  settings: CodexRotationSettings;
+  loading: boolean;
+  refresh: () => Promise<void>;
+  /**
+   * Trigger a LIVE batched /wham/usage refresh across all accounts, then re-read
+   * the cached metadata so the new windows land on `accounts`. Modeled on `pin`.
+   * No-op (resolves false) when the client can't refresh usage.
+   */
+  refreshUsage: () => Promise<boolean>;
+  /** True while a live usage refresh is in flight (drives the bar skeleton). */
+  refreshingUsage: boolean;
+  /** Pin (or unpin via "auto") the session's account; returns true on success. */
+  pin: (target: string) => Promise<boolean>;
+  pinning: boolean;
+  /** The target of the in-flight pin (for per-row spinner gating). */
+  pinningTarget: string | null;
+  mutationError: Error | null;
+};
+
+const EMPTY_SETTINGS: CodexRotationSettings = { rotationEnabled: false, rotationStrategy: "most_remaining", activeCredentialId: null };
+
+type CodexAccountsState = {
+  accounts: CodexAccount[];
+  activeAccountId: string | null;
+  settings: CodexRotationSettings;
+  pinnedAccountId: string | null;
+  lastAccountId: string | null;
+};
+
+const EMPTY_STATE: CodexAccountsState = {
+  accounts: [],
+  activeAccountId: null,
+  settings: EMPTY_SETTINGS,
+  pinnedAccountId: null,
+  lastAccountId: null,
+};
+
+/**
+ * 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.
+ * Dual-consumer safe via the structural `CodexAccountsClientLike` surface.
+ */
+export function useCodexAccounts(options: UseCodexAccountsOptions = {}): UseCodexAccountsResult {
+  const { client, workspaceId } = useOpenGeni(options);
+  const codexClient = (options.codexClient ?? (client as unknown as CodexAccountsClientLike));
+  const sessionId = options.sessionId;
+  const sharedEvents = options.events;
+
+  const load = useCallback(async (): Promise<CodexAccountsState> => {
+    const accountsP = codexClient.listCodexAccounts(workspaceId);
+    const sessionP = sessionId && codexClient.getSession
+      ? codexClient.getSession(workspaceId, sessionId).catch(() => null)
+      : Promise.resolve(null);
+    const [acc, session] = await Promise.all([accountsP, sessionP]);
+    return {
+      accounts: acc.accounts,
+      activeAccountId: acc.activeAccountId,
+      settings: acc.settings,
+      pinnedAccountId: session?.codexPinnedCredentialId ?? null,
+      lastAccountId: session?.codexLastCredentialId ?? null,
+    };
+  }, [codexClient, workspaceId, sessionId]);
+
+  const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled: options.enabled });
+  const mutation = useMutationRunner();
+  const usageMutation = 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.
+  useSessionEventTrigger(
+    client,
+    workspaceId,
+    sessionId,
+    isCodexAccountEvent,
+    () => void state.refresh(),
+    { enabled: options.enabled ?? true, ...(sharedEvents !== undefined ? { events: sharedEvents } : {}) },
+  );
+
+  const pin = useCallback(
+    async (target: string): Promise<boolean> => {
+      if (!sessionId || !codexClient.pinSessionCodexAccount) {
+        return false;
+      }
+      setPinningTarget(target);
+      const result = await mutation.run(async () => {
+        await codexClient.pinSessionCodexAccount!(workspaceId, sessionId, target);
+        return true;
+      });
+      setPinningTarget(null);
+      if (result) await state.refresh();
+      return result === true;
+    },
+    [codexClient, workspaceId, sessionId, mutation.run, state.refresh],
+  );
+
+  // Live usage refresh: hit the batched provider read, then re-read cached
+  // metadata so the fresh windows land on `accounts`. The provider read writes the
+  // cache columns server-side; state.refresh() pulls them back.
+  const refreshUsage = useCallback(
+    async (): Promise<boolean> => {
+      if (!codexClient.refreshCodexUsage) {
+        return false;
+      }
+      const result = await usageMutation.run(async () => {
+        await codexClient.refreshCodexUsage!(workspaceId);
+        return true;
+      });
+      if (result) await state.refresh();
+      return result === true;
+    },
+    [codexClient, workspaceId, usageMutation.run, state.refresh],
+  );
+
+  const data = state.data ?? EMPTY_STATE;
+  const effectiveAccountId = data.pinnedAccountId ?? data.activeAccountId;
+
+  return {
+    accounts: data.accounts,
+    activeAccountId: data.activeAccountId,
+    pinnedAccountId: data.pinnedAccountId,
+    effectiveAccountId,
+    lastAccountId: data.lastAccountId,
+    settings: data.settings,
+    loading: state.loading,
+    refresh: state.refresh,
+    refreshUsage,
+    refreshingUsage: usageMutation.mutating,
+    pin,
+    pinning: mutation.mutating,
+    pinningTarget,
+    mutationError: mutation.mutationError,
+  };
+}

package/src/hooks/use-desktop-stream.ts

@@ -7,17 +7,21 @@ import {
   type DesktopStreamCapability,
 } from "@opengeni/sdk";
 import { type RefObject, useEffect, useRef, useState } from "react";
+import { type DesktopWebSocketFactory, useRelayFrameStream } from "./use-relay-frame-stream";
 
 export type UseDesktopStreamOptions = {
   /** The desktop cell of the negotiated capabilities (`capabilities.DesktopStream`). */
   capability: DesktopStreamCapability | null;
-  /** The mount target. RFB attaches here on connect. */
+  /** The mount target. RFB (or the frame canvas) attaches here on connect. */
   containerRef: RefObject<HTMLDivElement | null>;
   /** Read-only by default (v1 ruling H). interactive only when cap.mode allows. */
   interactive?: boolean | undefined;
   scaleViewport?: boolean | undefined;
   /** Custom RFB factory (tests / a WebRTC swap). Defaults to a lazy @novnc/novnc. */
   rfbFactory?: DesktopRfbFactory | undefined;
+  /** Custom socket factory for the `relay-frames` transport (tests). Defaults to
+   *  `new WebSocket(url)`. Mirrors `rfbFactory` for the frame renderer. */
+  webSocketFactory?: DesktopWebSocketFactory | undefined;
 };
 
 export type UseDesktopStreamResult = {
@@ -57,9 +61,26 @@ async function defaultRfbFactory(): Promise<DesktopRfbFactory> {
  * `interactive` prop → `RFB.viewOnly`. v1 always resolves to read-only. On a
  * capability `url` change (a rotation), the old RFB disconnects and a fresh one
  * connects to the new URL — a brief "desktop blink", acceptable on rollover.
+ *
+ * Transport dispatch: a Modal box negotiates `transport: "vnc-ws"` and drives the
+ * noVNC RFB below. A SELF-HOSTED machine negotiates `transport: "relay-frames"`
+ * (PNG-per-frame over the relay, view-only) — that path is delegated to
+ * `useRelayFrameStream`, which paints a `<canvas>`. Both hooks are ALWAYS called
+ * (rules of hooks); each is dormant for the other's transport, and we return the
+ * result of whichever owns the surface. The public interface is identical either
+ * way, so `DesktopViewer` is transport-agnostic.
  */
 export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopStreamResult {
-  const { capability, containerRef, interactive, scaleViewport, rfbFactory } = options;
+  const { capability, containerRef, interactive, scaleViewport, rfbFactory, webSocketFactory } =
+    options;
+
+  // The self-hosted PNG-frame path. Always invoked (rules of hooks); dormant
+  // unless `transport === "relay-frames"`, in which case it owns the surface.
+  const frameStream = useRelayFrameStream({
+    capability,
+    containerRef,
+    ...(webSocketFactory ? { webSocketFactory } : {}),
+  });
   const [state, setState] = useState<DesktopConnectionState>("idle");
   const [error, setError] = useState<Error | null>(null);
   const [nonce, setNonce] = useState(0);
@@ -210,5 +231,10 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [scaleViewport, state]);
 
+  // Delegate to whichever transport owns the surface. For `relay-frames` the
+  // noVNC effect above is dormant (it bailed to idle) and the frame renderer
+  // drives; for `vnc-ws` (and everything else) the noVNC path drives while the
+  // frame renderer stays idle. Same public shape either way.
+  if (transport === "relay-frames") return frameStream;
   return { state, error, reconnect };
 }

package/src/hooks/use-goal.ts

@@ -42,6 +42,8 @@ export type UseGoalResult = {
 export function useGoal(sessionId: string | null | undefined, options: UseGoalOptions = {}): UseGoalResult {
   const { client, workspaceId } = useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
+  const sharedEvents = options.events;
+  const sharedFeed = sharedEvents !== undefined;
   const [goal, setGoal] = useState<SessionGoal | null>(null);
   const [loading, setLoading] = useState(enabled);
   const [error, setError] = useState<Error | null>(null);
@@ -87,6 +89,12 @@ export function useGoal(sessionId: string | null | undefined, options: UseGoalOp
       setLoading(false);
       return;
     }
+    if (sharedFeed) {
+      setLoading(false);
+      return () => {
+        generation.current += 1;
+      };
+    }
     setLoading(true);
     void load();
     const pollIntervalMs = options.pollIntervalMs;
@@ -100,12 +108,12 @@ export function useGoal(sessionId: string | null | undefined, options: UseGoalOp
       clearInterval(timer);
       generation.current += 1;
     };
-  }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs]);
+  }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs, sharedFeed]);
 
   const scheduleRefresh = useDebouncedCallback(() => void load());
   useSessionEventTrigger(client, workspaceId, sessionId, isGoalEvent, scheduleRefresh, {
     enabled,
-    ...(options.events !== undefined ? { events: options.events } : {}),
+    ...(sharedEvents !== undefined ? { events: sharedEvents } : {}),
   });
 
   const pause = useCallback(

package/src/hooks/use-machines.ts

@@ -0,0 +1,157 @@
+import { useCallback, useState } from "react";
+import { useOpenGeni, type ClientOverride } from "../provider";
+import { useMutationRunner, usePolledValue } from "./internal";
+import type { MachinesResponse, MachineView, MetricSample } from "../types/machines";
+
+/**
+ * The slice of the SDK client the Machines surface needs. The method NAMES +
+ * SIGNATURES match M10's `OpenGeniClient` (`listMachines`, `machineMetricsSeries`)
+ * so the real SDK client satisfies this surface DIRECTLY for the read paths — no
+ * adapter needed. It is declared structurally (not a hard `OpenGeniClient` Pick)
+ * so a test/demo/Geni-frontend client can stand in, keeping the hook dual-consumer
+ * safe (works in apps/web AND the separate Geni frontend).
+ *
+ * The active-sandbox SWAP is now a typed SDK call (`swapActiveSandbox`, the M7
+ * user-authenticated REST equivalent of the `sandbox_swap` MCP tool). The real
+ * SDK client satisfies it structurally, so the default attach path is wired
+ * WHENEVER a sessionId is in scope (the swap is session-scoped). `attachMachine`
+ * stays an OPTIONAL escape hatch for a host that wants to supply its own swap
+ * adapter; when neither it nor a sessionId is present, attach is a no-op and the
+ * card hides the button.
+ */
+export type MachinesClientLike = {
+  /** GET /v1/workspaces/:ws/machines — the dashboard list + active pointer. */
+  listMachines: (workspaceId: string, options?: { sessionId?: string }) => Promise<MachinesResponse>;
+  /** GET .../machines/:enrollmentId/metrics/series — the downsampled history. */
+  machineMetricsSeries?: (
+    workspaceId: string,
+    enrollmentId: string,
+    options?: { window?: "15m" | "1h" | "6h" | "24h" },
+  ) => Promise<MetricSample[]>;
+  /**
+   * POST .../sessions/:sessionId/active-sandbox — swap the session's active
+   * sandbox to a machine. The default swap path; the real SDK client provides it.
+   */
+  swapActiveSandbox?: (
+    workspaceId: string,
+    sessionId: string,
+    request: { target: string },
+  ) => Promise<unknown>;
+  /**
+   * Host-supplied swap adapter (an escape hatch). When present it wins over the
+   * default `swapActiveSandbox` path. Session-scoped, like the swap it backs.
+   */
+  attachMachine?: (workspaceId: string, sessionId: string, sandboxId: string) => Promise<unknown>;
+};
+
+export type UseMachinesOptions = ClientOverride & {
+  pollIntervalMs?: number | undefined;
+  enabled?: boolean | undefined;
+  /** Scope the list to a session (adds the synthetic Modal group box + pointer). */
+  sessionId?: string | undefined;
+  /**
+   * Override the client with one implementing `MachinesClientLike`. Defaults to
+   * the provider client cast to the surface (the real SDK client satisfies the
+   * read paths). An app supplies an adapter to wire `attachMachine` (the swap).
+   */
+  machinesClient?: MachinesClientLike | undefined;
+};
+
+export type UseMachinesResult = {
+  machines: MachineView[];
+  activeSandboxId: string | null;
+  activeEpoch: number;
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  /** Attach/swap the session's active sandbox to a machine (returns the new pointer). */
+  attach: (sandboxId: string) => Promise<boolean>;
+  /** Whether the host wired an attach/swap path (drives the card affordance). */
+  canAttach: boolean;
+  /** Fetch a downsampled metric series for one enrolled machine. */
+  fetchSeries: (enrollmentId: string, window?: "15m" | "1h" | "6h" | "24h") => Promise<MetricSample[]>;
+  attaching: boolean;
+  /** The sandbox id of the in-flight attach (for per-card spinner gating). */
+  attachingSandboxId: string | null;
+  mutationError: Error | null;
+  clearMutationError: () => void;
+};
+
+const EMPTY: MachinesResponse = { activeSandboxId: null, activeEpoch: 0, machines: [] };
+
+/**
+ * The workspace Machines fleet: the selfhosted enrollments + the session's Modal
+ * box, each with latest metrics + state, plus the active-sandbox pointer. Polls
+ * the M10 `GET /machines` endpoint and exposes attach/swap + a metric-series
+ * fetch. Renders via `<MachinesDashboard>`. Dual-consumer safe: it reads only the
+ * structural `MachinesClientLike` surface, so it works in apps/web AND the Geni
+ * frontend (each provides its own client/adapter).
+ */
+export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult {
+  const { client, workspaceId } = useOpenGeni(options);
+  const machinesClient = (options.machinesClient ?? (client as unknown as MachinesClientLike)) satisfies MachinesClientLike;
+  const sessionId = options.sessionId;
+
+  const load = useCallback(async () => {
+    return await machinesClient.listMachines(workspaceId, sessionId ? { sessionId } : undefined);
+  }, [machinesClient, workspaceId, sessionId]);
+
+  const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled: options.enabled });
+  const mutation = useMutationRunner();
+  // The sandbox id of the in-flight attach (drives the per-card spinner).
+  const [attachingSandboxId, setAttachingSandboxId] = useState<string | null>(null);
+
+  const data = state.data ?? EMPTY;
+  // The swap is session-scoped: a host adapter (`attachMachine`) wins; otherwise
+  // the default `swapActiveSandbox` path is wired whenever a sessionId is in
+  // scope. Either way attach needs a sessionId to point at.
+  const canAttach =
+    sessionId !== undefined &&
+    (typeof machinesClient.attachMachine === "function" ||
+      typeof machinesClient.swapActiveSandbox === "function");
+
+  const attach = useCallback(
+    async (sandboxId: string): Promise<boolean> => {
+      if (sessionId === undefined) return false;
+      const runSwap = machinesClient.attachMachine
+        ? () => machinesClient.attachMachine!(workspaceId, sessionId, sandboxId)
+        : machinesClient.swapActiveSandbox
+          ? () => machinesClient.swapActiveSandbox!(workspaceId, sessionId, { target: sandboxId })
+          : null;
+      if (!runSwap) return false;
+      setAttachingSandboxId(sandboxId);
+      const result = await mutation.run(async () => {
+        await runSwap();
+        return true;
+      });
+      setAttachingSandboxId(null);
+      if (result) await state.refresh();
+      return result === true;
+    },
+    [machinesClient, workspaceId, sessionId, mutation.run, state.refresh],
+  );
+
+  const fetchSeries = useCallback(
+    async (enrollmentId: string, window: "15m" | "1h" | "6h" | "24h" = "1h"): Promise<MetricSample[]> => {
+      if (!machinesClient.machineMetricsSeries) return [];
+      return await machinesClient.machineMetricsSeries(workspaceId, enrollmentId, { window });
+    },
+    [machinesClient, workspaceId],
+  );
+
+  return {
+    machines: data.machines,
+    activeSandboxId: data.activeSandboxId,
+    activeEpoch: data.activeEpoch,
+    loading: state.loading,
+    error: state.error,
+    refresh: state.refresh,
+    attach,
+    canAttach,
+    fetchSeries,
+    attaching: mutation.mutating,
+    attachingSandboxId,
+    mutationError: mutation.mutationError,
+    clearMutationError: mutation.clearMutationError,
+  };
+}