@opengeni/react 0.1.0

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

@@ -0,0 +1,366 @@
+import type { KeyboardEvent } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
+import {
+  argHint,
+  filterCommands,
+  firstMissingRequiredArg,
+  matchCommand,
+  parseCommandLine,
+} from "../commands/registry";
+import type { CommandContext, Notice, SlashCommand } from "../commands/types";
+
+/**
+ * Context the composer supplies for command execution and visibility. The
+ * composer owns the UI affordances (notice/openHelp/clearView/confirm), so they
+ * are NOT part of this slice — the hook closes over them via `handlers`.
+ */
+export type SlashCommandContext = Pick<
+  CommandContext,
+  "client" | "workspaceId" | "sessionId" | "status" | "permissions"
+>;
+
+/**
+ * UI affordances the composer supplies. `confirm` differs from the registry-
+ * facing {@link CommandContext.confirm} (which takes no args): the composer's
+ * confirm receives the command being run so the confirm bar renders from that
+ * exact command's identity. The hook bridges the two in {@link buildContext}.
+ */
+export type SlashCommandHandlers = Pick<CommandContext, "notice" | "openHelp" | "clearView"> & {
+  confirm: (command: SlashCommand) => Promise<boolean>;
+};
+
+export type ConfirmState = {
+  command: SlashCommand;
+  /** Resolve the pending confirm() promise. */
+  resolve: (confirmed: boolean) => void;
+} | null;
+
+export type UseSlashCommandsOptions = {
+  commands: readonly SlashCommand[];
+  context: SlashCommandContext | undefined;
+  handlers: SlashCommandHandlers;
+  /** The current composer draft. */
+  value: string;
+  /** Replace the composer draft (autocomplete writes through this). */
+  setValue: (value: string) => void;
+};
+
+export type UseSlashCommandsResult = {
+  /** Whether the palette is open (a command token is being typed). */
+  open: boolean;
+  /**
+   * Whether the draft is a slash-command attempt (matches a registered command)
+   * — true even after Escape dismisses the popover. The composer blocks its send
+   * path while this holds so a command can't be delivered to the agent as chat.
+   */
+  isCommandDraft: boolean;
+  /** Commands shown for the current token + context, in display order. */
+  items: SlashCommand[];
+  /** Index into `items` of the highlighted row. */
+  highlight: number;
+  setHighlight: (index: number) => void;
+  /** The matched command once the name is closed by a space (arg-hint mode). */
+  activeCommand: SlashCommand | null;
+  /** The arg hint string for the active command (footer), or "". */
+  activeArgHint: string;
+  /**
+   * Key handler for the textarea. Returns true when it consumed the event
+   * (the composer must then NOT run its send path). Only consumes while open.
+   */
+  onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => boolean;
+  /** Run the highlighted command (or the active command in arg-hint mode). */
+  runHighlighted: () => Promise<void>;
+  /**
+   * Run the command at an explicitly chosen index (a pointer click on a row).
+   * Bypasses the exact-match token heuristic that runHighlighted uses for
+   * keyboard Enter, so an explicit click always runs the clicked command.
+   */
+  runAt: (index: number) => Promise<void>;
+  /** Autocomplete the highlighted command name + a trailing space. */
+  autocompleteHighlighted: () => void;
+};
+
+export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashCommandsResult {
+  const { commands, context, handlers, value, setValue } = options;
+  const [highlight, setHighlight] = useState(0);
+  // Escape closes the palette but keeps the draft. We remember the dismissed
+  // value; any further edit (value !== dismissed) re-opens the palette.
+  const [dismissedValue, setDismissedValue] = useState<string | null>(null);
+  const dismissed = dismissedValue !== null && dismissedValue === value;
+
+  // Whether the operator has explicitly arrow-navigated the highlight for the
+  // CURRENT draft. When they have, Enter is an explicit choice of the
+  // highlighted row — the exact-match token override must NOT hijack it (else
+  // ArrowDown to /clear-view + Enter would still fire the destructive /clear,
+  // since "clear" exact-matches the token). Reset whenever the draft changes.
+  const navigatedRef = useRef(false);
+  const navTokenRef = useRef(value);
+  if (navTokenRef.current !== value) {
+    navTokenRef.current = value;
+    navigatedRef.current = false;
+  }
+
+  const parsed = useMemo(() => parseCommandLine(value), [value]);
+  const filterCtx = useMemo(
+    () => ({
+      sessionId: context?.sessionId ?? null,
+      status: context?.status ?? null,
+      permissions: context?.permissions ?? [],
+    }),
+    [context?.sessionId, context?.status, context?.permissions],
+  );
+
+  // In arg-hint mode ("/name "), the list collapses to the matched command so
+  // the palette shows just its arg hint; while typing the name it filters.
+  const activeCommand = useMemo(() => {
+    if (!parsed || !parsed.hasTrailingSpace) {
+      return null;
+    }
+    return matchCommand(commands, value);
+  }, [commands, value, parsed]);
+
+  const items = useMemo(() => {
+    if (!parsed) {
+      return [];
+    }
+    if (activeCommand) {
+      return [activeCommand];
+    }
+    return filterCommands(commands, parsed.name, filterCtx);
+  }, [commands, parsed, activeCommand, filterCtx]);
+
+  const open = parsed !== null && items.length > 0 && !dismissed;
+
+  // Whether the current draft is a slash-command ATTEMPT that should be run via
+  // the palette, never delivered to the agent as plain chat. True even when the
+  // palette is dismissed (Escape) — the draft still starts with "/" and matches
+  // a command, so the composer must block its send path (button + Enter) to keep
+  // commands from leaking into the conversation as messages the model reads.
+  const isCommandDraft = parsed !== null && items.length > 0;
+
+  // Keep highlight in range as items change.
+  const clampedHighlight = items.length === 0 ? 0 : Math.min(highlight, items.length - 1);
+
+  const activeArgHint = activeCommand ? argHint(activeCommand.args) : "";
+
+  // Build the context for a SPECIFIC command. The danger confirm() is bound to
+  // that command so the confirm bar names the command actually about to run —
+  // not whatever near-match happens to sit highlighted in the palette (e.g.
+  // typing "/clear"+Enter runs the destructive `clear`, but `clear-view` sorts
+  // first and would otherwise mislabel the bar as a harmless local-view reset).
+  const buildContext = useCallback(
+    (command: SlashCommand): CommandContext | null => {
+      if (!context) {
+        return null;
+      }
+      return { ...context, ...handlers, confirm: () => handlers.confirm(command) };
+    },
+    [context, handlers],
+  );
+
+  const execute = useCallback(
+    async (command: SlashCommand, args: string[]): Promise<void> => {
+      const ctx = buildContext(command);
+      if (!ctx) {
+        return;
+      }
+      try {
+        const result = await command.run(args, ctx);
+        if (result.message) {
+          ctx.notice({ tone: result.status === "ok" ? "ok" : "error", message: result.message });
+        }
+        if (result.status === "ok" && !result.keepDraft) {
+          setValue("");
+        }
+      } catch (cause) {
+        ctx.notice({ tone: "error", message: errorMessage(cause) });
+      }
+    },
+    [buildContext, setValue],
+  );
+
+  const autocomplete = useCallback(
+    (command: SlashCommand) => {
+      setValue(`/${command.name} `);
+      setHighlight(0);
+    },
+    [setValue],
+  );
+
+  const autocompleteHighlighted = useCallback(() => {
+    const command = items[clampedHighlight];
+    if (command) {
+      autocomplete(command);
+    }
+  }, [items, clampedHighlight, autocomplete]);
+
+  // Resolve a SPECIFIC, already-chosen command against the current draft, then
+  // either autocomplete (name-only / required arg missing) or execute. This is
+  // the shared core for both Enter (which first resolves WHICH command via the
+  // exact-match heuristic) and a pointer click (which has ALREADY chosen the
+  // command — the clicked row — and must not re-resolve to a near-match).
+  const runResolved = useCallback(
+    async (command: SlashCommand, options?: { explicit?: boolean }): Promise<void> => {
+      if (!parsed) {
+        return;
+      }
+      const explicit = options?.explicit ?? false;
+      // Token-vs-command equality is case-insensitive (matching the registry's
+      // matchCommand/filterCommands), so a fully-typed "/Clear" counts as having
+      // named `clear` and runs rather than autocompleting.
+      const nameMatchesToken =
+        command.name === parsed.name.toLowerCase() ||
+        (command.aliases?.includes(parsed.name.toLowerCase()) ?? false);
+      // A name-only token whose name doesn't yet equal the resolved command (e.g.
+      // "/cl" -> clear) first autocompletes so the operator sees the full name.
+      // An EXPLICIT pointer click skips this: the operator already chose the row,
+      // so clicking "/clear-view" (while the token is "clear") runs it outright
+      // rather than merely filling the name and waiting for a second Enter.
+      if (!explicit && !activeCommand && !nameMatchesToken && !parsed.hasTrailingSpace) {
+        autocomplete(command);
+        return;
+      }
+      // When the click resolves a different command than the typed token, the
+      // typed token's tail isn't this command's args — run with no positional
+      // args and let the required-arg guard below prompt for them via autocomplete.
+      const args = nameMatchesToken || parsed.hasTrailingSpace ? parsed.args : [];
+      const missing = firstMissingRequiredArg(command, args);
+      if (missing) {
+        // A required arg is absent: keep the palette open at the arg hint rather
+        // than firing a half-formed command.
+        if (!parsed.hasTrailingSpace) {
+          autocomplete(command);
+        }
+        return;
+      }
+      await execute(command, args);
+    },
+    [parsed, activeCommand, autocomplete, execute],
+  );
+
+  const runHighlighted = useCallback(async (): Promise<void> => {
+    if (!parsed) {
+      return;
+    }
+    // If the operator has arrow-navigated, Enter is an explicit choice of the
+    // highlighted row — run it directly, exactly like a click. This makes
+    // /clear-view reachable via ArrowDown+Enter even when "/clear" is fully
+    // typed (otherwise the exact-match override below would hijack it).
+    if (navigatedRef.current && !activeCommand) {
+      const highlighted = items[clampedHighlight];
+      if (highlighted) {
+        await runResolved(highlighted, { explicit: true });
+      }
+      return;
+    }
+    // Otherwise (no explicit navigation): when the typed token is an exact
+    // command name (e.g. "/clear" while the longer "/clear-view" sits first in
+    // the filtered list), Enter should run THAT command, not autocomplete the
+    // highlighted near-match. Exact match wins over the highlight; otherwise use
+    // the highlighted row. A pointer click goes through runAt, never here.
+    // Compare case-insensitively, matching filterCommands/matchCommand, so a
+    // fully-typed "/Clear" still resolves to the exact (destructive) clear
+    // rather than the highlighted prefix near-match.
+    const token = parsed.name.toLowerCase();
+    const exact = items.find((item) => item.name === token || item.aliases?.includes(token));
+    const command = activeCommand ?? exact ?? items[clampedHighlight];
+    if (!command) {
+      return;
+    }
+    await runResolved(command);
+  }, [parsed, activeCommand, items, clampedHighlight, runResolved]);
+
+  // Run the command at an EXPLICITLY chosen index (a pointer click on a palette
+  // row). Unlike runHighlighted this does NOT apply the exact-match override:
+  // clicking the harmless `/clear-view` row while the draft is "/clear" must run
+  // clear-view, never the destructive `/clear` that exact-matches the token. The
+  // operator's pointer is the selection; token-resolution heuristics don't apply.
+  const runAt = useCallback(
+    async (index: number): Promise<void> => {
+      const command = items[index];
+      if (!command) {
+        return;
+      }
+      await runResolved(command, { explicit: true });
+    },
+    [items, runResolved],
+  );
+
+  // Track an in-flight run so Enter can't double-fire.
+  const runningRef = useRef(false);
+
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLTextAreaElement>): boolean => {
+      if (!open) {
+        return false;
+      }
+      switch (event.key) {
+        case "ArrowDown": {
+          event.preventDefault();
+          navigatedRef.current = true;
+          setHighlight((current) => (items.length === 0 ? 0 : (Math.min(current, items.length - 1) + 1) % items.length));
+          return true;
+        }
+        case "ArrowUp": {
+          event.preventDefault();
+          navigatedRef.current = true;
+          setHighlight((current) => {
+            const base = Math.min(current, items.length - 1);
+            return items.length === 0 ? 0 : (base - 1 + items.length) % items.length;
+          });
+          return true;
+        }
+        case "Tab": {
+          event.preventDefault();
+          autocompleteHighlighted();
+          return true;
+        }
+        case "Enter": {
+          if (event.shiftKey || event.nativeEvent?.isComposing) {
+            return false;
+          }
+          event.preventDefault();
+          if (runningRef.current) {
+            return true;
+          }
+          runningRef.current = true;
+          void runHighlighted().finally(() => {
+            runningRef.current = false;
+          });
+          return true;
+        }
+        case "Escape": {
+          event.preventDefault();
+          // Close the palette but keep the draft intact. Remember the dismissed
+          // value; the next edit re-opens (value !== dismissedValue).
+          setDismissedValue(value);
+          return true;
+        }
+        default:
+          return false;
+      }
+    },
+    [open, items, autocompleteHighlighted, runHighlighted, value],
+  );
+
+  return {
+    open,
+    isCommandDraft,
+    items,
+    highlight: clampedHighlight,
+    setHighlight,
+    activeCommand,
+    activeArgHint,
+    onKeyDown,
+    runHighlighted,
+    runAt,
+    autocompleteHighlighted,
+  };
+}
+
+function errorMessage(cause: unknown): string {
+  if (cause instanceof Error) {
+    return cause.message;
+  }
+  return String(cause);
+}

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

@@ -0,0 +1,229 @@
+import type { SessionEvent, SessionTurn, UpdateSessionTurnRequest } from "@opengeni/sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useOpenGeni, type ClientOverride } from "../provider";
+import { useDebouncedCallback, useMutationRunner, useSessionEventTrigger, type SessionEventFeedOptions } from "./internal";
+
+/** Event types that change the turn queue (queue/edit/reorder/claim/finish). */
+export function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean {
+  return event.type.startsWith("turn.");
+}
+
+/** Queued turns in execution order (position, then creation time). */
+export function queueFromTurns(turns: SessionTurn[]): SessionTurn[] {
+  return turns
+    .filter((turn) => turn.status === "queued")
+    .sort((a, b) => a.position - b.position || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+}
+
+/** The turn currently holding the session (running or awaiting approval). */
+export function activeTurnFromTurns(turns: SessionTurn[]): SessionTurn | null {
+  return turns.find((turn) => turn.status === "running" || turn.status === "requires_action") ?? null;
+}
+
+/** Optimistic projection of a queued-turn edit. */
+export function applyTurnEdit(turns: SessionTurn[], turnId: string, update: UpdateSessionTurnRequest): SessionTurn[] {
+  return turns.map((turn) => {
+    if (turn.id !== turnId || turn.status !== "queued") {
+      return turn;
+    }
+    return {
+      ...turn,
+      ...(update.prompt !== undefined ? { prompt: update.prompt } : {}),
+      ...(update.resources !== undefined ? { resources: update.resources } : {}),
+      ...(update.tools !== undefined ? { tools: update.tools } : {}),
+      ...(update.model !== undefined ? { model: update.model } : {}),
+      ...(update.reasoningEffort !== undefined ? { reasoningEffort: update.reasoningEffort } : {}),
+      ...(update.sandboxBackend !== undefined ? { sandboxBackend: update.sandboxBackend } : {}),
+      ...(update.metadata !== undefined ? { metadata: update.metadata } : {}),
+    };
+  });
+}
+
+/**
+ * Optimistic projection of a reorder, mirroring the server: the listed
+ * queued turns get positions 1..n in the given order; everything else keeps
+ * its position.
+ */
+export function applyTurnReorder(turns: SessionTurn[], turnIds: string[]): SessionTurn[] {
+  const positions = new Map(turnIds.map((turnId, index) => [turnId, index + 1] as const));
+  return turns.map((turn) => {
+    const position = positions.get(turn.id);
+    return position !== undefined && turn.status === "queued" ? { ...turn, position } : turn;
+  });
+}
+
+/** Optimistic projection of a queued-turn delete (server marks it cancelled). */
+export function applyTurnRemoval(turns: SessionTurn[], turnId: string): SessionTurn[] {
+  return turns.map((turn) => (turn.id === turnId && turn.status === "queued" ? { ...turn, status: "cancelled" as const } : turn));
+}
+
+export type UseTurnQueueOptions = ClientOverride & SessionEventFeedOptions & {
+  /** Optional safety-net polling (ms). Off by default — turn.* events drive updates. */
+  pollIntervalMs?: number | undefined;
+};
+
+export type UseTurnQueueResult = {
+  /** All turns the API returned (history + queue), newest server view. */
+  turns: SessionTurn[];
+  /** Queued turns in execution order — render this as the editable queue. */
+  queue: SessionTurn[];
+  /** The running / requires_action turn, if any. */
+  activeTurn: SessionTurn | null;
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  /** Edit a queued turn (optimistic; rolls back via refetch on failure). */
+  editTurn: (turnId: string, update: UpdateSessionTurnRequest) => Promise<SessionTurn | null>;
+  /** Reorder the queue to the given queued-turn id order (optimistic). */
+  reorderTurns: (turnIds: string[]) => Promise<SessionTurn[] | null>;
+  /** Delete (cancel) a queued turn before it is claimed (optimistic). */
+  removeTurn: (turnId: string) => Promise<SessionTurn | null>;
+  /** True while an edit/reorder/remove is in flight. */
+  mutating: boolean;
+  /** Last failed mutation, until the next mutation or clear. */
+  mutationError: Error | null;
+  clearMutationError: () => void;
+};
+
+/**
+ * The live turn queue — the heart of the queue-by-default interaction model.
+ * Messages sent mid-turn stack up here, visible and editable/reorderable/
+ * deletable until the worker claims them. Updates arrive over the session
+ * event stream (`turn.*`), either shared via `options.events` (pass the log
+ * from `useSessionEvents` to reuse its connection) or a dedicated tail
+ * stream. All mutations apply optimistically and reconcile with the server.
+ */
+export function useTurnQueue(sessionId: string | null | undefined, options: UseTurnQueueOptions = {}): UseTurnQueueResult {
+  const { client, workspaceId } = useOpenGeni(options);
+  const enabled = (options.enabled ?? true) && Boolean(sessionId);
+  const [turns, setTurns] = useState<SessionTurn[]>([]);
+  const [loading, setLoading] = useState(enabled);
+  const [error, setError] = useState<Error | null>(null);
+  const mutation = useMutationRunner();
+  const generation = useRef(0);
+  const targetKeyRef = useRef<string | null>(null);
+
+  const load = useCallback(async (): Promise<void> => {
+    if (!sessionId) {
+      return;
+    }
+    const ticket = ++generation.current;
+    try {
+      const fetched = await client.listTurns(workspaceId, sessionId);
+      if (ticket === generation.current) {
+        setTurns(fetched);
+        setError(null);
+        setLoading(false);
+      }
+    } catch (cause) {
+      if (ticket === generation.current) {
+        setError(cause instanceof Error ? cause : new Error(String(cause)));
+        setLoading(false);
+      }
+    }
+  }, [client, workspaceId, sessionId]);
+
+  // Reset when the target session changes; initial load + optional polling.
+  useEffect(() => {
+    const targetKey = `${workspaceId}\u0000${sessionId ?? ""}`;
+    if (targetKeyRef.current !== targetKey) {
+      targetKeyRef.current = targetKey;
+      setTurns([]);
+      setError(null);
+    }
+    if (!enabled) {
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    void load();
+    const pollIntervalMs = options.pollIntervalMs;
+    if (pollIntervalMs === undefined || pollIntervalMs <= 0) {
+      return () => {
+        generation.current += 1;
+      };
+    }
+    const timer = setInterval(() => void load(), pollIntervalMs);
+    return () => {
+      clearInterval(timer);
+      generation.current += 1;
+    };
+  }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs]);
+
+  // Live updates: any turn.* event re-syncs the queue (debounced).
+  const scheduleRefresh = useDebouncedCallback(() => void load());
+  useSessionEventTrigger(client, workspaceId, sessionId, isTurnQueueEvent, scheduleRefresh, {
+    enabled,
+    ...(options.events !== undefined ? { events: options.events } : {}),
+  });
+
+  const editTurn = useCallback(
+    async (turnId: string, update: UpdateSessionTurnRequest): Promise<SessionTurn | null> => {
+      if (!sessionId) {
+        return null;
+      }
+      setTurns((current) => applyTurnEdit(current, turnId, update));
+      const result = await mutation.run(() => client.updateQueuedTurn(workspaceId, sessionId, turnId, update));
+      if (result) {
+        setTurns((current) => current.map((turn) => (turn.id === result.id ? result : turn)));
+      } else {
+        void load();
+      }
+      return result;
+    },
+    [client, workspaceId, sessionId, mutation.run, load],
+  );
+
+  const reorderTurns = useCallback(
+    async (turnIds: string[]): Promise<SessionTurn[] | null> => {
+      if (!sessionId || turnIds.length === 0) {
+        return null;
+      }
+      setTurns((current) => applyTurnReorder(current, turnIds));
+      const result = await mutation.run(() => client.reorderQueuedTurns(workspaceId, sessionId, turnIds));
+      if (result) {
+        // The server returns the queued turns; merge them over local state.
+        setTurns((current) => {
+          const bySId = new Map(result.map((turn) => [turn.id, turn] as const));
+          return current.map((turn) => bySId.get(turn.id) ?? turn);
+        });
+      } else {
+        void load();
+      }
+      return result;
+    },
+    [client, workspaceId, sessionId, mutation.run, load],
+  );
+
+  const removeTurn = useCallback(
+    async (turnId: string): Promise<SessionTurn | null> => {
+      if (!sessionId) {
+        return null;
+      }
+      setTurns((current) => applyTurnRemoval(current, turnId));
+      const result = await mutation.run(() => client.deleteQueuedTurn(workspaceId, sessionId, turnId));
+      if (result) {
+        setTurns((current) => current.map((turn) => (turn.id === result.id ? result : turn)));
+      } else {
+        void load();
+      }
+      return result;
+    },
+    [client, workspaceId, sessionId, mutation.run, load],
+  );
+
+  return {
+    turns,
+    queue: queueFromTurns(turns),
+    activeTurn: activeTurnFromTurns(turns),
+    loading,
+    error,
+    refresh: load,
+    editTurn,
+    reorderTurns,
+    removeTurn,
+    mutating: mutation.mutating,
+    mutationError: mutation.mutationError,
+    clearMutationError: mutation.clearMutationError,
+  };
+}

package/src/hooks/use-workspace-sessions.ts

@@ -0,0 +1,30 @@
+import type { Session } from "@opengeni/sdk";
+import { useCallback } from "react";
+import { useOpenGeni, type ClientOverride } from "../provider";
+import { usePolledValue } from "./internal";
+
+export type UseWorkspaceSessionsOptions = ClientOverride & {
+  limit?: number | undefined;
+  /** Refresh interval (ms) for fleet/manager views. Off by default. */
+  pollIntervalMs?: number | undefined;
+  enabled?: boolean | undefined;
+};
+
+export type UseWorkspaceSessionsResult = {
+  sessions: Session[];
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+};
+
+/** List the workspace's sessions — the data behind fleet and manager views. */
+export function useWorkspaceSessions(options: UseWorkspaceSessionsOptions = {}): UseWorkspaceSessionsResult {
+  const { client, workspaceId } = useOpenGeni(options);
+  const limit = options.limit;
+  const load = useCallback(
+    async () => await client.listSessions(workspaceId, limit !== undefined ? { limit } : {}),
+    [client, workspaceId, limit],
+  );
+  const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled: options.enabled });
+  return { sessions: state.data ?? [], loading: state.loading, error: state.error, refresh: state.refresh };
+}

package/src/hooks/use-workspaces.ts

@@ -0,0 +1,66 @@
+import type { CreateWorkspaceRequest, UpdateWorkspaceRequest, Workspace } from "@opengeni/sdk";
+import { useCallback } from "react";
+import { useOpenGeniClient, type ClientOverride } from "../provider";
+import { useMutationRunner, usePolledValue } from "./internal";
+
+export type UseWorkspacesOptions = Pick<ClientOverride, "client"> & {
+  pollIntervalMs?: number | undefined;
+  enabled?: boolean | undefined;
+};
+
+export type UseWorkspacesResult = {
+  workspaces: Workspace[];
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  create: (request: CreateWorkspaceRequest) => Promise<Workspace | null>;
+  update: (workspaceId: string, request: UpdateWorkspaceRequest) => Promise<Workspace | null>;
+  mutating: boolean;
+  mutationError: Error | null;
+  clearMutationError: () => void;
+};
+
+/**
+ * The caller's workspaces (workspace switchers, onboarding). Not scoped to
+ * the provider's workspace, so it only needs the client.
+ */
+export function useWorkspaces(options: UseWorkspacesOptions = {}): UseWorkspacesResult {
+  const client = useOpenGeniClient(options);
+  const load = useCallback(async () => await client.listWorkspaces(), [client]);
+  const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled: options.enabled });
+  const mutation = useMutationRunner();
+
+  const create = useCallback(
+    async (request: CreateWorkspaceRequest): Promise<Workspace | null> => {
+      const result = await mutation.run(() => client.createWorkspace(request));
+      if (result) {
+        await state.refresh();
+      }
+      return result;
+    },
+    [client, mutation.run, state.refresh],
+  );
+
+  const update = useCallback(
+    async (workspaceId: string, request: UpdateWorkspaceRequest): Promise<Workspace | null> => {
+      const result = await mutation.run(() => client.updateWorkspace(workspaceId, request));
+      if (result) {
+        await state.refresh();
+      }
+      return result;
+    },
+    [client, mutation.run, state.refresh],
+  );
+
+  return {
+    workspaces: state.data ?? [],
+    loading: state.loading,
+    error: state.error,
+    refresh: state.refresh,
+    create,
+    update,
+    mutating: mutation.mutating,
+    mutationError: mutation.mutationError,
+    clearMutationError: mutation.clearMutationError,
+  };
+}