@opengeni/react 0.57.0 → 1.0.2-canary.37191796234001

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

@@ -11,12 +11,16 @@ export type UseSessionLineageOptions = EmbeddedSessionLineageClientOverride & {
   /** Refresh interval (ms). Off by default. */
   pollIntervalMs?: number | undefined;
   enabled?: boolean | undefined;
+  /** Optional shared causal clock invoked when each network read starts. */
+  beginRead?: (() => number) | undefined;
 };
 
 export type UseSessionLineageResult = {
   lineage: SessionLineageResponse | null;
   loading: boolean;
   error: Error | null;
+  /** Causal generation captured when the accepted lineage read started. */
+  readGeneration: number;
   refresh: () => Promise<void>;
 };
 
@@ -63,12 +67,29 @@ export function useSessionLineage(
   const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
     useEmbeddedSessionLineage(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
+  const nextReadGeneration = useRef(0);
+  const beginRead = options.beginRead;
   const load = useCallback(
-    async () =>
-      sessionId
-        ? await client.getSessionLineage(workspaceId, sessionId)
-        : { ancestors: [], children: [], truncated: false },
-    [client, workspaceId, sessionId],
+    async (signal?: AbortSignal) => {
+      if (!sessionId) {
+        return {
+          lineage: { ancestors: [], children: [], truncated: false },
+          readGeneration: 0,
+        };
+      }
+      let readGeneration = 0;
+      const lineage = await client.getSessionLineage(workspaceId, sessionId, {
+        signal,
+        onRequestStart: (sharedReadGeneration) => {
+          readGeneration = sharedReadGeneration ?? beginRead?.() ?? ++nextReadGeneration.current;
+        },
+      });
+      return {
+        lineage,
+        readGeneration,
+      };
+    },
+    [beginRead, client, workspaceId, sessionId],
   );
   const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled });
   const refresh = state.refresh;
@@ -123,9 +144,10 @@ export function useSessionLineage(
     { events: options.events, enabled: enabled && options.events !== undefined },
   );
   return {
-    lineage: state.data,
+    lineage: state.data?.lineage ?? null,
     loading: state.loading,
     error: state.error,
+    readGeneration: state.data?.readGeneration ?? 0,
     refresh,
   };
 }

package/src/hooks/use-session-mcp-approval-policy.ts

@@ -1,7 +1,7 @@
 import type {
   SessionEvent,
   SessionMcpApprovalPolicy,
-  SessionMcpServerMetadata,
+  SessionMcpApprovalPolicyTarget,
   UpdateSessionMcpApprovalPolicyResponse,
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
@@ -38,7 +38,7 @@ export type UseSessionMcpApprovalPolicyOptions = EmbeddedSessionMcpApprovalPolic
   };
 
 export type UseSessionMcpApprovalPolicyResult = {
-  server: SessionMcpServerMetadata | null;
+  server: SessionMcpApprovalPolicyTarget | null;
   policy: SessionMcpApprovalPolicy | null;
   loading: boolean;
   error: Error | null;
@@ -61,7 +61,7 @@ export function useSessionMcpApprovalPolicy(
 ): UseSessionMcpApprovalPolicyResult {
   const { client, workspaceId } = useEmbeddedSessionMcpApprovalPolicy(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId && serverId);
-  const [override, setOverride] = useState<SessionMcpServerMetadata | null>(null);
+  const [override, setOverride] = useState<SessionMcpApprovalPolicyTarget | null>(null);
   const targetKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${serverId ?? ""}`;
   const authoritativeGeneration = useRef(0);
   const mutationIdentity = useMemo(() => ({ client, targetKey }), [client, targetKey]);
@@ -75,7 +75,7 @@ export function useSessionMcpApprovalPolicy(
   type PolicyRead = {
     targetKey: string;
     generation: number;
-    server: SessionMcpServerMetadata | null;
+    server: SessionMcpApprovalPolicyTarget | null;
   };
   const load = useCallback(async (): Promise<PolicyRead> => {
     const generation = authoritativeGeneration.current;
@@ -86,7 +86,15 @@ export function useSessionMcpApprovalPolicy(
     return {
       targetKey,
       generation,
-      server: session.mcpServers.find((server) => server.id === serverId) ?? null,
+      server:
+        session.mcpServers.find((server) => server.id === serverId) ??
+        (session.mcpApprovalPolicies && Object.hasOwn(session.mcpApprovalPolicies, serverId)
+          ? {
+              id: serverId,
+              source: "workspace",
+              requireApproval: session.mcpApprovalPolicies[serverId]!,
+            }
+          : null),
     };
   }, [client, serverId, sessionId, targetKey, workspaceId]);
   const {

package/src/hooks/use-session.ts

@@ -1,5 +1,5 @@
 import type { Session, SessionEvent } from "@opengeni/sdk";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useEmbeddedSessionRead, type EmbeddedSessionReadClientOverride } from "../session-context";
 import {
   useMutationRunner,
@@ -12,12 +12,18 @@ export type UseSessionOptions = EmbeddedSessionReadClientOverride &
   SessionEventFeedOptions & {
     /** Re-fetch on an interval (ms). Off by default — pair with `useSessionEvents` for live status. */
     pollIntervalMs?: number | undefined;
+    /** Optional shared causal clock invoked when each network read starts. */
+    beginRead?: (() => number) | undefined;
   };
 
 export type UseSessionResult = {
   session: Session | null;
   loading: boolean;
   error: Error | null;
+  /** Monotonic revision of accepted authoritative detail reads. */
+  readRevision: number;
+  /** Causal generation captured when the accepted network read started. */
+  readGeneration: number;
   refresh: () => Promise<void>;
   /** Manually rename the session (PATCH, source='user'). Returns the updated session, or null on failure. */
   updateTitle: (title: string) => Promise<Session | null>;
@@ -32,6 +38,16 @@ export function isTitleEvent(event: Pick<SessionEvent, "type">): boolean {
   return event.type === "session.title_set";
 }
 
+function isSessionDetailEvent(event: Pick<SessionEvent, "type">): boolean {
+  return (
+    isTitleEvent(event) ||
+    event.type.startsWith("session.command.") ||
+    event.type.startsWith("session.wait.") ||
+    event.type === "session.status.changed" ||
+    event.type === "system.update.pending"
+  );
+}
+
 /** Fetch one session (with optional polling), live-patching its title on `session.title_set`. */
 export function useSession(
   sessionId: string | null | undefined,
@@ -41,16 +57,33 @@ export function useSession(
     useEmbeddedSessionRead(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const [override, setOverride] = useState<Session | null>(null);
+  const nextReadRevision = useRef(0);
+  const nextReadGeneration = useRef(0);
+  const beginRead = options.beginRead;
   const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
-  const load = useCallback(async () => {
-    if (!sessionId) {
-      return null;
-    }
-    const fetched = await client.getSession(workspaceId, sessionId);
-    // A fresh server read supersedes any optimistic/event-driven override.
-    setOverride(null);
-    return fetched;
-  }, [client, workspaceId, sessionId]);
+  const load = useCallback(
+    async (signal?: AbortSignal) => {
+      if (!sessionId) {
+        return null;
+      }
+      let readGeneration = 0;
+      const fetched = await client.getSession(workspaceId, sessionId, {
+        fresh: true,
+        signal,
+        onRequestStart: () => {
+          readGeneration = beginRead?.() ?? ++nextReadGeneration.current;
+        },
+      });
+      // A fresh server read supersedes any optimistic/event-driven override.
+      setOverride(null);
+      return {
+        session: fetched,
+        revision: ++nextReadRevision.current,
+        readGeneration,
+      };
+    },
+    [beginRead, client, workspaceId, sessionId],
+  );
   const { data, loading, error, refresh } = usePolledValue(load, {
     pollIntervalMs: options.pollIntervalMs,
     enabled,
@@ -63,7 +96,9 @@ export function useSession(
     return registerSessionReconciler(sessionId, "session", refresh);
   }, [enabled, refresh, registerSessionReconciler, sessionId]);
 
-  const base = data ?? null;
+  const base = data?.session ?? null;
+  const readRevision = data?.revision ?? 0;
+  const readGeneration = data?.readGeneration ?? 0;
   // The override only ever carries title/titleSource patches; it is reset on
   // every fresh load so it can never go stale against the server snapshot.
   const session = useMemo(
@@ -74,10 +109,35 @@ export function useSession(
     [base, override],
   );
 
+  const sharedEvents = options.events;
+
   // Live-patch the title on auto (agent) + cross-client (user/agent) renames so
   // the UI reflects the new title without polling or a full re-fetch.
   const onTitleEvent = useCallback(
     (event: SessionEvent) => {
+      // Reconciliation emits only the last matching member of a shared batch.
+      // A later title must not hide an earlier command activity change.
+      if (
+        sharedEvents?.some(
+          (item) =>
+            item.sessionId === sessionId &&
+            !isTitleEvent(item) &&
+            isSessionDetailEvent(item) &&
+            item.sequence > (base?.lastSequence ?? -1),
+        )
+      ) {
+        void refresh();
+      } else if (!isTitleEvent(event)) {
+        if (!base || event.sequence > base.lastSequence) void refresh();
+        return;
+      }
+      // The fetched session row is the authoritative title projection through
+      // lastSequence. Shared feeds may replay that historical tail after the
+      // fetch; applying it would undo a row-only migration quarantine. Only an
+      // event committed after this snapshot may live-patch the title.
+      if (!base || event.sequence <= base.lastSequence) {
+        return;
+      }
       const payload = (event.payload ?? {}) as { title?: unknown; source?: unknown };
       const title = payload.title;
       if (typeof title !== "string") {
@@ -87,15 +147,12 @@ export function useSession(
         payload.source === "user" || payload.source === "agent" ? payload.source : null;
       setOverride((current): Session | null => {
         const next = current ?? base;
-        if (!next) {
-          return current;
-        }
         return { ...next, title, titleSource: source };
       });
     },
-    [base],
+    [base, refresh, sharedEvents, sessionId],
   );
-  useSessionEventTrigger(client, workspaceId, sessionId, isTitleEvent, onTitleEvent, {
+  useSessionEventTrigger(client, workspaceId, sessionId, isSessionDetailEvent, onTitleEvent, {
     enabled,
     ...(options.events !== undefined ? { events: options.events } : {}),
   });
@@ -118,6 +175,8 @@ export function useSession(
     session,
     loading,
     error,
+    readRevision,
+    readGeneration,
     refresh,
     updateTitle,
     updating: mutating,

package/src/hooks/use-slash-commands.ts

@@ -1,5 +1,6 @@
 import type { KeyboardEvent } from "react";
 import { useCallback, useMemo, useRef, useState } from "react";
+import { useErrorMessage } from "../lib/error-message";
 import {
   argHint,
   filterCommands,
@@ -81,6 +82,7 @@ export type UseSlashCommandsResult = {
 };
 
 export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashCommandsResult {
+  const formatError = useErrorMessage();
   const { commands, context, handlers, value, setValue } = options;
   const [highlight, setHighlight] = useState(0);
   // Escape closes the palette but keeps the draft. We remember the dismissed
@@ -153,9 +155,9 @@ export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashComm
       if (!context) {
         return null;
       }
-      return { ...context, ...handlers, confirm: () => handlers.confirm(command) };
+      return { ...context, ...handlers, formatError, confirm: () => handlers.confirm(command) };
     },
-    [context, handlers],
+    [context, handlers, formatError],
   );
 
   const execute = useCallback(
@@ -173,10 +175,10 @@ export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashComm
           setValue("");
         }
       } catch (cause) {
-        ctx.notice({ tone: "error", message: errorMessage(cause) });
+        ctx.notice({ tone: "error", message: formatError(cause) });
       }
     },
-    [buildContext, setValue],
+    [buildContext, setValue, formatError],
   );
 
   const autocomplete = useCallback(
@@ -359,10 +361,3 @@ export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashComm
     autocompleteHighlighted,
   };
 }
-
-function errorMessage(cause: unknown): string {
-  if (cause instanceof Error) {
-    return cause.message;
-  }
-  return String(cause);
-}

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

@@ -10,6 +10,7 @@ import type {
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { useEmbeddedSession, type EmbeddedSessionClientOverride } from "../session-context";
+import { normalizeError } from "../lib/error-message";
 import {
   useDebouncedCallback,
   usePageLiveActivity,
@@ -42,6 +43,17 @@ function queueSnapshotCovers(
 export type QueueMutationKind = "move" | "edit" | "steer" | "delete";
 const EMPTY_PENDING_BY_TURN: Readonly<Record<string, QueueMutationKind>> = {};
 
+export type AcceptedQueueSteer = {
+  turnId: string;
+  triggerEventId: string;
+  text: string;
+  annotations: SessionTurn["annotations"];
+  resources: SessionTurn["resources"];
+  tools: SessionTurn["tools"];
+  occurredAt: string;
+  state: "sending" | "queued";
+};
+
 export type UseTurnQueueOptions = EmbeddedSessionClientOverride &
   SessionEventFeedOptions & {
     pollIntervalMs?: number | undefined;
@@ -77,6 +89,8 @@ export type UseTurnQueueResult = {
   mutating: boolean;
   mutationError: Error | null;
   clearMutationError: () => void;
+  /** Immediate chat bridge while the durable Steer event catches up over SSE. */
+  acceptedSteers?: AcceptedQueueSteer[] | undefined;
 };
 
 /**
@@ -99,6 +113,7 @@ export function useTurnQueue(
   const [error, setError] = useState<Error | null>(null);
   const [mutationError, setMutationError] = useState<Error | null>(null);
   const [pendingByTurn, setPendingByTurn] = useState<Record<string, QueueMutationKind>>({});
+  const [acceptedSteers, setAcceptedSteers] = useState<AcceptedQueueSteer[]>([]);
   const pendingRef = useRef<Record<string, QueueMutationKind>>({});
   const readGeneration = useRef(0);
   const targetKeyRef = useRef(targetKey);
@@ -118,8 +133,26 @@ export function useTurnQueue(
     setError(null);
     setMutationError(null);
     setPendingByTurn({});
+    setAcceptedSteers([]);
   }, [enabled, targetKey]);
 
+  useEffect(() => {
+    if (acceptedSteers.length === 0 || options.events === undefined) return;
+    const durablyStartedTurnIds = new Set(
+      options.events.flatMap((event) =>
+        event.type === "turn.started" && event.turnId ? [event.turnId] : [],
+      ),
+    );
+    if (durablyStartedTurnIds.size === 0) return;
+    // steer_requested can reach the browser before the timeline projection
+    // that moves the queued user.message into chat. Keep this bridge through
+    // physical cancellation; turn.started is the first boundary at which the
+    // replacement timeline must already be visible.
+    setAcceptedSteers((current) =>
+      current.filter((steer) => !durablyStartedTurnIds.has(steer.turnId)),
+    );
+  }, [acceptedSteers.length, options.events]);
+
   const acceptSnapshot = useCallback(
     (ownedTargetKey: string, next: SessionQueueSnapshot | null): boolean => {
       if (targetKeyRef.current !== ownedTargetKey) return false;
@@ -234,6 +267,7 @@ export function useTurnQueue(
       command: (
         current: SessionQueueSnapshot,
         turn: SessionTurn,
+        clientEventId: string,
       ) => Promise<SessionQueueMutationResponse>,
     ): Promise<SessionQueueMutationResponse | null> => {
       const ownedTargetKey = targetKey;
@@ -247,8 +281,17 @@ export function useTurnQueue(
       setStateTargetKey(ownedTargetKey);
       setPendingByTurn(pendingRef.current);
       setMutationError(null);
+      const clientEventId = operationKey();
       try {
-        const result = await command(current, turn);
+        let result: SessionQueueMutationResponse;
+        try {
+          result = await command(current, turn, clientEventId);
+        } catch (cause) {
+          if (!isOutcomeUnknownError(cause)) throw cause;
+          // Same-key replay is a fact check against the durable receipt. It
+          // cannot duplicate the command even if the first response was lost.
+          result = await command(current, turn, clientEventId);
+        }
         if (targetKeyRef.current !== ownedTargetKey) return null;
         acceptSnapshot(ownedTargetKey, result.snapshot);
         return result;
@@ -272,9 +315,9 @@ export function useTurnQueue(
 
   const moveTurn = useCallback(
     async (turnId: string, beforeTurnId: string | null): Promise<boolean> => {
-      const result = await mutate(turnId, "move", (current) =>
+      const result = await mutate(turnId, "move", (current, _turn, clientEventId) =>
         client.moveQueueItem(workspaceId, sessionId!, turnId, {
-          clientEventId: operationKey(),
+          clientEventId,
           expectedQueueVersion: current.version,
           beforeTurnId,
         }),
@@ -289,9 +332,9 @@ export function useTurnQueue(
       turnId: string,
       edit: { expectedDraftRevision: number; replaceDraft: boolean },
     ): Promise<ComposerDraft | null> => {
-      const result = await mutate(turnId, "edit", (_current, turn) =>
+      const result = await mutate(turnId, "edit", (_current, turn, clientEventId) =>
         client.editQueueItem(workspaceId, sessionId!, turnId, {
-          clientEventId: operationKey(),
+          clientEventId,
           expectedTurnVersion: turn.version,
           expectedDraftRevision: edit.expectedDraftRevision,
           replaceDraft: edit.replaceDraft,
@@ -304,23 +347,71 @@ export function useTurnQueue(
 
   const steerTurn = useCallback(
     async (turnId: string): Promise<boolean> => {
-      const result = await mutate(turnId, "steer", (current, turn) =>
+      const ownedTargetKey = targetKey;
+      const turn = snapshotRef.current?.items.find((candidate) => candidate.id === turnId);
+      if (targetKeyRef.current !== ownedTargetKey) return false;
+      if (!turn) {
+        setMutationError(new Error("That queued prompt changed before Steer could be sent."));
+        await load();
+        return false;
+      }
+      const optimistic: AcceptedQueueSteer = {
+        turnId: turn.id,
+        triggerEventId: turn.triggerEventId,
+        text: turn.prompt,
+        annotations: turn.annotations ?? [],
+        resources: turn.resources,
+        tools: turn.tools,
+        occurredAt: new Date().toISOString(),
+        state: "sending",
+      };
+      setAcceptedSteers((current) => [
+        ...current.filter((steer) => steer.turnId !== turnId),
+        optimistic,
+      ]);
+      const result = await mutate(turnId, "steer", (current, queuedTurn, clientEventId) =>
         client.steerQueueItem(workspaceId, sessionId!, turnId, {
-          clientEventId: operationKey(),
-          expectedTurnVersion: turn.version,
+          clientEventId,
+          expectedTurnVersion: queuedTurn.version,
           controlEtag: current.effectiveControl.controlEtag,
         }),
       );
-      return result !== null;
+      if (targetKeyRef.current !== ownedTargetKey) return false;
+      // The active turn can finish while the operator clicks Steer. In that
+      // race the queued prompt is atomically claimed before the steer command,
+      // so the command conflicts but the user's prompt already advanced into
+      // chat. Reconciled absence is success, not a scary unknown-outcome lie.
+      const advancedWithoutSteer =
+        result === null &&
+        snapshotRef.current !== null &&
+        !snapshotRef.current.items.some((candidate) => candidate.id === turnId);
+      if (advancedWithoutSteer) {
+        setMutationError(null);
+        setAcceptedSteers((current) => current.filter((steer) => steer.turnId !== turnId));
+        return true;
+      }
+      const accepted =
+        result !== null ||
+        snapshotRef.current?.items.some(
+          (candidate) => candidate.id === turnId && candidate.metadata.delivery === "steer",
+        ) === true;
+      setAcceptedSteers((current) =>
+        accepted
+          ? current.map((steer) =>
+              steer.turnId === turnId ? { ...steer, state: "queued" as const } : steer,
+            )
+          : current.filter((steer) => steer.turnId !== turnId),
+      );
+      return accepted;
     },
-    [client, mutate, sessionId, workspaceId],
+    [client, load, mutate, sessionId, targetKey, workspaceId],
   );
 
   const removeTurn = useCallback(
     async (turnId: string): Promise<boolean> => {
-      const result = await mutate(turnId, "delete", (_current, turn) =>
+      const result = await mutate(turnId, "delete", (_current, turn, clientEventId) =>
         client.deleteQueueItem(workspaceId, sessionId!, turnId, {
-          clientEventId: operationKey(),
+          clientEventId,
           expectedTurnVersion: turn.version,
           reason: "Deleted from the prompt queue",
         }),
@@ -364,6 +455,7 @@ export function useTurnQueue(
     clearMutationError: useCallback(() => {
       if (targetKeyRef.current === targetKey) setMutationError(null);
     }, [targetKey]),
+    acceptedSteers: identityMatches ? acceptedSteers : [],
   };
 }
 
@@ -372,5 +464,13 @@ function operationKey(): string {
 }
 
 function asError(cause: unknown): Error {
-  return cause instanceof Error ? cause : new Error(String(cause));
+  return normalizeError(cause);
+}
+
+function isOutcomeUnknownError(cause: unknown): boolean {
+  return (
+    typeof cause === "object" &&
+    cause !== null &&
+    (cause as { outcomeUnknown?: unknown }).outcomeUnknown === true
+  );
 }

package/src/hooks/use-usage.ts

@@ -0,0 +1,100 @@
+import type { OpenGeniClient } from "@opengeni/sdk";
+import {
+  getMyUsage,
+  type UsageAllowancePeriod,
+  type WorkspaceUsageResponse,
+} from "@opengeni/sdk/usage-allowances";
+import { useCallback, useContext, useEffect, useMemo, useRef } from "react";
+
+import { OpenGeniContext } from "../session-context";
+import { summarizeUsage, type UsageSummary } from "../usage/summary";
+import { usePolledValue } from "./internal";
+
+/**
+ * Anything that can read the signed-in member's own usage: the root SDK client
+ * pointed at your session proxy (`getMyUsage`), or any client exposing
+ * `requestJson` (for example the narrower browser client).
+ */
+export type UsageClientLike =
+  | Pick<OpenGeniClient, "getMyUsage">
+  | Pick<OpenGeniClient, "requestJson">;
+
+export type UseUsageOptions = {
+  /** Defaults to the `<OpenGeniProvider>` client. */
+  client?: UsageClientLike | undefined;
+  /** Defaults to the `<OpenGeniProvider>` workspace. */
+  workspaceId?: string | undefined;
+  /** `"current"` (default) or a `YYYY-MM` allowance period. */
+  period?: UsageAllowancePeriod | undefined;
+  /** Re-read on an interval. Off by default; usage changes only when work settles. */
+  pollIntervalMs?: number | undefined;
+  enabled?: boolean | undefined;
+  /**
+   * Re-read whenever this value changes, keeping the current reading while it
+   * loads. Pass something that changes when work settles (a turn count, the
+   * session status) so the meter follows real usage without polling.
+   */
+  refreshKey?: unknown;
+};
+
+export type UseUsageResult = {
+  /** The raw `/usage/me` response: the workspace pool and your own row. */
+  usage: WorkspaceUsageResponse | null;
+  /** What to tell this member; null until loaded. */
+  summary: UsageSummary | null;
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+};
+
+function readOwnUsage(
+  client: UsageClientLike,
+  workspaceId: string,
+  period: UsageAllowancePeriod | undefined,
+  signal: AbortSignal | undefined,
+): Promise<WorkspaceUsageResponse> {
+  const query = period === undefined ? {} : { period };
+  const options = signal ? { signal } : {};
+  if ("getMyUsage" in client && typeof client.getMyUsage === "function") {
+    return client.getMyUsage(workspaceId, query, options);
+  }
+  if ("requestJson" in client && typeof client.requestJson === "function") {
+    return getMyUsage(client, workspaceId, query, options);
+  }
+  throw new Error("@opengeni/react: the usage client needs getMyUsage or requestJson.");
+}
+
+/**
+ * The signed-in member's own usage in one workspace, read through `/usage/me`
+ * (the session proxy serves exactly this route). Never reads another member.
+ */
+export function useUsage(options: UseUsageOptions = {}): UseUsageResult {
+  const context = useContext(OpenGeniContext);
+  const client = (options.client ?? context?.client) as UsageClientLike | undefined;
+  const workspaceId = options.workspaceId ?? context?.workspaceId;
+  if (!client || !workspaceId) {
+    throw new Error(
+      "@opengeni/react: useUsage needs a client and workspace. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId }.",
+    );
+  }
+  const period = options.period;
+  const load = useCallback(
+    (signal?: AbortSignal) => readOwnUsage(client, workspaceId, period, signal),
+    [client, workspaceId, period],
+  );
+  const state = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  const refreshKey = options.refreshKey;
+  const seenKey = useRef(refreshKey);
+  const refresh = state.refresh;
+  useEffect(() => {
+    if (Object.is(seenKey.current, refreshKey)) return;
+    seenKey.current = refreshKey;
+    void refresh();
+  }, [refreshKey, refresh]);
+  const usage = state.data;
+  const summary = useMemo(() => (usage ? summarizeUsage(usage) : null), [usage]);
+  return { usage, summary, loading: state.loading, error: state.error, refresh };
+}