@opengeni/react 0.13.0 → 0.15.0

package/src/hooks/use-session.ts

@@ -1,5 +1,5 @@
 import type { Session, SessionEvent } from "@opengeni/sdk";
-import { useCallback, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
 import {
   useMutationRunner,
@@ -37,7 +37,8 @@ export function useSession(
   sessionId: string | null | undefined,
   options: UseSessionOptions = {},
 ): UseSessionResult {
-  const { client, workspaceId } = useOpenGeni(options);
+  const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
+    useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const [override, setOverride] = useState<Session | null>(null);
   const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
@@ -54,6 +55,13 @@ export function useSession(
     pollIntervalMs: options.pollIntervalMs,
     enabled,
   });
+  useEffect(() => {
+    if (enabled && workspaceControlEvent) void refresh();
+  }, [enabled, refresh, workspaceControlEvent]);
+  useEffect(() => {
+    if (!sessionId || !enabled) return;
+    return registerSessionReconciler(sessionId, "session", refresh);
+  }, [enabled, refresh, registerSessionReconciler, sessionId]);
 
   const base = data ?? null;
   // The override only ever carries title/titleSource patches; it is reset on

package/src/hooks/use-turn-queue.ts

@@ -1,14 +1,20 @@
-import type { SessionEvent, SessionQueueSnapshot, SessionTurn } from "@opengeni/sdk";
-import { useCallback, useEffect, useRef, useState } from "react";
+import type {
+  ComposerDraft,
+  EffectiveSessionControl,
+  SessionEvent,
+  SessionQueueMutationResponse,
+  SessionQueueSnapshot,
+  SessionTurn,
+} from "@opengeni/sdk";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
 import {
   useDebouncedCallback,
-  useMutationRunner,
   useSessionEventTrigger,
   type SessionEventFeedOptions,
 } from "./internal";
 
-/** Events that can change the authoritative prompt queue or its pause gates. */
+/** Events that can change the authoritative prompt queue or effective control. */
 export function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean {
   return (
     event.type.startsWith("turn.") ||
@@ -18,6 +24,8 @@ export function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean {
   );
 }
 
+export type QueueMutationKind = "move" | "edit" | "steer" | "delete";
+
 export type UseTurnQueueOptions = ClientOverride &
   SessionEventFeedOptions & {
     pollIntervalMs?: number | undefined;
@@ -27,68 +35,91 @@ export type UseTurnQueueResult = {
   snapshot: SessionQueueSnapshot | null;
   /** Human/API prompts exactly in server execution order. Never client-sorted. */
   queue: SessionTurn[];
-  controlState: SessionQueueSnapshot["controlState"] | null;
-  controlGeneration: number | null;
-  workspaceInferenceState: SessionQueueSnapshot["workspaceInferenceState"] | null;
-  workspaceInferenceGeneration: number | null;
-  workspaceRunExceptionGeneration: number | null;
+  effectiveControl: EffectiveSessionControl | null;
   loading: boolean;
   error: Error | null;
   refresh: () => Promise<void>;
-  /** Delete a waiting prompt before the worker claims it. */
+  moveTurn: (turnId: string, beforeTurnId: string | null) => Promise<boolean>;
+  /** Atomically withdraw a waiting prompt into the private durable composer draft. */
+  editTurn: (
+    turnId: string,
+    options: { expectedDraftRevision: number; replaceDraft: boolean },
+  ) => Promise<ComposerDraft | null>;
+  /** Advance the same durable waiting prompt; no duplicate prompt is created. */
+  steerTurn: (turnId: string) => Promise<boolean>;
   removeTurn: (turnId: string) => Promise<boolean>;
+  pendingByTurn: Readonly<Record<string, QueueMutationKind>>;
+  mutationFor: (turnId: string) => QueueMutationKind | null;
   mutating: boolean;
   mutationError: Error | null;
   clearMutationError: () => void;
 };
 
 /**
- * The single authoritative waiting-prompt queue. The server owns ordering; the
- * client renders the returned array verbatim and supports deletion only.
+ * The one authoritative human prompt queue. Every mutation carries the exact
+ * server versions the operator saw and accepts only monotonic snapshots. A
+ * conflict immediately reloads server truth; the client never invents order.
  */
 export function useTurnQueue(
   sessionId: string | null | undefined,
   options: UseTurnQueueOptions = {},
 ): UseTurnQueueResult {
-  const { client, workspaceId } = useOpenGeni(options);
+  const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
+    useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const [snapshot, setSnapshot] = useState<SessionQueueSnapshot | null>(null);
   const [loading, setLoading] = useState(enabled);
   const [error, setError] = useState<Error | null>(null);
-  const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
-  const generation = useRef(0);
+  const [mutationError, setMutationError] = useState<Error | null>(null);
+  const [pendingByTurn, setPendingByTurn] = useState<Record<string, QueueMutationKind>>({});
+  const pendingRef = useRef<Record<string, QueueMutationKind>>({});
+  const readGeneration = useRef(0);
   const targetKeyRef = useRef<string | null>(null);
   const snapshotRef = useRef<SessionQueueSnapshot | null>(null);
 
-  const replaceSnapshot = useCallback((next: SessionQueueSnapshot | null): void => {
+  const acceptSnapshot = useCallback((next: SessionQueueSnapshot | null): boolean => {
+    const current = snapshotRef.current;
+    if (
+      next &&
+      current &&
+      (next.version < current.version ||
+        next.effectiveControl.controlVersion < current.effectiveControl.controlVersion)
+    ) {
+      return false;
+    }
     snapshotRef.current = next;
     setSnapshot(next);
+    return true;
   }, []);
 
   const load = useCallback(async (): Promise<void> => {
     if (!sessionId) return;
-    const ticket = ++generation.current;
+    const ticket = ++readGeneration.current;
     try {
       const fetched = await client.getQueue(workspaceId, sessionId);
-      if (ticket === generation.current) {
-        replaceSnapshot(fetched);
+      if (ticket === readGeneration.current) {
+        acceptSnapshot(fetched);
         setError(null);
         setLoading(false);
       }
     } catch (cause) {
-      if (ticket === generation.current) {
-        setError(cause instanceof Error ? cause : new Error(String(cause)));
+      if (ticket === readGeneration.current) {
+        setError(asError(cause));
         setLoading(false);
       }
     }
-  }, [client, workspaceId, sessionId, replaceSnapshot]);
+  }, [client, workspaceId, sessionId, acceptSnapshot]);
 
   useEffect(() => {
     const targetKey = `${workspaceId}\u0000${sessionId ?? ""}`;
     if (targetKeyRef.current !== targetKey) {
       targetKeyRef.current = targetKey;
-      replaceSnapshot(null);
+      readGeneration.current += 1;
+      acceptSnapshot(null);
       setError(null);
+      setMutationError(null);
+      setPendingByTurn({});
+      pendingRef.current = {};
     }
     if (!enabled) {
       setLoading(false);
@@ -99,15 +130,23 @@ export function useTurnQueue(
     const pollIntervalMs = options.pollIntervalMs;
     if (pollIntervalMs === undefined || pollIntervalMs <= 0) {
       return () => {
-        generation.current += 1;
+        readGeneration.current += 1;
       };
     }
     const timer = setInterval(() => void load(), pollIntervalMs);
     return () => {
       clearInterval(timer);
-      generation.current += 1;
+      readGeneration.current += 1;
     };
-  }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs, replaceSnapshot]);
+  }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs, acceptSnapshot]);
+
+  useEffect(() => {
+    if (enabled && workspaceControlEvent) void load();
+  }, [enabled, load, workspaceControlEvent]);
+  useEffect(() => {
+    if (!sessionId || !enabled) return;
+    return registerSessionReconciler(sessionId, "queue", load);
+  }, [enabled, load, registerSessionReconciler, sessionId]);
 
   const scheduleRefresh = useDebouncedCallback(() => void load());
   useSessionEventTrigger(client, workspaceId, sessionId, isTurnQueueEvent, scheduleRefresh, {
@@ -115,42 +154,131 @@ export function useTurnQueue(
     ...(options.events !== undefined ? { events: options.events } : {}),
   });
 
-  const removeTurn = useCallback(
-    async (turnId: string): Promise<boolean> => {
-      if (!sessionId) return false;
+  const mutate = useCallback(
+    async (
+      turnId: string,
+      kind: QueueMutationKind,
+      command: (
+        current: SessionQueueSnapshot,
+        turn: SessionTurn,
+      ) => Promise<SessionQueueMutationResponse>,
+    ): Promise<SessionQueueMutationResponse | null> => {
+      if (!sessionId || pendingRef.current[turnId]) return null;
       const current = snapshotRef.current;
-      const item = current?.items.find((turn) => turn.id === turnId);
-      if (!current || !item) return false;
-      const result = await run(() =>
-        client.cancelQueueItem(workspaceId, sessionId, turnId, {
+      const turn = current?.items.find((candidate) => candidate.id === turnId);
+      if (!current || !turn) return null;
+      pendingRef.current = { ...pendingRef.current, [turnId]: kind };
+      setPendingByTurn(pendingRef.current);
+      setMutationError(null);
+      try {
+        const result = await command(current, turn);
+        acceptSnapshot(result.snapshot);
+        return result;
+      } catch (cause) {
+        setMutationError(asError(cause));
+        await load();
+        return null;
+      } finally {
+        if (turnId in pendingRef.current) {
+          const next = { ...pendingRef.current };
+          delete next[turnId];
+          pendingRef.current = next;
+          setPendingByTurn(next);
+        }
+      }
+    },
+    [acceptSnapshot, load, sessionId],
+  );
+
+  const moveTurn = useCallback(
+    async (turnId: string, beforeTurnId: string | null): Promise<boolean> => {
+      const result = await mutate(turnId, "move", (current) =>
+        client.moveQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
           expectedQueueVersion: current.version,
-          expectedItemVersion: item.version,
+          beforeTurnId,
         }),
       );
-      if (!result) {
-        void load();
-        return false;
-      }
-      replaceSnapshot(result.snapshot);
-      return true;
+      return result !== null;
+    },
+    [client, mutate, sessionId, workspaceId],
+  );
+
+  const editTurn = useCallback(
+    async (
+      turnId: string,
+      edit: { expectedDraftRevision: number; replaceDraft: boolean },
+    ): Promise<ComposerDraft | null> => {
+      const result = await mutate(turnId, "edit", (_current, turn) =>
+        client.editQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
+          expectedTurnVersion: turn.version,
+          expectedDraftRevision: edit.expectedDraftRevision,
+          replaceDraft: edit.replaceDraft,
+        }),
+      );
+      return result?.draft ?? null;
+    },
+    [client, mutate, sessionId, workspaceId],
+  );
+
+  const steerTurn = useCallback(
+    async (turnId: string): Promise<boolean> => {
+      const result = await mutate(turnId, "steer", (current, turn) =>
+        client.steerQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
+          expectedTurnVersion: turn.version,
+          controlEtag: current.effectiveControl.controlEtag,
+        }),
+      );
+      return result !== null;
+    },
+    [client, mutate, sessionId, workspaceId],
+  );
+
+  const removeTurn = useCallback(
+    async (turnId: string): Promise<boolean> => {
+      const result = await mutate(turnId, "delete", (_current, turn) =>
+        client.deleteQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
+          expectedTurnVersion: turn.version,
+          reason: "Deleted from the prompt queue",
+        }),
+      );
+      return result !== null;
     },
-    [client, workspaceId, sessionId, run, load, replaceSnapshot],
+    [client, mutate, sessionId, workspaceId],
+  );
+
+  const mutationFor = useCallback(
+    (turnId: string): QueueMutationKind | null => pendingByTurn[turnId] ?? null,
+    [pendingByTurn],
   );
+  const mutating = useMemo(() => Object.keys(pendingByTurn).length > 0, [pendingByTurn]);
 
   return {
     snapshot,
     queue: snapshot?.items ?? [],
-    controlState: snapshot?.controlState ?? null,
-    controlGeneration: snapshot?.controlGeneration ?? null,
-    workspaceInferenceState: snapshot?.workspaceInferenceState ?? null,
-    workspaceInferenceGeneration: snapshot?.workspaceInferenceGeneration ?? null,
-    workspaceRunExceptionGeneration: snapshot?.workspaceRunExceptionGeneration ?? null,
+    effectiveControl: snapshot?.effectiveControl ?? null,
     loading,
     error,
     refresh: load,
+    moveTurn,
+    editTurn,
+    steerTurn,
     removeTurn,
+    pendingByTurn,
+    mutationFor,
     mutating,
     mutationError,
-    clearMutationError,
+    clearMutationError: useCallback(() => setMutationError(null), []),
   };
 }
+
+function operationKey(): string {
+  return globalThis.crypto.randomUUID();
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}

package/src/index.ts

@@ -1,3 +1,6 @@
+// oxlint-disable-next-line typescript/triple-slash-reference -- package consumers must load the ambient type for this optional untyped peer without emitting a runtime import.
+/// <reference path="./types/external.d.ts" />
+
 // @opengeni/react — hooks + styled components on @opengeni/sdk.
 //
 // Import the styles once in your Tailwind entry CSS:
@@ -20,15 +23,11 @@ export type {
 export {
   useComposer,
   composeSendInput,
+  shouldSteerOnKey,
   shouldSubmitOnKey,
   FILE_ONLY_MESSAGE_TEXT,
 } from "./hooks/use-composer";
-export type {
-  ComposerMode,
-  ComposerSendExtras,
-  ComposerState,
-  UseComposerOptions,
-} from "./hooks/use-composer";
+export type { ComposerSendExtras, ComposerState, UseComposerOptions } from "./hooks/use-composer";
 export { useFileAttachments } from "./hooks/use-file-attachments";
 export type {
   FileAttachment,
@@ -36,7 +35,14 @@ export type {
   UseFileAttachmentsResult,
 } from "./hooks/use-file-attachments";
 export { useTurnQueue, isTurnQueueEvent } from "./hooks/use-turn-queue";
-export type { UseTurnQueueOptions, UseTurnQueueResult } from "./hooks/use-turn-queue";
+export type {
+  QueueMutationKind,
+  UseTurnQueueOptions,
+  UseTurnQueueResult,
+} from "./hooks/use-turn-queue";
+export { QueueSurface } from "./components/queue-surface";
+export type { QueueSurfaceProps } from "./components/queue-surface";
+export { OPEN_WORKSTREAM_CONTROL_EVENT } from "./components/chat-composer";
 export { useGoal, isGoalEvent } from "./hooks/use-goal";
 export type { UseGoalOptions, UseGoalResult } from "./hooks/use-goal";
 export { useSessionControl } from "./hooks/use-session-control";

package/src/machines.ts

@@ -34,6 +34,22 @@ export { MachineMetrics } from "./components/machine-metrics";
 export type { MachineMetricsProps } from "./components/machine-metrics";
 export { MachineCard } from "./components/machine-card";
 export type { MachineCardProps } from "./components/machine-card";
+export { MachineHealthPill } from "./components/machine-health-pill";
+export type { MachineHealthPillProps } from "./components/machine-health-pill";
+// Telemetry: fused health signal + history charts + the per-machine detail view.
+export { deriveHealth, HEALTH_TOKEN, healthPulses } from "./components/machines/health";
+export type { HealthLevel, HealthVerdict } from "./components/machines/health";
+export { MetricSparkline } from "./components/machines/metric-sparkline";
+export type { MetricSparklineProps } from "./components/machines/metric-sparkline";
+export { MetricHistoryChart } from "./components/machines/metric-history-chart";
+export type {
+  MetricHistoryChartProps,
+  SeriesPoint,
+} from "./components/machines/metric-history-chart";
+export { MachineDetail } from "./components/machines/machine-detail";
+export type { MachineDetailProps } from "./components/machines/machine-detail";
+export { METRICS, METRIC_WINDOWS, WINDOW_LABEL, pointsFor } from "./components/machines/series";
+export type { MetricDef, MetricKey, MetricWindow } from "./components/machines/series";
 export { MachinesDashboard } from "./components/machines-dashboard";
 export type { MachinesDashboardProps } from "./components/machines-dashboard";
 export { MachineDockBar, SharedMachineDisclosure } from "./components/machine-dock-bar";

package/src/provider.tsx

@@ -1,16 +1,44 @@
-import { createContext, useContext, useMemo, type ReactNode } from "react";
+import {
+  OpenGeniApiContractMismatchError,
+  OPENGENI_API_CONTRACT_REVISION,
+  type StreamConnectionState,
+  type WorkspaceControlEvent,
+} from "@opengeni/sdk";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import type { SessionClientLike } from "./client";
 
 export type OpenGeniContextValue = {
   client: SessionClientLike;
   workspaceId: string;
+  workspaceControlEvent: WorkspaceControlEvent | null;
+  workspaceControlConnectionState: StreamConnectionState | "idle" | "error";
+  registerSessionReconciler: (
+    sessionId: string,
+    key: string,
+    reconcile: () => Promise<void>,
+  ) => () => void;
+  reconcileSession: (sessionId: string) => Promise<void>;
 };
 
 const OpenGeniContext = createContext<OpenGeniContextValue | null>(null);
+const NOOP_REGISTER_RECONCILER: OpenGeniContextValue["registerSessionReconciler"] = () => () =>
+  undefined;
+const NOOP_RECONCILE_SESSION: OpenGeniContextValue["reconcileSession"] = async () => undefined;
+const CONTRACT_RELOAD_STORAGE_PREFIX = "opengeni.reloadForApiContract:";
 
 export type OpenGeniProviderProps = {
   client: SessionClientLike;
   workspaceId: string;
+  onWorkspaceControlEvent?: ((event: WorkspaceControlEvent) => void) | undefined;
   children?: ReactNode;
 };
 
@@ -18,9 +46,161 @@ export type OpenGeniProviderProps = {
  * Supplies the OpenGeni client + workspace to all hooks below it. Hooks also
  * accept `{ client, workspaceId }` overrides per call for multi-workspace UIs.
  */
-export function OpenGeniProvider({ client, workspaceId, children }: OpenGeniProviderProps) {
-  const value = useMemo(() => ({ client, workspaceId }), [client, workspaceId]);
-  return <OpenGeniContext.Provider value={value}>{children}</OpenGeniContext.Provider>;
+export function OpenGeniProvider({
+  client,
+  workspaceId,
+  onWorkspaceControlEvent,
+  children,
+}: OpenGeniProviderProps) {
+  const [workspaceControlEvent, setWorkspaceControlEvent] = useState<WorkspaceControlEvent | null>(
+    null,
+  );
+  const [workspaceControlConnectionState, setWorkspaceControlConnectionState] = useState<
+    StreamConnectionState | "idle" | "error"
+  >("idle");
+  const [contractMismatch, setContractMismatch] = useState<OpenGeniApiContractMismatchError | null>(
+    null,
+  );
+  const callbackRef = useRef(onWorkspaceControlEvent);
+  const reconcilersRef = useRef(new Map<string, Map<string, () => Promise<void>>>());
+  callbackRef.current = onWorkspaceControlEvent;
+
+  const verifyApiContract = useCallback(async (): Promise<void> => {
+    try {
+      const config = await client.getClientConfig();
+      if (config.apiContractRevision !== OPENGENI_API_CONTRACT_REVISION) {
+        throw new OpenGeniApiContractMismatchError(
+          OPENGENI_API_CONTRACT_REVISION,
+          String(config.apiContractRevision || "(missing)"),
+        );
+      }
+    } catch (error) {
+      if (error instanceof OpenGeniApiContractMismatchError) {
+        setContractMismatch(error);
+        reloadForContractMismatchOnce(error);
+      }
+      throw error;
+    }
+  }, [client]);
+
+  const registerSessionReconciler = useMemo(
+    () =>
+      (sessionId: string, key: string, reconcile: () => Promise<void>): (() => void) => {
+        const sessionReconcilers = reconcilersRef.current.get(sessionId) ?? new Map();
+        sessionReconcilers.set(key, reconcile);
+        reconcilersRef.current.set(sessionId, sessionReconcilers);
+        return () => {
+          const current = reconcilersRef.current.get(sessionId);
+          current?.delete(key);
+          if (current?.size === 0) reconcilersRef.current.delete(sessionId);
+        };
+      },
+    [],
+  );
+  const reconcileSession = useMemo(
+    () =>
+      async (sessionId: string): Promise<void> => {
+        // This read also crosses the exact API-contract handshake before stale
+        // state can be presented as live after a deployment.
+        await verifyApiContract();
+        const callbacks = [...(reconcilersRef.current.get(sessionId)?.values() ?? [])];
+        await Promise.all(callbacks.map((reconcile) => reconcile()));
+      },
+    [verifyApiContract],
+  );
+
+  useEffect(() => {
+    const controller = new AbortController();
+    setWorkspaceControlEvent(null);
+    setWorkspaceControlConnectionState("connecting");
+    void (async () => {
+      try {
+        await verifyApiContract();
+        const workspace = await client.getWorkspace(workspaceId);
+        const stream = client.streamWorkspaceControlEvents(workspaceId, {
+          after: workspace.inferenceControl.revision,
+          signal: controller.signal,
+          onStateChange: setWorkspaceControlConnectionState,
+        });
+        for await (const event of stream) {
+          if (controller.signal.aborted) return;
+          setWorkspaceControlEvent((current) =>
+            !current || event.sequence > current.sequence ? event : current,
+          );
+          callbackRef.current?.(event);
+        }
+      } catch (error) {
+        if (error instanceof OpenGeniApiContractMismatchError) {
+          setContractMismatch(error);
+          reloadForContractMismatchOnce(error);
+        }
+        if (!controller.signal.aborted) setWorkspaceControlConnectionState("error");
+      }
+    })();
+    return () => controller.abort();
+  }, [client, verifyApiContract, workspaceId]);
+
+  const value = useMemo(
+    () => ({
+      client,
+      workspaceId,
+      workspaceControlEvent,
+      workspaceControlConnectionState,
+      registerSessionReconciler,
+      reconcileSession,
+    }),
+    [
+      client,
+      workspaceId,
+      workspaceControlEvent,
+      workspaceControlConnectionState,
+      registerSessionReconciler,
+      reconcileSession,
+    ],
+  );
+  return (
+    <OpenGeniContext.Provider value={value}>
+      {children}
+      {contractMismatch ? <ApiContractMismatchScreen mismatch={contractMismatch} /> : null}
+    </OpenGeniContext.Provider>
+  );
+}
+
+function ApiContractMismatchScreen({ mismatch }: { mismatch: OpenGeniApiContractMismatchError }) {
+  return (
+    <div
+      className="og-root fixed inset-0 z-[2147483647] grid place-items-center bg-og-bg/95 p-6 backdrop-blur-sm"
+      role="alert"
+      aria-live="assertive"
+      data-opengeni-api-contract-mismatch
+    >
+      <div className="w-full max-w-md rounded-xl border border-og-border bg-og-surface p-6 shadow-2xl">
+        <p className="text-sm font-semibold text-og-fg">OpenGeni updated</p>
+        <p className="mt-2 text-sm leading-6 text-og-muted">
+          This tab cannot safely continue with the new server version. Reload it before sending or
+          controlling work.
+        </p>
+        <p className="mt-3 font-mono text-xs text-og-subtle">
+          Client {mismatch.expected} · API {mismatch.actual}
+        </p>
+        <button
+          type="button"
+          className="mt-5 inline-flex h-9 items-center rounded-md bg-og-fg px-3 text-sm font-medium text-og-bg"
+          onClick={() => window.location.reload()}
+        >
+          Reload now
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function reloadForContractMismatchOnce(mismatch: OpenGeniApiContractMismatchError): void {
+  if (typeof window === "undefined" || typeof sessionStorage === "undefined") return;
+  const key = `${CONTRACT_RELOAD_STORAGE_PREFIX}${mismatch.actual}`;
+  if (sessionStorage.getItem(key) === OPENGENI_API_CONTRACT_REVISION) return;
+  sessionStorage.setItem(key, OPENGENI_API_CONTRACT_REVISION);
+  window.setTimeout(() => window.location.reload(), 150);
 }
 
 export type ClientOverride = {
@@ -38,7 +218,14 @@ export function useOpenGeni(override: ClientOverride = {}): OpenGeniContextValue
       "@opengeni/react: no OpenGeni client/workspace available. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId } to the hook.",
     );
   }
-  return { client, workspaceId };
+  return {
+    client,
+    workspaceId,
+    workspaceControlEvent: context?.workspaceControlEvent ?? null,
+    workspaceControlConnectionState: context?.workspaceControlConnectionState ?? "idle",
+    registerSessionReconciler: context?.registerSessionReconciler ?? NOOP_REGISTER_RECONCILER,
+    reconcileSession: context?.reconcileSession ?? NOOP_RECONCILE_SESSION,
+  };
 }
 
 /**